前言

概述

CIPHER是安全算法模块，它提供了AES对称加解密算法，HASH及HMAC摘要算法，随机数算法，以及RSA不对称算法，主要用于对音视频码流进行加解密及数据合法性验证等场景。

说明： 本文未有特殊说明，SS927V100与SS928V100内容完全一致。

产品版本

与本文档相对应的产品版本如下。

产品名称

产品版本

SS928

V100

SS626

V100

SS927

V100

读者对象

本文档（本指南）主要适用于以下工程师：

  • 技术支持工程师

  • 软件开发工程师

符号约定

在本文中可能出现下列标志，它们所代表的含义如下。

符号

说明

表示如不避免则将会导致死亡或严重伤害的具有高等级风险的危害。

表示如不避免则可能导致死亡或严重伤害的具有中等级风险的危害。

表示如不避免则可能导致轻微或中度伤害的具有低等级风险的危害。

用于传递设备或环境安全警示信息。如不避免则可能会导致设备损坏、数据丢失、设备性能降低或其它不可预知的结果。

“须知”不涉及人身伤害。

对正文中重点信息的补充说明。

“说明”不是安全警示信息，不涉及人身、设备及环境伤害信息。

修订记录

修订记录累积了每次文档更新的说明。最新版本的文档包含以前所有文档版本的更新内容。

文档版本

发布日期

修改说明

00B01

2025-09-15

第1次临时版本发布。

概述

概述

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 规格差异说明

规格差异

SS928V100、SS626V100

AES (ECB/CBC/CTR/CFB/OFB)

支持

AES (CCM/GCM)

支持

HASH (SHA256)

HMAC (SHA256)

支持

HASH (SHA384/SHA512)

HMAC (SHA384/SHA512)

支持

RSA 2048/3072/4096

支持

TRNG

支持

SM2

不支持

SM3

不支持

SM4

不支持

使用流程

单包数据加解密（对称加解密算法）

场景说明

对单包数据进行加密或解密。当物理内存中有一段码流数据需要进行加/解密时，获取物理地址后在用户层调用CIPHER模块实现加/解密，或当虚拟内存中有一段数据需要进行加/解密时，获取虚拟地址后在用户层调用CIPHER模块实现加/解密。

工作流程

  1. CIPHER设备初始化。调用接口ss_mpi_cipher_init。

  2. 创建CIPHER句柄。调用接口ss_mpi_cipher_create。

  3. 创建KEYSLOT句柄。调用接口ss_mpi_keyslot_create。

  4. 绑定CIPHER和KEYSLOT句柄。调用接口ss_mpi_cipher_attach。

  5. 配置CIPHER控制信息。包含加解密算法、工作模式等信息。调用接口ss_mpi_cipher_set_cfg。

  6. 配置密钥。请参考《KLAD API 参考》1.2.1 明文KEY传递或1.2.2 ROOTKEY传递。

  7. 加解密数据。用户可调用以下任意接口加解密数据。

  8. 解绑定CIPHER和KEYSLOT句柄。调用接口ss_mpi_cipher_detach。

  9. 销毁KEYSLOT句柄。调用接口ss_mpi_keyslot_destroy。

  10. 销毁CIPHER句柄。调用接口ss_mpi_cipher_destroy。

  11. 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()

    图 1 CIPHER应用场景1，每次调用都需要更新IV

    【场景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()

    图 2 CIPHER应用场景2，只在第一次调用时配置IV

    请结合实际场景进行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模块实现加/解密。

工作流程

  1. CIPHER设备初始化。调用接口ss_mpi_cipher_init。

  2. 创建CIPHER句柄。调用接口ss_mpi_cipher_create。

  3. 创建KEYSLOT句柄。调用接口ss_mpi_keyslot_create。

  4. 绑定CIPHER和KEYSLOT句柄。调用接口ss_mpi_cipher_attach。

  5. 配置CIPHER控制信息。包含加解密算法、工作模式等信息。调用接口ss_mpi_cipher_set_cfg。

  6. 配置密钥。请参考《KLAD API 参考》1.2.1 明文KEY传递或1.2.2 ROOTKEY传递。

  7. 加解密数据。用户可调用以下任意接口加解密数据。

  8. 解绑定CIPHER和KEYSLOT句柄。调用接口ss_mpi_cipher_detach。

  9. 销毁KEYSLOT句柄。调用接口ss_mpi_keyslot_destroy。

  10. 销毁CIPHER句柄。调用接口ss_mpi_cipher_destroy。

  11. 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。

