SubtleCrypto: sign() メソッド

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

安全なコンテキスト用: この機能は一部またはすべての対応しているブラウザーにおいて、安全なコンテキスト (HTTPS) でのみ利用できます。

sign()SubtleCrypto インターフェイスのメソッドで、デジタル署名を生成します。

引数として、署名する、アルゴリズム固有の引数、署名するデータを取ります。署名で履行されるプロミス (Promise) を返します。

対応する SubtleCrypto.verify() メソッドを使用して、署名を検証することができます。

構文

js
sign(algorithm, key, data)

引数

algorithm

使用する署名アルゴリズムとその引数を指定する文字列またはオブジェクトです。

  • RSASSA-PKCS1-v1_5 を使用する場合は、"RSASSA-PKCS1-v1_5" という文字列か、 { "name": "RSASSA-PKCS1-v1_5" } の形の文字列を渡してください。
  • RSA-PSS を使用するには、 RsaPssParams を渡してください。
  • ECDSA を使用するには、 EcdsaParams を渡してください。
  • HMAC を使用するには、 "HMAC" という文字列か、 { "name": "HMAC" } の形の文字列を渡してください。
key

署名に用いる鍵を格納した CryptoKey オブジェクトです。 もし algorithm が公開鍵暗号方式であれば、これは秘密鍵です。

data

署名するデータを格納した ArrayBufferTypedArrayDataView のいずれかのオブジェクト。

返値

署名を格納した ArrayBuffer で履行される Promise です。

例外

以下の例外が発生した場合、プロミスは拒否されます:

InvalidAccessError DOMException

署名鍵がリクエストされた署名アルゴリズムの鍵でない場合、または未知の、あるいは署名に適さないアルゴリズムを使用しようとした場合に発生します。

対応しているアルゴリズム

ウェブ暗号 API は、署名と署名の検証に使用できるアルゴリズムを 4 つ提供しています。

これらのアルゴリズムのうち、 RSASSA-PKCS1-v1_5、RSA-PSS、ECDSA の 3 つは公開鍵暗号システムでらい、署名に秘密鍵を使用し、検証に公開鍵を使用します。 これらのシステムはすべてダイジェストアルゴリズムを使用して、署名の前にメッセージを短い固定長のデータにハッシュ化します。 ECDSA (これは algorithm オブジェクトに渡されます)を除き、ダイジェストアルゴリズムの選択は generateKey() または importKey() 関数に渡されます。

4 番目のアルゴリズムである HMAC は、署名と検証に同じアルゴリズムと鍵を用います。これは、検証鍵を秘密にしなければならないことを意味しています。しかし、署名者と検証者が同じエンティティである場合には良い選択となります。

RSASSA-PKCS1-v1_5

RSASSA-PKCS1-v1_5 アルゴリズムは RFC 3447 で定義されています。

RSA-PSS

RSA-PSS アルゴリズムは RFC 3447 で定義されています。

RSASSA-PKCS1-v1_5 とは異なる形で、署名処理にランダムなソルトを組み込んでいるため、同じ鍵で署名された同じメッセージが毎回同じ署名になることはありません。ソルトの長さを定義する追加のプロパティは、 sign()verify() 関数を呼び出す際に渡されます。

ECDSA

ECDSA (Elliptic Curve Digital Signature Algorithm) は、 FIPS-186 で定義されている、楕円曲線暗号 (RFC 6090) を使用するデジタル署名アルゴリズムの一種です。

署名は RFC 6090 で指定されている s1s2 の値(RFC 4754 ではそれぞれ rs として知られている)をビッグエンディアンのバイト配列でエンコードしたものです。 これらの値はこの順番で連結されます。

このエンコーダーは IEEE 1363-2000 標準でも 提案されており、 IEEE P1363 形式と呼ばれることもあります。これは X.509 の署名構造とは異なり、 OpenSSL などのいくつかのツールやライブラリーでは既定で生成される形式です。

HMAC

HMAC アルゴリズムは、 FIPS 198-1 標準に従ってハッシュベースのメッセージ認証コードを計算し、検証します。

使用するダイジェストアルゴリズムは、 HmacKeyGenParams オブジェクトを generateKey() に渡すか、または HmacImportParams オブジェクトを importKey() に渡すことで指定します。

メモ: GitHub の動作例をご覧ください。

RSASSA-PKCS1-v1_5

このコードはテキストボックスの内容を取得し、署名用にエンコードし、秘密鍵で署名します。 完全なソースコードは GitHub で参照してください。

js
/*
Fetch the contents of the "message" textbox, and encode it
in a form we can use for the sign operation.
*/
function getMessageEncoding() {
  const messageBox = document.querySelector(".rsassa-pkcs1 #message");
  let message = messageBox.value;
  let enc = new TextEncoder();
  return enc.encode(message);
}

let encoded = getMessageEncoding();
let signature = await window.crypto.subtle.sign(
  "RSASSA-PKCS1-v1_5",
  privateKey,
  encoded,
);

RSA-PSS

このコードはテキストボックスの内容を取得し、署名用にエンコードし、秘密鍵で署名します。 完全なソースコードは GitHub で参照してください。

js
/*
Fetch the contents of the "message" textbox, and encode it
in a form we can use for the sign operation.
*/
function getMessageEncoding() {
  const messageBox = document.querySelector(".rsa-pss #message");
  let message = messageBox.value;
  let enc = new TextEncoder();
  return enc.encode(message);
}

let encoded = getMessageEncoding();
let signature = await window.crypto.subtle.sign(
  {
    name: "RSA-PSS",
    saltLength: 32,
  },
  privateKey,
  encoded,
);

ECDSA

このコードはテキストボックスの内容を取得し、署名用にエンコードし、秘密鍵で署名します。 完全なソースコードは GitHub で参照してください。

js
/*
Fetch the contents of the "message" textbox, and encode it
in a form we can use for the sign operation.
*/
function getMessageEncoding() {
  const messageBox = document.querySelector(".ecdsa #message");
  let message = messageBox.value;
  let enc = new TextEncoder();
  return enc.encode(message);
}

let encoded = getMessageEncoding();
let signature = await window.crypto.subtle.sign(
  {
    name: "ECDSA",
    hash: { name: "SHA-384" },
  },
  privateKey,
  encoded,
);

HMAC

このコードはテキストボックスの内容を取得し、署名用にエンコードし、秘密鍵で署名します。 完全なソースコードは GitHub で参照してください。

js
/*
Fetch the contents of the "message" textbox, and encode it
in a form we can use for the sign operation.
*/
function getMessageEncoding() {
  const messageBox = document.querySelector(".hmac #message");
  let message = messageBox.value;
  let enc = new TextEncoder();
  return enc.encode(message);
}

let encoded = getMessageEncoding();
let signature = await window.crypto.subtle.sign("HMAC", key, encoded);

仕様書

Specification
Web Cryptography API
# SubtleCrypto-method-sign

ブラウザーの互換性

BCD tables only load in the browser

関連情報