Web Crypto API

稳定性：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('我爱纸杯蛋糕');

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

})();

稳定性：1.1 - 积极开发中

Node.js 提供了以下功能的实现，来自 Web 加密 API 中的现代算法 WICG 提案：

算法：

• 'AES-OCB'¹
• 'Argon2d'²
• 'Argon2i'²
• 'Argon2id'²
• 'ChaCha20-Poly1305'
• 'cSHAKE128'
• 'cSHAKE256'
• 'KMAC128'¹
• 'KMAC256'¹
• 'KT128'
• 'KT256'
• 'ML-DSA-44'³
• 'ML-DSA-65'³
• 'ML-DSA-87'³
• 'ML-KEM-512'³
• 'ML-KEM-768'³
• 'ML-KEM-1024'³
• 'MLKEM768-P256'³
• 'MLKEM768-X25519'³
• 'MLKEM1024-P384'³
• 'SHA3-256'
• 'SHA3-384'
• 'SHA3-512'
• 'TurboSHAKE128'
• 'TurboSHAKE256'

密钥格式：

• 'raw-public'
• 'raw-secret'
• 'raw-seed'

方法：

• subtle.decapsulateBits()
• subtle.decapsulateKey()
• subtle.encapsulateBits()
• subtle.encapsulateKey()
• subtle.getPublicKey()
• SubtleCrypto.supports()。

稳定性：1.1 - 积极开发中

Node.js 提供了以下功能的实现，来自 Web 加密 API 中的安全曲线 WICG 提案：

算法：

• 'Ed448'
• 'X448'

SubtleCrypto 类可用于生成对称（秘密）密钥 或非对称密钥对（公钥和私钥）。

const { subtle } = globalThis.crypto;

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

  return key;
}

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 };
}

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']);
}

const { subtle } = globalThis.crypto;

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

  return key;
}

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;
}

SubtleCrypto.supports() 允许在 Web Crypto API 中进行功能检测， 可用于检测给定的操作是否支持给定的算法标识符 （包括其参数）。

此示例使用 Argon2 从密码派生密钥（如果可用）， 否则使用 PBKDF2；然后使用 AES-OCB（如果可用）或 AES-GCM 用它加密和解密一些文本。

const { SubtleCrypto, crypto } = globalThis;

const password = 'correct horse battery staple';
const derivationAlg =
  SubtleCrypto.supports?.('importKey', 'Argon2id') ?
    'Argon2id' :
    'PBKDF2';
const encryptionAlg =
  SubtleCrypto.supports?.('importKey', 'AES-OCB') ?
    'AES-OCB' :
    'AES-GCM';
const passwordKey = await crypto.subtle.importKey(
  derivationAlg === 'Argon2id' ? 'raw-secret' : 'raw',
  new TextEncoder().encode(password),
  derivationAlg,
  false,
  ['deriveKey'],
);
const nonce = crypto.getRandomValues(new Uint8Array(16));
const derivationParams =
  derivationAlg === 'Argon2id' ?
    {
      nonce,
      parallelism: 4,
      memory: 2 ** 21,
      passes: 1,
    } :
    {
      salt: nonce,
      iterations: 100_000,
      hash: 'SHA-256',
    };
const key = await crypto.subtle.deriveKey(
  {
    name: derivationAlg,
    ...derivationParams,
  },
  passwordKey,
  {
    name: encryptionAlg,
    length: 256,
  },
  false,
  ['encrypt', 'decrypt'],
);
const plaintext = 'Hello, world!';
const iv = crypto.getRandomValues(new Uint8Array(12));
const encrypted = await crypto.subtle.encrypt(
  { name: encryptionAlg, iv },
  key,
  new TextEncoder().encode(plaintext),
);
const decrypted = new TextDecoder().decode(await crypto.subtle.decrypt(
  { name: encryptionAlg, iv },
  key,
  encrypted,
));

以下部分详细介绍 Node.js Web Crypto API 实现所支持的算法，以及每种算法所支持的 API：

