跳至主要內容

Aes模块用户手册

大约 9 分钟约 2680 字2025/12/26

Aes模块用户手册

目录

1. 简介

1.1 支持的设备

当前软件适用于以下芯片：

  • KF32A158xxxSF

1.2 名词及缩写

缩写解释
AES高级加密标准(Advanced Encryption Standard)
ECB电码本模式(Electronic Code Book)
CBC密码分组链接模式(Cipher Block Chaining)
CTR计数器模式(Counter)
GCMGalois/Counter模式(Galois/Counter)
GMAC伽罗瓦消息验证码(Galois Message Authentication Code)
CCM密码块链接-消息认证码计数器模式(Counter with Cipher Block Chaining-Message Authentication Code)

2. 文件结构

文件名称描述
kf32axxx_hli_aes.h此头文件输出Aes驱动程序的宏、类型定义和函数原型
kf32axxx_hli_aes.c此文件包含Aes驱动程序的通用功能
kf32axxx_hli_aes_cfg.h此头文件输出Aes开关类的宏
kf32axxx_hli_aes_Lcfg.h此头文件输出Aes驱动程序的配置项
kf32axxx_hli_aes_Lcfg.c此头文件输出Aes驱动程序的配置项原型

3. 数据结构

3.1 数据类型

3.1.1 宏定义

无。

3.1.2 枚举

  1. AES加密/解密

    HLI_Aes_FunctionEnumTypeAES加密、解密操作类型
    HLI_AES_ENCRYPT加密操作
    HLI_AES_DECRYPT解密操作

  2. AES加密/解密模式

    HLI_Aes_LinkModeEnumTypeAES模式类型
    HLI_AES_LINK_MODE_ECBECB模式
    HLI_AES_LINK_MODE_CTRCTR模式
    HLI_AES_LINK_MODE_CBCCBC模式
    HLI_AES_LINK_MODE_GCM_GMACGCM/GMAC模式
    HLI_AES_LINK_MODE_CCMCCM模式

  3. 密匙长度

    HLI_Aes_KeyLenEnumType秘钥长度类型
    HLI_AES_KEYLEN_128128bit长度秘钥
    HLI_AES_KEYLEN_192192bit长度秘钥
    HLI_AES_KEYLEN_256256bit长度秘钥

  4. AES状态（函数执行结果）

    HLI_Aes_StatusTypeAES模块状态
    HLI_AES_STATUS_OKAES OK
    HLI_AES_STATUS_ERRORAES错误
    HLI_AES_STATUS_BUSYAES正在工作
    HLI_AES_STATUS_TIMEOUTAES函数执行超时
    HLI_AES_STATUS_UNINITIALIZEDAES为初始化
    HLI_AES_STATUS_ALREADY_INITIALIZEDAES已经初始化
    HLI_AES_STATUS_INVALID_PARAM传入的参数错误

3.1.3 类型定义

无。

3.2 配置项说明

  1. AES功能配置

    成员解释取值范围
    LinkModeAES模式可选范围参考 HLI_Aes_LinkModeEnumType.
    FunctionAES功能, 加密/解密可选范围参考 HLI_Aes_FunctionEnumType.
    KeyLenAES密钥长度, 128bit/192bit/256bit可选范围参考 HLI_Aes_KeyLenEnumType.
    KeyBuf指向密钥buffer的指针uint32_t类型的数组.
    JobFinishIntrFlag是否打开中断, 打开中断标志使用异步方式进行计算.true/false
    JobFinishIntrCallback完成回调HLI_AES_InterruptHandler 类型的函数指针.

  2. AES加密/解密数据结构体

    成员解释取值范围
    FuncConfig指向AES功能配置的指针指向 HLI_Aes_FuncConfigType 类型的指针.
    IvBuf指向IV buffer的指针, ECB不需要IV, 此项为NULL即可uint32_t类型的数组.
    IvLenIV 长度CTR/CBC模式下为16Bytes, GCM模式下为12Bytes, CCM模式下7~13Bytes.
    AuthInfoBuf指向认证信息buffer的指针uint32_t类型的数组.
    AuthInfoLen认证信息长度仅GCM/CCM需要此参数, CCM最长支持255字节.
    PayloadBuf指向有效负载buffer的指针uint32_t类型的数组.
    PayloadLen有效负载长度0xFFFFFFFF字节以下.
    OutputBuf指向输出buffer的指针, 其长度与有效负载长度一致uint32_t类型的数组.
    TagBuf指向输出标签buffer的指针uint32_t类型的数组.
    TagLen标签长度仅CCM模式下有效, GCM标签长度固定16Byte
    CCM 有效标签长度为4、6、8、10、12、14、16Byte