工作流程

  1. CIPHER设备初始化。调用接口ss_mpi_cipher_init。

  2. 创建CIPHER句柄。调用接口ss_mpi_cipher_create。

  3. 创建KEYSLOT句柄。调用接口ss_mpi_keyslot_create。

  4. 绑定CIPHER和KEYSLOT句柄。调用接口ss_mpi_cipher_attach。

  5. 配置CIPHER控制信息。包含加解密算法、工作模式等信息。调用接口ss_mpi_cipher_set_cfg。

  6. 配置密钥。请参考《KLAD API 参考》1.2.1 明文KEY传递或1.2.2 ROOTKEY传递。

  7. 加解密数据。用户可调用以下任意接口加解密数据。

  8. 获取TAG值。调用接口ss_mpi_cipher_get_tag。

  9. 解绑定CIPHER和KEYSLOT句柄。调用接口ss_mpi_cipher_detach。

  10. 销毁KEYSLOT句柄。调用接口ss_mpi_keyslot_destroy。

  11. 销毁CIPHER句柄。调用接口ss_mpi_cipher_destroy。

  12. 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。

工作流程

  1. CIPHER设备初始化。调用接口ss_mpi_cipher_init完成。

  2. 创建一路HASH，获取HASH句柄，选择HASH算法。调用接口ss_mpi_cipher_hash_init完成。

  3. 输入数据，逐个数据块依次计算HASH值。调用接口ss_mpi_cipher_hash_update完成。

  4. 如果摘要未计算完成，再次执行3。

  5. 完成摘要计算，结束输入，获取计算结果。调用接口ss_mpi_cipher_hash_final完成。

  6. 关闭CIPHER设备。调用接口ss_mpi_cipher_deinit完成。

注意事项

支持软件多通道，可同时进行多个HASH运算， 即执行2启动一个HASH运算，在本次HASH计算未完成（即未执行5）之前，可申请一个新通道启动另一个HASH运算，直到申请不到通道为止。

最多支持15个HASH软件通道，15个通道可同时都被打开，但同一时间内只有一个通道在进行运算。

HMAC计算（摘要算法）

场景说明

计算数据的HMAC值。基于的HASH算法为 SHA256/SHA384/SHA512。

工作流程

HMAC运算开发操作步骤如下：

  1. 调用ss_mpi_cipher_init初始化CIPHER模块。

  2. 调用ss_mpi_cipher_hash_init选择使用的HASH算法，并配置HMAC计算的密钥，初始化HASH模块。

  3. 调用ss_mpi_cipher_hash_update输入数据，可以一个BLOCK接一个BLOCK输入。

  4. 调用ss_mpi_cipher_hash_final结束输入，并输出HMAC值。

  5. 调用ss_mpi_cipher_deinit 去初始化CIPHER设备。

注意事项

支持软件多通道，可同时进行多个HMAC运算， 即执行2启动一个HMAC运算，在本次HMAC计算未完成（即未执行4）之前，可申请一个新通道启动另一个HMAC运算，直到申请不到通道为止。

HMAC和HASH共用15个软件通道，15个通道可同时都被打开，但同一时间内只有一个通道在进行运算。

随机数生成

场景说明

获取硬件产生的真随机数。

工作流程

生成随机数据的过程如下：

  1. CIPHER设备初始化。调用接口ss_mpi_cipher_init完成。

  2. 获取32bits的随机数。调用接口ss_mpi_cipher_get_random_num完成。

  3. 关闭CIPHER设备。调用接口ss_mpi_cipher_deinit完成。

注意事项

无。

RSA加解密（不对称加解密算法）

场景说明

对数据进行RSA不对称算法进行加解密，当使用公钥加密的数据，必须使用私钥进行解密，反之，使用私钥加密的数据，必须使用公钥进行解密。