• subtle.generateKey()、subtle.exportKey() 和 subtle.importKey() 支持 'AES-CBC'、'AES-CTR'、'AES-GCM'、 'AES-KW'、'AES-OCB'、'ChaCha20-Poly1305'⁴、'HMAC'、 'KMAC128'⁴ 和 'KMAC256'⁴。
• subtle.importKey() 支持 'Argon2d'、'Argon2i'、'Argon2id'、 'HKDF' 和 'PBKDF2'。
• subtle.generateKey()、subtle.exportKey()、 subtle.importKey() 和 subtle.getPublicKey() 支持 'ECDH'、 'ECDSA'、'Ed25519'、'Ed448'⁵、 'ML-DSA-44'⁴、'ML-DSA-65'⁴、 'ML-DSA-87'⁴、'ML-KEM-512'⁴、 'ML-KEM-768'⁴、'ML-KEM-1024'⁴、 'MLKEM768-P256'⁴、'MLKEM768-X25519'⁴、 'MLKEM1024-P384'⁴、'RSA-OAEP'、'RSA-PSS'、 'RSASSA-PKCS1-v1_5'、'X25519' 和 'X448'⁵。

• subtle.encrypt() 和 subtle.decrypt() 支持 'AES-CBC'、 'AES-CTR'、'AES-GCM'、'AES-OCB'、 'ChaCha20-Poly1305'⁴ 和 'RSA-OAEP'。
• subtle.sign() 和 subtle.verify() 支持 'ECDSA'、'Ed25519'、 'Ed448'⁵、'HMAC'、'KMAC128'⁴、 'KMAC256'⁴、'ML-DSA-44'⁴、 'ML-DSA-65'⁴、'ML-DSA-87'⁴、'RSA-PSS' 和 'RSASSA-PKCS1-v1_5'。
• subtle.deriveBits() 和 subtle.deriveKey() 支持 'Argon2d'、 'Argon2i'、'Argon2id'、'ECDH'、'HKDF'、'PBKDF2'、'X25519' 和 'X448'⁵。
• subtle.wrapKey() 和 subtle.unwrapKey() 支持 'AES-CBC'、 'AES-CTR'、'AES-GCM'、'AES-KW'、'AES-OCB'、 'ChaCha20-Poly1305'⁴ 和 'RSA-OAEP'。
• subtle.encapsulateBits()、subtle.decapsulateBits()、 subtle.encapsulateKey() 和 subtle.decapsulateKey() 支持 'ML-KEM-512'⁴、'ML-KEM-768'⁴、 'ML-KEM-1024'⁴、'MLKEM768-P256'⁴、 'MLKEM768-X25519'⁴ 和 'MLKEM1024-P384'⁴。
• subtle.digest() 支持 'cSHAKE128'⁴、 'cSHAKE256'⁴、'KT128'⁴、 'KT256'⁴、'SHA-1'、'SHA-256'、'SHA-384'、'SHA-512'、 'SHA3-256'⁴、'SHA3-384'⁴、 'SHA3-512'⁴、'TurboSHAKE128'⁴ 和 'TurboSHAKE256'⁴。

以下列表描述 subtle.importKey() 和 subtle.exportKey() 所支持的格式。

• 'AES-CBC'、'AES-CTR'、'AES-GCM'、'AES-KW' 和 'HMAC' 可以使用 'jwk'、'raw' 和 'raw-secret'⁴ 导入和导出。
• 'AES-OCB'⁴、'ChaCha20-Poly1305'⁴、 'KMAC128'⁴ 和 'KMAC256'⁴ 可以使用 'jwk' 和 'raw-secret'⁴ 导入和导出。
• 'Argon2d'⁴、'Argon2i'⁴ 和 'Argon2id'⁴ 可以使用 'raw-secret'⁴ 导入；不支持导出。
• 'ECDH'、'ECDSA'、'Ed25519'、'Ed448'⁵、'X25519' 和 'X448'⁵ 可以使用 'spki'、 'pkcs8'、'jwk'、'raw' 和 'raw-public'⁴ 导入和导出。
• 'HKDF' 和 'PBKDF2' 可以使用 'raw' 和 'raw-secret'⁴ 导入；不支持导出。
• 'ML-DSA-44'⁴、'ML-DSA-65'⁴、 'ML-DSA-87'⁴、'ML-KEM-512'⁴、 'ML-KEM-768'⁴ 和 'ML-KEM-1024'⁴ 可以使用 'spki'、'pkcs8'、'jwk'、 'raw-public'⁴ 和 'raw-seed'⁴ 导入和导出。
• 'MLKEM768-P256'⁴、 'MLKEM768-X25519'⁴ 和 'MLKEM1024-P384'⁴ 可以使用 'jwk'、'raw-public'⁴ 和 'raw-seed'⁴ 导入和导出。
• 'RSA-OAEP'、'RSA-PSS' 和 'RSASSA-PKCS1-v1_5' 可以使用 'spki'、'pkcs8' 和 'jwk' 导入和导出。

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

