Node.js v25.0.0 文件

靜態方法：Certificate.exportChallenge(spkac[, encoding])#

• spkac <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• encoding <string> spkac 字串的編碼。
• 返回：<Buffer> spkac 資料結構中的 challenge 元件，包含公鑰和質詢。

const { Certificate } = await import('node:crypto');
const spkac = getSpkacSomehow();
const challenge = Certificate.exportChallenge(spkac);
console.log(challenge.toString('utf8'));
// Prints: the challenge as a UTF8 stringconst { Certificate } = require('node:crypto');
const spkac = getSpkacSomehow();
const challenge = Certificate.exportChallenge(spkac);
console.log(challenge.toString('utf8'));
// Prints: the challenge as a UTF8 stringcopy

靜態方法：Certificate.exportPublicKey(spkac[, encoding])#

• spkac <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• encoding <string> spkac 字串的編碼。
• 返回：<Buffer> spkac 資料結構中的公鑰元件，包含公鑰和質詢。

const { Certificate } = await import('node:crypto');
const spkac = getSpkacSomehow();
const publicKey = Certificate.exportPublicKey(spkac);
console.log(publicKey);
// Prints: the public key as <Buffer ...>const { Certificate } = require('node:crypto');
const spkac = getSpkacSomehow();
const publicKey = Certificate.exportPublicKey(spkac);
console.log(publicKey);
// Prints: the public key as <Buffer ...>copy

靜態方法：Certificate.verifySpkac(spkac[, encoding])#

• spkac <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• encoding <string> spkac 字串的編碼。
• 返回：<boolean> 如果給定的 spkac 資料結構有效，則返回 true，否則返回 false。

import { Buffer } from 'node:buffer';
const { Certificate } = await import('node:crypto');

const spkac = getSpkacSomehow();
console.log(Certificate.verifySpkac(Buffer.from(spkac)));
// Prints: true or falseconst { Buffer } = require('node:buffer');
const { Certificate } = require('node:crypto');

const spkac = getSpkacSomehow();
console.log(Certificate.verifySpkac(Buffer.from(spkac)));
// Prints: true or falsecopy

舊版 API#

作為舊版介面，可以建立 crypto.Certificate 類的新例項，如下例所示。

const { Certificate } = await import('node:crypto');

const cert1 = new Certificate();
const cert2 = Certificate();const { Certificate } = require('node:crypto');

const cert1 = new Certificate();
const cert2 = Certificate();copy

const { Certificate } = await import('node:crypto');
const cert = Certificate();
const spkac = getSpkacSomehow();
const challenge = cert.exportChallenge(spkac);
console.log(challenge.toString('utf8'));
// Prints: the challenge as a UTF8 stringconst { Certificate } = require('node:crypto');
const cert = Certificate();
const spkac = getSpkacSomehow();
const challenge = cert.exportChallenge(spkac);
console.log(challenge.toString('utf8'));
// Prints: the challenge as a UTF8 stringcopy

const { Certificate } = await import('node:crypto');
const cert = Certificate();
const spkac = getSpkacSomehow();
const publicKey = cert.exportPublicKey(spkac);
console.log(publicKey);
// Prints: the public key as <Buffer ...>const { Certificate } = require('node:crypto');
const cert = Certificate();
const spkac = getSpkacSomehow();
const publicKey = cert.exportPublicKey(spkac);
console.log(publicKey);
// Prints: the public key as <Buffer ...>copy

import { Buffer } from 'node:buffer';
const { Certificate } = await import('node:crypto');

const cert = Certificate();
const spkac = getSpkacSomehow();
console.log(cert.verifySpkac(Buffer.from(spkac)));
// Prints: true or falseconst { Buffer } = require('node:buffer');
const { Certificate } = require('node:crypto');

const cert = Certificate();
const spkac = getSpkacSomehow();
console.log(cert.verifySpkac(Buffer.from(spkac)));
// Prints: true or falsecopy

cipher.final([outputEncoding])#

• outputEncoding <string> 返回值的編碼。
• 返回：<Buffer> | <string> 任何剩餘的加密內容。如果指定了 outputEncoding，則返回一個字串。如果未提供 outputEncoding，則返回一個 Buffer。

一旦呼叫了 cipher.final() 方法，Cipheriv 物件就不能再用於加密資料。多次嘗試呼叫 cipher.final() 將導致丟擲錯誤。

cipher.getAuthTag()#

• 返回：<Buffer> 當使用認證加密模式（目前支援 GCM、CCM、OCB 和 chacha20-poly1305）時，cipher.getAuthTag() 方法返回一個 Buffer，其中包含從給定資料計算出的*認證標籤*。

cipher.getAuthTag() 方法只應在使用 cipher.final() 方法完成加密後呼叫。

如果在 cipher 例項建立期間設定了 authTagLength 選項，此函式將返回確切的 authTagLength 位元組。

cipher.setAAD(buffer[, options])#

• buffer <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• options <Object> stream.transform 選項
  • plaintextLength <number>
  • encoding <string> 當 buffer 是字串時使用的字串編碼。
• 返回：<Cipheriv> 同一個 Cipheriv 例項，用於方法鏈式呼叫。

當使用認證加密模式（目前支援 GCM、CCM、OCB 和 chacha20-poly1305）時，cipher.setAAD() 方法設定用於*附加認證資料*（AAD）輸入引數的值。

對於 GCM 和 OCB，plaintextLength 選項是可選的。使用 CCM 時，必須指定 plaintextLength 選項，並且其值必須與明文的位元組長度匹配。請參見 CCM 模式。

cipher.setAAD() 方法必須在 cipher.update() 之前呼叫。

cipher.setAutoPadding([autoPadding])#

• autoPadding <boolean> 預設值: true
• 返回：<Cipheriv> 同一個 Cipheriv 例項，用於方法鏈式呼叫。

當使用分組加密演算法時，Cipheriv 類會自動向輸入資料新增填充，使其達到適當的分組大小。要停用預設填充，請呼叫 cipher.setAutoPadding(false)。

當 autoPadding 為 false 時，整個輸入資料的長度必須是密碼分組大小的倍數，否則 cipher.final() 會丟擲錯誤。停用自動填充對於非標準填充很有用，例如使用 0x0 而不是 PKCS 填充。

cipher.setAutoPadding() 方法必須在 cipher.final() 之前呼叫。

cipher.update(data[, inputEncoding][, outputEncoding])#

• data <string> | <Buffer> | <TypedArray> | <DataView>
• inputEncoding <string> 資料的編碼。
• outputEncoding <string> 返回值的編碼。
• 返回：<Buffer> | <string>

用 data 更新密碼器。如果給定了 inputEncoding 引數，則 data 引數是使用指定編碼的字串。如果未給定 inputEncoding 引數，data 必須是 Buffer、TypedArray 或 DataView。如果 data 是 Buffer、TypedArray 或 DataView，則忽略 inputEncoding。

outputEncoding 指定加密資料的輸出格式。如果指定了 outputEncoding，則返回使用指定編碼的字串。如果沒有提供 outputEncoding，則返回一個 Buffer。

cipher.update() 方法可以多次呼叫以處理新資料，直到呼叫 cipher.final() 為止。在呼叫 cipher.final() 之後再呼叫 cipher.update() 將導致丟擲錯誤。

decipher.final([outputEncoding])#

• outputEncoding <string> 返回值的編碼。
• 返回：<Buffer> | <string> 任何剩餘的解密內容。如果指定了 outputEncoding，則返回一個字串。如果沒有提供 outputEncoding，則返回一個 Buffer。

一旦呼叫了 decipher.final() 方法，Decipheriv 物件就不能再用於解密資料。多次嘗試呼叫 decipher.final() 將導致丟擲錯誤。

decipher.setAAD(buffer[, options])#

• buffer <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• options <Object> stream.transform 選項
  • plaintextLength <number>
  • encoding <string> 當 buffer 是字串時使用的字串編碼。
• 返回：<Decipheriv> 同一個 Decipher 例項，用於方法鏈式呼叫。

當使用認證加密模式（目前支援 GCM、CCM、OCB 和 chacha20-poly1305）時，decipher.setAAD() 方法設定用於*附加認證資料*（AAD）輸入引數的值。

對於 GCM，options 引數是可選的。使用 CCM 時，必須指定 plaintextLength 選項，並且其值必須與密文的位元組長度匹配。請參見 CCM 模式。

decipher.setAAD() 方法必須在 decipher.update() 之前呼叫。

當將字串作為 buffer 傳遞時，請考慮將字串用作加密 API 輸入的注意事項。

decipher.setAuthTag(buffer[, encoding])#

• buffer <string> | <Buffer> | <ArrayBuffer> | <TypedArray> | <DataView>
• encoding <string> 當 buffer 是字串時使用的字串編碼。
• 返回：<Decipheriv> 同一個 Decipher 例項，用於方法鏈式呼叫。

當使用認證加密模式（目前支援 GCM、CCM、OCB 和 chacha20-poly1305）時，decipher.setAuthTag() 方法用於傳入接收到的*認證標籤*。如果沒有提供標籤，或者密文被篡改，decipher.final() 將會丟擲異常，表明由於認證失敗，應丟棄該密文。如果標籤長度根據 NIST SP 800-38D 無效，或者與 authTagLength 選項的值不匹配，decipher.setAuthTag() 將丟擲錯誤。

對於 CCM 模式，decipher.setAuthTag() 必須在 decipher.update() 之前呼叫；對於 GCM、OCB 模式和 chacha20-poly1305，則必須在 decipher.final() 之前呼叫。decipher.setAuthTag() 只能呼叫一次。

當將字串作為認證標籤傳遞時，請考慮將字串用作加密 API 輸入的注意事項。

decipher.setAutoPadding([autoPadding])#

• autoPadding <boolean> 預設值: true
• 返回：<Decipheriv> 同一個 Decipher 例項，用於方法鏈式呼叫。

當資料在沒有標準塊填充的情況下被加密時，呼叫 decipher.setAutoPadding(false) 將停用自動填充，以防止 decipher.final() 檢查和移除填充。

關閉自動填充僅在輸入資料的長度是密碼器塊大小的倍數時才有效。

decipher.setAutoPadding() 方法必須在 decipher.final() 之前呼叫。

decipher.update(data[, inputEncoding][, outputEncoding])#

• data <string> | <Buffer> | <TypedArray> | <DataView>
• inputEncoding <string> data 字串的編碼。
• outputEncoding <string> 返回值的編碼。
• 返回：<Buffer> | <string>

用 data 更新解密器。如果給定了 inputEncoding 引數，則 data 引數是使用指定編碼的字串。如果未給定 inputEncoding 引數，data 必須是 Buffer。如果 data 是 Buffer，則忽略 inputEncoding。

outputEncoding 指定加密資料的輸出格式。如果指定了 outputEncoding，則返回使用指定編碼的字串。如果沒有提供 outputEncoding，則返回一個 Buffer。

decipher.update() 方法可以多次呼叫以處理新資料，直到呼叫 decipher.final() 為止。在呼叫 decipher.final() 之後再呼叫 decipher.update() 將導致丟擲錯誤。

