Hi3403开发文档
前言¶
CIPHER是安全算法模块，它提供了AES对称加解密算法，HASH及HMAC摘要算法，随机数算法，以及RSA不对称算法，主要用于对音视频码流进行加解密及数据合法性验证等场景。
说明： 本文未有特殊说明，SS927V100与SS928V100内容完全一致。
与本文档相对应的产品版本如下。
本文档（本指南）主要适用于以下工程师：
技术支持工程师
软件开发工程师
在本文中可能出现下列标志，它们所代表的含义如下。
修订记录累积了每次文档更新的说明。最新版本的文档包含以前所有文档版本的更新内容。
概述¶
概述¶
CIPHER是安全算法模块，其提供了包括AES对称加解密算法，RSA不对称加解密算法，随机数生成，以及支持HASH、HMAC等摘要算法，主要用于对音视频码流进行加解密保护，用户合法性认证等场景。各功能划分如下。
对称加解密算法¶
AES：支持ECB/CBC/CFB/OFB/CTR/CCM/GCM等工作模式。CCM/GCM模式下，加解密结束后需获取一次TAG值。
以上算法除了CTR/CCM/GCM，其它算法、模式的数据长度必须按块大小对齐；CCM/GCM的N、A需要靠软件按标准把各个字段封装成块大小对齐的数据块；各种工作模式支持一次实现多个分组的加解密运算，也支持一次实现单个分组的加解密运算。
SS928V100、SS626V100支持申请15个通道。
ECB模式安全性低，该模式仅用于调试，不能用于产品。
不对称加解密算法¶
RSA：支持密钥位宽2048/3072/4096 bits。
随机数生成¶
RNG：支持DRBG，以更高速率获取随机数。
摘要算法¶
HASH：
支持SHA256/SHA384/SHA512；
支持HMAC256/HMAC384/HMAC512；
支持软件多通道，最多可以申请15个软件通道。
算法标准¶
以上各功能模块涉及的算法及工作模式符合以下标准：
AES算法的实现符合FIPS 197标准，其支持的工作模式符合以下标准：
ECB、CBC、1/8/128-CFB、128-OFB、CTR几种工作模式符合NIST special800-38a标准
CCM工作模式符合NIST special800-38c标准
GCM工作模式符合NIST special800-38d标准
RSA支持公钥加密私钥解密、私钥加密公钥解密、签名及验签等功能，各种模式的数据填充方式符合PKCS#1标准。支持PKCS#1 V1.5和PKCS#1 V2.1填充方式。在加解密模式时，PKCS#1 V2.1填充方式为OAEP；在签名验签模式时，PKCS#1 V2.1填充方式为PSS。
对称加解密算法的工作模式主要有： ECB（Electronic codebook，电子密码本模式）、CBC（Cipher-block chaining，密码分组链接模式）、CFB（Cipher feedback，密文反馈模式）、OFB（Output feedback，输出反馈模式）、CTR（Counter mode，计数器模式）、CCM（counter with CBC-MAC，CTR加密模式和消息认证码CMAC算法的混合）、GCM（Galois/Counter Mode，伽罗华域/计数器模式），主要由工作在计数器模式下的分组密码和在伽罗华域GF（2^128）上的哈希运算组成。CCM模式在加解密的同时生成CMAC检验值，GCM模式使用GHASH生成认证信息，解密时的CMAC要和加密时的CMAC一样才说明解密是正确的，常用在需要同时加密和认证的领域，欲了解算法的详细内容，请参考相关文献。
块密码学中，将需要加密/解密的消息块分成数块： ECB模式中，对每个块进行独立加密/解密，块与块之间没有依赖；非ECB模式中，块与块之间有依赖性，并且为了保证每条消息的唯一性，在第一个块中需要使用初始化向量IV。
CIPHER使用注意事项¶
CIPHER部署在不同场景下时，使用方式可能会有所不同。
在LiteOS环境下，链接CIPHER的静态库libss_cipher.a。
在Linux环境下，用户态使用CIPHER可以通过链接静态库libss_cipher.a或动态库libss_cipher.so的方式，依赖libsecurec.a或libsecurec.so。内核态CIPHER使用模块插入方式，即insmod ot_cipher.ko，需要依赖ot_osal.ko， ot_base.ko，sys_config.ko，ot_sys.ko，此方式CIPHER默认依赖MMZ地址。
在OPTEE环境下
用户态调用CIPHER对外接口由Linux环境下的ss_mpi_xxx命名形式对应更改为ot_tee_xxx；
内核态调用CIPHER对外接口由Linux环境下的ss_mpi_xxx命名形式对应更改为ot_drv_xxx。
在UBOOT环境下，用户态调用CIPHER对外接口由Linux环境下的ss_mpi_xxx命名形式对应变更为ot_mpi_xxx。
规格差异说明¶
CIPHER支持的AES、HASH、RSA不同解决方案间的配置差异如表1所示。
表 1 规格差异说明
使用流程¶
单包数据加解密（对称加解密算法）¶
场景说明¶
对单包数据进行加密或解密。当物理内存中有一段码流数据需要进行加/解密时，获取物理地址后在用户层调用CIPHER模块实现加/解密，或当虚拟内存中有一段数据需要进行加/解密时，获取虚拟地址后在用户层调用CIPHER模块实现加/解密。
工作流程¶
CIPHER设备初始化。调用接口ss_mpi_cipher_init。
创建CIPHER句柄。调用接口ss_mpi_cipher_create。
创建KEYSLOT句柄。调用接口ss_mpi_keyslot_create。
绑定CIPHER和KEYSLOT句柄。调用接口ss_mpi_cipher_attach。
配置CIPHER控制信息。包含加解密算法、工作模式等信息。调用接口ss_mpi_cipher_set_cfg。
配置密钥。请参考《KLAD API 参考》1.2.1 明文KEY传递或1.2.2 ROOTKEY传递。
加解密数据。用户可调用以下任意接口加解密数据。
物理内存中数据的单包加密--ss_mpi_cipher_encrypt
物理内存中数据的单包解密--ss_mpi_cipher_decrypt
虚拟内存中数据的单包加密--ss_mpi_cipher_encrypt_virt
虚拟内存中数据的单包解密--ss_mpi_cipher_decrypt_virt
解绑定CIPHER和KEYSLOT句柄。调用接口ss_mpi_cipher_detach。
销毁KEYSLOT句柄。调用接口ss_mpi_keyslot_destroy。
销毁CIPHER句柄。调用接口ss_mpi_cipher_destroy。
CIPHER设备去初始化。调用接口ss_mpi_cipher_deinit。
注意事项¶
使用CIPHER模块时，请特别注意以下几点。
该接口支持AES对称加解密算法。
各算法支持ECB/CBC/CFB/OFB/CTR/CCM/GCM等工作模式。CCM/GCM工作模式加解密请参考“CCM/GCM加解密（对称加解密算法）”章节。
在进行加密、解密运算前必须先获取CIPHER句柄，当长时间不使用时可以释放，建议加密、解密各获取一个句柄，每个句柄只进行加密或者只进行解密操作。
支持对不带cache的物理空间连续的内存数据进行加密、解密（如果是带cache的，需要用户自己执行刷cache操作）和对虚拟空间的内存数据进行加密、解密（用户可以使用malloc等申请虚拟地址）。
CIPHER内部采用DMA方式传输数据，所以调用ss_mpi_cipher_encrypt或ss_mpi_cipher_decrypt接口进行数据的加密或解密时，传入的地址参数为数据的物理地址。当调用ss_mpi_cipher_encrypt_virt或ss_mpi_cipher_decrypt_virt接口进行数据的加密或解密时，传入的地址参数为数据的虚拟地址。
加密、解密的源地址、目的地址可以相同，即可以在原地（密文、明文使用同一块buffer）进行数据的加密和解密。
使用非ECB模式进行CIPHER的加解密时，需要使用初始化向量IV（Initial Vector）。
配置IV时有以下两个场景（以解密数据块为例）：
【场景1】
每次调用CIPHER时都需要更新IV，此时请设置chg_flags = OT_CIPHER_IV_CHG_ALL_PACK，并正确配置IV值。
函数调用顺序请参考：
ss_mpi_cipher_set_cfg() // should set chg_flags = OT_CIPHER_IV_CHG_ALL_PACK and update iv ss_mpi_cipher_decrypt() ss_mpi_cipher_set_cfg() // should set chg_flags = OT_CIPHER_IV_CHG_ALL_PACK and update iv ss_mpi_cipher_decrypt() …. ss_mpi_cipher_set_cfg() // should set chg_flags = OT_CIPHER_IV_CHG_ALL_PACK and update iv ss_mpi_cipher_decrypt()
【场景2】
只需第一次调用CIPHER时设置IV，此时请设置chg_flags = OT_CIPHER_IV_CHG_ONE_PACK，且配置IV值。
函数调用顺序请参考：
ss_mpi_cipher_set_cfg() // should set chg_flags = OT_CIPHER_IV_CHG_ONE_PACK and update iv ss_mpi_cipher_decrypt() ss_mpi_cipher_decrypt() ss_mpi_cipher_decrypt()
请结合实际场景进行IV的配置。
单包加解密的IV向量可继承。创建一路CIPHER，配置属性（假设配置的工作模式需要使用IV向量）之后，每次调用单包加解密接口时，IV向量会依次轮流使用。
例如：用户需依次加密数据0，数据1。向量为a,b,c,d。用户加密完数据0之后，数据0的最后一个分块数据使用了IV向量中的b进行加密处理；此时，用户再加密数据1时，数据1的第一个分块数据将会使用IV向量c进行加密，然后依次为d,a,b,c,d…。
因此在加解密时，必须要保证两次向量使用的一致性。重新配置CIPHER控制信息将设置IV向量从第一个开始
CCM、GCM在计算完成后需要获取TAG值，解密的TAG要和加密时一样解密才成功。
多包数据加解密（对称加解密算法）¶
场景说明¶
对多个数据包进行加密或解密。当物理内存中有多段码流数据需要进行加/解密时，获取物理地址后在用户层调用CIPHER模块实现加/解密。
工作流程¶
CIPHER设备初始化。调用接口ss_mpi_cipher_init。
创建CIPHER句柄。调用接口ss_mpi_cipher_create。
创建KEYSLOT句柄。调用接口ss_mpi_keyslot_create。
绑定CIPHER和KEYSLOT句柄。调用接口ss_mpi_cipher_attach。
配置CIPHER控制信息。包含加解密算法、工作模式等信息。调用接口ss_mpi_cipher_set_cfg。
配置密钥。请参考《KLAD API 参考》1.2.1 明文KEY传递或1.2.2 ROOTKEY传递。
加解密数据。用户可调用以下任意接口加解密数据。
解绑定CIPHER和KEYSLOT句柄。调用接口ss_mpi_cipher_detach。
销毁KEYSLOT句柄。调用接口ss_mpi_keyslot_destroy。
销毁CIPHER句柄。调用接口ss_mpi_cipher_destroy。
CIPHER设备去初始化。调用接口ss_mpi_cipher_deinit。
注意事项¶
进行多包加解密时，最多支持同时加解密5000个包。
对于多个包的操作，每个包都使用ss_mpi_cipher_set_cfg配置的向量进行运算，IV作用域是可配置的，前一个包的向量运算结果可以作为下一个包的IV，或者每个包IV都是独立运算的（前一次函数调用的结果不会影响后一次函数调用的运算结果）。
进行多包加解密时，需要使用物理地址作为地址参数。
其它注意事项同“单包数据加解密（对称加解密算法）”章节。
CCM/GCM加解密（对称加解密算法）¶
场景说明¶
对数据进行CCM加解密。该算法请参考：SP800-38C_updated-July20_2007_CCM. The CCM Mode for Authentication and Confidentiality。
对数据进行GCM加解密。该算法请参考：SP-800-38D-GCM. Galois/Counter Mode (GCM) and GMAC。
工作流程¶
CIPHER设备初始化。调用接口ss_mpi_cipher_init。
创建CIPHER句柄。调用接口ss_mpi_cipher_create。
创建KEYSLOT句柄。调用接口ss_mpi_keyslot_create。
绑定CIPHER和KEYSLOT句柄。调用接口ss_mpi_cipher_attach。
配置CIPHER控制信息。包含加解密算法、工作模式等信息。调用接口ss_mpi_cipher_set_cfg。
配置密钥。请参考《KLAD API 参考》1.2.1 明文KEY传递或1.2.2 ROOTKEY传递。
加解密数据。用户可调用以下任意接口加解密数据。
物理内存中数据加密--ss_mpi_cipher_encrypt
物理内存中数据解密--ss_mpi_cipher_decrypt
虚拟内存中数据加密--ss_mpi_cipher_encrypt_virt
虚拟内存中数据解密--ss_mpi_cipher_decrypt_virt
获取TAG值。调用接口ss_mpi_cipher_get_tag。
解绑定CIPHER和KEYSLOT句柄。调用接口ss_mpi_cipher_detach。
销毁KEYSLOT句柄。调用接口ss_mpi_keyslot_destroy。
销毁CIPHER句柄。调用接口ss_mpi_cipher_destroy。
CIPHER设备去初始化。调用接口ss_mpi_cipher_deinit。
注意事项¶
CCM/GCM密钥长度为128/192/256 bits(硬件 key 只支持 128/256 bits)。CCM/GCM解密产生的TAG值必须和加密时一样，解密结果才是正确的。
AES-CCM模式由AES CTR加密模式和CBC-MAC认证算法构成，既可以保证数据的保密性，也能保证数据的完整性。
根据CCM算法原理，向量IV长度iv_len可取{7, 8, 9, 10, 11, 12, 13} bytes，IV存放算法标准中的Nonce数据N，加密数据的长度用n个Byte表示，且应满足条件：iv_len+n=15, 所以iv_len为13时，n为2，此时加密数据长度最长为65535bytes，其它以此类推。
CCM加密时的向量N、关联数据A取值必须与解密时保持一致。
AES-GCM模式由AES CTR和GHASH构成，既可以保证数据的保密性，也能保证数据的完整性。
根据GCM算法原理，GCM的向量IV长度iv_len可取范围为[1~16]。
GCM加密时的关联数据A取值必须与解密时保持一致。
HASH计算（摘要算法）¶
场景说明¶
计算数据的HASH值，可选择SHA256/SHA384/SHA512。
工作流程¶
CIPHER设备初始化。调用接口ss_mpi_cipher_init完成。
创建一路HASH，获取HASH句柄，选择HASH算法。调用接口ss_mpi_cipher_hash_init完成。
输入数据，逐个数据块依次计算HASH值。调用接口ss_mpi_cipher_hash_update完成。
如果摘要未计算完成，再次执行3。
完成摘要计算，结束输入，获取计算结果。调用接口ss_mpi_cipher_hash_final完成。
关闭CIPHER设备。调用接口ss_mpi_cipher_deinit完成。
注意事项¶
支持软件多通道，可同时进行多个HASH运算， 即执行2启动一个HASH运算，在本次HASH计算未完成（即未执行5）之前，可申请一个新通道启动另一个HASH运算，直到申请不到通道为止。
最多支持15个HASH软件通道，15个通道可同时都被打开，但同一时间内只有一个通道在进行运算。
HMAC计算（摘要算法）¶
场景说明¶
计算数据的HMAC值。基于的HASH算法为 SHA256/SHA384/SHA512。
工作流程¶
HMAC运算开发操作步骤如下：
调用ss_mpi_cipher_init初始化CIPHER模块。
调用ss_mpi_cipher_hash_init选择使用的HASH算法，并配置HMAC计算的密钥，初始化HASH模块。
调用ss_mpi_cipher_hash_update输入数据，可以一个BLOCK接一个BLOCK输入。
调用ss_mpi_cipher_hash_final结束输入，并输出HMAC值。
调用ss_mpi_cipher_deinit 去初始化CIPHER设备。
注意事项¶
支持软件多通道，可同时进行多个HMAC运算， 即执行2启动一个HMAC运算，在本次HMAC计算未完成（即未执行4）之前，可申请一个新通道启动另一个HMAC运算，直到申请不到通道为止。
HMAC和HASH共用15个软件通道，15个通道可同时都被打开，但同一时间内只有一个通道在进行运算。
随机数生成¶
场景说明¶
获取硬件产生的真随机数。
工作流程¶
生成随机数据的过程如下：
CIPHER设备初始化。调用接口ss_mpi_cipher_init完成。
获取32bits的随机数。调用接口ss_mpi_cipher_get_random_num完成。
关闭CIPHER设备。调用接口ss_mpi_cipher_deinit完成。
注意事项¶
无。
RSA加解密（不对称加解密算法）¶
场景说明¶
对数据进行RSA不对称算法进行加解密，当使用公钥加密的数据，必须使用私钥进行解密，反之，使用私钥加密的数据，必须使用公钥进行解密。
该算法请参考：rfc3447. RSA Cryptography Specifications。
工作流程¶
对数据进行不对称的RSA加解密的过程如下：
CIPHER设备初始化。调用接口ss_mpi_cipher_init完成。
对数据进行加解密。根据使用的密钥不同，分为4个接口，用户可以调用以下任一接口进行加解密等。
关闭CIPHER设备。调用接口ss_mpi_cipher_deinit完成。
注意事项¶
RSA密钥位宽可选2048、3072及4096。根据RSA算法原理，明文和密文都必须比公钥N小，所以待加解密的数据长度必须小于或等于密钥的长度，惯用 做法是在待加解密的数据的高位补0等，使其长度和公钥N相等，但其值比公钥N小。支持PKCS#1 V1.5和PKCS#1 V2.1填充方式，其中PKCS#1 V1.5为弱填充方式，客户不建议使用该填充方式，PKCS#1 V2.1填充方式为OAEP。注意：op-tee、uboot环境不支持RSA私钥，priv_key用p/q/dp/dq/qp代替d。
RSA签名及验签（不对称加解密算法）¶
场景说明¶
对数据进行RSA签名及验签时，使用私钥进行数据签名，使用公钥进行数据验签。
该算法请参考：rfc3447. RSA Cryptography Specifications。
工作流程¶
对数据进行不对称的RSA签名及验签的过程如下：
CIPHER设备初始化。调用接口ss_mpi_cipher_init完成。
对数据进行签名验证，调用以下接口签名验证。
私钥签名--ss_mpi_cipher_rsa_sign
公钥验证--ss_mpi_cipher_rsa_verify
关闭CIPHER设备。调用接口ss_mpi_cipher_deinit完成。
注意事项¶
RSA密钥位宽可选2048、3072及4096。根据RSA算法原理，明文和密文都必须比公钥小，所以待加解密的数据长度必须小于或等于密钥的长度，惯用作法是先计算待签名数据的HASH值，接着将HASH值填充成长度和公钥N相等但其值比公钥N小的数据，然后再进行加密。支持PKCS#1 V1.5和PKCS#1 V2.1填充方式，其中PKCS#1 V1.5为弱填充方式，客户不要该填充方式，PKCS#1 V2.1填充方式为PSS。注意：op-tee、uboot环境不支持RSA私钥，priv_key用p/q/dp/dq/qp代替d。
API参考¶
CIPHER提供以下API：
ss_mpi_cipher_init：初始化CIPHER模块。
ss_mpi_cipher_deinit：去初始化CIPHER模块。
ss_mpi_cipher_create：对称加解密时创建一路的CIPHER句柄。
ss_mpi_cipher_destroy：对称加解密时销毁已存在的CIPHER句柄。
ss_mpi_cipher_set_cfg：对称加解密时配置CIPHER通道对应的控制信息。
ss_mpi_cipher_get_cfg：对称加解密时获取CIPHER通道对应的配置信息。
ss_mpi_cipher_encrypt：对称加解密时单包数据加密功能。
ss_mpi_cipher_decrypt：对称加解密时单包数据解密功能。
ss_mpi_cipher_encrypt_virt：对称加解密时对数据进行加密。
ss_mpi_cipher_decrypt_virt：对称加解密时对数据进行解密。
ss_mpi_cipher_encrypt_multi_pack：对称加解密时多包数据加密功能。
ss_mpi_cipher_decrypt_multi_pack：对称加解密时多包数据解密功能。
ss_mpi_cipher_get_tag：对称加解密时CCM/GCM模式获取TAG值。
ss_mpi_cipher_hash_init：HASH、HMAC计算初始化功能。
ss_mpi_cipher_hash_update：HASH、HMAC计算数据输入功能。
ss_mpi_cipher_hash_final：HASH、HMAC计算最终结果输出功能。
ss_mpi_cipher_get_random_num：获取随机数功能。
ss_mpi_cipher_rsa_public_encrypt：使用RSA公钥加密一段明文。
ss_mpi_cipher_rsa_private_decrypt：使用RSA私钥解密一段密文。
ss_mpi_cipher_rsa_private_encrypt：使用RSA私钥加密一段明文。
ss_mpi_cipher_rsa_public_decrypt：使用RSA公钥解密一段密文。
ss_mpi_cipher_rsa_sign：使用RSA私钥签名一段文本。
ss_mpi_cipher_rsa_verify：使用RSA公钥验证一段文本。
ss_mpi_cipher_sm2_encrypt：使用SM2公钥加密一段明文。
ss_mpi_cipher_sm2_decrypt：使用SM2私钥解密一段密文。
ss_mpi_cipher_sm2_sign：使用SM2签名一段文本。
ss_mpi_cipher_sm2_verify：使用SM2验证一段文本。
ss_mpi_keyslot_create：对称加解密时创建一路keyslot句柄。
ss_mpi_keyslot_destroy：对称加解密时销毁一路keyslot句柄。
ss_mpi_cipher_attach：对称加解密时cipher句柄与keyslot句柄绑定。
ss_mpi_cipher_detach：对称加解密时cipher句柄与keyslot句柄解绑定。
ss_mpi_cipher_init¶
【描述】
初始化CIPHER模块。
【语法】
td_s32 ss_mpi_cipher_init(td_void);
【参数】
无。
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_cipher.h、ss_mpi_cipher.h
库文件：libss_cipher.a、libss_cipher.so
【注意】
支持多次调用。
初始化和去初始化成对使用。
内核态不需要调用此接口。
【举例】
无。
ss_mpi_cipher_deinit¶
【描述】
去初始化CIPHER模块。
【语法】
td_s32 ss_mpi_cipher_deinit(td_void);
【参数】
无。
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_cipher.h、ss_mpi_cipher.h
库文件：libss_cipher.a、libss_cipher.so
【注意】
支持多次调用。
初始化和去初始化成对使用。
【举例】
无。
ss_mpi_cipher_create¶
【描述】
对称算法加解密时创建的CIPHER句柄。
【语法】
td_s32 ss_mpi_cipher_create (td_handle *handle, const ot_cipher_attr *cipher_attr);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_cipher.h、ss_mpi_cipher.h
库文件：libss_cipher.a、libss_cipher.so
【注意】
handle、cipher_attr不能为空。
SS928V100、SS626V100支持15路CIPHER通道。
使用完通道后，应销毁对应的通道。
【举例】
无。
ss_mpi_cipher_destroy¶
【描述】
对称算法加解密时销毁的CIPHER句柄。
【语法】
td_s32 ss_mpi_cipher_destroy (td_handle handle);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_cipher.h、ss_mpi_cipher.h
库文件：libss_cipher.a、libss_cipher.so
【注意】
创建与销毁通道成对使用。
【举例】
无。
ss_mpi_cipher_set_cfg¶
【描述】
对称加解密时配置CIPHER通道对应的信息。详细配置请参见结构体ot_cipher_ctrl。
【语法】
td_s32 ss_mpi_cipher_set_cfg (td_handle handle, const ot_cipher_ctrl *ctrl);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_cipher.h、ss_mpi_cipher.h
库文件：libss_cipher.a、libss_cipher.so
【注意】
CIPHER句柄必须已创建。
ctrl不能为空。
【举例】
无。
ss_mpi_cipher_get_cfg¶
【描述】
对称加解密时获取CIPHER通道对应的配置信息。
【语法】
td_s32 ss_mpi_cipher_get_cfg(td_handle handle, ot_cipher_ctrl *ctrl);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_cipher.h、ss_mpi_cipher.h
库文件：libss_cipher.a、libss_cipher.so
【注意】
CIPHER句柄必须已创建。
ctrl不能为空。
【举例】
无。
ss_mpi_cipher_encrypt¶
【描述】
对称加解密时对物理内存数据进行加密。
【语法】
td_s32 ss_mpi_cipher_encrypt(td_handle handle, td_phys_addr_t src_phys_addr, td_phys_addr_t dst_phys_addr, td_u32 byte_len);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_cipher.h、ss_mpi_cipher.h
库文件：libss_cipher.a、libss_cipher.so
【注意】
CIPHER句柄必须已创建。
可多次调用，需配合 ss_mpi_cipher_set_cfg 使用，使用方法可参考 注意事项。
模式为CTR/CCM/GCM时数据的长度为任意长度，其他模式要求block对齐。
加密源地址、目的地址可以相同。
optee平台不支持。
【举例】
无。
ss_mpi_cipher_decrypt¶
【描述】
对称加解密时对物理内存数据进行解密。
【语法】
td_s32 ss_mpi_cipher_decrypt(td_handle handle, td_phys_addr_t src_phys_addr, td_phys_addr_t dst_phys_addr, td_u32 byte_len);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_cipher.h、ss_mpi_cipher.h
库文件：libss_cipher.a、libss_cipher.so
【注意】
CIPHER句柄必须已创建。
可多次调用，需配合 ss_mpi_cipher_set_cfg 使用，使用方法可参考 注意事项。
模式为CTR/CCM/GCM时数据的长度为任意长度，其他模式要求block对齐。
解密的源地址、目的地址可以相同。
optee平台不支持。
【举例】
无。
ss_mpi_cipher_encrypt_virt¶
【描述】
对称加解密时对虚拟内存数据进行加密。
【语法】
td_s32 ss_mpi_cipher_encrypt_virt(td_handle handle, const td_u8 *src_data, td_u8 *dst_data, td_u32 byte_len);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_cipher.h、ss_mpi_cipher.h
库文件：libss_cipher.a、libss_cipher.so
【注意】
CIPHER句柄必须已创建。
可多次调用，需配合 ss_mpi_cipher_set_cfg 使用，使用方法可参考“注意事项” 。
模式为CTR/CCM/GCM时数据的长度为任意长度，其他模式要求block对齐。
加密的源地址、目的地址可以相同。
一次加密的数据长度byte_len最大不能超过4M。
【举例】
无。
ss_mpi_cipher_decrypt_virt¶
【描述】
对称加解密时对虚拟内存数据进行解密。
【语法】
td_s32 ss_mpi_cipher_decrypt_virt(td_handle handle, const td_u8 *src_data, td_u8 *dst_data, td_u32 byte_len);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_cipher.h、ss_mpi_cipher.h
库文件：libss_cipher.a、libss_cipher.so
【注意】
CIPHER句柄必须已创建。
可多次调用，需配合ss_mpi_cipher_set_cfg 使用，使用方法可参考“注意事项” 。
模式为CTR/CCM/GCM时数据的长度为任意长度，其他模式要求block对齐。
解密的源地址、目的地址可以相同。
一次解密的数据长度byte_len最大不能超过4M。
【举例】
无。
ss_mpi_cipher_encrypt_multi_pack¶
【描述】
对称加解密时进行多个包数据的加密。
【语法】
td_s32 ss_mpi_cipher_encrypt_multi_pack(td_handle handle, const ot_cipher_data *data_pack,
td_u32 data_pack_num);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_cipher.h、ss_mpi_cipher.h
库文件：libss_cipher.a、libss_cipher.so
【注意】
CIPHER句柄必须已创建。
可多次调用，需配合 ss_mpi_cipher_set_cfg使用，使用方法可参考 “注意事项”。
对于多个包的操作，每个包都使用ss_mpi_cipher_set_cfg配置的向量进行运算，前一个包的向量运算结果不会作用于下一个包的运算，每个包都是独立运算的。前一次函数调用的结果也不会影响后一次函数调用的运算结果。
加密的源地址、目的地址可以相同。
data_pack_num取值范围为1~5000。
optee平台不支持。
【举例】
无。
ss_mpi_cipher_decrypt_multi_pack¶
【描述】
对称加解密时进行多个包数据的解密。
【语法】
td_s32 ss_mpi_cipher_decrypt_multi_pack(td_handle handle, const ot_cipher_data *data_pack, td_u32 data_pack_num);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_cipher.h、ss_mpi_cipher.h
库文件：libss_cipher.a、libss_cipher.so
【注意】
CIPHER句柄必须已创建。
可多次调用，需配合 ss_mpi_cipher_set_cfg 使用，使用方法可参考 “注意事项”。
对于多个包的操作，每个包都使用ss_mpi_cipher_set_cfg配置的向量进行运算，前一个包的向量运算结果不会作用于下一个包的运算，每个包都是独立运算的。前一次函数调用的结果也不会影响后一次函数调用的运算结果。
解密的源地址、目的地址可以相同。
data_pack_num取值范围为1~5000。
optee平台不支持。
【举例】
无。
ss_mpi_cipher_get_tag¶
【描述】
对称加解密时CCM/GCM模式获取TAG值。
【语法】
td_s32 ss_mpi_cipher_get_tag(td_handle handle, td_u8 *tag, td_u32 tag_len);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_cipher.h、ss_mpi_cipher.h
库文件：libss_cipher.a、libss_cipher.so
【注意】
CIPHER句柄必须已创建。
tag不能为空。
输入tag_len小于ot_cipher_ctrl_aes_ccm_gcm结构体成员tag_len指定的值时，接口异常。
只有在CCM、GCM模式下此接口才有效。
【举例】
无。
ss_mpi_cipher_hash_init¶
【描述】
初始化HASH模块。
【语法】
td_s32 ss_mpi_cipher_hash_init(const ot_cipher_hash_attr *hash_attr, td_handle *handle);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_cipher.h、ss_mpi_cipher.h
库文件：libss_cipher.a、libss_cipher.so
【注意】
hash_attr，handle不能为空。
如果有其他程序正在使用HASH模块，返回失败状态。
【举例】
无。
ss_mpi_cipher_hash_update¶
【描述】
计算hash值。
【语法】
td_s32 ss_mpi_cipher_hash_update(td_handle handle, const td_u8 *in_data, td_u32 in_data_len);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_cipher.h、ss_mpi_cipher.h
库文件：libss_cipher.a、libss_cipher.so
【注意】
Hash句柄必须已经创建。
可以分多次调用，每次计算若干个block。
【举例】
无。
ss_mpi_cipher_hash_final¶
【描述】
获取hash值。
【语法】
td_s32 ss_mpi_cipher_hash_final(td_handle handle, td_u8 *out_hash, td_u32 out_hash_len);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_cipher.h、ss_mpi_cipher.h
库文件：libss_cipher.a、libss_cipher.so
【注意】
out_hash_len不能小于指定hash的输出长度。sha256输出长度为32byte，sha384输出长度为48byte，sha512输出长度为64byte，sm3输出长度为32byte。
【举例】
无。
ss_mpi_cipher_get_random_num¶
【描述】
生成随机数。
【语法】
td_s32 ss_mpi_cipher_get_random_num(td_u32 *random_num);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_cipher.h、ss_mpi_cipher.h
库文件：libss_cipher.a、libss_cipher.so
【注意】
random_num不能为空。
【举例】
无。
ss_mpi_cipher_rsa_public_encrypt¶
【描述】
使用RSA公钥加密一段明文。
【语法】
td_s32 ss_mpi_cipher_rsa_public_encrypt(ot_cipher_rsa_scheme scheme, ot_cipher_hash_type sha_type, const ot_cipher_rsa_public_key *rsa_key, const ot_cipher_common_data *plain_txt, ot_cipher_common_data*cipher_txt);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_cipher.h、ss_mpi_cipher.h
库文件：libss_cipher.a、libss_cipher.so
【注意】
rsa_key，plain_txt，cipher_txt不能为空。
cipher_txt的成员data_len即是加密的数据缓冲区长度，也是加密输出的数据长度。缓冲区长度不能小于输出的数据长度。
RSA填充方式为OT_CIPHER_RSA_SCHEME_PKCS1_V15时，sha_type不影响加解密结果。
【举例】
无。
ss_mpi_cipher_rsa_private_decrypt¶
【描述】
使用RSA私钥解密一段密文。
【语法】
td_s32 ss_mpi_cipher_rsa_private_decrypt(ot_cipher_rsa_scheme scheme, ot_cipher_hash_type sha_type, const ot_cipher_rsa_private_key *rsa_key, const ot_cipher_common_data *cipher_txt, ot_cipher_common_data*plain_txt);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_cipher.h、ss_mpi_cipher.h
库文件：libss_cipher.a、libss_cipher.so
【注意】
rsa_key，plain_txt，cipher_txt不能为空。
plain_txt的成员data_len即是解密的数据缓冲区长度，也是解密输出的数据长度。缓冲区长度不能小于输出的数据长度。
【举例】
无。
ss_mpi_cipher_rsa_private_encrypt¶
【描述】
使用RSA私钥加密一段明文。
【语法】
td_s32 ss_mpi_cipher_rsa_private_encrypt(ot_cipher_rsa_scheme scheme, ot_cipher_hash_type sha_type, const ot_cipher_rsa_private_key *rsa_key, const ot_cipher_common_data *plain_txt, ot_cipher_common_data *cipher_txt);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_cipher.h、ss_mpi_cipher.h
库文件：libss_cipher.a、libss_cipher.so
【注意】
rsa_key，plain_txt，cipher_txt不能为空。
cipher_txt的成员data_len即是加密的数据缓冲区长度，也是加密输出的数据长度。缓冲区长度不能小于输出的数据长度。
【举例】
无。
ss_mpi_cipher_rsa_public_decrypt¶
【描述】
使用RSA公钥解密一段密文。
【语法】
td_s32 ss_mpi_cipher_rsa_public_decrypt(ot_cipher_rsa_scheme scheme, ot_cipher_hash_type sha_type, const ot_cipher_rsa_public_key *rsa_key, const ot_cipher_common_data *cipher_txt, ot_cipher_common_data *plain_txt);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_cipher.h、ss_mpi_cipher.h
库文件：libss_cipher.a、libss_cipher.so
【注意】
rsa_key，plain_txt，cipher_txt不能为空。
plain_txt的成员data_len即是解密的数据缓冲区长度，也是解密输出的数据长度。缓冲区长度不能小于输出的数据长度。
【举例】
无。
ss_mpi_cipher_rsa_sign¶
【描述】
使用RSA私钥签名一段文本。
【语法】
td_s32 ss_mpi_cipher_rsa_sign(ot_cipher_rsa_scheme scheme, ot_cipher_hash_type sha_type, const ot_cipher_rsa_private_key *rsa_key, const ot_cipher_sign_in_data *rsa_data, ot_cipher_common_data *sign_data);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_cipher.h、ss_mpi_cipher.h
库文件：libss_cipher.a、libss_cipher.so
【注意】
rsa_key，rsa_data，sign_data不能为空。
sign_data的成员data_len即是签名的数据缓冲区长度，也是签名输出的数据长度。缓冲区长度不能小于输出的数据长度。
【举例】
无。
ss_mpi_cipher_rsa_verify¶
【描述】
使用RSA公钥验证一段文本。
【语法】
td_s32 ss_mpi_cipher_rsa_verify(ot_cipher_rsa_scheme scheme, ot_cipher_hash_type sha_type, const ot_cipher_rsa_public_key *rsa_key, const ot_cipher_sign_in_data *rsa_data, const ot_cipher_common_data *sign_data);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_cipher.h、ss_mpi_cipher.h
库文件：libss_cipher.a、libss_cipher.so
【注意】
rsa_key，rsa_data，sign_data不能为空。
sign_data的成员data_len必须与rsa_key的n_len保持一致。
【举例】
无。
ss_mpi_cipher_sm2_encrypt¶
【描述】
使用SM2公钥加密一段明文。
【语法】
td_s32 ss_mpi_cipher_sm2_encrypt(const ot_cipher_sm2_public_key *sm2_key, const ot_cipher_common_data *plain_txt, ot_cipher_common_data*cipher_txt);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_cipher.h、ss_mpi_cipher.h
库文件：libss_cipher.a、libss_cipher.so
【注意】
sm2_key，plain_txt，cipher_txt不能为空。
cipher_txt的成员data_len即是加密的数据缓冲区长度，也是加密输出的数据长度。缓冲区长度不能小于输出的数据长度。
SS928V100、SS626V100不支持SM2接口。
【举例】
无。
ss_mpi_cipher_sm2_decrypt¶
【描述】
使用SM2私钥解密一段密文。
【语法】
td_s32 ss_mpi_cipher_sm2_decrypt(const ot_cipher_sm2_private_key *sm2_key, const ot_cipher_common_data *cipher_txt, ot_cipher_common_data*plain_txt);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_cipher.h、ss_mpi_cipher.h
库文件：libss_cipher.a、libss_cipher.so
【注意】
sm2_key，plain_txt，cipher_txt不能为空。
plain_txt的成员data_len即是解密的数据缓冲区长度，也是解密输出的数据长度。缓冲区长度不能小于输出的数据长度。
SS928V100、SS626V100不支持SM2接口。
【举例】
无。
ss_mpi_cipher_sm2_sign¶
【描述】
使用SM2签名一段文本。
【语法】
td_s32 ss_mpi_cipher_sm2_sign(const ot_cipher_sm2_sign *sm2_sign, const ot_cipher_sign_in_data *sm2_data, ot_cipher_sm2_sign_data *sign_data);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_cipher.h、ss_mpi_cipher.h
库文件：libss_cipher.a、libss_cipher.so
【注意】
sm2_sign，sm2_data，sign_data不能为空。
当前SM2只支持签名数据类型OT_CIPHER_SIGN_TYPE_MSG。
SS928V100、SS626V100不支持SM2接口。
【举例】
无。
ss_mpi_cipher_sm2_verify¶
【描述】
使用SM2验证一段文本。
【语法】
td_s32 ss_mpi_cipher_sm2_verify(const ot_cipher_sm2_verify *sm2_verify, const ot_cipher_sign_in_data *sm2_data, const ot_cipher_sm2_sign_data*sign_data);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_cipher.h、ss_mpi_cipher.h
库文件：libss_cipher.a、libss_cipher.so
【注意】
sm2_verify，sm2_data，sign_data不能为空。
当前SM2只支持签名数据类型OT_CIPHER_SIGN_TYPE_MSG。
SS928V100、SS626V100不支持SM2接口。
【举例】
无。
ss_mpi_keyslot_create¶
【描述】
对称加解密时创建的keyslot句柄。
【语法】
td_s32 ss_mpi_keyslot_create(const ot_keyslot_attr *attr, td_handle *keyslot);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_cipher.h、ss_mpi_cipher.h
库文件：libss_cipher.a、libss_cipher.so
【注意】
attr、keyslot不能为空。
使用完通道后，应销毁对应的通道。
最多可创建16个软件通道。
【举例】
无。
ss_mpi_keyslot_destroy¶
【描述】
对称加解密时销毁的keyslot句柄。
【语法】
td_s32 ss_mpi_keyslot_destroy (td_handle keyslot);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_cipher.h、ss_mpi_cipher.h
库文件：libss_cipher.a、libss_cipher.so
【注意】
keyslot句柄必须已创建。
创建和销毁keyslot通道必须成对存在。
【举例】
无。
ss_mpi_cipher_attach¶
【描述】
对称加解密时cipher句柄与keyslot句柄绑定。
【语法】
td_s32 ss_mpi_cipher_attach(td_handle cipher, td_handle keyslot);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_cipher.h、ss_mpi_cipher.h
库文件：libss_cipher.a、libss_cipher.so
【注意】
cipher、keyslot句柄必须已创建。在句柄未创建的情况下，句柄之间的绑定可能成功，但是会导致功能的失败。
绑定和解绑定必须成对使用。
【举例】
无。
ss_mpi_cipher_detach¶
【描述】
对称加解密时cipher 句柄与keyslot句柄解绑定。
【语法】
td_s32 ss_mpi_cipher_detach(td_handle cipher, td_handle keyslot);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_cipher.h、ss_mpi_cipher.h
库文件：libss_cipher.a、libss_cipher.so
【注意】
cipher、keyslot句柄必须已创建。
绑定和解绑定必须成对使用。
【举例】
无。
数据类型¶
相关数据类型、数据结构定义如下（其他公共数据类型定义请参考ot_type.h）：
ot_cipher_work_mode：定义CIPHER工作模式。
ot_cipher_alg：定义CIPHER加密算法。
ot_cipher_key_len：定义CIPHER密钥长度。
ot_cipher_bit_width：定义CIPHER加密位宽。
ot_cipher_ctrl_chg_flag：定义CIPHER 向量变更标志。
ot_cipher_type：定义CIPHER加解密类型选择。
ot_cipher_attr：定义CIPHER加解密属性结构体。
ot_cipher_ctrl_aes：AES加密控制信息结构体。
ot_cipher_ctrl_aes_ccm_gcm：AES-CCM、AES-GCM 加密控制信息结构体。
ot_cipher_ctrl_sm4：定义SM4加密控制信息结构体。
ot_cipher_ctrl：定义加密控制信息结构体。
ot_cipher_data：定义CIPHER加解密数据。
ot_cipher_hash_type：定义CIPHER哈希算法类型。
ot_cipher_hash_attr：定义CIPHER哈希算法初始化输入结构体。
ot_cipher_common_data：定义通用输入输出数据格式。
ot_cipher_rsa_scheme：定义RSA算法填充。
ot_cipher_rsa_public_key：定义RSA公钥结构体。
ot_cipher_rsa_private_key：定义RSA私钥结构体。
ot_cipher_sign_type：定义非对称算法签名验签输入数据类型。
ot_cipher_sign_in_data：定义非对称算法签名验签输入数据结构体。
ot_cipher_sm2_public_key：定义SM2公钥结构体。
ot_cipher_sm2_private_key：定义SM2私钥结构体。
ot_cipher_sm2_sign：定义SM2签名结构体。
ot_cipher_sm2_verify：定义SM2验签结构体。
ot_cipher_sm2_sign_data：定义SM2签名验签数据结构体。
ot_keyslot_type：keyslot类型枚举值。
ot_keyslot_secure_mode：keyslot安全模式枚举值。
ot_keyslot_attr：keyslot属性结构体。
OT_CIPHER_MAX_IV_SIZE_IN_WORD：CIPHER 的IV最大长度。
OT_CIPHER_SM2_LEN_IN_WORD：SM2密钥、签名验签数据长度。
ot_cipher_work_mode¶
【说明】
定义CIPHER工作模式。
【定义】
/* Cipher work mode */
typedef enum {
OT_CIPHER_WORK_MODE_ECB = 0x0,
OT_CIPHER_WORK_MODE_CBC,
OT_CIPHER_WORK_MODE_CFB,
OT_CIPHER_WORK_MODE_OFB,
OT_CIPHER_WORK_MODE_CTR,
OT_CIPHER_WORK_MODE_CCM,
OT_CIPHER_WORK_MODE_GCM,
OT_CIPHER_WORK_MODE_BUTT,
} ot_cipher_work_mode;
【成员】
CCM（Counter with Cipher Block Chaining-Message Authentication）模式。 |
|
【注意事项】
ECB/CBC/CFB/OFB模式输入数据长度必须block对齐。
【相关数据类型及接口】
ot_cipher_alg¶
【说明】
定义CIPHER加密算法。
【定义】
/* Cipher algorithm */
typedef enum {
OT_CIPHER_ALG_AES = 0x0, /* Advanced encryption standard (AES) algorithm */
OT_CIPHER_ALG_SM1, /* SM1 algorithm. */
OT_CIPHER_ALG_SM4, /* SM4 algorithm. */
OT_CIPHER_ALG_DMA, /* DMA copy. */
OT_CIPHER_ALG_BUTT,
} ot_cipher_alg;
【成员】
【注意事项】
SS928V100、SS626V100不支持SM1、SM4。
【相关数据类型及接口】
ot_cipher_key_len¶
【说明】
定义CIPHER密钥长度。
【定义】
/* Key length */
typedef enum {
OT_CIPHER_KEY_DEFAULT = 0x0,
OT_CIPHER_KEY_AES_128BIT = 0x0,
OT_CIPHER_KEY_AES_192BIT = 0x1,
OT_CIPHER_KEY_AES_256BIT = 0x2,
OT_CIPHER_KEY_LEN_BUTT = 0x3,
} ot_cipher_key_len;
【成员】
【注意事项】
AES的密钥长度可以为128bit，192bit或256bit。
【相关数据类型及接口】
ot_cipher_bit_width¶
【说明】
定义CIPHER加密位宽。
【定义】
/* Cipher bit width */
typedef enum {
OT_CIPHER_BIT_WIDTH_1BIT = 0x0, /* 1-bit width */
OT_CIPHER_BIT_WIDTH_8BIT = 0x1, /* 8-bit width */
OT_CIPHER_BIT_WIDTH_64BIT = 0x2, /* 64-bit width */
OT_CIPHER_BIT_WIDTH_128BIT = 0x3, /* 128-bit width */
OT_CIPHER_BIT_WIDTH_BUTT,
} ot_cipher_bit_width;
【成员】
【注意事项】
无。
【相关数据类型及接口】
ot_cipher_ctrl_chg_flag¶
【说明】
定义CIPHER 向量变更标志。
【定义】
/* Cipher control parameters */
typedef enum {
OT_CIPHER_IV_CHG_NONE = 0, /** CIPHER set key and don't set IV */
OT_CIPHER_IV_CHG_ONE_PACK, /** CIPHER set key and IV for first package */
OT_CIPHER_IV_CHG_ALL_PACK, /** CIPHER set key and IV for all package */
OT_CIPHER_IV_CHG_BUTT,
} ot_cipher_ctrl_chg_flag;
【成员】
【注意事项】
无。
【相关数据类型及接口】
ot_cipher_type¶
【说明】
定义CIPHER加解密类型选择。
【定义】
/* Encryption/Decryption type selecting */
typedef enum {
OT_CIPHER_TYPE_NORMAL = 0x0,
OT_CIPHER_TYPE_BUTT,
} ot_cipher_type;
【成员】
【注意事项】
无。
【相关数据类型及接口】
ot_cipher_attr¶
【说明】
定义CIPHER加解密属性结构体。
【定义】
/* Structure of the cipher type */
typedef struct {
ot_cipher_type cipher_type;
} ot_cipher_attr;
【成员】
【注意事项】
无。
【相关数据类型及接口】
ot_cipher_ctrl_aes¶
【说明】
AES加密控制信息结构体。
【定义】
/* Structure of the cipher AES control information */
typedef struct {
td_u32 iv[OT_CIPHER_MAX_IV_SIZE_IN_WORD]; /* Initialization vector (IV) for 4 byte */
ot_cipher_bit_width bit_width; /* Bit width for encryption or decryption */
ot_cipher_key_len key_len; /* Key length */
ot_cipher_ctrl_chg_flag chg_flags;
} ot_cipher_ctrl_aes;
【成员】
【注意事项】
AES支持的工作模式为：ECB/CBC/CFB/OFB/CTR，其中CFB支持的位宽可以为1、8、128bit，OFB模式仅支持128bit位宽。其他模式默认只支持128bit位宽。
【相关数据类型及接口】
ot_cipher_ctrl_aes_ccm_gcm¶
【说明】
AES-CCM、AES-GCM加密控制信息结构体。
【定义】
/* Structure of the cipher AES CCM/GCM control information */
typedef struct {
td_u32 iv[OT_CIPHER_MAX_IV_SIZE_IN_WORD];
ot_cipher_key_len key_len;
td_u32 iv_len;
td_u32 tag_len;
td_u32 aad_len;
td_phys_addr_t aad_phys_addr;
td_u8 *aad_addr;
} ot_cipher_ctrl_aes_ccm_gcm;
【成员】
【注意事项】
对于CCM：向量iv长度iv_len可取{7, 8, 9, 10, 11, 12, 13} byte，iv存放算法标准中的Nonce数据N。加密数据的长度用n个Byte表示，且应满足条件：iv_len+n=15。因此，iv_len为13时，n为2，此时加密数据长度最长为65535byte，其它以此类推。tag的长度tag_len可取{4, 6, 8, 10, 12, 14, 16}byte，CCM加密时的向量N、关联数据A取值必须与解密时保持一致。
对于GCM：向量iv长度iv_len可取范围为[1~16]byte，tag的长度tag_len可为{12, 13, 14, 15, 16}byte，特殊情况可取4、8byte，GCM加密时的关联数据A取值必须与解密时保持一致。
linux平台关联数据A只支持物理地址，optee平台关联数据A只支持虚拟地址，linux平台请将物理地址传给aad_phys_addr，optee平台请将虚拟地址传给aad_phys_addr。
【相关数据类型及接口】
ot_cipher_ctrl_sm4¶
【说明】
定义SM4加密控制信息结构体。
【定义】
/* Structure of the cipher SM4 control information */
typedef struct {
td_u32 iv[OT_CIPHER_MAX_IV_SIZE_IN_WORD]; /* (IV) */
ot_cipher_ctrl_chg_flag chg_flags;
} ot_cipher_ctrl_sm4;
【成员】
【注意事项】
SM4支持的工作模式为：ECB/CBC/CFB/OFB/CTR，其中CFB支持的位宽可以为1、8、128bit，OFB模式仅支持128bit位宽。
ECB模式可以不配置iv。
SS928V100、SS626V100不支持SM4。
【相关数据类型及接口】
ot_cipher_ctrl¶
【说明】
定义加密控制信息结构体。
【定义】
/* Structure of the cipher control information */
typedef struct {
ot_cipher_alg alg; /* cipher algorithm */
ot_cipher_work_mode work_mode; /* algorithm work mode */
union {
ot_cipher_ctrl_aes aes_ctrl; /* AES ECB/CBC/CFB/OFB/CTR control */
ot_cipher_ctrl_aes_ccm_gcm aes_ccm_gcm_ctrl; /* AES CCM/GCM control */
ot_cipher_ctrl_sm4 sm4_ctrl; /* SM4 ECB/CBC/CFB/OFB/CTR control */
};
} ot_cipher_ctrl;
【成员】
【注意事项】
当算法 alg 为 OT_CIPHER_ALG_AES 且工作模式 work_mode 为 OT_CIPHER_WORK_MODE_ECB、OT_CIPHER_WORK_MODE_CBC、OT_CIPHER_WORK_MODE_CFB、OT_CIPHER_WORK_MODE_OFB、OT_CIPHER_WORK_MODE_CTR中的一种时，联合体指向的结构体为 ot_cipher_ctrl_aes。
当算法 alg 为 OT_CIPHER_ALG_AES 且工作模式 work_mode 为 OT_CIPHER_WORK_MODE_CCM、OT_CIPHER_WORK_MODE_GCM中的一种时，联合体指向的结构体为 ot_cipher_ctrl_aes_ccm_gcm。
当算法 alg 为 OT_CIPHER_ALG_SM4 且工作模式 work_mode 为 OT_CIPHER_WORK_MODE_ECB、OT_CIPHER_WORK_MODE_CBC、OT_CIPHER_WORK_MODE_CFB、OT_CIPHER_WORK_MODE_OFB、OT_CIPHER_WORK_MODE_CTR中的一种时，联合体指向的结构体为 ot_cipher_ctrl_sm4。
【相关数据类型及接口】
ot_cipher_data¶
【说明】
定义CIPHER加解密数据。
【定义】
/* Cipher data */
typedef struct {
td_phys_addr_t src_phys_addr; /* phy address of the original data */
td_phys_addr_t dst_phys_addr; /* phy address of the purpose data */
td_u32 byte_len; /* cipher data length*/
} ot_cipher_data;
【成员】
【注意事项】
无。
【相关数据类型及接口】
ot_cipher_hash_type¶
【说明】
定义CIPHER哈希算法类型。
【定义】
/* Hash algorithm type */
typedef enum {
OT_CIPHER_HASH_TYPE_SHA1 = 0x00,
OT_CIPHER_HASH_TYPE_SHA224,
OT_CIPHER_HASH_TYPE_SHA256,
OT_CIPHER_HASH_TYPE_SHA384,
OT_CIPHER_HASH_TYPE_SHA512,
OT_CIPHER_HASH_TYPE_SM3 = 0x10,
OT_CIPHER_HASH_TYPE_HMAC_SHA1 = 0x20,
OT_CIPHER_HASH_TYPE_HMAC_SHA224,
OT_CIPHER_HASH_TYPE_HMAC_SHA256,
OT_CIPHER_HASH_TYPE_HMAC_SHA384,
OT_CIPHER_HASH_TYPE_HMAC_SHA512,
OT_CIPHER_HASH_TYPE_HMAC_SM3 = 0x30,
OT_CIPHER_HASH_TYPE_BUTT,
} ot_cipher_hash_type;
【成员】
【注意事项】
不支持SHA1、SHA224、HMAC-SHA1、HMAC-SHA224。
SS928V100、SS626V100不支持SM3、HMAC-SM3。
【相关数据类型及接口】
ot_cipher_hash_attr¶
【说明】
定义CIPHER哈希算法初始化输入结构体。
【定义】
/* Hash init struct input */
typedef struct {
td_u8 *hmac_key;
td_u32 hmac_key_len;
ot_cipher_hash_type sha_type;
} ot_cipher_hash_attr;
【成员】
【注意事项】
无。
【相关数据类型及接口】
ot_cipher_common_data¶
【说明】
定义通用输入输出数据格式结构体。
【定义】
typedef struct {
td_u8 *data;
td_u32 data_len;
} ot_cipher_common_data;
【成员】
【注意事项】
data_len作为输入时，为输入的缓冲区长度；作为输出时，即是输出的缓冲区长度，同时也是输出数据的长度，缓冲区长度不能小于输出数据的长度。
【相关数据类型及接口】
ot_cipher_rsa_scheme¶
【说明】
定义RSA算法填充方式。
【定义】
typedef enum {
OT_CIPHER_RSA_SCHEME_PKCS1_V15 = 0x00, /* PKCS#1 V15 */
OT_CIPHER_RSA_SCHEME_PKCS1_V21, /* PKCS#1 V21, PSS for signing, OAEP for encryption */
OT_CIPHER_RSA_SCHEME_BUTT,
} ot_cipher_rsa_scheme;
【成员】
【注意事项】
建议使用PKCS#1 V21填充方式，其他方式为弱填充或不安全填充方式。
【相关数据类型及接口】
ot_cipher_rsa_public_key¶
【说明】
定义RSA公钥结构体。
【定义】
/* RSA pub key struct */
typedef struct {
td_u8 *n; /* Point to pub modulus */
td_u8 *e; /* Point to pub exponent */
td_u16 n_len; /* Length of pub modulus, max value is 512Byte */
td_u16 e_len; /* Length of pub exponent, max value is 512Byte */
} ot_cipher_rsa_public_key;
【成员】
【注意事项】
n、e不能为空。
【相关数据类型及接口】
ot_cipher_rsa_private_key¶
【说明】
定义RSA私钥结构体。
【定义】
/* RSA private key struct */
typedef struct {
td_u8 *n; /* Pub modulus */
td_u8 *e; /* Pub 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 pub modulus */
td_u16 e_len; /* Length of pub exponent */
td_u16 d_len; /* Length of private exponent */
td_u16 p_len;
td_u16 q_len;
td_u16 dp_len;
td_u16 dq_len;
td_u16 qp_len;
} ot_cipher_rsa_private_key;
【成员】
【注意事项】
n不能为空。
d为非空时，e、p、q、dp、dq、qp可以为空；d为空时，p、q、dp、dq、qp不能为空。
【相关数据类型及接口】
ot_cipher_sign_type¶
【说明】
定义非对称算法签名验签输入数据类型。
【定义】
typedef enum {
OT_CIPHER_SIGN_TYPE_MSG = 0x00,
OT_CIPHER_SIGN_TYPE_HASH,
OT_CIPHER_SIGN_TYPE_BUTT,
} ot_cipher_sign_type;
【成员】
【注意事项】
对于RSA算法，既支持OT_CIPHER_SIGN_TYPE_MSG，也支持OT_CIPHER_SIGN_TYPE_HASH。
对于SM2算法，当前仅支持OT_CIPHER_SIGN_TYPE_MSG。
【相关数据类型及接口】
ot_cipher_sign_in_data¶
【说明】
定义非对称算法签名验签输入数据结构体。
【定义】
typedef struct {
ot_cipher_sign_type sign_type;
td_u8 *input;
td_u32 input_len;
} ot_cipher_sign_in_data;
【成员】
【注意事项】
无。
【相关数据类型及接口】
ot_cipher_sm2_public_key¶
【说明】
定义SM2公钥结构体。
【定义】
typedef struct {
td_u32 px[OT_CIPHER_SM2_LEN_IN_WORD];
td_u32 py[OT_CIPHER_SM2_LEN_IN_WORD];
} ot_cipher_sm2_public_key;
【成员】
【注意事项】
SS928V100、SS626V100不支持SM2。
【相关数据类型及接口】
ot_cipher_sm2_private_key¶
【说明】
定义SM2私钥结构体。
【定义】
typedef struct {
td_u32 d[OT_CIPHER_SM2_LEN_IN_WORD];
} ot_cipher_sm2_private_key;
【成员】
【注意事项】
SS928V100、SS626V100不支持SM2。
【相关数据类型及接口】
ot_cipher_sm2_sign¶
【说明】
定义SM2签名结构体。
【定义】
typedef struct {
td_u32 d[OT_CIPHER_SM2_LEN_IN_WORD];
td_u32 px[OT_CIPHER_SM2_LEN_IN_WORD];
td_u32 py[OT_CIPHER_SM2_LEN_IN_WORD];
td_u8 *id;
td_u16 id_len;
} ot_cipher_sm2_sign;
【成员】
【注意事项】
SS928V100、SS626V100不支持SM2。
【相关数据类型及接口】
ot_cipher_sm2_verify¶
【说明】
定义SM2验签结构体。
【定义】
typedef struct {
td_u32 px[OT_CIPHER_SM2_LEN_IN_WORD];
td_u32 py[OT_CIPHER_SM2_LEN_IN_WORD];
td_u8 *id;
td_u16 id_len;
} ot_cipher_sm2_verify;
【成员】
【注意事项】
SS928V100、SS626V100不支持SM2。
【相关数据类型及接口】
ot_cipher_sm2_sign_data¶
【说明】
定义SM2签名验签数据结构体。
【定义】
typedef struct {
td_u32 r[OT_CIPHER_SM2_LEN_IN_WORD];
td_u32 s[OT_CIPHER_SM2_LEN_IN_WORD];
} ot_cipher_sm2_sign_data;
【成员】
【注意事项】
SS928V100、SS626V100不支持SM2。
【相关数据类型及接口】
ot_keyslot_type¶
【说明】
keyslot类型枚举值。
【定义】
typedef enum {
OT_KEYSLOT_TYPE_MCIPHER, /* keyslot is used for mcipher. */
OT_KEYSLOT_TYPE_BUTT,
} ot_keyslot_type;
【成员】
【注意事项】
无。
【相关数据类型及接口】
ot_keyslot_secure_mode¶
【说明】
keyslot安全模式枚举值。
【定义】
typedef enum {
OT_KEYSLOT_SECURE_MODE_NONE = 0x00, /* no secure. */
OT_KEYSLOT_SECURE_MODE_TEE, /* tee. */
OT_KEYSLOT_SECURE_MODE_BUTT,
} ot_keyslot_secure_mode;
【成员】
【注意事项】
非安全CPU不能绑定TEE安全模式，安全CPU可绑定非安模式。
【相关数据类型及接口】
ot_keyslot_attr¶
【说明】
keyslot属性结构体。
【定义】
typedef struct {
ot_keyslot_type type;
ot_keyslot_secure_mode secure_mode;
} ot_keyslot_attr;
【成员】
【注意事项】
无。
【相关数据类型及接口】
OT_CIPHER_MAX_IV_SIZE_IN_WORD¶
【说明】
CIPHER 的IV最大长度。
【定义】
#define OT_CIPHER_MAX_IV_SIZE_IN_WORD 4
【注意事项】
无。
【相关数据类型及接口】
OT_CIPHER_SM2_LEN_IN_WORD¶
【说明】
SM2密钥、签名验签数据长度。
【定义】
#define OT_CIPHER_SM2_LEN_IN_WORD 8
【注意事项】
无。
【相关数据类型及接口】
错误码¶
CIPHER提供的错误码如下所示。
表 1 CIPHER模块的错误码
Proc调试信息¶
CIPHER状态¶
【调试信息】
执行 cat /proc/umap/cipher
[CIPHER] Version: [V1.0.0.0 B010 Release], Build Time[Apr 7 2021, 16:08:45]
---------------------------------------- cipher status --------------------
chn_id status decrypt alg mode key_len addr in/out
01 open 0 AES CCM 128 73cb0004/73cb1004
02 close 0 AES ECB 000 00000000/00000000
03 close 0 AES ECB 000 00000000/00000000
04 close 0 AES ECB 000 00000000/00000000
05 close 0 AES ECB 000 00000000/00000000
06 close 0 AES ECB 000 00000000/00000000
07 close 0 AES ECB 000 00000000/00000000
08 close 0 AES ECB 000 00000000/00000000
09 close 0 AES ECB 000 00000000/00000000
10 close 0 AES ECB 000 00000000/00000000
11 close 0 AES ECB 000 00000000/00000000
12 close 0 AES ECB 000 00000000/00000000
13 close 0 AES ECB 000 00000000/00000000
14 close 0 AES ECB 000 00000000/00000000
15 close 0 AES ECB 000 00000000/00000000
---------------------------------------------
key_from int_raw int_en int_status iv_out
00 0 0 0 07101112050000000000000000000000
00 0 0 0 00000000000000000000000000000000
00 0 0 0 00000000000000000000000000000000
00 0 0 0 00000000000000000000000000000000
00 0 0 0 00000000000000000000000000000000
00 0 0 0 00000000000000000000000000000000
00 0 0 0 00000000000000000000000000000000
00 0 0 0 00000000000000000000000000000000
00 0 0 0 00000000000000000000000000000000
00 0 0 0 00000000000000000000000000000000
00 0 0 0 00000000000000000000000000000000
00 0 0 0 00000000000000000000000000000000
00 0 0 0 00000000000000000000000000000000
00 0 0 0 00000000000000000000000000000000
00 0 0 0 00000000000000000000000000000000
【调试信息分析】
记录当前CIPHER各个通道的配置信息。
【参数说明】