• 类型：SubtleCrypto

提供对 SubtleCrypto API 的访问。

crypto.getRandomValues(typedArray): void

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

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

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

crypto.randomUUID(): void

• 返回：string

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

• 类型：KeyAlgorithm | RsaHashedKeyAlgorithm | EcKeyAlgorithm | AesKeyAlgorithm | HmacKeyAlgorithm | KmacKeyAlgorithm

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

只读。

• 类型：boolean

当为 true 时，CryptoKey 可以使用 subtle.exportKey() 或 subtle.wrapKey() 导出。

只读。

• 类型：string 'secret'、'private' 或 'public' 之一。

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

• 类型：string[]

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

可能的用途包括：

• 'encrypt' - 启用密钥与 subtle.encrypt() 一起使用
• 'decrypt' - 启用密钥与 subtle.decrypt() 一起使用
• 'sign' - 启用密钥与 subtle.sign() 一起使用
• 'verify' - 启用密钥与 subtle.verify() 一起使用
• 'deriveKey' - 启用密钥与 subtle.deriveKey() 一起使用
• 'deriveBits' - 启用密钥与 subtle.deriveBits() 一起使用
• 'encapsulateBits' - 启用密钥与 subtle.encapsulateBits() 一起使用
• 'decapsulateBits' - 启用密钥与 subtle.decapsulateBits() 一起使用
• 'encapsulateKey' - 启用密钥与 subtle.encapsulateKey() 一起使用
• 'decapsulateKey' - 启用密钥与 subtle.decapsulateKey() 一起使用
• 'wrapKey' - 启用密钥与 subtle.wrapKey() 一起使用
• 'unwrapKey' - 启用密钥与 subtle.unwrapKey() 一起使用

有效的密钥用途取决于密钥算法（由 cryptokey.algorithm.name 标识）。请参阅 [Crypto 操作 API][]，了解每种密钥算法支持的操作。

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

• 类型：CryptoKey 一个 type 为 'private' 的 CryptoKey。

• 类型：CryptoKey 一个 type 为 'public' 的 CryptoKey。

稳定性：1.1 - 积极开发中

允许在 Web Crypto API 中进行功能检测， 可用于检测给定的算法标识符 （包括其参数）是否支持给定的操作。

参见 [检查运行时算法支持][] 以了解此方法的示例用法。

subtle.decapsulateBits(decapsulationAlgorithm, decapsulationKey, ciphertext): void

稳定性：1.1 - 积极开发中

消息接收者使用他们的非对称私钥解密“封装密钥”（密文），从而恢复一个临时对称密钥（表示为 ArrayBuffer），然后用于解密消息。

目前支持的算法包括：

• 'ML-KEM-512'⁴
• 'ML-KEM-768'⁴
• 'ML-KEM-1024'⁴
• 'MLKEM768-P256'⁴
• 'MLKEM768-X25519'⁴
• 'MLKEM1024-P384'⁴

subtle.decapsulateKey(decapsulationAlgorithm, decapsulationKey, ciphertext, sharedKeyAlgorithm, extractable, keyUsages): void

稳定性：1.1 - 积极开发中

消息接收者使用他们的非对称私钥解密“封装密钥”（密文），从而恢复一个临时对称密钥（表示为 CryptoKey），然后用于解密消息。