即使底層密碼器實現了認證，此函式返回的明文的真實性和完整性此時可能不確定。對於認證加密演算法，真實性通常只有在應用程式呼叫 decipher.final() 時才能確定。

diffieHellman.computeSecret(otherPublicKey[, inputEncoding][, outputEncoding])#

• otherPublicKey <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• inputEncoding <string> otherPublicKey 字串的編碼。
• outputEncoding <string> 返回值的編碼。
• 返回：<Buffer> | <string>

使用 otherPublicKey 作為另一方的公鑰計算共享金鑰，並返回計算出的共享金鑰。提供的金鑰使用指定的 inputEncoding 進行解釋，金鑰使用指定的 outputEncoding 進行編碼。如果未提供 inputEncoding，則 otherPublicKey 應為 Buffer、TypedArray 或 DataView。

如果指定了 outputEncoding，則返回一個字串；否則，返回一個 Buffer。

diffieHellman.generateKeys([encoding])#

• encoding <string> 返回值的編碼。
• 返回：<Buffer> | <string>

生成私有和公共 Diffie-Hellman 金鑰值，除非它們已經被生成或計算過，並以指定的 encoding 返回公鑰。此金鑰應傳輸給另一方。如果提供了 encoding，則返回一個字串；否則返回一個 Buffer。

此函式是 DH_generate_key() 的一個薄封裝。特別地，一旦生成或設定了私鑰，呼叫此函式僅更新公鑰，而不會生成新的私鑰。

diffieHellman.getGenerator([encoding])#

• encoding <string> 返回值的編碼。
• 返回：<Buffer> | <string>

以指定的 encoding 返回 Diffie-Hellman 生成器。如果提供了 encoding，則返回一個字串；否則返回一個 Buffer。

diffieHellman.getPrime([encoding])#

• encoding <string> 返回值的編碼。
• 返回：<Buffer> | <string>

以指定的 encoding 返回 Diffie-Hellman 素數。如果提供了 encoding，則返回一個字串；否則返回一個 Buffer。

diffieHellman.getPrivateKey([encoding])#

• encoding <string> 返回值的編碼。
• 返回：<Buffer> | <string>

以指定的 encoding 返回 Diffie-Hellman 私鑰。如果提供了 encoding，則返回一個字串；否則返回一個 Buffer。

diffieHellman.getPublicKey([encoding])#

• encoding <string> 返回值的編碼。
• 返回：<Buffer> | <string>

以指定的 encoding 返回 Diffie-Hellman 公鑰。如果提供了 encoding，則返回一個字串；否則返回一個 Buffer。

diffieHellman.setPrivateKey(privateKey[, encoding])#

• privateKey <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• encoding <string> privateKey 字串的編碼。

設定 Diffie-Hellman 私鑰。如果提供了 encoding 引數，privateKey 應為一個字串。如果沒有提供 encoding，privateKey 應為一個 Buffer、TypedArray 或 DataView。

此函式不會自動計算相關的公鑰。可以使用 diffieHellman.setPublicKey() 或 diffieHellman.generateKeys() 來手動提供公鑰或自動推導它。

diffieHellman.setPublicKey(publicKey[, encoding])#

• publicKey <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• encoding <string> publicKey 字串的編碼。

設定 Diffie-Hellman 公鑰。如果提供了 encoding 引數，publicKey 應為一個字串。如果沒有提供 encoding，publicKey 應為一個 Buffer、TypedArray 或 DataView。

diffieHellman.verifyError#

一個位欄位，包含在 DiffieHellman 物件初始化期間執行檢查時產生的任何警告和/或錯誤。

以下值對此屬性有效（定義在 node:constants 模組中）：

• DH_CHECK_P_NOT_SAFE_PRIME
• DH_CHECK_P_NOT_PRIME
• DH_UNABLE_TO_CHECK_GENERATOR
• DH_NOT_SUITABLE_GENERATOR

靜態方法：ECDH.convertKey(key, curve[, inputEncoding[, outputEncoding[, format]]])#

• key <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• curve <string>
• inputEncoding <string> key 字串的編碼。
• outputEncoding <string> 返回值的編碼。
• format <string> 預設值: 'uncompressed'
• 返回：<Buffer> | <string>

將由 key 和 curve 指定的 EC Diffie-Hellman 公鑰轉換為由 format 指定的格式。format 引數指定點編碼，可以是 'compressed'、'uncompressed' 或 'hybrid'。提供的金鑰使用指定的 inputEncoding 進行解釋，返回的金鑰使用指定的 outputEncoding 進行編碼。

使用 crypto.getCurves() 獲取可用曲線名稱的列表。在最近的 OpenSSL 版本中，openssl ecparam -list_curves 也會顯示每個可用橢圓曲線的名稱和描述。

如果未指定 format，則點將以 'uncompressed' 格式返回。

如果未提供 inputEncoding，則 key 應為一個 Buffer、TypedArray 或 DataView。

示例（解壓縮一個金鑰）

const {
  createECDH,
  ECDH,
} = await import('node:crypto');

const ecdh = createECDH('secp256k1');
ecdh.generateKeys();

const compressedKey = ecdh.getPublicKey('hex', 'compressed');

const uncompressedKey = ECDH.convertKey(compressedKey,
                                        'secp256k1',
                                        'hex',
                                        'hex',
                                        'uncompressed');

// The converted key and the uncompressed public key should be the same
console.log(uncompressedKey === ecdh.getPublicKey('hex'));const {
  createECDH,
  ECDH,
} = require('node:crypto');

const ecdh = createECDH('secp256k1');
ecdh.generateKeys();

const compressedKey = ecdh.getPublicKey('hex', 'compressed');

const uncompressedKey = ECDH.convertKey(compressedKey,
                                        'secp256k1',
                                        'hex',
                                        'hex',
                                        'uncompressed');

// The converted key and the uncompressed public key should be the same
console.log(uncompressedKey === ecdh.getPublicKey('hex'));copy

ecdh.computeSecret(otherPublicKey[, inputEncoding][, outputEncoding])#

• otherPublicKey <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• inputEncoding <string> otherPublicKey 字串的編碼。
• outputEncoding <string> 返回值的編碼。
• 返回：<Buffer> | <string>

使用 otherPublicKey 作為另一方的公鑰計算共享金鑰，並返回計算出的共享金鑰。提供的金鑰使用指定的 inputEncoding 進行解釋，返回的金鑰使用指定的 outputEncoding 進行編碼。如果未提供 inputEncoding，則 otherPublicKey 應為一個 Buffer、TypedArray 或 DataView。

如果指定了 outputEncoding，將返回一個字串；否則返回一個 Buffer。

當 otherPublicKey 不在橢圓曲線上時，ecdh.computeSecret 會丟擲 ERR_CRYPTO_ECDH_INVALID_PUBLIC_KEY 錯誤。由於 otherPublicKey 通常由遠端使用者透過不安全的網路提供，請務必相應地處理此異常。

ecdh.generateKeys([encoding[, format]])#

• encoding <string> 返回值的編碼。
• format <string> 預設值: 'uncompressed'
• 返回：<Buffer> | <string>

生成私有和公共 EC Diffie-Hellman 金鑰值，並以指定的 format 和 encoding 返回公鑰。此金鑰應傳輸給另一方。

format 引數指定點編碼，可以是 'compressed' 或 'uncompressed'。如果未指定 format，則點將以 'uncompressed' 格式返回。

如果提供了 encoding，則返回一個字串；否則返回一個 Buffer。

ecdh.getPrivateKey([encoding])#

• encoding <string> 返回值的編碼。
• 返回：<Buffer> | <string> 指定 encoding 的 EC Diffie-Hellman 金鑰。

如果指定了 encoding，則返回一個字串；否則返回一個 Buffer。

ecdh.getPublicKey([encoding][, format])#

• encoding <string> 返回值的編碼。
• format <string> 預設值: 'uncompressed'
• 返回：<Buffer> | <string> 指定 encoding 和 format 的 EC Diffie-Hellman 公鑰。

format 引數指定點編碼，可以是 'compressed' 或 'uncompressed'。如果未指定 format，則點將以 'uncompressed' 格式返回。

如果指定了 encoding，則返回一個字串；否則返回一個 Buffer。

ecdh.setPrivateKey(privateKey[, encoding])#

• privateKey <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• encoding <string> privateKey 字串的編碼。

設定 EC Diffie-Hellman 私鑰。如果提供了 encoding，則 privateKey 應為一個字串；否則 privateKey 應為一個 Buffer、TypedArray 或 DataView。

如果 privateKey 對建立 ECDH 物件時指定的曲線無效，則會丟擲錯誤。設定私鑰後，相關的公鑰點（金鑰）也會生成並設定在 ECDH 物件中。

ecdh.setPublicKey(publicKey[, encoding])#

• publicKey <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• encoding <string> publicKey 字串的編碼。

設定 EC Diffie-Hellman 公鑰。如果提供了 encoding，則 publicKey 應為一個字串；否則應為一個 Buffer、TypedArray 或 DataView。

通常沒有理由呼叫此方法，因為 ECDH 只需要一個私鑰和另一方的公鑰來計算共享金鑰。通常會呼叫 ecdh.generateKeys() 或 ecdh.setPrivateKey()。ecdh.setPrivateKey() 方法會嘗試生成與正在設定的私鑰相關的公鑰點/金鑰。

示例（獲取共享金鑰）

const {
  createECDH,
  createHash,
} = await import('node:crypto');

const alice = createECDH('secp256k1');
const bob = createECDH('secp256k1');

// This is a shortcut way of specifying one of Alice's previous private
// keys. It would be unwise to use such a predictable private key in a real
// application.
alice.setPrivateKey(
  createHash('sha256').update('alice', 'utf8').digest(),
);

// Bob uses a newly generated cryptographically strong
// pseudorandom key pair
bob.generateKeys();

const aliceSecret = alice.computeSecret(bob.getPublicKey(), null, 'hex');
const bobSecret = bob.computeSecret(alice.getPublicKey(), null, 'hex');

// aliceSecret and bobSecret should be the same shared secret value
console.log(aliceSecret === bobSecret);const {
  createECDH,
  createHash,
} = require('node:crypto');

const alice = createECDH('secp256k1');
const bob = createECDH('secp256k1');

// This is a shortcut way of specifying one of Alice's previous private
// keys. It would be unwise to use such a predictable private key in a real
// application.
alice.setPrivateKey(
  createHash('sha256').update('alice', 'utf8').digest(),
);

// Bob uses a newly generated cryptographically strong
// pseudorandom key pair
bob.generateKeys();

const aliceSecret = alice.computeSecret(bob.getPublicKey(), null, 'hex');
const bobSecret = bob.computeSecret(alice.getPublicKey(), null, 'hex');

// aliceSecret and bobSecret should be the same shared secret value
console.log(aliceSecret === bobSecret);copy

hash.copy([options])#

• options <Object> stream.transform 選項
• 返回：<Hash>

