# AES加解密

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

# 功能概述

提供系统级的AES数据加解密功能，可对用户数据进行对称加解密，保障固件与网络传输数据的机密性。

## 主要应用场景

1. 网络通信数据加密：  
  在TLS/SSL握手完成后，底层数据流的传输（如HTTPS、MQTT over TLS）普遍采用AES加密。  
  即使在非安全链路（直接使用TCP/UDP）上，应用层也常直接调用AES接口（如 *qcm_aes_string_cbc_encryption()*）加密载荷数据。

2. 本地数据与存储安全：  
  文件系统加密：保护设备本地的敏感文件（如日志、配置、凭据），防止设备被拆解后Flash中的数据被直接读取。  
  数据库加密：例如SQLite的加密扩展通常基于AES实现。

3. 固件升级（FOTA）：  
  云端下发的升级包经AES加密，设备端下载后使用本地预置的固定密钥或动态协商的密钥解密，防止固件被逆向分析。

## 常见问题

1. 避免使用固定IV：每次加密应使用新生成的随机IV。

2. CBC模式不具备防篡改能力：建议优先使用AES-GCM/CCM等认证加密模式；若使用CBC，须额外附加HMAC完整性校验。

3. 做好密钥管理：密钥不得硬编码在代码中、不得输出到日志，也不应多台设备共用；同时应支持密钥的安全存储与定期轮换。

# AES加解密API

## 头文件

*qcm_aes.h*

## 函数概览

| **函数** | **说明** |
| --- | --- |
| *qcm_aes_string_encryption()* | 对单块16字节明文数据进行AES加密 |
| *qcm_aes_string_decryption()* | 对单块16字节密文数据进行AES解密 |
| *qcm_aes_string_cbc_encryption()* | 使用AES-CBC模式对任意长度数据进行加密，并自动进行PKCS#7填充 |

## 函数详解

### qcm_aes_string_encryption

- **功能描述**  
  使用给定密钥对单块16字节明文数据进行AES加密，输出16字节密文。

- **函数原型**

```c
void qcm_aes_string_encryption(qosa_uint8_t key[16],
                               int key_length,
                               qosa_uint8_t inputdata[16],
                               qosa_uint8_t outputdata[16]);
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *key* | 输入 | qosa_uint8_t [16] | AES加密密钥；长度由 *key_length* 指定 |
| *key_length* | 输入 | int | 密钥长度 |
| *inputdata* | 输入 | qosa_uint8_t [16] | 待加密的16字节明文数据 |
| *outputdata* | 输出 | qosa_uint8_t [16] | 用于存放16字节密文结果的缓冲区 |

- **返回值说明**  
  无

### qcm_aes_string_decryption

- **功能描述**  
  使用与加密端一致的密钥对单块16字节密文数据进行AES解密，还原出原始明文。

- **函数原型**

```c
void qcm_aes_string_decryption(qosa_uint8_t key[16],
                               int key_length,
                               qosa_uint8_t inputdata[16],
                               qosa_uint8_t outputdata[16]);
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *key* | 输入 | qosa_uint8_t [16] | AES解密密钥；必须与加密端使用的密钥一致 |
| *key_length* | 输入 | int | 密钥长度 |
| *inputdata* | 输入 | qosa_uint8_t [16] | 待解密的16字节密文数据 |
| *outputdata* | 输出 | qosa_uint8_t [16] | 用于存放16字节明文结果的缓冲区 |

- **返回值说明**  
  无

### qcm_aes_string_cbc_encryption

- **功能描述**  
  使用AES-CBC模式对任意长度的明文数据进行加密，并自动按PKCS#7标准填充至16字节的整数倍，适用于加密变长报文。输出缓冲区须预留足够空间，以容纳填充后的密文数据。

- **函数原型**

```c
void qcm_aes_string_cbc_encryption(
    qosa_uint8_t *key,
    qosa_uint32_t keybits,
    qosa_uint8_t  iv[16],
    qosa_uint8_t *inputdata,
    qosa_uint8_t *outputdata,
    int           inlen,
    int          *outlen
);
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *key* | 输入 | qosa_uint8_t * | 指向AES加密密钥的指针；密钥长度由 *keybits* 指定 |
| *keybits* | 输入 | qosa_uint32_t | 密钥长度；范围：128、192、256；单位：比特 |
| *iv* | 输入 | qosa_uint8_t [16] | 16字节初始化向量（IV）；每次加密应使用新生成的随机IV |
| *inputdata* | 输入 | qosa_uint8_t * | 指向待加密明文数据的指针；长度由 *inlen* 指定 |
| *outputdata* | 输出 | qosa_uint8_t * | 指向存放密文的输出缓冲区；容量至少为 *inlen*+16字节，以容纳PKCS#7填充后的数据 |
| *inlen* | 输入 | int | 明文数据长度；单位：字节 |
| *outlen* | 输出 | int * | 输出加密后密文的实际总长度，含PKCS#7填充；单位：字节 |

- **返回值说明**  
  无

# 应用逻辑流程图

```{image} images/image_XVTOb4leCo6ktpx3o37cMgvenie.webp
:width: 1039px
:height: 733px
```

# 示例代码

完整示例代码请查看https://github.com/UniRTOS/UniRTOS-Doc-Examples/blob/main/network/crypto/aes_demo.c