一、AAD到底认证了什么
cipher.setAAD()传入的数据会被纳入认证标签（authenticationtag）的计算，但不会出现在密文输出中。解密端用相同的AAD调用decipher.setAAD()，如果AAD有任何字节差异，decipher.final()会抛出异常，密文解密失败。
这个机制解决了一个具体问题：有些数据需要保证“没被篡改”，但不需要保密。比如TLS记录层的序列号、自定义协议中的消息ID、数据库加密字段的主键。把这些数据放进AAD，攻击者无法在不破坏认证标签的前提下修改它们，而它们仍然以明文形式参与协议流程。
官方文档明确：cipher.setAAD()必须在cipher.update()之前调用。这个时序约束不是建议，而是API契约。一旦调用过update，cipher对象进入加密状态，再调用setAAD会触发ERR_CRYPTO_INVALID_STATE。
二、语法与参数的真实约束
cipher.setAAD(buffer[, options])
第一个参数接受Buffer、TypedArray或DataView。如果传入字符串，需要依赖options.encoding指定编码，但官方文档对字符串输入有专门的注意事项（涉及编码一致性和潜在的安全），生产代码应始终显式构造Buffer。
options.plaintextLength的行为因算法而异，这是最容易踩坑的地方：
| 算法 | plaintextLength要求 |
|---|---|
| AES-GCM | 可选 |
| AES-OCB | 可选 |
| AES-CCM | 必须指定，且值必须等于明文字节长度 |
| chacha20-poly1305 | 可选（但指定可提前校验长度） |
CCM模式底层需要知道明文长度才能正确构造认证结构。如果忘记传plaintextLength，setAAD可能不立即报错，但后续update/final阶段会产生难以定位的认证失败。源码层面的历史提交显示，setAAD在状态不合法时抛出的是ERR_CRYPTO_INVALID_STATE，而非参数类型错误。
三、单元测试：时序、AAD篡改与CCM长度校验
以下测试覆盖了三个关键边界：setAAD在update之后调用、解密端AAD不匹配、CCM缺少plaintextLength。
const assert = require('assert');
const crypto = require('crypto');
// 用例 1：setAAD 必须在 update 之前
const key = crypto.randomBytes(32);
const iv = crypto.randomBytes(12);
const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
cipher.update('data');
assert.throws(
() => cipher.setAAD(Buffer.from('late')),
(err) => err.code === 'ERR_CRYPTO_INVALID_STATE'
);
// 用例 2：AAD 篡改导致解密失败
function encryptWithAAD(plaintext, aad) {
const k = crypto.randomBytes(32);
const v = crypto.randomBytes(12);
const c = crypto.createCipheriv('aes-256-gcm', k, v);
c.setAAD(aad);
const ct = Buffer.concat([c.update(plaintext, 'utf8'), c.final()]);
return { key: k, iv: v, ct, tag: c.getAuthTag() };
}
const { key: k2, iv: v2, ct, tag } = encryptWithAAD('secret', Buffer.from('header-v1'));
const decipher = crypto.createDecipheriv('aes-256-gcm', k2, v2);
decipher.setAAD(Buffer.from('header-v2')); // 与加密端不一致
decipher.setAuthTag(tag);
assert.throws(
() => decipher.final(),
/Unsupported state or unable to authenticate data/
);
// 用例 3：CCM 模式必须传入 plaintextLength
const ccmCipher = crypto.createCipheriv('aes-256-ccm', key, iv.slice(0, 12), { authTagLength: 16 });
assert.throws(
() => ccmCipher.setAAD(Buffer.from('aad-without-length')),
/plaintextLength/
);
用例3的异常信息在不同Node.js版本中措辞有差异，核心判断依据是plaintextLength缺失导致setAAD拒绝执行。
四、ERR_CRYPTO_INVALID_STATE的真实触发场景
这个错误码的触发条件比文档描述的更具体。官方定义是“在处于无效状态的对象上使用了加密方法”，示例为cipher.getAuthTag()在cipher.final()之前调用。对于setAAD，无效状态主要包括：
场景一：在update之后调用setAAD。这是最常见的误用。开发者可能先写了cipher.update(plaintext)，后来才想起要设置AAD，此时补救已经来不及。正确顺序是：createCipheriv→setAAD→update→final→getAuthTag。
场景二：在final之后调用setAAD。cipher对象已完成加密流程，任何状态变更都会被拒绝。
场景三：CCM模式下未提供plaintextLength就调用setAAD。部分Node.js版本会抛出ERR_CRYPTO_INVALID_STATE，而非专门的参数错误。处理策略是在调用前用Number.isSafeInteger(plaintextLength)做前置校验，不依赖异常来发现遗漏。
一个项目中的反思：在封装通用加密工具函数时，如果把setAAD设计为可选步骤，调用方很容易忘记在update前执行。更稳妥的设计是把aad和plaintextLength作为加密函数的必填参数，在函数内部强制走正确顺序。牺牲一点调用灵活性，换取状态机不被绕过。
五、与相邻方法的职责边界
| 方法 | 调用时机 | 职责 |
|---|---|---|
cipher.setAAD() |
update之前 |
绑定不加密但需认证的元数据 |
cipher.update() |
setAAD之后 |
加密明文数据，可多次调用 |
cipher.final() |
之后一次update之后 |
完成加密，返回剩余密文 |
cipher.getAuthTag() |
final之后 |
取出认证标签 |
decipher.setAuthTag() |
decipher.update之前 |
设置加密端产生的标签 |
decipher.setAAD() |
decipher.update之前 |
传入与加密端相同的AAD |
setAAD和setAuthTag容易被混淆。前者在加密端和解密端都需要调用，传入的是业务层面的元数据；后者只在解密端调用，传入的是加密端getAuthTag()的输出。加密端不需要（也没有）setAuthTag，解密端不需要getAuthTag。
六、常见误区速查
误区一：setAAD之后可以再次修改AAD。
不能。一个cipher实例的AAD在首次setAAD后即固定。重复调用setAAD不会追加数据，而是触发状态错误或覆盖行为（取决于版本和模式）。需要认证多段元数据时，应在调用前把它们拼接成一个Buffer。
误区二：AAD也会被加密。
AAD全程明文。加密端和解密端各自持有AAD的明文副本，认证标签只保证它未被篡改。如果AAD本身需要保密，应该把它作为普通明文加密，而不是放进AAD。
误区三：GCM模式可以省略plaintextLength，所以不用管。
在GCM中省略plaintextLength通常可以正常工作，但一旦切换到CCM，同样的代码会失败。编写同时支持多算法的封装层时，始终传入plaintextLength是更安全的做法，代价只是一行代码。
误区四：AAD不匹配时decipher.update()就会报错。
实际上，认证失败通常在decipher.final()才抛出。update阶段可能已经返回了部分“解密后”的数据，这些数据在认证失败后必须被丢弃。不要把update的返回值直接写入下游，除非final已经成功执行。
七、性能差异与实测认知
setAAD本身的调用开销极小，真正的性能变量在于AEAD算法的选择和数据尺寸。社区基准测试显示，对于chacha20-poly1305，Node.js的native实现在小载荷（约1KB）上比纯JS库快约1.25倍，但到了4KB及以上，纯JS实现反而略快或持平，差距随尺寸增大而扩大。这说明setAAD的调用位置（在update之前）并不会成为性能瓶颈，算法本身的跨语言调用开销才是需要关注的。
如果业务场景中AAD长度固定且较短（例如16字节的UUID或32字节的协议头），setAAD对整体吞吐的影响可以忽略。真正需要警惕的是在流式加密中每处理一个数据块就重建cipher实例，此时createCipheriv和setAAD的固定开销会累积。正确的做法是复用同一个cipher实例，多次调用update，只在会话开始时执行一次setAAD。
八、补齐：练习思考题与工程惯用写法
练习一：AAD与密文的绑定校验
设计一个函数encryptField(plaintext,fieldName)，要求把fieldName作为AAD绑定到密文上。解密时如果尝试用不同的fieldName解密同一密文，必须失败。写出加密和解密的完整代码，并说明为什么不能把fieldName直接拼接到明文中再加密。
练习二：流式加密中的AAD复用
一个日志加密管道需要持续加密多条记录，每条记录有自己的recordId。现有实现为每条记录都createCipheriv并setAAD(recordId)。请分析这种写法的开销来源，并给出一种在保持每条记录AAD独立的前提下减少cipher创建次数的方案（提示：考虑每条记录独立IV与AAD的关系）。
现在框架中的惯用处理
在TLS库或安全消息队列的Node.js实现中，setAAD的典型写法是把协议头整体作为一个Buffer传入，而不是逐个字段设置：
const header = Buffer.alloc(8);
header.writeUInt32BE(messageId, 0);
header.writeUInt32BE(timestamp, 4);
const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
cipher.setAAD(header, { plaintextLength: Buffer.byteLength(payload) });
const encrypted = Buffer.concat([cipher.update(payload, 'utf8'), cipher.final()]);
const tag = cipher.getAuthTag();
这种做法的好处是AAD的字节序列在编码层面就是确定的，不会因为字段顺序、字符串编码差异导致两端不一致。解密端只要按相同的字节布局重建header，认证就能通过。
九、延伸阅读与参考文献
Node.js 官方文档，cipher.setAAD(buffer[,options])
https://url.nodejs.cn/api/crypto/cipher_setaad_buffer_options.html
最直接的权威来源。明确列出支持的AEAD模式（GCM、CCM、OCB、chacha20-poly1305），以及CCM模式下plaintextLength的强制要求与setAAD必须先于update的时序约束。
Node.js 官方文档，ERR_CRYPTO_INVALID_STATE
https://url.nodejs.cn/api/v26/errors/err_crypto_invalid_state.html
定义了该错误码的含义与典型触发示例（getAuthTag在final之前调用）。对于setAAD的无效状态触发，可结合源码理解其通用模式。
GitHubnodejs/node，crypto:migrateCipherBasetointernal/errors提交
https://github.com/nodejs/node/commit/e567402aba903f7d828d428f1f5738bbf884636c
保留了setAAD在C++绑定层返回false时抛出ERR_CRYPTO_INVALID_STATE的实现痕迹，可用于追溯异常来源。
GeeksforGeeks，Node.jscipher.setAAD()Method
https://www.geeksforgeeks.org/node-js/node-js-cipher-setaad-method/
提供了AES-256-GCM下设置AAD并完成加密解密的完整示例，适合快速验证基本用法。注意其示例未覆盖CCM的plaintextLength特殊情况。
GitHubdenoland/denoIssue#33101，node:cryptochacha20-poly1305性能对比
https://github.com/denoland/deno/issues/33101
包含使用setAAD的基准测试代码，展示了不同载荷尺寸下native实现与纯JS实现的吞吐差异，对评估AAD在流式场景中的实际开销有参考价值。
Node.jsGitHub仓库，crypto.md历史版本（含decipher.setAAD变更记录）
https://raw.githubusercontent.com/nodejs/node/57d2e4881c9a7f9ac52d49d19d781dc455b2789d/doc/api/crypto.md
记录了decipher.setAAD在v15.0.0中buffer参数支持字符串和ArrayBuffer的变更，以及buffer参数长度限制为不超过2^31-1字节的历史约束。
