对称硬件加密引擎

概述

对称硬件加密引擎是 SoC 内置的硬件加速模块，用于执行 AES 加密和 HMAC 哈希运算。相比软件实现，硬件加密引擎具有以下优势：

  • 高性能：硬件并行运算，大幅提升加解密速度

  • 低功耗：专用电路减少 CPU 参与度，降低整体功耗

  • 高安全性：密钥存储在 OTP 区域，软件无法直接读取；支持 TrustZone 隔离

  • 减少 CPU 占用：DMA 模式下自主完成数据搬运和运算，释放 CPU 资源

该引擎的 AES 和 HMAC 算法已通过 NIST CAVP 认证，支持多种加密算法和操作模式，广泛应用于数据加密、安全启动、固件保护等安全场景。

工作原理

加密引擎采用硬件总线架构，通过 DMA 控制器或 APB 总线与系统交互：

  • DMA 模式：引擎内部 DMA 控制器直接访问内存，自主完成数据读取、运算和结果写回，适合大数据量加解密

  • 从模式：CPU 通过 APB 总线将数据写入引擎 FIFO，适合小数据量运算

引擎支持 TrustZone 技术，自动识别 CPU 的安全状态（Secure/Non-Secure），并通过硬件互斥锁机制防止安全域和非安全域同时访问引发冲突。每次释放锁时，引擎自动清除寄存器中的敏感信息，防止侧信道攻击。

AES 引擎

AES 引擎根据由 NIST 定义的高级加密标准（AES）对数据进行加密或解密，支持消息自动填充。可以使用软件寄存器密钥和硬件 OTP 密钥。

AES 算法支持

RTL8721Dx:

支持的密钥大小：AES-128，AES-192，AES-256

  • 支持的加解密模式：

    • ECB (Electronic Codebook)

    • CBC (Cipher Block Chaining)

    • OFB (Output Feedback)

    • CFB (Cipher Feedback)

    • CTR (Counter)

    • GCM (Galois/Counter)

AES 密钥

AES 引擎配备独立的密钥管理单元，支持软件密钥和 OTP 硬件密钥。

RTL8721Dx:

硬件加密引擎提供两种密钥加载方式：

  • 软件传递：密钥由应用程序动态传入，软件可访问

  • OTP 自动加载：密钥预烧录至 OTP 物理存储区，软件无法访问，仅加密引擎可访问，防止被篡改或读取

OTP 物理存储区支持存储 6 组密钥，需通过串口命令烧录。

引擎类型

安全性

密钥索引

OTP 密钥

AES

安全

0

S_IPSEC_Key1

AES

安全

1

S_IPSEC_Key2

AES

安全

2

RSIP_AES_Key1

AES

安全

3

RSIP_AES_Key2

AES

非安全

0

NS_IPSEC_Key1

AES

非安全

1

NS_IPSEC_Key2

AES

非安全

2

RSIP_AES_Key1

AES

非安全

3

RSIP_AES_Key2

备注

上表中 AES 引擎的安全与非安全侧各列出 4 个密钥索引（共 8 项），但其中安全侧与非安全侧的 RSIP_AES_Key1、RSIP_AES_Key2 实际对应**同一组** OTP 物理密钥——该密钥由安全 AES 引擎与非安全 AES 引擎共同自动加载，并非两组独立密钥。去除重复后，OTP 物理存储区中实际仅存在 6 组互不相同的密钥（S_IPSEC_Key1/Key2、NS_IPSEC_Key1/Key2、RSIP_AES_Key1/Key2），这正是前文"OTP 物理存储区支持存储 6 组密钥"的由来。

OTP 密钥的详细功能如下所示：

OTP 密钥名称

地址

比特数

默认值

描述

S_IPSEC_Key1 (RDP)

逻辑地址 0x200

256

0xFF

启用 OTPKey_init 功能时，安全加密引擎将自动加载此密钥

用于 HMAC 或 AES 算法

S_IPSEC_Key2

(安全启动 HMAC)

逻辑地址 0x220

256

0xFF

NS_IPSEC_Key1

逻辑地址 0x240

256

0xFF

启用 OTPKey_init 功能时，非安全加密引擎将自动

加载此密钥用于 HMAC 或 AES 算法

NS_IPSEC_Key2

逻辑地址 0x260

256

0xFF

RSIP_AES_Key1

逻辑地址 0x2c0

256

0xFF

启用 OTPKey_init 功能时，非安全 AES 引擎和安全 AES 引擎

将自动加载此密钥用于 AES 算法

RSIP_AES_Key2

逻辑地址 0x2e0

256

0xFF

S_IPSEC_Key1_Read_Protection

物理地址 0x365[3]

1

1

0：启用 S_IPSEC_Key1 读保护，禁止密钥被读出

1：禁用 S_IPSEC_Key1 读保护

S_IPSEC_Key1_Write_Protection

物理地址 0x365[4]

1

1

0：启用 S_IPSEC_Key1 写保护，禁止密钥被攻击者篡改为全 0

1：禁用 S_IPSEC_Key1 写保护

S_IPSEC_Key2_Read_Protection

物理地址 0x365[5]

1

1

0：启用 S_IPSEC_Key2 读保护，禁止密钥被读出

1：禁用 S_IPSEC_Key2 读保护

S_IPSEC_Key2_Write_Protection

物理地址 0x365[6]

1

1

0：启用 S_IPSEC_Key2 写保护，禁止密钥被攻击者篡改为全 0

1：禁用 S_IPSEC_Key2 写保护

RSIP_AES_Key1_Read_Protection

物理地址 0x366[7]

1

1

0：启用 RSIP_AES_Key1 读保护，禁止密钥被读出

1：禁用 RSIP_AES_Key1 读保护

RSIP_AES_Key1_Write_Protection

物理地址 0x367[0]

1

1

0：启用 RSIP_AES_Key1 写保护，禁止密钥被攻击者篡改为全 0

1：禁用 RSIP_AES_Key1 写保护

RSIP_AES_Key2_Read_Protection

物理地址 0x367[1]

1

1

0：启用 RSIP_AES_Key2 读保护，禁止密钥被读出

1：禁用 RSIP_AES_Key2 读保护

RSIP_AES_Key2_Write_Protection

物理地址 0x367[2]

1

1

0：启用 RSIP_AES_Key2 写保护，禁止密钥被攻击者篡改为全 0

1：禁用 RSIP_AES_Key2 写保护

AES 引擎安全

RTL8721Dx:

AES 架构通过硬件级隔离和智能仲裁，在保证安全性的同时实现高效加密处理：

  • 两套独立寄存器组：

    • 安全地址空间：0x5XXX_XXXX，映射到安全专用寄存器

    • 非安全地址空间：0x4XXX_XXXX，映射到非安全专用寄存器

  • 当安全域与非安全域同时请求加密引擎时的仲裁机制：

    • 基础策略：轮询调度+FIFO 状态优先（满者优先）

    • 原子性保障：必须完成整轮加密操作（LS=1）才切换引擎控制权

  • 中断机制：

    • 物理隔离设计：安全与非安全中断连接至不同的中断号

    • 错误隔离上报：总线错误同时触发双中断，但需独立清除

    • 特殊设定：中断安全属性仅支持硬件自动切换

AES 引擎使用模式

RTL8721Dx:

DMA 模式

../../_images/crypto_legacy_block_diag_aes.svg

DMA 模式下，AES 引擎使用 DMA 在内存和 FIFO 之间搬运数据，并在传输过程中完成加密或解密。

