Web Crypto API

[历史]

版本	变更
v23.5.0	算法 `Ed25519` 和 `X25519` 现在稳定。
v19.0.0	除 `Ed25519`、`Ed448`、`X25519` 和 `X448` 算法外，不再是实验性的。
v20.0.0, v18.17.0	参数现在根据其 WebIDL 定义进行强制转换和验证，就像在其他 Web Crypto API 实现中一样。
v18.4.0, v16.17.0	删除了专有的 `'node.keyObject'` 导入/导出格式。
v18.4.0, v16.17.0	删除了专有的 `'NODE-DSA'`、`'NODE-DH'` 和 `'NODE-SCRYPT'` 算法。
v18.4.0, v16.17.0	添加了 `'Ed25519'`、`'Ed448'`、`'X25519'` 和 `'X448'` 算法。
v18.4.0, v16.17.0	删除了专有的 `'NODE-ED25519'` 和 `'NODE-ED448'` 算法。
v18.4.0, v16.17.0	从 `'ECDH'` 算法中删除了专有的 `'NODE-X25519'` 和 `'NODE-X448'` 命名曲线。

[稳定: 2 - 稳定]

稳定: 2 稳定性: 2 - 稳定

Node.js 提供了标准 Web Crypto API 的实现。

使用 globalThis.crypto 或 require('node:crypto').webcrypto 来访问此模块。

const { subtle } = globalThis.crypto

;(async function () {
  const key = await subtle.generateKey(
    {
      name: 'HMAC',
      hash: 'SHA-256',
      length: 256,
    },
    true,
    ['sign', 'verify']
  )

  const enc = new TextEncoder()
  const message = enc.encode('I love cupcakes')

  const digest = await subtle.sign(
    {
      name: 'HMAC',
    },
    key,
    message
  )
})()

示例

生成密钥

可以使用<SubtleCrypto> 类生成对称密钥（秘密密钥）或非对称密钥对（公钥和私钥）。

AES 密钥

const { subtle } = globalThis.crypto

async function generateAesKey(length = 256) {
  const key = await subtle.generateKey(
    {
      name: 'AES-CBC',
      length,
    },
    true,
    ['encrypt', 'decrypt']
  )

  return key
}

ECDSA 密钥对

const { subtle } = globalThis.crypto

async function generateEcKey(namedCurve = 'P-521') {
  const { publicKey, privateKey } = await subtle.generateKey(
    {
      name: 'ECDSA',
      namedCurve,
    },
    true,
    ['sign', 'verify']
  )

  return { publicKey, privateKey }
}

Ed25519/X25519 密钥对

const { subtle } = globalThis.crypto

async function generateEd25519Key() {
  return subtle.generateKey(
    {
      name: 'Ed25519',
    },
    true,
    ['sign', 'verify']
  )
}

async function generateX25519Key() {
  return subtle.generateKey(
    {
      name: 'X25519',
    },
    true,
    ['deriveKey']
  )
}

HMAC 密钥

const { subtle } = globalThis.crypto

async function generateHmacKey(hash = 'SHA-256') {
  const key = await subtle.generateKey(
    {
      name: 'HMAC',
      hash,
    },
    true,
    ['sign', 'verify']
  )

  return key
}

RSA 密钥对

const { subtle } = globalThis.crypto
const publicExponent = new Uint8Array([1, 0, 1])

async function generateRsaKey(modulusLength = 2048, hash = 'SHA-256') {
  const { publicKey, privateKey } = await subtle.generateKey(
    {
      name: 'RSASSA-PKCS1-v1_5',
      modulusLength,
      publicExponent,
      hash,
    },
    true,
    ['sign', 'verify']
  )

  return { publicKey, privateKey }
}

加密和解密

const crypto = globalThis.crypto

async function aesEncrypt(plaintext) {
  const ec = new TextEncoder()
  const key = await generateAesKey()
  const iv = crypto.getRandomValues(new Uint8Array(16))

  const ciphertext = await crypto.subtle.encrypt(
    {
      name: 'AES-CBC',
      iv,
    },
    key,
    ec.encode(plaintext)
  )

  return {
    key,
    iv,
    ciphertext,
  }
}

async function aesDecrypt(ciphertext, key, iv) {
  const dec = new TextDecoder()
  const plaintext = await crypto.subtle.decrypt(
    {
      name: 'AES-CBC',
      iv,
    },
    key,
    ciphertext
  )

  return dec.decode(plaintext)
}

导出和导入密钥

const { subtle } = globalThis.crypto

async function generateAndExportHmacKey(format = 'jwk', hash = 'SHA-512') {
  const key = await subtle.generateKey(
    {
      name: 'HMAC',
      hash,
    },
    true,
    ['sign', 'verify']
  )

  return subtle.exportKey(format, key)
}

async function importHmacKey(keyData, format = 'jwk', hash = 'SHA-512') {
  const key = await subtle.importKey(
    format,
    keyData,
    {
      name: 'HMAC',
      hash,
    },
    true,
    ['sign', 'verify']
  )

  return key
}

包装和解包密钥

const { subtle } = globalThis.crypto

async function generateAndWrapHmacKey(format = 'jwk', hash = 'SHA-512') {
  const [key, wrappingKey] = await Promise.all([
    subtle.generateKey(
      {
        name: 'HMAC',
        hash,
      },
      true,
      ['sign', 'verify']
    ),
    subtle.generateKey(
      {
        name: 'AES-KW',
        length: 256,
      },
      true,
      ['wrapKey', 'unwrapKey']
    ),
  ])

  const wrappedKey = await subtle.wrapKey(format, key, wrappingKey, 'AES-KW')

  return { wrappedKey, wrappingKey }
}

