SubtleCrypto

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.

* 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()

引数に与えられたラップされた鍵に対応する CryptoKeyPromise を返します。

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 #8JSON 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 API
# subtlecrypto-interface

ブラウザーの互換性

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
Node.js
SubtleCrypto
decrypt
deriveBits
X25519 algorithm
deriveKey
AES as derivedKeyAlgorithm option value
HKDF as derivedKeyAlgorithm option value
HMAC as derivedKeyAlgorithm option value
PBKDF2 as derivedKeyAlgorithm option value
X25519 algorithm
digest
encrypt
exportKey
Ed25519 algorithm
X25519 algorithm
generateKey
Ed25519 algorithm
X25519 algorithm
importKey
Ed25519 algorithm
X25519 algorithm
Secure context required
sign
Ed25519 algorithm
unwrapKey
verify
Ed25519 algorithm
Available in workers
wrapKey

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
Partial support
Partial support
In development. Supported in a pre-release version.
In development. Supported in a pre-release version.
No support
No support
See implementation notes.
User must explicitly enable this feature.
Requires a vendor prefix or different name for use.
Has more compatibility info.

関連情報