Node.js v26.0.0 說明文件

Web Crypto API#

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

})();
copy

Web Cryptography API 中的現代演算法#

Node.js 提供來自 Web Cryptography 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'³
• '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()

Web Cryptography API 中的安全曲線#

Node.js 提供來自 Web Cryptography API 中的安全曲線 WICG 提案中下列功能的實作

演算法

• 'Ed448'
• 'X448'

範例#

產生金鑰#

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

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

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

HMAC 金鑰#

const { subtle } = globalThis.crypto;

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

  return key;
}
copy

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

加密與解密#

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

匯出與匯入金鑰#

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

封裝與解封裝金鑰#

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

簽署與驗證#

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

衍生位元與金鑰#

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

摘要#

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

檢查執行階段演算法支援#

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(16));
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,
));
copy

演算法矩陣#

此表格詳細列出 Node.js Web Crypto API 實作支援的演算法以及各個演算法支援的 API

金鑰管理 API#

加密操作 API#

欄位圖例

• 加密 (Encryption)：subtle.encrypt() / subtle.decrypt()
• 簽署與 MAC (Signatures and MAC)：subtle.sign() / subtle.verify()
• 金鑰或位元衍生 (Key or Bits Derivation)：subtle.deriveBits() / subtle.deriveKey()
• 金鑰封裝 (Key Wrapping)：subtle.wrapKey() / subtle.unwrapKey()
• 金鑰封裝機制 (Key Encapsulation)：subtle.encapsulateBits() / subtle.decapsulateBits() / subtle.encapsulateKey() / subtle.decapsulateKey()
• 摘要 (Digest)：subtle.digest()

類別：Crypto#

globalThis.crypto 是 Crypto 類別的一個執行個體。Crypto 是一個單例 (singleton)，提供存取其餘 crypto API 的途徑。

crypto.subtle#

• 類型：<SubtleCrypto>

提供存取 SubtleCrypto API 的途徑。

crypto.getRandomValues(typedArray)#

• typedArray <Buffer> | <TypedArray>
• 回傳：<Buffer> | <TypedArray>

產生加密強度強的隨機值。指定的 typedArray 會填滿隨機值，並回傳對 typedArray 的參考。

指定的 typedArray 必須是整數型的 <TypedArray> 執行個體，亦即 Float32Array 和 Float64Array 不被接受。

如果指定的 typedArray 大於 65,536 位元組，則會拋出錯誤。

crypto.randomUUID()#

• 傳回：<string>

生成隨機 RFC 4122 第 4 版 UUID。此 UUID 是使用加密虛擬隨機數生成器生成的。

類別：CryptoKey#

cryptoKey.algorithm#

• 型別：<KeyAlgorithm> | <RsaHashedKeyAlgorithm> | <EcKeyAlgorithm> | <AesKeyAlgorithm> | <HmacKeyAlgorithm>

一個詳細說明該金鑰可用演算法以及其他演算法特定參數的物件。

唯讀。

cryptoKey.extractable#

• 類型：<boolean>

當為 true 時，可以使用 subtle.exportKey() 或 subtle.wrapKey() 匯出該 <CryptoKey>。

唯讀。

cryptoKey.type#

• 型別：<string> 'secret'、'private' 或 'public' 其中之一。

識別金鑰是對稱金鑰 ('secret') 還是非對稱金鑰 ('private' 或 'public') 的字串。

cryptoKey.usages#

• 類型：<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 識別）。

欄位圖例

• 加密 (Encryption)：subtle.encrypt() / subtle.decrypt()
• 簽署與 MAC (Signatures and MAC)：subtle.sign() / subtle.verify()
• 金鑰或位元衍生 (Key or Bits Derivation)：subtle.deriveBits() / subtle.deriveKey()
• 金鑰封裝 (Key Wrapping)：subtle.wrapKey() / subtle.unwrapKey()
• 金鑰封裝機制 (Key Encapsulation)：subtle.encapsulateBits() / subtle.decapsulateBits() / subtle.encapsulateKey() / subtle.decapsulateKey()