该模式适用于大数据量的加解密场景，具有较高的运算效率。但数据地址和长度必须按 32 字节（缓存行长度）对齐，否则可能导致缓存数据不一致。驱动已自动处理源地址的缓存清理和目的地址的缓存无效化操作，用户无需额外处理。

如果地址或长度未对齐，系统会在串口日志中打印警告信息。

AES API

Realtek 提供了 ROM API，用户无需关注具体的寄存器操作。为提升易用性，AES 硬件加速引擎已集成到 MbedTLS 中。

受软硬件限制，MbedTLS 的 CMAC 和 AES-GCM 算法未实现硬件加速，用户执行这两种运算时可直接调用 ROM API 以获得更好的性能。

MbedTLS API 仅支持软件密钥，使用 OTP 密钥时需调用 ROM API。

HMAC 引擎

HMAC 引擎是一款用于计算 HMAC、SHA2 的硬件加速器，支持消息自动填充。HMAC 算法支持软件寄存器密钥和硬件 OTP 密钥。

HMAC 算法支持

RTL8721Dx:

支持的密钥大小：AES-128，AES-192，AES-256

  • 支持的加解密模式：

    • ECB (Electronic Codebook)

    • CBC (Cipher Block Chaining)

    • OFB (Output Feedback)

    • CFB (Cipher Feedback)

    • CTR (Counter)

    • GCM (Galois/Counter)

HMAC 密钥

HMAC 引擎配备独立的密钥管理单元，支持软件密钥和 OTP 硬件密钥。

RTL8721Dx:

硬件加密引擎提供两种密钥加载方式：

  • 软件传递：密钥由应用程序动态传入，软件可访问

  • OTP 自动加载：密钥预烧录至 OTP 物理存储区，软件无法访问，仅加密引擎可访问，防止被篡改或读取

OTP 物理存储区支持存储多组密钥，需通过串口命令烧录。

引擎类型

安全性

密钥索引

OTP 密钥

SHA HMAC

安全

0

S_IPSEC_Key1

SHA HMAC

安全

1

S_IPSEC_Key2

SHA HMAC

非安全

0

NS_IPSEC_Key1

SHA HMAC

非安全

1

NS_IPSEC_Key2

OTP 密钥的详细功能如下所示：

OTP 密钥名称

地址

比特数

默认值

描述

S_IPSEC_Key1 (RDP)

逻辑地址 0x200

256

0xFF

启用 OTPKey_init 功能时，安全加密引擎将自动加载此密钥

用于 HMAC 或 AES 算法

S_IPSEC_Key2

(安全启动 HMAC)

逻辑地址 0x220

256

0xFF

NS_IPSEC_Key1

逻辑地址 0x240

256

0xFF

启用 OTPKey_init 功能时，非安全加密引擎将自动加载此密钥

用于 HMAC 算法

NS_IPSEC_Key2

逻辑地址 0x260

256

0xFF

S_IPSEC_Key1_Read_Protection

物理地址 0x365[3]

1

1

0：启用 S_IPSEC_Key1 读保护，禁止密钥被读出

1：禁用 S_IPSEC_Key1 读保护

S_IPSEC_Key1_Write_Protection

物理地址 0x365[4]

1

1

0：启用 S_IPSEC_Key1 写保护，禁止密钥被攻击者篡改为全 0

1：禁用 S_IPSEC_Key1 写保护

S_IPSEC_Key2_Read_Protection

物理地址 0x365[5]

1

1

0：启用 S_IPSEC_Key2 读保护，禁止密钥被读出

1：禁用 S_IPSEC_Key2 读保护

S_IPSEC_Key2_Write_Protection

物理地址 0x365[6]

1

1

0：启用 S_IPSEC_Key2 写保护，禁止密钥被攻击者篡改为全 0

1：禁用 S_IPSEC_Key2 写保护

NS_IPSEC_Key1_Read_Protection

物理地址 0x365[7]

1

1

0：启用 NS_IPSEC_Key1 读保护，禁止密钥被读出

1：禁用 NS_IPSEC_Key1 读保护

NS_IPSEC_Key1_Write_Protection

物理地址 0x366[0]

1

1

0：启用 NS_IPSEC_Key1 写保护，禁止密钥被攻击者篡改为全 0

1：禁用 NS_IPSEC_Key1 写保护

NS_IPSEC_Key2_Read_Protection

物理地址 0x366[1]

1

1

0：启用 NS_IPSEC_Key2 读保护，禁止密钥被读出

1：禁用 NS_IPSEC_Key2 读保护

NS_IPSEC_Key2_Write_Protection

物理地址 0x366[2]

1

1

0：启用 NS_IPSEC_Key2 写保护，禁止密钥被攻击者篡改为全 0

1：禁用 NS_IPSEC_Key2 写保护

HMAC 引擎安全

RTL8721Dx:

HASH 架构通过硬件级隔离和智能仲裁，在保证安全性的同时实现高效加密处理：

  • 两套独立寄存器组：

    • 安全地址空间：0x5XXX_XXXX，映射到安全专用寄存器

    • 非安全地址空间：0x4XXX_XXXX，映射到非安全专用寄存器

  • 当安全域与非安全域同时请求加密引擎时的仲裁机制：

    • 基础策略：轮询调度+FIFO 状态优先（满者优先）

    • 原子性保障：必须完成整轮加密操作（LS=1）才切换引擎控制权

  • 中断机制：

    • 物理隔离设计：安全与非安全中断连接至不同的中断号

    • 错误隔离上报：总线错误同时触发双中断，但需独立清除

    • 特殊设定：中断安全属性仅支持硬件自动切换

HMAC 引擎使用模式

RTL8721Dx:

DMA 模式

../../_images/crypto_legacy_block_diag_hmac.svg

DMA 模式下，HASH 引擎使用 DMA 在内存和 FIFO 之间搬运数据，并在传输过程中计算 HMAC。

该模式适用于大数据量的运算场景，具有较高的运算效率。但数据地址和长度必须按 32 字节（缓存行长度）对齐，否则可能导致缓存数据不一致。驱动已自动处理源地址的缓存清理和目的地址的缓存无效化操作，用户无需额外处理。

如果地址或长度未对齐，系统会在串口日志中打印警告信息。

HMAC API

与 AES 引擎类似，Realtek 提供了 HMAC 底层 API，用户无需关注具体的寄存器操作。为提升易用性，SHA2 硬件加速引擎已集成到 MbedTLS 的 SHA2-Hash 和 HMAC API 中。SHA1、MD5 等其他哈希算法未实现硬件加速。

MbedTLS API 仅支持软件密钥。使用 OTP 密钥或 DMA 拷贝模式时，需调用底层 API。

密钥字节序

Crypto Engine 的密钥字节序与 MbedTLS 的数据结构相同，均采用小端序（little-endian）。 以下以 256-bit 密钥为例，说明从可读的十六进制字符串转换为数组并烧录至 OTP 的正确字节顺序。

开发阶段：密钥数组写法

在开发阶段，应用程序以字节数组形式将密钥传递给硬件 API，数组需按小端序排列。示例数组为 32 字节：

/* 256-bit key, little-endian byte order */
uint8_t key1[32] = {
   0xff, 0xee, 0xdd, 0xcc, 0xbb, 0xaa, 0x99, 0x88, 0x77, 0x66, 0x55, 0x44, 0x33, 0x22, 0x11, 0x00,
   0xef, 0xcd, 0xab, 0x89, 0x67, 0x45, 0x23, 0x01, 0xef, 0xcd, 0xab, 0x89, 0x67, 0x45, 0x23, 0x01
};