该算法请参考：rfc3447. RSA Cryptography Specifications。

工作流程

对数据进行不对称的RSA加解密的过程如下：

  1. CIPHER设备初始化。调用接口ss_mpi_cipher_init完成。

  2. 对数据进行加解密。根据使用的密钥不同，分为4个接口，用户可以调用以下任一接口进行加解密等。

  3. 关闭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签名及验签的过程如下：

  1. CIPHER设备初始化。调用接口ss_mpi_cipher_init完成。

  2. 对数据进行签名验证，调用以下接口签名验证。

  3. 关闭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);

【参数】

无。

【返回值】

返回值

描述

0

成功。

非0

参见错误码。

【需求】

  • 头文件：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);

【参数】

无。

【返回值】

返回值

描述

0

成功。

非0

参见错误码。

【需求】

  • 头文件：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);

【参数】

参数名称

描述

输入/输出

handle

CIPHER句柄指针。

输出

cipher_attr

CIPHER属性指针。

输入

【返回值】

返回值

描述

0

成功。

非0

参见错误码。

【需求】

  • 头文件：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);

【参数】

参数名称

描述

输入/输出

handle

CIPHER句柄。

输入

【返回值】

返回值

描述

0

成功。

非0

参见错误码。

【需求】

  • 头文件：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);

【参数】

参数名称

描述

输入/输出

handle

CIPHER句柄。

输入

ctrl

控制信息指针。

输入

【返回值】

返回值

描述

0

成功。

非0

参见错误码。

【需求】

  • 头文件：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);

【参数】

参数名称

描述

输入/输出

handle

CIPHER句柄。

输入

ctrl

CIPHER通道的配置信息。

输出

【返回值】

返回值

描述

0

成功。

非0

参见错误码。

【需求】

  • 头文件：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);

【参数】

参数名称

描述

输入/输出

handle

CIPHER句柄。

输入

src_phys_addr

源数据（待加密的数据）的物理地址。

输入

dst_phys_addr

存放加密结果的物理地址。

输入

byte_len

数据的长度（单位：byte）。

输入

【返回值】

返回值

描述

0

成功。

非0

参见错误码。

【需求】

  • 头文件：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);

【参数】

参数名称

描述

输入/输出

handle

CIPHER句柄。

输入

src_phys_addr

源数据（待解密的数据）的物理地址。

输入

dst_phys_addr

存放解密结果的物理地址。

输入

byte_len

数据的长度（单位：byte）。

输入

【返回值】

返回值

描述

0

成功。

非0

参见错误码。

【需求】

  • 头文件：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);

【参数】

参数名称

描述

输入/输出

handle

CIPHER句柄。

输入

src_data

源数据（待加密的数据）的虚拟地址。

输入

dst_data

存放加密结果的虚拟地址。

输出

byte_len

数据的长度（单位：byte）。

输入

【返回值】

返回值

描述

0

成功。

非0

参见错误码。

【需求】

  • 头文件：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);

【参数】

参数名称

描述

输入/输出

handle

CIPHER句柄。

输入

src_data

源数据（待解密的数据）的虚拟地址。

输入

dst_data

存放解密结果的虚拟地址。

输出

byte_len

数据的长度（单位：byte）。

输入

【返回值】

返回值

描述

0

成功。

非0

参见错误码。

【需求】

  • 头文件：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);

【参数】

参数名称

描述

输入/输出

handle

CIPHER句柄。

输入

data_pack

待加密的数据包。

输入

data_pack_num

待加密的数据包个数。

输入

【返回值】

返回值

描述

0

成功。

非0

参见错误码。

【需求】

  • 头文件：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);

【参数】

参数名称

描述

输入/输出

handle

CIPHER句柄。

输入

data_pack

待解密的数据包。

输入

data_pack_num

待解密的数据包个数。

输入

【返回值】

返回值

描述

0

成功。

非0

参见错误码。

【需求】

  • 头文件：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);

【参数】

参数名称

描述

输入/输出

handle

CIPHER句柄。

输入

tag

TAG值。

输出

tag_len