類別：CryptoKeyPair#

CryptoKeyPair 是一個簡單的字典物件，具有 publicKey 和 privateKey 屬性，代表一個非對稱金鑰對。

cryptoKeyPair.privateKey#

• 型別：<CryptoKey> 一個 type 為 'private' 的 <CryptoKey>。

cryptoKeyPair.publicKey#

• 型別：<CryptoKey> 一個 type 為 'public' 的 <CryptoKey>。

類別：SubtleCrypto#

靜態方法：SubtleCrypto.supports(operation, algorithm[, lengthOrAdditionalAlgorithm])#

• operation <string> "encrypt"、"decrypt"、"sign"、"verify"、"digest"、"generateKey"、"deriveKey"、"deriveBits"、"importKey"、"exportKey"、"getPublicKey"、"wrapKey"、"unwrapKey"、"encapsulateBits"、"encapsulateKey"、"decapsulateBits" 或 "decapsulateKey"
• algorithm <string> | <Algorithm>
• lengthOrAdditionalAlgorithm <null> | <number> | <string> | <Algorithm> | <undefined> 根據操作的不同，此參數可能被忽略，或者是：當操作為 "deriveBits" 時的 length 參數值；當操作為 "deriveKey" 時要衍生金鑰的演算法；當操作為 "wrapKey" 時在封裝前要匯出金鑰的演算法；當操作為 "unwrapKey" 時在解封裝後要匯入金鑰的演算法；或當操作為 "encapsulateKey" 或 "decapsulateKey" 時在封裝/解封裝金鑰後要匯入金鑰的演算法。 預設值：當操作為 "deriveBits" 時為 null，其餘情況為 undefined。
• 回傳：<boolean> 表示實作是否支援指定的操作

允許在 Web Crypto API 中進行功能偵測，可用於偵測指定的演算法識別碼（包括其參數）是否支援指定的操作。

此方法的範例用法請參閱檢查執行階段演算法支援。

subtle.decapsulateBits(decapsulationAlgorithm, decapsulationKey, ciphertext)#

• decapsulationAlgorithm <string> | <Algorithm>
• decapsulationKey <CryptoKey>
• ciphertext <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
• 回傳：<Promise> 成功時會履行 (fulfill) 並回傳 <ArrayBuffer>。

訊息接收者使用其非對稱私鑰來解密「封裝金鑰」(ciphertext)，藉此復原暫時性對稱金鑰（表示為 <ArrayBuffer>），該金鑰隨後用於解密訊息。

目前支援的演算法包括：

• 'ML-KEM-512'⁴
• 'ML-KEM-768'⁴
• 'ML-KEM-1024'⁴

subtle.decapsulateKey(decapsulationAlgorithm, decapsulationKey, ciphertext, sharedKeyAlgorithm, extractable, usages)#

• decapsulationAlgorithm <string> | <Algorithm>
• decapsulationKey <CryptoKey>
• ciphertext <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
• sharedKeyAlgorithm <string> | <Algorithm> | <HmacImportParams> | <AesDerivedKeyParams>
• extractable <boolean>
• usages <string[]> 參閱 金鑰用途。
• 回傳：<Promise> 成功時會履行並回傳 <CryptoKey>。

訊息接收者使用其非對稱私鑰來解密「封裝金鑰」(ciphertext)，藉此復原暫時性對稱金鑰（表示為 <CryptoKey>），該金鑰隨後用於解密訊息。

目前支援的演算法包括：

• 'ML-KEM-512'⁴
• 'ML-KEM-768'⁴
• 'ML-KEM-1024'⁴

subtle.decrypt(algorithm, key, data)#

• algorithm <RsaOaepParams> | <AesCtrParams> | <AesCbcParams>
• key <CryptoKey>
• data <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
• 回傳：<Promise> 成功時會履行並回傳 <ArrayBuffer>。

使用 algorithm 中指定的方法和參數以及 key 提供的金鑰材料，此方法會嘗試對指定的 data 進行解密。如果成功，回傳的 promise 將解析為包含明文結果的 <ArrayBuffer>。

