本文详解如何使用 pointycastle 库在 dart 中实现与 javascript（sjcl）完全兼容的 aes-ccm 加密，涵盖密钥/iv/ad 解码、参数配置、标签长度处理及安全实践。
本文详解如何使用 pointycastle 库在 dart 中实现与 javascript（sjcl）完全兼容的 aes-ccm 加密，涵盖密钥/iv/ad 解码、参数配置、标签长度处理及安全实践。
AES-CCM（Counter with CBC-MAC）是一种标准化的认证加密模式，广泛用于资源受限环境（如物联网设备），但其与更常见的 AES-GCM 在算法结构、参数语义和输出格式上存在本质差异。许多开发者在迁移 JavaScript（如使用 Stanford JS Crypto Library）代码至 Dart 时，误用 cryptography 包中的 AesGcm——该类仅支持 GCM 模式，无法替代 CCM，导致加密结果不一致甚至运行时异常（例如密钥长度校验失败）。
关键差异在于：
- 模式不匹配：JS 示例明确调用 sjcl.mode.ccm.encrypt，而 Dart 原始代码使用 AesGcm，二者底层算法（CTR+CBC-MAC vs. CTR+GHASH）和认证标签生成逻辑完全不同；
- 输入编码错误：原始 Dart 代码将十六进制字符串（如 "6dbe8f..."）直接 utf8.encode()，实际应进行 hex 解码 转为字节序列；
- 密钥长度不符：256-bit AES 要求密钥为 32 字节，而 "6dbe8f8c87d58e61c2ec29321f42e9ff" 是 32 字符 hex 字符串，解码后恰为 16 字节（对应 AES-128）。JS 代码中 sjcl.cipher.aes(...) 自动适配密钥长度，Dart 需显式匹配——此处应使用 AES-128。
✅ 正确方案：采用 pointycastle 库（Pub.dev 官方推荐密码学基础库），它完整支持 CCM 模式，并提供精细的 AEAD 参数控制。
✅ 步骤实现（Dart）
首先添加依赖（pubspec.yaml）：
dependencies: pointycastle: ^3.9.0 convert: ^3.1.0
然后编写兼容性加密代码：
import 'package:pointycastle/export.dart';
import 'dart:typed_data';
import 'package:convert/convert.dart';
void main() async {
// ✅ 正确 hex 解码（非 utf8.encode！）
final key = Uint8List.fromList(hex.decode("6dbe8f8c87d58e61c2ec29321f42e9ff")); // 16 bytes → AES-128
final nonce = Uint8List.fromList(hex.decode("101112131415161718191A1B")); // 12 bytes IV
final aad = Uint8List.fromList(hex.decode("6465764944")); // Additional Authenticated Data
final plaintext = Uint8List.fromList(hex.decode("00626c742e332e3132397649356b744455415443"));
// ? 初始化 CCM 加密器（AES-128）
final cipher = CCMBlockCipher(AESEngine());
final params = AEADParameters(
KeyParameter(key),
32, // tagLength: 32 bits = 4 bytes（与 JS 的第 5 参数一致）
nonce,
aad,
);
cipher.init(true, params);
// ? 输出格式：ciphertext || tag（JS/SJCL 默认行为）
final ciphertextWithTag = cipher.process(plaintext);
print('Result (hex): ${hex.encode(ciphertextWithTag)}');
// 输出: a2bbe65fcc7d13a8aeef2309055c3e2d24cd2f07bd2265cc
// 其中末尾 4 字节 '65cc' 是 32-bit 认证标签
}⚠️ 重要注意事项
- 标签长度（Tag Length）：JS 代码中 ccm.encrypt(..., 32) 明确指定 32-bit（4 字节）标签。RFC 3610 强烈建议最小使用 64-bit（8 字节）标签以保障安全性。生产环境请改用 tagLength: 64 并同步调整 JS 端。
- IV/Nonce 安全性：示例中 IV 是静态值，绝不可用于生产。每次加密必须使用密码学安全的随机数生成器（如 Random.secure()）生成唯一 nonce，并与密文一同传输（通常前置拼接）。
- 密钥管理：确保密钥保密且长度匹配算法（AES-128 → 16 字节，AES-192 → 24 字节，AES-256 → 32 字节）。hex 字符串需严格解码，避免长度误判。
- 解密验证：CCMBlockCipher.process() 在解密时自动校验标签，若篡改密文或 AAD，将抛出 InvalidCipherTextException，无需手动验证。
通过以上实现，Dart 输出将与 SJCL JavaScript 完全一致，真正达成跨语言 AES-CCM 互操作。记住：模式匹配、编码一致、参数对齐，是认证加密迁移成功的三大基石。
