安全子系统 API 参考
前言
本文档主要介绍了安全驱动 API 及其用法。
说明：
本文以Hi3519DV500为例，未有特殊说明，Hi3516DV500与Hi3519DV500内容完全一致。
与本文档相对应的产品版本如下。
本文档主要适用于以下工程师：
- 技术支持工程师
- 软件开发工程师
- 测试工程师
在本文中可能出现下列标志，它们所代表的含义如下。
安全驱动概述
CIPHER DRIVER
功能描述
CIPHER DRIVER为安全算法模块，包括两层接口：MPI层、KAPI。
接口说明：
-
MPI 层
由用户层应用调用，为 CA/TA 提供安全驱动能力。
-
KAPI 层
由内核模块调用，为内核模块提供安全驱动能力。
功能描述：
-
CIPHER DRIVER提供如下算法：
- AES、SM4、TDES等对称加解密算法；
- HASH、SM3及HASH-MAC、SM3-MAC摘要算法；
- PBKDF2 算法；
- RSA、ECC、SM2等非对称签名验签、密钥协商、加解密算法，大数运算；
- 随机数算法。
-
CIPHER DRIVER包括3个子模块：SPACC、PKE、TRNG。
SPACC
SPACC（Security Protocol Accelerator，安全协议加速器）模块实现了对称加解密算法、HASH及HMAC摘要算法。
对称加解密算法
-
AES：支持ECB/CBC/CFB/OFB/CTR/CCM/GCM/CMAC/CBC_MAC共9种工作模式。其中：
- CFB模式支持的加密数据位宽可为8/128bit，Hi3516CV610、Hi3511CV100支持1bit。
- ECB/CBC/OFB/CTR/CCM/GCM/CMAC/CBC_MAC模式支持的加密数据位宽可为128bit。
- CCM/GCM模式下，加解密结束后需获取一次TAG值。
- ECB、CBC、CBC_MAC模式加密数据长度必须为16字节对齐，CMAC允许最后一块加密数据长度非16字节对齐。
- 支持AES-128/AES-256/AES-192（128、256、192均指传入的密钥长度，单位为bit）。注：Hi3519DV500不支持AES-192。
- CCM/GCM模式下，加密数据位宽为无效参数。
-
SM4：支持ECB/CBC/CTR共3种工作模式，Hi3516CV610、Hi3511CV100还支持CFB/OFB模式。支持SM4-128；除CTR模式外，加密数据长度须为16字节对齐。
- TDES：支持CBC/CFB/ECB/OFB共4种工作模式。支持TDES-128。其中：
- CFB模式支持的加密数据位宽可为8/64bit。
- CBC/ECB/OFB模式支持的加密数据位宽可为64bit。
- ECB/CBC模式加密数据长度必须为8字节对齐。
cipher驱动支持软件多通道，单个进程最多可以同时申请32个，Hi3516CV610、Hi3511CV100默认配置为8个；支持低功耗模式，默认开启低功耗；支持轮询和wait_event模式，默认开启wait_event模式。
须知：
- TDES算法及ECB模式属于非安全算法，不建议使用。
- Hi3516CV610、Hi3511CV100不支持TDES算法。
- Hi3519DV500不支持AES-192。
摘要算法
- HASH：支持SHA256/SHA384/SHA512/SM3。
- HMAC：支持HMAC_SHA256/HMAC_SHA384/HMAC_SHA512/HMAC_SM3。
- HASH和HMAC支持中途传入非block size对齐的数据块；
- 支持软件多通道，单进程最多可以同时申请32个，Hi3516CV610、Hi3511CV100默认配置为8。
Hi3516CV610、Hi3511CV100不支持SHA384/SHA512、HMAC_SHA384/HMAC_SHA512。 HMAC走长期通道，计算时会占用一个物理通道；HASH走短期通道，计算时会占用一个软件通道。
PKE
PKE（Public Key Encryption，公钥加密），即非对称加解密算法。常用于文件的签名和验签，以及非对称密钥的加解密，主要包括以下算法：
-
RSA
- 支持 PKCS#1 v1.5和 PKCS#1 v2.1 PSS两种模式的私钥签名和公钥验签。
- 支持PKCS#1 v1.5 和 PKCS#1 v2.1 OAEP两种模式的公钥加密和私钥解密。
- 支持密钥位宽2048/3072/4096。
-
ECC
- 支持 RFC 5639 - Brainpool 256/384/512、NIST FIPS 186 - 4 P 256/384/521 和 RFC 8032 - ED25519（即EDDSA）的私钥签名和公钥验签，Hi3516CV610、Hi3511CV100不支持RFC 8032。
- 支持密钥位宽256/384/512(521)。
-
SM2
- 支持SM2公钥加密和私钥解密。
- 支持SM2私钥签名和公钥验签。
-
密钥协商
- 支持RFC 5639 - Brainpool 256/384/512、NIST FIPS 186 - 4 P 256/384/521、RFC 7748 - Curve25519、 RFC 8032 - ED25519（即EDDSA）和SM2的公私钥对生成，及由给定的私钥生成其对应的公钥，Hi3516CV610、Hi3511CV100不支持RFC 7748和RFC 8032。
- 支持RFC 5639 - Brainpool 256/384/512、NIST FIPS 186 - 4 P 256/384/521、RFC 7748 - Curve25519和SM2的密钥交换（ECDH），Hi3516CV610、Hi3511CV100不支持RFC 7748。
-
曲线上点的验证
支持RFC 5639 - Brainpool 256/384/512、NIST FIPS 186 - 4 P 256/384/521和SM2的点是否在曲线上的验证。
-
大数运算
- 支持256/384/521/2048/3072/4096位的模加、模减、模乘和模运算。
- 支持256/384/521的模逆、乘法运算；支持密钥位宽为256位的Curve25519蒙哥马利点乘。
- 支持密钥位宽为256位的ED25519 ED点乘。
- 支持密钥位宽为256/384/521位的ED点加（Uranus ES不支持）。
- 支持密钥位宽为256/384/521位的ECC点乘、点加、倍点运算。
- 支持2048/3072/4096位的模幂运算。
- Hi3516CV610、Hi3511CV100不支持大数运算。
PKE支持低功耗模式，并支持PKE时钟的开启与关闭。当关闭时钟时，PKE模块整个不可用。支持轮询和wait_event模式，默认开启wait_event模式。
- 默认不支持NIST FIPS 186-4 P256/384/521曲线，如需打开需要用户在security_subsys/crypto_features.h中定义宏CONFIG_PKE_SUPPORT_ECC_FIPS_P256R、CONFIG_PKE_SUPPORT_ECC_FIPS_P384R、CONFIG_PKE_SUPPORT_ECC_FIPS_P521R，并重新编译驱动。
- 默认不支持RSA算法PKCS#1 v1.5填充模式，如需打开需要用户在security_subsys/crypto_features.h中定义宏CONFIG_PKE_RSA_V15_SUPPORT，并重新编译驱动。
- 默认不支持对称算法ECB模式，如需打开需要用户在security_subsys/crypto_features.h中定义宏CONFIG_SYMC_MODE_ECB_SUPPORT，并重新编译驱动。
- 默认不支持RSA2048，如需打开需要用户在security_subsys/crypto_features.h中定义宏CONFIG_PKE_RSA_2048_SUPPORT，并重新编译驱动。
- 默认不支持SHA224，如需打开需要用户在security_subsys/crypto_features.h中定义宏CONFIG_HASH_SHA224_SUPPORT，并重新编译驱动。
TRNG
随机数获取模块，获取硬件产生的真随机数（满足FIPS 140-2标准）。
使用流程
HASH计算
场景说明
获取消息摘要。
工作流程
- HASH 模块初始化。调用 ot_mpi_cipher_hash_init接口完成。
- 创建一路HASH，配置当前HASH计算类型，并获取HASH句柄。调用ot_mpi_cipher_hash_create 接口完成。
- 传入消息数据，对消息进行摘要计算，调用ot_mpi_cipher_hash_update 接口完成。
- 获取消息摘要，调用ot_mpi_cipher_hash_finish接口完成。
注意事项
支持多段数据连续update，结果与多段数据一次性update结果一致。
HMAC计算
场景说明
计算一块数据的 HMAC值。
工作流程
- HASH 模块初始化。调用 ot_mpi_cipher_hash_init 接口完成。
- 创建一路HASH，配置当前HMAC算法及密钥并获取HASH句柄。调用ot_mpi_cipher_hash_create 接口完成。
- 传入消息数据，对消息进行摘要计算，调用ot_mpi_cipher_hash_update 接口完成。
- 获取消息摘要，调用ot_mpi_cipher_hash_finish接口完成。
注意事项
支持明文key与硬件key，支持多段数据连续update，结果与多段数据一次性update结果一致。
HASH Clone 计算
场景说明
计算HASH(Message1 || Message2)，其中Message1的处理由hash_handle1完成，Message2的处理由hash_handle2完成，最终由hash_handle2计算出HASH(Message1 || Message2)的结果。
工作流程
- HASH 模块初始化。调用 ot_mpi_cipher_hash_init 接口完成。
- 创建一路HASH，设置当前HASH算法获取hash_handle1。调用ot_mpi_cipher_hash_create 接口完成。
- 创建第二路HASH，获取hash_handle2。调用ot_mpi_cipher_hash_create 接口完成。
- hash_handle1 传入 Message1进行摘要计算，调用ot_mpi_cipher_hash_update接口完成。
- 获取 hash_handle1的计算中间结果，调用ot_mpi_cipher_hash_get接口完成。
- 销毁hash_handle1，调用ot_mpi_cipher_hash_destroy接口完成。
- 将步骤5获取的中间结果设置到 hash_handle2，调用ot_mpi_cipher_hash_set接口完成。
- hash_handle2传入Message2进行摘要计算，调用ot_mpi_cipher_hash_update接口完成。
- 使用hash_handle2获取消息摘要，调用ot_mpi_cipher_hash_finish接口完成。
注意事项
- 支持多段数据连续update，结果与多段数据一次性update结果一致。
- HASH Clone计算时，若两个handle的type不一致以第一个handle的配置为准。
HMAC Clone 计算
- HMAC在使用硬件算法时，不支持Clone计算
- HMAC在使用明文key软件算法时，支持Clone计算，流程同HASH Clone
PBKDF2计算
调用ot_mpi_cipher_pbkdf2进行PBKDF2计算。
获取真随机数
调用ot_mpi_cipher_trng_get_random 获取四个字节的真随机数或调用ot_mpi_cipher_trng_get_multi_random获取任意字节的真随机数。
对称加解密，工作模式为ECB/CBC/CTR/OFB/CFB/ CFB8
- 调用ot_mpi_cipher_symc_init初始化SYMC模块；
- 调用ot_mpi_cipher_symc_create创建SYMC句柄；
- 调用ot_mpi_cipher_symc_attach绑定KEYSLOT通道，KEYSLOT通道创建可参考KEYSLOT&KLAD相关接口说明；
- 调用ot_mpi_cipher_symc_set_config设置算法参数；
- 调用ot_mpi_cipher_symc_encrypt进行加密（或调用ot_mpi_cipher_symc_decrypt进行解密）；
- 调用ot_mpi_cipher_symc_destroy销毁SYMC句柄；
- 调用ot_mpi_cipher_symc_deinit去初始化SYMC模块。
注意：
步骤5进行加密后，iv值会更新。如果要使用相同的SYMC句柄进行解密，需要重新进行步骤4设置算法参数。
对称加解密，工作模式为GCM/CCM
- 调用ot_mpi_cipher_symc_init初始化SYMC模块；
- 调用ot_mpi_cipher_symc_create创建SYMC句柄；
- 调用ot_mpi_cipher_symc_attach绑定KEYSLOT通道，KEYSLOT通道创建可参考KEYSLOT&KLAD相关接口说明；
- 调用ot_mpi_cipher_symc_set_config设置算法参数；
- 调用ot_mpi_cipher_symc_encrypt进行加密（或调用ot_mpi_cipher_symc_decrypt进行解密）；
- 调用ot_mpi_cipher_symc_get_tag获得tag值；
- 调用ot_mpi_cipher_symc_destroy销毁SYMC句柄；
- 调用ot_mpi_cipher_symc_deinit去初始化SYMC模块。
SYMC MAC
- 调用ot_mpi_cipher_symc_init初始化SYMC模块；
- 调用ot_mpi_cipher_mac_start 创建句柄；
- 调用ot_mpi_cipher_mac_update传入数据（可调用一次或多次）；
- 调用ot_mpi_cipher_mac_finish获取MAC值，并销毁句柄；
- 调用ot_mpi_cipher_symc_deinit去初始化SYMC模块。
RSA加解密
场景说明
RSA加解密为公钥加密私钥解密应用场景。
工作流程
- PKE 模块初始化，调用ot_mpi_cipher_pke_init 接口完成；
- 公钥加密，调用ot_mpi_cipher_pke_rsa_public_encrypt接口完成；
- 私钥解密，调用ot_mpi_cipher_pke_rsa_private_decrypt接口完成；
- PKE模块去初始化，调用ot_mpi_cipher_pke_deinit接口完成。
注意事项
支持PKCS#1 v1.5 和 PKCS#1 v2.1 OAEP两种模式，且用户标签数据（label）可选， 该label仅在PKCS#1 v2.1 OAEP模式下使用。
RSA签名验签
场景说明
RSA签名验签主要应用场景是私钥签名和公钥验签。
工作流程
- PKE 模块初始化，调用 ot_mpi_cipher_pke_init 接口完成；
- 私钥签名，调用ot_mpi_cipher_pke_rsa_sign接口完成；
- 公钥验签，调用ot_mpi_cipher_pke_rsa_verify接口完成；
- PKE模块去初始化，调用ot_mpi_cipher_pke_deinit接口完成。
注意事项
支持 PKCS#1 v1.5和 PKCS#1 v2.1 PSS两种模式的私钥签名和公钥验签。
SM2加解密
场景说明
SM2加解密应用场景是公钥加密私钥解密。
工作流程
- PKE 模块初始化，调用 ot_mpi_cipher_pke_init 接口完成；
- 公钥加密，调用ot_mpi_cipher_pke_sm2_public_encrypt接口完成；
- 私钥解密，调用ot_mpi_cipher_pke_sm2_private_decrypt接口完成；
- PKE模块去初始化，调用ot_mpi_cipher_pke_deinit接口完成。
SM2签名验签
场景说明
SM2签名验签主要应用场景是私钥签名和公钥验签。
工作流程
- PKE 模块初始化，调用 ot_mpi_cipher_pke_init 接口完成；
- 生成消息对应的HASH摘要，调用ot_mpi_cipher_pke_sm2_dsa_hash接口完成；
- 私钥签名，调用ot_mpi_cipher_pke_ecdsa_sign接口完成；
- 公钥验签，调用ot_mpi_cipher_pke_ecdsa_verify接口完成；
- PKE模块去初始化，调用ot_mpi_cipher_pke_deinit接口完成。
签名验签所需要的公私钥对可调用ot_mpi_cipher_pke_ecc_gen_key接口生成，可以调用ot_mpi_cipher_pke_check_dot_on_curve接口以确认公钥确实是曲线上的点。
ECDSA签名验签
场景说明
ECDSA签名验签主要应用场景是私钥签名和公钥验签。
工作流程
- PKE 模块初始化，调用 ot_mpi_cipher_pke_init 接口完成。
- 生成消息对应的HASH摘要，调用HASH/HMAC相应接口完成。
- 私钥签名，调用ot_mpi_cipher_pke_ecdsa_sign接口完成。
- 公钥验签，调用ot_mpi_cipher_pke_ecdsa_verify接口完成。
- PKE模块去初始化，调用ot_mpi_cipher_pke_deinit接口完成。
注意事项
支持 RFC 5639 - Brainpool 256/384/512、NIST FIPS 186 - 4 P 256/384/521的私钥签名和公钥验签。
EDDSA签名验签
场景说明
EDDSA签名验签主要应用场景是私钥签名和公钥验签，是使用ed25519这种特殊曲线签名验签。
工作流程
- PKE 模块初始化，调用 ot_mpi_cipher_pke_init 接口完成。
- 私钥签名，调用ot_mpi_cipher_pke_eddsa_sign接口完成。
- 公钥验签，调用ot_mpi_cipher_pke_eddsa_verify接口完成。
- PKE模块去初始化，调用ot_mpi_cipher_pke_deinit接口完成。
注意事项
支持 RFC 8032 - ED25519的私钥签名和公钥验签。
KM DRIVER
功能描述
KM DRIVER为密钥管理模块，对外提供两层接口：MPI 层、KAPI 层。
接口说明：
-
MPI 层
由用户层应用调用，为 CA/TA 提供密钥管理驱动能力。
-
KAPI 层
由内核模块调用，为内核模块提供密钥管理驱动能力。
功能描述：
明文KEY传递
- 支持 AES 128/192/256bits加解密。
- 支持 SM4 128bits加解密。
- 支持TDES 128bits加解密。
- 支持HMAC。
- 明文KEY即加解密引擎使用的工作密钥，应由用户妥善保管。
- Hi3516CV610、Hi3511CV100不支持TDES。
- Hi3519DV500不支持192bits
ROOTKEY传递
ROOTKEY即通过OTP模块的根密钥，经密钥解混淆、密钥派生后产生的KEY。ROOTKEY存储在硬件中，用户不可读取。加解密的工作密钥是KLAD多次层级传递后得到的KEY，该KEY也是存储在硬件中，用户不可读取。该方案大多用于安全方案要求高的场景。
- 支持 AES 128/192/256bits加解密。
- 支持 SM4 128bits加解密。
- 支持TDES 128bits加解密。
- 支持HMAC
- 派生材料由用户妥善保管，SBRK0在启动阶段使用并关闭，启动后不可使用。
- Hi3516CV610、Hi3511CV100不支持TDES。
- Hi3519DV500不支持192bits
使用流程
明文KEY传递
场景说明
当用于加解密的工作密钥由用户自己传入时，需使用到明文KEY相关的接口。KLAD将工作密钥传递给一个KEYSLOT。加解密时，加解密引擎取对应KEYSLOT中的KEY用于加解密。
工作流程
- KLAD 设备初始化。调用 ot_mpi_km_init 接口完成。
- 创建KEYSLOT句柄。调用ot_mpi_keyslot_create接口完成。
- 创建KLAD句柄。调用ot_mpi_klad_create 接口完成。
- 绑定KLAD和KEYSLOT句柄，调用ot_mpi_klad_attach 接口完成。
- 设置KLAD属性，调用ot_mpi_klad_set_attr接口完成。
- 设置明文KEY，调用ot_mpi_klad_set_clear_key接口完成。
- 解绑定KLAD和KEYSLOT句柄，调用ot_mpi_klad_detach接口完成。
- 销毁KLAD句柄，调用ot_mpi_klad_destroy接口完成。
- 去初始化KLAD设备，调用接口ot_mpi_km_deinit接口完成。
注意事项
KEYSLOT句柄在配置KLAD的过程中必须已创建。
ROOTKEY传递
场景说明
当安全方案要求高的场景下采用，ROOTKEY经密钥解混淆、密钥派生后产生，经多级KLAD传递后得到一个真正的工作密钥。工作密钥存储在硬件中，用户不可读取。KLAD将工作密钥传递给一个KEYSLOT。加解密时，加解密引擎取对应KEYSLOT中的KEY用于加解密。
工作流程
- KLAD 设备初始化。调用 ot_mpi_km_init 接口完成。
- 创建KEYSLOT句柄。调用ot_mpi_keyslot_create接口完成。
- 创建KLAD句柄。调用ot_mpi_klad_create 接口完成。
- 绑定KLAD和KEYSLOT句柄，调用ot_mpi_klad_attach 接口完成。
- 设置KLAD属性，调用ot_mpi_klad_set_attr接口完成。
- Hi3516CV610、Hi3511CV100设置盐值，调用ot_mpi_klad_set_effective_key接口完成。Hi3519DV500设置一级KEY，调用ot_mpi_klad_set_session_key接口完成；设置二级KEY，调用ot_mpi_klad_set_content_key接口完成。
- 解绑定KLAD和KEYSLOT句柄，调用ot_mpi_klad_detach接口完成。
- 销毁KLAD句柄，调用ot_mpi_klad_destroy接口完成。
- 去初始化KLAD设备，调用接口ot_mpi_km_deinit接口完成。
注意事项
KEYSLOT句柄在配置KLAD的过程中必须已创建。
- session_key为一级密钥。
- content_key为二级密钥。
- Hi3516CV610、Hi3511CV100不支持二级KLAD派生，即不支持session_key和content_key。只支持使用effective_key，调用ot_mpi_klad_set_effective_key接口完成。
- Hi3516CV610、Hi3511CV100 OTP密钥区域对应派生密钥类型： obfu_mrk1对应密钥CRYPTO_KDF_HARD_KEY_TYPE_ERK_TEE、CRYPTO_KDF_HARD_KEY_TYPE_ERK_REE oem_rootkey1对应密钥CRYPTO_KDF_HARD_KEY_TYPE_ERK1_REE oem_rootkey2对应密钥CRYPTO_KDF_HARD_KEY_TYPE_ERK2_REE
OTP DRIVER
功能描述
OTP DRIVER主要实现OTP非易失性存储器的读写，对外提供两层接口：MPI 层、KAPI 层。
接口说明：
-
MPI 层
由用户层应用调用，为 CA/TA 提供OTP读写能力。
-
KAPI 层
由内核模块调用，为内核模块提供OTP读写能力。
功能描述：
OTP DRIVER支持按字节读、按字节写和按字读。
使用流程
OTP按字节读
场景说明
支持用户读取指定地址的一字节OTP数据。
工作流程
- OTP 设备初始化。调用 ot_mpi_otp_init 接口完成。
- 按字节读。调用ot_mpi_otp_read_byte 接口完成。
- 去初始化OTP设备，调用接口ot_mpi_otp_deinit接口完成。
OTP按字节写
场景说明
支持用户在指定地址写入一字节OTP数据。
工作流程
- OTP 设备初始化。调用 ot_mpi_otp_init 接口完成。
- 按字节写。调用ot_mpi_otp_write_byte 接口完成。
- 去初始化OTP设备，调用ot_mpi_otp_deinit接口完成。
OTP按字读
场景说明
支持用户读取指定地址的一字长OTP数据。
工作流程
- OTP 设备初始化。调用 ot_mpi_otp_init 接口完成。
- 按字读。调用ot_mpi_otp_read_word 接口完成。
- 去初始化OTP设备，调用接口ot_mpi_otp_deinit接口完成。
API参考
SPACC HASH API
以下 API 说明适用于 MPI, KAPI 两层接口，此处以MPI层接口为例，MPI层接口以 ot_mpi开头，KAPI层接口以kapi开头，后缀命名和参数均一致。KAPI层代码仅提供给在内核下有开发需求的用户使用，如无此需求，则只需使用MPI层接口，MPI层接口在Linux、U-Boot、OP-TEE三个环境下使用方式完全一致。 U-BOOT下如需使用安全子系统接口则应将安全子系统编译宏打开，在编译配置文件中设置 CONFIG_SECURITY_SUBSYS_ENABLE=y，并在使用安全子系统前调用 crypto_cipher_init() 接口初始化驱动，该接口对应的头文件为security_subsys_init.h。
ot_mpi_cipher_hash_init
【描述】
HASH 模块初始化。
【语法】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
无
ot_mpi_cipher_hash_deinit
【描述】
HASH 模块去初始化。
【语法】
【返回值】
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
该接口不会返回失败，若接口内出错会打印 warn 日志。
ot_mpi_cipher_hash_create
【描述】
创建HASH句柄，并配置算法参数。
【语法】
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
- mpi_hash_handle不能为空指针。
- 通道数可通过头文件crypto_features.h中宏定义CONFIG_HASH_VIRT_CHN_NUM进行调整。
ot_mpi_cipher_hash_update
【描述】
HASH或HMAC update 计算。
【语法】
td_s32 ot_mpi_cipher_hash_update(td_handle mpi_hash_handle, const crypto_buf_attr *src_buf, const td_u32 len);
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
- len 不可为0，且最大长度为4294901760（即16进制0xFFFF0000），无对齐要求（需保证为传入的buf长度）。
- src_buf目前只支持使用virt_addr类型（即通过malloc or kmalloc等接口申请的虚拟内存），不支持其他类型。
- 对于一段数据，调用一次update传入整段数据和调用多次update分段传入数据，结果相同。
ot_mpi_cipher_hash_finish
【描述】
HASH或HMAC计算获取摘要信息，并在计算成功的时候销毁HASH句柄。
【语法】
td_s32 ot_mpi_cipher_hash_finish(td_handle mpi_hash_handle, td_u8 *virt_addr, td_u32 buffer_len, td_u32 *result_len);
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
- 可不调用update接口，直接调用finish接口，表示计算空数据的HASH值。
- buffer_len输入值应该为传入buffer的大小，不应小于HASH算法对应的HASH值长度，输出为实际的HASH值长度。
ot_mpi_cipher_hash_set
【描述】
设置HASH句柄属性。
【语法】
td_s32 ot_mpi_cipher_hash_set(td_handle mpi_hash_handle, const crypto_hash_clone_ctx *hash_clone_ctx);
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
无
ot_mpi_cipher_hash_get
【描述】
获取HASH句柄属性。
【语法】
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
无
ot_mpi_cipher_hash_destroy
【描述】
销毁HASH句柄。
【语法】
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
- 必须已经创建了HASH句柄。
- 如已经调用了 ot_mpi_cipher_hash_finish 接口销毁 HASH 句柄，则不能再次调用该接口。
- 无论之前流程计算成功与否，均可调用该接口销毁HASH句柄。
ot_mpi_cipher_pbkdf2
【描述】
PBKDF2 计算。
【语法】
td_s32 ot_mpi_cipher_pbkdf2(const crypto_kdf_pbkdf2_param *param, td_u8 *out, const td_u32 out_len);
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
- param和out不能为空指针。
- 迭代次数超过10000次，out_len为1023的高压场景下，接口耗时较长超过10分钟。
TRNG
ot_mpi_cipher_trng_get_random
【描述】
获取4字节的硬件随机数。
【语法】
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
randnum不能为空指针。
ot_mpi_cipher_trng_get_multi_random
【描述】
获取指定字节的硬件随机数。
【语法】
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
- size不能为0，且不得大于1024
- randnum不能为空指针。
PKE
ot_mpi_cipher_pke_init
【描述】
pke 模块初始化。
【语法】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
无
ot_mpi_cipher_pke_deinit
【描述】
pke 模块去初始化。
【语法】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
无
ot_mpi_cipher_pke_rsa_sign
【描述】
RSA签名，签名对象必须为HASH值。
【语法】
td_s32 ot_mpi_cipher_pke_rsa_sign(
const drv_pke_rsa_priv_key *priv_key,
drv_pke_rsa_scheme scheme,
drv_pke_hash_type hash_type,
const drv_pke_data *input_hash,
drv_pke_data *sign);
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
priv_key、input_hash和sign不能为空指针；Hi3516CV610只支持SHA256的HASH。
ot_mpi_cipher_pke_rsa_verify
【描述】
RSA验签，与RSA签名相对应。
【语法】
td_s32 ot_mpi_cipher_pke_rsa_verify(
const drv_pke_rsa_pub_key *pub_key,
drv_pke_rsa_scheme scheme,
drv_pke_hash_type hash_type,
drv_pke_data *input_hash,
const drv_pke_data *sig
);
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
pub_key、input_hash、sig不能为空指针。
ot_mpi_cipher_pke_rsa_public_encrypt
【描述】
RSA公钥加密，与RSA私钥解密相对应。
【语法】
td_s32 ot_mpi_cipher_pke_rsa_public_encrypt(
drv_pke_rsa_scheme scheme,
drv_pke_hash_type hash_type,
const drv_pke_rsa_pub_key *pub_key,
const drv_pke_data *input,
const drv_pke_data *label,
drv_pke_data *output);
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
- pub_key、input和output不能为空指针。
- 使用label需要开启宏CONFIG_PKE_RSA_LABEL_SUPPORT。
ot_mpi_cipher_pke_rsa_private_decrypt
【描述】
RSA私钥解密，与RSA公钥加密相对应。
【语法】
td_s32 ot_mpi_cipher_pke_rsa_private_decrypt(
drv_pke_rsa_scheme scheme,
drv_pke_hash_type hash_type,
const drv_pke_rsa_priv_key *priv_key,
const drv_pke_data *input,
const drv_pke_data *label,
drv_pke_data *output);
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
- priv_key、input和output不能为空指针。
- 使用label需要开启宏CONFIG_PKE_RSA_LABEL_SUPPORT
ot_mpi_cipher_pke_ecc_gen_key
【描述】
ECC密钥生成。
【语法】
td_s32 ot_mpi_cipher_pke_ecc_gen_key(
drv_pke_ecc_curve_type curve_type,
const drv_pke_data *input_priv_key,
const drv_pke_data *output_priv_key,
const drv_pke_ecc_point *output_pub_key);
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
output_priv_key和output_pub_key不能为空指针。
ot_mpi_cipher_pke_ecc_gen_ecdh_key
【描述】
ECDH密钥交换。
【语法】
td_s32 ot_mpi_cipher_pke_ecc_gen_ecdh_key(
drv_pke_ecc_curve_type curve_type,
const drv_pke_ecc_point *input_pub_key,
const drv_pke_data *input_priv_key,
const drv_pke_data *output_shared_key);
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
input_pub_key、input_priv_key和output_shared_key不能为空指针。
ot_mpi_cipher_pke_ecdsa_sign
【描述】
ECC签名，签名对象必须为HASH值。
【语法】
td_s32 ot_mpi_cipher_pke_ecdsa_sign(
drv_pke_ecc_curve_type curve_type,
const drv_pke_data *priv_key,
const drv_pke_data *hash,
const drv_pke_ecc_sig *sig);
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
- priv_key、hash和sig不能为空指针。
- 可开启宏CONFIG_PKE_ECC_SECURITY_STRENGTH_CHECK，增加安全长度检查。
ot_mpi_cipher_pke_ecdsa_verify
【描述】
ECC签名验证，签名对象必须为HASH值。
【语法】
td_s32 ot_mpi_cipher_pke_ecdsa_verify(
drv_pke_ecc_curve_type curve_type,
const drv_pke_ecc_point *pub_key,
const drv_pke_data *hash,
const drv_pke_ecc_sig *sig
);
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
- pub_key、hash、sig不能为空指针。
- 可开启宏CONFIG_PKE_ECC_SECURITY_STRENGTH_CHECK，增加安全长度检查。
ot_mpi_cipher_pke_sm2_public_encrypt
【描述】
SM2公钥加密。
【语法】
td_s32 ot_mpi_cipher_pke_sm2_public_encrypt(
const drv_pke_ecc_point *pub_key,
const drv_pke_data *plain_text,
drv_pke_data *cipher_text);
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
pub_key、plain_text、cipher_text不能为空指针。
ot_mpi_cipher_pke_sm2_private_decrypt
【描述】
SM2私钥解密。
【语法】
td_s32 ot_mpi_cipher_pke_sm2_private_decrypt(
const drv_pke_data *priv_key,
const drv_pke_data *cipher_text,
drv_pke_data *plain_text);
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
priv_key、plain_text、cipher_text不能为空指针。
ot_mpi_cipher_pke_check_dot_on_curve
【描述】
检查点是否在曲线上。
【语法】
td_s32 ot_mpi_cipher_pke_check_dot_on_curve(drv_pke_ecc_curve_type curve_type, const drv_pke_ecc_point *pub_key, td_bool *is_on_curve);
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
curve_type、pub_key、is_on_curve不能为空指针。
ot_mpi_cipher_pke_sm2_dsa_hash
【描述】
使用sm3计算sm2签名验证的HASH值。
【语法】
td_s32 ot_mpi_cipher_pke_sm2_dsa_hash(const drv_pke_data *sm2_id, const drv_pke_ecc_point *pub_key, const drv_pke_msg *msg, drv_pke_data *hash);
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
sm2_id、pub_key、msg、hash不能为空指针。
ot_mpi_cipher_pke_eddsa_sign
【描述】
使用爱德华曲线进行EDDSA签名。
【语法】
td_s32 ot_mpi_cipher_pke_eddsa_sign(drv_pke_ecc_curve_type curve_type, const drv_pke_data *priv_key, const drv_pke_msg *msg, const drv_pke_ecc_sig *sig);
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
priv_key、msg、sig不能为空指针。
ot_mpi_cipher_pke_eddsa_verify
【描述】
使用爱德华曲线进行eddsa签名验证。
【语法】
td_s32 ot_mpi_cipher_pke_eddsa_verify(drv_pke_ecc_curve_type curve_type, const [drv_pke_ecc_point](#ZH-CN_TOPIC_0000001425627402) *pub_key, const [drv_pke_msg](#ZH-CN_TOPIC_0000001430000028) *msg, const [drv_pke_ecc_sig](#ZH-CN_TOPIC_0000001425787374) *sig);
td_s32 ot_mpi_cipher_pke_eddsa_verify(drv_pke_ecc_curve_type curve_type, const drv_pke_ecc_point *pub_key, const drv_pke_msg *msg, const drv_pke_ecc_sig *sig);
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
pub_key、msg、sig不能为空指针。
SPACC SYMC API
ot_mpi_cipher_symc_init
【描述】
SYMC 模块初始化。
【语法】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
无
ot_mpi_cipher_symc_deinit
【描述】
SYMC 模块去初始化。
【语法】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
该接口不会返回失败，若接口内出错会打印 warn 日志。
ot_mpi_cipher_symc_create
【描述】
SYMC 模块创建通道。
【语法】
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
- 最多只支持创建32个通道。Hi3516CV610、Hi3511CV100默认为8通道。
- 通道数可通过头文件crypto_features.h中宏定义CONFIG_SYMC_VIRT_CHN_NUM进行调整。
- symc_handle、symc_attr不能为空指针。
ot_mpi_cipher_symc_destroy
【描述】
SYMC 模块销毁通道。
【语法】
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
无。
ot_mpi_cipher_symc_set_config
【描述】
SYMC 模块设置算法参数。
【语法】
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
symc_ctrl不能为空指针。
ot_mpi_cipher_symc_attach
【描述】
SYMC 模块绑定 KEYSLOT 句柄。
【语法】
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
此接口应在ot_mpi_cipher_symc_set_config前调用。
ot_mpi_cipher_symc_encrypt
【描述】
SYMC 模块加密。
【语法】
td_s32 ot_mpi_cipher_symc_encrypt(td_handle symc_handle, const crypto_buf_attr *src_buf, const crypto_buf_attr *dst_buf, td_u32 length);
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
- src_buf和dst_buf 仅支持 phys_addr 内存类型。
- src_buf和dst_buf 不能为空指针。
ot_mpi_cipher_symc_decrypt
【描述】
SYMC 模块解密。
【语法】
td_s32 ot_mpi_cipher_symc_decrypt(td_handle symc_handle, const crypto_buf_attr *src_buf, const crypto_buf_attr *dst_buf, td_u32 length);
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
- src_buf和dst_buf仅支持 phys_addr 内存类型。
- src_buf和dst_buf不能为空指针。
ot_mpi_cipher_symc_get_tag
【描述】
SYMC 模块获取 Tag 值。
【语法】
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
tag不能为空指针。
ot_mpi_cipher_mac_start
【描述】
SYMC 模块创建 MAC 句柄。
【语法】
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
symc_handle、mac_attr不能为空指针。
ot_mpi_cipher_mac_update
【描述】
对传入 SYMC 模块的数据进行 MAC 计算。
【语法】
td_s32 ot_mpi_cipher_mac_update(td_handle symc_handle, const crypto_buf_attr *src_buf, td_u32 length);
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
- length 要求为16字节的整数倍且不为0，最大长度为4294901760（即16进制0xFFFF0000）；
- src_buf不能为空指针。
ot_mpi_cipher_mac_finish
【描述】
获取 SYMC 模块数据的 MAC 计算结果。
【语法】
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_cipher.h
- 库文件：libot_mpi_cipher.a
【注意】
mac、mac_length不能为空指针。
KM
ot_mpi_km_init
【描述】
初始化KLAD模块。
【语法】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_km.h
- 库文件：libot_mpi_km.a
【注意】
无
ot_mpi_km_deinit
【描述】
去初始化KLAD模块。
【语法】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_km.h
- 库文件：libot_mpi_km.a
【注意】
km模块必须已经初始化。
ot_mpi_klad_create
【描述】
创建KLAD句柄。
【语法】
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_km.h
- 库文件：libot_mpi_km.a
【注意】
mpi_klad_handle不能为空。
ot_mpi_klad_destroy
【描述】
销毁KLAD句柄。
【语法】
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_km.h
- 库文件：libot_mpi_km.a
【注意】
- KLAD句柄必须已创建。
- 销毁KLAD句柄的task必须与创建KLAD句柄的task是同一个。
ot_mpi_klad_attach
【描述】
绑定KLAD句柄与KEYSLOT通道。
【语法】
td_s32 ot_mpi_klad_attach(crypto_handle mpi_klad_handle, km_klad_dest_type klad_type, crypto_handle mpi_keyslot_handle);
【参数】
当klad_type为MCIPHER或HMAC时，指KEYSLOT句柄；当klad_type为FLASH，指km_klad_flash_key_type。 |
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_km.h
- 库文件：libot_mpi_km.a
【注意】
- KLAD句柄必须已创建。
- 执行绑定操作的task必须与创建KLAD句柄的task是同一个。
ot_mpi_klad_detach
【描述】
解绑KLAD句柄与KEYSLOT通道。
【语法】
td_s32 ot_mpi_klad_detach(crypto_handle mpi_klad_handle, km_klad_dest_type klad_type, crypto_handle mpi_keyslot_handle);
【参数】
当klad_type为MCIPHER或HMAC时，指KEYSLOT句柄；当klad_type为FLASH，指km_klad_flash_key_type。 |
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_km.h
- 库文件：libot_mpi_km.a
【注意】
- KLAD句柄必须已创建。
- KLAD句柄必须已绑定了KEYSLOT通道。
- 执行解绑操作的task必须与创建KLAD句柄的task是同一个。
ot_mpi_klad_set_attr
【描述】
设置KLAD句柄属性。
【语法】
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_km.h
- 库文件：libot_mpi_km.a
【注意】
- KLAD句柄必须已创建。
- KLAD句柄属性指针不能为空。
- 执行set操作的task必须与创建KLAD句柄的task是同一个。
ot_mpi_klad_get_attr
【描述】
获取KLAD句柄属性。
【语法】
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_km.h
- 库文件：libot_mpi_km.a
【注意】
- KLAD句柄必须已创建。
- KLAD句柄属性指针不能为空。
- 执行get操作的task必须与创建KLAD句柄的task是同一个。
ot_mpi_klad_set_session_key
【描述】
设置密文密钥一级密钥。
【语法】
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_km.h
- 库文件：libot_mpi_km.a
【注意】
- KLAD句柄必须已创建。
- 存储一级key属性的指针不能为空。
- 执行操作的task必须与创建KLAD句柄的task是同一个。
- Hi3516CV610、Hi3511CV100不支持此接口。
ot_mpi_klad_set_content_key
【描述】
设置密文密钥二级密钥。
【语法】
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_km.h
- 库文件：libot_mpi_km.a
【注意】
- KLAD句柄必须已创建。
- 存储二级key属性的指针不能为空。
- 执行操作的task必须与创建KLAD句柄的task是同一个。
- Hi3516CV610、Hi3511CV100不支持此接口。
ot_mpi_klad_set_clear_key
【描述】
设置明文密钥。
【语法】
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_km.h
- 库文件：libot_mpi_km.a
【注意】
- KLAD句柄必须已创建。
- 存储明文key属性的指针不能为空。
- 执行操作的task必须与创建KLAD句柄的task是同一个。
ot_mpi_keyslot_create
【描述】
创建KEYSLOT句柄。
【语法】
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_km.h
- 库文件：libot_mpi_km.a
【注意】
- Hi3516CV610对称算法支持2个硬件通道，Hi3511CV100对称算法支持8个硬件通道，两者的hash算法都只支持2个硬件通道。
- km_keyslot_type参数目前不生效，默认为KM_KEYSLOT_TYPE_MCIPHER，实际的密钥类型由ot_mpi_klad_attach接口km_klad_dest_type参数决定。
ot_mpi_keyslot_destroy
【描述】
销毁KEYSLOT句柄。
【语法】
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_km.h
- 库文件：libot_mpi_km.a
【注意】
- KEYSLOT句柄必须已创建。
- 执行操作的task必须与创建KEYSLOT句柄的task是同一个。
- 此API是销毁KM模块中KEYSLOT句柄的相关资源，销毁后对应的KEYSLOT行为与具体芯片有关。不要在销毁后再使用此KEYSLOT。
ot_mpi_klad_set_effective_key
【描述】
设置硬件派生密钥。
【语法】
td_s32 ot_mpi_klad_set_effective_key(crypto_handle mpi_klad_handle, const km_klad_effective_key *key);
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ot_mpi_km.h
- 库文件：libot_mpi_km.a
【注意】
- KLAD句柄必须已创建。
- 存储effective key属性的指针不能为空。
- 执行操作的task必须与创建KLAD句柄的task是同一个。
OTP
ot_mpi_otp_init
【描述】
OTP模块初始化。
【语法】
【返回值】
参见错误码 |
【需求】
- 头文件：ss_mpi_otp.h
- 库文件：libss_mpi_otp.a
【注意】
无
ot_mpi_otp_deinit
【描述】
OTP模块去初始化。
【语法】
【返回值】
参见错误码 |
【需求】
- 头文件：ss_mpi_otp.h
- 库文件：libss_mpi_otp.a
【注意】
无。
ot_mpi_otp_read_word
【描述】
按字读取指定OTP地址中的值。
【语法】
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ss_mpi_otp.h
- 库文件：libss_mpi_otp.a
【注意】
data指针不能为空
ot_mpi_otp_read_byte
【描述】
按字节读取指定OTP地址中的值。
【语法】
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ss_mpi_otp.h
- 库文件：libss_mpi_otp.a
【注意】
data指针不能为空
ot_mpi_otp_write_byte
【描述】
按字节写OTP。
【语法】
【参数】
【返回值】
参见错误码 |
【需求】
- 头文件：ss_mpi_otp.h
- 库文件：libss_mpi_otp.a
【注意】
可执行写操作的OTP地址范围为(0x00~0x3ff)。
数据类型
SPACC Common
crypto_buffer_secure
【描述】
内存安全属性
【定义】
【成员】
【注意】
无
crypto_buf_attr
【描述】
内存属性
【定义】
typedef struct {
unsigned long long uapi_mem_handle;
unsigned long long addr_offset;
td_void *kapi_mem_handle;
unsigned long long phys_addr;
void *virt_addr;
crypto_buffer_secure buf_sec;
} crypto_buf_attr;
【成员】
【注意】
内存支持如下地址类型：
- 只传入virt_addr；
- 只传入 phys_addr；
- 同时传入virt_addr和phys_addr；
- HASH的摘要数据输入支持仅传入virt_addr或同时传入virt_addr和phys_addr；
- SYMC的加解密数据输入支持仅传入phys_addr或同时传入virt_addr和phys_addr。
SPACC HASH
crypto_hash_type
【描述】
HASH 算法类型。
【定义】
typedef enum {
/* Hash. */
CRYPTO_HASH_TYPE_SHA1 = 0xf690a0,
CRYPTO_HASH_TYPE_SHA224= 0x10690e0,
CRYPTO_HASH_TYPE_SHA256 = 0x1169100,
CRYPTO_HASH_TYPE_SHA384 = 0x127a180,
CRYPTO_HASH_TYPE_SHA512 = 0x137a200,
CRYPTO_HASH_TYPE_SM3 = 0x2169100,
/* HMAC. */
CRYPTO_HASH_TYPE_HMAC_SHA1 = 0x10f690a0,
CRYPTO_HASH_TYPE_HMAC_SHA224 = 0x110690e0,
CRYPTO_HASH_TYPE_HMAC_SHA256 = 0x11169100,
CRYPTO_HASH_TYPE_HMAC_SHA384 = 0x1127a180,
CRYPTO_HASH_TYPE_HMAC_SHA512 = 0x1137a200,
CRYPTO_HASH_TYPE_HMAC_SM3 = 0x12169100,
CRYPTO_HASH_TYPE_INVALID = 0xffffffff,
} crypto_hash_type;
【成员】
【注意】
Hi3511CV100与Hi3516CV610仅支持HMAC_SHA256和HMAC_SM3哈希算法。
crypto_hash_attr
【描述】
HASH 句柄属性。
【定义】
typedef struct {
td_u8 *key;
td_u32 key_len;
td_handle drv_keyslot_handle;
crypto_hash_type hash_type;
td_bool is_keyslot;
td_bool is_long_term;
} crypto_hash_attr;
【成员】
【注意】
- is_keyslot 为TD_FALSE时，使用软件算法，为TD_TRUE时，使用Keyslot和硬件算法；
- 当key_len为0时，key可为NULL；
- key_len 不超过 HASH 算法对应的 Block Size。（SHA256/SM3 为 64 Bytes，SHA384/SHA512 为 128 Bytes）；
- is_keyslot 为 TD_TRUE 时，drv_keyslot_handle应配置为Keyslot通道号。
- hash_type为非HMAC算法时，is_long_term值为0。
crypto_hash_clone_ctx
【描述】
HASH 计算中间数据结构体。
【定义】
typedef struct {
td_u32 length[2];
td_u32 state[CRYPTO_HASH_RESULT_SIZE_MAX_IN_WORD];
td_u32 tail_len;
crypto_hash_type hash_type;
td_u8 o_key_pad[CRYPTO_HASH_BLOCK_SIZE_MAX];
td_u8 i_key_pad[CRYPTO_HASH_BLOCK_SIZE_MAX];
td_u8 tail[CRYPTO_HASH_BLOCK_SIZE_MAX];
} crypto_hash_clone_ctx;
【成员】
【注意】
CRYPTO_HASH_RESULT_SIZE_MAX_IN_WORD 为 16，CRYPTO_HASH_BLOCK_SIZE_MAX 为 128。
crypto_kdf_pbkdf2_param
【描述】
HASH 计算中间数据结构体。
【定义】
typedef struct {
[crypto_hash_type](#ZH-CN_TOPIC_0000001425627390)crypto_hash_type hash_type;
td_u8 *password;
td_u32 plen;
td_u8 *salt;
td_u32 slen;
td_u16 count;
} crypto_kdf_pbkdf2_param;
【成员】
【注意】
此处hash_type成员支持的HASH算法类型仅为HMAC算法。
SPACC SYMC
crypto_symc_pack
【描述】
SYMC数据pack类型。
【定义】
【成员】
【注意】
无
crypto_symc_type
【描述】
SYMC 通道类型。
【定义】
typedef enum {
CRYPTO_SYMC_TYPE_NORMAL = 0x0,
CRYPTO_SYMC_TYPE_REG,
CRYPTO_SYMC_TYPE_MAX,
CRYPTO_SYMC_TYPE_INVALID = 0xffffffff,
} crypto_symc_type;
【成员】
【注意】
无
crypto_symc_attr
【描述】
SYMC 句柄属性。
【定义】
typedef struct {
crypto_symc_alg symc_alg;
crypto_symc_work_mode work_mode;
crypto_symc_type symc_type;
td_bool is_long_term;
} crypto_symc_attr;
【成员】
【注意】
- symc_alg 参数为软件算法配置，目前不支持，未生效。
- work_mode 参数为软件算法配置，目前不支持，未生效。
- symc_type 参数目前不生效，默认为DMA通道。
crypto_symc_alg
【描述】
SYMC 算法。
【定义】
typedef enum {
CRYPTO_SYMC_ALG_TDES = 0x0,
CRYPTO_SYMC_ALG_AES = 0x1,
CRYPTO_SYMC_ALG_SM4 = 0x2,
CRYPTO_SYMC_ALG_LEA = 0x3,
CRYPTO_SYMC_ALG_DMA = 0x4,
CRYPTO_SYMC_ALG_MAX,
CRYPTO_SYMC_ALG_INVALID = 0xffffffff,
} crypto_symc_alg;
【成员】
【注意】
无
crypto_symc_work_mode
【描述】
SYMC 算法工作模式。
【定义】
typedef enum {
CRYPTO_SYMC_WORK_MODE_ECB = 0x0,
CRYPTO_SYMC_WORK_MODE_CBC,
CRYPTO_SYMC_WORK_MODE_CTR,
CRYPTO_SYMC_WORK_MODE_OFB,
CRYPTO_SYMC_WORK_MODE_CFB,
CRYPTO_SYMC_WORK_MODE_CCM,
CRYPTO_SYMC_WORK_MODE_GCM,
CRYPTO_SYMC_WORK_MODE_CBC_MAC,
CRYPTO_SYMC_WORK_MODE_CMAC,
CRYPTO_SYMC_WORK_MODE_MAX,
CRYPTO_SYMC_WORK_MODE_INVALID = 0xffffffff,
} crypto_symc_work_mode;
【成员】
【注意】
- CFB工作模式在加密位宽为1bit且datasize大于2M时，计算会超时；
- 宏定义CONFIG_SYMC_WAIT_TIMEOUT_IN_US可调整超时时间。
crypto_symc_key_length
【描述】
SYMC 算法key长度。
【定义】
typedef enum {
CRYPTO_SYMC_KEY_64BIT = 0x0,
CRYPTO_SYMC_KEY_128BIT = 0x1,
CRYPTO_SYMC_KEY_192BIT = 0x2,
CRYPTO_SYMC_KEY_256BIT = 0x3,
CRYPTO_SYMC_KEY_LENGTH_MAX,
CRYPTO_SYMC_KEY_LENGTH_INVALID = 0xffffffff,
} crypto_symc_key_length;
【成员】
【注意】
无
crypto_symc_key_parity
【描述】
SYMC 算法key奇偶性。
【定义】
typedef enum {
CRYPTO_SYMC_KEY_EVEN = 0x0,
CRYPTO_SYMC_KEY_ODD = 0x1,
CRYPTO_SYMC_KEY_PARITY_MAX,
CRYPTO_SYMC_KEY_PARITY_INVALID = 0xffffffff,
} crypto_symc_key_parity;
【成员】
【注意】
当前默认为偶密钥，该配置项暂未使用。
crypto_symc_bit_width
【描述】
SYMC 算法位宽。
【定义】
typedef enum {
CRYPTO_SYMC_BIT_WIDTH_1BIT = 0x0,
CRYPTO_SYMC_BIT_WIDTH_8BIT = 0x1,
CRYPTO_SYMC_BIT_WIDTH_64BIT = 0x2,
CRYPTO_SYMC_BIT_WIDTH_128BIT = 0x3,
CRYPTO_SYMC_BIT_WIDTH_MAX,
CRYPTO_SYMC_BIT_WIDTH_INVALID = 0xffffffff,
} crypto_symc_bit_width;
【成员】
【注意】
无
crypto_symc_iv_change_type
【描述】
SYMC 算法iv 标志。
【定义】
typedef enum {
CRYPTO_SYMC_IV_DO_NOT_CHANGE = 0,
CRYPTO_SYMC_IV_CHANGE_ONE_PKG,
CRYPTO_SYMC_IV_CHANGE_ALL_PKG,
/* GCM. */
CRYPTO_SYMC_GCM_IV_DO_NOT_CHANGE,
CRYPTO_SYMC_GCM_IV_CHANGE_START,
CRYPTO_SYMC_GCM_IV_CHANGE_UPDATE,
CRYPTO_SYMC_GCM_IV_CHANGE_FINISH,
/* CCM. */
CRYPTO_SYMC_CCM_IV_DO_NOT_CHANGE,
CRYPTO_SYMC_CCM_IV_CHANGE_START,
CRYPTO_SYMC_CCM_IV_CHANGE_UPDATE,
CRYPTO_SYMC_CCM_IV_CHANGE_FINISH,
CRYPTO_SYMC_IV_CHANGE_MAX,
CRYPTO_SYMC_IV_CHANGE_INVALID = 0xffffffff,
} crypto_symc_iv_change_type;
【成员】
【注意】
- CCM 需要配置CRYPTO_SYMC_CCM_IV_CHANGE_START；
- GCM 需要配置CRYPTO_SYMC_GCM_IV_CHANGE_START；
- 其余算法无需配置该参数，初始化为0。
crypto_symc_config_aes_ccm_gcm
【描述】
SYMC 算法CCM&GCM参数。
【定义】
typedef struct {
crypto_buf_attr aad_buf;
td_u32 aad_len;
td_u32 data_len;
td_u32 tag_len;
td_u32 total_aad_len;
} crypto_symc_config_aes_ccm_gcm;
【成员】
【注意】
aad_buf的虚拟地址及物理地址字段均需填充，U-BOOT下物理地址及虚拟地址应为同一值。
crypto_symc_ctrl_t
【描述】
SYMC 算法参数。
【定义】
typedef struct {
crypto_symc_alg symc_alg;
crypto_symc_work_mode work_mode;
crypto_symc_key_length symc_key_length;
crypto_symc_key_parity key_parity;
crypto_symc_bit_width symc_bit_width;
crypto_symc_iv_change_type iv_change_flag;
td_u8 iv[CRYPTO_IV_LEN_IN_BYTES];
td_u32 iv_length;
td_void *param;
} crypto_symc_ctrl_t;
【成员】
【注意】
- key_parity参数未起作用，可暂时忽略；
- CRYPTO_IV_LEN_IN_BYTES 取值为 16。
crypto_symc_mac_attr
【描述】
SYMC 算法MAC参数。
【定义】
typedef struct {
td_bool is_long_term;
crypto_symc_alg symc_alg;
crypto_symc_work_mode work_mode;
crypto_symc_key_length symc_key_length;
td_u32 keyslot_chn;
} crypto_symc_mac_attr;
【成员】
【注意】
work_mode 当前支持CRYPTO_SYMC_WORK_MODE_CBC_MAC和CRYPTO_SYMC_WORK_MODE_CMAC。
PKE
drv_pke_rsa_priv_key
【描述】
RSA私钥结构体。
【定义】
typedef struct {
td_u8 *n; /* *< public modulus */
td_u8 *e; /* *< public exponent */
td_u8 *d; /* *< private exponent */
td_u8 *p; /* *< 1st prime factor */
td_u8 *q; /* *< 2nd prime factor */
td_u8 *dp; /* *< D % (P - 1) */
td_u8 *dq; /* *< D % (Q - 1) */
td_u8 *qp; /* *< 1 / (Q % P) */
td_u16 n_len; /* *< length of public modulus */
td_u16 e_len; /* *< length of public exponent */
td_u16 d_len; /* *< length of private exponent */
td_u16 p_len; /* *< length of 1st prime factor,should be half of u16NLen */
td_u16 q_len; /* *< length of 2nd prime factor,should be half of u16NLen */
td_u16 dp_len; /* *< length of D % (P - 1),should be half of u16NLen */
td_u16 dq_len; /* *< length of D % (Q - 1),should be half of u16NLen */
td_u16 qp_len; /* *< length of 1 / (Q % P),should be half of u16NLen */
} drv_pke_rsa_priv_key;
【成员】
【注意】
p、q用于RSA密钥生成，dp、dq、qp用于crt解密算法。
drv_pke_rsa_pub_key
【描述】
RSA公钥结构体。
【定义】
typedef struct {
td_u8 *n; /* point to public modulus */
td_u8 *e; /* point to public exponent */
td_u16 len; /* length of public modulus, max value is 512Byte */
} drv_pke_rsa_pub_key;
【成员】
【注意】
公钥指数e需在前面填充0，直到长度与公钥模数n相同。
drv_pke_data
【描述】
PKE中高频使用的数据结构体，有数据内容和长度两个属性。
【定义】
【成员】
【注意】
无。
drv_pke_buffer_secure
【描述】
数据所在buffer的安全属性枚举类型。
【定义】
typedef enum {
DRV_PKE_BUF_NONSECURE = 0x00,
DRV_PKE_BUF_SECURE,
DRV_PKE_BUF_INVALID = 0xffffffff,
} drv_pke_buffer_secure;
【成员】
【注意】
无。
drv_pke_msg
【描述】
PKE中高频使用的数据结构体，比drv_pke_data多一个buffer属性。
【定义】
【成员】
【注意】
buf_sec参数当前暂未使用。
drv_pke_len
【描述】
ECC密钥字节长度枚举类型。
【定义】
typedef enum {
DRV_PKE_LEN_192 = 24,
DRV_PKE_LEN_224 = 28,
DRV_PKE_LEN_256 = 32,
DRV_PKE_LEN_384 = 48,
DRV_PKE_LEN_448 = 56,
DRV_PKE_LEN_512 = 64,
DRV_PKE_LEN_521 = 68,
DRV_PKE_LEN_576 = 72,
DRV_PKE_LEN_1024 = 128,
DRV_PKE_LEN_1536 = 192,
DRV_PKE_LEN_2048 = 256,
DRV_PKE_LEN_3072 = 384,
DRV_PKE_LEN_4096 = 512,
DRV_PKE_LEN_MAX,
DRV_PKE_LEN_INVALID = 0xffffffff,
} drv_pke_len;
【成员】
【注意】
Hi3519DV500不支持DRV_PKE_LEN_192、DRV_PKE_LEN_224、DRV_PKE_LEN_448、DRV_PKE_LEN_1024、DRV_PKE_LEN_1536。
drv_pke_ecc_curve_type
【描述】
ECC曲线类型。
【定义】
typedef enum {
DRV_PKE_ECC_TYPE_RFC5639_P256 = 0x20,
DRV_PKE_ECC_TYPE_RFC5639_P384 = 0x430,
DRV_PKE_ECC_TYPE_RFC5639_P512 = 0x840,
DRV_PKE_ECC_TYPE_FIPS_P256K = 0xc20,
DRV_PKE_ECC_TYPE_FIPS_P192R = 0x1018,
DRV_PKE_ECC_TYPE_FIPS_P224R = 0x141c,
DRV_PKE_ECC_TYPE_FIPS_P256R = 0x1820,
DRV_PKE_ECC_TYPE_FIPS_P384R = 0x1c30,
DRV_PKE_ECC_TYPE_FIPS_P521R = 0x2048,
DRV_PKE_ECC_TYPE_RFC7748 = 0x2420,
DRV_PKE_ECC_TYPE_RFC7748_448 = 0x2838,
DRV_PKE_ECC_TYPE_RFC8032 = 0x2c20,
DRV_PKE_ECC_TYPE_SM2 = 0x3020,
DRV_PKE_ECC_TYPE_MAX,
DRV_PKE_ECC_TYPE_INVALID = 0xffffffff,
} drv_pke_ecc_curve_type;
【成员】
【注意】
Hi3519DV500不支持DRV_PKE_ECC_TYPE_FIPS_P192R、DRV_PKE_ECC_TYPE_FIPS_P224R。
drv_pke_ecc_curve
【描述】
ECC曲线参数。
【定义】
typedef struct {
const td_u8 *p; /* prime specifying the base field.*/
const td_u8 *a; /* Curve parameter a.*/
const td_u8 *b; /* Curve parameter b.*/
const td_u8 *gx; /* X coordinates of G which is a base point on the curve. */
const td_u8 *gy; /* Y coordinates of G which is a base point on the curve. */
const td_u8 *n; /* Prime which is the order of G point. */
td_u32 h; /* Cofactor, which is the order of the elliptic curve divided by the order of the point G. */
drv_pke_len ksize; /* Ecc key size in bytes. It corresponds to the size in bytes of the prime. */
drv_pke_ecc_curve_type ecc_type; /* Type of ECC curve */
} drv_pke_ecc_curve;
【成员】
【注意】
无。
drv_pke_ecc_point
【描述】
描述ECC曲线中的点的结构体。
【定义】
typedef struct {
td_u8 *x; /* X coordinates of the generated public key */
td_u8 *y; /* Y coordinates of the generated public key */
td_u32 length;
} drv_pke_ecc_point;
【成员】
【注意】
无。
drv_pke_ecc_sig
【描述】
描述ECC签名结果的结构体。
【定义】
typedef struct {
td_u8 *r; /* r component of the signature. */
td_u8 *s; /* s component of the signature. */
td_u32 length;
} drv_pke_ecc_sig;
【成员】
【注意】
无。
drv_pke_rsa_scheme
【描述】
描述RSA填充方式的枚举类型。
【定义】
typedef enum {
DRV_PKE_RSA_SCHEME_PKCS1_V15 = 0x00, /* PKCS#1 V15 */
DRV_PKE_RSA_SCHEME_PKCS1_V21, /* PKCS#1 V21, PSS for signing, OAEP for encryption */
DRV_PKE_RSA_SCHEME_MAX,
DRV_PKE_RSA_SCHEME_INVALID = 0xffffffff,
} drv_pke_rsa_scheme;
【成员】
【注意】
无。
drv_pke_hash_type
【描述】
PKE 模块的HASH算法枚举类型。
【定义】
typedef enum {
DRV_PKE_HASH_TYPE_SHA1 = 0x00, /* Suggest Not to use */
DRV_PKE_HASH_TYPE_SHA224,
DRV_PKE_HASH_TYPE_SHA256,
DRV_PKE_HASH_TYPE_SHA384,
DRV_PKE_HASH_TYPE_SHA512,
DRV_PKE_HASH_TYPE_SM3,
DRV_PKE_HASH_TYPE_MAX,
DRV_PKE_HASH_TYPE_INVALID = 0xffffffff,
} drv_pke_hash_type;
【成员】
【注意】
Hi3511CV100与Hi3516CV610 rsa加解密仅支持SHA256算法。
KM
km_keyslot_type
【描述】
KM 模块支持的 KEYSLOT 类型。
【定义】
typedef enum {
KM_KEYSLOT_TYPE_MCIPHER = 0x00,
KM_KEYSLOT_TYPE_HMAC,
KM_KEYSLOT_TYPE_MAX,
KM_KEYSLOT_TYPE_INVALID = 0xffffffff,
} km_keyslot_type;
【成员】
【注意】
无。
km_klad_hmac_type
【描述】
Klad 支持的 HMAC 类型。
【定义】
typedef enum {
KM_KLAD_HMAC_SHA1 = 0x20, /* Do Not Recommend to Use */
KM_KLAD_HMAC_SHA224, /* Software Kdf not support */
KM_KLAD_HMAC_SHA256,
KM_KLAD_HMAC_SHA384,
KM_KLAD_HMAC_SHA512,
KM_KLAD_HMAC_SM3 = 0x30,
KM_KLAD_HMAC_MAX,
KM_KLAD_HMAC_INVALID = 0xffffffff,
} km_klad_hmac_type;
【成员】
【注意】
Hi3511CV100与Hi3516CV610不支持HMAC_SHA1，HMAC_SHA224，HMAC_SHA384及HMAC_SHA512算法。
km_klad_sec
【描述】
密钥安全属性。
【定义】
typedef enum {
KM_KLAD_SEC_DISABLE = 0,
KM_KLAD_SEC_ENABLE,
KM_KLAD_SEC_MAX,
KM_KLAD_SEC_INVALID = 0xffffffff,
} km_klad_sec;
【成员】
【注意】
无。
km_klad_level
【描述】
密钥层级。
【定义】
typedef enum {
KM_KLAD_LEVEL1 = 0,
KM_KLAD_LEVEL_MAX,
KM_KLAD_LEVEL_INVALID = 0xffffffff,
} km_klad_level;
【成员】
【注意】
无。
km_klad_alg_type
【描述】
密钥派生算法。
【定义】
typedef enum {
KM_KLAD_ALG_TYPE_TDES = 0, /* Do Not Recommend to Use */
KM_KLAD_ALG_TYPE_AES,
KM_KLAD_ALG_TYPE_SM4,
KM_KLAD_ALG_TYPE_MAX,
KM_KLAD_ALG_TYPE_INVALID = 0xffffffff,
} km_klad_alg_type;
【成员】
【注意】
无。
km_crypto_alg
【描述】
派生出的密钥可用于的模块和对应算法。
【定义】
typedef enum {
KM_CRYPTO_ALG_AES = 0x20,
KM_CRYPTO_ALG_LEA = 0x40, /* Flash online decryption and Cipher offline encryption */
KM_CRYPTO_ALG_SM4 = 0x50,
KM_CRYPTO_ALG_TDES = 0x70, /* Do Not Recommend to Use */
KM_CRYPTO_ALG_HMAC_SHA1 = 0xA0, /* Do Not Recommend to Use */
KM_CRYPTO_ALG_HMAC_SHA2 = 0xA1,
KM_CRYPTO_ALG_HMAC_SM3 = 0xA2,
KM_CRYPTO_ALG_MAX,
KM_CRYPTO_ALG_INVALID = 0xffffffff,
} km_crypto_alg;
【成员】
【注意】
无。
km_klad_dest_type
【描述】
派生出的密钥将被送往的模块。
【定义】
typedef enum {
KM_KLAD_DEST_TYPE_MCIPHER = 0x00, /* keyslot for mcipher */
KM_KLAD_DEST_TYPE_HMAC, /* keyslot for hmac */
KM_KLAD_DEST_TYPE_FLASH, /* flash controller, for flash on line decryption and authentication */
KM_KLAD_DEST_TYPE_NPU, /* for NPU */
KM_KLAD_DEST_TYPE_MAX,
KM_KLAD_DEST_TYPE_INVALID = 0xffffffff,
} km_klad_dest_type;
【成员】
【注意】
无。
km_klad_flash_key_type
【描述】
定义 flash 在线解密和在线解密校验密钥类型。
【定义】
typedef enum {
KM_KLAD_FLASH_KEY_TYPE_REE_DEC = 0x00, /* REE flash online decryption key */
KM_KLAD_FLASH_KEY_TYPE_TEE_DEC, /* TEE flash online decryption key */
KM_KLAD_FLASH_KEY_TYPE_TEE_AUT, /* TEE flash online authentication key */
KM_KLAD_FLASH_KEY_TYPE_MAX,
KM_KLAD_FLASH_KEY_TYPE_INVALID = 0xffffffff,
} km_klad_flash_key_type;
【成员】
【注意】
无。
km_klad_key_parity
【描述】
定义密钥奇偶属性。
【定义】
typedef enum {
KM_KLAD_KEY_EVEN = 0x0, /* even key */
KM_KLAD_KEY_ODD = 0x1, /* odd key */
KM_KLAD_KEY_PARITY_MAX,
KM_KLAD_KEY_PARITY_INVALID = 0xffffffff,
} km_klad_key_parity;
【成员】
【注意】
无。
km_klad_config
【描述】
定义KLAD根密钥属性。
【定义】
typedef struct {
td_u32 rootkey_type; /* Keyladder rootkey type, KM_KLAD_KEY_TYPE_xxx. */
} km_klad_config;
enum {
/* SBRK0, TEE Global Boot Root Key0, delivered from MRK1, soc_tee_enable and Hash of TEE Root Public Key */
KM_KLAD_KEY_TYPE_SBRK0 = 0x03000000,
/* SBRK1, TEE Global Boot Root Key1, delivered from MRK1, soc_tee_enable and Hash of TEE Root Public Key */
KM_KLAD_KEY_TYPE_SBRK1,
/* SBRK2, TEE Global Boot Root Key2, delivered from MRK1, soc_tee_enable and Hash of TEE Root Public Key */
KM_KLAD_KEY_TYPE_SBRK2,
/* ABRK0, REE Global Boot Root Key0, delivered from MRK1 */
KM_KLAD_KEY_TYPE_ABRK0,
/* ABRK1, REE Global Boot Root Key1, delivered from MRK1 */
KM_KLAD_KEY_TYPE_ABRK1,
/* ABRK2, REE Global Boot Root Key2, delivered from MRK1 */
KM_KLAD_KEY_TYPE_ABRK2,
/* DRK0, TEE unique data decryption root key, delivered from USK */
KM_KLAD_KEY_TYPE_DRK0,
/* DRK1, REE unique data decryption root key, delivered from USK */
KM_KLAD_KEY_TYPE_DRK1,
/* RDRK0, TEE random data decryption root key, delivered from RUSK */
KM_KLAD_KEY_TYPE_RDRK0,
/* RDRK1, REE random data decryption root key, delivered from RUSK */
KM_KLAD_KEY_TYPE_RDRK1,
/* PSK, delivered from MRK1 */
KM_KLAD_KEY_TYPE_PSK,
/* ODRK0, TEE flash online decryption root key, delivered from MRK0/1,
soc_tee_enable and Hash of TEE Root Public Key */
KM_KLAD_KEY_TYPE_ODRK0,
/* OARK0 TEE flash online authentication root key, delivered from MRK0/1,
soc_tee_enable and Hash of TEE Root Public Key */
KM_KLAD_KEY_TYPE_OARK0,
/* ODRK1, REE flash online decryption root key, delivered from MRK1 */
KM_KLAD_KEY_TYPE_ODRK1,
/* MDRK0 */
KM_KLAD_KEY_TYPE_MDRK0,
/* MDRK1 */
KM_KLAD_KEY_TYPE_MDRK1,
/* MDRK2 */
KM_KLAD_KEY_TYPE_MDRK2,
/* MDRK3 */
KM_KLAD_KEY_TYPE_MDRK3,
KM_KLAD_KEY_TYPE_ABRK_REE,
KM_KLAD_KEY_TYPE_ABRK_TEE,
KM_KLAD_KEY_TYPE_RDRK_REE,
KM_KLAD_KEY_TYPE_RDRK_TEE,
KM_KLAD_KEY_TYPE_ERK_TEE,
KM_KLAD_KEY_TYPE_ERK_REE
};
【成员】
【注意】
无。
km_klad_key_secure_config
【描述】
密钥的安全属性配置。
【定义】
typedef struct {
km_klad_sec key_sec; /* Secure key can only be used by TEE CPU and AIDSP locked cipher and hash channel */
/* Only the cipher or hash channel which is locked by same CPU as keyladder can use this key,
valid only for TEE CPU and AIDSP */
td_bool master_only_enable;
td_bool dest_buf_sec_support; /* The destination buffer of target engine can be secure. */
td_bool dest_buf_non_sec_support; /* The destination buffer of target engine can be non-secure. */
td_bool src_buf_sec_support; /* The source buffer of target engine can be secure. */
td_bool src_buf_non_sec_support; /* The source buffer of target engine can be non-secure. */
} km_klad_key_secure_config;
【成员】
只有锁定 SYMC 或 HASH 通道的核或模块类型与创建 KLAD 句柄一致时，才可以使用该密钥，S 核和 AIDSP 创建的 KLAD 派生的密钥会对该属性进行判断。 |
|
【注意】
- master_only_enable参数在Hi3516CV610及Hi3511CV100上配置无效，无需关注。
- tee环境下，密钥加解密出的数据或者密钥要加解密的数据放在安全缓冲区。
- ree环境下，密钥加解密出的数据或者密钥要加解密的数据放在非安全缓冲区。
km_klad_key_config
【描述】
密钥属性配置。
【定义】
typedef struct {
km_crypto_alg engine; /* The content key can be used for which algorithm of the crypto engine. */
td_bool decrypt_support; /* The content key can be used for decrypting. */
td_bool encrypt_support; /* The content key can be used for encrypting. */
} km_klad_key_config;
【成员】
【注意】
无。
km_klad_attr
【描述】
KLAD句柄属性。
【定义】
typedef struct {
km_klad_config klad_cfg; /* The keyladder configuration, valid for hardware key. */
km_klad_key_config key_cfg; /* The content key configuration. */
km_klad_key_secure_config key_sec_cfg; /* The content key security configuration. */
td_u32 rkp_sw_cfg; /* The software configuration for NPU */
} km_klad_attr;
【成员】
【注意】
在set_clear_key明文密钥属性配置中HMAC类型选择256或SM3时，key_cfg中engine属性配置无效。
km_klad_session_key
【描述】
多级密钥属性配置。
【定义】
typedef struct {
km_klad_level level; /* the level of session key. */
km_klad_alg_type alg; /* the algorithm used to derive session key. */
td_u32 key_size; /* the size of session key, should be 16. */
td_u8 *key; /* the session key. */
} km_klad_session_key;
【成员】
【注意】
无。
km_klad_content_key
【描述】
密文密钥属性配置。
【定义】
typedef struct {
km_klad_alg_type alg; /* The algorithm of the content key. */
td_u32 key_size; /* The size of content key, should be 16 or 32. */
td_u8 *key; /* The content key. */
km_klad_key_parity key_parity; /* Odd or even key flag. */
} km_klad_content_key;
【成员】
【注意】
当前只支持使用偶密钥。
km_klad_clear_key
【描述】
明文密钥属性配置。
【定义】
typedef struct {
km_klad_hmac_type hmac_type; /* hmac type, only send hmac key need to config. */
td_u32 key_size; /* The size of content key, 16, 24 or 32 for cipher, not more than block size for HMAC. */
td_u8 *key; /* The content key. */
km_klad_key_parity key_parity; /* Odd or even key flag. */
} km_klad_clear_key;
【成员】
明文密钥长度，对于 SYMC 模块只能为16、24或32字节，对于 HMAC 模块，则不应该大于对应 HMAC 类型的块大小。 |
|
【注意】
当前只支持使用偶密钥。
crypto_kdf_hard_alg
【描述】
KDF硬件派生算法
【定义】
typedef enum {
CRYPTO_KDF_HARD_ALG_SHA256 = 0,
CRYPTO_KDF_HARD_ALG_SM3,
CRYPTO_KDF_HARD_ALG_MAX
} crypto_kdf_hard_alg;
【成员】
【注意】
无
crypto_klad_key_size
【描述】
KDF硬件派生密钥长度
【定义】
typedef enum {
CRYPTO_KLAD_KEY_SIZE_128BIT,
CRYPTO_KLAD_KEY_SIZE_192BIT,
CRYPTO_KLAD_KEY_SIZE_256BIT,
} crypto_klad_key_size;
【成员】
【注意】
无
km_klad_effective_key
【描述】
硬件密钥属性配置。
【定义】
typedef struct {
crypto_kdf_hard_alg kdf_hard_alg;
td_bool key_parity;
crypto_klad_key_size key_size;
td_u8 *salt;
td_u32 salt_length;
td_bool oneway;
} km_klad_effective_key;
【成员】
【注意】
effective key的盐值长度固定为28字节。
OTP
无。
错误码
本章描述了CIPHER DRIVER、KM DRIVER、OTP DRIVER的错误码，便于开发人员理解与定位所发生的错误。
错误码结构与说明
Cipher驱动返回值通常有成功和失败两种类型，如表1所示。
表 1 Cipher驱动返回值
为了通过错误码更加清晰的标识错误发生的具体信息，采用了层级结构的信息拼接。其结构为：
Env(4 bits) | Layer(4 bits) | Modules(4 bits) | Reserved(12 bits) | Error Code(8 bits)
ENV
【描述】
错误码发生的操作系统环境。
【定义】
#define ERROR_ENV_LINUX 0x1
#define ERROR_ENV_ITRUSTEE 0x2
#define ERROR_ENV_OPTEE 0x3
#define ERROR_ENV_LITEOS 0x4
#define ERROR_ENV_SELITEOS 0x5
#define ERROR_ENV_NOOS 0x6
#define ERROR_ENV_FREERTOS 0x7
#define ERROR_ENV_ALIOS 0x8
【成员】
【注意】
Hi3519DV500不支持ERROR_ENV_FREERTOS和ERROR_ENV_ALIOS。
LAYER
【描述】
错误码发生的代码层级。
【定义】
enum {
ERROR_LAYER_UAPI = 0x1,
ERROR_LAYER_DISPATCH,
ERROR_LAYER_KAPI,
ERROR_LAYER_DRV,
ERROR_LAYER_HAL,
};
【成员】
【注意】
无
MODULE
【描述】
错误码发生的CIPHER模块。
【定义】
enum {
ERROR_MODULE_SYMC = 0x1,
ERROR_MODULE_HASH,
ERROR_MODULE_PKE,
ERROR_MODULE_TRNG,
ERROR_MODULE_KM,
ERROR_MODULE_OTP,
ERROR_MODULE_OTHER
};
【成员】
【注意】
无
错误类型
【描述】
错误码发生的具体错误类型。
【定义】
/* Common Error Code. 0x01 ~ 0x3F. */
ERROR_INVALID_PARAM = 0x1, /* return when the input param's value is not in the valid range. */
ERROR_PARAM_IS_NULL, /* return when the input param is NULL and required not NULL. */
ERROR_NOT_INIT, /* return when call other functions before call init function. */
ERROR_UNSUPPORT, /* return when some configuration is unsupport. */
ERROR_UNEXPECTED, /* return when unexpected error occurs. */
ERROR_TRY_TIMES, /* return when the number of try attempts failed. */
ERROR_CHN_BUSY, /* return when try to create one channel but all channels are busy. */
ERROR_CTX_CLOSED, /* return when using one ctx to do something but has been closed. */
ERROR_NOT_SET_CONFIG, /* return when not set_config but need for symc. */
ERROR_NOT_ATTACHED, /* return when not attach but need for symc. */
ERROR_NOT_SET_SESSION_KEY, /* return when not set_session_key but need for klad. */
ERROR_NOT_MAC_START, /* return when not mac_start but need for symc. */
ERROR_INVALID_HANDLE, /* return when pass one invalid handle. */
ERROR_GET_PHYS_ADDR, /* return when transfer from virt_addr to phys_addr failed. */
ERROR_SYMC_LEN_NOT_ALIGNED, /* return when length isn't aligned to 16-Byte except CTR/CCM/GCM. */
ERROR_SYMC_ADDR_NOT_ALIGNED, /* return when the phys_addr writing to register is not aligned to 4-Byte. */
ERROR_PKE_RSA_SAME_DATA, /* return when rsa exp_mod, the input is equal to output. */
ERROR_PKE_RSA_CRYPTO_V15_CHECK, /* return when rsa crypto v15 padding check failed. */
ERROR_PKE_RSA_CRYPTO_OAEP_CHECK, /* return when rsa crypto oaep padding check failed. */
ERROR_PKE_RSA_VERIFY_V15_CHECK, /* return when rsa verify v15 padding check failed. */
ERROR_PKE_RSA_VERIFY_PSS_CHECK, /* return when rsa verify pss padding check failed. */
ERROR_PKE_RSA_GEN_KEY, /* return when rsa generate key failed. */
ERROR_PKE_SM2_DECRYPT, /* return when sm2 decrypt failed. */
ERROR_ECDSA_SIGN_R_IS_ZERO, /* return when ecdsa sign, the sig_r is zero. */
ERROR_ECDSA_SIGN_S_IS_ZERO, /* return when ecdsa sign, the sig_s is zero. */
ERROR_PKE_ECDSA_VERIFY_CHECK, /* return when ecdsa verify check failed. */
ERROR_OTP_ADDR_NOT_ALIGNED, /* return when otp address is not aligned to 4. */
ERROR_HASH_ADDR_NOT_ALIGNED, /* return when hash data's address is not aligned */
ERROR_HASH_LEN_NOT_ALIGNED, /* return when hash length is not aligned to block size. */
ERROR_PKE_SM2_T_IS_ZERO, /* return when sm2 encrypt or decrypt kdf out is zero. */
/* Outer's Error Code. 0x40 ~ 0x5F. */
ERROR_MEMCPY_S = 0x40, /* return when call memcpy_s failed. */
ERROR_MALLOC, /* return when call xxx_malloc failed. */
ERROR_MUTEX_INIT, /* return when call xxx_mutex_init failed. */
ERROR_MUTEX_LOCK, /* return when call xxx_lock failed. */
/* Specific Error Code for UAPI. 0x60 ~ 0x6F. */
ERROR_DEV_OPEN_FAILED, /* return when open dev failed. */
ERROR_COUNT_OVERFLOW, /* return when call init too many times. */
/* Specific Error Code for Dispatch. 0x70 ~ 0x7F. */
ERROR_CMD_DISMATCH = 0x70, /* return when cmd is dismatched. */
ERROR_COPY_FROM_USER, /* return when call copy_from_user failed. */
ERROR_COPY_TO_USER, /* return when call copy_to_user failed. */
ERROR_MEM_HANDLE_GET, /* return when parse user's mem handle to kernel's mem handle failed. */
ERROR_GET_OWNER, /* return when call crypto_get_owner failed. */
/* Specific Error Code for KAPI. 0x80 ~ 0x8F. */
ERROR_PROCESS_NOT_INIT = 0x80, /* return when one process not call kapi_xxx_init first. */
ERROR_MAX_PROCESS, /* return when process's num is over the limit. */
ERROR_MEMORY_ACCESS, /* return when access the memory that does not belong to itself. */
ERROR_INVALID_PROCESS, /* return when the process accesses resources of other processes. */
/* Specific Error Code for DRV. 0x90 ~ 0x9F. */
/* Specific Error Code for HAL. 0xA0 ~ 0xAF. */
ERROR_HASH_LOGIC = 0xA0, /* return when hash logic's error occurs. */
ERROR_PKE_LOGIC, /* return when pke logic's error occurs. */
ERROR_INVALID_CPU_TYPE, /* return when logic get the invalid cpu type. */
ERROR_INVALID_REGISTER_VALUE, /* return when value in register is invalid. */
ERROR_INVALID_PHYS_ADDR, /* return when phys_addr is invalid. */
ERROR_OTP_PERMISSION, /* return when otp access is forbidden. */
ERROR_KM_LOGIC, /* return when km logic's error occurs. */
ERROR_KM_KL_LOGIC, /* return when km HKL logic's error occurs. */
ERROR_KM_KC_LOGIC, /* return when km KEY CTRL logic's error occurs. */
ERROR_KLAD_ROOTKEY_NOT_READY, /* return when klad rootkey is not ready. */
/* Specific Error Code for Timeout. 0xB0 ~ 0xBF. */
ERROR_GET_TRNG_TIMEOUT = 0xB0, /* return when logic get rnd timeout. */
ERROR_HASH_CLEAR_CHN_TIMEOUT, /* return when clear hash channel timeout. */
ERROR_HASH_CALC_TIMEOUT, /* return when hash calculation timeout. */
ERROR_SYMC_CLEAR_CHN_TIMEOUT, /* return when clear symc channel timeout. */
ERROR_SYMC_CALC_TIMEOUT, /* return when symc crypto timeout. */
ERROR_SYMC_GET_TAG_TIMEOUT, /* return when symc get tag timeout. */
ERROR_PKE_LOCK_TIMEOUT, /* return when pke lock timeout. */
ERROR_PKE_WAIT_DONE_TIMEOUT, /* return when pke wait done timeout. */
ERROR_PKE_ROBUST_WARNING, /* return when pke wait done timeout. */
ERROR_RKP_LOCK_TIMEOUT, /* return when rkp lock timeout. */
ERROR_RKP_CALC_TIMEOUT, /* return when rkp calculate timeout. */
ERROR_KLAD_COM_ROUTE_TIMEOUT, /* return when klad com route timeout. */
ERROR_OTP_TIMEOUT, /* return when otp wait timeout. */
ERROR_KEYSLOT_TIMEOUT, /* return when keyslot wait timeout. */
ERROR_KEYSLOT_LOCK, /* return when keyslot lock or unlock fail. */
ERROR_KLAD_TIMEOUT, /* return when klad wait timeout. */
ERROR_KLAD_LOCK, /* return when klad lock or unlock fail. */
【成员】
【注意】
- Hi3516CV610、Hi3511CV100错误码的起始值从1开始，即 ERROR_INVALID_PARAM = 0x1
- Hi3519DV500不支持ERROR_ECDSA_SIGN_R_IS_ZERO、ERROR_ECDSA_SIGN_S_IS_ZERO、ERROR_HASH_ADDR_NOT_ALIGNED、ERROR_HASH_LEN_NOT_ALIGNED、ERROR_KM_KL_LOGIC、ERROR_KM_KC_LOGIC、ERROR_KLAD_ROOTKEY_NOT_READY、ERROR_KLAD_COM_ROUTE_TIMEOUT。
网络安全注意事项
安全驱动
- Cipher驱动实现了标准的对称加密AES/TDES/SM4算法，非对称RSA、ECDSA/SM2/ED25519算法，摘要算法SHA/SM3/HMAC_SHA/SM3，密钥协商算法ECDH，密钥派生算法PBKDF2，没有使用任何私有算法。
-
对称算法使用建议：
- TDES为非安全算法，不建议使用。
- AES/SM4算法ECB模式为非安全算法，不建议使用。
- 对称算法的密钥的长度越长，安全等级越高，建议用户使用AES 128bits及以上的密钥。
-
非对称算法使用建议：
- RSA算法建议使用密钥长度3072bits及以上的密钥。
- RSA签名算法padding方式建议使用PSS padding方式。
- RSA加解密算法padding方式建议使用OAEP padding方式。
- ECDSA算法建议使用密钥长度256bits及以上的密钥。
- ECDSA算法曲线不建议使用NIST P256/384/521曲线。
-
摘要算法使用建议：
SHA/HMAC_SHA算法建议使用SHA256/HMAC_SHA256及以上的算法。
-
密钥协商算法使用建议：
ECDH算法建议使用密钥长度256bits及以上的密钥。
-
密钥派生算法使用建议：
- 迭代次数和安全性成正比，也与计算时间成正比，迭代次数越大，意味着计算密钥花费时间越长，同时抗暴力破解能力越强。对于性能不敏感或高安全性要求场景推荐迭代次数至少需要10000000次，其他场景迭代次数默认推荐至少10000次；对于性能有特殊要求的产品最低可以迭代1000次（NIST SP 800 -132）。
- 哈希函数推荐选择SHA256或更安全的哈希算法。
- 盐值至少16字节，应使用安全的随机数。
- 用于口令单向哈希时，其输出长度应该不小于256bit。
其他使用安全注意事项
JTAG接口
恶意者可通过JTAG接口，篡改系统和配置，恶意破坏系统。
建议用户采用以下措施：
- 产品出厂时，将JTAG接口从物理上删除。
- 芯片提供JTAG disable功能，软件通过写OTP，可从芯片层面直接永久关闭JTAG。
附录
HASH 不同算法对应参数
注：所有的长度以 bit 为单位。
默认关闭算法
通过删除smp/a7_linux/source/out/include/autoconf.h文件中与security_subsys相关的宏定义，可以裁剪security_subsys对外接口，从而减小重新编译后的.ko和静态库大小。
/* 使能hash相关接口的宏*/
CONFIG_HASH_SUPPORT
CONFIG_HASH_PBKDF2_SUPPORT
CONFIG_HASH_CLONE_SUPPORT
/* 使能SYMC相关接口的宏*/
CONFIG_SYMC_SUPPORT
CONFIG_SYMC_CCM_SUPPORT
CONFIG_SYMC_GCM_SUPPORT
CONFIG_SYMC_CMAC_SUPPORT
CONFIG_SYMC_CBC_MAC_SUPPORT
/* 使能PKE ECC相关接口的宏*/
CONFIG_PKE_ECC_SUPPORT
CONFIG_PKE_ECC_GEN_KEY_SUPPORT
CONFIG_PKE_ECC_ECDH_SUPPORT
CONFIG_PKE_ECC_ECDSA_SIGN_SUPPORT
CONFIG_PKE_ECC_ECDSA_VERIFY_SUPPORT
CONFIG_PKE_ECC_CHECK_DOT_ON_CURVE_SUPPORT
CONFIG_PKE_ECC_SM2_DSA_HASH_SUPPORT
CONFIG_PKE_ECC_SM2_PUB_ENC_SUPPORT
CONFIG_PKE_ECC_SM2_PRIV_DEC_SUPPORT
/* 使能PKE RSA相关接口的宏*/
CONFIG_PKE_RSA_SUPPORT
CONFIG_PKE_RSA_SIGN_SUPPORT
CONFIG_PKE_RSA_VERIFY_SUPPORT
CONFIG_PKE_RSA_PUB_ENC_SUPPORT
CONFIG_PKE_RSA_PRIV_DEC_SUPPORT
/* 使能大数计算相关接口的宏*/
CONFIG_PKE_MOD_SUPPORT
CONFIG_PKE_EXP_MOD_SUPPORT
/* 使能TRNG相关接口的宏*/
CONFIG_TRNG_GET_RANDOM_SUPPORT
CONFIG_TRNG_GET_MULTI_RANDOM_SUPPORT
/* 使能KM相关接口的宏*/
CONFIG_OT_KM_SUPPORT
CONFIG_KM_CLEAR_KEY_SUPPORT
CONFIG_KM_EFFECTIVE_KEY_SUPPORT
相关接口的功能由宏CONFIG_HASH_SUPPORT、CONFIG_SYMC_SUPPORT、CONFIG_PKE_ECC_SUPPORT和CONFIG_PKE_RSA_SUPPORT分别控制，要支持以上接口，需要先在代码中定义相应的宏。
- CONFIG_HASH_SUPPORT用于哈希功能
- CONFIG_SYMC_SUPPORT用于对称加密功能
- CONFIG_PKE_ECC_SUPPORT用于椭圆曲线加密（ECC）功能
- CONFIG_PKE_RSA_SUPPORT用于RSA加密功能