目前支援的演算法包括：

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

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

• algorithm <EcdhKeyDeriveParams> | <HkdfParams> | <Pbkdf2Params>
• baseKey <CryptoKey>
• length <number> | <null> 預設值： null
• 回傳：<Promise> 成功時會履行並回傳 <ArrayBuffer>。

使用 algorithm 中指定的方法和參數以及 baseKey 提供的金鑰材料，此方法會嘗試產生 length 位元。

當未提供 length 或為 null 時，會為指定演算法產生最大位元數。這適用於 'ECDH'、'X25519' 和 'X448'⁵ 演算法，其餘演算法則要求 length 必須為數字。

如果成功，回傳的 promise 將解析為包含所產生資料的 <ArrayBuffer>。

目前支援的演算法包括：

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

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

• algorithm <EcdhKeyDeriveParams> | <HkdfParams> | <Pbkdf2Params>
• baseKey <CryptoKey>
• derivedKeyAlgorithm <string> | <Algorithm> | <HmacImportParams> | <AesDerivedKeyParams>
• extractable <boolean>
• keyUsages <string[]> 參閱 金鑰用途。
• 回傳：<Promise> 成功時會履行並回傳 <CryptoKey>。

使用 algorithm 中指定的方法和參數以及 baseKey 提供的金鑰材料，此方法會根據 derivedKeyAlgorithm 中的方法和參數嘗試產生一個新的 <CryptoKey>。

呼叫此方法等同於先呼叫 subtle.deriveBits() 產生原始金鑰材料，然後將結果傳入 subtle.importKey() 方法，並使用 deriveKeyAlgorithm、extractable 和 keyUsages 參數作為輸入。

目前支援的演算法包括：

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

subtle.digest(algorithm, data)#

• algorithm <string> | <Algorithm>
• data <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
• 回傳：<Promise> 成功時會履行並回傳 <ArrayBuffer>。

使用 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)#

• encapsulationAlgorithm <string> | <Algorithm>
• encapsulationKey <CryptoKey>
• 回傳：<Promise> 成功時履行並回傳 {EncapsulatedBits}。

使用訊息接收者的非對稱公鑰來加密暫時性對稱金鑰。此加密金鑰即為表示為 {EncapsulatedBits} 的「封裝金鑰」。

目前支援的演算法包括：

• 'ML-KEM-512'⁴
• 'ML-KEM-768'⁴
• 'ML-KEM-1024'⁴

subtle.encapsulateKey(encapsulationAlgorithm, encapsulationKey, sharedKeyAlgorithm, extractable, usages)#

• encapsulationAlgorithm <string> | <Algorithm>
• encapsulationKey <CryptoKey>
• sharedKeyAlgorithm <string> | <Algorithm> | <HmacImportParams> | <AesDerivedKeyParams>
• extractable <boolean>
• usages <string[]> 參閱 金鑰用途。
• 回傳：<Promise> 成功時履行並回傳 {EncapsulatedKey}。

使用訊息接收者的非對稱公鑰來加密暫時性對稱金鑰。此加密金鑰即為表示為 {EncapsulatedKey} 的「封裝金鑰」。

目前支援的演算法包括：

• 'ML-KEM-512'⁴
• 'ML-KEM-768'⁴
• 'ML-KEM-1024'⁴

subtle.encrypt(algorithm, key, data)#

• algorithm <RsaOaepParams> | <AesCtrParams> | <AesCbcParams>
• key <CryptoKey>
• data <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
• 回傳：<Promise> 成功時會履行並回傳 <ArrayBuffer>。

使用 algorithm 指定的方法和參數以及 key 提供的金鑰材料，此方法會嘗試對 data 進行加密。如果成功，回傳的 promise 會解析為包含加密結果的 <ArrayBuffer>。

目前支援的演算法包括：

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

subtle.exportKey(format, key)#

