CANN Crypto 架构设计揭秘：分层依赖如何让密码算子高效复用

【免费下载链接】cryptocrypto SIG 是密码学兴趣小组，围绕昇腾 NPU 打造高性能密码软件库，提供丰富的密码算子与算法实现项目地址: https://gitcode.com/cann/crypto

CANN Crypto 是 CANN（Compute Architecture for Neural Networks）中面向昇腾 NPU的密码学算子与算法库，提供 AES、SM2/SM3/SM4、SHA-2/3、ML-KEM、ML-DSA 等丰富的密码算子与算法实现。它的核心设计思想是分层依赖：按数学引擎、密码原语、算法服务三层组织代码，依赖只能向下流动，让下层能力被多个算法族复用——这正是"密码算子高效复用"的关键。本文用一次清晰的架构拆解，带你快速看懂这套设计。

一张图看懂 CANN Crypto 分层依赖

先看整体目录与依赖方向（箭头一律向下，绝不回头）：

include/cann_crypto/ 对外稳定 C ABI（唯一承诺兼容性的边界） │ src/api/ ABI 校验、句柄/plan 生命周期、算法分发 │ src/core/ 运行时：handle / stream / workspace / 密钥管理 │ src/algorithms/ 算法服务：digest / aead / mac / kdf / signature / kem │ src/primitives/ 密码原语：AES、SM4、Keccak-f、ChaCha、GHASH、EC │ src/math/ 数学引擎：大数模乘、NTT/RNS、GF(2^k)、位平面转置 │ reference/ 纯 C 参考实现（零 CANN 依赖，正确性基准）

分层规则写在根 README 中，非常明确：

分层依赖只能向下：algorithms/与primitives/不实现数学运算，需要时下沉到math/；算法族之间不互相依赖。 —— README.md

每层职责拆解：从 C ABI 到数学引擎

每一层都有各自的 README.md 说明职责与约束。下面逐层说明它们"做什么"和"不做什么"。

1️⃣ include + api：唯一的兼容边界

• 对外接口是纯 C ABI：不出现 C++ 类型、异常、模板，公共描述符带structSize/version字段，保证 ABI 可平滑演进，见 include/cann_crypto/README.md。
• src/api/ 负责边界校验（空指针、版本、缓冲区重叠等）、句柄与 plan 生命周期管理，并按算法枚举分发到algorithms/。
• 关键点：算法特有的参数校验（密钥、nonce、tag 长度）不在这里重复，而是下沉到各算法的op_host/，避免一处改、处处漏。

2️⃣ core：所有算法族共用的"控制面"

src/core/ 提供所有算法族共享的运行时能力：

约束只有一条但很硬：不依赖任何具体算法。这样新算法接入时无需改动运行时。

3️⃣ math：被所有算法族共享的数学引擎

src/math/ 是整个复用体系的"地基"：

• 大数与模运算（Montgomery、Barrett）
• NTT / INTT / RNS（后量子密码的命脉）
• GF(2^k) 域运算（对称密码的土壤）
• 位平面转置、面向 Cube 单元的限位整数卷积

两条铁律：本目录有单一 owner；primitives/与algorithms/不得自行实现本目录已覆盖的运算。这就是复用能发生的根本原因——数学只写一遍。

4️⃣ primitives：密码原语层

src/primitives/ 存放算法内核：AES、SM4、Keccak-f、ChaCha、GHASH、Poly1305、EC 点运算等。

值得注意的设计决策：这些原语单独使用并不构成完整的安全服务（比如 GHASH 本身不是 MAC），因此不对最终用户默认暴露。它是"给上层算法用的零件"，而非"给用户用的产品"。

5️⃣ algorithms：只做组合与调度

src/algorithms/ 提供语义完整的密码服务，按digest/aead/mac/kdf/signature/kem等算法族分目录。约束是：

• 只做组合、参数校验与调度，不实现数学运算；
• 算法族之间不得互相依赖，需要共用能力时下沉到primitives/或math/。

复用如何发生？3 个真实例子

分层架构的价值，体现在"写一次、用多处"。以仓库中已有的代码为例：

🔄 例 1：Keccak-f 一个原语，撑起两个算法

Keccak-f[1600] 置换实现位于 src/primitives/keccak/，而 SHAKE128 / SHAKE256 两个 XOF 算子位于 src/algorithms/hash/shake/。算法服务层只负责"吸挤（squeeze）"的调度与输出长度控制，置换本体零重复——同族再加 SHA3-256 时，新增的只是薄薄一层组合。

🔄 例 2：NTT 引擎服务整个后量子密码族

src/math/ntt/ 提供完整的 NTT/RNS 数学引擎，且自带 CANN 算子适配（见 ntt_adapter.h）。ML-KEM、ML-DSA 这类基于多项式环的算法全部复用同一套数论变换实现，而不是各自造轮子。

🔄 例 3：AES 模式扩展 = 原语组合

src/primitives/AES/ 下 CTR 与 GCM 两条模式线，分别复用 AES 分组加密内核；GCM 再叠加 GHASH 原语。对称密码新模式的成本被压缩到"组合逻辑"级别。

算子内部三层协作：op_api / op_host / op_kernel

宏观分层解决"算法间"的复用，每个算子内部还有一套与 CANN 算子仓一致的微观分层：

<alg>/ ├── <alg>_internal.h # 中性类型内部接口，原生 API 与 aclnn 入口共用 ├── <alg>_launch.cpp # kernel 组合与变体选择 ├── op_api/ # aclnn 两段式入口 ├── op_host/ # 算子定义、infershape、tiling ├── op_kernel/ # Ascend C 实现 └── tests/

以一个真实算子为例，shake 算子目录 中的分工是：

这个"中性接口"细节很妙：同一份 tiling 逻辑同时服务两种调用入口，从机制上杜绝了两份实现漂移分叉。

正确性如何兜底：reference 独立基准

高性能设备端代码最怕"算错了还跑得欢"。reference/ 目录放各算法的纯 C 参考实现，三条约束保证它是独立 oracle：

1. 只求显然正确，不做任何优化；
2. 零 CANN 依赖，无设备机器也能单独编译；
3. 不得 includesrc/下任何文件——一旦与被测实现共享代码，就不再是独立基准。

tests/host/的差分测试以它为基准（例如 golden.py），KAT 与差分测试因此能进 PR 门禁。这是"分层 + 独立基准"组合在工程上的完整闭环。

给新手的分层开发速查表 ✍️

写新代码前，先问自己"我属于哪一层"：

更多贡献规范见 CONTRIBUTING.md，各层职责以目录内 README 为准。

小结

CANN Crypto 的分层依赖可以浓缩成三句话：

1. 依赖只向下：算法 → 原语 → 数学，永不回头；
2. 能力下沉复用：数学引擎单一 owner，原语跨算法族共享；
3. 边界清晰可信：C ABI 是唯一兼容承诺，reference 是独立正确性基准。

理解了这套结构，你就能快速判断任何新密码算子该落在哪一层、复用什么、避免什么重复实现——这正是这套架构能持续高效扩展的底层原因。

【免费下载链接】cryptocrypto SIG 是密码学兴趣小组，围绕昇腾 NPU 打造高性能密码软件库，提供丰富的密码算子与算法实现项目地址: https://gitcode.com/cann/crypto