async function unwrapHmacKey(wrappedKey, wrappingKey, format = 'jwk', hash = 'SHA-512') {
  const key = await subtle.unwrapKey(format, wrappedKey, wrappingKey, 'AES-KW', { name: 'HMAC', hash }, true, [
    'sign',
    'verify',
  ])

  return key
}

签名和验证

const { subtle } = globalThis.crypto

async function sign(key, data) {
  const ec = new TextEncoder()
  const signature = await subtle.sign('RSASSA-PKCS1-v1_5', key, ec.encode(data))
  return signature
}

async function verify(key, signature, data) {
  const ec = new TextEncoder()
  const verified = await subtle.verify('RSASSA-PKCS1-v1_5', key, signature, ec.encode(data))
  return verified
}

推导比特和密钥

const { subtle } = globalThis.crypto

async function pbkdf2(pass, salt, iterations = 1000, length = 256) {
  const ec = new TextEncoder()
  const key = await subtle.importKey('raw', ec.encode(pass), 'PBKDF2', false, ['deriveBits'])
  const bits = await subtle.deriveBits(
    {
      name: 'PBKDF2',
      hash: 'SHA-512',
      salt: ec.encode(salt),
      iterations,
    },
    key,
    length
  )
  return bits
}

async function pbkdf2Key(pass, salt, iterations = 1000, length = 256) {
  const ec = new TextEncoder()
  const keyMaterial = await subtle.importKey('raw', ec.encode(pass), 'PBKDF2', false, ['deriveKey'])
  const key = await subtle.deriveKey(
    {
      name: 'PBKDF2',
      hash: 'SHA-512',
      salt: ec.encode(salt),
      iterations,
    },
    keyMaterial,
    {
      name: 'AES-GCM',
      length,
    },
    true,
    ['encrypt', 'decrypt']
  )
  return key
}

摘要

const { subtle } = globalThis.crypto

async function digest(data, algorithm = 'SHA-512') {
  const ec = new TextEncoder()
  const digest = await subtle.digest(algorithm, ec.encode(data))
  return digest
}

算法矩阵

下表详细说明了 Node.js Web Crypto API 实现支持的算法以及每个算法支持的 API：

算法	`generateKey`	`exportKey`	`importKey`	`encrypt`	`decrypt`	`wrapKey`	`unwrapKey`	`deriveBits`	`deriveKey`	`sign`	`verify`	`digest`
`'RSASSA-PKCS1-v1_5'`	✔	✔	✔							✔	✔
`'RSA-PSS'`	✔	✔	✔							✔	✔
`'RSA-OAEP'`	✔	✔	✔	✔	✔	✔	✔
`'ECDSA'`	✔	✔	✔							✔	✔
`'Ed25519'`	✔	✔	✔							✔	✔
`'Ed448'`	✔	✔	✔							✔	✔
`'ECDH'`	✔	✔	✔					✔	✔
`'X25519'`	✔	✔	✔					✔	✔
`'X448'`	✔	✔	✔					✔	✔
`'AES-CTR'`	✔	✔	✔	✔	✔	✔	✔
`'AES-CBC'`	✔	✔	✔	✔	✔	✔	✔
`'AES-GCM'`	✔	✔	✔	✔	✔	✔	✔
`'AES-KW'`	✔	✔	✔			✔	✔
`'HMAC'`	✔	✔	✔							✔	✔
`'HKDF'`		✔	✔					✔	✔
`'PBKDF2'`		✔	✔					✔	✔
`'SHA-1'`												✔
`'SHA-256'`												✔
`'SHA-384'`												✔
`'SHA-512'`												✔

类: `Crypto`

新增于: v15.0.0

globalThis.crypto 是 Crypto 类的实例。Crypto 是一个单例对象，提供对其余加密 API 的访问。

`crypto.subtle`

新增于: v15.0.0

类型: <SubtleCrypto>

提供对 SubtleCrypto API 的访问。

`crypto.getRandomValues(typedArray)`

新增于: v15.0.0

typedArray <Buffer> | <TypedArray>
返回值: <Buffer> | <TypedArray>

生成密码学安全的随机值。给定的 typedArray 将填充随机值，并返回对 typedArray 的引用。

给定的 typedArray 必须是 <TypedArray> 的基于整数的实例，即 Float32Array 和 Float64Array 不被接受。

如果给定的 typedArray 大于 65,536 字节，则会抛出错误。

`crypto.randomUUID()`

新增于：v16.7.0

返回值：<string>

生成一个随机的 RFC 4122 version 4 UUID。UUID 使用密码学伪随机数生成器生成。

类：`CryptoKey`

新增于：v15.0.0

`cryptoKey.algorithm`

新增于：v15.0.0

类型：<AesKeyGenParams> | <RsaHashedKeyGenParams> | <EcKeyGenParams> | <HmacKeyGenParams>

一个对象，详细说明了密钥可用于的算法以及其他特定于算法的参数。

只读。

`cryptoKey.extractable`

新增于：v15.0.0

类型：<boolean>

当值为 true 时，<CryptoKey> 可以使用 subtleCrypto.exportKey() 或 subtleCrypto.wrapKey() 导出。

只读。

`cryptoKey.type`

新增于: v15.0.0