TAG的输入缓冲区的大小（单位：byte）。

输入

【返回值】

返回值

描述

0

成功。

非0

参见错误码。

【需求】

  • 头文件：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);

【参数】

参数名称

描述

输入/输出

hash_attr

用于计算HASH的结构体参数。

输入

handle

输出的HASH句柄。

输出

【返回值】

返回值

描述

0

成功。

非0

参见错误码。

【需求】

  • 头文件：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);

【参数】

参数名称

描述

输入/输出

handle

HASH句柄。

输入

in_data

输入数据。

输入

in_data_len

输入数据的长度，单位：byte。

输入

【返回值】

返回值

描述

0

成功。

非0

参见错误码。

【需求】

  • 头文件：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);

【参数】

参数名称

描述

输入/输出

handle

HASH句柄。

输入

out_hash

输出的HASH值。

输出

out_hash_len

输出的HASH缓冲区长度，单位：byte。

输入

【返回值】

返回值

描述

0

成功。

非0

参见错误码。

【需求】

  • 头文件：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);

【参数】

参数名称

描述

输入/输出

random_num

输出的随机数。

输出

【返回值】

返回值

描述

0

成功。

非0

参见错误码。

【需求】

  • 头文件：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);

【参数】

参数名称

描述

输入/输出

scheme

RSA填充方式。

输入

sha_type

RSA使用的摘要算法。

输入

rsa_key

密钥结构体。

输入

plain_txt

明文文本。

输入

cipher_txt

密文文本。

输入/输出

【返回值】

返回值

描述

0

成功。

非0

参见错误码。

【需求】

  • 头文件：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);

【参数】

参数名称

描述

输入/输出

scheme

RSA填充方式。

输入

sha_type

RSA使用的摘要算法。

输入

rsa_key

密钥结构体。

输入

cipher_txt

密文文本。

输入

plain_txt

明文文本。

输入/输出

【返回值】

返回值

描述

0

成功。

非0

参见错误码。

【需求】

  • 头文件：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);

【参数】

参数名称

描述

输入/输出

scheme

RSA填充方式。

输入

sha_type

RSA使用的摘要算法。

输入

rsa_key

密钥结构体。

输入

plain_txt

明文文本。

输入

cipher_txt

密文文本。

输入/输出

【返回值】

返回值

描述

0

成功。

非0

参见错误码。

【需求】

  • 头文件：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);

【参数】

参数名称

描述

输入/输出

scheme

RSA填充方式。

输入

sha_type

RSA使用的摘要算法。

输入

rsa_key

密钥结构体。

输入

cipher_txt

密文文本。

输入

plain_txt

明文文本。

输入/输出

【返回值】

返回值

描述

0

成功。

非0

参见错误码。

【需求】

  • 头文件：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);

【参数】

参数名称

描述

输入/输出

scheme

RSA填充方式。

输入

sha_type

RSA使用的摘要算法。

输入

rsa_key

密钥结构体。

输入

rsa_data

RSA签名输入的数据。

输入

sign_data

RSA签名后的数据。

输入/输出

【返回值】

返回值

描述

0

成功。

非0

参见错误码。

【需求】

  • 头文件：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);

【参数】

参数名称

描述

输入/输出

scheme

RSA填充方式。

输入

sha_type

RSA使用的摘要算法。

输入

rsa_key

密钥结构体。

输入

rsa_data

RSA签名输入的数据。

输入

sign_data

RSA签名后的数据。

输入

【返回值】

返回值

描述

0

成功。

非0

参见错误码。

【需求】

  • 头文件：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);

【参数】

参数名称

描述

输入/输出

sm2_key

SM2公钥结构体。

输入

plain_txt

明文文本。

输入

cipher_txt

密文文本。

输入/输出

【返回值】

返回值

描述

0

成功。

非0

参见错误码。

【需求】

  • 头文件：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);

【参数】

参数名称

描述

输入/输出

sm2_key

SM2私钥结构体。

输入

cipher_txt

密文文本。

输入

plain_txt

明文文本。

输入/输出

【返回值】

返回值

描述

0

成功。

非0

参见错误码。

【需求】

  • 头文件：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);