生产阶段：OTP 密钥烧录

生产阶段需将密钥烧录至 OTP 物理存储区。以下以 NS_IPSEC_Key2 为例，使用 AT+OTP=WRAW 串口烧录命令 写入 OTP 0x260 物理地址（长度 0x20，32 字节）：

AT+OTP=WRAW,0x260,0x20,ffeeddccbbaa99887766554433221100efcdab8967452301efcdab8967452301

量产阶段在密钥写入后，必须按照上述 OTP 表格的说明启用密钥读取保护和写入保护，防止 OTP 密钥被篡改或泄露。

备注

  • 上述示例以 32 字节 NS_IPSEC_Key2 密钥为例，实际地址与长度需根据实际需要调整。

  • 注意 OTP 烧录并重启系统后，OTP 密钥才能加载到引擎中。

  • 此字节序规则适用于所有 IC 型号。

OTP 密钥内容对应

上述指令写入后，OTP 物理地址区段中的实际内容：

OTP 内容（0x260 ~ 0x27F）

Address

b0

b1

b2

b3

b4

b5

b6

b7

b8

b9

b10

b11

b12

b13

b14

b15

0x260

ff

ee

dd

cc

bb

aa

99

88

77

66

55

44

33

22

11

00

0x270

ef

cd

ab

89

67

45

23

01

ef

cd

ab

89

67

45

23

01

Raw API

AES Exported Types

struct AES_InitTypeDef

AES Init Structure Definition.

Public Members

u32 CipherMode

Specifies the AES cipher mode. This parameter can be a value of AES Cipher Mode.

u32 EngineMode

Specifies the AES engine mode. This parameter can be a value of AES Engine Mode.

u32 IsEnc

Specifies AES encrypt or decrypt. This parameter can be TRUE or FALSE.

u32 CipherLen

Specifies the AES cipher length in bytes.

u32 key_len

AES key length in bits. This parameter can be a value of AES Key Size.

SHA Exported Types

struct SHA_InitTypeDef

SHA Init Structure Definition.

Public Members

u32 EngineMode

Specifies the SHA engine mode. This parameter can be a value of SHA Engine Mode.

u32 IcgEn

Specifies enable or disable SHA auto clock gating. This parameter can be ENABLE or DISABLE.

u32 DmaMode

Specifies SHA DMA mode. This parameter can be a value of SHA DMA Mode.

u32 HmacMode

Specifies the HMAC mode. This parameter can be a value of SHA HMAC Mode.

struct SHA_context

SHA Context Structure Definition.

Public Members

u32 sha_mode

Specifies the SHA mode. This parameter can be a value of SHA Mode.

u32 hmac_mode

HMAC operation mode. 0x0: hash mode. 0x1: HMAC mode.

u32 block_size

Block size. This parameter can be a value of SHA Block Size.

u32 ilen_bytes

Bytes occupied by input length storage.

u32 digest_len

Digest length.

u32 state[16]

Digest state

u8 buffer[128]

Data block being processed

u32 buf_used_bytes

Buffer bytes used

u32 total_len

The total number of data bytes to be processed

u8 dma_copy

DMA operation mode. 0x0: read-only mode. 0x1: copy mode

u8 seq_hash_first

Flag for sequential hash: 1 = this is the first block, 0 = subsequent block

u8 key_id

Key management key ID used for HMAC

u32 key_len_bits

HMAC key length in bits

u32 DMA_CTL_LOW

DMA control register low word value cached for this context

Hash Engine Mode

RTL8721F:

Not supported.

Crypto Symmetric Cipher Exported Types

Crypto Engine Mode

RTL8721F:

Not supported.

AES Exported Constants

AES Byte Swap Defaults

/* Default byte swap: key in native order, no swap */
#define AES_BYTE_SWAP_DEFAULTS AES_BIT_KEY_SWAP_DISABLE

/* Byte swap setting: key swap disabled (both key and payload in native order) */
#define AES_BYTE_SWAP_KEY_SWAP ((u32) 0x00)

AES Cipher Mode

/* AES encryption direction */
#define CIPHER_ENCRYPTION_MODE ((u8)0x01)

/* AES decryption direction */
#define CIPHER_DECRYPTION_MODE ((u8)0x00)

/* Electronic Codebook mode */
#define CIPHER_MODE_ECB ((u8)0x00)

/* Cipher Block Chaining mode */
#define CIPHER_MODE_CBC ((u8)0x01)

/* Cipher Feedback mode */
#define CIPHER_MODE_CFB ((u8)0x02)

/* Output Feedback mode */
#define CIPHER_MODE_OFB ((u8)0x03)

/* Counter mode */
#define CIPHER_MODE_CTR ((u8)0x04)

/* Galois Message Authentication Code mode */
#define CIPHER_MODE_GMAC ((u8)0x05)

/* Galois/Counter Mode (authenticated encryption) */
#define CIPHER_MODE_GCM ((u8)0x06)

/* Cipher-based Message Authentication Code mode */
#define CIPHER_MODE_CMAC ((u8)0x07)
RTL8721F: 
/* XEX-based tweaked-codebook mode with ciphertext stealing */
#define CIPHER_MODE_XTS ((u8)0x08)

/* Check whether MODE is a valid AES cipher mode. */
#define IS_AES_CIPHER_MODE (((MODE) == CIPHER_MODE_ECB) || \
    ((MODE) == CIPHER_MODE_CBC) || \
    ((MODE) == CIPHER_MODE_CFB) || \
    ((MODE) == CIPHER_MODE_OFB) || \
    ((MODE) == CIPHER_MODE_CTR) || \
    ((MODE) == CIPHER_MODE_GMAC) || \
    ((MODE) == CIPHER_MODE_GCM) || \
    ((MODE) == CIPHER_MODE_CMAC) || \
    ((MODE) == CIPHER_MODE_XTS))

AES DMA Size

/* AES block size in bytes */
#define AES_BLOCK_SIZE 16

/* AES block size in bits */
#define AES_BLOCK_SIZE_BIT 128

/* Maximum DMA block transfer size in transfer units */
#define AES_DMA_MAX_BLOCK_TS 536870910

/* Maximum DMA transfer size in bytes */
#define AES_DMA_MAX_BLOCK_BYTE (AES_DMA_MAX_BLOCK_TS * 1)

AES DMA Settings

/* DMA channel number for AES transfers */
#define AES_DMA_CH_NUM 0

/* DMA channel enable mask bit for AES */
#define AES_DMA_CH_MASK ((u32)0x00000001 << AES_DMA_CH_NUM)

AES Engine Mode

/* Slave mode: plaintext written directly to hardware registers */
#define AES_SLAVE_MODE ((u8)0x00)

/* DMA mode: plaintext transferred via DMA */
#define AES_DMA_MODE ((u8)0x01)

/* Check whether MODE is a valid AES engine mode. */
#define IS_AES_ENGINE_MODE (((MODE) == AES_SLAVE_MODE) || \
    ((MODE) == AES_DMA_MODE))

AES Key Size

/* Key size 128 bits */
#define AES_KEY_SIZE_128 ((u8)0x00)

/* Key size 192 bits */
#define AES_KEY_SIZE_192 ((u8)0x01)

/* Key size 256 bits */
#define AES_KEY_SIZE_256 ((u8)0x02)

