在此页

• 特性
• 方法
• Using SubtleCrypto
• 规范
• 浏览器兼容性
• 另请参阅
• 相关话题

安全上下文
此特征只可用于 安全上下文 (HTTPS)，在某些或所有 支持浏览器 .

SubtleCrypto 接口在 Web 加密 API provides a number of low-level cryptographic functions. Access to the features of SubtleCrypto is obtained through the subtle 特性为 Crypto object you get from Window.crypto .

警告： This API provides a number of low-level cryptographic primitives. It's very easy to misuse them, and the pitfalls involved can be very subtle.

Even assuming you use the basic cryptographic functions correctly, secure key management and overall security system design are extremely hard to get right, and are generally the domain of specialist security experts.

Errors in security system design and implementation can make the security of the system completely ineffective.

If you're not sure you know what you are doing, you probably shouldn't be using this API.

特性

This interface doesn't inherit any properties, as it has no parent interface.

方法

This interface doesn't inherit any methods, as it has no parent interface.

SubtleCrypto.encrypt()

返回 Promise that fufills with the encrypted data corresponding to the clear text, algorithm, and key given as parameters.

SubtleCrypto.decrypt()

返回 Promise that fulfills with the clear data corresponding to the encrypted text, algorithm, and key given as parameters.

SubtleCrypto.sign()

返回 Promise that fulfills with the signature corresponding to the text, algorithm, and key given as parameters.

SubtleCrypto.verify()

返回 Promise that fulfills with a 布尔 value indicating if the signature given as a parameter matches the text, algorithm, and key that are also given as parameters.

SubtleCrypto.digest()

返回 Promise that fulfills with a digest generated from the algorithm and text given as parameters.

SubtleCrypto.generateKey()

返回 Promise that fulfills with a newly-generated CryptoKey , for symmetrical algorithms, or a CryptoKeyPair , containing two newly generated keys, for asymmetrical algorithms. These will match the algorithm, usages, and extractability given as parameters.

SubtleCrypto.deriveKey()

返回 Promise that fulfills with a newly generated CryptoKey derived from the master key and specific algorithm given as parameters.

SubtleCrypto.deriveBits()

返回 Promise that fulfills with a newly generated buffer of pseudo-random bits derived from the master key and specific algorithm given as parameters.

SubtleCrypto.importKey()

返回 Promise that fulfills with a CryptoKey corresponding to the format, the algorithm, raw key data, usages, and extractability given as parameters.

SubtleCrypto.exportKey()

返回 Promise that fulfills with a buffer containing the key in the requested format.

SubtleCrypto.wrapKey()

返回 Promise that fulfills with a wrapped symmetric key for usage (transfer and storage) in insecure environments. The wrapped key matches the format specified in the given parameters, and wrapping is done by the given wrapping key, using the specified algorithm.

SubtleCrypto.unwrapKey()

返回 Promise that fulfills with a CryptoKey corresponding to the wrapped key given in the parameter.

Using SubtleCrypto

We can split the functions implemented by this API into two groups: cryptography functions and key management functions.

Cryptography functions

These are the functions you can use to implement security features such as privacy and authentication in a system. The SubtleCrypto API provides the following cryptography functions:

* sign() and verify() : create and verify digital signatures.
* encrypt() and decrypt() : encrypt and decrypt data.
* digest() : create a fixed-length, collision-resistant digest of some data.

Key management functions

Except for digest() , all the cryptography functions in the API use cryptographic keys. In the SubtleCrypto API a cryptographic key is represented using a CryptoKey object. To perform operations like signing and encrypting, you pass a CryptoKey object into the sign() or encrypt() 函数。

Generating and deriving keys

generateKey() and deriveKey() functions both create a new CryptoKey 对象。

The difference is that generateKey() will generate a new distinct key value each time you call it, while deriveKey() derives a key from some initial keying material. If you provide the same keying material to two separate calls to deriveKey() , you will get two CryptoKey objects that have the same underlying value. This is useful if, for example, you want to derive an encryption key from a password and later derive the same key from the same password to decrypt the data.

Importing and exporting keys

To make keys available outside your app, you need to export the key, and that's what exportKey() is for. You can choose one of a number of export formats.

逆 exportKey() is importKey() . You can import keys from other systems, and support for standard formats like PKCS #8 and JSON Web Key helps you do this. The exportKey() function exports the key in an unencrypted format.

If the key is sensitive you should use wrapKey() , which exports the key and then encrypts it using another key; the API calls a "key-wrapping key".

逆 wrapKey() is unwrapKey() , which decrypts then imports the key.

Storing keys

CryptoKey objects can be stored using the structured clone algorithm , meaning that you can store and retrieve them using standard web storage APIs. The specification expects that most developers will use the IndexedDB API to store CryptoKey 对象。

Supported algorithms