【参数】

参数名称

描述

输入/输出

sm2_sign

SM2签名结构体。

输入

sm2_data

SM2签名输入的数据。

输入

sign_data

SM2签名后的数据。

输入/输出

【返回值】

返回值

描述

0

成功。

非0

参见错误码。

【需求】

  • 头文件：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);

【参数】

参数名称

描述

输入/输出

sm2_verify

SM2验签结构体。

输入

sm2_data

SM2签名输入的数据。

输入

sign_data

SM2签名后的数据。

输入

【返回值】

返回值

描述

0

成功。

非0

参见错误码。

【需求】

  • 头文件：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);

【参数】

参数名称

描述

输入/输出

attr

keyslot属性结构体指针。

输入

keyslot

keyslot句柄指针。

输出

【返回值】

返回值

描述

0

成功。

非0

参见错误码。

【需求】

  • 头文件：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);

【参数】

参数名称

描述

输入/输出

keyslot

keyslot句柄。

输入

【返回值】

返回值

描述

0

成功。

非0

参见错误码。

【需求】

  • 头文件：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);

【参数】

参数名称

描述

输入/输出

cipher

cipher 句柄

输入

keyslot

keyslot句柄。

输入

【返回值】

返回值

描述

0

成功。

非0

参见错误码。

【需求】

  • 头文件：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);

【参数】

参数名称

描述

输入/输出

cipher

cipher 句柄

输入

keyslot

keyslot句柄。

输入

【返回值】

返回值

描述

0

成功。

非0

参见错误码。

【需求】

  • 头文件：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;

【成员】

成员名称

描述

OT_CIPHER_WORK_MODE_ECB

ECB（Electronic CodeBook）模式。

OT_CIPHER_WORK_MODE_CBC

CBC（Cipher Block Chaining）模式。

OT_CIPHER_WORK_MODE_CFB

CFB（Cipher FeedBack）模式。

OT_CIPHER_WORK_MODE_OFB

OFB（Output FeedBack）模式。

OT_CIPHER_WORK_MODE_CTR

CTR（Counter）模式。

OT_CIPHER_WORK_MODE_CCM

CCM（Counter with Cipher Block Chaining-Message Authentication）模式。

OT_CIPHER_WORK_MODE_GCM

GCM（Galois/Counter Mode）模式。

OT_CIPHER_WORK_MODE_BUTT

边界值，做边界检查使用，无效模式。

【注意事项】

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;

【成员】

成员名称

描述

OT_CIPHER_ALG_AES

AES算法。

OT_CIPHER_ALG_SM1

SM1算法。

OT_CIPHER_ALG_SM4

SM4算法。

OT_CIPHER_ALG_DMA

DMA直接拷贝，不做加解密运算。

OT_CIPHER_ALG_BUTT

边界值，做边界检查使用，无效算法。

【注意事项】

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;

【成员】

成员名称

描述

OT_CIPHER_KEY_DEFAULT

默认key长度，AES：16 byte，SM1：48 byte，SM4：16 byte

OT_CIPHER_KEY_AES_128BIT

AES运算方式下采用128bit密钥长度。

OT_CIPHER_KEY_AES_192BIT

AES运算方式下采用192bit密钥长度。

OT_CIPHER_KEY_AES_256BIT

AES运算方式下采用256bit密钥长度。

OT_CIPHER_KEY_LEN_BUTT

边界值，做边界检查使用，无效Key长度。

【注意事项】

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_BIT_WIDTH_1BIT

1bit位宽。

OT_CIPHER_BIT_WIDTH_8BIT

8bit位宽。

OT_CIPHER_BIT_WIDTH_64BIT

64bit位宽。

OT_CIPHER_BIT_WIDTH_128BIT

128bit位宽。

OT_CIPHER_BIT_WIDTH_BUTT

边界值，做边界检查使用，无效位宽。

【注意事项】

无。

【相关数据类型及接口】

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_IV_CHG_NONE

更新密钥，不更新向量

OT_CIPHER_IV_CHG_ONE_PACK

为第一个数据包更新向量和密钥

OT_CIPHER_IV_CHG_ALL_PACK

