SubtleCrypto

基于Web Crypto APISubtleCrypto 接口提供了许多底层加密功能。它通过窗口上下文提供可用的Crypto.subtle 属性来访问(通过Window.crypto)。

注意: 此API提供了许多底层加密源语。滥用他们很容易陷入微妙的陷阱中。

即使你正确的使用基础加密方法,也很难设计一套正确的安全密钥管理及整体安全设计方案,这些往往是安全专家的领域。

错误的安全系统设计和实现会使系统的安全性完全失效

如果你不知道此API能为你提供什么,则不应该使用该API

概览

我们可以将此API的功能分为两类:加密功能和密钥管理功能。

加密功能

这些函数你可以用来实现系统中的隐私和身份验证等安全功能。SubtleCrypto API提供了如下加密函数:

sign() 、 verify(): 创建和验证数字签名。
* encrypt()decrypt(): 加密和解密数据。
* digest():为数据生成一个定长的,防碰撞的消息摘要。

密钥管理功能

除了 digest(),在SubtleCrypto API中所有加密功能都会使用密钥,并使用CryptoKey对象表示加密密钥。要执行签名和加密操作, 请将 CryptoKey 对象传参给 sign() 或 encrypt() 函数.

生成和派生密钥

generateKey() 和 deriveKey() 函数都可以创建一个新的 CryptoKey 对象。

不同之处在于 generateKey() 每次都会生成一个新的键值对, 而 deriveKey() 通过从基础密钥资源中生成一个新的密钥。如果为两个独立的deriveKey()提供相同的基础密钥资源,那么你会获得两个具有相同基础值的 CryptoKey 对象。如果你想通过密码派生加密密钥,然后从相同的密码派生相同的密钥以解密数据,那么这将会非常有用。

导入和导出密钥

要在应用程序外部使密钥可用,您需要导出密钥,exportKey() 可以为你提供该功能。你可以选择多种导出格式。

importKey()与 exportKey() 刚好相反。你可以从其他系统导入密钥,并且支持像 PKCS #8 和 JSON Web Key 这样可以帮助你执行此操作的标准格式。exportKey() 函数以非标准格式导出密钥。

如果密钥是敏感的,你需要使用 wrapKey(), 该函数导出密钥并且使用另外一个密钥加密它。

unwrapKey()wrapKey()相反,该函数解密密钥后导入解密的密钥

存储密钥

CryptoKey对象可以通过 structured clone algorithm来存储,这意味着你可以通过web storage APIs来存储和获取他们。更为规范的方式是通过使用IndexedDB API 来存储CryptoKey对象。

支持的算法

Web Crypto API提供的加密函数可以由一个或多个不同的加密算法执行:

函数可以通过参数来指定使用的算法。一些算法需要额外的参数,在这些情况下通过将算法参数作为对象字典传入额外的参数中实现。

下表总结了哪些算法适用于哪些加密操作:

 

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        

属性

此接口既不继承也不实现任何属性。

方法

此接口不继承任何方法。

SubtleCrypto.encrypt()
以算法、密钥、明文为参数,返回一个包含加密数据的 Promise 对象。
SubtleCrypto.decrypt()
以算法、密钥、密文为参数,返回一个包含解密数据的 Promise 对象。
SubtleCrypto.sign() (en-US)
以文本、算法和密码为参数,返回一个包含签名的 Promise
SubtleCrypto.verify() (en-US)
以签名、与之匹配的文本、算法、密码为参数,验证签名的真实性,返回一个包含布尔型的 {jsxref("Promise")}} 对象。
SubtleCrypto.digest() (en-US)
以生成摘要的算法和文本作为参数,返回一个包含数据摘要的 Promise 对象。
SubtleCrypto.generateKey() (en-US)
以给出的用法和返可提取性作为参数,返回一个包含用于对称算法的新生成的 CryptoKey 或者包含两个新的生成的密钥用于非对称加密的 CryptoKeyPair (en-US) 的 Promise 对象。
SubtleCrypto.deriveKey() (en-US)
以从 master key 派生出来的密钥和特定的算法作为参数,返回一个包含新生成的 CryptoKey  的 Promise对象。
SubtleCrypto.deriveBits() (en-US)
以从 master key 派生出来的密钥和特定的算法作为参数,返回一个包含新生成的伪随机字节的 Buffer的 Promise 对象。
SubtleCrypto.importKey() (en-US)
以格式、算法、原始密钥数据、用途和可提取性作为参数,返回一个包含 CryptoKey 的 Promise 对象。
SubtleCrypto.exportKey() (en-US)
返回一个包含所请求格式的密钥的 Buffer 的 Promise 对象。
SubtleCrypto.wrapKey() (en-US)
返回一个包含在不安全环境中使用(传输,存储)的包裹对称密钥的 Promise 对象。返回的被包裹的缓冲数据是按照参数中给出的格式的,包含使用给定算法的给予包装密钥包裹的密钥。
SubtleCrypto.unwrapKey() (en-US)
返回一个包含对应于参数中给出的包裹密钥的 CryptoKeyPromise 对象。

规范

Specification Status Comment
Web Cryptography API
SubtleCrypto
Recommendation Initial definition.

浏览器支持

We're converting our compatibility data into a machine-readable JSON format. This compatibility table still uses the old format, because we haven't yet converted the data it contains. Find out how you can help! (en-US)

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support 37 34 (34) 未实现 ? 未实现
Feature Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support 37 37 34.0 (34) 未实现 ? 未实现

另见