Web Crypto API | Node.js v21.7.2 文档

Web Crypto API#

历史记录

版本	更改
v19.0.0	不再是实验性功能，除了 `Ed25519`、`Ed448`、`X25519` 和 `X448` 算法。
v20.0.0、v18.17.0	现在，参数会强制转换为 WebIDL 定义，并按其 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	已移除专有的 `'NODE-X25519'` 和 `'NODE-X448'` 命名曲线，使其不再属于 `'ECDH'` 算法。

稳定性：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/Ed448/X25519/X448 密钥对#

稳定性：1 - 实验性

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 是一个单例，它提供对 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 版本 4 UUID。UUID 使用加密伪随机数生成器生成。

类：`CryptoKey`#

在 v15.0.0 中添加

`cryptoKey.algorithm`#

在 v15.0.0 中添加

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

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

只读。

`cryptoKey.extractable`#

在 v15.0.0 中添加

类型：<boolean>

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

只读。

`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> type 为 'private' 的 <CryptoKey>。

`cryptoKeyPair.publicKey`#

在 v15.0.0 中添加

类型：<CryptoKey> type 为 'public' 的 <CryptoKey>。

类：`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)`#

历史记录

版本	更改
v18.4.0、v16.17.0	添加了 `'X25519'` 和 `'X448'` 算法。
v15.0.0	在 v15.0.0 中添加

algorithm: <AlgorithmIdentifier> | <EcdhKeyDeriveParams> | <HkdfParams> | <Pbkdf2Params>
baseKey: <CryptoKey>
length: <number> | <null>
返回：<Promise> 使用包含纯文本结果的 <ArrayBuffer> 兑现。

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

Node.js 实现要求当 length 为数字时，它必须是 8 的倍数。

当 length 为 null 时，将生成给定算法的最大位数。这适用于 'ECDH'、'X25519' 和 'X448' 算法。

如果成功，返回的 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: <boolean>
keyUsages: <string[]> 请参阅密钥用法。
返回：<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> 兑现。

使用由 algorithm 标识的方法，subtle.digest() 尝试生成 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> 兑现。

使用由 algorithm 指定的方法和参数以及由 key 提供的密钥材料，subtle.encrypt() 尝试对 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: <string> 必须是 'raw'、'pkcs8'、'spki' 或 'jwk' 之一。
key：<CryptoKey>
返回：<Promise> 使用 <ArrayBuffer> | <Object> 兑现。

如果受支持，则将给定的密钥导出为指定格式。

如果 <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> 兑现

使用 algorithm 中提供的算法和参数，subtle.generateKey() 尝试生成新的密钥材料。根据所使用的算法，该算法可以生成单个 <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: <string> 必须是 'raw'、'pkcs8'、'spki' 或 'jwk' 之一。
keyData: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer> | <Object>

算法：<AlgorithmIdentifier> | <RsaHashedImportParams> | <EcKeyImportParams> | <HmacImportParams>

extractable: <boolean>
keyUsages: <string[]> 请参阅密钥用法。
返回：<Promise> 使用 <CryptoKey> 兑现

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> 兑现。

使用 algorithm 给出的方法和参数以及 key 提供的关键材料，subtle.sign() 尝试生成 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: <string> 必须是 'raw'、'pkcs8'、'spki' 或 'jwk' 之一。
wrappedKey: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
unwrappingKey: <CryptoKey>

unwrapAlgo: <AlgorithmIdentifier> | <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>
unwrappedKeyAlgo: <AlgorithmIdentifier> | <RsaHashedImportParams> | <EcKeyImportParams> | <HmacImportParams>

extractable: <boolean>
keyUsages: <string[]> 请参阅密钥用法。
返回：<Promise> 使用 <CryptoKey> 兑现

在密码学中，“包装密钥”是指导出密钥材料并对其进行加密。subtle.unwrapKey() 方法尝试解密已包装的密钥并创建一个 <CryptoKey> 实例。它等效于首先对加密的密钥数据调用 subtle.decrypt()（使用 wrappedKey、unwrapAlgo 和 unwrappingKey 参数作为输入），然后使用 unwrappedKeyAlgo、extractable 和 keyUsages 参数作为输入将结果传递到 subtle.importKey() 方法。如果成功，则返回的 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>
签名: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
data：<ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
返回: <Promise> 使用 <boolean> 兑现

使用 算法 中给出的方法和参数以及 密钥 提供的关键材料，subtle.verify() 尝试验证 签名 是 数据 的有效加密签名。返回的承诺以 true 或 false 解决。

当前支持的算法包括

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

`subtle.wrapKey(格式, 密钥, 包装密钥, 包装算法)`#

在 v15.0.0 中添加

format: <string> 必须是 'raw'、'pkcs8'、'spki' 或 'jwk' 之一。
key：<CryptoKey>
包装密钥: <CryptoKey>
包装算法: <AlgorithmIdentifier> | <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>
返回：<Promise> 使用包含纯文本结果的 <ArrayBuffer> 兑现。

在密码学中，“包装密钥”是指导出然后加密密钥材料。subtle.wrapKey() 方法将密钥材料导出到由 格式 标识的格式，然后使用 包装算法 指定的方法和参数以及 包装密钥 提供的关键材料对其进行加密。它等同于使用 格式 和 密钥 作为参数调用 subtle.exportKey()，然后使用 包装密钥 和 包装算法 作为输入将其结果传递给 subtle.encrypt() 方法。如果成功，返回的承诺将使用包含加密密钥数据的 <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 位作为计数器，并将剩余位作为随机数。

`aesCtrParams.length`#

在 v15.0.0 中添加

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

`aesCtrParams.name`#

在 v15.0.0 中添加

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

类：`AesGcmParams`#

在 v15.0.0 中添加

`aesGcmParams.additionalData`#

在 v15.0.0 中添加

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

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

`aesGcmParams.iv`#

在 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>

盐值显著提高了 HKDF 算法的强度。它应该是随机的或伪随机的，并且应该与摘要函数的输出长度相同（例如，如果使用 'SHA-256' 作为摘要，则盐应该是 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>

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

An experimental implementation of Secure Curves in the Web Cryptography API as of 30 August 2023 ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹ ↩¹⁰ ↩¹¹ ↩¹² ↩¹³ ↩¹⁴ ↩¹⁵ ↩¹⁶ ↩¹⁷ ↩¹⁸ ↩¹⁹ ↩²⁰ ↩²¹ ↩²² ↩²³ ↩²⁴ ↩²⁵ ↩²⁶ ↩²⁷ ↩²⁸ ↩²⁹ ↩³⁰

Web Crypto API#

示例#

生成密钥#

AES 密钥#

ECDSA 密钥对#

Ed25519/Ed448/X25519/X448 密钥对#

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(格式, 密钥, 包装密钥, 包装算法)#

算法参数#

类: 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#

类：`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(格式, 密钥, 包装密钥, 包装算法)`#

类: `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`#

`hmacImportParams.length`#

`hmacImportParams.name`#

类：`HmacKeyGenParams`#

`hmacKeyGenParams.hash`#

`hmacKeyGenParams.length`#

`hmacKeyGenParams.name`#

类：`Pbkdf2Params`#

`pbkdb2Params.hash`#

`pbkdf2Params.iterations`#

`pbkdf2Params.name`#

`pbkdf2Params.salt`#

类：`RsaHashedImportParams`#

`rsaHashedImportParams.hash`#

`rsaHashedImportParams.name`#

类：`RsaHashedKeyGenParams`#

`rsaHashedKeyGenParams.hash`#