建立一個新的 Hash 物件，其中包含當前 Hash 物件內部狀態的深複製。

可選的 options 引數控制流的行為。對於 XOF 雜湊函式（如 'shake256'），可以使用 outputLength 選項來指定所需的輸出長度（以位元組為單位）。

當在其 hash.digest() 方法被呼叫後嘗試複製 Hash 物件時，會丟擲一個錯誤。

// Calculate a rolling hash.
const {
  createHash,
} = await import('node:crypto');

const hash = createHash('sha256');

hash.update('one');
console.log(hash.copy().digest('hex'));

hash.update('two');
console.log(hash.copy().digest('hex'));

hash.update('three');
console.log(hash.copy().digest('hex'));

// Etc.// Calculate a rolling hash.
const {
  createHash,
} = require('node:crypto');

const hash = createHash('sha256');

hash.update('one');
console.log(hash.copy().digest('hex'));

hash.update('two');
console.log(hash.copy().digest('hex'));

hash.update('three');
console.log(hash.copy().digest('hex'));

// Etc.copy

hash.digest([encoding])#

• encoding <string> 返回值的編碼。
• 返回：<Buffer> | <string>

計算所有被傳入進行雜湊處理的資料的摘要（使用 hash.update() 方法）。如果提供了 encoding，將返回一個字串；否則返回一個 Buffer。

在 hash.digest() 方法被呼叫後，Hash 物件不能再次使用。多次呼叫會引發錯誤。

hash.update(data[, inputEncoding])#

• data <string> | <Buffer> | <TypedArray> | <DataView>
• inputEncoding <string> data 字串的編碼。

用給定的 data 更新雜湊內容，其編碼在 inputEncoding 中給出。如果未提供 encoding，且 data 是一個字串，則強制使用 'utf8' 編碼。如果 data 是一個 Buffer、TypedArray 或 DataView，則忽略 inputEncoding。

當新資料以流式傳輸時，可以多次呼叫此方法。

hmac.digest([encoding])#

• encoding <string> 返回值的編碼。
• 返回：<Buffer> | <string>

計算使用 hmac.update() 傳入的所有資料的 HMAC 摘要。如果提供了 encoding，則返回一個字串；否則返回一個 Buffer。

在 hmac.digest() 被呼叫後，Hmac 物件不能再次使用。多次呼叫 hmac.digest() 將導致丟擲錯誤。

hmac.update(data[, inputEncoding])#

• data <string> | <Buffer> | <TypedArray> | <DataView>
• inputEncoding <string> data 字串的編碼。

用給定的 data 更新 Hmac 內容，其編碼在 inputEncoding 中給出。如果未提供 encoding，且 data 是一個字串，則強制使用 'utf8' 編碼。如果 data 是一個 Buffer、TypedArray 或 DataView，則忽略 inputEncoding。

當新資料以流式傳輸時，可以多次呼叫此方法。

靜態方法：KeyObject.from(key)#

• key <CryptoKey>
• 返回：<KeyObject>

示例：將 CryptoKey 例項轉換為 KeyObject

const { KeyObject } = await import('node:crypto');
const { subtle } = globalThis.crypto;

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

const keyObject = KeyObject.from(key);
console.log(keyObject.symmetricKeySize);
// Prints: 32 (symmetric key size in bytes)const { KeyObject } = require('node:crypto');
const { subtle } = globalThis.crypto;

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

  const keyObject = KeyObject.from(key);
  console.log(keyObject.symmetricKeySize);
  // Prints: 32 (symmetric key size in bytes)
})();copy

keyObject.asymmetricKeyDetails#

• 型別：<Object>
  • modulusLength <number> 金鑰大小（以位為單位）（RSA, DSA）。
  • publicExponent <bigint> 公共指數（RSA）。
  • hashAlgorithm <string> 訊息摘要的名稱（RSA-PSS）。
  • mgf1HashAlgorithm <string> MGF1 使用的訊息摘要的名稱（RSA-PSS）。
  • saltLength <number> 最小鹽長度（以位元組為單位）（RSA-PSS）。
  • divisorLength <number> q 的大小（以位為單位）（DSA）。
  • namedCurve <string> 曲線名稱（EC）。

此屬性僅存在於非對稱金鑰上。根據金鑰的型別，此物件包含有關金鑰的資訊。透過此屬性獲得的任何資訊都不能用於唯一標識金鑰或危及金鑰的安全性。

對於 RSA-PSS 金鑰，如果金鑰材料包含 RSASSA-PSS-params 序列，則將設定 hashAlgorithm、mgf1HashAlgorithm 和 saltLength 屬性。

其他金鑰詳細資訊可能會透過此 API 使用其他屬性公開。

keyObject.asymmetricKeyType#

• 型別：<string>

對於非對稱金鑰，此屬性表示金鑰的型別。請參見支援的非對稱金鑰型別。

對於無法識別的 KeyObject 型別和對稱金鑰，此屬性為 undefined。

keyObject.equals(otherKeyObject)#

• otherKeyObject <KeyObject> 一個與 keyObject 進行比較的 KeyObject。
• 返回：<boolean>

根據金鑰是否具有完全相同的型別、值和引數，返回 true 或 false。此方法不是時間恆定的。

keyObject.export([options])#

• options <Object>
• 返回：<string> | <Buffer> | <Object>

對於對稱金鑰，可以使用以下編碼選項：

• format <string> 必須是 'buffer' (預設) 或 'jwk'。

對於公鑰，可以使用以下編碼選項：

• type <string> 必須是 'pkcs1' (僅限 RSA) 或 'spki' 之一。
• format <string> 必須是 'pem'、'der' 或 'jwk'。

對於私鑰，可以使用以下編碼選項：

• type <string> 必須是 'pkcs1' (僅限 RSA)、'pkcs8' 或 'sec1' (僅限 EC) 之一。
• format <string> 必須是 'pem'、'der' 或 'jwk'。
• cipher <string> 如果指定，私鑰將使用給定的 cipher 和 passphrase 透過 PKCS#5 v2.0 基於密碼的加密進行加密。
• passphrase <string> | <Buffer> 用於加密的密碼短語，參見 cipher。

結果型別取決於所選的編碼格式，當為 PEM 時，結果為字串；當為 DER 時，它將是一個包含 DER 編碼資料的緩衝區；當為 JWK 時，它將是一個物件。

當選擇 JWK 編碼格式時，所有其他編碼選項都將被忽略。

PKCS#1、SEC1 和 PKCS#8 型別的金鑰可以透過結合使用 cipher 和 format 選項來加密。PKCS#8 type 可以與任何 format 一起使用，透過指定 cipher 來加密任何金鑰演算法（RSA、EC 或 DH）。PKCS#1 和 SEC1 只能在指定 cipher 且使用 PEM format 時進行加密。為了獲得最大的相容性，請使用 PKCS#8 來處理加密的私鑰。由於 PKCS#8 定義了自己的加密機制，因此在加密 PKCS#8 金鑰時不支援 PEM 級別的加密。有關 PKCS#8 加密，請參見 RFC 5208；有關 PKCS#1 和 SEC1 加密，請參見 RFC 1421。

keyObject.symmetricKeySize#

• 型別：<number>

對於金鑰，此屬性表示金鑰的大小（以位元組為單位）。對於非對稱金鑰，此屬性為 undefined。

keyObject.toCryptoKey(algorithm, extractable, keyUsages)#

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

• extractable <boolean>
• keyUsages <string[]> 參見 金鑰用途。
• 返回：<CryptoKey>

將 KeyObject 例項轉換為 CryptoKey。

keyObject.type#

• 型別：<string>

根據此 KeyObject 的型別，此屬性對於金鑰（對稱金鑰）為 'secret'，對於公鑰（非對稱金鑰）為 'public'，或對於私鑰（非對稱金鑰）為 'private'。

sign.sign(privateKey[, outputEncoding])#

• privateKey <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
  • dsaEncoding <string>
  • padding <integer>
  • saltLength <integer>
• outputEncoding <string> 返回值的編碼。
• 返回：<Buffer> | <string>

計算透過 sign.update() 或 sign.write() 傳入的所有資料的簽名。

如果 privateKey 不是一個 KeyObject，此函式的行為就好像 privateKey 已被傳遞給 crypto.createPrivateKey()。如果它是一個物件，可以傳遞以下附加屬性：

• dsaEncoding <string> 對於 DSA 和 ECDSA，此選項指定生成簽名的格式。它可以是以下之一：

  • 'der' (預設): DER 編碼的 ASN.1 簽名結構，編碼為 (r, s)。
  • 'ieee-p1363'：IEEE-P1363 中提議的簽名格式 r || s。

• padding <integer> RSA 的可選填充值，為以下之一：

  • crypto.constants.RSA_PKCS1_PADDING (預設)
  • crypto.constants.RSA_PKCS1_PSS_PADDING

  RSA_PKCS1_PSS_PADDING 將使用 MGF1，其雜湊函式與用於簽署訊息的雜湊函式相同，如 RFC 4055 第 3.1 節所述，除非已根據 RFC 4055 第 3.3 節的規定，在金鑰中指定了 MGF1 雜湊函式。

• saltLength <integer> 當填充為 RSA_PKCS1_PSS_PADDING 時的鹽長度。特殊值 crypto.constants.RSA_PSS_SALTLEN_DIGEST 將鹽長度設定為摘要大小，crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN (預設) 將其設定為最大允許值。

如果提供了 outputEncoding，則返回一個字串；否則返回一個 Buffer。

在 sign.sign() 方法被呼叫後，Sign 物件不能再次使用。多次呼叫 sign.sign() 將導致丟擲錯誤。

sign.update(data[, inputEncoding])#

• data <string> | <Buffer> | <TypedArray> | <DataView>
• inputEncoding <string> data 字串的編碼。

用給定的 data 更新 Sign 內容，其編碼在 inputEncoding 中給出。如果未提供 encoding，且 data 是一個字串，則強制使用 'utf8' 編碼。如果 data 是一個 Buffer、TypedArray 或 DataView，則忽略 inputEncoding。

當新資料以流式傳輸時，可以多次呼叫此方法。

verify.update(data[, inputEncoding])#

• data <string> | <Buffer> | <TypedArray> | <DataView>
• inputEncoding <string> data 字串的編碼。

用給定的 data 更新 Verify 內容，其編碼在 inputEncoding 中給出。如果未提供 inputEncoding，且 data 是一個字串，則強制使用 'utf8' 編碼。如果 data 是一個 Buffer、TypedArray 或 DataView，則忽略 inputEncoding。

當新資料以流式傳輸時，可以多次呼叫此方法。

verify.verify(object, signature[, signatureEncoding])#

• object <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
  • dsaEncoding <string>
  • padding <integer>
  • saltLength <integer>
• signature <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• signatureEncoding <string> signature 字串的編碼。
• 返回：<boolean> 根據資料和公鑰的簽名有效性返回 true 或 false。

使用給定的 object 和 signature 驗證所提供的資料。

如果 object 不是一個 KeyObject，此函式的行為就好像 object 已被傳遞給 crypto.createPublicKey()。如果它是一個物件，可以傳遞以下附加屬性：

