对称加解密与哈希开发指南
本文档以 security_demo_cipher_hash.c 为例，介绍在 HiDiTing 开发板上实现 AES-GCM 加解密与 SHA-256 摘要计算的开发流程，以及 Security Unified 对称加解密和哈希接口的使用方法。
配套 Demo 可直接参与 pack_diting_community 构建。示例包含标准向量自检、Tag 篡改测试和结果汇总，用于验证正确输入的计算结果，并确认驱动能够拒绝认证失败的数据。
对称加解密与哈希背景知识
对称加密使用同一份密钥完成加密和解密，适合处理数据量较大的场景。HASH 将任意长度输入映射为固定长度摘要，主要用于完整性校验，不能从摘要恢复原文。
硬件加密与软件加密
| 对比项 | 硬件安全引擎 | 纯软件实现 |
|---|---|---|
| 运算位置 | 独立安全硬件模块 | CPU 执行算法指令 |
| CPU 占用 | 较低 | 随数据量增大 |
| 密钥使用 | 可结合 Keyslot，减少明文密钥暴露 | 通常需要在普通内存中展开密钥 |
| 适用场景 | 固件校验、日志加密、通信报文、安全存储 | 小数据、兼容性回退、硬件不支持的算法 |
| 注意事项 | 受芯片能力、对齐、通道和配置约束 | 受 CPU 性能和侧信道防护质量影响 |
说明： Security Unified 同时提供单次接口和分段接口。小数据优先使用单次接口；流式数据或大数据优先使用 Start/Update/Finish 形式，避免一次性占用过多内存。
加密与 HASH 的区别
| 能力 | 输入 | 输出 | 是否可逆 | 典型用途 |
|---|---|---|---|---|
| AES/SM4 加密 | 明文、密钥、IV/Nonce | 密文 | 使用正确密钥可逆 | 数据保密 |
| AES-GCM | 明文、密钥、Nonce、AAD | 密文、Tag | 可逆且可认证 | 同时保护机密性和完整性 |
| SHA-256/SM3 | 任意数据 | 固定长度摘要 | 不可逆 | 完整性校验、签名前摘要 |
HASH 本身不提供身份认证。攻击者如果能同时替换数据和摘要，普通 HASH 无法发现该替换。需要认证能力时，应使用 AES-GCM、HMAC 或数字签名。
算法与工作模式
HiDiTingV100 LiteOS 安全配置中启用了 AES/SM4 对称算法所需的 ECB、CBC、CTR、OFB、CFB、CCM、GCM 等能力，并启用了 SHA-224、SHA-256、SHA-384、SHA-512 和 SM3。实际可用能力以芯片配置文件和接口返回值为准。
| 算法或模式 | 特点 | 建议 |
|---|---|---|
| AES-GCM | 同时生成密文和认证 Tag | 新设计优先使用 |
| AES-CCM | 认证加密，适合部分受限协议 | 按协议要求使用 |
| AES-CTR | 不要求分组对齐，但不自带认证 | 必须额外提供完整性保护 |
| AES-CBC | 需要正确填充和完整性保护 | 兼容既有协议时使用 |
| SM4 | 国密对称算法 | 按项目合规要求使用 |
| ECB | 相同明文块产生相同密文块 | 不建议使用 |
| SHA-256 | 32 字节摘要，生态成熟 | 通用完整性校验优先使用 |
| SM3 | 32 字节国密摘要 | 按国密合规要求使用 |
| SHA-1/SHA-224 | 安全裕量不足或不符合新项目要求 | 新设计不建议使用 |
安全目标与能力边界
使用密码接口前，应明确待保护资产和安全目标，不能仅以“已经加密”作为系统满足安全要求的依据。
| 安全目标 | 本文能力 | 仍需配套的机制 |
|---|---|---|
| 机密性 | AES/SM4 加密可降低明文泄露风险 | 安全密钥生成、存储、轮换和访问控制 |
| 完整性 | AES-GCM/CCM 的 Tag 可检测密文和 AAD 篡改 | 正确处理认证失败，禁止使用未认证明文 |
| 数据摘要 | SHA-256/SM3 可生成固定长度摘要 | 需要身份认证时使用 HMAC 或数字签名 |
| 防重放 | 不直接提供 | 协议中加入计数器、序列号、时间窗或挑战值 |
| 端点身份 | 不直接提供 | 证书、预共享密钥、数字签名或安全配网 |
| 固件可信 | 不由普通数据加密接口保证 | 安全启动、签名校验和防回滚方案 |
以下做法不能形成完整安全方案：
- 只加密、不认证。
- 使用固定密钥和固定 Nonce。
- 只比较 HASH，不验证摘要来源。
- Tag 校验失败后继续处理输出缓冲区。
- 将接口调用成功等同于产品已经满足安全目标。
模块设计
Security Unified 采用分层架构。应用通过 src/include/driver/security_unified 中的统一接口访问 Service Layer，并依次经过 KAPI/Driver、HAL 和 3322 芯片适配层访问硬件安全引擎。系统在启动阶段完成安全环境初始化，应用不应重复初始化或反初始化全局安全环境。
主要代码位置如下：
| 层级 | 代码位置 | 作用 |
|---|---|---|
| 对外接口 | src/include/driver/security_unified/security_symc.h | 对称加解密、CCM、GCM |
| 对外接口 | src/include/driver/security_unified/security_hash.h | SHA/SM3 单次及分段计算 |
| 服务层 | src/drivers/drivers/driver/security_unified/service_layer | 参数封装和简化接口 |
| 驱动层 | src/drivers/drivers/driver/security_unified/drv_code | 上下文、通道及算法驱动 |
| HAL | src/drivers/drivers/hal/security_unified | 硬件寄存器抽象 |
| 芯片适配 | src/drivers/chips/3322/porting/security_unified | Hi3322 能力和环境配置 |
参数与配置说明
HiDiTingV100 LiteOS 配置文件 security_unified_config_liteos.h 已定义下列能力宏：
| 配置 | 作用 |
|---|---|
CONFIG_SECURITY_UNIFIED_SUPPORT_SYMC |
使能对称加解密模块 |
CONFIG_SYMC_SUPPORT_GCM |
使能 GCM |
CONFIG_SECURITY_UNIFIED_SUPPORT_HASH |
使能 HASH |
CONFIG_HASH_SUPPORT_SHA256 |
使能 SHA-256 |
diting-community 目标已经增加 CONFIG_ENABLE_SECURITY_SAMPLE，并在 samples/native_samples/CMakeLists.txt 中按该开关加入 security 子目录；目标组件列表同时加入 security_sample。如果将 Demo 移植到其他目标，需要同步完成这三处接入。
AES-GCM 建议测试参数：
| 参数 | 建议值 | 说明 |
|---|---|---|
| 算法 | AES | 通用项目优先 |
| 密钥长度 | 16 或 32 字节 | 分别对应 AES-128/AES-256 |
| Nonce 长度 | 12 字节 | GCM 常用长度 |
| Tag 长度 | 16 字节 | 不建议无依据截短 |
| AAD | 命令头、版本号等无需加密但需要认证的数据 | 解密端必须完全一致 |
| Keyslot | 本示例使用 UAPI_DRV_INVALID_KEY_SLOT |
Keyslot 用法见密钥指南 |
警告： 同一把 GCM 密钥下不得重复使用 Nonce。Nonce 重用会破坏 GCM 的机密性和完整性保证。
API 接口列表
AES-GCM 单次接口
| 接口函数 | 说明 |
|---|---|
| uapi_drv_cipher_symc_gcm_encrypt | 使用 AES/SM4 GCM 加密并生成 Tag |
| uapi_drv_cipher_symc_gcm_decrypt_verify | 解密密文并校验 Tag |
AES-GCM 分段接口
| 接口函数 | 说明 |
|---|---|
| uapi_drv_cipher_symc_gcm_setup | 创建 GCM 上下文 |
| uapi_drv_cipher_symc_gcm_update_ad | 输入一段或多段 AAD |
| uapi_drv_cipher_symc_gcm_update | 输入一段或多段明文/密文 |
| uapi_drv_cipher_symc_gcm_finish | 完成运算并获取 Tag |
| uapi_drv_cipher_symc_gcm_teardown | 销毁 GCM 上下文 |
SHA-256 接口
| 接口函数 | 说明 |
|---|---|
| uapi_drv_cipher_sha256 | 单次计算 SHA-256 |
| uapi_drv_cipher_sha256_start | 创建 SHA-256 上下文 |
| uapi_drv_cipher_sha256_update | 更新一段消息 |
| uapi_drv_cipher_sha256_finish | 完成计算并输出 32 字节摘要 |
| uapi_drv_cipher_sha_destroy | Finish 后或异常退出时销毁 HASH 上下文 |
说明： 接口定义和参数约束以 HiDiTingV100 API Reference、
security_symc.h和security_hash.h为准。
快速跑通加解密与哈希 Demo
功能说明
配套示例通过 AT 命令分别验证 AES-GCM 和 SHA-256：
| 命令 | 作用 |
|---|---|
AT+SECAESGCM |
加密固定测试向量、正确解密、篡改 Tag 后确认校验失败 |
AT+SECHASH |
分别执行 SHA-256 单次计算和分段计算，并与标准摘要比较 |
示例使用公开测试向量，不涉及生产密钥。仅当接口返回成功且输出与预期向量完全一致时，测试结果才显示 PASS。
操作流程
编译
完成一站式 CLI 环境配置后执行：
构建成功后，使用一站式 CLI 烧写固件并打开 UART2 串口监视器。以下为 Windows USB DFU 示例；将 COM3 替换为实际日志串口，其他平台和串口烧写参数参见一站式 CLI 开发环境使用指南。
fbb flash -f "$env:FBB_SDK_DIR\output\3322\fwpkg\diting-community.fwpkg" --chip 3322 -d --timeout 180
fbb monitor --port COM3 --baud 750000
预期固件路径：
说明： 本文示例命令以一站式 CLI 为主。实际开发可从以下三种环境中选择，推荐使用一站式 CLI。
| 开发环境 | 适用场景 | 使用指南 |
|---|---|---|
| 一站式 CLI（推荐） | 快速完成目标选择、构建、烧录和串口监视 | 一站式 CLI 开发环境使用指南 |
| HiSpark Studio for VS Code | 图形化编辑、编译、烧录和调试 | HiSpark Studio for VS Code 开发环境使用指南 |
| WSL 与 Docker | 在 Windows 上使用一致的 Linux 容器构建环境 | WSL 与 Docker 环境使用指南 |
使用方式
- 烧录
diting-community.fwpkg并复位开发板。 - 打开串口监视器。
- 执行
AT+SECAESGCM。 - 执行
AT+SECHASH。 - 保存完整日志和接口返回码。
也可以执行 AT+SECDEMOALL 一次运行 AES-GCM、HASH、PKE、密钥管理和 mbed TLS 五组示例。命令返回 OK，五项汇总均为 PASS，且最后出现 [SEC][ALL] PASS 才表示全部示例通过。
验证说明： Demo 已完成
diting-community目标的完整编译、最终 ELF 链接及固件 BIN 生成验证。
预期结果
[SEC][AES-GCM] start
[SEC][PASS] AES-GCM encrypt
[SEC][PASS] AES-GCM ciphertext vector
[SEC][PASS] AES-GCM tag vector
[SEC][PASS] AES-GCM decrypt and verify
[SEC][PASS] AES-GCM restored plaintext
[SEC][PASS] AES-GCM tampered tag rejected, ret=0x........
[SEC][AES-GCM] PASS
OK
[SEC][HASH] start
[SEC][PASS] SHA-256 one-shot
[SEC][PASS] SHA-256 one-shot vector
[SEC][PASS] SHA-256 start
[SEC][PASS] SHA-256 update
...
[SEC][PASS] SHA-256 finish
[SEC][PASS] SHA-256 multipart vector
[SEC][PASS] SHA-256 destroy
[SEC][HASH] PASS
OK
其中 0x........ 代表平台返回的实际认证失败错误码；该步骤返回失败是预期行为，示例会将“成功拒绝篡改 Tag”判定为 PASS。
出现以下任一情况时必须判定 FAIL：
- 接口返回非
ERRCODE_SUCC。 - AES-GCM 密文或 Tag 与标准向量不同。
- 正确 Tag 无法解密。
- 被篡改的 Tag 仍被接受。
- SHA-256 摘要与标准向量不同。
- 单次计算和分段计算结果不同。
文件结构与代码走读
文件结构
配套代码统一放置在 samples/native_samples/security，并按命令入口、功能实现和公共检查函数分层，便于按功能查阅和复用：
samples/native_samples/security/
├── CMakeLists.txt
├── security_demo.c
├── security_demo.h
├── security_demo_cipher_hash.c
├── security_demo_pke.c
├── security_demo_key.c
├── security_demo_mbedtls.c
├── security_demo_utils.c
├── security_demo_utils.h
└── README.md
各文件职责
| 文件 | 职责 |
|---|---|
| /samples/native_samples/security/security_demo.c | 注册六条安全示例 AT 命令并汇总执行结果：SECAESGCM、SECHASH、SECPKE、SECKEY、SECMBEDTLS、SECDEMOALL |
| /samples/native_samples/security/security_demo_cipher_hash.c | AES-GCM、SHA-256 正向和负向自检 |
| /samples/native_samples/security/security_demo_mbedtls.c | 通过 mbed TLS 公共接口执行 SHA-256 标准向量自检 |
| /samples/native_samples/security/security_demo_utils.c | 统一打印 PASS/FAIL、比较结果和安全清零 |
| /samples/native_samples/security/CMakeLists.txt | 定义 security_sample 构建组件 |
代码走读
本节结合 /samples/native_samples/security/security_demo_cipher_hash.c 说明接口调用顺序。示例中的固定密钥、Nonce 和消息均为公开测试向量，仅用于功能自检。
AES-GCM 实现步骤
- 包含
security_unified/security_symc.h和公共错误码头文件。 - 准备公开的 AES-GCM 测试向量，包括密钥、Nonce、明文、期望密文和期望 Tag。当前示例不使用 AAD，接口对应参数传入
NULL, 0。 - 调用
uapi_drv_cipher_symc_gcm_encrypt，检查返回值。 - 比对密文和 Tag。Demo 的
security_demo_expect_bytes仅用于公开测试向量；业务代码比较秘密认证值时应使用经过审计的常量时间比较函数。 - 调用
uapi_drv_cipher_symc_gcm_decrypt_verify，检查返回值并比对恢复的明文。 - 复制并修改一个 Tag 字节，再次调用解密接口。只有接口拒绝篡改数据时，该项测试才通过。
- 使用安全清零函数清理测试密钥和中间缓冲区。
概念性调用顺序如下：
ret = uapi_drv_cipher_symc_gcm_encrypt(
UAPI_DRV_CIPHER_SYMC_ALG_AES,
key, key_len, UAPI_DRV_INVALID_KEY_SLOT,
nonce, nonce_len,
aad, aad_len,
plain, cipher, plain_len,
tag, tag_len);
ret = uapi_drv_cipher_symc_gcm_decrypt_verify(
UAPI_DRV_CIPHER_SYMC_ALG_AES,
key, key_len, UAPI_DRV_INVALID_KEY_SLOT,
nonce, nonce_len,
aad, aad_len,
cipher, restored, plain_len,
tag, tag_len);
SHA-256 单次计算
- 准备消息和 32 字节输出缓冲区。
- 调用
uapi_drv_cipher_sha256。 - 检查返回值后再比较摘要。
- 与标准测试向量比较并打印结果。
SHA-256 分段计算
- 调用
uapi_drv_cipher_sha256_start创建上下文。 - 按数据到达顺序多次调用
uapi_drv_cipher_sha256_update。 - 调用
uapi_drv_cipher_sha256_finish输出摘要。 - 无论 Finish 成功还是前序步骤失败，只要上下文创建成功，都调用
uapi_drv_cipher_sha_destroy释放资源。 - 分段结果必须与对相同消息执行单次计算的结果一致。
hash_handle_t ctx;
ret = uapi_drv_cipher_sha256_start(&ctx);
ret = uapi_drv_cipher_sha256_update(ctx, part1, part1_len);
ret = uapi_drv_cipher_sha256_update(ctx, part2, part2_len);
ret = uapi_drv_cipher_sha256_finish(ctx, digest);
基于安全 Demo 开发应用
配套 Demo 可以通过 AT 命令触发板端回归，但自定义安全应用应从业务任务或服务直接调用安全接口或可复用的运行函数，并为新增算法补充标准向量、异常处理和敏感数据清理逻辑。
代码清单
- 新增或修改示例源文件
- 补充函数声明与编译配置
- 从业务任务或服务调用运行函数并处理结果
- 增加标准测试向量
- 增加负向测试与资源释放路径
- 如需串口回归，再注册独立 AT 命令（可选）
CMakeLists.txt 修改示例
在上层 samples/native_samples/CMakeLists.txt 中按功能宏加入示例目录：
在目标 config.py 中添加 CONFIG_ENABLE_SECURITY_SAMPLE，并将 security_sample 加入目标组件列表。
关键代码片段
以下代码展示业务入口直接复用现有自检函数的基本方式：
扩展建议：
开发阶段与量产阶段的安全目标不同，应分别制定密钥、日志和验收要求。
| 项目 | 开发验证 | 量产要求 |
|---|---|---|
| 输入数据 | 公开标准测试向量 | 业务协议数据和边界条件 |
| 密钥 | 固定公开测试密钥 | 每设备或每密钥域独立生成和管理 |
| Nonce/IV | 为复现测试可使用固定向量 | 按协议保证唯一性或不可预测性 |
| 日志 | 可打印公开向量和阶段信息 | 禁止打印密钥、敏感明文和完整认证材料 |
| 失败处理 | 打印阶段与错误码 | 拒绝数据、清理状态、记录脱敏审计信息 |
| 验收 | 正向向量 + 篡改测试 | 威胁建模、互操作、异常掉电、升级和长期运行测试 |
量产前至少确认：
- 已明确数据资产、攻击面和失败后的安全状态。
- 已确定密钥来源、轮换、吊销和设备返修策略。
- AES-GCM Nonce 在密钥生命周期内不会重复。
- 所有认证失败路径都会拒绝数据。
- 使用的 SDK 版本已包含项目要求的安全修复。
- 调试日志和测试密钥不会进入量产镜像。
测试验证
完成一站式 CLI 环境配置后执行：
# 编译固件，编译生成的固件从 output/3322/fwpkg 中获取 diting-community.fwpkg
fbb set-target pack_diting_community
fbb build
- 烧录固件并启动设备。
- 从业务任务或测试任务调用
security_demo_run_aes_gcm()、security_demo_run_hash()或自定义运行函数。 - 保存函数结果、错误码和必要的脱敏日志。
- 确认所有正向检查通过，并且篡改输入被拒绝。
- 需要板端串口回归时，可选用配套 AT 命令触发同一运行函数。
注意事项
- 新设计优先选择 AES-GCM 或 AES-CCM 等认证加密模式。
- 禁止在同一密钥下重复使用 GCM Nonce。
- 不得使用 ECB 保护结构化业务数据。
- CBC/CTR 不自带完整性保护，必须结合可靠的 MAC 或签名机制。
- 不得将 HASH 用作加密，也不得将普通 HASH 用作身份认证。
- 不得在日志中输出产品密钥、派生密钥或完整的敏感明文。
- 认证失败后不得使用解密缓冲区中的数据。
- 分段上下文必须成对创建和结束；异常路径也必须释放资源。
- 示例中的固定密钥仅用于测试向量，不能进入量产固件。
- 系统已负责全局安全环境初始化，应用不得擅自调用全局反初始化接口。
常见编译错误
错误码解析
Security Unified 组合错误码由运行环境、软件层级、功能模块和具体错误类型组成，定义位于 /src/drivers/drivers/hal/security_unified/include/common_include/crypto_errno.h：
31 28 27 24 23 20 19 8 7 0
+----------------+----------------+----------------+----------------+----------------+
| ENV（4 bit） | LAYER（4 bit） | MODULE（4 bit）| Reserved | Error Code |
| | | | （12 bit） | （8 bit） |
+----------------+----------------+----------------+----------------+----------------+
env = (error >> 28) & 0xF;
layer = (error >> 24) & 0xF;
module = (error >> 20) & 0xF;
error_code = error & 0xFF;
常用字段取值如下：
| 字段 | 值 | 含义 |
|---|---|---|
| ENV | 0x1/0x2/0x3 | Linux/iTrustee/OP-TEE |
| ENV | 0x4/0x5/0x6 | LiteOS/SELiteOS/无 OS |
| ENV | 0x7/0x8 | FreeRTOS/AliOS |
| LAYER | 0x1/0x2 | UAPI/Dispatch |
| LAYER | 0x3/0x4/0x5 | KAPI/Driver/HAL |
| MODULE | 0x1 | SYMC 对称加解密模块 |
| MODULE | 0x2 | HASH、HMAC 和 KDF 模块 |
例如，0x41200001 表示 LiteOS 环境下，HASH 模块的 UAPI 层检测到无效参数。应优先检查接口指针、长度、枚举值和输出缓冲区，不应直接从硬件寄存器开始排查。
与对称加解密和哈希相关的常用错误类型如下：
| 名称 | 低 8 位 | 含义 | 优先检查项 |
|---|---|---|---|
ERROR_INVALID_PARAM |
0x01 | 参数取值无效 | Key、IV、Nonce、Tag、长度和算法枚举 |
ERROR_PARAM_IS_NULL |
0x02 | 必填指针为空 | 输入输出缓冲区和上下文指针 |
ERROR_NOT_INIT |
0x03 | 模块或上下文未初始化 | Start/Update/Finish 调用顺序 |
ERROR_UNSUPPORT |
0x04 | 配置或能力不支持 | SYMC、GCM、HASH 和 SHA-256 配置宏 |
ERROR_CHN_BUSY |
0x07 | 硬件通道繁忙 | 并发访问和异常路径资源释放 |
ERROR_CTX_CLOSED |
0x08 | 上下文已经关闭 | Finish/Destroy 后是否复用句柄 |
ERROR_SYMC_LEN_NOT_ALIGNED |
0x0F | 数据长度未按分组对齐 | ECB/CBC 输入长度和填充方式 |
ERROR_SYMC_AEAD_TAG_INVALID |
0x21 | AEAD Tag 校验失败 | Key、Nonce、AAD、Tag 和密文 |
ERROR_MALLOC |
0x41 | 内存申请失败 | 堆余量、缓冲区生命周期和释放路径 |
ERROR_HASH_LOGIC |
0xA0 | HASH 硬件逻辑错误 | 时钟、寄存器和硬件状态 |
ERROR_HASH_CALC_TIMEOUT |
0xB2 | HASH 计算超时 | 通道、时钟和硬件状态 |
ERROR_SYMC_CALC_TIMEOUT |
0xB4 | SYMC 计算超时 | DMA、通道和硬件状态 |
说明： 某些底层接口可能直接返回通用错误值或
0xFFFFFFFF，不一定包含完整的组合字段。解析前应确认返回值是否符合组合错误码格式。
常见运行问题
AES-GCM 加密返回参数错误
依次检查以下参数：
key_len是否为 16、24 或 32。- Keyslot 模式下
key是否为NULL，keyslot_handle是否有效。 - 明文、密文和 Tag 缓冲区长度是否满足接口要求。
tag_len是否大于 0 且未超过接口支持的上限。- 算法枚举是否为 AES 或目标配置明确支持的算法。
AES-GCM 解密 Tag 校验失败
加密端和解密端的 Key、Nonce/IV、AAD、Tag、密文及对应长度必须完全一致。Tag 校验失败属于安全校验结果，应用必须拒绝该数据，并且不得继续使用解密输出缓冲区。
CBC/ECB 数据长度不对齐
ECB 和 CBC 等分组模式通常要求输入长度按 16 字节对齐。需要填充时，应使用协议规定的标准填充方式，并额外提供完整性保护。CTR、CCM 和 GCM 的长度约束应分别按对应接口文档处理。
SHA-256 单次结果与分段结果不同
- 确认所有分段按原顺序拼接后与单次输入完全一致。
- 检查是否存在数据遗漏、重复或重排。
- 确认 Start、Update 和 Finish 使用同一上下文。
- Update 返回失败后不得继续使用当前计算结果。
- Finish 或 Destroy 后不得继续使用旧句柄。
HASH 句柄无效或已关闭
仅在 Start 成功后调用 Update 和 Finish。只要上下文创建成功，无论后续运算成功还是异常退出，都应调用 Destroy 释放上下文。
常见编译与链接问题
| 错误现象 | 原因 | 解决方法 |
|---|---|---|
找不到 security_symc.h |
安全头文件路径未加入组件 | 检查 PRIVATE_HEADER 是否包含 src/include/driver |
undefined reference to uapi_drv_cipher_* |
Security Unified 组件未链接 | 检查目标组件集合和安全能力配置 |
| AT 命令不存在 | Demo 开关或命令注册未生效 | 检查 CONFIG_ENABLE_SECURITY_SAMPLE 和 AT 注册函数 |
| AES-GCM 返回参数错误 | Key、Nonce、Tag 或长度不符合约束 | 使用标准向量逐项核对参数 |
| 增量编译结果异常 | 旧对象文件或缓存掩盖配置变化 | 清理构建缓存后执行完整构建 |
调试方法
- 记录每个接口的完整十六进制返回值，避免仅输出“失败”。
- 优先使用固定公开测试向量，排除随机输入和业务协议差异。
- 检查
key_len是否为 16、24 或 32。 - 检查加密端和解密端的 Key、Nonce、AAD、Tag 和长度是否完全一致。
- 检查输出缓冲区是否足够，输入输出是否发生不允许的重叠。
- 分段 HASH 失败时，确认调用顺序为 Start → Update → Finish。
- 检查相应配置宏和安全组件是否参与构建。
- 按本节说明解析 ENV、LAYER、MODULE 和 Error Code，并保留完整返回值。
问题反馈信息
提交 Issue 或请求技术支持时，应提供 SDK 版本、芯片与开发板、构建目标、失败接口、完整十六进制返回值、相关配置宏、输入长度、最小复现步骤、预期结果和实际日志。日志中不得包含生产密钥、敏感明文或设备生产凭据；设备唯一标识应按项目要求脱敏。