Node.js cipher.setAAD() 方法

2025年2月15日 | 阅读 4 分钟

在本文中，我们将讨论 Node.js 的 cipher.setAAD() 方法，包括其语法、参数和示例。

Node.js cipher.setAAD() 方法是什么？

Node.js 的 cipher.setAAD() 函数用于为加密/解密流设置附加的认证数据 (AAD)。AAD 是经过验证但未加密的数据部分。当传输需要验证但无需保密的加密数据时，这非常有用。

Node.js cipher.setAAD() 函数是 crypto 模块的一部分，该模块提供了各种 OpenSSL 函数的包装器，如哈希、HMAC、cipher、decipher、sign 和 verify。

在带附加数据的认证加密 (AEAD) 模式下，将执行 cipher.setAAD() 函数。除了确保数据机密性外，AEAD 加密还确保数据的完整性和真实性。当仅加密数据不足以保证安全通信协议（例如 TLS）时，它特别有用，因为 TLS 需要数据验证。

语法

它具有以下语法：

参数

cipher.setAAD() 方法需要两个参数

Aad：一个包含附加认证数据 (aad) 的 buffer 或 typed array。
Options：一个用于配置 AAD 的选项对象，这是可选的。此对象可能包含 plaintextLength 属性，该属性包含将要加密的明文数据的字节数。

用途

cipher.setAAD() 函数可用于设置将进行验证但不会被加密的附加认证数据 (AAD)。因此，由于在确定认证标签时会考虑 AAD，任何对 AAD 的更改将在解密时被检测到。

使用 cipher.setAAD() 是否合适？

安全通信协议（如 TLS）保证数据的完整性和真实性。
数据完整性是指在加密通信中保护元数据或头数据。
对于认证加密，使用 AES-GCM（Galois/Counter Mode）或 AES-CCM（Counter with CBC-MAC）等算法。

示例 1

让我们举一个例子来说明 Node.js 的 cipher.setAAD() 函数。

 
const crypto = require('crypto');

// Example plaintext and AAD
const plaintext = 'This is some data to encrypt';
const aad = 'This is some additional authenticated data';

// Key and IV for AES-GCM
const key = crypto.randomBytes(32);
const iv = crypto.randomBytes(12);

// Create cipher instance
const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);

// Set AAD before encrypting
cipher.setAAD(Buffer.from(aad));

// Encrypt the plaintext
let encrypted = cipher.update(plaintext, 'utf8', 'hex');
encrypted += cipher.final('hex');

// Get the authentication tag
const authTag = cipher.getAuthTag().toString('hex');

console.log(`Encrypted: ${encrypted}`);
console.log(`Auth Tag: ${authTag}`);   

输出

 
Encrypted: b5f89c1acb2462d8b01f696b6751a9d90317ebe96202910ad5cacf73
Auth Tag: 1545941ba1b598c8aa3c048ff0662b5b

说明

操作顺序： cipher.setAAD() 函数必须在任何使用 cipher.update() 加密数据之前调用。

兼容性： cipher.setAAD() 函数仅兼容 AES-GCM 和 AES-CCM 密码。

真实性和完整性验证：在解密过程中，需要使用 decipher.setAuthTag() 函数来检查认证标签。

示例 2

让我们再举一个例子来说明 Node.js 的 cipher.setAAD() 函数。

 
const crypto = require('crypto');

async function main() {
  const key = crypto.randomBytes(32); // 256-bit key for AES-256
  const iv = crypto.randomBytes(12); // 96-bit IV for AES-GCM

  const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);

  cipher.setAAD(Buffer.from('authenticated data example'));

  // Encrypt some sample data
  let encrypted = cipher.update('example data to encrypt', 'utf8', 'hex');
  encrypted += cipher.final('hex');

  // Obtain the authentication tag
  const authTag = cipher.getAuthTag();

  const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);

  // Set the same AAD and authentication tag for decryption
  decipher.setAAD(Buffer.from('authenticated data example'));
  decipher.setAuthTag(authTag);

  // Decrypt the encrypted data
  let decrypted = decipher.update(encrypted, 'hex', 'utf8');
  decrypted += decipher.final('utf8');

  // Output the decrypted data
  console.log(decrypted);
}

main();   

输出

 
example data to encrypt

说明

此示例演示了如何在 Node.js 中使用 AES-256-GCM 密码执行认证加密。它首先使用 crypto.randomBytes 函数创建一个随机的 256 位密钥和一个 96 位初始化向量 (IV)。之后，代码使用 AES-256-GCM 算法创建一个 cipher 实例，并使用 cipher.setAAD() 将附加认证数据 (AAD) 设置为“authenticated data example”。此 AAD 仅用于完整性验证；它不是加密输出的一部分。在对明文“example data to encrypt”使用 cipher.update() 和 cipher.final() 进行加密后，密文以十六进制格式显示。使用 cipher.getAuthTag() 函数创建的认证标签，确保了加密数据的完整性和真实性。

结论

总之，当使用 AEAD（带附加数据的认证加密）模式在 Node.js 中实现认证加密时，cipher.setAAD() 函数的使用至关重要。它允许开发人员在加密过程中添加附加的已验证但未加密的数据，从而确保数据的完整性和真实性。这种方法在需要数据完整性和机密性的安全通信协议中尤为重要。当 cipher.setAAD() 与正确的认证标签处理结合使用时，开发人员可以保护他们的应用程序免受不必要的修改和篡改。这保证了加密数据和任何相关的附加数据的安全传输和接收。总而言之，这加强了 Node.js 应用程序中加密操作的安全模型。

下一主题Nodejs-console-groupcollapsed-method

Node.js cipher.setAAD() 方法