• dsaEncoding <string> 對於 DSA 和 ECDSA，此選項指定簽名的格式。它可以是以下之一：

  • 'der' (預設): DER 編碼的 ASN.1 簽名結構，編碼為 (r, s)。
  • 'ieee-p1363'：IEEE-P1363 中提議的簽名格式 r || s。

• padding <integer> RSA 的可選填充值，為以下之一：

  • crypto.constants.RSA_PKCS1_PADDING (預設)
  • crypto.constants.RSA_PKCS1_PSS_PADDING

  RSA_PKCS1_PSS_PADDING 將使用 MGF1，其雜湊函式與用於驗證訊息的雜湊函式相同，如 RFC 4055 第 3.1 節所述，除非已根據 RFC 4055 第 3.3 節的規定，在金鑰中指定了 MGF1 雜湊函式。

• saltLength <integer> 當填充為 RSA_PKCS1_PSS_PADDING 時的鹽長度。特殊值 crypto.constants.RSA_PSS_SALTLEN_DIGEST 將鹽長度設定為摘要大小，crypto.constants.RSA_PSS_SALTLEN_AUTO (預設) 使其自動確定。

signature 引數是先前為資料計算的簽名，其編碼為 signatureEncoding。如果指定了 signatureEncoding，則 signature 應為一個字串；否則 signature 應為一個 Buffer、TypedArray 或 DataView。

在 verify.verify() 被呼叫後，verify 物件不能再次使用。多次呼叫 verify.verify() 將導致丟擲錯誤。

因為公鑰可以從私鑰派生，所以可以傳遞私鑰來代替公鑰。

new X509Certificate(buffer)#

• buffer <string> | <TypedArray> | <Buffer> | <DataView> PEM 或 DER 編碼的 X509 證書。

x509.ca#

• 型別：<boolean> 如果這是證書頒發機構 (CA) 證書，則為 true。

x509.checkEmail(email[, options])#

• email <string>
• options <Object>
  • subject <string> 'default'、'always' 或 'never'。預設值： 'default'。
• 返回：<string> | <undefined> 如果證書匹配，則返回 email，否則返回 undefined。

檢查證書是否與給定的電子郵件地址匹配。

如果 'subject' 選項未定義或設定為 'default'，則僅當主題備用名稱擴充套件不存在或不包含任何電子郵件地址時，才會考慮證書主題。

如果 'subject' 選項設定為 'always'，並且主題備用名稱擴充套件不存在或不包含匹配的電子郵件地址，則會考慮證書主題。

如果 'subject' 選項設定為 'never'，則永遠不會考慮證書主題，即使證書不包含主題備用名稱。

x509.checkHost(name[, options])#

• name <string>
• options <Object>
  • subject <string> 'default'、'always' 或 'never'。預設值： 'default'。
  • wildcards <boolean> 預設值： true。
  • partialWildcards <boolean> 預設值： true。
  • multiLabelWildcards <boolean> 預設值： false。
  • singleLabelSubdomains <boolean> 預設值： false。
• 返回：<string> | <undefined> 返回與 name 匹配的主題名稱，如果沒有主題名稱匹配 name，則返回 undefined。

檢查證書是否與給定的主機名匹配。

如果證書與給定的主機名匹配，則返回匹配的主題名稱。返回的名稱可能是精確匹配（例如 foo.example.com），也可能包含萬用字元（例如 *.example.com）。因為主機名比較不區分大小寫，所以返回的主題名稱的大小寫也可能與給定的 name 不同。

如果 'subject' 選項未定義或設定為 'default'，則僅當主題備用名稱擴充套件不存在或不包含任何 DNS 名稱時，才會考慮證書主題。此行為與 RFC 2818（“HTTP Over TLS”）一致。

如果 'subject' 選項設定為 'always'，並且主題備用名稱擴充套件不存在或不包含匹配的 DNS 名稱，則會考慮證書主題。

如果 'subject' 選項設定為 'never'，則永遠不會考慮證書主題，即使證書不包含主題備用名稱。

x509.checkIP(ip)#

• ip <string>
• 返回：<string> | <undefined> 如果證書匹配，則返回 ip，否則返回 undefined。

檢查證書是否與給定的 IP 地址（IPv4 或 IPv6）匹配。

僅考慮 RFC 5280 iPAddress 主題備用名稱，並且它們必須與給定的 ip 地址完全匹配。證書的其他主題備用名稱以及主題欄位將被忽略。

x509.checkIssued(otherCert)#

• otherCert <X509Certificate>
• 返回：<boolean>

透過比較證書元資料，檢查此證書是否可能由給定的 otherCert 頒發。

這對於修剪可能的頒發者證書列表非常有用，這些證書是使用更基本的過濾例程（即僅基於主題和頒發者名稱）選擇的。

最後，要驗證此證書的簽名是由與 otherCert 的公鑰對應的私鑰生成的，請使用 x509.verify(publicKey)，其中 otherCert 的公鑰表示為一個 KeyObject，如下所示

if (!x509.verify(otherCert.publicKey)) {
  throw new Error('otherCert did not issue x509');
} copy

x509.checkPrivateKey(privateKey)#

• privateKey <KeyObject> 私鑰。
• 返回：<boolean>

檢查此證書的公鑰是否與給定的私鑰一致。

x509.fingerprint#

• 型別：<string>

此證書的 SHA-1 指紋。

由於 SHA-1 在密碼學上已被破解，並且 SHA-1 的安全性明顯低於通常用於簽署證書的演算法，因此請考慮改用 x509.fingerprint256。

x509.fingerprint256#

• 型別：<string>

此證書的 SHA-256 指紋。

x509.fingerprint512#

• 型別：<string>

此證書的 SHA-512 指紋。

由於計算 SHA-256 指紋通常更快，並且其大小僅為 SHA-512 指紋的一半，因此 x509.fingerprint256 可能是更好的選擇。雖然 SHA-512 通常被認為提供了更高的安全級別，但 SHA-256 的安全性與大多數常用於簽署證書的演算法相匹配。

x509.infoAccess#

• 型別：<string>

證書的頒發機構資訊訪問擴充套件的文字表示。

這是一個以換行符分隔的訪問描述列表。每行以訪問方法和訪問位置的型別開頭，後跟一個冒號和與訪問位置關聯的值。

在表示訪問方法和訪問位置型別的字首之後，每行剩餘的部分可能會用引號括起來，以表明該值是一個 JSON 字串字面量。為了向後相容，Node.js 僅在為避免歧義而必要時才在此屬性內使用 JSON 字串字面量。第三方程式碼應準備好處理這兩種可能的條目格式。

x509.issuer#

• 型別：<string>

此證書中包含的頒發者標識。

x509.issuerCertificate#

• 型別：<X509Certificate>

頒發者證書，如果頒發者證書不可用，則為 undefined。

x509.keyUsage#

• 型別：<string[]>

一個詳細說明此證書金鑰擴充套件用途的陣列。

x509.publicKey#

• 型別：<KeyObject>

此證書的公鑰 <KeyObject>。

x509.raw#

• 型別：<Buffer>

一個包含此證書 DER 編碼的 Buffer。

x509.serialNumber#

• 型別：<string>

此證書的序列號。

序列號由證書頒發機構分配，不能唯一標識證書。請考慮改用 x509.fingerprint256 作為唯一識別符號。

x509.subject#

• 型別：<string>

此證書的完整主題。

x509.subjectAltName#

• 型別：<string>

為此證書指定的主題備用名稱。

這是一個以逗號分隔的主題備用名稱列表。每個條目以一個標識主題備用名稱型別的字串開頭，後跟一個冒號和與該條目關聯的值。

早期版本的 Node.js 錯誤地假設在此屬性上按雙字元序列 ', ' 進行分割是安全的（參見 CVE-2021-44532）。然而，無論是惡意證書還是合法證書，在表示為字串時，其主題備用名稱都可能包含此序列。

在表示條目型別的字首之後，每個條目的剩餘部分可能會用引號括起來，以表明該值是一個 JSON 字串字面量。為了向後相容，Node.js 僅在為避免歧義而必要時才在此屬性內使用 JSON 字串字面量。第三方程式碼應準備好處理這兩種可能的條目格式。

x509.toJSON()#

• 型別：<string>

沒有針對 X509 證書的標準 JSON 編碼。toJSON() 方法返回一個包含 PEM 編碼證書的字串。

x509.toLegacyObject()#

• 型別：<Object>

使用舊的 證書物件 編碼返回有關此證書的資訊。

x509.toString()#

• 型別：<string>

返回 PEM 編碼的證書。

x509.validFrom#

• 型別：<string>

此證書的有效起始日期/時間。

x509.validFromDate#

• 型別：<Date>

此證書的有效起始日期/時間，封裝在一個 Date 物件中。

x509.validTo#

• 型別：<string>

此證書的有效截止日期/時間。

x509.validToDate#

• 型別：<Date>

此證書的有效截止日期/時間，封裝在一個 Date 物件中。

x509.signatureAlgorithm#

• 型別：<string> | <undefined>

用於簽署證書的演算法，如果 OpenSSL 不知道該簽名演算法，則為 undefined。

x509.signatureAlgorithmOid#

• 型別：<string>

用於簽署證書的演算法的 OID。

x509.verify(publicKey)#

• publicKey <KeyObject> 公鑰。
• 返回：<boolean>

驗證此證書是否由給定的公鑰簽名。不對證書執行任何其他驗證檢查。

crypto.argon2(algorithm, parameters, callback)#

• algorithm <string> Argon2 的變體，為 "argon2d"、"argon2i" 或 "argon2id" 之一。
• parameters <Object>
  • message <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> 必需，這是 Argon2 密碼雜湊應用的密碼。
  • nonce <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> 必需，必須至少為 8 位元組長。這是 Argon2 密碼雜湊應用的鹽。
  • parallelism <number> 必需，並行度決定了可以執行多少個計算鏈（通道）。必須大於 1 且小於 2**24-1。
  • tagLength <number> 必需，要生成的金鑰長度。必須大於 4 且小於 2**32-1。
  • memory <number> 必需，以 1KiB 塊為單位的記憶體成本。必須大於 8 * parallelism 且小於 2**32-1。實際塊數會向下取整到最接近 4 * parallelism 的倍數。
  • passes <number> 必需，傳遞次數（迭代次數）。必須大於 1 且小於 2**32-1。
  • secret <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <undefined> 可選，隨機的附加輸入，類似於鹽，不應與派生金鑰一起儲存。這在密碼雜湊應用中被稱為“胡椒”（pepper）。如果使用，長度不得超過 2**32-1 位元組。
  • associatedData <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <undefined> 可選，要新增到雜湊中的附加資料，功能上等同於鹽或秘密，但用於非隨機資料。如果使用，長度不得超過 2**32-1 位元組。
• callback <Function>
  • err <Error>
  • derivedKey <Buffer>

提供一個非同步的 Argon2 實現。Argon2 是一種基於密碼的金鑰派生函式，旨在使計算和記憶體成本高昂，從而使暴力攻擊變得不划算。