AES Timeout

/* DMA mode operation timeout count */
#define AES_DMA_TIMEOUT ((u32) 10000000)

/* Engine mutex acquisition timeout count */
#define AES_MUTEX_TIMEOUT ((u32) 1000000)

/* Slave mode operation timeout count */
#define AES_SLAVE_TIMEOUT ((u32) 10000)

Crypto Block Size

RTL8721F:

Not supported.

HW_CRYPTO_ENGINE Exported Constants

Crypto Key

/* 128 bits */
#define KEY_BIT_128 (128)

/* 192 bits */
#define KEY_BIT_192 (192)

/* 256 bits */
#define KEY_BIT_256 (256)

/* Reverse the byte order of a 32-bit word (swap big-endian and little-endian). */
#define BIG_LITTLE_SWAP32 ( (((*(long int *)&x) & 0xff000000) >> 24) | \
    (((*(long int *)&x) & 0x00ff0000) >> 8) | \
    (((*(long int *)&x) & 0x0000ff00) << 8) | \
    (((*(long int *)&x) & 0x000000ff) << 24) )
RTL8721F: 
/* Check whether LEN is a valid AES key length in bits. */
#define IS_KEY_LEN_BIT (((LEN) == KEY_BIT_128) || \
    ((LEN) == KEY_BIT_192) || \
    ((LEN) == KEY_BIT_256))

Crypto Process Status

/* Descriptor number out of valid range */
#define _ERRNO_CRYPTO_DESC_NUM_SET_OutRange -2

/* DMA burst number out of valid range */
#define _ERRNO_CRYPTO_BURST_NUM_SET_OutRange -3

/* NULL pointer passed as argument */
#define _ERRNO_CRYPTO_NULL_POINTER -4

/* Crypto engine not initialized */
#define _ERRNO_CRYPTO_ENGINE_NOT_INIT -5

/* Buffer address not 4-byte aligned */
#define _ERRNO_CRYPTO_ADDR_NOT_4Byte_Aligned -6

/* Key index out of valid range */
#define _ERRNO_CRYPTO_KEY_OutRange -7

/* Message length out of valid range */
#define _ERRNO_CRYPTO_MSG_OutRange -8

/* IV length out of valid range */
#define _ERRNO_CRYPTO_IV_OutRange -9

/* Authentication type mismatch */
#define _ERRNO_CRYPTO_AUTH_TYPE_NOT_MATCH -10

/* Cipher type mismatch */
#define _ERRNO_CRYPTO_CIPHER_TYPE_NOT_MATCH -11

/* Key and IV length mismatch */
#define _ERRNO_CRYPTO_KEY_IV_LEN_DIFF -12

/* hash_final called without prior hash_update */
#define _ERRNO_CRYPTO_HASH_FINAL_NO_UPDATE -13

/* Secure key access error */
#define _ERRNO_CRYPTO_KEY_SECURE_ERR -14

/* Invalid key length */
#define _ERRNO_CRYPTO_KEY_LENGTH_ERR -15

/* Key load failure */
#define _ERRNO_CRYPTO_KEY_LOAD_ERR -16

/* DMA transfer error */
#define _ERRNO_CRYPTO_DMA_ERR -17

/* Invalid message length */
#define _ERRNO_CRYPTO_MESSAGE_LEN_ERR -18

/* Tag length out of valid range */
#define _ERRNO_CRYPTO_TAG_OutRange -19

/* GCM authentication tag verification failed */
#define _ERRNO_CRYPTO_GCM_TAG_NOT_MATCH -20

/* Slave mode operation timeout */
#define _ERRNO_CRYPTO_SLAVE_TIME_OUT -21

/* Slave mode hardware error */
#define _ERRNO_CRYPTO_SLAVE_ERROR -22
RTL8721F:

Not supported.

SHA Exported Constants

RTL8721F:

Not supported.

SHA Block Size

/* Block size in bytes for SHA-224/256 (512-bit block = 64 bytes) */
#define SHA_BLOCK_256 64

/* Block size in bytes for SHA-384/512 (1024-bit block = 128 bytes) */
#define SHA_BLOCK_512 128

SHA Byte Inversion

/* Native (big-endian) byte order */
#define SHA_NATIVE_ORDER ((u8)0x00)

/* Inverse (little-endian) byte order */
#define SHA_INVERSE_ORDER ((u8)0x01)

/* Check whether INV is a valid SHA byte inversion setting. */
#define IS_SHA_BYTE_INV (((INV) == SHA_NATIVE_ORDER) || \
    ((INV) == SHA_INVERSE_ORDER))

SHA Byte Swap Defaults

/* Bitmask for key and payload byte inversion bits in CONTROL register */
#define SHA_MASK_BYTE_INVERSION ((u32)0x00000003 << 12)
RTL8721F: 
/* Default: key in native order, payload byte-inverted */
#define SHA_BYTE_SWAP_DEFAULTS ((u32)(~SHA_BIT_KEY_BYTE_INVERSION_ENABLE) & SHA_BIT_PAYLOAD_BYTE_INVERSION_ENABLE)

/* Both key and payload in inverse byte order */
#define SHA_BYTE_SWAP_KEY_SWAP ((u32)  SHA_BIT_KEY_BYTE_INVERSION_ENABLE  | SHA_BIT_PAYLOAD_BYTE_INVERSION_ENABLE)

SHA Digest Length

/* SHA-224 digest output length in bytes */
#define SHA_DIGEST_224 28

/* SHA-256 digest output length in bytes */
#define SHA_DIGEST_256 32

/* SHA-384 digest output length in bytes */
#define SHA_DIGEST_384 48

/* SHA-512 digest output length in bytes */
#define SHA_DIGEST_512 64

SHA DMA

/* DMA channel number for SHA transfers */
#define SHA_DMA_CH_NUM 1

/* DMA channel enable mask bit for SHA */
#define SHA_DMA_CH_MASK ((u32)0x00000001 << SHA_DMA_CH_NUM)

/* Max DMA block transfer size for SHA-224/256 (64-byte aligned) */
#define SHA_DMA_MAX_BLOCK_TS_256 0x1FFFFFC0

/* Max DMA block transfer size for SHA-384/512 (128-byte aligned) */
#define SHA_DMA_MAX_BLOCK_TS_512 0x1FFFFF80

/* DMA destination transfer width: byte */
#define SHA_DMA_DST_TR_WIDTH TrWidthOneByte

/* DMA source transfer width: byte */
#define SHA_DMA_SRC_TR_WIDTH TrWidthOneByte

SHA DMA Beat

/* Write a 64-bit value into byte buffer at offset i in big-endian order; used for SHA padding. */
#define SHA_PUT_UINT64_BE {                                                                                                          \
    (b)[(i)    ] = (unsigned char) ( (n) >> 56 );       \
    (b)[(i) + 1] = (unsigned char) ( (n) >> 48 );       \
    (b)[(i) + 2] = (unsigned char) ( (n) >> 40 );       \
    (b)[(i) + 3] = (unsigned char) ( (n) >> 32 );       \
    (b)[(i) + 4] = (unsigned char) ( (n) >> 24 );       \
    (b)[(i) + 5] = (unsigned char) ( (n) >> 16 );       \
    (b)[(i) + 6] = (unsigned char) ( (n) >>  8 );       \
    (b)[(i) + 7] = (unsigned char) ( (n)       );       \
}