类型: <string> 'secret', 'private' 或 'public' 之一。

一个字符串，标识密钥是对称密钥('secret')还是非对称密钥('private' 或 'public')。

`cryptoKey.usages`

新增于: v15.0.0

类型: <string[]>

一个字符串数组，标识密钥可用于的操作。

可能的使用方式包括：

'encrypt' - 密钥可用于加密数据。
'decrypt' - 密钥可用于解密数据。
'sign' - 密钥可用于生成数字签名。
'verify' - 密钥可用于验证数字签名。
'deriveKey' - 密钥可用于导出新密钥。
'deriveBits' - 密钥可用于导出比特位。
'wrapKey' - 密钥可用于包装另一个密钥。
'unwrapKey' - 密钥可用于解包另一个密钥。

有效的密钥使用方式取决于密钥算法（由 cryptokey.algorithm.name 标识）。

密钥类型	`'encrypt'`	`'decrypt'`	`'sign'`	`'verify'`	`'deriveKey'`	`'deriveBits'`	`'wrapKey'`	`'unwrapKey'`
`'AES-CBC'`	✔	✔					✔	✔
`'AES-CTR'`	✔	✔					✔	✔
`'AES-GCM'`	✔	✔					✔	✔
`'AES-KW'`							✔	✔
`'ECDH'`					✔	✔
`'X25519'`					✔	✔
`'X448'`					✔	✔
`'ECDSA'`			✔	✔
`'Ed25519'`			✔	✔
`'Ed448'`			✔	✔
`'HDKF'`					✔	✔
`'HMAC'`			✔	✔
`'PBKDF2'`					✔	✔
`'RSA-OAEP'`	✔	✔					✔	✔
`'RSA-PSS'`			✔	✔
`'RSASSA-PKCS1-v1_5'`			✔	✔

类: `CryptoKeyPair`

新增于: v15.0.0

CryptoKeyPair 是一个简单的字典对象，具有 publicKey 和 privateKey 属性，代表一个非对称密钥对。

`cryptoKeyPair.privateKey`

新增于: v15.0.0

类型: <CryptoKey> 一个 <CryptoKey> ，其 type 将为 'private'。

`cryptoKeyPair.publicKey`

新增于: v15.0.0

类型: <CryptoKey> 一个 <CryptoKey> ，其 type 将为 'public'。

类: `SubtleCrypto`

新增于: v15.0.0

`subtle.decrypt(algorithm, key, data)`

新增于: v15.0.0

algorithm: <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>
key: <CryptoKey>
data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
返回值: <Promise> 以 <ArrayBuffer> 作为结果完成。

使用 algorithm 中指定的方法和参数以及 key 提供的密钥材料，subtle.decrypt() 尝试解密提供的 data。如果成功，则返回的 Promise 将以包含明文结果的 <ArrayBuffer> 完成。

当前支持的算法包括：

'RSA-OAEP'
'AES-CTR'
'AES-CBC'
'AES-GCM'

`subtle.deriveBits(algorithm, baseKey[, length])`

[历史]

版本	变更
v22.5.0, v20.17.0	`'ECDH'`, `'X25519'` 和 `'X448'` 算法的 `length` 参数现在可选。
v18.4.0, v16.17.0	新增 `'X25519'` 和 `'X448'` 算法。
v15.0.0	首次引入: v15.0.0

algorithm: <算法标识符> | <EcdhKeyDeriveParams> | <HkdfParams> | <Pbkdf2Params>
baseKey: <CryptoKey>
length: <数字> | <null> 默认值: null
返回值: <Promise> 成功后返回一个 <ArrayBuffer>

subtle.deriveBits() 使用 algorithm 中指定的方法和参数以及 baseKey 提供的密钥材料尝试生成 length 位数据。

当 length 未提供或为 null 时，将生成给定算法的最大位数。'ECDH', 'X25519' 和 'X448' 算法允许这样做，对于其他算法，length 必须为数字。

如果成功，则返回的 promise 将解析为包含生成数据的 <ArrayBuffer>。

当前支持的算法包括：

'ECDH'
'X25519'
'X448'
'HKDF'
'PBKDF2'

`subtle.deriveKey(algorithm, baseKey, derivedKeyAlgorithm, extractable, keyUsages)`

[历史]

版本	变更
v18.4.0, v16.17.0	新增 `'X25519'` 和 `'X448'` 算法。
v15.0.0	首次引入: v15.0.0

algorithm: <AlgorithmIdentifier> | <EcdhKeyDeriveParams> | <HkdfParams> | <Pbkdf2Params>
baseKey: <CryptoKey>
derivedKeyAlgorithm: <HmacKeyGenParams> | <AesKeyGenParams>
extractable: <布尔值>
keyUsages: <字符串数组> 查看密钥用途。
返回值: <Promise> 返回一个 <CryptoKey>

使用 algorithm 中指定的方法和参数，以及 baseKey 提供的密钥材料，subtle.deriveKey() 尝试根据 derivedKeyAlgorithm 中的方法和参数生成一个新的 <CryptoKey>。

调用 subtle.deriveKey() 等同于调用 subtle.deriveBits() 生成原始密钥材料，然后使用 deriveKeyAlgorithm、extractable 和 keyUsages 参数作为输入，将结果传递给 subtle.importKey() 方法。

当前支持的算法包括：

'ECDH'
'X25519'
'X448'
'HKDF'
'PBKDF2'

`subtle.digest(algorithm, data)`