nonce 應該儘可能唯一。建議 nonce 是隨機的且至少 16 位元組長。詳情請參閱 NIST SP 800-132。

當為 message、nonce、secret 或 associatedData 傳遞字串時，請考慮將字串用作加密 API 輸入時的注意事項。

callback 函式被呼叫時帶有兩個引數：err 和 derivedKey。當金鑰派生失敗時，err 是一個異常物件，否則 err 為 null。derivedKey 作為 Buffer 傳遞給回撥函式。

當任何輸入引數指定了無效的值或型別時，會丟擲異常。

const { argon2, randomBytes } = await import('node:crypto');

const parameters = {
  message: 'password',
  nonce: randomBytes(16),
  parallelism: 4,
  tagLength: 64,
  memory: 65536,
  passes: 3,
};

argon2('argon2id', parameters, (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // 'af91dad...9520f15'
});const { argon2, randomBytes } = require('node:crypto');

const parameters = {
  message: 'password',
  nonce: randomBytes(16),
  parallelism: 4,
  tagLength: 64,
  memory: 65536,
  passes: 3,
};

argon2('argon2id', parameters, (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // 'af91dad...9520f15'
});copy

crypto.argon2Sync(algorithm, parameters)#

• algorithm <string> Argon2 的變體，為 "argon2d"、"argon2i" 或 "argon2id" 之一。
• parameters <Object>
  • message <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> 必需，這是 Argon2 密碼雜湊應用的密碼。
  • nonce <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> 必需，必須至少為 8 位元組長。這是 Argon2 密碼雜湊應用的鹽。
  • parallelism <number> 必需，並行度決定了可以執行多少個計算鏈（通道）。必須大於 1 且小於 2**24-1。
  • tagLength <number> 必需，要生成的金鑰長度。必須大於 4 且小於 2**32-1。
  • memory <number> 必需，以 1KiB 塊為單位的記憶體成本。必須大於 8 * parallelism 且小於 2**32-1。實際塊數會向下取整到最接近 4 * parallelism 的倍數。
  • passes <number> 必需，傳遞次數（迭代次數）。必須大於 1 且小於 2**32-1。
  • secret <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <undefined> 可選，隨機的附加輸入，類似於鹽，不應與派生金鑰一起儲存。這在密碼雜湊應用中被稱為“胡椒”（pepper）。如果使用，長度不得超過 2**32-1 位元組。
  • associatedData <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <undefined> 可選，要新增到雜湊中的附加資料，功能上等同於鹽或秘密，但用於非隨機資料。如果使用，長度不得超過 2**32-1 位元組。
• 返回：<Buffer>

提供一個同步的 Argon2 實現。Argon2 是一種基於密碼的金鑰派生函式，旨在使計算和記憶體成本高昂，從而使暴力攻擊變得不划算。

nonce 應該儘可能唯一。建議 nonce 是隨機的且至少 16 位元組長。詳情請參閱 NIST SP 800-132。

當為 message、nonce、secret 或 associatedData 傳遞字串時，請考慮將字串用作加密 API 輸入時的注意事項。

當金鑰派生失敗時，會丟擲異常，否則派生的金鑰將作為 Buffer 返回。

當任何輸入引數指定了無效的值或型別時，會丟擲異常。

const { argon2Sync, randomBytes } = await import('node:crypto');

const parameters = {
  message: 'password',
  nonce: randomBytes(16),
  parallelism: 4,
  tagLength: 64,
  memory: 65536,
  passes: 3,
};

const derivedKey = argon2Sync('argon2id', parameters);
console.log(derivedKey.toString('hex'));  // 'af91dad...9520f15'const { argon2Sync, randomBytes } = require('node:crypto');

const parameters = {
  message: 'password',
  nonce: randomBytes(16),
  parallelism: 4,
  tagLength: 64,
  memory: 65536,
  passes: 3,
};

const derivedKey = argon2Sync('argon2id', parameters);
console.log(derivedKey.toString('hex'));  // 'af91dad...9520f15'copy

crypto.checkPrime(candidate[, options], callback)#

• candidate <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Buffer> | <DataView> | <bigint> 一個可能的素數，編碼為任意長度的大端位元組序列。
• options <Object>
  • checks <number> 要執行的 Miller-Rabin 機率性素性測試的迭代次數。當值為 0（零）時，將使用一定數量的檢查，使得對於隨機輸入，假陽性率最多為 2^-64。選擇檢查次數時必須謹慎。有關更多詳細資訊，請參閱 OpenSSL 文件中關於 BN_is_prime_ex 函式的 nchecks 選項。預設值： 0
• callback <Function>
  • err <Error> 如果在檢查期間發生錯誤，則設定為一個 <Error> 物件。
  • result <boolean> 如果候選數是素數且錯誤機率小於 0.25 ** options.checks，則為 true。

檢查 candidate 的素性。

crypto.checkPrimeSync(candidate[, options])#

• candidate <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Buffer> | <DataView> | <bigint> 一個可能的素數，編碼為任意長度的大端位元組序列。
• options <Object>
  • checks <number> 要執行的 Miller-Rabin 機率性素性測試的迭代次數。當值為 0（零）時，將使用一定數量的檢查，使得對於隨機輸入，假陽性率最多為 2^-64。選擇檢查次數時必須謹慎。有關更多詳細資訊，請參閱 OpenSSL 文件中關於 BN_is_prime_ex 函式的 nchecks 選項。預設值： 0
• 返回：<boolean> 如果候選數是素數且錯誤機率小於 0.25 ** options.checks，則為 true。

檢查 candidate 的素性。

crypto.constants#

• 型別：<Object>

一個包含與加密和安全相關操作常用常量的物件。當前定義的具體常量在 加密常量 中有描述。

crypto.createCipheriv(algorithm, key, iv[, options])#

• algorithm <string>
• key <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
• iv <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <null>
• options <Object> stream.transform 選項
• 返回：<Cipheriv>

建立並返回一個 Cipheriv 物件，使用給定的 algorithm、key 和初始化向量 (iv)。

options 引數控制流行為，並且是可選的，除非使用 CCM 或 OCB 模式的密碼（例如 'aes-128-ccm'）。在這種情況下，authTagLength 選項是必需的，並指定身份驗證標籤的長度（以位元組為單位），請參閱 CCM 模式。在 GCM 模式下，authTagLength 選項不是必需的，但可用於設定將由 getAuthTag() 返回的身份驗證標籤的長度，預設為 16 位元組。對於 chacha20-poly1305，authTagLength 選項預設為 16 位元組。

algorithm 取決於 OpenSSL，例如 'aes192' 等。在最新的 OpenSSL 版本中，openssl list -cipher-algorithms 將顯示可用的密碼演算法。

key 是 algorithm 使用的原始金鑰，iv 是初始化向量。兩個引數都必須是 'utf8' 編碼的字串、Buffers、TypedArray 或 DataView。key 也可以是型別為 secret 的 KeyObject。如果密碼不需要初始化向量，iv 可以是 null。

當為 key 或 iv 傳遞字串時，請考慮將字串用作加密 API 輸入時的注意事項。

初始化向量應該是不可預測且唯一的；理想情況下，它們應該是加密安全的隨機數。它們不必是機密的：IV 通常只是以未加密的形式新增到密文訊息中。某些事物必須是不可預測且唯一的，但又不必是機密的，這聽起來可能有些矛盾；請記住，攻擊者必須不能提前預測出給定的 IV 將是什麼。

crypto.createDecipheriv(algorithm, key, iv[, options])#

• algorithm <string>
• key <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
• iv <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <null>
• options <Object> stream.transform 選項
• 返回：<Decipheriv>

建立並返回一個使用給定 algorithm、key 和初始化向量 (iv) 的 Decipheriv 物件。

options 引數控制流行為，並且是可選的，除非使用 CCM 或 OCB 模式的密碼（例如 'aes-128-ccm'）。在這種情況下，authTagLength 選項是必需的，並指定身份驗證標籤的長度（以位元組為單位），請參閱 CCM 模式。對於 AES-GCM 和 chacha20-poly1305，authTagLength 選項預設為 16 位元組，如果使用不同長度，則必須設定為不同的值。

algorithm 取決於 OpenSSL，例如 'aes192' 等。在最新的 OpenSSL 版本中，openssl list -cipher-algorithms 將顯示可用的密碼演算法。

key 是 algorithm 使用的原始金鑰，iv 是初始化向量。兩個引數都必須是 'utf8' 編碼的字串、Buffers、TypedArray 或 DataView。key 也可以是型別為 secret 的 KeyObject。如果密碼不需要初始化向量，iv 可以是 null。

當為 key 或 iv 傳遞字串時，請考慮將字串用作加密 API 輸入時的注意事項。

初始化向量應該是不可預測且唯一的；理想情況下，它們應該是加密安全的隨機數。它們不必是機密的：IV 通常只是以未加密的形式新增到密文訊息中。某些事物必須是不可預測且唯一的，但又不必是機密的，這聽起來可能有些矛盾；請記住，攻擊者必須不能提前預測出給定的 IV 將是什麼。

crypto.createDiffieHellman(prime[, primeEncoding][, generator][, generatorEncoding])#

• prime <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• primeEncoding <string> prime 字串的編碼。
• generator <number> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> 預設值： 2
• generatorEncoding <string> generator 字串的編碼。
• 返回：<DiffieHellman>

使用提供的 prime 和一個可選的特定 generator 建立一個 DiffieHellman 金鑰交換物件。

generator 引數可以是一個數字、字串或 Buffer。如果未指定 generator，則使用值 2。

如果指定了 primeEncoding，則 prime 應為字串；否則應為 Buffer、TypedArray 或 DataView。

如果指定了 generatorEncoding，則 generator 應為字串；否則應為數字、Buffer、TypedArray 或 DataView。

crypto.createDiffieHellman(primeLength[, generator])#

• primeLength <number>
• generator <number> 預設值： 2
• 返回：<DiffieHellman>

建立一個 DiffieHellman 金鑰交換物件，並使用可選的特定數值 generator 生成一個 primeLength 位的素數。如果未指定 generator，則使用值 2。

crypto.createDiffieHellmanGroup(name)#

• name <string>
• 返回：<DiffieHellmanGroup>

crypto.getDiffieHellman() 的別名

crypto.createECDH(curveName)#

• curveName <string>
• 返回：<ECDH>

使用由 curveName 字串指定的預定義曲線建立一個橢圓曲線迪菲-赫爾曼 (ECDH) 金鑰交換物件。使用 crypto.getCurves() 獲取可用曲線名稱的列表。在最新的 OpenSSL 版本中，openssl ecparam -list_curves 也會顯示每個可用橢圓曲線的名稱和描述。

crypto.createHash(algorithm[, options])#

• algorithm <string>
• options <Object> stream.transform 選項
• 返回：<Hash>

建立並返回一個 Hash 物件，該物件可用於使用給定的 algorithm 生成雜湊摘要。可選的 options 引數控制流行為。對於 XOF 雜湊函式（如 'shake256'），可以使用 outputLength 選項來指定所需的輸出長度（以位元組為單位）。