为所有数据包更新向量和密钥

OT_CIPHER_IV_CHG_BUTT

边界值，做边界检查使用，无效。

【注意事项】

无。

【相关数据类型及接口】

ot_cipher_type

【说明】

定义CIPHER加解密类型选择。

【定义】

/* Encryption/Decryption type selecting */
typedef enum {
    OT_CIPHER_TYPE_NORMAL       = 0x0,
    OT_CIPHER_TYPE_BUTT,
} ot_cipher_type;

【成员】

成员名称

描述

OT_CIPHER_TYPE_NORMAL

1-15通道DMA方式。

OT_CIPHER_TYPE_BUTT

边界值，做边界检查使用，无效通道类型。

【注意事项】

无。

【相关数据类型及接口】

ot_cipher_attr

【说明】

定义CIPHER加解密属性结构体。

【定义】

/* Structure of the cipher type */
typedef struct {
    ot_cipher_type cipher_type;
} ot_cipher_attr;

【成员】

成员名称

描述

cipher_type

加密类型结构体变量。

【注意事项】

无。

【相关数据类型及接口】

ss_mpi_cipher_create

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;

【成员】

成员名称

描述

iv[OT_CIPHER_MAX_IV_SIZE_IN_WORD]

向量

bit_width

加密位宽

key_len

加密Key长度

chg_flags

向量变更标志

【注意事项】

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;

【成员】

成员名称

描述

iv[OT_CIPHER_MAX_IV_SIZE_IN_WORD]

向量IV

key_len

加密Key长度

iv_len

向量IV长度

tag_len

TAG长度

aad_len

关联数据A的长度

aad_phys_addr

关联数据A的物理地址

aad_addr

保留参数，后续用于关联数据A的地址类型拓展。

【注意事项】

  • 对于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;

【成员】

成员名称

描述

iv[OT_CIPHER_MAX_IV_SIZE_IN_WORD]

向量

chg_flags

向量变更标志

【注意事项】

  • 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

对称加解密算法

work_mode

对称算法工作模式

aes_ctrl

AES ECB/CBC/CFB/OFB/CTR控制信息

aes_ccm_gcm_ctrl

AES CCM/GCM 控制信息

sm4_ctrl

SM4 ECB/CBC/CFB/OFB/CTR控制信息

【注意事项】

  • 当算法 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;

【成员】

成员名称

描述

src_phys_addr

源数据物理地址。

dst_phys_addr

目的数据物理地址。

byte_len

加解密数据长度。

【注意事项】

无。

【相关数据类型及接口】

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;

【成员】

成员名称

描述

OT_CIPHER_HASH_TYPE_SHA1

SHA1哈希算法。

OT_CIPHER_HASH_TYPE_SHA224

SHA224哈希算法。

OT_CIPHER_HASH_TYPE_SHA256

SHA256哈希算法。

OT_CIPHER_HASH_TYPE_SHA384

SHA384哈希算法。

OT_CIPHER_HASH_TYPE_SHA512

SHA512哈希算法。

OT_CIPHER_HASH_TYPE_SM3

SM3 杂凑算法

OT_CIPHER_HASH_TYPE_HMAC_SHA1

HMAC_SHA1哈希算法。

OT_CIPHER_HASH_TYPE_HMAC_SHA224

HMAC_SHA224哈希算法。

OT_CIPHER_HASH_TYPE_HMAC_SHA256

HMAC_SHA256哈希算法。

OT_CIPHER_HASH_TYPE_HMAC_SHA384

HMAC_SHA384哈希算法。

OT_CIPHER_HASH_TYPE_HMAC_SHA512

HMAC_SHA512哈希算法。

OT_CIPHER_HASH_TYPE_HMAC_SM3

HMAC_SM3杂凑算法。

OT_CIPHER_HASH_TYPE_BUTT

边界值，做边界检查使用，无效算法。

【注意事项】

  • 不支持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;

【成员】

成员名称

描述

hmac_key

HMAC 密钥。

hmac_key_len

HMAC 密钥长度。

sha_type

选择哈希算法类型。

【注意事项】

无。

【相关数据类型及接口】