目前支持的算法包括：

• 'ML-KEM-512'⁴
• 'ML-KEM-768'⁴
• 'ML-KEM-1024'⁴
• 'MLKEM768-P256'⁴
• 'MLKEM768-X25519'⁴
• 'MLKEM1024-P384'⁴

subtle.decrypt(algorithm, key, data): void

使用 algorithm 中指定的方法和参数以及 key 提供的密钥材料，此方法尝试解密提供的 data。如果成功，返回的 Promise 将解决为一个包含明文结果的 ArrayBuffer。

目前支持的算法包括：

• 'AES-CBC'
• 'AES-CTR'
• 'AES-GCM'
• 'AES-OCB'⁴
• 'ChaCha20-Poly1305'⁴
• 'RSA-OAEP'

subtle.deriveBits(algorithm, baseKey, length?): void

使用 algorithm 中指定的方法和参数以及 baseKey 提供的密钥材料，此方法尝试生成 length 位。

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

如果成功，返回的 Promise 将解决为一个包含生成数据的 ArrayBuffer。

目前支持的算法包括：

• 'Argon2d'⁴
• 'Argon2i'⁴
• 'Argon2id'⁴
• 'ECDH'
• 'HKDF'
• 'PBKDF2'
• 'X25519'
• 'X448'⁵

subtle.deriveKey(algorithm, baseKey, derivedKeyType, extractable, keyUsages): void

使用 algorithm 中指定的方法和参数，以及 baseKey 提供的密钥材料，此方法尝试基于 derivedKeyType 中的方法和参数生成一个新的 CryptoKey。

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

目前支持的算法包括：

• 'Argon2d'⁴
• 'Argon2i'⁴
• 'Argon2id'⁴
• 'ECDH'
• 'HKDF'
• 'PBKDF2'
• 'X25519'
• 'X448'⁵

subtle.digest(algorithm, data): void

使用 algorithm 标识的方法，此方法尝试生成 data 的摘要。如果成功，返回的 Promise 将兑现为一个包含计算摘要的 ArrayBuffer。

如果 algorithm 作为 string 提供，它必须是以下之一：

• 'cSHAKE128'⁴
• 'cSHAKE256'⁴
• 'KT128'⁴
• 'KT256'⁴
• 'SHA-1'
• 'SHA-256'
• 'SHA-384'
• 'SHA-512'
• 'SHA3-256'⁴
• 'SHA3-384'⁴
• 'SHA3-512'⁴
• 'TurboSHAKE128'⁴
• 'TurboSHAKE256'⁴

如果 algorithm 作为 Object 提供，它必须具有一个 name 属性，其值为上述之一。

subtle.encapsulateBits(encapsulationAlgorithm, encapsulationKey): void

稳定性：1.1 - 积极开发中

使用消息接收者的非对称公钥加密临时对称密钥。此加密密钥是表示为 EncapsulatedBits 的“封装密钥”。

目前支持的算法包括：

• 'ML-KEM-512'⁴
• 'ML-KEM-768'⁴
• 'ML-KEM-1024'⁴
• 'MLKEM768-P256'⁴
• 'MLKEM768-X25519'⁴
• 'MLKEM1024-P384'⁴

subtle.encapsulateKey(encapsulationAlgorithm, encapsulationKey, sharedKeyAlgorithm, extractable, keyUsages): void

稳定性：1.1 - 积极开发中

使用消息接收者的非对称公钥加密临时对称密钥。此加密密钥是表示为 EncapsulatedKey 的“封装密钥”。

目前支持的算法包括：

• 'ML-KEM-512'⁴
• 'ML-KEM-768'⁴
• 'ML-KEM-1024'⁴
• 'MLKEM768-P256'⁴
• 'MLKEM768-X25519'⁴
• 'MLKEM1024-P384'⁴

subtle.encrypt(algorithm, key, data): void

使用 algorithm 指定的方法和参数以及 key 提供的密钥材料，此方法尝试加密 data。如果成功，返回的 Promise 将解决为一个包含加密结果的 ArrayBuffer。

目前支持的算法包括：