• format <string> 必須是 'raw'、'pkcs8'、'spki'、'jwk'、'raw-secret'⁴、'raw-public'⁴ 或 'raw-seed'⁴ 其中之一。
• key <CryptoKey>
• 回傳：<Promise> 成功時履行並回傳 <ArrayBuffer> | <Object>。

將指定的金鑰匯出為指定的格式（如果支援）。

如果 <CryptoKey> 無法擷取，回傳的 promise 將會拒絕 (reject)。

當 format 為 'pkcs8' 或 'spki' 且匯出成功時，回傳的 promise 將解析為包含匯出金鑰資料的 <ArrayBuffer>。

當 format 為 'jwk' 且匯出成功時，回傳的 promise 將解析為符合 JSON Web Key 規範的 JavaScript 物件。

subtle.getPublicKey(key, keyUsages)#

• key <CryptoKey> 用於衍生對應公鑰的私鑰。
• keyUsages <string[]> 參閱 金鑰用途。
• 回傳：<Promise> 成功時會履行並回傳 <CryptoKey>。

從指定的私鑰衍生公鑰。

subtle.generateKey(algorithm, extractable, keyUsages)#

• algorithm <string> | <Algorithm> | <RsaHashedKeyGenParams> | <EcKeyGenParams> | <HmacKeyGenParams> | <AesKeyGenParams>

• extractable <boolean>
• keyUsages <string[]> 參閱 金鑰用途。
• 回傳：<Promise> 成功時履行並回傳 <CryptoKey> | <CryptoKeyPair>。

使用 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'⁴
• '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)#

• format <string> 必須是 'raw'、'pkcs8'、'spki'、'jwk'、'raw-secret'⁴、'raw-public'⁴ 或 'raw-seed'⁴ 其中之一。
• keyData <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer> | <Object>

• algorithm <string> | <Algorithm> | <RsaHashedImportParams> | <EcKeyImportParams> | <HmacImportParams>

• extractable <boolean>
• keyUsages <string[]> 參閱 金鑰用途。
• 回傳：<Promise> 成功時會履行並回傳 <CryptoKey>。

此方法嘗試將提供的 keyData 解釋為指定的 format，並使用提供的 algorithm、extractable 和 keyUsages 參數來建立 <CryptoKey> 執行個體。如果匯入成功，回傳的 promise 將解析為該金鑰材料的 <CryptoKey> 表示形式。

匯入 KDF 演算法金鑰時，extractable 必須為 false。

目前支援的演算法包括：

subtle.sign(algorithm, key, data)#

• algorithm <string> | <Algorithm> | <RsaPssParams> | <EcdsaParams>
• key <CryptoKey>
• data <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
• 回傳：<Promise> 成功時會履行並回傳 <ArrayBuffer>。

使用 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, unwrapAlgo, unwrappedKeyAlgo, extractable, keyUsages)#

• format <string> 必須是 'raw'、'pkcs8'、'spki'、'jwk'、'raw-secret'⁴、'raw-public'⁴ 或 'raw-seed'⁴ 其中之一。
• wrappedKey <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
• unwrappingKey <CryptoKey>

• unwrapAlgo <string> | <Algorithm> | <RsaOaepParams> | <AesCtrParams> | <AesCbcParams>
• unwrappedKeyAlgo <string> | <Algorithm> | <RsaHashedImportParams> | <EcKeyImportParams> | <HmacImportParams>

• extractable <boolean>
• keyUsages <string[]> 參閱 金鑰用途。
• 回傳：<Promise> 成功時會履行並回傳 <CryptoKey>。

在密碼學中，「封裝金鑰 (wrapping a key)」是指匯出並加密金鑰材料。此方法嘗試解密一個封裝金鑰並建立 <CryptoKey> 執行個體。這等同於先在加密的金鑰資料上呼叫 subtle.decrypt()（使用 wrappedKey、unwrapAlgo 和 unwrappingKey 作為輸入），然後將結果傳入 subtle.importKey() 方法，並使用 unwrappedKeyAlgo、extractable 和 keyUsages 作為輸入。如果成功，回傳的 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'⁴v
• 'RSA-OAEP'
• 'RSA-PSS'
• 'RSASSA-PKCS1-v1_5'
• 'X25519'
• 'X448'⁵

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