新增于: v15.0.0

algorithm: <string> | <Object>
data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
返回值: <Promise> 返回一个包含计算结果的 <ArrayBuffer>

subtle.digest() 使用 algorithm 指定的方法尝试生成 data 的摘要。如果成功，则返回的 Promise 会解析为一个包含计算出的摘要的 <ArrayBuffer>。

如果 algorithm 为 <string> 类型，它必须是以下之一：

'SHA-1'
'SHA-256'
'SHA-384'
'SHA-512'

如果 algorithm 为 <Object> 类型，它必须具有一个名为 name 的属性，其值必须是上述值之一。

`subtle.encrypt(algorithm, key, data)`

新增于：v15.0.0

algorithm: <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>
key: <CryptoKey>
data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
返回值: <Promise> 成功后返回一个包含加密结果的 <ArrayBuffer>

subtle.encrypt() 使用 algorithm 指定的方法和参数以及 key 提供的密钥材料来尝试加密 data。如果成功，则返回的 Promise 将以包含加密结果的 <ArrayBuffer> 解析。

当前支持的算法包括：

'RSA-OAEP'
'AES-CTR'
'AES-CBC'
'AES-GCM'

`subtle.exportKey(format, key)`

[历史]

版本	变更
v18.4.0, v16.17.0	新增 `'Ed25519'`, `'Ed448'`, `'X25519'` 和 `'X448'` 算法。
v15.9.0	移除 `'NODE-DSA'` JWK 导出。
v15.0.0	v15.0.0 版本中添加

format: <字符串> 必须是 'raw', 'pkcs8', 'spki' 或 'jwk' 之一。
key: <CryptoKey>
返回值: <Promise> 成功返回 <ArrayBuffer> | <对象>。

导出给定密钥到指定的格式（如果支持）。

如果 <CryptoKey> 不可提取，则返回的 Promise 将被拒绝。

当 format 为 'pkcs8' 或 'spki' 且导出成功时，返回的 Promise 将解析为包含已导出密钥数据的 <ArrayBuffer>。

当 format 为 'jwk' 且导出成功时，返回的 Promise 将解析为符合 JSON Web Key 规范的 JavaScript 对象。

密钥类型	`'spki'`	`'pkcs8'`	`'jwk'`	`'raw'`
`'AES-CBC'`			✔	✔
`'AES-CTR'`			✔	✔
`'AES-GCM'`			✔	✔
`'AES-KW'`			✔	✔
`'ECDH'`	✔	✔	✔	✔
`'ECDSA'`	✔	✔	✔	✔
`'Ed25519'`	✔	✔	✔	✔
`'Ed448'`	✔	✔	✔	✔
`'HDKF'`
`'HMAC'`			✔	✔
`'PBKDF2'`
`'RSA-OAEP'`	✔	✔	✔
`'RSA-PSS'`	✔	✔	✔
`'RSASSA-PKCS1-v1_5'`	✔	✔	✔

`subtle.generateKey(algorithm, extractable, keyUsages)`

新增于: v15.0.0

algorithm: <AlgorithmIdentifier> | <RsaHashedKeyGenParams> | <EcKeyGenParams> | <HmacKeyGenParams> | <AesKeyGenParams>
extractable: <boolean>
keyUsages: <string[]> 查看密钥用途。
返回值: <Promise> 返回一个 <CryptoKey> | <CryptoKeyPair>

subtle.generateKey() 使用 algorithm 中提供的方法和参数尝试生成新的密钥材料。根据使用的方法，该方法可能会生成单个 <CryptoKey> 或 <CryptoKeyPair>。

支持的 <CryptoKeyPair>（公钥和私钥）生成算法包括：

'RSASSA-PKCS1-v1_5'
'RSA-PSS'
'RSA-OAEP'
'ECDSA'
'Ed25519'
'Ed448'
'ECDH'
'X25519'
'X448'

支持的 <CryptoKey>（密钥）生成算法包括：

'HMAC'
'AES-CTR'
'AES-CBC'
'AES-GCM'
'AES-KW'

`subtle.importKey(format, keyData, algorithm, extractable, keyUsages)`

[历史]

版本	变更
v18.4.0, v16.17.0	新增 `'Ed25519'`, `'Ed448'`, `'X25519'` 和 `'X448'` 算法。
v15.9.0	移除 `'NODE-DSA'` JWK 导入。
v15.0.0	v15.0.0 版本新增

format: <字符串> 必须是 'raw', 'pkcs8', 'spki' 或 'jwk' 之一。
keyData: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer> | <对象>
algorithm: <AlgorithmIdentifier> | <RsaHashedImportParams> | <EcKeyImportParams> | <HmacImportParams>
extractable: <布尔值>
keyUsages: <字符串数组> 查看密钥用途。
返回值: <Promise> 返回一个 <CryptoKey> 的 Promise 对象。

subtle.importKey() 方法尝试将提供的 keyData 作为给定的 format 来解释，使用提供的 algorithm、extractable 和 keyUsages 参数创建一个 <CryptoKey> 实例。如果导入成功，则返回的 Promise 将会解析为创建的 <CryptoKey>。

如果导入 'PBKDF2' 密钥，extractable 必须为 false。

当前支持的算法包括：