• 'AES-CBC'
• 'AES-CTR'
• 'AES-GCM'
• 'AES-OCB'⁴
• 'ChaCha20-Poly1305'⁴
• 'RSA-OAEP'

subtle.exportKey(format, key): void

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

如果 CryptoKey 不可导出，返回的 Promise 将被拒绝。

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

当 format 为 'jwk' 且导出成功时，返回的 Promise 将解决为一个符合 [JSON Web 密钥][] 规范的 JavaScript 对象。

请参阅[密钥格式][]，了解每种算法支持的格式。

subtle.getPublicKey(key, keyUsages): void

稳定性：1.1 - 积极开发中

从给定的私钥派生公钥。

subtle.generateKey(algorithm, extractable, keyUsages): void

使用 algorithm 中提供的参数，此方法尝试生成新的密钥材料。根据使用的算法，生成单个 CryptoKey 或 CryptoKeyPair。

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

• 'ECDH'
• 'ECDSA'
• 'Ed25519'
• 'Ed448'⁵
• 'ML-DSA-44'⁴
• 'ML-DSA-65'⁴
• 'ML-DSA-87'⁴
• 'ML-KEM-512'⁴
• 'ML-KEM-768'⁴
• 'ML-KEM-1024'⁴
• 'MLKEM768-P256'⁴
• 'MLKEM768-X25519'⁴
• 'MLKEM1024-P384'⁴
• 'RSA-OAEP'
• 'RSA-PSS'
• 'RSASSA-PKCS1-v1_5'
• 'X25519'
• 'X448'⁵

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

• 'AES-CBC'
• 'AES-CTR'
• 'AES-GCM'
• 'AES-KW'
• 'AES-OCB'⁴
• 'ChaCha20-Poly1305'⁴
• 'HMAC'
• 'KMAC128'⁴
• 'KMAC256'⁴

subtle.importKey(format, keyData, algorithm, extractable, keyUsages): void

此方法尝试将提供的 keyData 解释为给定的 format，以使用提供的 algorithm、extractable 和 keyUsages 参数创建 CryptoKey 实例。如果导入成功，返回的 Promise 将解决为密钥材料的 CryptoKey 表示。

如果导入 KDF 算法密钥，extractable 必须为 false。

请参阅[密钥格式][]，了解当前支持的算法和格式。

subtle.sign(algorithm, key, data): void

使用 algorithm 给出的方法和参数以及 key 提供的密钥材料，此方法尝试生成 data 的密码学签名。如果成功，返回的 Promise 将解决为一个包含生成签名的 ArrayBuffer。

目前支持的算法包括：

• 'ECDSA'
• 'Ed25519'
• 'Ed448'⁵
• 'HMAC'
• 'KMAC128'⁴
• 'KMAC256'⁴
• 'ML-DSA-44'⁴
• 'ML-DSA-65'⁴
• 'ML-DSA-87'⁴
• 'RSA-PSS'
• 'RSASSA-PKCS1-v1_5'

subtle.unwrapKey(format, wrappedKey, unwrappingKey, unwrapAlgorithm, unwrappedKeyAlgorithm, extractable, keyUsages): void

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

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

• 'AES-CBC'
• 'AES-CTR'
• 'AES-GCM'
• 'AES-KW'
• 'AES-OCB'⁴
• 'ChaCha20-Poly1305'⁴
• 'RSA-OAEP'

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

• 'AES-CBC'
• 'AES-CTR'
• 'AES-GCM'
• 'AES-KW'
• 'AES-OCB'⁴
• 'ChaCha20-Poly1305'⁴
• 'ECDH'
• 'ECDSA'
• 'Ed25519'
• 'Ed448'⁵
• 'HMAC'
• 'KMAC128'⁴
• 'KMAC256'⁴
• 'ML-DSA-44'⁴
• 'ML-DSA-65'⁴
• 'ML-DSA-87'⁴
• 'ML-KEM-512'⁴
• 'ML-KEM-768'⁴
• 'ML-KEM-1024'⁴
• 'MLKEM768-P256'⁴
• 'MLKEM768-X25519'⁴
• 'MLKEM1024-P384'⁴
• 'RSA-OAEP'
• 'RSA-PSS'
• 'RSASSA-PKCS1-v1_5'
• 'X25519'
• 'X448'⁵