The cryptographic functions provided by the Web Crypto API can be performed by one or more different cryptographic algorithms : the algorithm argument to the function indicates which algorithm to use. Some algorithms need extra parameters: in these cases the algorithm argument is a dictionary object that includes the extra parameters.

The table below summarises which algorithms are suitable for which cryptographic operations:

	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					✓

规范

规范	状态	注释
Web Cryptography API The definition of 'SubtleCrypto' in that specification.	推荐	初始定义。

浏览器兼容性

The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request. 更新 GitHub 上的兼容性数据

	桌面						移动
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet
SubtleCrypto	Chrome 37	Edge 部分支持 12	Firefox 34 34 不支持 32 — 34 Disabled Disabled ). To change preferences in Firefox, visit	IE 部分支持 11	Opera 24	Safari 10.1 10.1 7 Prefixed Prefixed Implemented with the vendor prefix: WebKit	WebView Android 37	Chrome Android 37	Firefox Android 34 34 不支持 32 — 34 Disabled Disabled ). To change preferences in Firefox, visit	Opera Android 24	Safari iOS 10.3 10.3 7 Prefixed Prefixed Implemented with the vendor prefix: WebKit	Samsung Internet Android 6.0
decrypt	Chrome 37	Edge 部分支持 12 部分支持 12 Not supported: AES-CTR.	Firefox 34 34 不支持 32 — 34 Disabled Disabled ). To change preferences in Firefox, visit	IE 部分支持 11 部分支持 11 返回 CryptoOperation 而不是 Promise	Opera 24	Safari 7	WebView Android 37	Chrome Android 37	Firefox Android 34 34 不支持 32 — 34 Disabled Disabled ). To change preferences in Firefox, visit	Opera Android 24	Safari iOS 7	Samsung Internet Android 6.0
deriveBits	Chrome 37	Edge 部分支持 12 部分支持 12 Not supported: ECDH. Not supported: HKDF, PBKDF2.	Firefox 34 34 不支持 32 — 34 Disabled Disabled ). To change preferences in Firefox, visit	IE No	Opera 24	Safari 7	WebView Android 37	Chrome Android 37	Firefox Android 34 34 不支持 32 — 34 Disabled Disabled ). To change preferences in Firefox, visit	Opera Android 24	Safari iOS 7	Samsung Internet Android 6.0
deriveKey	Chrome 37	Edge 部分支持 12 部分支持 12 Not supported: ECDH. Not supported: HKDF, PBKDF2.	Firefox 34 34 不支持 32 — 34 Disabled Disabled ). To change preferences in Firefox, visit	IE No	Opera 24	Safari 7	WebView Android 37	Chrome Android 37	Firefox Android 34 34 不支持 32 — 34 Disabled Disabled ). To change preferences in Firefox, visit	Opera Android 24	Safari iOS 7	Samsung Internet Android 6.0
digest	Chrome 37	Edge 部分支持 12 部分支持 12 Not supported: SHA-1.	Firefox 34 34 不支持 32 — 34 Disabled Disabled ). To change preferences in Firefox, visit	IE 部分支持 11 部分支持 11 返回 CryptoOperation 而不是 Promise	Opera 24	Safari 7	WebView Android 37	Chrome Android 37	Firefox Android 34 34 不支持 32 — 34 Disabled Disabled ). To change preferences in Firefox, visit	Opera Android 24	Safari iOS 7	Samsung Internet Android 6.0
encrypt	Chrome 37	Edge 部分支持 12 部分支持 12 Not supported: AES-CTR.	Firefox 34 34 不支持 32 — 34 Disabled Disabled ). To change preferences in Firefox, visit	IE 部分支持 11 部分支持 11 返回 CryptoOperation 而不是 Promise	Opera 24	Safari 7	WebView Android 37	Chrome Android 37	Firefox Android 34 34 不支持 32 — 34 Disabled Disabled ). To change preferences in Firefox, visit	Opera Android 24	Safari iOS 7	Samsung Internet Android 6.0
exportKey	Chrome 37	Edge 部分支持 12 部分支持 12 Not supported: RSA-PSS, ECDSA, ECDH. Not supported: AES-CTR.	Firefox 34 34 不支持 32 — 34 Disabled Disabled ). To change preferences in Firefox, visit	IE 部分支持 11 部分支持 11 返回 KeyOperation 而不是 Promise	Opera 24	Safari 7	WebView Android 37	Chrome Android 37	Firefox Android 34 34 不支持 32 — 34 Disabled Disabled ). To change preferences in Firefox, visit	Opera Android 24	Safari iOS 7	Samsung Internet Android 6.0
generateKey	Chrome 37	Edge 部分支持 12 部分支持 12 Not supported: RSA-PSS, ECDSA, ECDH. Not supported: AES-CTR.	Firefox 34 34 不支持 32 — 34 Disabled Disabled ). To change preferences in Firefox, visit	IE 部分支持 11 部分支持 11 返回 KeyOperation 而不是 Promise	Opera 24	Safari 7	WebView Android 37	Chrome Android 37	Firefox Android 34 34 不支持 32 — 34 Disabled Disabled ). To change preferences in Firefox, visit	Opera Android 24	Safari iOS 7	Samsung Internet Android 6.0
importKey	Chrome 37	Edge 部分支持 12 部分支持 12 Not supported: RSA-PSS, ECDSA, ECDH. Not supported: AES-CTR, HKDF, PBKDF2.	Firefox 34 34 不支持 32 — 34 Disabled Disabled ). To change preferences in Firefox, visit	IE 部分支持 11 部分支持 11 返回 KeyOperation 而不是 Promise	Opera 24	Safari 7	WebView Android 37	Chrome Android 37	Firefox Android 34 34 不支持 32 — 34 Disabled Disabled ). To change preferences in Firefox, visit	Opera Android 24	Safari iOS 7	Samsung Internet Android 6.0
Secure context required	Chrome 60	Edge 79	Firefox 75	IE No	Opera 47	Safari No	WebView Android 60	Chrome Android 60	Firefox Android No	Opera Android 47	Safari iOS No	Samsung Internet Android No
sign	Chrome 37	Edge 部分支持 12 部分支持 12 Not supported: RSA-PSS, ECDSA.	Firefox 34 34 不支持 32 — 34 Disabled Disabled ). To change preferences in Firefox, visit	IE 部分支持 11 部分支持 11 返回 CryptoOperation 而不是 Promise	Opera 24	Safari 7	WebView Android 37	Chrome Android 37	Firefox Android 34 34 不支持 32 — 34 Disabled Disabled ). To change preferences in Firefox, visit	Opera Android 24	Safari iOS 7	Samsung Internet Android 6.0
unwrapKey	Chrome 37	Edge 部分支持 12 部分支持 12 Not supported: AES-CTR.	Firefox 34 34 不支持 32 — 34 Disabled Disabled ). To change preferences in Firefox, visit	IE 部分支持 11 部分支持 11 返回 KeyOperation 而不是 Promise	Opera 24	Safari 7	WebView Android ?	Chrome Android 37	Firefox Android 34 34 不支持 32 — 34 Disabled Disabled ). To change preferences in Firefox, visit	Opera Android 24	Safari iOS 7	Samsung Internet Android 6.0
verify	Chrome 37	Edge 部分支持 12 部分支持 12 Not supported: RSA-PSS, ECDSA.	Firefox 34 34 不支持 32 — 34 Disabled Disabled ). To change preferences in Firefox, visit	IE 部分支持 11 部分支持 11 返回 CryptoOperation 而不是 Promise	Opera 24	Safari 7	WebView Android 37	Chrome Android 37	Firefox Android 34 34 不支持 32 — 34 Disabled Disabled ). To change preferences in Firefox, visit	Opera Android 24	Safari iOS 7	Samsung Internet Android 6.0
Available in workers	Chrome ?	Edge ?	Firefox 48	IE ?	Opera ?	Safari ?	WebView Android ?	Chrome Android ?	Firefox Android ?	Opera Android ?	Safari iOS ?	Samsung Internet Android ?
wrapKey	Chrome 37	Edge 部分支持 12 部分支持 12 Not supported: AES-CTR.	Firefox 34 34 不支持 32 — 34 Disabled Disabled ). To change preferences in Firefox, visit	IE 部分支持 11 部分支持 11 返回 KeyOperation 而不是 Promise	Opera 24	Safari 7	WebView Android 37	Chrome Android 37	Firefox Android 34 34 不支持 32 — 34 Disabled Disabled ). To change preferences in Firefox, visit	Opera Android 24	Safari iOS 7	Samsung Internet Android 6.0

图例

完整支持

完整支持

部分支持

部分支持

不支持

不支持

兼容性未知 ?

兼容性未知

见实现注意事项。

用户必须明确启用此特征。

用户必须明确启用此特征。

要求使用供应商前缀或不同名称。

要求使用供应商前缀或不同名称。

另请参阅

• Web 加密 API
• Web security
• Privacy, permissions, and information security
• Crypto and Crypto.subtle .
• Crypto 101 : an introductory course on cryptography.

元数据

• 最后修改： Mar 23, 2020

相关话题

1. Web 加密 API
2. SubtleCrypto
3. 方法

   1. decrypt()
   2. deriveBits()
   3. deriveKey()
   4. digest()
   5. encrypt()
   6. exportKey()
   7. generateKey()
   8. importKey()
   9. sign()
   10. unwrapKey()
   11. verify()
   12. wrapKey()
4. Related pages for Web Crypto API

   1. Crypto
   2. CryptoKey
   3. CryptoKeyPair
   4. RandomSource
   5. Window.crypto