SubtleCrypto
Web Crypto API的SubtleCrypto接口提供了许多低级加密功能。
接口名称包含“subtle”一词，表示许多算法都有较为细微的使用要求，因此必须谨慎使用才能提供适当的安全保障。
属性
decrypt()
decrypt: (
algorithm,key,data) =>Promise<ArrayBuffer>
SubtleCrypto接口的decrypt() 方法可对一些加密后的数据进行解密。此方法接受的参数包括用于解密的密钥、一些可选的额外参数和要解密的数据（也称为“密文”）。此方法会返回将通过解密后的数据（也称为“明文”）来实现的Promise。
参数
algorithm
一个对象，用于指定要使用的算法以及所需的任何额外参数。为额外参数提供的值必须与传递给相应encrypt调用的值相匹配。
- 要使用RSA-OAEP，请传递一个RsaOaepParams对象。
- 要使用AES-CTR，请传递一个AesCtrParams对象。
- 要使用AES-CBC，请传递一个AesCbcParams对象。
- 要使用AES-GCM，请传递一个AesGcmParams对象。
key
CryptoKey，其中包含用于解密的密钥。如果使用RSA-OAEP，则为CryptoKeyPair对象的privateKey属性。
data
ArrayBuffer、TypedArray或DataView，其中包含待解密的数据（也称为“密文”）。
返回值
Promise<ArrayBuffer>
使用包含明文的ArrayBuffer来实现的Promise。
抛出
如果算法参数无效或缺少必填字段，则抛出InvalidArgumentError
抛出
如果算法不受支持或参数包含不受支持的值，则抛出NotSupportedError
deriveBits()
deriveBits: (
algorithm,baseKey,length) =>Promise<ArrayBuffer>
SubtleCrypto接口的deriveBits() 方法可用于从基本密钥派生出位数组。
此方法接受的参数包括基本密钥、要使用的派生算法和要派生的位长度。此方法会返回将使用包含派生位的ArrayBuffer来实现的Promise。
参数
algorithm
一个对象，用于定义要使用的派生算法。
- 要使用ECDH，请传递一个EcdhKeyDeriveParams对象，指定字符串
“ECDH”作为name属性。 - 要使用HKDF，请传递一个HkdfParams对象。
- 要使用PBKDF2，请传递一个Pbkdf2Params对象。
baseKey
表示派生算法输入的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
一个对象，用于定义要使用的派生算法。
- 要使用ECDH，请传递一个EcdhKeyDeriveParams对象，指定字符串
“ECDH”作为name属性。 - 要使用HKDF，请传递一个HkdfParams对象。
- 要使用PBKDF2，请传递一个Pbkdf2Params对象。
baseKey
表示派生算法输入的CryptoKey。如果算法是ECDH，则为ECDH私钥。否则，它将是派生函数的初始密钥材料：例如，对于PBKDF2，它可能是一个密码，并使用SubtleCrypto.importKey作为CryptoKey导入。
derivedKeyAlgorithm
定义派生密钥将用于哪个算法的对象：
- 对于HMAC，传递一个HmacKeyGenParams对象。
- 对于AES-CTR、AES-CBC或AES-GCM，传递一个AesKeyGenParams对象。
- 对于HKDF，传递一个HkdfParams对象。
- 对于PBKDF2，传递一个Pbkdf2Params对象。
extractable
boolean
一个布尔值，表示是否可以使用 () 导出密钥。
keyUsages
KeyUsage[]
一个数组，表示可以用派生密钥执行的操作。请注意，在derivedKeyAlgorithm中设置的算法必须允许使用密钥。数组可能的值为：
encrypt： 密钥可用于加密消息。decrypt： 密钥可用于解密消息。sign： 密钥可用于对消息签名。verify: 密钥可用于验证签名。deriveKey: 密钥可用于派生新密钥。deriveBits: 密钥可用于派生位。wrapKey： 密钥可用于封装其他密钥。unwrapKey: 密钥可用于解封装其他密钥。
返回值
Promise<CryptoKey>
使用CryptoKey实现的Promise。
抛出
如果指定的派生算法不受支持，则抛出NotSupportedError。
抛出
如果算法参数无效，则抛出InvalidArgumentError。
digest()
digest: (
algorithm,data) =>Promise<ArrayBuffer>
SubtleCrypto接口的digest() 方法会使用指定的哈希函数生成给定数据的摘要。摘要是源自某些可变长度输入的短固定长度值。加密摘要应具有抗碰撞性，这意味着很难找到两个具有相同摘要值的不同输入。
此方法接受的参数包括要使用的摘要算法的标识符以及需要进行摘要处理的数据。此方法会返回将通过摘要来实现的Promise。
请注意，此API不支持流式输入：您必须先将整个输入读入内存，然后才能将其传递到摘要函数。
参数
algorithm
这既可以是字符串，也可以是只有一个属性名称（即字符串）的对象。该字符串用于指定要使用的哈希函数。支持的值：
SHA-256SHA-384SHA-512
data
ArrayBuffer、TypedArray或DataView对象，其中包含要进行摘要处理的数据。
返回值
Promise<ArrayBuffer>
使用包含摘要的ArrayBuffer来实现的Promise。
抛出
如果指定的哈希函数不受支持，则抛出NotSupportedError。
抛出
如果输入参数无效，则抛出InvalidArgumentError。
encrypt()
encrypt: (
algorithm,key,data) =>Promise<ArrayBuffer>
SubtleCrypto接口的encrypt() 方法会对数据进行加密。
此方法接受的参数包括用于加密的密钥、一些特定于算法的参数和要加密的数据（也称为“明文”）。此方法会返回将通过加密数据（也称为“密文”）来实现的Promise。
参数
algorithm
一个对象，用于指定要使用的算法以及任何额外的参数（如有需要）：
- 要使用RSA-OAEP，请传递一个RsaOaepParams对象。
- 要使用AES-CTR，请传递一个AesCtrParams对象。
- 要使用AES-CBC，请传递一个AesCbcParams对象。
- 要使用AES-GCM，请传递一个AesGcmParams对象。
key
CryptoKey，其中包含用于加密的密钥。
data
ArrayBuffer、TypedArray或DataView，其中包含待加密的数据（也称为“明文”）。
返回值
Promise<ArrayBuffer>
使用包含“明文”的ArrayBuffer来实现的Promise。
抛出
如果算法参数无效或缺少必填字段，则抛出InvalidArgumentError
抛出
如果算法不受支持或参数包含不受支持的值，则抛出NotSupportedError
exportKey()
exportKey: (
format,key) =>Promise<ArrayBuffer|JsonWebKey>
SubtleCrypto接口的exportKey() 方法会导出密钥：也就是说，它将CryptoKey对象作为输入，并以外部可移植格式为您提供密钥。
要导出密钥，该密钥的CryptoKey.extractable必须设置为true。密钥支持以多种格式导出。
参数
format
一个字符串值，用于描述应以何种数据格式导出密钥。格式可以是以下任一项：
raw： 原始格式（用于对称密钥或椭圆曲线公钥）。pkcs8: PKCS #8格式（用于私钥）。spki： SubjectPublicKeyInfo格式（用于公钥）。jwk： JSON Web密钥格式（用于对称或非对称密钥）。
key
要导出的CryptoKey。
返回值
Promise<ArrayBuffer | JsonWebKey>
Promise。
- 如果格式为jwk，则Promise通过包含密钥的JSON对象来实现。
- 否则，Promise使用包含密钥的
ArrayBuffer来实现。
抛出
如果密钥不可提取，则抛出InvalidArgumentError
抛出
如果请求格式不受给定密钥类型的支持，则抛出NotSupportedError
generateKey()
generateKey: (
algorithm,extractable,keyUsages) =>Promise<CryptoKey|CryptoKeyPair>
SubtleCrypto接口的generateKey() 方法用于生成新密钥（用于对称算法）或密钥对（用于公钥算法）。
参数
algorithm
一个对象，用于定义要生成的密钥类型并提供特定于算法的额外参数。
- 对于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
一个字符串，用于描述要导入的密钥的数据格式。格式可以是以下任一项：
raw： 原始格式（用于对称密钥或椭圆曲线公钥）。pkcs8: PKCS #8格式（用于私钥）。spki： SubjectPublicKeyInfo格式（用于公钥）。jwk： JSON Web密钥格式。
keyData
ArrayBuffer、TypedArray、DataView或JSONWebKey对象，其中包含给定格式的密钥。
JsonWebKey |
BufferSource |
algorithm
一个对象，用于定义要导入的密钥类型并提供特定于算法的额外参数。
- 对于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。
抛出
如果格式无效或keyData与要求的格式不匹配，则抛出InvalidArgumentError
抛出
如果算法或密钥格式组合不受支持，则抛出NotSupportedError
sign()
sign: (
algorithm,key,data) =>Promise<ArrayBuffer>
SubtleCrypto接口的sign() 方法可生成数字签名。
此方法接受的参数包括用于签名的密钥、一些特定于算法的参数和要签名的数据。此方法会返回将通过签名来实现的Promise。
您可以使用相应的SubtleCrypto.verify方法来验证签名。
参数
algorithm
一个字符串或对象，可指定要使用的签名算法及其参数：
- 要使用RSASSA-PKCS1-v1_5，请传递字符串
"RSASSA-PKCS1-v1_5"或形式为{name: "RSASSA-PKCS1-v1_5"}的对象。 - 要使用RSA-PSS，请传递一个RsaPssParams对象。
- 要使用ECDSA，请传递一个EcdsaParams对象。
- 要使用HMAC，请传递字符串
"HMAC"或形式为 {name: "HMAC"} 的对象。
key
一个CryptoKey对象，其中包含用于签名的密钥。如果算法可识别出公钥密码系统，则密钥为私钥。
data
ArrayBuffer、TypedArray或DataView对象，其中包含要签名的数据。
返回值
Promise<ArrayBuffer>
使用包含签名的ArrayBuffer来实现的Promise。
抛出
如果算法参数无效，则抛出InvalidArgumentError
抛出
如果算法不受支持，则抛出NotSupportedError
verify()
verify: (
algorithm,key,signature,data) =>Promise<boolean>
SubtleCrypto接口的verify() 方法可验证数字签名。
此方法接受的参数包括用于验证签名的密钥、一些特定于算法的参数、签名和原始签名数据。此方法会返回将使用一个表示签名是否有效的布尔值来实现的Promise。
参数
algorithm
一个字符串或对象，用于定义要使用的算法；对于某些算法选项，还需要定义一些额外的参数。为额外参数提供的值必须与传递给相应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，其中包含用于验证签名的密钥。它既是对称算法的密钥，也是公钥系统的公钥。
signature
ArrayBuffer
ArrayBuffer，其中包含要验证的签名。
data
ArrayBuffer
ArrayBuffer，其中包含要验证签名的数据。
返回值
Promise<boolean>
使用布尔值实现的Promise：如果签名有效，则为true，否则为false。
抛出
如果算法参数无效，则抛出InvalidArgumentError
抛出
如果算法不受支持，则抛出NotSupportedError
Last updated: 2025年10月2日