algorithm 取決於平臺上 OpenSSL 版本支援的可用演算法。例如 'sha256'、'sha512' 等。在最新的 OpenSSL 版本中，openssl list -digest-algorithms 將顯示可用的摘要演算法。

示例：生成檔案的 sha256 校驗和

import {
  createReadStream,
} from 'node:fs';
import { argv } from 'node:process';
const {
  createHash,
} = await import('node:crypto');

const filename = argv[2];

const hash = createHash('sha256');

const input = createReadStream(filename);
input.on('readable', () => {
  // Only one element is going to be produced by the
  // hash stream.
  const data = input.read();
  if (data)
    hash.update(data);
  else {
    console.log(`${hash.digest('hex')} ${filename}`);
  }
});const {
  createReadStream,
} = require('node:fs');
const {
  createHash,
} = require('node:crypto');
const { argv } = require('node:process');

const filename = argv[2];

const hash = createHash('sha256');

const input = createReadStream(filename);
input.on('readable', () => {
  // Only one element is going to be produced by the
  // hash stream.
  const data = input.read();
  if (data)
    hash.update(data);
  else {
    console.log(`${hash.digest('hex')} ${filename}`);
  }
});copy

crypto.createHmac(algorithm, key[, options])#

• algorithm <string>
• key <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
• options <Object> stream.transform 選項
  • encoding <string> 當 key 是字串時使用的字串編碼。
• 返回：<Hmac>

建立並返回一個使用給定 algorithm 和 key 的 Hmac 物件。可選的 options 引數控制流行為。

algorithm 取決於平臺上 OpenSSL 版本支援的可用演算法。例如 'sha256'、'sha512' 等。在最新的 OpenSSL 版本中，openssl list -digest-algorithms 將顯示可用的摘要演算法。

key 是用於生成加密 HMAC 雜湊的 HMAC 金鑰。如果它是一個 KeyObject，其型別必須是 secret。如果它是一個字串，請考慮將字串用作加密 API 輸入時的注意事項。如果它是從加密安全的熵源（如 crypto.randomBytes() 或 crypto.generateKey()）獲得的，其長度不應超過 algorithm 的塊大小（例如，對於 SHA-256 為 512 位）。

示例：生成檔案的 sha256 HMAC

import {
  createReadStream,
} from 'node:fs';
import { argv } from 'node:process';
const {
  createHmac,
} = await import('node:crypto');

const filename = argv[2];

const hmac = createHmac('sha256', 'a secret');

const input = createReadStream(filename);
input.on('readable', () => {
  // Only one element is going to be produced by the
  // hash stream.
  const data = input.read();
  if (data)
    hmac.update(data);
  else {
    console.log(`${hmac.digest('hex')} ${filename}`);
  }
});const {
  createReadStream,
} = require('node:fs');
const {
  createHmac,
} = require('node:crypto');
const { argv } = require('node:process');

const filename = argv[2];

const hmac = createHmac('sha256', 'a secret');

const input = createReadStream(filename);
input.on('readable', () => {
  // Only one element is going to be produced by the
  // hash stream.
  const data = input.read();
  if (data)
    hmac.update(data);
  else {
    console.log(`${hmac.digest('hex')} ${filename}`);
  }
});copy

crypto.createPrivateKey(key)#

• key <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
  • key <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <Object> 金鑰材料，格式為 PEM、DER 或 JWK。
  • format <string> 必須是 'pem'、'der' 或 ''jwk'。預設值： 'pem'。
  • type <string> 必須是 'pkcs1'、'pkcs8' 或 'sec1'。此選項僅在 format 為 'der' 時是必需的，否則將被忽略。
  • passphrase <string> | <Buffer> 用於解密的密碼短語。
  • encoding <string> 當 key 是字串時使用的字串編碼。
• 返回：<KeyObject>

建立並返回一個包含私鑰的新金鑰物件。如果 key 是字串或 Buffer，則假定 format 為 'pem'；否則，key 必須是具有上述屬性的物件。

如果私鑰已加密，則必須指定 passphrase。密碼短語的長度限制為 1024 位元組。

crypto.createPublicKey(key)#

• key <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
  • key <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <Object> 金鑰材料，格式為 PEM、DER 或 JWK。
  • format <string> 必須是 'pem'、'der' 或 'jwk'。預設值： 'pem'。
  • type <string> 必須是 'pkcs1' 或 'spki'。此選項僅在 format 為 'der' 時是必需的，否則將被忽略。
  • encoding <string> 當 key 是字串時使用的字串編碼。
• 返回：<KeyObject>

建立並返回一個包含公鑰的新金鑰物件。如果 key 是字串或 Buffer，則假定 format 為 'pem'；如果 key 是一個型別為 'private' 的 KeyObject，則公鑰從給定的私鑰派生；否則，key 必須是具有上述屬性的物件。

如果格式是 'pem'，'key' 也可以是 X.509 證書。

因為公鑰可以從私鑰派生，所以可以傳遞私鑰來代替公鑰。在這種情況下，此函式的行為就好像呼叫了 crypto.createPrivateKey() 一樣，只是返回的 KeyObject 的型別將是 'public'，並且無法從返回的 KeyObject 中提取私鑰。類似地，如果給定一個型別為 'private' 的 KeyObject，將返回一個型別為 'public' 的新 KeyObject，並且無法從返回的物件中提取私鑰。

crypto.createSecretKey(key[, encoding])#

• key <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• encoding <string> 當 key 是字串時的字串編碼。
• 返回：<KeyObject>

建立並返回一個包含用於對稱加密或 Hmac 的金鑰的新金鑰物件。

crypto.createSign(algorithm[, options])#

• algorithm <string>
• options <Object> stream.Writable 選項
• 返回：<Sign>

建立並返回一個使用給定 algorithm 的 Sign 物件。使用 crypto.getHashes() 獲取可用摘要演算法的名稱。可選的 options 引數控制 stream.Writable 行為。

在某些情況下，可以使用簽名演算法的名稱（如 'RSA-SHA256'）來建立 Sign 例項，而不是摘要演算法的名稱。這將使用相應的摘要演算法。但這不適用於所有簽名演算法，例如 'ecdsa-with-SHA256'，所以最好總是使用摘要演算法的名稱。

crypto.createVerify(algorithm[, options])#

• algorithm <string>
• options <Object> stream.Writable 選項
• 返回：<Verify>

建立並返回一個使用給定演算法的 Verify 物件。使用 crypto.getHashes() 獲取可用簽名演算法名稱的陣列。可選的 options 引數控制 stream.Writable 行為。

在某些情況下，可以使用簽名演算法的名稱（如 'RSA-SHA256'）來建立 Verify 例項，而不是摘要演算法的名稱。這將使用相應的摘要演算法。但這不適用於所有簽名演算法，例如 'ecdsa-with-SHA256'，所以最好總是使用摘要演算法的名稱。

crypto.decapsulate(key, ciphertext[, callback])#

• key <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> 私鑰
• ciphertext <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• callback <Function>
  • err <Error>
  • sharedKey <Buffer>
• 返回：如果未提供 callback 函式，則返回 <Buffer>。

使用 KEM 演算法和私鑰進行金鑰解封裝。

支援的金鑰型別及其 KEM 演算法如下

• 'rsa'² RSA 秘密值封裝
• 'ec'³ DHKEM(P-256, HKDF-SHA256), DHKEM(P-384, HKDF-SHA256), DHKEM(P-521, HKDF-SHA256)
• 'x25519'³ DHKEM(X25519, HKDF-SHA256)
• 'x448'³ DHKEM(X448, HKDF-SHA512)
• 'ml-kem-512'¹ ML-KEM
• 'ml-kem-768'¹ ML-KEM
• 'ml-kem-1024'¹ ML-KEM

如果 key 不是 KeyObject，此函式的行為就好像將 key 傳遞給了 crypto.createPrivateKey() 一樣。

如果提供了 callback 函式，此函式將使用 libuv 的執行緒池。

crypto.diffieHellman(options[, callback])#

• options <Object>
  • privateKey <KeyObject>
  • publicKey <KeyObject>
• callback <Function>
  • err <Error>
  • secret <Buffer>
• 返回：如果未提供 callback 函式，則返回 <Buffer>。

根據 privateKey 和 publicKey 計算 Diffie-Hellman 共享金鑰。兩個金鑰必須具有相同的 asymmetricKeyType，並且必須支援 DH 或 ECDH 操作。

如果提供了 callback 函式，此函式將使用 libuv 的執行緒池。

crypto.encapsulate(key[, callback])#

• key <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> 公鑰
• callback <Function>
  • err <Error>
  • result <Object>
    • sharedKey <Buffer>
    • ciphertext <Buffer>
• 返回：如果未提供 callback 函式，則返回 <Object>。
  • sharedKey <Buffer>
  • ciphertext <Buffer>

使用 KEM 演算法和公鑰進行金鑰封裝。

支援的金鑰型別及其 KEM 演算法如下

• 'rsa'² RSA 秘密值封裝
• 'ec'³ DHKEM(P-256, HKDF-SHA256), DHKEM(P-384, HKDF-SHA256), DHKEM(P-521, HKDF-SHA256)
• 'x25519'³ DHKEM(X25519, HKDF-SHA256)
• 'x448'³ DHKEM(X448, HKDF-SHA512)
• 'ml-kem-512'¹ ML-KEM
• 'ml-kem-768'¹ ML-KEM
• 'ml-kem-1024'¹ ML-KEM

如果 key 不是 KeyObject，此函式的行為就好像將 key 傳遞給了 crypto.createPublicKey() 一樣。

如果提供了 callback 函式，此函式將使用 libuv 的執行緒池。

crypto.fips#

用於檢查和控制當前是否正在使用符合 FIPS 的加密提供程式的屬性。設定為 true 需要 Node.js 的 FIPS 構建版本。

此屬性已棄用。請改用 crypto.setFips() 和 crypto.getFips()。

crypto.generateKey(type, options, callback)#

• type <string> 生成的金鑰的預期用途。當前接受的值是 'hmac' 和 'aes'。
• options <Object>
  • length <number> 要生成的金鑰的位長度。此值必須大於 0。
    • 如果 type 是 'hmac'，最小值為 8，最大長度為 2³¹-1。如果該值不是 8 的倍數，生成的金鑰將被截斷為 Math.floor(length / 8)。
    • 如果 type 是 'aes'，長度必須是 128、192 或 256 之一。
• callback <Function>
  • err <Error>
  • key <KeyObject>

非同步生成一個給定 length 的新隨機金鑰。type 將決定對 length 執行哪些驗證。

const {
  generateKey,
} = await import('node:crypto');

generateKey('hmac', { length: 512 }, (err, key) => {
  if (err) throw err;
  console.log(key.export().toString('hex'));  // 46e..........620
});const {
  generateKey,
} = require('node:crypto');

generateKey('hmac', { length: 512 }, (err, key) => {
  if (err) throw err;
  console.log(key.export().toString('hex'));  // 46e..........620
});copy