密钥类型	`'spki'`	`'pkcs8'`	`'jwk'`	`'raw'`
`'AES-CBC'`			✔	✔
`'AES-CTR'`			✔	✔
`'AES-GCM'`			✔	✔
`'AES-KW'`			✔	✔
`'ECDH'`	✔	✔	✔	✔
`'X25519'`	✔	✔	✔	✔
`'X448'`	✔	✔	✔	✔
`'ECDSA'`	✔	✔	✔	✔
`'Ed25519'`	✔	✔	✔	✔
`'Ed448'`	✔	✔	✔	✔
`'HDKF'`				✔
`'HMAC'`			✔	✔
`'PBKDF2'`				✔
`'RSA-OAEP'`	✔	✔	✔
`'RSA-PSS'`	✔	✔	✔
`'RSASSA-PKCS1-v1_5'`	✔	✔	✔

`subtle.sign(algorithm, key, data)`

[历史]

版本	变更
v18.4.0, v16.17.0	新增 `'Ed25519'` 和 `'Ed448'` 算法。
v15.0.0	首次引入: v15.0.0

algorithm: <AlgorithmIdentifier> | <RsaPssParams> | <EcdsaParams> | <Ed448Params>
key: <CryptoKey>
data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
返回值: <Promise> 成功时返回包含生成的签名的 <ArrayBuffer>。

subtle.sign() 使用 algorithm 指定的方法和参数以及 key 提供的密钥材料来尝试生成 data 的加密签名。如果成功，则返回的 Promise 将解析为包含生成的签名的 <ArrayBuffer>。

当前支持的算法包括：

'RSASSA-PKCS1-v1_5'
'RSA-PSS'
'ECDSA'
'Ed25519'
'Ed448'
'HMAC'

`subtle.unwrapKey(format, wrappedKey, unwrappingKey, unwrapAlgo, unwrappedKeyAlgo, extractable, keyUsages)`

新增于：v15.0.0

format: <字符串> 必须是 'raw'、'pkcs8'、'spki' 或 'jwk' 之一。
wrappedKey: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
unwrappingKey: <CryptoKey>
unwrapAlgo: <AlgorithmIdentifier> | <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>
unwrappedKeyAlgo: <AlgorithmIdentifier> | <RsaHashedImportParams> | <EcKeyImportParams> | <HmacImportParams>
extractable: <布尔值>
keyUsages: <字符串数组> 参见密钥用途。
返回值：<Promise> 返回一个 <CryptoKey> 的 Promise。

在密码学中，“密钥包装”是指导出并加密密钥材料。subtle.unwrapKey() 方法尝试解密包装密钥并创建一个 <CryptoKey> 实例。它等效于首先使用 subtle.decrypt() 对加密的密钥数据进行解密（使用 wrappedKey、unwrapAlgo 和 unwrappingKey 参数作为输入），然后使用 subtle.importKey() 方法并将结果传递给它，使用 unwrappedKeyAlgo、extractable 和 keyUsages 参数作为输入。如果成功，则返回的 Promise 将以 <CryptoKey> 对象解析。

当前支持的包装算法包括：

'RSA-OAEP'
'AES-CTR'
'AES-CBC'
'AES-GCM'
'AES-KW'

支持的解包密钥算法包括：

'RSASSA-PKCS1-v1_5'
'RSA-PSS'
'RSA-OAEP'
'ECDSA'
'Ed25519'
'Ed448'
'ECDH'
'X25519'
'X448'
'HMAC'
'AES-CTR'
'AES-CBC'
'AES-GCM'
'AES-KW'

`subtle.verify(algorithm, key, signature, data)`

[历史]

版本	变更
v18.4.0, v16.17.0	新增 `'Ed25519'` 和 `'Ed448'` 算法。
v15.0.0	v15.0.0 版本新增

algorithm: <AlgorithmIdentifier> | <RsaPssParams> | <EcdsaParams> | <Ed448Params>
key: <CryptoKey>
signature: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
返回值: <Promise> 返回一个 <boolean> 值

subtle.verify() 使用 algorithm 中给出的方法和参数以及 key 提供的密钥材料，尝试验证 signature 是否是 data 的有效加密签名。返回的 Promise 将以 true 或 false 解析。

当前支持的算法包括：

'RSASSA-PKCS1-v1_5'
'RSA-PSS'
'ECDSA'
'Ed25519'
'Ed448'
'HMAC'

`subtle.wrapKey(format, key, wrappingKey, wrapAlgo)`

新增于：v15.0.0

format: <string> 必须是 'raw'、'pkcs8'、'spki' 或 'jwk' 之一。
key: <CryptoKey>
wrappingKey: <CryptoKey>
wrapAlgo: <AlgorithmIdentifier> | <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>
返回值: <Promise> 完成时返回 <ArrayBuffer>

在密码学中，“包装密钥”指的是导出密钥材料然后对其进行加密。subtle.wrapKey() 方法将密钥材料导出到 format 指定的格式，然后使用 wrapAlgo 指定的方法和参数以及 wrappingKey 提供的密钥材料对其进行加密。它等效于使用 format 和 key 作为参数调用 subtle.exportKey() 方法，然后使用 wrappingKey 和 wrapAlgo 作为输入将结果传递给 subtle.encrypt() 方法。如果成功，则返回的 Promise 将会以包含加密密钥数据的 <ArrayBuffer> 来完成。

当前支持的密钥包装算法包括：

'RSA-OAEP'
'AES-CTR'
'AES-CBC'
'AES-GCM'
'AES-KW'

算法参数

算法参数对象定义了各种<SubtleCrypto> 方法使用的方法和参数。虽然此处将其描述为“类”，但它们是简单的 JavaScript 字典对象。