• algorithm <string> | <Algorithm> | <RsaPssParams> | <EcdsaParams>
• key <CryptoKey>
• signature <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
• data <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
• 回傳：<Promise> 成功時履行並回傳 <boolean>。

使用 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, wrapAlgo)#

• format <string> 必須是 'raw'、'pkcs8'、'spki'、'jwk'、'raw-secret'⁴、'raw-public'⁴ 或 'raw-seed'⁴ 其中之一。
• key <CryptoKey>
• wrappingKey <CryptoKey>
• wrapAlgo <string> | <Algorithm> | <RsaOaepParams> | <AesCtrParams> | <AesCbcParams>
• 回傳：<Promise> 成功時會履行並回傳 <ArrayBuffer>。

在密碼學中，「封裝金鑰 (wrapping a key)」是指匯出並加密金鑰材料。此方法會將金鑰材料匯出為由 format 識別的格式，然後使用 wrapAlgo 指定的方法與參數以及 wrappingKey 提供的金鑰材料對其進行加密。這等同於呼叫 subtle.exportKey() 並使用 format 和 key 作為參數，然後將結果傳入 subtle.encrypt() 方法並使用 wrappingKey 和 wrapAlgo 作為輸入。如果成功，回傳的 promise 將解析為一個包含加密金鑰資料的 <ArrayBuffer>。

目前支援的封裝演算法包括：

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

演算法參數#

演算法參數物件定義了各種 <SubtleCrypto> 方法所使用的方法和參數。雖然在此處被描述為「類別」，但它們實際上是簡單的 JavaScript 字典物件。

類別：Algorithm#

Algorithm.name#

• 類型：<string>

類別：AeadParams#

aeadParams.additionalData#

• 型別：<ArrayBuffer> | <TypedArray> | <DataView> | <Buffer> | <undefined>

未加密但包含在資料驗證中的額外輸入。additionalData 是選填的。

aeadParams.iv#

• 型別：<ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

初始向量必須對於使用給定金鑰的每個加密操作都是唯一的。

aeadParams.name#

• 型別：<string> 必須是 'AES-GCM'、'AES-OCB' 或 'ChaCha20-Poly1305'。

aeadParams.tagLength#

• 型別：<number> 產生的驗證標籤的大小（以位元為單位）。

類別：AesDerivedKeyParams#

aesDerivedKeyParams.name#

• 類型：<string> 必須是 'AES-CBC'、'AES-CTR'、'AES-GCM'、'AES-OCB' 或 'AES-KW' 之一

aesDerivedKeyParams.length#

• 類型：<number>

要衍生的 AES 金鑰長度。必須為 128、192 或 256。

類別：AesCbcParams#

aesCbcParams.iv#

• 型別：<ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

提供初始化向量。長度必須正好為 16 位元組，且應為不可預測且具備加密強度的隨機值。

aesCbcParams.name#

• 類型：<string> 必須是 'AES-CBC'。

類別：AesCtrParams#

aesCtrParams.counter#

• 型別：<ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

計數器區塊的初始值。長度必須正好為 16 位元組。

AES-CTR 方法使用區塊最右側的 length 位元作為計數器，其餘位元作為 nonce。

aesCtrParams.length#

• 類型：<number> aesCtrParams.counter 中用作計數器的位元數。

aesCtrParams.name#

• 類型：<string> 必須是 'AES-CTR'。

類別：AesKeyAlgorithm#

aesKeyAlgorithm.length#

• 類型：<number>

AES 金鑰的長度（位元）。

aesKeyAlgorithm.name#

• 類型：<string>

類別：AesKeyGenParams#

aesKeyGenParams.length#

• 類型：<number>

要產生的 AES 金鑰長度。必須為 128、192 或 256。

aesKeyGenParams.name#

• 類型：<string> 必須是 'AES-CBC'、'AES-CTR'、'AES-GCM' 或 'AES-KW' 之一