/* Write a 32-bit value into byte buffer at offset i in big-endian order; used for SHA padding. */
#define SHA_PUT_UINT32_BE {                                                                                                          \
    (b)[(i)    ] = (unsigned char) ( (n) >> 24 );       \
    (b)[(i) + 1] = (unsigned char) ( (n) >> 16 );       \
    (b)[(i) + 2] = (unsigned char) ( (n) >>  8 );       \
    (b)[(i) + 3] = (unsigned char) ( (n)       );       \
}

SHA DMA Mode

/* DMA read-only mode: engine reads source, no output copy */
#define SHA_READ_MODE ((u8)0x00)

/* DMA copy mode: engine reads source and writes to destination */
#define SHA_COPY_MODE ((u8)0x01)

/* Switch from copy mode to read-only mode on next DMA transfer */
#define SHA_COPY_TO_READ_SWITCH ((u8)0x01)

/* Switch from read-only mode to copy mode on next DMA transfer */
#define SHA_READ_TO_COPY_SWITCH ((u8)0x02)

/* Check whether MODE is a valid SHA DMA mode. */
#define IS_SHA_DMA_MODE (((MODE) == SHA_READ_MODE) || \
    ((MODE) == SHA_COPY_MODE))

SHA Engine Mode

/* DMA mode: message data provided via DMA */
#define SHA_DMA_MODE ((u8)0x00)

/* Slave mode: message data written directly to FIFO */
#define SHA_SLAVE_MODE ((u8)0x01)

/* Check whether MODE is a valid SHA engine mode. */
#define IS_SHA_ENGINE_MODE (((MODE) == SHA_DMA_MODE) || \
    ((MODE) == SHA_SLAVE_MODE))

SHA HMAC Key Byte Length

/* HMAC key length: 16 bytes (128 bits) */
#define SHA_HMAC_KEY_BYTE_128 16

/* HMAC key length: 24 bytes (192 bits) */
#define SHA_HMAC_KEY_BYTE_192 24

/* HMAC key length: 32 bytes (256 bits) */
#define SHA_HMAC_KEY_BYTE_256 32

SHA HMAC Key Size

/* Register encoding for 128-bit HMAC key */
#define SHA_HMAC_KEY_SIZE_128 (0x00)

/* Register encoding for 192-bit HMAC key */
#define SHA_HMAC_KEY_SIZE_192 (0x01)

/* Register encoding for 256-bit HMAC key */
#define SHA_HMAC_KEY_SIZE_256 (0x02)

/* HMAC key length: 128 bits */
#define SHA_HMAC_KEY_BIT_128 128

/* HMAC key length: 192 bits */
#define SHA_HMAC_KEY_BIT_192 192

/* HMAC key length: 256 bits */
#define SHA_HMAC_KEY_BIT_256 256

/* Check whether SIZE is a valid HMAC key length in bits. */
#define IS_SHA_HMAC_KEY_BIT (((SIZE) == SHA_HMAC_KEY_BIT_128) || \
    ((SIZE) == SHA_HMAC_KEY_BIT_192) || \
    ((SIZE) == SHA_HMAC_KEY_BIT_256))

SHA HMAC Mode

/* Pure hash mode (no HMAC padding) */
#define SHA_HASH_MODE (0x00)

/* HMAC mode (i-pad and o-pad applied to key) */
#define SHA_HMAC_MODE (0x01)

/* Check whether MODE is a valid SHA/HMAC operation mode. */
#define IS_SHA_HMAC_MODE (((MODE) == SHA_HASH_MODE) || \
    ((MODE) == SHA_HMAC_MODE))

SHA Input Length Bytes

/* Input length field size for SHA-224/256: 8 bytes (64-bit) */
#define SHA_ILEN_BYTES_256 8

/* Input length field size for SHA-384/512: 16 bytes (128-bit) */
#define SHA_ILEN_BYTES_512 16

SHA Mode

/* SHA-224 algorithm */
#define SHA_224 ((u8)0x00)

/* SHA-256 algorithm */
#define SHA_256 ((u8)0x01)

/* SHA-384 algorithm */
#define SHA_384 ((u8)0x02)

/* SHA-512 algorithm */
#define SHA_512 ((u8)0x03)

/* Check whether MODE is a valid SHA-2 algorithm selection. */
#define IS_SHA_MODE (((MODE) == SHA_224) || \
    ((MODE) == SHA_256) || \
    ((MODE) == SHA_384) || \
    ((MODE) == SHA_512))
RTL8721F:

Not supported.

SHA Timeout

/* DMA mode operation timeout count */
#define SHA_DMA_TIMEOUT ((u32) 1000000)

/* Engine mutex acquisition timeout count */
#define SHA_MUTEX_TIMEOUT ((u32) 1000000)

/* Slave mode operation timeout count */
#define SHA_SLAVE_TIMEOUT ((u32) 10000)

KEY_MANAGEMENT Exported Constants

KM Key

RTL8721F: 
/* Secure Hardware Key_1, OTP raw address:0x200, size: 256-bit */
#define KM_HMAC_KEY_S_IPSEC_KEY1 ((u8)0x00)

/* Secure Hardware Key_2, OTP raw address:0x220, size: 256-bit */
#define KM_HMAC_KEY_S_IPSEC_KEY2 ((u8)0x01)

/* Secure Hardware Key_3, OTP raw address:0x240, size: 256-bit */
#define KM_HMAC_KEY_S_IPSEC_KEY3 ((u8)0x02)

/* Secure Hardware Key_4, OTP raw address:0x260, size: 256-bit */
#define KM_HMAC_KEY_S_IPSEC_KEY4 ((u8)0x03)

/* Secure Software Key, size: 256-bit */
#define KM_HMAC_KEY_S_SW ((u8)0x21)

/* Non-Secure Software Key, size: 256-bit */
#define KM_HMAC_KEY_NS_SW ((u8)0x22)

/* Secure Hardware Key_1, OTP raw address:0x200, size: 256-bit */
#define KM_AES_KEY_S_IPSEC_KEY1 ((u8)0x00)

/* Secure Hardware Key_2, OTP raw address:0x220, size: 256-bit */
#define KM_AES_KEY_S_IPSEC_KEY2 ((u8)0x01)

/* Secure Hardware Key_3, OTP raw address:0x240, size: 256-bit */
#define KM_AES_KEY_S_IPSEC_KEY3 ((u8)0x02)

/* Secure Hardware Key_4, OTP raw address:0x260, size: 256-bit */
#define KM_AES_KEY_S_IPSEC_KEY4 ((u8)0x03)

/* Secure Hardware Key_5, OTP raw address:0x2C0, size: 256-bit */
#define KM_AES_KEY_S_RSIP_ECB_KEY ((u8)0x04)

/* Secure Hardware Key_6, OTP raw address:0x2E0, size: 256-bit */
#define KM_AES_KEY_S_RSIP_CTR_KEY ((u8)0x05)

/* Secure Software Key, size: 256-bit */
#define KM_AES_KEY_S_SW1 ((u8)0x21)

/* Secure Software Key, size: 256-bit */
#define KM_AES_KEY_S_SW2 ((u8)0x22)

/* Non-Secure Software Key, size: 256-bit */
#define KM_AES_KEY_NS_SW1 ((u8)0x23)

/* Non-Secure Software Key, size: 256-bit */
#define KM_AES_KEY_NS_SW2 ((u8)0x24)

KM Shared Key

RTL8721F: 
/* If 1, secure Hardware Key_1 share to non-secure */
#define KM_HMAC_SHARE_SEC_S_IPSEC_KEY1 ((u32)0x00000001 << 1)