生成的 HMAC 金鑰的大小不應超過底層雜湊函式的塊大小。有關更多資訊，請參閱 crypto.createHmac()。

crypto.generateKeyPair(type, options, callback)#

• type <string> 要生成的非對稱金鑰型別。請參閱支援的非對稱金鑰型別。
• options <Object>
  • modulusLength <number> 金鑰大小（以位為單位）（RSA, DSA）。
  • publicExponent <number> 公共指數 (RSA)。預設值： 0x10001。
  • hashAlgorithm <string> 訊息摘要的名稱（RSA-PSS）。
  • mgf1HashAlgorithm <string> MGF1 使用的訊息摘要的名稱（RSA-PSS）。
  • saltLength <number> 最小鹽長度（以位元組為單位）（RSA-PSS）。
  • divisorLength <number> q 的大小（以位為單位）（DSA）。
  • namedCurve <string> 要使用的曲線名稱 (EC)。
  • prime <Buffer> 素數引數 (DH)。
  • primeLength <number> 素數長度（以位為單位）(DH)。
  • generator <number> 自定義生成元 (DH)。預設值： 2。
  • groupName <string> Diffie-Hellman 組名 (DH)。請參閱 crypto.getDiffieHellman()。
  • paramEncoding <string> 必須是 'named' 或 'explicit' (EC)。預設值： 'named'。
  • publicKeyEncoding <Object> 請參閱 keyObject.export()。
  • privateKeyEncoding <Object> 請參閱 keyObject.export()。
• callback <Function>
  • err <Error>
  • publicKey <string> | <Buffer> | <KeyObject>
  • privateKey <string> | <Buffer> | <KeyObject>

生成給定 type 的新非對稱金鑰對。目前支援 RSA、RSA-PSS、DSA、EC、Ed25519、Ed448、X25519、X448 和 DH。

如果指定了 publicKeyEncoding 或 privateKeyEncoding，此函式的行為就好像在其結果上呼叫了 keyObject.export()。否則，金鑰的相應部分將作為 KeyObject 返回。

建議將公鑰編碼為 'spki'，將私鑰編碼為 'pkcs8' 並進行加密以供長期儲存。

const {
  generateKeyPair,
} = await import('node:crypto');

generateKeyPair('rsa', {
  modulusLength: 4096,
  publicKeyEncoding: {
    type: 'spki',
    format: 'pem',
  },
  privateKeyEncoding: {
    type: 'pkcs8',
    format: 'pem',
    cipher: 'aes-256-cbc',
    passphrase: 'top secret',
  },
}, (err, publicKey, privateKey) => {
  // Handle errors and use the generated key pair.
});const {
  generateKeyPair,
} = require('node:crypto');

generateKeyPair('rsa', {
  modulusLength: 4096,
  publicKeyEncoding: {
    type: 'spki',
    format: 'pem',
  },
  privateKeyEncoding: {
    type: 'pkcs8',
    format: 'pem',
    cipher: 'aes-256-cbc',
    passphrase: 'top secret',
  },
}, (err, publicKey, privateKey) => {
  // Handle errors and use the generated key pair.
});copy

完成後，將呼叫 callback，其中 err 設定為 undefined，publicKey / privateKey 表示生成的金鑰對。

如果此方法作為其 util.promisify() 版本被呼叫，它將返回一個 Promise，該 Promise 解析為一個具有 publicKey 和 privateKey 屬性的物件。

crypto.generateKeyPairSync(type, options)#

• type <string> 要生成的非對稱金鑰型別。請參閱支援的非對稱金鑰型別。
• options <Object>
  • modulusLength <number> 金鑰大小（以位為單位）（RSA, DSA）。
  • publicExponent <number> 公共指數 (RSA)。預設值： 0x10001。
  • hashAlgorithm <string> 訊息摘要的名稱（RSA-PSS）。
  • mgf1HashAlgorithm <string> MGF1 使用的訊息摘要的名稱（RSA-PSS）。
  • saltLength <number> 最小鹽長度（以位元組為單位）（RSA-PSS）。
  • divisorLength <number> q 的大小（以位為單位）（DSA）。
  • namedCurve <string> 要使用的曲線名稱 (EC)。
  • prime <Buffer> 素數引數 (DH)。
  • primeLength <number> 素數長度（以位為單位）(DH)。
  • generator <number> 自定義生成元 (DH)。預設值： 2。
  • groupName <string> Diffie-Hellman 組名 (DH)。請參閱 crypto.getDiffieHellman()。
  • paramEncoding <string> 必須是 'named' 或 'explicit' (EC)。預設值： 'named'。
  • publicKeyEncoding <Object> 請參閱 keyObject.export()。
  • privateKeyEncoding <Object> 請參閱 keyObject.export()。
• 返回：<Object>
  • publicKey <string> | <Buffer> | <KeyObject>
  • privateKey <string> | <Buffer> | <KeyObject>

生成給定 type 的新非對稱金鑰對。目前支援 RSA、RSA-PSS、DSA、EC、Ed25519、Ed448、X25519、X448、DH 和 ML-DSA¹。

如果指定了 publicKeyEncoding 或 privateKeyEncoding，此函式的行為就好像在其結果上呼叫了 keyObject.export()。否則，金鑰的相應部分將作為 KeyObject 返回。

編碼公鑰時，建議使用 'spki'。編碼私鑰時，建議使用 'pkcs8' 和強密碼，並對密碼保密。

const {
  generateKeyPairSync,
} = await import('node:crypto');

const {
  publicKey,
  privateKey,
} = generateKeyPairSync('rsa', {
  modulusLength: 4096,
  publicKeyEncoding: {
    type: 'spki',
    format: 'pem',
  },
  privateKeyEncoding: {
    type: 'pkcs8',
    format: 'pem',
    cipher: 'aes-256-cbc',
    passphrase: 'top secret',
  },
});const {
  generateKeyPairSync,
} = require('node:crypto');

const {
  publicKey,
  privateKey,
} = generateKeyPairSync('rsa', {
  modulusLength: 4096,
  publicKeyEncoding: {
    type: 'spki',
    format: 'pem',
  },
  privateKeyEncoding: {
    type: 'pkcs8',
    format: 'pem',
    cipher: 'aes-256-cbc',
    passphrase: 'top secret',
  },
});copy

返回值 { publicKey, privateKey } 表示生成的金鑰對。當選擇 PEM 編碼時，相應的金鑰將是一個字串，否則它將是一個包含 DER 編碼資料的緩衝區。

crypto.generateKeySync(type, options)#

• type <string> 生成的金鑰的預期用途。當前接受的值是 'hmac' 和 'aes'。
• options <Object>
  • length <number> 要生成的金鑰的位長度。
    • 如果 type 是 'hmac'，最小值為 8，最大長度為 2³¹-1。如果該值不是 8 的倍數，生成的金鑰將被截斷為 Math.floor(length / 8)。
    • 如果 type 是 'aes'，長度必須是 128、192 或 256 之一。
• 返回：<KeyObject>

同步生成一個給定 length 的新隨機金鑰。type 將決定對 length 執行哪些驗證。

const {
  generateKeySync,
} = await import('node:crypto');

const key = generateKeySync('hmac', { length: 512 });
console.log(key.export().toString('hex'));  // e89..........41econst {
  generateKeySync,
} = require('node:crypto');

const key = generateKeySync('hmac', { length: 512 });
console.log(key.export().toString('hex'));  // e89..........41ecopy

生成的 HMAC 金鑰的大小不應超過底層雜湊函式的塊大小。有關更多資訊，請參閱 crypto.createHmac()。

crypto.generatePrime(size[, options], callback)#

• size <number> 要生成的素數的大小（以位為單位）。
• options <Object>
  • add <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Buffer> | <DataView> | <bigint>
  • rem <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Buffer> | <DataView> | <bigint>
  • safe <boolean> 預設值： false。
  • bigint <boolean> 當為 true 時，生成的素數將作為 bigint 返回。
• callback <Function>
  • err <Error>
  • prime <ArrayBuffer> | <bigint>

生成一個 size 位的偽隨機素數。

如果 options.safe 為 true，則該素數將是一個安全素數——也就是說，(prime - 1) / 2 也將是一個素數。

options.add 和 options.rem 引數可用於強制執行附加要求，例如用於 Diffie-Hellman

• 如果 options.add 和 options.rem 都被設定，素數將滿足條件 prime % add = rem。
• 如果僅設定了 options.add 且 options.safe 不為 true，則素數將滿足條件 prime % add = 1。
• 如果僅設定了 options.add 且 options.safe 設定為 true，則素數將改為滿足條件 prime % add = 3。這是必要的，因為對於 options.add > 2，prime % add = 1 會與 options.safe 強制執行的條件相矛盾。
• 如果未給出 options.add，則忽略 options.rem。

如果 options.add 和 options.rem 以 ArrayBuffer、SharedArrayBuffer、TypedArray、Buffer 或 DataView 的形式給出，則它們必須編碼為大端序列。

預設情況下，素數被編碼為 <ArrayBuffer> 中的大端八位位元組序列。如果 bigint 選項為 true，則提供一個 <bigint>。

素數的 size 會直接影響生成素數所需的時間。size 越大，所需時間越長。因為我們使用 OpenSSL 的 BN_generate_prime_ex 函式，該函式對我們中斷生成過程的能力控制很小，所以不建議生成過大的素數，因為這樣做可能會使程序無響應。

crypto.generatePrimeSync(size[, options])#

• size <number> 要生成的素數的大小（以位為單位）。
• options <Object>
  • add <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Buffer> | <DataView> | <bigint>
  • rem <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Buffer> | <DataView> | <bigint>
  • safe <boolean> 預設值： false。
  • bigint <boolean> 當為 true 時，生成的素數將作為 bigint 返回。
• 返回：<ArrayBuffer> | <bigint>

生成一個 size 位的偽隨機素數。

如果 options.safe 為 true，則該素數將是一個安全素數——也就是說，(prime - 1) / 2 也將是一個素數。

options.add 和 options.rem 引數可用於強制執行附加要求，例如用於 Diffie-Hellman

• 如果 options.add 和 options.rem 都被設定，素數將滿足條件 prime % add = rem。
• 如果僅設定了 options.add 且 options.safe 不為 true，則素數將滿足條件 prime % add = 1。
• 如果僅設定了 options.add 且 options.safe 設定為 true，則素數將改為滿足條件 prime % add = 3。這是必要的，因為對於 options.add > 2，prime % add = 1 會與 options.safe 強制執行的條件相矛盾。
• 如果未給出 options.add，則忽略 options.rem。

如果 options.add 和 options.rem 以 ArrayBuffer、SharedArrayBuffer、TypedArray、Buffer 或 DataView 的形式給出，則它們必須編碼為大端序列。

預設情況下，素數被編碼為 <ArrayBuffer> 中的大端八位位元組序列。如果 bigint 選項為 true，則提供一個 <bigint>。