類別：Argon2Params#

argon2Params.associatedData#

• 型別：<ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

表示選用的關聯數據 (associated data)。

argon2Params.memory#

• 類型：<number>

表示以 kibibytes 為單位的記憶體大小。必須至少為平行度的 8 倍。

argon2Params.name#

• 類型：<string> 必須是 'Argon2d'、'Argon2i' 或 'Argon2id' 之一。

argon2Params.nonce#

• 型別：<ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

表示 nonce，這是用於密碼雜湊應用的鹽值 (salt)。

argon2Params.parallelism#

• 類型：<number>

表示平行度 (degree of parallelism)。

argon2Params.passes#

• 類型：<number>

表示通過次數 (passes)。

argon2Params.secretValue#

• 型別：<ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

表示選用的秘密值。

argon2Params.version#

• 類型：<number>

表示 Argon2 版本號。預設且目前唯一定義的版本為 19 (0x13)。

類別：ContextParams#

contextParams.name#

• 類型：<string> 必須是 Ed448⁵、'ML-DSA-44'⁴、'ML-DSA-65'⁴ 或 'ML-DSA-87'⁴。

contextParams.context#

• 型別：<ArrayBuffer> | <TypedArray> | <DataView> | <Buffer> | <undefined>

context 成員表示要與訊息關聯的選用上下文數據。

類別：CShakeParams#

cShakeParams.name#

• 類型：<string> 必須是 'cSHAKE128'⁴ 或 'cSHAKE256'⁴

cShakeParams.outputLength#

• 類型：<number> 表示要求的輸出位元長度。

cShakeParams.functionName#

• 型別：<ArrayBuffer> | <TypedArray> | <DataView> | <Buffer> | <undefined>

functionName 成員表示函式名稱，NIST 用於定義基於 cSHAKE 的函式。Node.js Web Crypto API 實作僅支援零長度的 functionName，這等同於完全不提供 functionName。

cShakeParams.customization#

• 型別：<ArrayBuffer> | <TypedArray> | <DataView> | <Buffer> | <undefined>

customization 成員表示自訂字串。Node.js Web Crypto API 實作僅支援零長度的 customization，這等同於完全不提供 customization。

類別：EcdhKeyDeriveParams#

ecdhKeyDeriveParams.name#

• 類型：<string> 必須是 'ECDH'、'X25519' 或 'X448'⁵。

ecdhKeyDeriveParams.public#

• 類型：<CryptoKey>

ECDH 金鑰衍生操作是將一方的私鑰與另一方的公鑰作為輸入，兩者共同用於產生一個共享秘密。ecdhKeyDeriveParams.public 屬性設定為另一方的公鑰。

類別：EcdsaParams#

ecdsaParams.hash#

• 類型：<string> | <Algorithm>

如果表示為 <string>，則值必須是下列之一

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

如果表示為 <Algorithm>，則該物件的 name 屬性必須是上述列出的值之一。

ecdsaParams.name#

• 類型：<string> 必須是 'ECDSA'。

類別：EcKeyAlgorithm#

ecKeyAlgorithm.name#

• 類型：<string>

ecKeyAlgorithm.namedCurve#

• 類型：<string>

類別：EcKeyGenParams#

ecKeyGenParams.name#

• 類型：<string> 必須是 'ECDSA' 或 'ECDH' 之一。

ecKeyGenParams.namedCurve#

• 類型：<string> 必須是 'P-256'、'P-384'、'P-521' 之一。

類別：EcKeyImportParams#

ecKeyImportParams.name#

• 類型：<string> 必須是 'ECDSA' 或 'ECDH' 之一。

ecKeyImportParams.namedCurve#

• 類型：<string> 必須是 'P-256'、'P-384'、'P-521' 之一。

類別：EncapsulatedBits#

一個用於訊息加密的暫時對稱秘密金鑰（表示為 <ArrayBuffer>），以及由該共享金鑰加密的密文（可隨訊息一起傳輸給訊息接收者）。接收者使用其私鑰來確定共享金鑰，進而解密訊息。