/* If 1, secure Hardware Key_2 share to non-secure */
#define KM_HMAC_SHARE_SEC_S_IPSEC_KEY2 ((u32)0x00000001 << 2)

/* If 1, secure Hardware Key_3 share to non-secure */
#define KM_HMAC_SHARE_SEC_S_IPSEC_KEY3 ((u32)0x00000001 << 3)

/* If 1, secure Hardware Key_4 share to non-secure */
#define KM_HMAC_SHARE_SEC_S_IPSEC_KEY4 ((u32)0x00000001 << 4)

/* If 1, secure Software Key_33 share to non-secure */
#define KM_HMAC_SHARE_SEC_S_SW ((u32)0x00000001 << 5)

/* If 1, secure Hardware Key_1 share to non-secure */
#define KM_AES_SHARE_SEC_S_IPSEC_KEY1 ((u32)0x00000001 << 1)

/* If 1, secure Hardware Key_2 share to non-secure */
#define KM_AES_SHARE_SEC_S_IPSEC_KEY2 ((u32)0x00000001 << 2)

/* If 1, secure Hardware Key_3 share to non-secure */
#define KM_AES_SHARE_SEC_S_IPSEC_KEY3 ((u32)0x00000001 << 3)

/* If 1, secure Hardware Key_4 share to non-secure */
#define KM_AES_SHARE_SEC_S_IPSEC_KEY4 ((u32)0x00000001 << 4)

/* If 1, secure Hardware Key_5 share to non-secure */
#define KM_AES_SHARE_SEC_S_RSIP_ECB_KEY ((u32)0x00000001 << 5)

/* If 1, secure Hardware Key_6 share to non-secure */
#define KM_AES_SHARE_SEC_S_RSIP_CTR_KEY ((u32)0x00000001 << 6)

/* If 1, secure Software Key_33 share to non-secure */
#define KM_AES_SHARE_SEC_S_SW1 ((u32)0x00000001 << 7)

/* If 1, secure Software Key_34 share to non-secure */
#define KM_AES_SHARE_SEC_S_SW2 ((u32)0x00000001 << 8)

Crypto Symmetric Cipher Exported Constants

RTL8721F:

Not supported.

Crypto Hash Exported Constants

Crypto Timeout

RTL8721F:

Not supported.

Hash Algorithm Selection

RTL8721F:

Not supported.

Hash Block Size

RTL8721F:

Not supported.

Hash Digest Length

RTL8721F:

Not supported.

SM4 Exported Constants

SM4 Cipher Mode

RTL8721F:

Not supported.

SM3 Exported Constants

SM3 Mode

RTL8721F:

Not supported.

SM3 Block Size

RTL8721F:

Not supported.

SM3 Digest Length

RTL8721F:

Not supported.

AES Exported Functions

int crypto_aes_cbc(u8 key_id, u32 key_len_bits, u8 is_encryption, const u8 *input, u32 len, u8 iv[16], u8 *output)

Perform AES-CBC encryption and decryption in DMA mode.

参数:

  • key_id -- Value of KM Key

  • key_len_bits --

    • KEY_BIT_128

    • KEY_BIT_192

    • KEY_BIT_256

  • is_encryption --

    • 1: Encryption

    • 0: Decryption

  • input -- The address of the input data.

  • len -- The length of the data.

  • iv -- IV array address. IV length must be 16 bytes.

  • output -- The address of the output data.

返回:

Process status:

备注

  • The engine will be locked during the execution of this function, and will be unlocked after execution. Avoid multiple threads/CPUs using the AES engine at the same time.

  • The length of encrypted and decrypted data must be 32-byte (cache line size) aligned. At the same time, the destination address is also 32-byte aligned. Otherwise, an error will be reported.

int crypto_aes_cfb(u8 key_id, u32 key_len_bits, u8 is_encryption, const u8 *input, u32 len, u8 iv[16], u8 *output)

Perform AES-CFB encryption and decryption in DMA mode.

参数:

  • key_id -- Value of KM Key

  • key_len_bits --

    • KEY_BIT_128

    • KEY_BIT_192

    • KEY_BIT_256

  • is_encryption --

    • 1: Encryption

    • 0: Decryption

  • input -- The address of the input data.

  • len -- The length of the data.

  • iv -- IV array address. IV length must be 16 bytes.

  • output -- The address of the output data.

返回:

Process status:

备注

  • The engine will be locked during the execution of this function, and will be unlocked after execution. Avoid multiple threads/CPUs using the AES engine at the same time.

  • The length of encrypted and decrypted data must be 32-byte (cache line size) aligned. At the same time, the destination address is also 32-byte aligned. Otherwise, an error will be reported.

int crypto_aes_ctr(u8 key_id, u32 key_len_bits, u8 is_encryption, const u8 *input, u32 len, u8 iv[16], u8 *output)

Perform AES-CTR encryption and decryption in DMA mode.

参数:

  • key_id -- Value of KM Key

  • key_len_bits --

    • KEY_BIT_128

    • KEY_BIT_192

    • KEY_BIT_256

  • is_encryption --

    • 1: Encryption

    • 0: Decryption

  • input -- The address of the input data.

  • len -- The length of the data.

  • iv -- IV array address. IV length must be 16 bytes.

  • output -- The address of the output data.

返回:

Process status:

备注

  • The engine will be locked during the execution of this function, and will be unlocked after execution. Avoid multiple threads/CPUs using the AES engine at the same time.

  • The length of encrypted and decrypted data must be 32-byte (cache line size) aligned. At the same time, the destination address is also 32-byte aligned. Otherwise, an error will be reported.

int crypto_aes_ecb(u8 key_id, u32 key_len_bits, u8 is_encryption, const u8 *input, u32 len, u8 *output)

Perform AES-ECB encryption and decryption in DMA mode.

参数:

  • key_id -- Value of KM Key

  • key_len_bits --

    • KEY_BIT_128

    • KEY_BIT_192

    • KEY_BIT_256

  • is_encryption --

    • 1: Encryption

    • 0: Decryption

  • input -- The address of the input data.

  • len -- The length of the data.

  • output -- The address of the output data.

返回:

Process status:

备注

  • The engine will be locked during the execution of this function, and will be unlocked after execution. Avoid multiple threads/CPUs using the AES engine at the same time.

  • The length of encrypted and decrypted data must be 32-byte (cache line size) aligned. At the same time, the destination address is also 32-byte aligned. Otherwise, an error will be reported.

int crypto_aes_ofb(u8 key_id, u32 key_len_bits, u8 is_encryption, const u8 *input, u32 len, u8 iv[16], u8 *output)

Perform AES-OFB encryption and decryption in DMA mode.

参数:

  • key_id -- Value of KM Key

  • key_len_bits --

    • KEY_BIT_128

    • KEY_BIT_192

    • KEY_BIT_256

  • is_encryption --

    • 1: Encryption

    • 0: Decryption

  • input -- The address of the input data.

  • len -- The length of the data.

  • iv -- IV array address. IV length must be 16 bytes.

  • output -- The address of the output data.

返回:

Process status:

备注

  • The engine will be locked during the execution of this function, and will be unlocked after execution. Avoid multiple threads/CPUs using the AES engine at the same time.

  • The length of encrypted and decrypted data must be 32-byte (cache line size) aligned. At the same time, the destination address is also 32-byte aligned. Otherwise, an error will be reported.