素數的 size 會直接影響生成素數所需的時間。size 越大，所需時間越長。因為我們使用 OpenSSL 的 BN_generate_prime_ex 函式，該函式對我們中斷生成過程的能力控制很小，所以不建議生成過大的素數，因為這樣做可能會使程序無響應。

crypto.getCipherInfo(nameOrNid[, options])#

• nameOrNid <string> | <number> 要查詢的密碼的名稱或 nid。
• options <Object>
  • keyLength <number> 一個測試金鑰長度。
  • ivLength <number> 一個測試 IV 長度。
• 返回：<Object>
  • name <string> 密碼的名稱
  • nid <number> 密碼的 nid
  • blockSize <number> 密碼的塊大小（以位元組為單位）。當 mode 為 'stream' 時，此屬性被省略。
  • ivLength <number> 預期的或預設的初始化向量長度（以位元組為單位）。如果密碼不使用初始化向量，則省略此屬性。
  • keyLength <number> 預期的或預設的金鑰長度（以位元組為單位）。
  • mode <string> 密碼模式。為 'cbc'、'ccm'、'cfb'、'ctr'、'ecb'、'gcm'、'ocb'、'ofb'、'stream'、'wrap'、'xts' 之一。

返回有關給定密碼的資訊。

一些密碼接受可變長度的金鑰和初始化向量。預設情況下，crypto.getCipherInfo() 方法將返回這些密碼的預設值。要測試給定的金鑰長度或 IV 長度是否適用於給定的密碼，請使用 keyLength 和 ivLength 選項。如果給定的值不可接受，將返回 undefined。

crypto.getCiphers()#

• 返回：<string[]> 一個包含支援的密碼演算法名稱的陣列。

const {
  getCiphers,
} = await import('node:crypto');

console.log(getCiphers()); // ['aes-128-cbc', 'aes-128-ccm', ...]const {
  getCiphers,
} = require('node:crypto');

console.log(getCiphers()); // ['aes-128-cbc', 'aes-128-ccm', ...]copy

crypto.getCurves()#

• 返回：<string[]> 一個包含支援的橢圓曲線名稱的陣列。

const {
  getCurves,
} = await import('node:crypto');

console.log(getCurves()); // ['Oakley-EC2N-3', 'Oakley-EC2N-4', ...]const {
  getCurves,
} = require('node:crypto');

console.log(getCurves()); // ['Oakley-EC2N-3', 'Oakley-EC2N-4', ...]copy

crypto.getDiffieHellman(groupName)#

• groupName <string>
• 返回：<DiffieHellmanGroup>

建立一個預定義的 DiffieHellmanGroup 金鑰交換物件。支援的組在 DiffieHellmanGroup 的文件中列出。

返回的物件模仿由 crypto.createDiffieHellman() 建立的物件的介面，但不允許更改金鑰（例如，使用 diffieHellman.setPublicKey()）。使用此方法的優點是各方不必事先生成或交換組模數，從而節省了處理器和通訊時間。

示例（獲取共享金鑰）

const {
  getDiffieHellman,
} = await import('node:crypto');
const alice = getDiffieHellman('modp14');
const bob = getDiffieHellman('modp14');

alice.generateKeys();
bob.generateKeys();

const aliceSecret = alice.computeSecret(bob.getPublicKey(), null, 'hex');
const bobSecret = bob.computeSecret(alice.getPublicKey(), null, 'hex');

/* aliceSecret and bobSecret should be the same */
console.log(aliceSecret === bobSecret);const {
  getDiffieHellman,
} = require('node:crypto');

const alice = getDiffieHellman('modp14');
const bob = getDiffieHellman('modp14');

alice.generateKeys();
bob.generateKeys();

const aliceSecret = alice.computeSecret(bob.getPublicKey(), null, 'hex');
const bobSecret = bob.computeSecret(alice.getPublicKey(), null, 'hex');

/* aliceSecret and bobSecret should be the same */
console.log(aliceSecret === bobSecret);copy

crypto.getFips()#

• 返回：<number> 當且僅當當前正在使用符合 FIPS 的加密提供程式時返回 1，否則返回 0。未來的 semver-major 版本可能會將此 API 的返回型別更改為 <boolean>。

crypto.getHashes()#

• 返回：<string[]> 一個包含支援的雜湊演算法名稱的陣列，例如 'RSA-SHA256'。雜湊演算法也稱為“摘要”演算法。

const {
  getHashes,
} = await import('node:crypto');

console.log(getHashes()); // ['DSA', 'DSA-SHA', 'DSA-SHA1', ...]const {
  getHashes,
} = require('node:crypto');

console.log(getHashes()); // ['DSA', 'DSA-SHA', 'DSA-SHA1', ...]copy

crypto.getRandomValues(typedArray)#

• typedArray <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer>
• 返回：<Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> 返回 typedArray。

crypto.webcrypto.getRandomValues() 的一個方便別名。此實現不符合 Web Crypto 規範，要編寫與 Web 相容的程式碼，請改用 crypto.webcrypto.getRandomValues()。

crypto.hash(algorithm, data[, options])#

• algorithm <string> | <undefined>
• data <string> | <Buffer> | <TypedArray> | <DataView> 當 data 是字串時，它將在雜湊前被編碼為 UTF-8。如果希望對字串輸入使用不同的輸入編碼，使用者可以使用 TextEncoder 或 Buffer.from() 將字串編碼為 TypedArray，然後將編碼後的 TypedArray 傳遞給此 API。
• options <Object> | <string>
  • outputEncoding <string> 用於編碼返回的摘要的編碼。預設值： 'hex'。
  • outputLength <number> 對於 XOF 雜湊函式（如 'shake256'），可以使用 outputLength 選項來指定所需的輸出長度（以位元組為單位）。
• 返回：<string> | <Buffer>

一個用於建立資料的一次性雜湊摘要的實用工具。在對較小量（<= 5MB）且已準備好的資料進行雜湊時，它可能比基於物件的 crypto.createHash() 更快。如果資料可能很大或是流式資料，仍建議使用 crypto.createHash()。

algorithm 取決於平臺上 OpenSSL 版本支援的可用演算法。例如 'sha256'、'sha512' 等。在最新的 OpenSSL 版本中，openssl list -digest-algorithms 將顯示可用的摘要演算法。

如果 options 是一個字串，則它指定了 outputEncoding。

示例

const crypto = require('node:crypto');
const { Buffer } = require('node:buffer');

// Hashing a string and return the result as a hex-encoded string.
const string = 'Node.js';
// 10b3493287f831e81a438811a1ffba01f8cec4b7
console.log(crypto.hash('sha1', string));

// Encode a base64-encoded string into a Buffer, hash it and return
// the result as a buffer.
const base64 = 'Tm9kZS5qcw==';
// <Buffer 10 b3 49 32 87 f8 31 e8 1a 43 88 11 a1 ff ba 01 f8 ce c4 b7>
console.log(crypto.hash('sha1', Buffer.from(base64, 'base64'), 'buffer'));import crypto from 'node:crypto';
import { Buffer } from 'node:buffer';

// Hashing a string and return the result as a hex-encoded string.
const string = 'Node.js';
// 10b3493287f831e81a438811a1ffba01f8cec4b7
console.log(crypto.hash('sha1', string));

// Encode a base64-encoded string into a Buffer, hash it and return
// the result as a buffer.
const base64 = 'Tm9kZS5qcw==';
// <Buffer 10 b3 49 32 87 f8 31 e8 1a 43 88 11 a1 ff ba 01 f8 ce c4 b7>
console.log(crypto.hash('sha1', Buffer.from(base64, 'base64'), 'buffer'));copy

crypto.hkdf(digest, ikm, salt, info, keylen, callback)#

• digest <string> 要使用的摘要演算法。
• ikm <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> 輸入金鑰材料。必須提供，但可以為零長度。
• salt <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> 鹽值。必須提供，但可以為零長度。
• info <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> 附加資訊值。必須提供，但可以為零長度，並且不能超過 1024 位元組。
• keylen <number> 要生成的金鑰的長度。必須大於 0。允許的最大值是所選摘要函式產生的位元組數的 255 倍（例如，sha512 生成 64 位元組的雜湊，使得最大 HKDF 輸出為 16320 位元組）。
• callback <Function>
  • err <Error>
  • derivedKey <ArrayBuffer>

HKDF 是 RFC 5869 中定義的一個簡單的金鑰派生函式。給定的 ikm、salt 和 info 與 digest 一起用於派生一個長度為 keylen 位元組的金鑰。

提供的 callback 函式被呼叫時帶有兩個引數：err 和 derivedKey。如果在派生金鑰時發生錯誤，err 將被設定；否則 err 將為 null。成功生成的 derivedKey 將作為 <ArrayBuffer> 傳遞給回撥函式。如果任何輸入引數指定了無效的值或型別，將丟擲錯誤。

import { Buffer } from 'node:buffer';
const {
  hkdf,
} = await import('node:crypto');

hkdf('sha512', 'key', 'salt', 'info', 64, (err, derivedKey) => {
  if (err) throw err;
  console.log(Buffer.from(derivedKey).toString('hex'));  // '24156e2...5391653'
});const {
  hkdf,
} = require('node:crypto');
const { Buffer } = require('node:buffer');

hkdf('sha512', 'key', 'salt', 'info', 64, (err, derivedKey) => {
  if (err) throw err;
  console.log(Buffer.from(derivedKey).toString('hex'));  // '24156e2...5391653'
});copy

crypto.hkdfSync(digest, ikm, salt, info, keylen)#

• digest <string> 要使用的摘要演算法。
• ikm <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> 輸入金鑰材料。必須提供，但可以為零長度。
• salt <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> 鹽值。必須提供，但可以為零長度。
• info <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> 附加資訊值。必須提供，但可以為零長度，並且不能超過 1024 位元組。
• keylen <number> 要生成的金鑰的長度。必須大於 0。允許的最大值是所選摘要函式產生的位元組數的 255 倍（例如，sha512 生成 64 位元組的雜湊，使得最大 HKDF 輸出為 16320 位元組）。
• 返回：<ArrayBuffer>

提供一個同步的 HKDF 金鑰派生函式，如 RFC 5869 中定義。給定的 ikm、salt 和 info 與 digest 一起用於派生一個長度為 keylen 位元組的金鑰。

成功生成的 derivedKey 將作為 <ArrayBuffer> 返回。

如果任何輸入引數指定了無效的值或型別，或者無法生成派生金鑰，則將丟擲錯誤。

import { Buffer } from 'node:buffer';
const {
  hkdfSync,
} = await import('node:crypto');

const derivedKey = hkdfSync('sha512', 'key', 'salt', 'info', 64);
console.log(Buffer.from(derivedKey).toString('hex'));  // '24156e2...5391653'const {
  hkdfSync,
} = require('node:crypto');
const { Buffer } = require('node:buffer');

const derivedKey = hkdfSync('sha512', 'key', 'salt', 'info', 64);
console.log(Buffer.from(derivedKey).toString('hex'));  // '24156e2...5391653'copy

crypto.pbkdf2(password, salt, iterations, keylen, digest, callback)#