ss_mpi_cipher_hash_init

ot_cipher_common_data

【说明】

定义通用输入输出数据格式结构体。

【定义】

typedef struct {
    td_u8 *data;
    td_u32 data_len;
} ot_cipher_common_data;

【成员】

成员名称

描述

data

输入输出的数据。

data_len

输入输出的数据长度（单位：byte）。

【注意事项】

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;

【成员】

成员名称

描述

OT_CIPHER_RSA_SCHEME_PKCS1_V15

填充算法 PKCS#1 V15。

OT_CIPHER_RSA_SCHEME_PKCS1_V21

填充算法 PKCS#1 V21，对于签名是 PSS算法，对于加解密时 OAEP 算法。

OT_CIPHER_RSA_SCHEME_BUTT

边界值，做边界检查使用，无效填充方式。

【注意事项】

建议使用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

指向RSA公钥N的指针

e

指向RSA公钥E的指针

n_len

RSA公钥N的长度

e_len

RSA公钥E的长度

【注意事项】

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

指向RSA私钥n的指针

e

指向RSA私钥e的指针

d

指向RSA私钥d的指针

p

指向RSA私钥p的指针

q

指向RSA私钥q的指针

dp

指向RSA私钥dp的指针

dq

指向RSA私钥dq的指针

qp

指向RSA私钥qp的指针

n_len

RSA私钥n的长度

e_len

RSA私钥e的长度

d_len

RSA私钥d的长度

p_len

RSA私钥p的长度，长度为n_len一半

q_len

RSA私钥q的长度，长度为n_len一半

dp_len

RSA私钥dp的长度，长度为n_len一半

dq_len

RSA私钥dq的长度，长度为n_len一半

qp_len

RSA私钥qp的长度，长度为n_len一半

【注意事项】

  • 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;

【成员】

成员名称

描述

OT_CIPHER_SIGN_TYPE_MSG

签名的原数据

OT_CIPHER_SIGN_TYPE_HASH

签名的原数据经过摘要算法预处理后的数据

OT_CIPHER_SIGN_TYPE_BUTT

边界值，做边界检查使用，无效签名类型。

【注意事项】

  • 对于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;

【成员】

成员名称

描述

sign_type

签名验签数据类型。

input

签名验签输入的数据。

input_len

签名验签输入的数据长度（单位：byte）。

【注意事项】

无。

【相关数据类型及接口】

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;

【成员】

成员名称

描述

px

公钥点p的x轴坐标

py

公钥点p的y轴坐标

【注意事项】

SS928V100、SS626V100不支持SM2。

【相关数据类型及接口】

ss_mpi_cipher_sm2_encrypt

ot_cipher_sm2_private_key

【说明】

定义SM2私钥结构体。

【定义】

typedef struct {
    td_u32 d[OT_CIPHER_SM2_LEN_IN_WORD];
} ot_cipher_sm2_private_key;

【成员】

成员名称

描述

d

私钥d的数值

【注意事项】

SS928V100、SS626V100不支持SM2。

【相关数据类型及接口】

ss_mpi_cipher_sm2_decrypt

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;

【成员】

成员名称

描述

d

SM2私钥d的数值

px

SM2公钥点p的x轴坐标

py

SM2公钥点p的y轴坐标

id

SM2签名的身份ID

id_len

SM2签名的身份ID长度

【注意事项】

SS928V100、SS626V100不支持SM2。

【相关数据类型及接口】

ss_mpi_cipher_sm2_sign

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;

【成员】

成员名称

描述

px

SM2公钥点p的x轴坐标

py

SM2公钥点p的y轴坐标

id

SM2验签的身份ID

id_len

SM2验签的身份ID长度

【注意事项】

SS928V100、SS626V100不支持SM2。

【相关数据类型及接口】

ss_mpi_cipher_sm2_verify

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;

【成员】

成员名称

描述

r

SM2签名的数据值r

s

SM2签名的数据值s

【注意事项】

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_TYPE_MCIPHER

keyslot 用于 mcipher。

OT_KEYSLOT_TYPE_BUTT

边界值，做边界检查使用，无效类型。

【注意事项】