RTL8721F:
int crypto_aes_ctr_slave(u8 key_id, u32 key_len_bits, u8 is_encryption, const u8 input[16], u8 iv[16], u8 output[16])

Perform AES-CTR mode encryption and decryption in slave mode. In order to avoid the impact of 32-byte cache line alignment, an additional slave mode interface is provided. Input and output are limited to 16 bytes.

参数:

  • key_id -- Value of KM Key

  • key_len_bits --

    • KEY_BIT_128

    • KEY_BIT_192

    • KEY_BIT_256

  • is_encryption --

    • 1: Encryption

    • 0: Decryption

  • input -- The address of the input data.

  • iv -- IV array address. IV length must be 16 bytes.

  • output -- The address of the output data.

返回:

Process status:

备注

  • The engine will be locked during the execution of this function, and will be unlocked after execution. Avoid multiple threads/CPUs using the AES engine at the same time.

  • The length of encrypted and decrypted data must be 32-byte (cache line size) aligned. At the same time, the destination address is also 32-byte aligned. Otherwise, an error will be reported.

int crypto_aes_ecb_slave(u8 key_id, u32 key_len_bits, u8 is_encryption, const u8 input[16], u8 output[16])

Perform AES-ECB mode encryption and decryption in slave mode. In order to avoid the impact of 32-byte cache line alignment, an additional slave mode interface is provided. Input and output are limited to 16 bytes.

参数:

  • key_id -- Value of KM Key

  • key_len_bits --

    • KEY_BIT_128

    • KEY_BIT_192

    • KEY_BIT_256

  • is_encryption --

    • 1: Encryption

    • 0: Decryption

  • input -- The address of the input data.

  • output -- The address of the output data.

返回:

Process status:

备注

  • The engine will be locked during the execution of this function, and will be unlocked after execution. Avoid multiple threads/CPUs using the AES engine at the same time.

  • The length of encrypted and decrypted data must be 32-byte (cache line size) aligned. At the same time, the destination address is also 32-byte aligned. Otherwise, an error will be reported.

int crypto_aes_set_sw_key(u8 key_id, u32 key_len_bits, const u8 *key_addr)

Set software key value for AES.

参数:

  • key_id -- Value of KM Key

  • key_len_bits --

    • KEY_BIT_128

    • KEY_BIT_192

    • KEY_BIT_256

  • key_addr -- Address to software key array

返回:

Process status:

int crypto_aes_share_secure_key(const u8 key_id, const u8 is_share)

Control whether security keys can be shared with non-secure world. Note that if sharing is enabled, non-secure code can only trigger the use of the key, but cannot read or write.

参数:

  • key_id -- Value of KM Key

  • is_share -- 1: share 0: not share (secure only)

返回:

Process status:

int crypto_aes_start(u8 key_id, u8 xts_key2_id, u32 key_len_bits, int aes_mode, u8 is_encryption, const u8 *input, u32 len, u8 iv[16], u8 *output)

Generic AES DMA mode encryption and decryption for ECB, CBC, CFB, OFB, CTR, and XTS cipher modes. This is the underlying function called by mode-specific APIs such as crypto_aes_ecb(), crypto_aes_cbc(), etc.

参数:

  • key_id -- Value of KM Key. For XTS mode, this is key 1.

  • xts_key2_id -- XTS key 2 ID. For non-XTS modes, pass 0.

  • key_len_bits --

    • KEY_BIT_128

    • KEY_BIT_192

    • KEY_BIT_256

  • aes_mode -- AES cipher mode. This parameter can be a value of AES Cipher Mode. Supported modes: CIPHER_MODE_ECB, CIPHER_MODE_CBC, CIPHER_MODE_CFB, CIPHER_MODE_OFB, CIPHER_MODE_CTR, CIPHER_MODE_XTS.

  • is_encryption --

    • 1: encryption

    • 0: decryption

  • input -- The address of the input data.

  • len -- The length of the data in bytes.

  • iv -- IV array address. IV length must be 16 bytes. Pass NULL for ECB mode. For non-ECB modes, the updated IV is written back after the operation.

  • output -- The address of the output data.

返回:

Process status:

备注

  • The engine will be locked during the execution of this function, and will be unlocked after execution. Avoid multiple threads/CPUs using the AES engine at the same time.

  • The length of encrypted and decrypted data must be 32-byte (cache line size) aligned. At the same time, the destination address is also 32-byte aligned. Otherwise, an error will be reported.

int crypto_aes_xts(u8 key1_id, u8 key2_id, u32 key_len_bits, u8 is_encryption, const u8 *input, u32 len, u8 tweak[16], u8 *output)

AES-XTS encryption and decryption in DMA mode.

参数:

  • key1_id -- XTS key 1 ID

  • key2_id -- XTS key 2 ID

  • key_len_bits --

    • KEY_BIT_128

    • KEY_BIT_192

    • KEY_BIT_256

  • is_encryption --

    • 1: Encryption

    • 0: Decryption

  • input -- The address of the input data.

  • len -- The length of the data.

  • tweak -- Tweak array address. Tweak length must be 16 Bytes.

  • output -- The address of the output data.

返回:

Process status:

备注

  • The engine will be locked during the execution of this function, and will be unlocked after execution. Avoid multiple threads/CPUs using the AES engine at the same time.

  • The length of encrypted and decrypted data must be 32-byte (cache line size) aligned. At the same time, the destination address is also 32-byte aligned. Otherwise, an error will be reported.

int crypto_cmac(u8 key_id, u32 key_len_bits, const u8 *input, u32 len, u8 *tag)

Compute AES-CMAC authentication tag.

参数:

  • key_id -- Value of KM Key

  • key_len_bits --

    • KEY_BIT_128

    • KEY_BIT_192

    • KEY_BIT_256

  • input -- The address of the input data.

  • len -- The length of input data.

  • tag -- Pointer to the output tag address

返回:

Process status:

备注

  • The engine will be locked during the execution of this function, and will be unlocked after execution. Avoid multiple threads/CPUs using the AES engine at the same time.

  • The length of encrypted and decrypted data must be 32-byte (cache line size) aligned. At the same time, the destination address is also 32-byte aligned. Otherwise, an error will be reported.

int crypto_gcm_auth_decrypt(u8 key_id, u32 key_len_bits, u32 len, u8 *iv_addr, u32 iv_len, u8 *aad_addr, u32 aad_len, const u8 *input, u8 *output, u32 tag_len, u8 *tag)

AES-GCM mode decryption and authentication. While decrypting, the API will check whether the TAG generated by decryption is consistent with the input TAG. If the TAG is consistent, it will return success. Otherwise, the decryption verification fails.

参数:

  • key_id -- Value of KM Key

  • key_len_bits --

    • KEY_BIT_128

    • KEY_BIT_192

    • KEY_BIT_256

  • len -- The length of the message.

  • iv_addr -- IV array address.

  • iv_len -- IV length

  • aad_addr -- AAD address

  • aad_len -- AAD length

  • input -- The address of the input message.

  • output -- The address of output data

  • tag_len -- GCM tag length, max length is 16 bytes

  • tag -- GCM tag address (input for authentication)

返回:

Process status:

备注