4. 驱动函数

4.1 函数接口

4.1.1 HLI_Aes_Init

NameDescription
函数名称HLI_Aes_Init
语法:HLI_Aes_StatusType HLI_Aes_Init(void)
同步/异步:同步
重入性 :不可重入
形参(输入):void
形参(输出):无
返回值:HLI_AES_STATUS_OK AES模块初始化成功
描述:初始化AES模块, 对时钟等配置项进行配置
注意事项:无

4.1.2 HLI_Aes_ProcessData

NameDescription
函数名称HLI_Aes_ProcessData
语法:HLI_Aes_StatusType HLI_Aes_ProcessData(const HLI_Aes_DataStrucType *DataStruc)
同步/异步:同步
重入性 :不可重入
形参(输入):HLI_Aes_DataStrucType : 完成AES加密、解密所需输入的数据类型
返回值:HLI_AES_STATUS_OK 加解密操作完成
返回值:HLI_AES_STATUS_INVALID_PARAM AES模块输入参数无效
返回值:HLI_AES_STATUS_BUSY AES模块正在运算
返回值:HLI_AES_STATUS_TIMEOUT 运算超时
描述:使用AES模块对数据进行加密或解密
注意事项:1. 数据长度和数据输入方式严格按照配置文件样例格式；
2. 当使能中断时, 该函数为异步接口, 需要等待完成回调产生后输出数据才有效；
3.GCM/CCM不支持异步方式。
4.初始化AES后, 调用本函数进行数据加密或解密.

4.1.3 HLI_Aes_DeInit

NameDescription
函数名称HLI_Aes_DeInit
语法:HLI_Aes_StatusType HLI_Aes_DeInit(void)
同步/异步:同步
重入性 :不可重入
形参(输入):void
形参(输出):无
返回值:HLI_AES_STATUS_OK 反初始化操作完成
描述:对AES加解密模块进行反初始化
注意事项:需要确认AES已完成初始化

4.2 中断回调

4.2.1 AES_JobFinishIntrCallback

NameDescription
函数名称AES_JobFinishIntrCallback
语法void AES_JobFinishIntrCallback(void)
形参(输入)无
形参(输出)无
描述AES数据加解密完成回调函数,可根据用户需求决定是否配置
注意事项需要使用该回调函数时, 需要打开对应的一级中断, 不需要使用该回调函数时, 需要关闭对应的一级中断。
建议不在回调函数内进行耗时操作, 仅操作数据.

5. 示例

注

示例中使用的参数仅用作示例演示，应用时以实际为准。

1. ECB 模式 (同步)

这是最基本的使用方式，调用加密/解密函数后，程序会阻塞等待计算完成。

2. ECB 模式 (异步)

异步模式通过中断回调来通知计算完成，调用 HLI_Aes_ProcessData 后函数会立即返回，不会阻塞。

3. GCM 模式

GCM 是一种认证加密模式，除了生成密文，还会生成一个认证标签(Tag)。它仅支持同步计算。

4. CCM 模式

CCM 也是一种认证加密模式，与GCM类似，但算法不同。它同样仅支持同步计算。

6. 限制与假设

  1. _EINT31TO20_exception 为一个共用中断服务函数.
  2. 时钟源暂只支持系统主时钟源SCLK, 时钟分频限制不分频.
  3. 算法类型暂只支持AES标准算法, 数据输入限制无数据交换模式.
  4. AES ECB/CBC/CTR 模式下, 有效负载长度必须是128bit的倍数.
  5. AES GCM/CCM 模式下, 有效负载长度必须是4Byte的倍数.
  6. CCM 认证信息最大支持255字节.
  7. 输入内容未对齐4Byte的内容, 需要使用0填充对齐。如：0x1112补齐为0x11120000。

7. 变更记录

版本时间变更记录
v1.02025.11.20新增初版文档
最近更新
贡献者: 翟宇