SubtleCrypto

Web Crypto APIのSubtleCryptoインターフェイスは、多くの低レベル暗号化関数を提供しています。

インターフェイス名に「subtle」という語が含まれているのは、そのアルゴリズムの多くに繊細な使用要件があることを示しています。また、これは適切なセキュリティ保証を提供するため慎重に使用する必要があることを示しています。

プロパティ

decrypt()

decrypt: (algorithm, key, data) => Promise<ArrayBuffer>

SubtleCryptoインターフェイスのdecrypt() メソッドは、暗号化されたデータの一部を復号化します。復号化に使用するキー、いくつかの任意の追加パラメーター、および復号化するデータ（「暗号文」とも呼ばれる）を引数として受け取ります。復号化されたデータ（「プレーンテキスト」とも呼ばれる）を処理結果として取得できるPromiseが返されます。

パラメーター

algorithm

EncryptionAlgorithm

使用するアルゴリズムと、必要に応じて追加のパラメーターを指定するオブジェクト。追加パラメーターに指定する値は、対応するencrypt呼び出しに渡された値と一致する必要があります。

• RSA-OAEPを使用するには、RsaOaepParamsオブジェクトを渡します。
• AES-CTRを使用するには、AesCtrParamsオブジェクトを渡します。
• AES-CBCを使用するには、AesCbcParamsオブジェクトを渡します。
• AES-GCMを使用するには、AesGcmParamsオブジェクトを渡します。

key

CryptoKey

復号化に使用するキーを含むCryptoKey。RSA-OAEPを使用している場合、CryptoKeyPairオブジェクトのprivateKeyプロパティにします。

data

BufferSource

復号化するデータ（暗号文とも呼ばれる）を含むArrayBuffer、TypedArray、またはDataView。

戻り値

Promise<ArrayBuffer>

プレーンテキストを含むArrayBufferを処理結果として取得できるPromise。

スロー

InvalidArgumentError：アルゴリズムパラメーターが無効な場合、または必須フィールドが不足している場合に発生します。

スロー

NotSupportedError：アルゴリズムがサポートされていない場合、またはパラメーターにサポートされていない値がある場合に発生します。

---

deriveBits()

deriveBits: (algorithm, baseKey, length) => Promise<ArrayBuffer>

SubtleCryptoインターフェイスのderiveBits()メソッドは、基本となるキーからビット配列を導出させるために使用できます。

基本となるキー、使用する導出アルゴリズム、および導出するビットの長さを引数として受け取ります。導出されたビットを含むArrayBufferを処理結果として取得できるPromiseが返されます。

パラメーター

algorithm

DerivationAlgorithm

使用する導出アルゴリズムを定義するオブジェクト。

• ECDHを使用するには、nameプロパティとして文字列"ECDH"を指定して、EcdhKeyDeriveParamsオブジェクトを渡します。
• HKDFを使用するには、HkdfParamsオブジェクトを渡します。
• PBKDF2を使用するには、Pbkdf2Paramsオブジェクトを渡します。

baseKey

CryptoKey

導出アルゴリズムへの入力を表すCryptoKey。アルゴリズムがECDHの場合、これがECDHのプライベートキーになります。それ以外の場合は、導出関数の初期キーマテリアルになります。たとえば、PBKDF2の場合、SubtleCrypto.importKeyを使用してCryptoKeyとしてインポートされたパスワードである可能性があります。

length

number

導出するビット数を表す数値。この数は8の倍数である必要があります。

戻り値

Promise<ArrayBuffer>

導出されたビットを含むArrayBufferを処理結果として取得できるPromise。

スロー

NotSupportedError：指定された導出アルゴリズムがサポートされていない場合に発生します。

スロー

InvalidArgumentError：アルゴリズムパラメーターが無効な場合に発生します。

---

deriveKey()

deriveKey: (algorithm, baseKey, derivedKeyAlgorithm, extractable, keyUsages) => Promise<CryptoKey>