subtle.verify(algorithm, key, signature, data): void

使用 algorithm 中给出的方法和参数以及 key 提供的密钥材料，此方法尝试验证 signature 是否是 data 的有效密码学签名。返回的 Promise 将解决为 true 或 false。

目前支持的算法包括：

• 'ECDSA'
• 'Ed25519'
• 'Ed448'⁵
• 'HMAC'
• 'KMAC128'⁴
• 'KMAC256'⁴
• 'ML-DSA-44'⁴
• 'ML-DSA-65'⁴
• 'ML-DSA-87'⁴
• 'RSA-PSS'
• 'RSASSA-PKCS1-v1_5'

subtle.wrapKey(format, key, wrappingKey, wrapAlgorithm): void

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

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

• 'AES-CBC'
• 'AES-CTR'
• 'AES-GCM'
• 'AES-KW'
• 'AES-OCB'⁴
• 'ChaCha20-Poly1305'⁴
• 'RSA-OAEP'

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

• 类型：string

• 类型：ArrayBuffer | TypedArray | DataView | Buffer | undefined

额外的输入，不被加密但包含在数据的认证中。additionalData 的使用是可选的。

• 类型：ArrayBuffer | TypedArray | DataView | Buffer

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

• 类型：string 必须是 'AES-GCM'、'AES-OCB' 或 'ChaCha20-Poly1305'。

• 类型：number 生成的认证标签的位数大小。

• 类型：string 必须是 'AES-CBC'、'AES-CTR'、'AES-GCM'、'AES-OCB' 或 'AES-KW' 之一

• 类型：number

要派生的 AES 密钥的长度。必须是 128、192 或 256。

• 类型：ArrayBuffer | TypedArray | DataView | Buffer

提供初始化向量。其长度必须恰好为 16 字节，并且应该是不可预测且密码学随机的。

• 类型：string 必须是 'AES-CBC'。

• 类型：ArrayBuffer | TypedArray | DataView | Buffer

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

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

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

• 类型：string 必须是 'AES-CTR'。

• 类型：number

AES 密钥的长度（位）。

• 类型：string

• 类型：number

要生成的 AES 密钥的长度。必须是 128、192 或 256。

• 类型：string 必须是 'AES-CBC'、'AES-CTR'、'AES-GCM' 或 'AES-KW' 之一

• 类型：ArrayBuffer | TypedArray | DataView | Buffer

表示可选的关联数据。

• 类型：number

表示内存大小（kibibytes）。必须至少是并行度的 8 倍。

• 类型：string 必须是 'Argon2d'、'Argon2i' 或 'Argon2id' 之一。

• 类型：ArrayBuffer | TypedArray | DataView | Buffer

表示 nonce，在密码哈希应用中作为盐。

• 类型：number

表示并行度。

• 类型：number

表示遍数。

• 类型：ArrayBuffer | TypedArray | DataView | Buffer

表示可选的秘密值。

• 类型：number

表示 Argon2 版本号。默认且当前唯一定义的版本是 19 (0x13)。

• 类型：string 必须是 'Ed448'⁵、'ML-DSA-44'⁴、 'ML-DSA-65'⁴、或 'ML-DSA-87'⁴。

• 类型：ArrayBuffer | TypedArray | DataView | Buffer | undefined

context 成员表示要与消息关联的可选上下文数据。

当 functionName 和 customization 均为空或为 undefined 时，cSHAKE 等同于普通 SHAKE。

• 类型：string 必须是 'cSHAKE128'⁴ 或 'cSHAKE256'⁴。

• 类型：number 表示请求的输出长度（位）。必须是 8 的倍数。

• 类型：ArrayBuffer | TypedArray | DataView | Buffer | undefined

functionName 成员表示用于对基于 cSHAKE 构建的函数进行域分离的 NIST 函数名称字节字符串。非空值需要 OpenSSL 4.0 或更高版本。接受的值包括：