类：`AlgorithmIdentifier`

新增于：v18.4.0, v16.17.0

`algorithmIdentifier.name`

新增于：v18.4.0, v16.17.0

类型： <string>

类：`AesCbcParams`

新增于：v15.0.0

`aesCbcParams.iv`

新增于：v15.0.0

类型： <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

提供初始化向量。它必须正好为 16 字节长，并且应该是不可预测的和密码学安全的随机数。

`aesCbcParams.name`

新增于: v15.0.0

类型: <string> 必须为 'AES-CBC'。

类: `AesCtrParams`

新增于: v15.0.0

`aesCtrParams.counter`

新增于: v15.0.0

类型: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

计数器块的初始值。必须正好为 16 字节长。

AES-CTR 方法使用块的最右边的 length 位作为计数器，其余位作为 nonce。

`aesCtrParams.length`

新增于: v15.0.0

类型: <number> 用作计数器的 aesCtrParams.counter 中的位数。

`aesCtrParams.name`

Added in: v15.0.0

类型: <string> 必须为 'AES-CTR'。

类: `AesGcmParams`

Added in: v15.0.0

`aesGcmParams.additionalData`

Added in: v15.0.0

类型: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer> | <undefined>

使用 AES-GCM 方法时，additionalData 是额外的输入，不会被加密，但包含在数据的身份验证中。使用 additionalData 是可选的。

`aesGcmParams.iv`

Added in: v15.0.0

类型: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

初始化向量对于使用给定密钥的每次加密操作必须是唯一的。

理想情况下，这是一个确定的 12 字节值，其计算方式保证在使用相同密钥的所有调用中都是唯一的。或者，初始化向量可以由至少 12 个密码学安全的随机字节组成。有关为 AES-GCM 构造初始化向量的更多信息，请参阅 NIST SP 800-38D 的第 8 节。

`aesGcmParams.name`

新增于: v15.0.0

类型: <string> 必须为 'AES-GCM'。

`aesGcmParams.tagLength`

新增于: v15.0.0

类型: <number> 生成的身份验证标签的位数。此值必须为 32、64、96、104、112、120 或 128 之一。默认值: 128。

类: `AesKeyGenParams`

新增于: v15.0.0

`aesKeyGenParams.length`

新增于: v15.0.0

类型: <number>

要生成的 AES 密钥的长度。此值必须为 128、192 或 256 之一。

`aesKeyGenParams.name`

新增于: v15.0.0

类型: <string> 必须为 'AES-CBC'、'AES-CTR'、'AES-GCM' 或 'AES-KW' 之一

类: `EcdhKeyDeriveParams`

新增于: v15.0.0

`ecdhKeyDeriveParams.name`

新增于: v15.0.0

类型: <string> 必须是 'ECDH', 'X25519', 或 'X448'。

`ecdhKeyDeriveParams.public`

新增于: v15.0.0

类型: <CryptoKey>

ECDH 密钥推导操作通过将一方的私钥和另一方的公钥作为输入，使用两者来生成一个共同的共享密钥。ecdhKeyDeriveParams.public 属性设置为另一方的公钥。

类: `EcdsaParams`

新增于: v15.0.0

`ecdsaParams.hash`

新增于: v15.0.0

类型: <string> | <Object>

如果表示为 <string>，则值必须是以下之一：

'SHA-1'
'SHA-256'
'SHA-384'
'SHA-512'

如果表示为 <Object>，则该对象必须具有一个 name 属性，其值必须是上面列出的值之一。

`ecdsaParams.name`

新增于: v15.0.0

类型: <string> 必须为 'ECDSA'。

类: `EcKeyGenParams`

新增于: v15.0.0

`ecKeyGenParams.name`

新增于: v15.0.0

类型: <string> 必须为 'ECDSA' 或 'ECDH' 之一。

`ecKeyGenParams.namedCurve`

新增于: v15.0.0

类型: <string> 必须为 'P-256', 'P-384', 'P-521' 之一。

类: `EcKeyImportParams`

新增于: v15.0.0

`ecKeyImportParams.name`

新增于: v15.0.0

类型: <string> 必须为 'ECDSA' 或 'ECDH' 之一。

`ecKeyImportParams.namedCurve`

新增于: v15.0.0

类型: <string> 必须为 'P-256', 'P-384', 'P-521' 之一。

类: `Ed448Params`

新增于: v15.0.0

`ed448Params.name`

新增于: v18.4.0, v16.17.0

类型: <string> 必须为 'Ed448'。

`ed448Params.context`

新增于: v18.4.0, v16.17.0

类型: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer> | <undefined>

context 成员表示与消息关联的可选上下文数据。Node.js Web Crypto API 实现仅支持零长度上下文，这等效于根本不提供上下文。

类: `HkdfParams`

新增于: v15.0.0

`hkdfParams.hash`

新增于: v15.0.0

类型: <string> | <Object>

如果表示为 <string>，则其值必须为以下之一：

'SHA-1'
'SHA-256'
'SHA-384'
'SHA-512'

如果表示为 <Object>，则该对象必须具有一个 name 属性，其值必须为上述列出的值之一。

`hkdfParams.info`

新增于: v15.0.0

类型: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

向 HKDF 算法提供特定于应用程序的上下文输入。这可以是零长度，但必须提供。

`hkdfParams.name`

新增于：v15.0.0

类型： <string> 必须为 'HKDF'。

`hkdfParams.salt`