encapsulatedBits.ciphertext#

• 類型：<ArrayBuffer>

encapsulatedBits.sharedKey#

• 類型：<ArrayBuffer>

類別：EncapsulatedKey#

一個用於訊息加密的暫時對稱秘密金鑰（表示為 <CryptoKey>），以及由該共享金鑰加密的密文（可隨訊息一起傳輸給訊息接收者）。接收者使用其私鑰來確定共享金鑰，進而解密訊息。

encapsulatedKey.ciphertext#

• 類型：<ArrayBuffer>

encapsulatedKey.sharedKey#

• 類型：<CryptoKey>

類別：HkdfParams#

hkdfParams.hash#

• 類型：<string> | <Algorithm>

如果表示為 <string>，則值必須是下列之一

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

如果表示為 <Algorithm>，則該物件的 name 屬性必須是上述列出的值之一。

hkdfParams.info#

• 型別：<ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

為 HKDF 演算法提供特定應用程式的上下文輸入。長度可以為零，但必須提供。

hkdfParams.name#

• 類型：<string> 必須是 'HKDF'。

hkdfParams.salt#

• 型別：<ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

鹽值 (salt) 可顯著提高 HKDF 演算法的強度。它應該是隨機或偽隨機的，且長度應與摘要函式的輸出相同（例如，如果使用 'SHA-256' 作為摘要，鹽值應為 256 位元的隨機數據）。

類別：HmacImportParams#

hmacImportParams.hash#

• 類型：<string> | <Algorithm>

如果表示為 <string>，則值必須是下列之一

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

如果表示為 <Algorithm>，則該物件的 name 屬性必須是上述列出的值之一。

hmacImportParams.length#

• 類型：<number>

HMAC 金鑰中選用的位元數。這是選用的，大多數情況下應省略。

hmacImportParams.name#

• 類型：<string> 必須是 'HMAC'。

類別：HmacKeyAlgorithm#

hmacKeyAlgorithm.hash#

• 類型：<Algorithm>

hmacKeyAlgorithm.length#

• 類型：<number>

HMAC 金鑰的長度（位元）。

hmacKeyAlgorithm.name#

• 類型：<string>

類別：HmacKeyGenParams#

hmacKeyGenParams.hash#

• 類型：<string> | <Algorithm>

如果表示為 <string>，則值必須是下列之一

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

如果表示為 <Algorithm>，則該物件的 name 屬性必須是上述列出的值之一。

hmacKeyGenParams.length#

• 類型：<number>

要產生的 HMAC 金鑰位元數。如果省略，長度將由所使用的雜湊演算法決定。這是選用的，大多數情況下應省略。

hmacKeyGenParams.name#

• 類型：<string> 必須是 'HMAC'。

類別：KeyAlgorithm#

keyAlgorithm.name#

• 類型：<string>

類別：KangarooTwelveParams#

kangarooTwelveParams.customization#

• 型別：<ArrayBuffer> | <TypedArray> | <DataView> | <Buffer> | <undefined>

KangarooTwelve 選用的自訂字串。

kangarooTwelveParams.name#

• 類型：<string> 必須是 'KT128'⁴ 或 'KT256'⁴

kangarooTwelveParams.outputLength#

• 類型：<number> 表示要求的輸出位元長度。

類別：KmacImportParams#

kmacImportParams.length#

• 類型：<number>

KMAC 金鑰中選用的位元數。這是選用的，大多數情況下應省略。

kmacImportParams.name#

• 類型：<string> 必須是 'KMAC128' 或 'KMAC256'。

類別：KmacKeyAlgorithm#

kmacKeyAlgorithm.length#

• 類型：<number>

KMAC 金鑰的長度（位元）。

kmacKeyAlgorithm.name#

• 類型：<string>

類別：KmacKeyGenParams#

kmacKeyGenParams.length#

• 類型：<number>

要產生的 KMAC 金鑰位元數。如果省略，長度將由所使用的 KMAC 演算法決定。這是選用的，大多數情況下應省略。

kmacKeyGenParams.name#