• 空值或 undefined
• ASCII 字节序列 'KMAC'
• ASCII 字节序列 'TupleHash'
• ASCII 字节序列 'ParallelHash'

如果你的目标是：

customization 成员表示自定义数据。非空值需要 OpenSSL 4.0 或更高版本。接受的值包括：

• 空值或 undefined
• 最多 512 字节且不包含空字节的数据

• “帮我还原占位符”
• “帮我整理成完整中文文档”
• “帮我说明这段内容讲的是什么”

如果你愿意，我也可以直接根据上下文推断出这些条目对应的 Node.js Crypto API 名称并补全。

• 'SHA-1'
• 'SHA-256'
• 'SHA-384'
• 'SHA-512'
• 'SHA3-256'⁴
• 'SHA3-384'⁴
• 'SHA3-512'⁴

如果表示为 Algorithm，对象的 name 属性必须是上述列出的值之一。

• 类型：number

要为 HMAC 密钥生成的位数。如果省略，长度将由所用的哈希算法确定。 这是可选的，在大多数情况下应省略。

• 类型：string 必须是 'HMAC'。

• 类型：string

• 类型：ArrayBuffer | TypedArray | DataView | Buffer | undefined

KangarooTwelve 的可选自定义字符串。不得超过 512 字节。

• 类型：string 必须是 'KT128'⁴ 或 'KT256'⁴。

• 类型：number 表示请求的输出长度（位）。

• 类型：number

KMAC 密钥中的可选位数。此项为可选，在大多数情况下应省略。密钥长度必须至少为 32 位，且必须是 8 的倍数。

• 类型：string 必须是 'KMAC128' 或 'KMAC256'。

• 类型：number

KMAC 密钥的长度（位）。

• 类型：string

• 类型：number

要为 KMAC 密钥生成的位数。如果省略，长度将由所用的 KMAC 算法确定。 这是可选的，在大多数情况下应省略。必须至少为 32 位，且必须是 8 的倍数。

• 类型：string 必须是 'KMAC128' 或 'KMAC256'。

• 类型：string 必须是 'KMAC128' 或 'KMAC256'。

• 类型：number 表示请求的输出长度（位）。必须是 8 的倍数。

• 类型：ArrayBuffer | TypedArray | DataView | Buffer | undefined

customization 成员表示可选的自定义字符串。

• 类型：string | Algorithm

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

• 'SHA-1'
• 'SHA-256'
• 'SHA-384'
• 'SHA-512'
• 'SHA3-256'⁴
• 'SHA3-384'⁴
• 'SHA3-512'⁴

如果表示为 Algorithm，对象的 name 属性必须是上述列出的值之一。

• 类型：number

PBKDF2 算法在派生位时应进行的迭代次数。

• 类型：string 必须是 'PBKDF2'。

• 类型：ArrayBuffer | TypedArray | DataView | Buffer

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

• 类型：string | Algorithm

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

• 'SHA-1'
• 'SHA-256'
• 'SHA-384'
• 'SHA-512'
• 'SHA3-256'⁴
• 'SHA3-384'⁴
• 'SHA3-512'⁴

如果表示为 Algorithm，对象的 name 属性必须是上述列出的值之一。

• 类型：string 必须是 'RSASSA-PKCS1-v1_5'、'RSA-PSS' 或 'RSA-OAEP' 之一。

• 类型：Algorithm

• 类型：number

RSA 模数的长度（位）。

• 类型：string

• 类型：Uint8Array

RSA 公钥指数。

• 类型：string | Algorithm

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

• 'SHA-1'
• 'SHA-256'
• 'SHA-384'
• 'SHA-512'
• 'SHA3-256'⁴
• 'SHA3-384'⁴
• 'SHA3-512'⁴

如果表示为 Algorithm，对象的 name 属性必须是上述列出的值之一。

• 类型：number

RSA 模数的长度（位）。作为最佳实践，这应至少为 2048。

• 类型：string 必须是 'RSASSA-PKCS1-v1_5'、'RSA-PSS' 或 'RSA-OAEP' 之一。