SubtleCryptoインターフェイスのderiveKey()メソッドを使用して、マスターキーからシークレットキーを導出できます。

引数として、いくつかの初期キーマテリアル、使用する導出アルゴリズム、および導出するキーに必要なプロパティを取ります。新しいキーを表すCryptoKeyオブジェクトを処理結果として取得できるPromiseを返します。

パラメーター

algorithm

DerivationAlgorithm

使用する導出アルゴリズムを定義するオブジェクト。

• ECDHを使用するには、nameプロパティとして文字列"ECDH"を指定して、EcdhKeyDeriveParamsオブジェクトを渡します。
• HKDFを使用するには、HkdfParamsオブジェクトを渡します。
• PBKDF2を使用するには、Pbkdf2Paramsオブジェクトを渡します。

baseKey

CryptoKey

導出アルゴリズムへの入力を表すCryptoKey。アルゴリズムがECDHの場合、これがECDHのプライベートキーになります。それ以外の場合は、導出関数の初期キーマテリアルになります。たとえば、PBKDF2の場合、SubtleCrypto.importKeyを使用してCryptoKeyとしてインポートされたパスワードである可能性があります。

derivedKeyAlgorithm

DerivedKeyAlgorithm

導出されたキーが使用されるアルゴリズムを定義するオブジェクト。

• HMACの場合は、HmacKeyGenParamsオブジェクトを渡します。
• AES-CTR、AES-CBC、AES-GCMの場合は、AesKeyGenParamsオブジェクトを渡します。
• HKDFの場合は、HkdfParamsオブジェクトを渡します。
• PBKDF2の場合は、Pbkdf2Paramsオブジェクトを渡します。

extractable

boolean

()を使用してキーをエクスポートできるかどうかを示すブール値。

keyUsages

KeyUsage[]

導出されたキーで実行できる処理を示すArray。注：キーの使用は、derivedKeyAlgorithmに設定されたアルゴリズムで許可されている必要があります。配列に指定できる値は次のとおりです。

• encrypt： このキーはメッセージを暗号化するために使用できます。
• decrypt： このキーはメッセージを復号化するために使用できます。
• sign： このキーはメッセージに署名するために使用できます。
• verify： このキーは署名の検証に使用できます。
• deriveKey： このキーは新しいキーを生成する際に使用できます。
• deriveBits： このキーはビットの導出に使用できます。
• wrapKey： このキーはキーをラップするために使用できます。
• unwrapKey： このキーはキーのラップを解除するために使用できます。

戻り値

Promise<CryptoKey>

CryptoKeyを処理結果として取得できるPromise。

スロー

NotSupportedError：指定された導出アルゴリズムがサポートされていない場合に発生します。

スロー

InvalidArgumentError：アルゴリズムパラメーターが無効な場合に発生します。

---

digest()

digest: (algorithm, data) => Promise<ArrayBuffer>

SubtleCryptoインターフェイスのdigest()メソッドは、指定されたハッシュ関数を使用して、指定されたデータのダイジェストを生成します。ダイジェストとは、可変長の入力から得られる短い固定長の値です。暗号ダイジェストは衝突耐性を備えている必要があります。つまり、同じダイジェスト値を持つ2つの異なる入力を思い付くのは困難であるということです。

使用するダイジェストアルゴリズムの識別子とダイジェストするデータを引数として受け取ります。ダイジェストを処理結果として取得できるPromiseが返されます。

このAPIはストリーミング入力をサポートしていないことに注意してください。ダイジェスト関数に渡す前に、入力全体をメモリに読み込む必要があります。

パラメーター

algorithm

DigestAlgorithm

これは、文字列、または文字列である単一のプロパティnameを持つオブジェクトです。文字列には使用するハッシュ関数名を指定します。サポートされる値は次のとおりです。

• SHA-256
• SHA-384
• SHA-512

data

BufferSource