• 類型：<string> 必須是 'KMAC128' 或 'KMAC256'。

類別：KmacParams#

kmacParams.algorithm#

• 類型：<string> 必須是 'KMAC128' 或 'KMAC256'。

kmacParams.outputLength#

• 類型：<number>

輸出長度（位元組）。必須為正整數。

kmacParams.customization#

• 型別：<ArrayBuffer> | <TypedArray> | <DataView> | <Buffer> | <undefined>

customization 成員表示選用的自訂字串。

類別：Pbkdf2Params#

pbkdf2Params.hash#

• 類型：<string> | <Algorithm>

如果表示為 <string>，則值必須是下列之一

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

如果表示為 <Algorithm>，則該物件的 name 屬性必須是上述列出的值之一。

pbkdf2Params.iterations#

• 類型：<number>

PBKDF2 演算法在衍生位元時應執行的疊代次數。

pbkdf2Params.name#

• 類型：<string> 必須是 'PBKDF2'。

pbkdf2Params.salt#

• 型別：<ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

應至少為 16 位元組的隨機或偽隨機值。

類別：RsaHashedImportParams#

rsaHashedImportParams.hash#

• 類型：<string> | <Algorithm>

如果表示為 <string>，則值必須是下列之一

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

如果表示為 <Algorithm>，則該物件的 name 屬性必須是上述列出的值之一。

rsaHashedImportParams.name#

• 類型：<string> 必須是 'RSASSA-PKCS1-v1_5'、'RSA-PSS' 或 'RSA-OAEP' 之一。

類別：RsaHashedKeyAlgorithm#

rsaHashedKeyAlgorithm.hash#

• 類型：<Algorithm>

rsaHashedKeyAlgorithm.modulusLength#

• 類型：<number>

RSA 模數的位元長度。

rsaHashedKeyAlgorithm.name#

• 類型：<string>

rsaHashedKeyAlgorithm.publicExponent#

• 類型：<Uint8Array>

RSA 公鑰指數。

類別：RsaHashedKeyGenParams#

rsaHashedKeyGenParams.hash#

• 類型：<string> | <Algorithm>

如果表示為 <string>，則值必須是下列之一

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

如果表示為 <Algorithm>，則該物件的 name 屬性必須是上述列出的值之一。

rsaHashedKeyGenParams.modulusLength#

• 類型：<number>

RSA 模數的位元長度。根據最佳實踐，此值應至少為 2048。

rsaHashedKeyGenParams.name#

• 類型：<string> 必須是 'RSASSA-PKCS1-v1_5'、'RSA-PSS' 或 'RSA-OAEP' 之一。

rsaHashedKeyGenParams.publicExponent#

• 類型：<Uint8Array>

RSA 公鑰指數。這必須是一個 <Uint8Array>，包含一個必須在 32 位元以內的大端序 (big-endian) 無符號整數。<Uint8Array> 可以包含任意數量的領先零位元。該值必須是質數。除非有理由使用其他值，否則請使用 new Uint8Array([1, 0, 1]) (65537) 作為公鑰指數。

類別：RsaOaepParams#

rsaOaepParams.label#

• 型別：<ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

不會被加密、但會與產生的密文綁定在一起的額外位元組集合。

rsaOaepParams.label 參數是選用的。

rsaOaepParams.name#

• 類型：<string> 必須是 'RSA-OAEP'。

類別：RsaPssParams#

rsaPssParams.name#

• 類型：<string> 必須是 'RSA-PSS'。

rsaPssParams.saltLength#

• 類型：<number>

要使用的隨機鹽值的長度（位元組）。

類別：TurboShakeParams#

turboShakeParams.domainSeparation#

• 類型：<number> | <undefined>

選用的網域分離 (domain separation) 位元組 (0x01-0x7f)。預設為 0x1f。

turboShakeParams.name#

• 類型：<string> 必須是 'TurboSHAKE128'⁴ 或 'TurboSHAKE256'⁴

turboShakeParams.outputLength#

• 類型：<number> 表示要求的輸出位元長度。