新增于：v15.0.0

类型： <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

salt 值显著提高了 HKDF 算法的强度。它应该为随机或伪随机值，并且长度应与摘要函数的输出长度相同（例如，如果使用 'SHA-256' 作为摘要，则 salt 应为 256 位随机数据）。

类：`HmacImportParams`

新增于：v15.0.0

`hmacImportParams.hash`

新增于：v15.0.0

类型： <string> | <Object>

如果表示为 <string>，则其值必须为以下之一：

'SHA-1'
'SHA-256'
'SHA-384'
'SHA-512'

如果表示为 <Object>，则该对象必须具有一个 name 属性，其值为上述列出的值之一。

`hmacImportParams.length`

新增于：v15.0.0

类型：<number>

HMAC 密钥中比特数的可选值。这是可选的，大多数情况下应该省略。

`hmacImportParams.name`

新增于：v15.0.0

类型：<string> 必须为 'HMAC'。

类：`HmacKeyGenParams`

新增于：v15.0.0

`hmacKeyGenParams.hash`

新增于：v15.0.0

类型：<string> | <Object>

如果表示为 <string>，则其值必须为以下之一：

'SHA-1'
'SHA-256'
'SHA-384'
'SHA-512'

如果表示为 <Object>，则该对象必须具有一个 name 属性，其值为上述列出的值之一。

`hmacKeyGenParams.length`

新增于: v15.0.0

类型: <number>

HMAC 密钥生成的比特数。如果省略，长度将由使用的哈希算法决定。这是可选的，大多数情况下应该省略。

`hmacKeyGenParams.name`

新增于: v15.0.0

类型: <string> 必须为 'HMAC'。

类: `Pbkdf2Params`

新增于: v15.0.0

`pbkdb2Params.hash`

新增于: v15.0.0

类型: <string> | <Object>

如果表示为 <string>，则值必须为以下之一：

'SHA-1'
'SHA-256'
'SHA-384'
'SHA-512'

如果表示为 <Object>，则该对象必须具有一个 name 属性，其值为上述列出的值之一。

`pbkdf2Params.iterations`

新增于：v15.0.0

类型：<number>

PBKDF2 算法在导出比特时应进行的迭代次数。

`pbkdf2Params.name`

新增于：v15.0.0

类型：<string> 必须为 'PBKDF2'。

`pbkdf2Params.salt`

新增于：v15.0.0

类型：<ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

应至少为 16 个随机或伪随机字节。

类：`RsaHashedImportParams`

新增于：v15.0.0

`rsaHashedImportParams.hash`

新增于：v15.0.0

类型：<string> | <Object>

如果表示为 <string>，则其值必须为以下之一：

'SHA-1'
'SHA-256'
'SHA-384'
'SHA-512'

如果表示为 <Object>，则该对象必须具有一个 name 属性，其值必须为上述列出的值之一。

`rsaHashedImportParams.name`

新增于：v15.0.0

类型： <string> 必须是 'RSASSA-PKCS1-v1_5', 'RSA-PSS', 或 'RSA-OAEP' 之一。

类：`RsaHashedKeyGenParams`

新增于：v15.0.0

`rsaHashedKeyGenParams.hash`

新增于：v15.0.0

类型： <string> | <Object>

如果表示为 <string>，则其值必须为以下之一：

'SHA-1'
'SHA-256'
'SHA-384'
'SHA-512'

如果表示为 <Object>，则该对象必须具有一个 name 属性，其值必须为上面列出的值之一。

`rsaHashedKeyGenParams.modulusLength`

新增于：v15.0.0

类型： <number>

RSA 模数的位长。最佳实践是至少为 2048。

`rsaHashedKeyGenParams.name`

新增于：v15.0.0

类型： <string> 必须是 'RSASSA-PKCS1-v1_5', 'RSA-PSS', 或 'RSA-OAEP' 之一。

`rsaHashedKeyGenParams.publicExponent`

新增于：v15.0.0

类型： <Uint8Array>

RSA 公钥指数。这必须是一个 <Uint8Array>，包含一个大端序无符号整数，必须小于 32 位。 <Uint8Array> 可以包含任意数量的前导零位。该值必须是素数。除非有理由使用其他值，否则请使用 new Uint8Array([1, 0, 1]) (65537) 作为公钥指数。

类：`RsaOaepParams`

新增于：v15.0.0

`rsaOaepParams.label`

新增于: v15.0.0

类型: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

一组不会被加密但会绑定到生成的密文的额外字节。

rsaOaepParams.label 参数是可选的。

`rsaOaepParams.name`

新增于: v15.0.0

类型: <string> 必须为 'RSA-OAEP'。

类: `RsaPssParams`

新增于: v15.0.0

`rsaPssParams.name`

新增于: v15.0.0

类型: <string> 必须为 'RSA-PSS'。

`rsaPssParams.saltLength`

新增于: v15.0.0

类型: <number>

要使用的随机盐的长度（以字节为单位）。

##脚注

Web Crypto API ​

示例 ​

生成密钥 ​

AES 密钥 ​

ECDSA 密钥对 ​

Ed25519/X25519 密钥对 ​

HMAC 密钥 ​

RSA 密钥对 ​

加密和解密 ​

导出和导入密钥 ​

包装和解包密钥 ​

签名和验证 ​

推导比特和密钥 ​

摘要 ​

算法矩阵 ​

类: Crypto ​

crypto.subtle ​

crypto.getRandomValues(typedArray) ​