ダイジェストするデータを含むArrayBuffer、TypedArray、またはDataViewオブジェクト。

戻り値

Promise<ArrayBuffer>

ダイジェストを含むArrayBufferを処理結果として取得できるPromise。

スロー

NotSupportedError：指定されたハッシュ関数がサポートされていない場合に発生します。

スロー

InvalidArgumentError：入力パラメーターが無効な場合に発生します。

---

encrypt()

encrypt: (algorithm, key, data) => Promise<ArrayBuffer>

SubtleCryptoインターフェイスのencrypt()メソッドはデータを暗号化します。

暗号化に使用するキー、アルゴリズム固有のパラメーター、および暗号化するデータ（「プレーンテキスト」とも呼ばれる）を引数として受け取ります。暗号化されたデータ（「暗号文」とも呼ばれる）を処理結果として取得できるPromiseが返されます。

パラメーター

algorithm

EncryptionAlgorithm

使用するアルゴリズムを指定するオブジェクトと、必要に応じた追加のパラメーター。

• RSA-OAEPを使用するには、RsaOaepParamsオブジェクトを渡します。
• AES-CTRを使用するには、AesCtrParamsオブジェクトを渡します。
• AES-CBCを使用するには、AesCbcParamsオブジェクトを渡します。
• AES-GCMを使用するには、AesGcmParamsオブジェクトを渡します。

key

CryptoKey

暗号化に使用するキーを含むCryptoKey。

data

BufferSource

暗号化するデータ（プレーンテキストとも呼ばれる）を含むArrayBuffer、TypedArray、またはDataView。

戻り値

Promise<ArrayBuffer>

「暗号文」を含むArrayBufferを処理結果として取得できるPromise。

スロー

InvalidArgumentError：アルゴリズムパラメーターが無効な場合、または必須フィールドが不足している場合に発生します。

スロー

NotSupportedError：アルゴリズムがサポートされていない場合、またはパラメーターにサポートされていない値がある場合に発生します。

---

exportKey()

exportKey: (format, key) => Promise<ArrayBuffer | JsonWebKey>

SubtleCryptoインターフェイスのexportKey()メソッドはキーをエクスポートします。CryptoKeyオブジェクトを入力として受け取り、外部で利用可能な形式でキーを提供します。

キーをエクスポートするには、キーのCryptoKey.extractableがtrueに設定されている必要があります。キーは複数の形式でエクスポートできます。

パラメーター

format

KeyFormat

キーをエクスポートするデータ形式を記述する文字列値。次のいずれかを指定できます。

• raw： Raw形式（対称キーまたは楕円曲線パブリックキー用）。
• pkcs8： PKCS #8形式（プライベートキー用）。
• spki： SubjectPublicKeyInfo形式（パブリックキー用）。
• jwk： JSON Web Key形式（対称キーまたは非対称キー用）。

key

CryptoKey

エクスポートするCryptoKey。

戻り値

Promise<ArrayBuffer | JsonWebKey>

Promise。

• 形式がjwkの場合、Promiseの処理結果はキーを含むJSONオブジェクトになります。
• それ以外の場合、Promiseの処理結果はキーを含むArrayBufferになります。

スロー

InvalidArgumentError：キーが抽出できない場合に発生します

スロー

NotSupportedError：要求された形式が指定されたキータイプでサポートされていない場合に発生します

---

generateKey()

generateKey: (algorithm, extractable, keyUsages) => Promise<CryptoKey | CryptoKeyPair>

SubtleCryptoインターフェイスのgenerateKey()メソッドは、新しいキー（対称アルゴリズムの場合）、またはキーペア（パブリックキーアルゴリズムの場合）を生成するために使用されます。

パラメーター

algorithm

KeyGenAlgorithm

生成するキーのタイプを定義し、追加のアルゴリズム固有のパラメーターを提供するオブジェクト。

