企业官网建设流程全解析

CANN Crypto 快速上手：5 分钟跑通昇腾 NPU 上的第一个密码算子

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

CANN Crypto（cann/crypto）是 CANN 中面向密码计算的算子与算法库，围绕昇腾 NPU 提供国密（SM2、SM3、SM4）与国际主流算法（AES、SHA-2/3、X25519、ML-KEM 等）的高性能实现。本文是一份面向新手的 CANN Crypto 快速上手指南：只需 5 个步骤，你就能在昇腾 NPU 上编译并运行自己的第一个密码算子，并学会验证结果是否正确。

一、为什么密码计算要跑在昇腾 NPU 上？

CPU 做密码计算已经足够快，但 CANN Crypto 解决的是 CPU 难以覆盖的两类场景：

• 设备驻留数据就地保护：数据已经放在 NPU 显存里，不必拷回主机加密再拷回去，减少一次昂贵的数据搬运；
• 批量密码计算卸载：大批量消息（如海量文件指纹、批量哈希）放到 NPU 并行执行，吞吐量更高。

项目按「数学引擎 → 密码原语 → 算法服务」三层组织，下层能力可被多个算法族复用，例如 SHAKE 算子就复用了 Keccak-f[1600] 原语。架构细节可参考 src 目录说明。

二、环境准备：安装 NPU 驱动与 CANN 软件包

跑通密码算子前，先确认两件事：

1. 机器上已有昇腾 NPU 设备，并安装了配套的 NPU 驱动；
2. 已安装 CANN 软件包（CANN 版本需与源码标签配套，设备验证基线为 CANN 9.1.0）。

💡 没有本地设备？可以使用社区提供的 CANNLab 在线环境，其中已预置配套 CANN 环境，开箱即用。

部分组件（如 AES PyTorch 扩展）还依赖torch与torch_npu，具体依赖以各组件的requirements.txt为准，例如 src/primitives/AES/requirements.txt。

三、下载 CANN Crypto 源码

执行以下命令克隆仓库（${tag_version}换成与你 CANN 版本配套的标签）：

git clone -b ${tag_version} https://gitcode.com/cann/crypto.git

说明：若环境中已有配套分支源码，可跳过本步骤。版本对应关系见仓库根目录 README.md 的「版本配套」章节。

四、编译第一个密码算子：一行命令搞定

仓库根目录的 build.sh 是统一的构建入口，组件通过src下的二级目录自动发现，无需手动修改构建脚本。

编译全部组件：

bash build.sh --pkg

只编译指定组件（推荐新手起步）：以 AES 原语为例：

bash build.sh --components=primitives/AES --pkg

编译完成后再跑单元测试，确认环境正常：

bash build.sh -u --opkernel # op_kernel 层，需要昇腾设备

分层测试策略：--ophost、--opapi层不需要设备，--opkernel层才需要 NPU，新手可按此顺序逐层验证。

五、运行示例：让 NPU 算出第一个密码结果

方式 A：Python 调用 AES-128-CTR（最直观）

AES 组件提供了 PyTorch 算子扩展，安装后直接运行样例：

cd src/primitives/AES/examples python3 aes128_ctr_example.py

样例 aes128_ctr_example.py 会在 NPU 上对 RFC 3686 标准测试向量做加密，并自动比对密文。看到输出AES-128-CTR example: PASS，就说明你的昇腾 NPU 已成功完成第一个密码算子！

方式 B：C++ 调用 SHAKE128 哈希算子

如果偏好 C++ 接口，SHAKE 算子提供了一个完整的 aclnn 调用样例 test_aclnn_shake_tensor.cpp，它演示了标准两步调用流程：

1. aclnnShake128TensorGetWorkspaceSize—— 查询工作空间大小、生成执行器；
2. aclnnShake128Tensor—— 把计算提交到指定流，同步后读取结果。

接口参数与约束的完整说明见 aclnnShake128Tensor.md。运行样例输出SHAKE128 example: PASS即表示成功。

六、结果不对或编译失败？常见排查点

七、继续探索：项目关键模块路径

跑通第一个算子后，推荐按以下路径深入：

• 📂算法样例：examples/ —— 每个算法族一个最小可运行样例，只依赖公开接口；
• 📂密码原语：src/primitives/ —— AES、SM4、Keccak-f 等基础原语；
• 📂参考实现：reference/ —— 零 CANN 依赖的纯 C 实现，作为正确性基准；
• 📂辅助脚本：scripts/ —— 测试向量获取、依赖检查等；
• 📖接口文档：各算子目录下docs/均有参数、约束与调用示例，如 aclnnKeccakF1600Tensor.md；
• 🤝参与贡献：先阅读 CONTRIBUTING.md 了解交付件要求与评审规则。

⏱️ 回顾一下完整路径：环境检查 → clone 源码 →build.sh --pkg编译 → 运行 AES/SHAKE 样例 → 看到 PASS。整个过程约 5 分钟，你已在昇腾 NPU 上完成了第一个密码算子。祝探索愉快！

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