crypto
PSA Crypto模块提供平台安全架构（PSA）密码学接口，支持密钥管理、对称加密、非对称加密、认证加密、哈希摘要、消息认证码、密钥协商、密钥派生等密码学操作。该模块在使用前需调用psa_crypto_init进行初始化。
头文件清单
接口清单
Functions
psa_crypto_init
函数声明
头文件清单
功能说明
- 初始化PSA Crypto模块，在使用任何其他PSA Crypto接口前必须调用
- 完成密码服务模块的注册和资源分配
- 初始化密钥存储区及密码算法后端
前置条件
- 硬件安全子系统已就绪
- 随机数生成器硬件已初始化
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| PSA_SUCCESS(0) | 执行成功 | 模块初始化成功 |
| Other | 其他错误码，参考psa_status_t | 执行失败 |
Kconfig配置
| 配置项 | 宏类型 | 说明 | 默认值 |
|---|---|---|---|
| CONFIG_PSA_SERVICE_SUPPORT | 功能宏 | 支持PSA Crypto接口功能 | n |
| ENABLE_PSA_SAMPLE | 编译参与宏 | 控制PSA示例参与编译 | n |
psa_set_key_type
函数声明
头文件清单
功能说明
- 设置密钥属性结构体中的密钥类型字段
- 密钥类型决定了密钥的算法体系和操作能力
- 设置后密钥的比特长度会被重置为0
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| attributes | psa_key_attributes_t * | 密钥属性结构体指针 | 非NULL |
| type | psa_key_type_t | 密钥类型 | PSA_KEY_TYPE_*系列宏 |
psa_set_key_algorithm
函数声明
头文件清单
功能说明
- 设置密钥属性结构体中的算法字段
- 算法决定了密钥可执行的密码操作类型
- 不同密钥类型对应不同的有效算法范围
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| attributes | psa_key_attributes_t * | 密钥属性结构体指针 | 非NULL |
| alg | psa_algorithm_t | 算法标识 | PSA_ALG_*系列宏 |
psa_set_key_bits
函数声明
头文件清单
功能说明
- 设置密钥属性结构体中的密钥比特长度字段
- 比特长度用于密钥生成和导入时的校验
- 导入密钥时可为0，表示从数据中自动推断
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| attributes | psa_key_attributes_t * | 密钥属性结构体指针 | 非NULL |
| bits | size_t | 密钥比特长度 | 0 ~ PSA_MAX_KEY_BITS |
psa_set_key_lifetime
函数声明
头文件清单
功能说明
- 设置密钥属性结构体中的密钥生命周期字段
- 生命周期决定密钥的存储位置和持久性策略
- 持久化密钥在设备重启后仍然可用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| attributes | psa_key_attributes_t * | 密钥属性结构体指针 | 非NULL |
| lifetime | psa_key_lifetime_t | 密钥生命周期 | PSA_KEY_LIFETIME_*系列宏 |
psa_set_key_id
函数声明
头文件清单
功能说明
- 设置密钥属性结构体中的密钥标识符字段
- 密钥标识符用于持久化密钥的存储和检索
- 仅在持久化生命周期下设置有效
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| attributes | psa_key_attributes_t * | 密钥属性结构体指针 | 非NULL |
| key | psa_key_id_t | 密钥标识符 | PSA_KEY_ID_INIT或有效密钥ID |
psa_set_key_usage_flags
函数声明
头文件清单
功能说明
- 设置密钥属性结构体中的密钥用途标志字段
- 用途标志控制密钥允许执行的操作类型
- 可通过位或运算组合多种用途标志
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| attributes | psa_key_attributes_t * | 密钥属性结构体指针 | 非NULL |
| usage_flags | psa_key_usage_t | 密钥用途标志 | PSA_KEY_USAGE_*系列宏的位或组合 |
psa_reset_key_attributes
函数声明
头文件清单
功能说明
- 将密钥属性结构体重置为初始值
- 重置后所有属性字段恢复为默认值
- 用于复用属性结构体前清除先前设置
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| attributes | psa_key_attributes_t * | 密钥属性结构体指针 | 非NULL |
psa_get_key_attributes
函数声明
头文件清单
功能说明
- 获取指定密钥标识符对应的密钥属性
- 通过密钥标识符从密钥存储区检索属性信息
- 获取的属性包含密钥类型、比特长度、用途等完整信息
前置条件
- crypto模块已初始化
- 密钥key已存在
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| key | psa_key_id_t | 密钥标识符 | 有效密钥ID |
出参
| 名称 | 数据类型 | 输出说明 |
|---|---|---|
| attributes | psa_key_attributes_t | 密钥属性结构体 |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| PSA_SUCCESS(0) | 执行成功 | 获取密钥属性成功 |
| Other | 其他错误码，参考psa_status_t | 执行失败 |
psa_import_key
函数声明
psa_status_t psa_import_key(const psa_key_attributes_t *attributes, const uint8_t *data, size_t data_length, psa_key_id_t *key);
头文件清单
功能说明
- 将二进制格式的密钥数据导入到密钥存储区
- 根据属性结构体中的设置确定密钥类型和用途
- 导入成功后返回密钥标识符用于后续操作
前置条件
- crypto模块已初始化
- attributes已正确设置密钥类型、用途等信息
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| attributes | const psa_key_attributes_t * | 密钥属性结构体指针 | 非NULL且已正确设置 |
| data | const uint8_t * | 密钥数据指针 | 非NULL |
| data_length | size_t | 密钥数据长度 | > 0 |
出参
| 名称 | 数据类型 | 输出说明 |
|---|---|---|
| key | psa_key_id_t | 导入后的密钥标识符 |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| PSA_SUCCESS(0) | 执行成功 | 密钥导入成功 |
| Other | 其他错误码，参考psa_status_t | 执行失败 |
psa_generate_key
函数声明
头文件清单
功能说明
- 根据密钥属性生成新的密钥
- 密钥类型和比特长度由属性结构体决定
- 生成的密钥存储在密钥存储区并返回标识符
前置条件
- crypto模块已初始化
- attributes已正确设置密钥类型、比特长度等信息
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| attributes | const psa_key_attributes_t * | 密钥属性结构体指针 | 非NULL且已正确设置 |
出参
| 名称 | 数据类型 | 输出说明 |
|---|---|---|
| key | psa_key_id_t | 生成的密钥标识符 |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| PSA_SUCCESS(0) | 执行成功 | 密钥生成成功 |
| Other | 其他错误码，参考psa_status_t | 执行失败 |
psa_export_public_key
函数声明
psa_status_t psa_export_public_key(psa_key_id_t key, uint8_t *data, size_t data_size, size_t *data_length);
头文件清单
功能说明
- 导出指定密钥对应的公钥数据
- 适用于非对称密钥对，提取其中的公钥部分
- 导出的公钥可用于分发或验签操作
前置条件
- crypto模块已初始化
- 密钥key已存在且为非对称密钥对
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| key | psa_key_id_t | 密钥标识符 | 有效密钥ID |
| data_size | size_t | 输出缓冲区大小 | >= 公钥数据长度 |
出参
| 名称 | 数据类型 | 输出说明 |
|---|---|---|
| data | uint8_t | 公钥数据输出缓冲区 |
| data_length | size_t | 实际输出的公钥数据长度 |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| PSA_SUCCESS(0) | 执行成功 | 公钥导出成功 |
| Other | 其他错误码，参考psa_status_t | 执行失败 |
psa_verify_key
函数声明
头文件清单
功能说明
- 校验密钥的CRC32值以验证密钥完整性
- 通过比较计算值与期望值确认密钥未被篡改
- 用于持久化密钥加载后的完整性检查
前置条件
- crypto模块已初始化
- 密钥key已存在
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| key | psa_key_id_t | 密钥标识符 | 有效密钥ID |
| crc32 | uint32_t | 密钥的CRC32校验值 | 32位无符号整数 |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| PSA_SUCCESS(0) | 执行成功 | 密钥校验通过 |
| Other | 其他错误码，参考psa_status_t | 执行失败 |
psa_destroy_key
函数声明
头文件清单
功能说明
- 销毁指定标识符的密钥
- 从密钥存储区中移除密钥数据并释放资源
- 销毁后密钥标识符不再有效
前置条件
- crypto模块已初始化
- 密钥key已存在
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| key | psa_key_id_t | 密钥标识符 | 有效密钥ID |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| PSA_SUCCESS(0) | 执行成功 | 密钥销毁成功 |
| Other | 其他错误码，参考psa_status_t | 执行失败 |
psa_generate_random
函数声明
头文件清单
功能说明
- 生成指定长度的随机数
- 基于硬件或软件随机数生成器
- 输出缓冲区由调用者分配并提供长度
前置条件
- crypto模块已初始化
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| output_size | size_t | 随机数输出长度 | > 0 |
出参
| 名称 | 数据类型 | 输出说明 |
|---|---|---|
| output | uint8_t | 随机数输出缓冲区 |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| PSA_SUCCESS(0) | 执行成功 | 随机数生成成功 |
| Other | 其他错误码，参考psa_status_t | 执行失败 |
psa_cipher_set_iv
函数声明
psa_status_t psa_cipher_set_iv(psa_cipher_operation_t *operation, const uint8_t *iv, size_t iv_length);
头文件清单
功能说明
- 设置对称加密操作的初始化向量
- IV用于CBC等需要初始向量的加密模式
- 必须在加密或解密操作开始前设置
前置条件
- crypto模块已初始化
- operation已初始化
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| operation | psa_cipher_operation_t * | 对称加密操作结构体指针 | 非NULL |
| iv | const uint8_t * | 初始化向量数据指针 | 非NULL |
| iv_length | size_t | 初始化向量长度 | > 0 |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| PSA_SUCCESS(0) | 执行成功 | IV设置成功 |
| Other | 其他错误码，参考psa_status_t | 执行失败 |
psa_cipher_encrypt
函数声明
psa_status_t psa_cipher_encrypt(psa_key_id_t key, psa_algorithm_t alg, const uint8_t *input, size_t input_length, uint8_t *output, size_t output_size, size_t *output_length);
头文件清单
功能说明
- 使用对称密钥对明文数据进行加密
- 支持AES和SM4等对称加密算法
- 密文输出长度可能因填充模式而大于明文长度
前置条件
- crypto模块已初始化
- 密钥key已存在且支持加密操作
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| key | psa_key_id_t | 密钥标识符 | 有效密钥ID且支持加密 |
| alg | psa_algorithm_t | 对称加密算法 | PSA_ALG_CBC_* / PSA_ALG_CTR / PSA_ALG_CFB / PSA_ALG_ECB_NO_PADDING |
| input | const uint8_t * | 明文数据指针 | 非NULL |
| input_length | size_t | 明文数据长度 | > 0 |
| output_size | size_t | 输出缓冲区大小 | >= 密文数据长度 |
出参
| 名称 | 数据类型 | 输出说明 |
|---|---|---|
| output | uint8_t | 密文数据输出缓冲区 |
| output_length | size_t | 实际输出的密文数据长度 |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| PSA_SUCCESS(0) | 执行成功 | 加密成功 |
| Other | 其他错误码，参考psa_status_t | 执行失败 |
psa_cipher_decrypt
函数声明
psa_status_t psa_cipher_decrypt(psa_key_id_t key, psa_algorithm_t alg, const uint8_t *input, size_t input_length, uint8_t *output, size_t output_size, size_t *output_length);
头文件清单
功能说明
- 使用对称密钥对密文数据进行解密
- 支持AES和SM4等对称解密算法
- 解密时需使用与加密相同的密钥和算法
前置条件
- crypto模块已初始化
- 密钥key已存在且支持解密操作
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| key | psa_key_id_t | 密钥标识符 | 有效密钥ID且支持解密 |
| alg | psa_algorithm_t | 对称解密算法 | PSA_ALG_CBC_* / PSA_ALG_CTR / PSA_ALG_CFB / PSA_ALG_ECB_NO_PADDING |
| input | const uint8_t * | 密文数据指针 | 非NULL |
| input_length | size_t | 密文数据长度 | > 0 |
| output_size | size_t | 输出缓冲区大小 | >= 明文数据长度 |
出参
| 名称 | 数据类型 | 输出说明 |
|---|---|---|
| output | uint8_t | 明文数据输出缓冲区 |
| output_length | size_t | 实际输出的明文数据长度 |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| PSA_SUCCESS(0) | 执行成功 | 解密成功 |
| Other | 其他错误码，参考psa_status_t | 执行失败 |
psa_aead_encrypt
函数声明
psa_status_t psa_aead_encrypt(psa_key_id_t key, psa_algorithm_t alg, const uint8_t *nonce, size_t nonce_length, const uint8_t *additional_data, size_t additional_data_length, const uint8_t *plaintext, size_t plaintext_length, uint8_t *ciphertext, size_t ciphertext_size, size_t *ciphertext_length);
头文件清单
功能说明
- 使用附加关联数据认证加密方式对明文进行加密
- 同时提供加密和完整性保护，输出包含认证标签
- 支持CCM和GCM等认证加密模式
前置条件
- crypto模块已初始化
- 密钥key已存在且支持加密操作
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| key | psa_key_id_t | 密钥标识符 | 有效密钥ID且支持加密 |
| alg | psa_algorithm_t | 认证加密算法 | PSA_ALG_CCM / PSA_ALG_GCM |
| nonce | const uint8_t * | 随机数指针 | 非NULL |
| nonce_length | size_t | 随机数长度 | > 0 |
| additional_data | const uint8_t * | 附加关联数据指针 | 可为NULL |
| additional_data_length | size_t | 附加关联数据长度 | >= 0 |
| plaintext | const uint8_t * | 明文数据指针 | 非NULL |
| plaintext_length | size_t | 明文数据长度 | > 0 |
| ciphertext_size | size_t | 输出缓冲区大小 | >= 密文+标签长度 |
出参
| 名称 | 数据类型 | 输出说明 |
|---|---|---|
| ciphertext | uint8_t | 密文数据输出缓冲区（含认证标签） |
| ciphertext_length | size_t | 实际输出的密文数据长度 |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| PSA_SUCCESS(0) | 执行成功 | 认证加密成功 |
| Other | 其他错误码，参考psa_status_t | 执行失败 |
psa_aead_decrypt
函数声明
psa_status_t psa_aead_decrypt(psa_key_id_t key, psa_algorithm_t alg, const uint8_t *nonce, size_t nonce_length, const uint8_t *additional_data, size_t additional_data_length, const uint8_t *ciphertext, size_t ciphertext_length, uint8_t *plaintext, size_t plaintext_size, size_t *plaintext_length);
头文件清单
功能说明
- 使用附加关联数据认证解密方式对密文进行解密
- 同时验证密文和关联数据的完整性
- 认证失败时不会输出明文数据
前置条件
- crypto模块已初始化
- 密钥key已存在且支持解密操作
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| key | psa_key_id_t | 密钥标识符 | 有效密钥ID且支持解密 |
| alg | psa_algorithm_t | 认证解密算法 | PSA_ALG_CCM / PSA_ALG_GCM |
| nonce | const uint8_t * | 随机数指针 | 非NULL |
| nonce_length | size_t | 随机数长度 | > 0 |
| additional_data | const uint8_t * | 附加关联数据指针 | 可为NULL |
| additional_data_length | size_t | 附加关联数据长度 | >= 0 |
| ciphertext | const uint8_t * | 密文数据指针（含认证标签） | 非NULL |
| ciphertext_length | size_t | 密文数据长度 | > 0 |
| plaintext_size | size_t | 输出缓冲区大小 | >= 明文数据长度 |
出参
| 名称 | 数据类型 | 输出说明 |
|---|---|---|
| plaintext | uint8_t | 明文数据输出缓冲区 |
| plaintext_length | size_t | 实际输出的明文数据长度 |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| PSA_SUCCESS(0) | 执行成功 | 认证解密成功 |
| Other | 其他错误码，参考psa_status_t | 执行失败 |
psa_hash_compute
函数声明
psa_status_t psa_hash_compute(psa_algorithm_t alg, const uint8_t *input, size_t input_length, uint8_t *hash, size_t hash_size, size_t *hash_length);
头文件清单
功能说明
- 计算输入数据的消息摘要
- 支持SHA-256、SHA-512和SM3等哈希算法
- 单次调用完成全部数据的摘要计算
前置条件
- crypto模块已初始化
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| alg | psa_algorithm_t | 哈希算法 | PSA_ALG_SHA_256 / PSA_ALG_SHA_512 / PSA_ALG_SM3 |
| input | const uint8_t * | 输入数据指针 | 非NULL |
| input_length | size_t | 输入数据长度 | > 0 |
| hash_size | size_t | 输出缓冲区大小 | >= 摘要输出长度 |
出参
| 名称 | 数据类型 | 输出说明 |
|---|---|---|
| hash | uint8_t | 摘要数据输出缓冲区 |
| hash_length | size_t | 实际输出的摘要数据长度 |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| PSA_SUCCESS(0) | 执行成功 | 摘要计算成功 |
| Other | 其他错误码，参考psa_status_t | 执行失败 |
psa_mac_compute
函数声明
psa_status_t psa_mac_compute(psa_key_id_t key, psa_algorithm_t alg, const uint8_t *input, size_t input_length, uint8_t *mac, size_t mac_size, size_t *mac_length);
头文件清单
功能说明
- 计算输入数据的消息认证码
- 支持HMAC、CMAC和CBC-MAC等算法
- 需要使用对称密钥进行认证码计算
前置条件
- crypto模块已初始化
- 密钥key已存在且支持签名操作
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| key | psa_key_id_t | 密钥标识符 | 有效密钥ID |
| alg | psa_algorithm_t | MAC算法 | PSA_ALG_HMAC_BASE / PSA_ALG_CMAC / PSA_ALG_CBC_MAC |
| input | const uint8_t * | 输入数据指针 | 非NULL |
| input_length | size_t | 输入数据长度 | > 0 |
| mac_size | size_t | 输出缓冲区大小 | >= MAC输出长度 |
出参
| 名称 | 数据类型 | 输出说明 |
|---|---|---|
| mac | uint8_t | MAC数据输出缓冲区 |
| mac_length | size_t | 实际输出的MAC数据长度 |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| PSA_SUCCESS(0) | 执行成功 | MAC计算成功 |
| Other | 其他错误码，参考psa_status_t | 执行失败 |
psa_key_agreement
函数声明
psa_status_t psa_key_agreement(psa_key_id_t private_key, const uint8_t *peer_key, size_t peer_key_length, psa_algorithm_t alg, const psa_key_attributes_t *attributes, psa_key_id_t *key);
头文件清单
功能说明
- 执行密钥协商并返回共享密钥标识符
- 支持ECDH和FFDH等密钥协商算法
- 协商结果作为新密钥存储在密钥存储区
前置条件
- crypto模块已初始化
- 私钥private_key已存在且支持密钥协商
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| private_key | psa_key_id_t | 本端私钥标识符 | 有效密钥ID |
| peer_key | const uint8_t * | 对端公钥数据指针 | 非NULL |
| peer_key_length | size_t | 对端公钥数据长度 | > 0 |
| alg | psa_algorithm_t | 密钥协商算法 | PSA_ALG_ECDH / PSA_ALG_FFDH |
| attributes | const psa_key_attributes_t * | 共享密钥属性结构体指针 | 非NULL且已正确设置 |
出参
| 名称 | 数据类型 | 输出说明 |
|---|---|---|
| key | psa_key_id_t | 协商生成的共享密钥标识符 |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| PSA_SUCCESS(0) | 执行成功 | 密钥协商成功 |
| Other | 其他错误码，参考psa_status_t | 执行失败 |
psa_raw_key_agreement
函数声明
psa_status_t psa_raw_key_agreement(psa_algorithm_t alg, psa_key_id_t private_key, const uint8_t *peer_key, size_t peer_key_length, uint8_t *output, size_t output_size, size_t *output_length);
头文件清单
功能说明
- 执行密钥协商并返回二进制共享密钥数据
- 支持ECDH和FFDH等密钥协商算法
- 输出原始共享密钥字节序列而非密钥标识符
前置条件
- crypto模块已初始化
- 私钥private_key已存在且支持密钥协商
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| alg | psa_algorithm_t | 密钥协商算法 | PSA_ALG_ECDH / PSA_ALG_FFDH |
| private_key | psa_key_id_t | 本端私钥标识符 | 有效密钥ID |
| peer_key | const uint8_t * | 对端公钥数据指针 | 非NULL |
| peer_key_length | size_t | 对端公钥数据长度 | > 0 |
| output_size | size_t | 输出缓冲区大小 | >= 共享密钥长度 |
出参
| 名称 | 数据类型 | 输出说明 |
|---|---|---|
| output | uint8_t | 共享密钥数据输出缓冲区 |
| output_length | size_t | 实际输出的共享密钥数据长度 |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| PSA_SUCCESS(0) | 执行成功 | 密钥协商成功 |
| Other | 其他错误码，参考psa_status_t | 执行失败 |
psa_sign_hash
函数声明
psa_status_t psa_sign_hash(psa_key_id_t key, psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, uint8_t *signature, size_t signature_size, size_t *signature_length);
头文件清单
功能说明
- 使用私钥对消息摘要进行数字签名
- 支持RSA和ECDSA等签名算法
- 签名结果可用于数据完整性验证和身份认证
前置条件
- crypto模块已初始化
- 密钥key已存在且支持签名操作
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| key | psa_key_id_t | 密钥标识符 | 有效密钥ID且支持签名 |
| alg | psa_algorithm_t | 签名算法 | PSA_ALG_RSA_PKCS1V15_SIGN_BASE / PSA_ALG_RSA_PSS_BASE / PSA_ALG_ECDSA_BASE |
| hash | const uint8_t * | 摘要数据指针 | 非NULL |
| hash_length | size_t | 摘要数据长度 | > 0 |
| signature_size | size_t | 签名输出缓冲区大小 | >= 签名长度 |
出参
| 名称 | 数据类型 | 输出说明 |
|---|---|---|
| signature | uint8_t | 签名数据输出缓冲区 |
| signature_length | size_t | 实际输出的签名数据长度 |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| PSA_SUCCESS(0) | 执行成功 | 签名成功 |
| Other | 其他错误码，参考psa_status_t | 执行失败 |
psa_verify_hash
函数声明
psa_status_t psa_verify_hash(psa_key_id_t key, psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, const uint8_t *signature, size_t signature_length);
头文件清单
功能说明
- 使用公钥对消息摘要进行数字签名验证
- 支持RSA和ECDSA等验签算法
- 验证签名数据的完整性和签名者身份
前置条件
- crypto模块已初始化
- 密钥key已存在且支持验签操作
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| key | psa_key_id_t | 密钥标识符 | 有效密钥ID且支持验签 |
| alg | psa_algorithm_t | 验签算法 | PSA_ALG_RSA_PKCS1V15_SIGN_BASE / PSA_ALG_RSA_PSS_BASE / PSA_ALG_ECDSA_BASE |
| hash | const uint8_t * | 摘要数据指针 | 非NULL |
| hash_length | size_t | 摘要数据长度 | > 0 |
| signature | const uint8_t * | 签名数据指针 | 非NULL |
| signature_length | size_t | 签名数据长度 | > 0 |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| PSA_SUCCESS(0) | 执行成功 | 验签通过 |
| Other | 其他错误码，参考psa_status_t | 执行失败 |
psa_asymmetric_encrypt
函数声明
psa_status_t psa_asymmetric_encrypt(psa_key_id_t key, psa_algorithm_t alg, const uint8_t *input, size_t input_length, const uint8_t *salt, size_t salt_length, uint8_t *output, size_t output_size, size_t *output_length);
头文件清单
功能说明
- 使用公钥对数据进行非对称加密
- 支持RSA和EC ElGamal等非对称加密算法
- 加密数据长度受密钥长度和算法模式限制
前置条件
- crypto模块已初始化
- 密钥key已存在且为公钥且支持加密操作
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| key | psa_key_id_t | 密钥标识符 | 有效密钥ID且支持加密 |
| alg | psa_algorithm_t | 非对称加密算法 | PSA_ALG_RSA_PKCS1V15_CRYPT / PSA_ALG_RSA_OAEP_BASE / PSA_ALG_EC_ELGAMAL |
| input | const uint8_t * | 明文数据指针 | 非NULL |
| input_length | size_t | 明文数据长度 | > 0 |
| salt | const uint8_t * | 盐值指针 | 可为NULL |
| salt_length | size_t | 盐值长度 | >= 0 |
| output_size | size_t | 输出缓冲区大小 | >= 密文数据长度 |
出参
| 名称 | 数据类型 | 输出说明 |
|---|---|---|
| output | uint8_t | 密文数据输出缓冲区 |
| output_length | size_t | 实际输出的密文数据长度 |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| PSA_SUCCESS(0) | 执行成功 | 非对称加密成功 |
| Other | 其他错误码，参考psa_status_t | 执行失败 |
psa_asymmetric_decrypt
函数声明
psa_status_t psa_asymmetric_decrypt(psa_key_id_t key, psa_algorithm_t alg, const uint8_t *input, size_t input_length, const uint8_t *salt, size_t salt_length, uint8_t *output, size_t output_size, size_t *output_length);
头文件清单
功能说明
- 使用私钥对密文进行非对称解密
- 支持RSA和EC ElGamal等非对称解密算法
- 解密时需使用与加密对应的密钥和算法
前置条件
- crypto模块已初始化
- 密钥key已存在且为私钥且支持解密操作
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| key | psa_key_id_t | 密钥标识符 | 有效密钥ID且支持解密 |
| alg | psa_algorithm_t | 非对称解密算法 | PSA_ALG_RSA_PKCS1V15_CRYPT / PSA_ALG_RSA_OAEP_BASE / PSA_ALG_EC_ELGAMAL |
| input | const uint8_t * | 密文数据指针 | 非NULL |
| input_length | size_t | 密文数据长度 | > 0 |
| salt | const uint8_t * | 盐值指针 | 可为NULL |
| salt_length | size_t | 盐值长度 | >= 0 |
| output_size | size_t | 输出缓冲区大小 | >= 明文数据长度 |
出参
| 名称 | 数据类型 | 输出说明 |
|---|---|---|
| output | uint8_t | 明文数据输出缓冲区 |
| output_length | size_t | 实际输出的明文数据长度 |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| PSA_SUCCESS(0) | 执行成功 | 非对称解密成功 |
| Other | 其他错误码，参考psa_status_t | 执行失败 |
psa_key_derivation_operation_init
函数声明
头文件清单
功能说明
- 初始化密钥派生操作结构体为零值状态
- 返回一个初始化后的操作结构体，可用于后续派生操作
- 必须在密钥派生操作开始前调用
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| psa_key_derivation_operation_t | 初始化后的密钥派生操作结构体 | 调用即返回 |
psa_key_derivation_setup
函数声明
psa_status_t psa_key_derivation_setup(psa_key_derivation_operation_t *operation, psa_algorithm_t alg);
头文件清单
功能说明
- 设置密钥派生操作的算法
- 初始化派生操作上下文并指定派生算法类型
- 必须在密钥派生输入参数之前调用
前置条件
- crypto模块已初始化
- operation已通过psa_key_derivation_operation_init初始化
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| operation | psa_key_derivation_operation_t * | 密钥派生操作结构体指针 | 非NULL |
| alg | psa_algorithm_t | 密钥派生算法 | PSA_ALG_HKDF_BASE / PSA_ALG_PBKDF2_HMAC_BASE |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| PSA_SUCCESS(0) | 执行成功 | 派生操作初始化成功 |
| Other | 其他错误码，参考psa_status_t | 执行失败 |
psa_key_derivation_abort
函数声明
头文件清单
功能说明
- 终止密钥派生操作并释放资源
- 将派生操作结构体重置为初始状态
- 可在派生操作的任何阶段调用以取消操作
前置条件
- crypto模块已初始化
- operation已初始化
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| operation | psa_key_derivation_operation_t * | 密钥派生操作结构体指针 | 非NULL |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| PSA_SUCCESS(0) | 执行成功 | 派生操作终止成功 |
| Other | 其他错误码，参考psa_status_t | 执行失败 |
psa_key_derivation_set_capacity
函数声明
psa_status_t psa_key_derivation_set_capacity(psa_key_derivation_operation_t *operation, size_t capacity);
头文件清单
功能说明
- 设置密钥派生操作的结果输出容量
- 容量限制了可从派生操作中读取的最大字节数
- 必须在setup之后、output之前设置
前置条件
- crypto模块已初始化
- operation已完成setup
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| operation | psa_key_derivation_operation_t * | 密钥派生操作结构体指针 | 非NULL |
| capacity | size_t | 派生结果容量（字节数） | > 0 |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| PSA_SUCCESS(0) | 执行成功 | 容量设置成功 |
| Other | 其他错误码，参考psa_status_t | 执行失败 |
psa_key_derivation_get_capacity
函数声明
psa_status_t psa_key_derivation_get_capacity(const psa_key_derivation_operation_t *operation, size_t *capacity);
头文件清单
功能说明
- 获取密钥派生操作的剩余结果输出容量
- 返回当前还可输出的字节数
- 每次output操作后容量会相应减少
前置条件
- crypto模块已初始化
- operation已完成setup
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| operation | const psa_key_derivation_operation_t * | 密钥派生操作结构体指针 | 非NULL |
出参
| 名称 | 数据类型 | 输出说明 |
|---|---|---|
| capacity | size_t | 剩余派生结果容量（字节数） |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| PSA_SUCCESS(0) | 执行成功 | 获取容量成功 |
| Other | 其他错误码，参考psa_status_t | 执行失败 |
psa_key_derivation_input_bytes
函数声明
psa_status_t psa_key_derivation_input_bytes(psa_key_derivation_operation_t *operation, psa_key_derivation_step_t step, const uint8_t *data, size_t data_length);
头文件清单
功能说明
- 以字节形式向密钥派生操作输入参数
- 根据步骤类型输入不同的派生参数（密钥、盐值、信息等）
- 必须按照派生算法要求的步骤顺序输入
前置条件
- crypto模块已初始化
- operation已完成setup
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| operation | psa_key_derivation_operation_t * | 密钥派生操作结构体指针 | 非NULL |
| step | psa_key_derivation_step_t | 派生步骤标识 | PSA_KEY_DERIVATION_INPUT_SECRET / PSA_KEY_DERIVATION_INPUT_SALT / PSA_KEY_DERIVATION_INPUT_INFO / PSA_KEY_DERIVATION_INPUT_PASSWORD / PSA_KEY_DERIVATION_INPUT_COST |
| data | const uint8_t * | 输入数据指针 | 非NULL |
| data_length | size_t | 输入数据长度 | > 0 |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| PSA_SUCCESS(0) | 执行成功 | 参数输入成功 |
| Other | 其他错误码，参考psa_status_t | 执行失败 |
psa_key_derivation_input_key
函数声明
psa_status_t psa_key_derivation_input_key(psa_key_derivation_operation_t *operation, psa_key_derivation_step_t step, psa_key_id_t key);
头文件清单
功能说明
- 以密钥标识符形式向密钥派生操作输入参数
- 适用于派生密钥材料已存储在密钥存储区的场景
- 密钥必须具有DERIVE用途标志
前置条件
- crypto模块已初始化
- operation已完成setup
- 密钥key已存在且支持派生操作
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| operation | psa_key_derivation_operation_t * | 密钥派生操作结构体指针 | 非NULL |
| step | psa_key_derivation_step_t | 派生步骤标识 | PSA_KEY_DERIVATION_INPUT_SECRET / PSA_KEY_DERIVATION_INPUT_PASSWORD |
| key | psa_key_id_t | 密钥标识符 | 有效密钥ID |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| PSA_SUCCESS(0) | 执行成功 | 密钥输入成功 |
| Other | 其他错误码，参考psa_status_t | 执行失败 |
psa_key_derivation_input_integer
函数声明
psa_status_t psa_key_derivation_input_integer(psa_key_derivation_operation_t *operation, psa_key_derivation_step_t step, uint64_t value);
头文件清单
功能说明
- 以整数形式向密钥派生操作输入参数
- 主要用于PBKDF2算法的迭代次数输入
- 整数值通过步骤标识确定其派生参数含义
前置条件
- crypto模块已初始化
- operation已完成setup
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| operation | psa_key_derivation_operation_t * | 密钥派生操作结构体指针 | 非NULL |
| step | psa_key_derivation_step_t | 派生步骤标识 | PSA_KEY_DERIVATION_INPUT_COST |
| value | uint64_t | 整数输入值 | > 0 |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| PSA_SUCCESS(0) | 执行成功 | 整数参数输入成功 |
| Other | 其他错误码，参考psa_status_t | 执行失败 |
psa_key_derivation_output_bytes
函数声明
psa_status_t psa_key_derivation_output_bytes(psa_key_derivation_operation_t *operation, uint8_t *output, size_t output_length);
头文件清单
功能说明
- 从密钥派生操作中获取派生结果数据
- 输出指定长度的派生密钥材料
- 输出长度不能超过当前剩余容量
前置条件
- crypto模块已初始化
- operation已完成setup和参数输入
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| operation | psa_key_derivation_operation_t * | 密钥派生操作结构体指针 | 非NULL |
| output_length | size_t | 请求输出的派生数据长度 | > 0且 <= 剩余容量 |
出参
| 名称 | 数据类型 | 输出说明 |
|---|---|---|
| output | uint8_t | 派生结果数据输出缓冲区 |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| PSA_SUCCESS(0) | 执行成功 | 派生结果获取成功 |
| Other | 其他错误码，参考psa_status_t | 执行失败 |
Type definitions
psa_status_t
使用说明
作为crypto模块所有返回psa_status_t类型接口的返回值类型
Structures
psa_key_policy_t
成员说明
| 成员名称 | 数据类型 | 描述 |
|---|---|---|
| usage | psa_key_usage_t | 密钥用途标志位 |
| alg | psa_algorithm_t | 密钥算法 |
psa_key_attributes_t
typedef struct {
psa_key_type_t type;
psa_key_bits_t bits;
psa_key_lifetime_t lifetime;
psa_key_policy_t policy;
psa_key_id_t key;
} psa_key_attributes_t;
成员说明
| 成员名称 | 数据类型 | 描述 |
|---|---|---|
| type | psa_key_type_t | 密钥类型 |
| bits | psa_key_bits_t | 密钥比特长度 |
| lifetime | psa_key_lifetime_t | 密钥生命周期 |
| policy | psa_key_policy_t | 密钥策略（用途与算法） |
| key | psa_key_id_t | 密钥标识符 |
psa_hkdf_key_derivation_t
typedef struct {
uint8_t *salt;
size_t salt_length;
uint8_t *info;
size_t info_length;
bool is_ikm_key_id;
psa_key_id_t ikm_key;
uint8_t *ikm;
size_t ikm_length;
} psa_hkdf_key_derivation_t;
成员说明
| 成员名称 | 数据类型 | 描述 |
|---|---|---|
| salt | uint8_t * | 盐值数据指针 |
| salt_length | size_t | 盐值数据长度 |
| info | uint8_t * | 信息数据指针 |
| info_length | size_t | 信息数据长度 |
| is_ikm_key_id | bool | 输入密钥材料是否为密钥标识符 |
| ikm_key | psa_key_id_t | 输入密钥标识符 |
| ikm | uint8_t * | 输入密钥材料数据指针 |
| ikm_length | size_t | 输入密钥材料数据长度 |
psa_pbkdf2_key_derivation_t
typedef struct {
bool is_password_key_id;
psa_key_id_t password_key;
uint8_t *password;
size_t password_length;
bool is_salt_key_id;
psa_key_id_t salt_key;
uint8_t *salt;
size_t salt_length;
uint64_t count;
} psa_pbkdf2_key_derivation_t;
成员说明
| 成员名称 | 数据类型 | 描述 |
|---|---|---|
| is_password_key_id | bool | 密码是否为密钥标识符形式 |
| password_key | psa_key_id_t | 密码密钥标识符 |
| password | uint8_t * | 密码数据指针 |
| password_length | size_t | 密码数据长度 |
| is_salt_key_id | bool | 盐值是否为密钥标识符形式 |
| salt_key | psa_key_id_t | 盐值密钥标识符 |
| salt | uint8_t * | 盐值数据指针 |
| salt_length | size_t | 盐值数据长度 |
| count | uint64_t | 迭代次数 |
psa_key_derivation_operation_t
typedef struct {
bool is_set_up;
psa_algorithm_t alg;
size_t capacity;
psa_hkdf_key_derivation_t hkdf;
psa_pbkdf2_key_derivation_t pbkdf2;
} psa_key_derivation_operation_t;
成员说明
| 成员名称 | 数据类型 | 描述 |
|---|---|---|
| is_set_up | bool | 是否已完成setup |
| alg | psa_algorithm_t | 密钥派生算法 |
| capacity | size_t | 派生结果容量（字节） |
| hkdf | psa_hkdf_key_derivation_t | HKDF派生参数 |
| pbkdf2 | psa_pbkdf2_key_derivation_t | PBKDF2派生参数 |
psa_cipher_operation_t
成员说明
| 成员名称 | 数据类型 | 描述 |
|---|---|---|
| key | psa_key_id_t | 密钥标识符 |
| alg | psa_algorithm_t | 加解密算法 |
Macros
PSA_KEY_TYPE_NONE
PSA_KEY_LIFETIME_VOLATILE
PSA_KEY_POLICY_INIT
PSA_KEY_ID_INIT
PSA_KEY_ATTRIBUTES_INIT
#define PSA_KEY_ATTRIBUTES_INIT { PSA_KEY_TYPE_NONE, 0, \
PSA_KEY_LIFETIME_VOLATILE, \
PSA_KEY_POLICY_INIT, \
PSA_KEY_ID_INIT }