• RSASSA-PKCS1-v1_5、RSA-PSS、RSA-OAEPの場合は、RsaHashedKeyGenParamsオブジェクトを渡します。
• ECDSAかECDHの場合は、EcKeyGenParamsオブジェクトを渡します。
• HMACの場合は、HmacKeyGenParamsオブジェクトを渡します。
• AES-CTR、AES-CBC、AES-GCMの場合は、AesKeyGenParamsオブジェクトを渡します。

extractable

boolean

SubtleCrypto.exportKeyを使用してキーをエクスポートできるかどうかを示すブール値。

keyUsages

KeyUsage[]

新しく生成されたキーで実行できる処理を示す文字列の配列。配列要素に指定できる値は次のとおりです。

• encrypt： このキーはメッセージを暗号化するために使用できます。
• decrypt： このキーはメッセージを復号化するために使用できます。
• sign： このキーはメッセージに署名するために使用できます。
• verify： このキーは署名の検証に使用できます。
• deriveKey： このキーは新しいキーを生成する際に使用できます。
• deriveBits： このキーはビットの導出に使用できます。
• wrapKey： このキーはキーをラップするために使用できます。
• unwrapKey： このキーはキーのラップを解除するために使用できます。

戻り値

Promise<CryptoKey | CryptoKeyPair>

CryptoKey（対称アルゴリズムの場合）、またはCryptoKeyPair（パブリックキーアルゴリズムの場合）を処理結果として取得できるPromise。

スロー

InvalidArgumentError：アルゴリズムパラメーターが無効な場合に発生します。

スロー

NotSupportedError：アルゴリズムまたはパラメーター値がサポートされていない場合に発生します

---

importKey()

importKey: (format, keyData, algorithm, extractable, keyUsages) => Promise<CryptoKey>

SubtleCryptoインターフェイスのimportKey() メソッドはキーをインポートします。外部で利用可能な形式のキーを入力として受け取り、Web Crypto APIで使用できるCryptoKeyオブジェクトを提供します。

パラメーター

format

KeyFormat

インポートするキーのデータ形式を説明する文字列。次のいずれかを指定できます。

• raw： Raw形式（対称キーまたは楕円曲線パブリックキー用）。
• pkcs8： PKCS #8形式（プライベートキー用）。
• spki： SubjectPublicKeyInfo形式（パブリックキー用）。
• jwk： JSON Web Key形式。

keyData

指定された形式のキーを含むArrayBuffer、TypedArray、DataView、またはJSON Web Keyオブジェクト。

JsonWebKey

BufferSource

algorithm

KeyImportAlgorithm

インポートするキーのタイプを定義し、追加のアルゴリズム固有のパラメーターを提供するオブジェクト。

• RSASSA-PKCS1-v1_5、RSA-PSS、RSA-OAEPの場合は、RsaHashedImportParamsオブジェクトを渡します。
• ECDSAやECDHの場合は、EcKeyImportParamsオブジェクトを渡します。
• HMACの場合は、HmacImportParamsオブジェクトを渡します。
• AES-CTR、AES-CBC、AES-GCMの場合は、アルゴリズムを識別する文字列、または {name: ALGORITHM} 形式のオブジェクトを渡します。ここで、ALGORITHMはアルゴリズムの名前です。
• PBKDF2の場合は、文字列PBKDF2、または{ name: "PBKDF2" }形式のオブジェクトを渡します。
• HKDFの場合、文字列HKDF、または{ name: "HKDF" }形式のオブジェクトを渡します。

extractable

boolean

SubtleCrypto.exportKeyを使用してキーをエクスポートできるかどうかを示すブール値。

keyUsages

KeyUsage[]

キーで実行できる処理を示す配列。指定できる配列値は次のとおりです。

• encrypt： このキーはメッセージを暗号化するために使用できます。
• decrypt： このキーはメッセージを復号化するために使用できます。
• sign： このキーはメッセージに署名するために使用できます。
• verify： このキーは署名の検証に使用できます。
• deriveKey： このキーは新しいキーを生成する際に使用できます。
• deriveBits： このキーはビットの導出に使用できます。
• wrapKey： このキーはキーをラップするために使用できます。
• unwrapKey： このキーはキーのラップを解除するために使用できます。