This API supports 4 input modes of GCM mode:

  • Without AAD/PT/CT: set the input buffer to all 0, use slave mode to calculate tag (similar to CMAC mode input_len = 0)

  • Without PT/CT, with AAD: first use DMA + GMAC mode to calculate the temp tag of aad, then set the input buffer to all 0, and use slave + GCM mode to calculate the final tag

  • Without AAD, with PT or CT: slave + ECB mode to calculate ghash key, copy cpu_dataout reg to ghash_key reg. DMA+GCM mode, output tag

  • With AAD/PT or CT: Calculate IV, GMAC tag (GMAC mode) in order, output plaintext or ciphertext and tag This API is consistent with Mbedtls in various GCM modes. Users do not need to pay special attention to the calculation process. The length of encrypted and decrypted data must be 32-byte (cache line size) aligned. At the same time, the destination address is also 32-byte aligned. Otherwise, an error will be reported.

int crypto_gcm_encrypt_and_tag(u8 key_id, u32 key_len_bits, u8 is_encryption, u32 len, u8 *iv_addr, u32 iv_len, u8 *aad_addr, u32 aad_len, const u8 *input, u8 *output, u32 tag_len, u8 *tag)

AES-GCM mode encryption and decryption.

参数:

  • key_id -- Value of KM Key

  • key_len_bits --

    • KEY_BIT_128

    • KEY_BIT_192

    • KEY_BIT_256

  • is_encryption --

    • 1: Encryption

    • 0: Decryption

  • len -- The length of the message.

  • iv_addr -- IV array address.

  • iv_len -- IV length

  • aad_addr -- AAD address

  • aad_len -- AAD length

  • input -- The address of the input message.

  • output -- The address of output data

  • tag_len -- GCM tag length, max length is 16 bytes

  • tag -- GCM tag output address

返回:

Process status:

备注

This API supports 4 input modes of GCM mode:

  • Without AAD/PT/CT: set the input buffer to all 0, use slave mode to calculate tag (similar to CMAC mode input_len = 0)

  • Without PT/CT, with AAD: first use DMA + GMAC mode to calculate the temp tag of aad, then set the input buffer to all 0, and use slave + GCM mode to calculate the final tag

  • Without AAD, with PT or CT: slave + ECB mode to calculate ghash key, copy cpu_dataout reg to ghash_key reg. DMA+GCM mode, output tag

  • With AAD/PT or CT: Calculate IV, GMAC tag (GMAC mode) in order, output plaintext or ciphertext and tag This API is consistent with Mbedtls in various GCM modes. Users do not need to pay special attention to the calculation process. The length of encrypted and decrypted data must be 32-byte (cache line size) aligned. At the same time, the destination address is also 32-byte aligned. Otherwise, an error will be reported.

SHA Exported Functions

SHA HAL Functions

int crypto_hmac_sha2_final(SHA_context *ctx, u8 *output)

Perform HMAC final process.

参数:

  • ctx -- SHA context.

  • output -- The result of HMAC function

返回:

Process status:

备注

  • The HMAC key will be reloaded before the final process. If a software key is used and the key is modified in final, the calculation result will be wrong. Ensure the software key is set to the correct value before calling the final process.

  • The engine will be locked during the execution of this function, and will be unlocked after execution. Avoid multiple threads/CPUs using the engine at the same time.

int crypto_hmac_sha2_init(SHA_context *ctx, u32 SHAtype, u8 key_id, u32 key_len_bits)

Initialize the HMAC-SHA2 context for read-only DMA mode computation.

参数:

  • SHAtype --

    • SHA_224

    • SHA_256

    • SHA_384

    • SHA_512

  • ctx -- SHA context.

  • key_id -- Value of KM Key

  • key_len_bits --

    • KEY_BIT_128

    • KEY_BIT_192

    • KEY_BIT_256

返回:

Process status:

备注

The engine will be locked during the execution of this function, and will be unlocked after execution. Avoid multiple threads/CPUs using the engine at the same time.

int crypto_hmac_sha2_update(SHA_context *ctx, const u8 *input, u8 *dst, size_t len)

Update HMAC state.

参数:

  • ctx -- SHA context.

  • input -- Pointer to input data.

  • dst -- Pointer to output data. If in read-only mode, set it to NULL

  • len -- Input data length.

返回:

Process status:

备注

  • If copy mode and read-only mode are mixed for update, then ensure that the message lengths of both copy mode and read-only mode are integer multiples of the SHA-BLOCK length. (64-byte alignment for SHA-224/256, 128-byte alignment for SHA-384/512)

  • The HMAC key will be reloaded before each update. If a software key is used, and the key is modified between updates, the calculation result will be wrong. Ensure the software key is set to the correct value before calling update.

  • The engine will be locked during the execution of this function, and will be unlocked after execution. Avoid multiple threads/CPUs using the engine at the same time.

  • In copy mode, the destination address and calculation length must be 32 bytes (cache line size) aligned.

int crypto_sha2_final(SHA_context *ctx, u8 *output)

Perform SHA final process.

参数:

  • ctx -- SHA context

  • output -- The result of SHA function

返回:

Process status:

备注

  • Since the SHA engine does not support hardware padding, software padding is performed instead.

  • The engine will be locked during the execution of this function, and will be unlocked after execution. Avoid multiple threads/CPUs using the engine at the same time.

int crypto_sha2_init(SHA_context *ctx, u32 SHAtype)

Initialize the SHA-2 context for read-only DMA mode computation.

参数:

  • SHAtype --

    • SHA_224

    • SHA_256

    • SHA_384

    • SHA_512

  • ctx -- SHA context. This function will initialize the context.

返回:

Process status:

备注

The engine will be locked during the execution of this function, and will be unlocked after execution. Avoid multiple threads/CPUs using the engine at the same time.

int crypto_sha2_update(SHA_context *ctx, const u8 *input, u8 *dst, size_t len)

Update SHA state.

参数:

  • ctx -- SHA context

  • input -- Pointer to input data.

  • dst -- Pointer to output data. If in read-only mode, set it to NULL

  • len -- Input data length.

返回:

Process status:

备注

  • If copy mode and read-only mode are mixed for update, then ensure that the message lengths of both copy mode and read-only mode are integer multiples of the SHA-BLOCK length. (64-byte alignment for SHA-224/256, 128-byte alignment for SHA-384/512)

  • The engine will be locked during the execution of this function, and will be unlocked after execution. Avoid multiple threads/CPUs using the engine at the same time.

  • In copy mode, the destination address and calculation length must be 32 bytes (cache line size) aligned.

RTL8721F:
int crypto_hmac_sha2_set_sw_key(u8 key_id, u32 key_len_bits, const u8 *key_addr)

Set software key value for HMAC.

参数:

  • key_id -- Value of KM Key

  • key_len_bits --

    • KEY_BIT_128

    • KEY_BIT_192

    • KEY_BIT_256

  • key_addr -- Address to software key array

返回:

Process status:

int crypto_hmac_sha2_share_secure_key(const u8 key_id, const u8 is_share)

Control whether security keys can be shared with non-secure world.

参数:

  • key_id -- Value of KM Key

  • is_share --

    • 1: share

    • 0: not share (secure only)

返回:

Process status:

备注

If sharing is enabled, non-secure code can only trigger the use of the key, but cannot read or write.

SM3 Exported Functions

SM3 HMAC Functions

RTL8721F:

Not supported.

SM3 Normal Functions

RTL8721F:

Not supported.

KEY_MANAGEMENT Exported Functions

RTL8721F:

Not supported.

SM4 Exported Functions

SM4 DMA Functions

RTL8721F:

Not supported.

SM4 AEAD Functions

RTL8721F:

Not supported.

SM4 Authentication Functions

RTL8721F:

Not supported.