SubtleCrypto

Baseline Widely available *

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

* Some parts of this feature may have varying levels of support.

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

SubtleCrypto はウェブ暗号化 API のインターフェイスで、数々の低水準の暗号化関数を提供します。 SubtleCrypto の機能にアクセスするには、 crypto プロパティから取得した Crypto オブジェクトの subtle プロパティを使用します。

警告: このAPIは、数多くの低レベル暗号プリミティブを提供しています。これらを悪用するのはとても簡単で、その落とし穴は非常に微妙なものです。

基本的な暗号機能を正しく使用すると想定されていても、安全な鍵管理と全体的なセキュリティシステムの設計を正しく行うのは非常に難しく、一般的にはセキュリティの専門家の領域です。

セキュリティシステムの設計と実装に誤りがあると、システムのセキュリティが完全に機能しなくなる可能性があります。

学び、実験してください。しかし、このテーマに詳しい人物が徹底的にレビューする前に、あなたの作品の安全性を保証したり、ほのめかしたりしないでください。暗号 101 コースは、安全なシステムの設計と実装するために学び始めるには最適な場所です。

インスタンスプロパティ

このインターフェイスには親インターフェイスがないので、何もプロパティを継承していません。

インスタンスメソッド

このインターフェイスには親インターフェイスがないので、何もメソッドを継承していません。

SubtleCrypto.encrypt(): 引数に与えられた平文テキストおよびアルゴリズム、鍵に対応する暗号化されたデータで履行される Promise を返します。
SubtleCrypto.decrypt(): 引数に与えられた暗号化されたテキストおよびアルゴリズム、鍵に対応する平文データで履行される Promise を返します。
SubtleCrypto.sign(): 引数に与えられたテキストおよびアルゴリズム、鍵に対応する署名で履行される Promise を返します。
SubtleCrypto.verify(): 引数に与えられた署名が、同じく引数に与えられたテキストおよびアルゴリズム、鍵と一致するかどうかを示す論理値で履行される Promise を返します。
SubtleCrypto.digest(): 引数に与えられたアルゴリズムとテキストから生成されたダイジェストで履行される Promise を返します。
SubtleCrypto.generateKey(): 対称アルゴリズムの場合は新しく生成された CryptoKey で、非対称アルゴリズムの場合は新しく生成された 2 つの鍵を含む CryptoKeyPair で履行される Promise を返します。これらは、引数として指定されたアルゴリズム、使用法、抽出可能性と一致します。
SubtleCrypto.deriveKey(): 引数に与えられたマスターキーと特定のアルゴリズムによりもたらされる、新たに生成された CryptoKey で履行される Promise を返します。
SubtleCrypto.deriveBits(): 引数に与えられたマスターキーと特定のアルゴリズムによりもたらされる、新たに生成された擬似乱数のビット列を含むバッファーで履行される Promise を返します。
SubtleCrypto.importKey(): 引数に与えられた書式およびアルゴリズム、生の鍵データ、使用法、抽出可能性に対応する CryptoKey で履行される Promise を返します。
SubtleCrypto.exportKey(): 要求された書式の鍵を含むバッファーで履行される Promise を返します。
SubtleCrypto.wrapKey(): 安全でない環境で使用（転送や保存）するために、ラップされた対称鍵で履行される Promise を返します。返されるラップされたバッファーは、引数に与えられた書式内にあり、与えられたアルゴリズムで与えられたラッピング鍵によりラップされた鍵を含みます。
SubtleCrypto.unwrapKey(): 引数に与えられたラップされた鍵に対応する CryptoKey の Promise を返します。

SubtleCrypto の使用

この API で実装する機能は、暗号化機能と鍵管理機能の 2 つに分けることができます。

暗号化関数

これらは、システムにプライバシーや認証などのセキュリティ機能を実装するために使用することができる関数です。 SubtleCrypto API は以下の暗号化関数を提供ししています。

sign() および verify(): デジタル署名の作成と検証
encrypt() および decrypt(): データの暗号化と復号
digest(): あるデータの固定長で衝突に強いダイジェストを作成します。

鍵管理関数

digest() を除き、 API 内の暗号機能はすべて暗号鍵を使用しています。 SubtleCrypto API では、暗号鍵は CryptoKey オブジェクトを使用して表します。署名や暗号化などの演算処理を実行するには、 CryptoKey オブジェクトを sign() または encrypt() 関数に渡します。

キーの生成と導出

generateKey() および deriveKey() 関数は、どちらも新しい CryptoKey オブジェクトを作成します。

この違いは、 generateKey() が呼び出すたびに新しい鍵を生成するのに対し、 deriveKey() は最初の鍵素材から鍵を導出する点です。同じ鍵素材を 2 回に分けて deriveKey() を呼び出すと、同じ基盤値がある 2 つの CryptoKey オブジェクトを取得することができます。この例は、例えばパスワードから暗号鍵を導出し、後で同じパスワードから同じ鍵を導出してデータを復号したい場合に有益です。

鍵のインポートとエクスポート

アプリの外部で鍵を利用できるようにするには、鍵をエクスポートする必要があります。それが exportKey() です。エクスポート形式はいくつか選べます。

exportKey() の逆は importKey() です。他のシステムから鍵をインポートすることができ、 PKCS #8 や JSON Web Key のような標準形式に対応しているため、これを支援することができます。 exportKey() 関数は暗号化されていない形式で鍵をエクスポートします。

鍵が機密性の高いものである場合、 wrapKey() を使用してください。これは鍵をエクスポートし、別の鍵を使用して暗号化するもので、 API では「鍵ラッピング鍵」と呼ばれています。

wrapKey() の逆は unwrapKey() で、鍵を復号してからインポートします。

鍵の格納

CryptoKey オブジェクトは、構造化複製アルゴリズムを使用して格納することができます。すなわち、標準のウェブストレージ API を使用して、鍵を格納したり受け取ったりすることができます。この仕様書では、ほとんどの開発者が IndexedDB API を使用して CryptoKey オブジェクトを格納することを想定しています。

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

ウェブ暗号 API が提供した暗号関数は、 1 つ以上の異なる「暗号アルゴリズム」によって実行することができます。関数の algorithm 引数は、使用するアルゴリズムを示します。アルゴリズムによっては追加の引数が必要です。このような場合、 algorithm 引数は追加の引数を含めるために辞書オブジェクトになります。

下記の表は、どのアルゴリズムがどの暗号処理を運営するのに適しているかをまとめたものです。

	sign() verify()	encrypt() decrypt()	digest()	deriveBits() deriveKey()	wrapKey() unwrapKey()
RSASSA-PKCS1-v1_5	✓
RSA-PSS	✓
ECDSA	✓
HMAC	✓
RSA-OAEP		✓			✓
AES-CTR		✓			✓
AES-CBC		✓			✓
AES-GCM		✓			✓
SHA-1			✓
SHA-256			✓
SHA-384			✓
SHA-512			✓
ECDH				✓
HKDF				✓
PBKDF2				✓
AES-KW					✓

仕様書

Specification
Web Cryptography Level 2 # subtlecrypto-interface