戻り値

Promise<CryptoKey>

CryptoKeyオブジェクト型のインポートされたキーを処理結果として取得できるPromise。

スロー

InvalidArgumentError：形式が無効な場合、またはkeyDataが必要な形式と一致しない場合に発生します。

スロー

アルゴリズムまたはキー形式の組み合わせがサポートされていない場合、NotSupportedErrorがスローされます。

---

sign()

sign: (algorithm, key, data) => Promise<ArrayBuffer>

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

署名に使用するキー、アルゴリズム固有のパラメーター、および署名するデータを引数として受け取ります。署名を処理結果として取得できるPromiseが返されます。

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

パラメーター

algorithm

SignatureAlgorithm

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

• RSASSA-PKCS1-v1_5を使用するには、文字列"RSASSA-PKCS1-v1_5"または{ name: "RSASSA-PKCS1-v1_5" }形式のオブジェクトを渡します。
• RSA-PSSを使用するには、RsaPssParamsオブジェクトを渡します。
• ECDSAを使用するには、EcdsaParamsオブジェクトを渡します。
• HMACを使用するには、文字列"HMAC"、または { name: "HMAC" }形式のオブジェクトを渡します。

key

CryptoKey

署名に使用するキーを含むCryptoKeyオブジェクト。アルゴリズムがパブリックキー暗号システムを識別する場合、これがプライベートキーになります。

data

BufferSource

署名するデータを含むArrayBuffer、TypedArray、またはDataViewオブジェクト。

戻り値

Promise<ArrayBuffer>

署名を含むArrayBufferを処理結果として取得できるPromise。

スロー

InvalidArgumentError：アルゴリズムパラメーターが無効な場合に発生します。

スロー

アルゴリズムがサポートされていない場合、NotSupportedErrorがスローされます。

---

verify()

verify: (algorithm, key, signature, data) => Promise<boolean>

SubtleCryptoインターフェイスのverify() メソッドは、デジタル署名を検証します。

署名を検証するためのキー、アルゴリズム固有のパラメーター、シグニチャー、および元の署名対象のデータを引数として受け取ります。署名が有効かどうかを示すブール値を処理結果として取得できるPromiseが返されます。

パラメーター

algorithm

SignatureAlgorithm

使用するアルゴリズムを定義する文字列またはオブジェクト。一部のアルゴリズムの選択では追加パラメーターも定義します。追加パラメーターに指定する値は、対応するsign呼び出しに渡される値と一致する必要があります。

• RSASSA-PKCS1-v1_5を使用するには、文字列"RSASSA-PKCS1-v1_5"または{ "name": "RSASSA-PKCS1-v1_5" }形式のオブジェクトを渡します。
• RSA-PSSを使用するには、RsaPssParamsオブジェクトを渡します。
• ECDSAを使用するには、EcdsaParamsオブジェクトを渡します。
• HMACを使用するには、文字列"HMAC"、または { "name": "HMAC" }形式のオブジェクトを渡します。

key

CryptoKey

署名の検証に使用されるキーを含むCryptoKey。対称アルゴリズムの場合はシークレットキー、パブリックキーシステムの場合はパブリックキーです。

signature

ArrayBuffer

検証する署名を含むArrayBuffer。

data

ArrayBuffer

署名を検証するデータを含むArrayBuffer。

戻り値

Promise<boolean>

ブール値を処理結果として取得できるPromise。署名が有効な場合はtrue、それ以外の場合はfalse。

スロー

InvalidArgumentError：アルゴリズムパラメーターが無効な場合に発生します。

スロー

アルゴリズムがサポートされていない場合、NotSupportedErrorがスローされます。

---

Last updated: 2025年10月2日