无。

【相关数据类型及接口】

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;

【成员】

成员名称

描述

OT_KEYSLOT_SECURE_MODE_NONE

keyslot与非安全CPU绑定。

OT_KEYSLOT_SECURE_MODE_TEE

keyslot与安全CPU绑定。

OT_KEYSLOT_SECURE_MODE_BUTT

边界值，做边界检查使用，无效安全模式。

【注意事项】

非安全CPU不能绑定TEE安全模式，安全CPU可绑定非安模式。

【相关数据类型及接口】

ot_keyslot_attr

【说明】

keyslot属性结构体。

【定义】

typedef struct {
    ot_keyslot_type type;
    ot_keyslot_secure_mode secure_mode;
} ot_keyslot_attr;

【成员】

成员名称

描述

type

keyslot类型。

secure_mode

keyslot安全模式。

【注意事项】

无。

【相关数据类型及接口】

ss_mpi_keyslot_create

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模块的错误码

错误代码

宏定义

描述

0x804d0001

OT_ERR_CIPHER_NOT_INIT

设备未初始化

0x804d0002

OT_ERR_CIPHER_INVALID_HANDLE

Handle号无效

0x804d0003

OT_ERR_CIPHER_INVALID_POINT

参数中有空指针

0x804d0004

OT_ERR_CIPHER_INVALID_PARAM

无效参数

0x804d0005

OT_ERR_CIPHER_FAILED_INIT

初始化失败

0x804d0006

OT_ERR_CIPHER_FAILED_GETHANDLE

获取handle失败

0x804d0007

OT_ERR_CIPHER_FAILED_RELEASEHANDLE

释放handle失败

0x804d0008

OT_ERR_CIPHER_FAILED_CFG_AES

AES配置无效

0x804d0009

OT_ERR_CIPHER_FAILED_CFG_DES

DES配置无效

0x804d000a

OT_ERR_CIPHER_FAILED_ENCRYPT

加密失败

0x804d000b

OT_ERR_CIPHER_FAILED_DECRYPT

解密失败

0x804d000c

OT_ERR_CIPHER_BUSY

忙状态

0x804d000d

OT_ERR_CIPHER_NO_AVAILABLE_RNG

没有可用的随机数

0x804d000e

OT_ERR_CIPHER_FAILED_MEM

内存申请错误

0x804d000f

OT_ERR_CIPHER_UNAVAILABLE

不可用

0x804d0010

OT_ERR_CIPHER_OVERFLOW

数据溢出

0x804d0011

OT_ERR_CIPHER_HARD_STATUS

硬件状态错误

0x804d0012

OT_ERR_CIPHER_TIMEOUT

等待超时

0x804d0013

OT_ERR_CIPHER_UNSUPPORTED

不支持的配置

0x804d0014

OT_ERR_CIPHER_REGISTER_IRQ

中断号无效

0x804d0015

OT_ERR_CIPHER_ILLEGAL_UUID

非法UUID

0x804d0016

OT_ERR_CIPHER_ILLEGAL_KEY

非法key

0x804d0017

OT_ERR_CIPHER_INVALID_ADDR

无效地址

0x804d0018

OT_ERR_CIPHER_INVALID_LEN

无效长度

0x804d0019

OT_ERR_CIPHER_ILLEGAL_DATA

无效数据

0x804d001a

OT_ERR_CIPHER_RSA_SIGN

RSA签名失败

0x804d001b

OT_ERR_CIPHER_RSA_VERIFY

RSA校验失败

0x804d001c

OT_ERR_CIPHER_FAILED_SEC_FUNC

调用安全函数失败

-1

TD_FAILURE

操作失败

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各个通道的配置信息。

【参数说明】

参数

描述

CIPHER基本属性

chn_id

通道号

status

打开/关闭

decrypt

加密/解密

alg

算法，AES等

mode

模式，ECB/CBC/CFB/CTR等

key_len

密钥长度，128/192/256等

addr in/out

输入/输出物理地址

key_from

密钥来源，KEYSLOT编号

int_raw

是否有原始中断

int_en

是否中断使能

int_status

中断状态

iv_out

输出IV