crypto.randomUUID() ​

类：CryptoKey ​

cryptoKey.algorithm ​

cryptoKey.extractable ​

cryptoKey.type ​

cryptoKey.usages ​

类: CryptoKeyPair ​

cryptoKeyPair.privateKey ​

cryptoKeyPair.publicKey ​

类: SubtleCrypto ​

subtle.decrypt(algorithm, key, data) ​

subtle.deriveBits(algorithm, baseKey[, length]) ​

subtle.deriveKey(algorithm, baseKey, derivedKeyAlgorithm, extractable, keyUsages) ​

subtle.digest(algorithm, data) ​

subtle.encrypt(algorithm, key, data) ​

subtle.exportKey(format, key) ​

subtle.generateKey(algorithm, extractable, keyUsages) ​

subtle.importKey(format, keyData, algorithm, extractable, keyUsages) ​

subtle.sign(algorithm, key, data) ​

subtle.unwrapKey(format, wrappedKey, unwrappingKey, unwrapAlgo, unwrappedKeyAlgo, extractable, keyUsages) ​

subtle.verify(algorithm, key, signature, data) ​

subtle.wrapKey(format, key, wrappingKey, wrapAlgo) ​

算法参数 ​

类：AlgorithmIdentifier ​

algorithmIdentifier.name ​

类：AesCbcParams ​

aesCbcParams.iv ​

aesCbcParams.name ​

类: AesCtrParams ​

aesCtrParams.counter ​

aesCtrParams.length ​

aesCtrParams.name ​

类: AesGcmParams ​

aesGcmParams.additionalData ​

aesGcmParams.iv ​

aesGcmParams.name ​

aesGcmParams.tagLength ​

类: AesKeyGenParams ​

aesKeyGenParams.length ​

aesKeyGenParams.name ​

类: EcdhKeyDeriveParams ​

ecdhKeyDeriveParams.name ​

ecdhKeyDeriveParams.public ​

类: EcdsaParams ​

ecdsaParams.hash ​

ecdsaParams.name ​

类: EcKeyGenParams ​

ecKeyGenParams.name ​

ecKeyGenParams.namedCurve ​

类: EcKeyImportParams ​

ecKeyImportParams.name ​

ecKeyImportParams.namedCurve ​

类: Ed448Params ​

ed448Params.name ​

ed448Params.context ​

类: HkdfParams ​

hkdfParams.hash ​

hkdfParams.info ​

hkdfParams.name ​

hkdfParams.salt ​

类：HmacImportParams ​

hmacImportParams.hash ​

Web Crypto API

示例

生成密钥

AES 密钥

ECDSA 密钥对

Ed25519/X25519 密钥对

HMAC 密钥

RSA 密钥对

加密和解密

导出和导入密钥

包装和解包密钥

签名和验证

推导比特和密钥

摘要

算法矩阵

类: `Crypto`

`crypto.subtle`

`crypto.getRandomValues(typedArray)`

`crypto.randomUUID()`

类：`CryptoKey`

`cryptoKey.algorithm`

`cryptoKey.extractable`

`cryptoKey.type`

`cryptoKey.usages`

类: `CryptoKeyPair`

`cryptoKeyPair.privateKey`

`cryptoKeyPair.publicKey`

类: `SubtleCrypto`

`subtle.decrypt(algorithm, key, data)`

`subtle.deriveBits(algorithm, baseKey[, length])`

`subtle.deriveKey(algorithm, baseKey, derivedKeyAlgorithm, extractable, keyUsages)`

`subtle.digest(algorithm, data)`

`subtle.encrypt(algorithm, key, data)`

`subtle.exportKey(format, key)`

`subtle.generateKey(algorithm, extractable, keyUsages)`

`subtle.importKey(format, keyData, algorithm, extractable, keyUsages)`

`subtle.sign(algorithm, key, data)`

`subtle.unwrapKey(format, wrappedKey, unwrappingKey, unwrapAlgo, unwrappedKeyAlgo, extractable, keyUsages)`

`subtle.verify(algorithm, key, signature, data)`

`subtle.wrapKey(format, key, wrappingKey, wrapAlgo)`

算法参数

类：`AlgorithmIdentifier`

`algorithmIdentifier.name`

类：`AesCbcParams`

`aesCbcParams.iv`

`aesCbcParams.name`

类: `AesCtrParams`

`aesCtrParams.counter`

`aesCtrParams.length`

`aesCtrParams.name`

类: `AesGcmParams`

`aesGcmParams.additionalData`

`aesGcmParams.iv`

`aesGcmParams.name`

`aesGcmParams.tagLength`

类: `AesKeyGenParams`

`aesKeyGenParams.length`

`aesKeyGenParams.name`

类: `EcdhKeyDeriveParams`

`ecdhKeyDeriveParams.name`

`ecdhKeyDeriveParams.public`

类: `EcdsaParams`

`ecdsaParams.hash`

`ecdsaParams.name`

类: `EcKeyGenParams`

`ecKeyGenParams.name`

`ecKeyGenParams.namedCurve`

类: `EcKeyImportParams`

`ecKeyImportParams.name`

`ecKeyImportParams.namedCurve`

类: `Ed448Params`

`ed448Params.name`

`ed448Params.context`

类: `HkdfParams`

`hkdfParams.hash`

`hkdfParams.info`

`hkdfParams.name`

`hkdfParams.salt`

类：`HmacImportParams`

`hmacImportParams.hash`