3. API参考¶
CIPHER 提供以下 API:
CVI_UNF_CIPHER_Init :初始化 CIPHER 模块。
CVI_UNF_CIPHER_Deinit :去初始化 CIPHER 模块。
CVI_UNF_CIPHER_Open :打开 CIPHER 模块。
CVI_UNF_CIPHER_Close :关闭 CIPHER 模块。
CVI_UNF_CIPHER_CreateHandle :创建 Cipher 句柄。
CVI_UNF_CIPHER_DestroyHandle :销毁已存在的 CIPHER 句柄。
CVI_UNF_CIPHER_ConfigHandle :配置 CIPHER 控制信息。
CVI_UNF_CIPHER_ConfigHandleEx :配置 CIPHER 控制信息（扩展）。
CVI_UNF_CIPHER_GetHandleConfig :获取 CIPHER配置信息。
CVI_UNF_CIPHER_Encrypt :单包数据加密功能。
CVI_UNF_CIPHER_Decrypt :单包数据解密功能。
CVI_UNF_CIPHER_EncryptVir :对数据进行加密。
CVI_UNF_CIPHER_DecryptVir :对数据进行解密。
CVI_UNF_CIPHER_EncryptMulti :多包数据加密功能。
CVI_UNF_CIPHER_DecryptMulti :多包数据解密功能。
CVI_UNF_CIPHER_HashInit :HASH、HMAC 计算初始化功能。
CVI_UNF_CIPHER_HashUpdate :HASH、HMAC 计算数据输入功能。
CVI_UNF_CIPHER_HashFinal :HASH、HMAC 计算最终结果输出功能。
CVI_UNF_CIPHER_GetRandomNumber :获取随机数功能。
CVI_UNF_CIPHER_GetTag :获取 TAG 值。
CVI_UNF_CIPHER_RsaPublicEncrypt :使用公钥对明文进行加密。
CVI_UNF_CIPHER_RsaPrivateDecrypt :使用私钥对密文进行解密。
CVI_UNF_CIPHER_RsaPublicDecrypt :使用公钥对密文进行解密。
CVI_UNF_CIPHER_RsaSign :使用私钥对用户数据进行签名。
CVI_UNF_CIPHER_RsaVerify :使用公钥对用户数据进行合法性及完整性验证。
CVI_UNF_CIPHER_KladEncryptKey :使用 KLAD 对透明密钥进行加密。
3.1. CVI_UNF_CIPHER_Init¶
【描述】
初始化 CIPHER 模块。
【语法】
CVI_S32 CVI_UNF_CIPHER_Init(void);
【参数】
无。
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功 |
非0 |
参考 错误码 。 |
3.2. CVI_UNF_CIPHER_Deinit¶
【描述】
去初始化 CIPHER 模块。
【语法】
CVI_S32 CVI_UNF_CIPHER_DeInit(void);
【参数】
无。
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功 |
非0 |
参考 错误码 。 |
3.3. CVI_UNF_CIPHER_Open¶
【描述】
打开 CIPHER 模块。
【语法】
#define CVI_UNF_CIPHER_Open(CVI_VOID)
CVI_UNF_CIPHER_Init(CVI_VOID);
【参数】
无。
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功 |
非0 |
参考 错误码 。 |
3.4. CVI_UNF_CIPHER_Close¶
【描述】
关闭 CIPHER 模块。
【语法】
#define CVI_UNF_CIPHER_Close(CVI_VOID)
CVI_UNF_CIPHER_DeInit(CVI_VOID);
【参数】
无。
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功 |
非0 |
参考 错误码 。 |
3.5. CVI_UNF_CIPHER_CreateHandle¶
【描述】
创建一路的 Cipher 句柄。
【语法】
CVI_S32 CVI_UNF_CIPHER_CreateHandle(CVI_HANDLE *phCipher, const CVI_UNF_CIPHER_ATTS_S *pstCipherAttr);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
phCipher |
CIPHER 句柄指针 |
输出 |
pstCipherAtt |
CIPHER 属性指针 |
输入 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功 |
非0 |
参考 错误码 。 |
3.6. CVI_UNF_CIPHER_DestroyHandle¶
【描述】
销毁一路 CIPHER。
【语法】
CVI_S32 CVI_UNF_CIPHER_DestroyHandle(CVI_HANDLE hCipher);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
hCipher |
CIPHER 句柄 |
输入 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功 |
非0 |
参考 错误码 。 |
3.7. CVI_UNF_CIPHER_ConfigHandle¶
【描述】
配置 CIPHER 控制信息。详细配置请参见结构体 CVI_UNF_CIPHER_CTRL_S。
【语法】
CVI_S32 CVI_UNF_CIPHER_ConfigHandle(CVI_HANDLE hCipher, CVI_UNF_CIPHER_CTRL_S* pstCtrl);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
hCipher |
CIPHER 句柄 |
输入 |
pstCtrl |
控制信息指针 |
输入 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功 |
非0 |
参考 错误码 。 |
3.8. CVI_UNF_CIPHER_ConfigHandleEx¶
【描述】
配置 CIPHER 控制信息。详细配置请参见结构体 CVI_UNF_CIPHER_CTRL_EX_S。
【语法】
CVI_S32 CVI_UNF_CIPHER_ConfigHandleEx(CVI_HANDLE hCipher, CVI_UNF_CIPHER_CTRL_EX_S* pstExCtrl);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
hCipher |
CIPHER 句柄 |
输入 |
pstExCtrl |
控制扩展信息指针 |
输入 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功 |
非0 |
参考 错误码 。 |
3.9. CVI_UNF_CIPHER_GetHandleConfig¶
【描述】
获取 CIPHER 信道对应的配置信息。
【语法】
CVI_S32 CVI_UNF_CIPHER_GetHandleConfig(CVI_HANDLE hCipher, CVI_UNF_CIPHER_CTRL_S* pstCtrl);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
hCipher |
CIPHER 句柄 |
输入 |
pstCtrl |
CIPHER 信道的配置信息 |
输出 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功 |
非0 |
参考 错误码 。 |
3.10. CVI_UNF_CIPHER_Encrypt¶
【描述】
对数据进行加密。
【语法】
CVI_S32 CVI_UNF_CIPHER_Encrypt(CVI_HANDLE hCipher, CVI_U32 u32SrcPhyAddr, CVI_U32 u32DestPhyAddr, CVI_U32 u32ByteLength);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
hCipher |
CIPHER 句柄 |
输入 |
u32SrcPhyAddr |
源数据（待加密的数据）的物理地址 |
输入 |
u32DestPhyAddr |
存放加密结果的物理地址 |
输入 |
u32ByteLength |
数据的长度（单位:字节） |
输入 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功 |
非0 |
参考 错误码 。 |
3.11. CVI_UNF_CIPHER_Decrypt¶
【描述】
对数据进行解密。
【语法】
CVI_S32 CVI_UNF_CIPHER_Decrypt(CVI_HANDLE hCipher, CVI_U32 u32SrcPhyAddr, CVI_U32 u32DestPhyAddr, CVI_U32 u32ByteLength);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
hCipher |
CIPHER 句柄 |
输入 |
u32SrcPhyAddr |
源数据（待解密的数据）的物理地址 |
输入 |
u32DestPhyAddr |
存放解密结果的物理地址 |
输入 |
u32ByteLength |
数据的长度（单位:字节） |
输入 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功 |
非0 |
参考 错误码 。 |
3.12. CVI_UNF_CIPHER_EncryptVir¶
【描述】
对数据进行加密。
【语法】
CVI_S32 CVI_UNF_CIPHER_EncryptVir(CVI_HANDLE hCipher, const CVI_U8 *pu8SrcData, CVI_U8 *pu8DestData, CVI_U32 u32ByteLength);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
hCipher |
CIPHER 句柄 |
输入 |
*pu8SrcData |
源数据（待加密的数据）的虚拟地址。 |
输入 |
*pu8DestData |
存放加密结果的虚拟地址 |
输出 |
u32ByteLength |
数据的长度（单位:字节） |
输入 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功 |
非0 |
参考 错误码 。 |
3.13. CVI_UNF_CIPHER_DecryptVir¶
【描述】
对数据进行解密。
【语法】
CVI_S32 CVI_UNF_CIPHER_DecryptVir(CVI_HANDLE hCipher, const CVI_U8 *pu8SrcData, CVI_U8 *pu8DestData, CVI_U32 u32ByteLength);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
hCipher |
CIPHER 句柄 |
输入 |
*pu8SrcData |
源数据（待解密的数据）的虚拟地址。 |
输入 |
*pu8DestData |
存放解密结果的虚拟地址 |
输出 |
u32ByteLength |
数据的长度（单位:字节） |
输入 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功 |
非0 |
参考 错误码 。 |
3.14. CVI_UNF_CIPHER_EncryptMulti¶
【描述】
进行多个包数据的加密。
【语法】
CVI_S32 CVI_UNF_CIPHER_EncryptMulti(CVI_HANDLE hCipher, CVI_UNF_CIPHER_DATA_S *pstDataPkg, CVI_U32 u32DataPkgNum);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
hCipher |
CIPHER 句柄 |
输入 |
*pstDataPkg |
待加密的数据包 |
输入 |
u32DataPkgNum |
待加密的数据包个数 |
输入 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功 |
非0 |
参考 错误码 。 |
3.15. CVI_UNF_CIPHER_DecryptMulti¶
【描述】
进行多个包数据的解密。
【语法】
CVI_S32 CVI_UNF_CIPHER_DecryptMulti(CVI_HANDLE hCipher, CVI_UNF_CIPHER_DATA_S *pstDataPkg, CVI_U32 u32DataPkgNum);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
hCipher |
CIPHER 句柄 |
输入 |
*pstDataPkg |
待解密的数据包 |
输入 |
u32DataPkgNum |
待解密的数据包个数 |
输入 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功 |
非0 |
参考 错误码 。 |
3.16. CVI_UNF_CIPHER_HashInit¶
【描述】
初始化 HASH 模块。
【语法】
CVI_S32 CVI_UNF_CIPHER_HashInit(CVI_UNF_CIPHER_HASH_ATTS_S *pstHashAttr, CVI_HANDLE *pHashHandle);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
pstHashAttr |
用于计算 hash 的结构体参数 |
输入 |
pHashHandle |
输出的 hash 句柄 |
输出 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功 |
非0 |
参考 错误码 。 |
3.17. CVI_UNF_CIPHER_HashUpdate¶
【描述】
计算 hash 值。
【语法】
CVI_S32 CVI_UNF_CIPHER_HashUpdate(CVI_HANDLE hHashHandle, CVI_U8 *pu8InputData, CVI_U32 u32InputDataLen);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
hHashHandl |
Hash 句柄 |
输入 |
pu8InputData |
输入数据缓冲 |
输入 |
u32InputDataLen |
输入数据的长度，单位:byte |
输入 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功 |
非0 |
参考 错误码 。 |
3.18. CVI_UNF_CIPHER_HashFinal¶
【描述】
获取 hash 值。
【语法】
CVI_S32 CVI_UNF_CIPHER_HashFinal(CVI_HANDLE hHashHandle, CVI_U8 *pu8OutputHash);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
hHashHandl |
Hash 句柄 |
输入 |
pu8OutputHash |
输出的 hash |
输出 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功 |
非0 |
参考 错误码 。 |
3.19. CVI_UNF_CIPHER_GetRandomNumber¶
【描述】
生成随机数。
【语法】
CVI_S32 CVI_UNF_CIPHER_GetRandomNumber(CVI_U32 *pu32RandomNumber);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
pu32RandomNumber |
输出的随机数 |
输出 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功 |
非0 |
参考 错误码 。 |
3.20. CVI_UNF_CIPHER_GetTag¶
【描述】
CCM/GCM 模式加解密后获取 TAG 值。
【语法】
CVI_S32 CVI_UNF_CIPHER_GetTag(CVI_HANDLE hCipher, CVI_U8 *pstTag);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
hCipher |
CIPHER 句柄 |
输入 |
pstTag |
TAG 值 |
输出 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功 |
非0 |
参考 错误码 。 |
3.21. CVI_UNF_CIPHER_RsaPublicEncrypt¶
【描述】
使用 RSA 公钥加密一段明文。
【语法】
CVI_S32 CVI_UNF_CIPHER_RsaPublicEncrypt(CVI_UNF_CIPHER_RSA_PUB_ENC_S *pstRsaEnc, CVI_U8 *pu8Input, CVI_U32 u32InLen, CVI_U8 *pu8Output, CVI_U32 CIPHER *pu32OutLen);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
pstRsaEnc |
公钥加密属性结构体 |
输入 |
pu8Input |
待加密的数据 |
输入 |
u32InLen |
待加密的数据长度，单位:byte |
输入 |
pu8Output |
加密结果数据 |
输出 |
pu32OutLen |
加密结果数据长度，单位:byte |
输出 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功 |
非0 |
参考 错误码 。 |
3.22. CVI_UNF_CIPHER_RsaPrivateDecrypt¶
【描述】
使用 RSA 私钥解密一段密文。
【语法】
CVI_S32 CVI_UNF_CIPHER_RsaPrivateDecrypt(CVI_UNF_CIPHER_RSA_PRI_ENC_S *pstRsaDec, CVI_U8 *pu8Input, CVI_U32 u32InLen, CVI_U8 *pu8Output, CVI_U32 *pu32OutLen);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
pstRsaEnc |
私钥加密属性结构体 |
输入 |
pu8Input |
待加密的数据 |
输入 |
u32InLen |
待加密的数据长度，单位:byte |
输入 |
pu8Output |
加密结果数据 |
输出 |
pu32OutLen |
加密结果数据长度，单位:byte |
输出 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功 |
非0 |
参考 错误码 。 |
3.23. CVI_UNF_CIPHER_RsaPublicDecrypt¶
【描述】
使用 RSA 公钥解密一段密文。
【语法】
CVI_S32 CVI_UNF_CIPHER_RsaPrivateDecrypt(CVI_UNF_CIPHER_RSA_PUB_ENC_S *pstRsaDec, CVI_U8 *pu8Input, CVI_U32 u32InLen, CVI_U8 *pu8Output, CVI_U32 *pu32OutLen);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
pstRsaDec |
公钥解密属性结构体 |
输入 |
pu8Input |
待解密的数据 |
输入 |
u32InLen |
待解密的数据长度，单位:byte |
输入 |
pu8Output |
解密结果数据 |
输出 |
pu32OutLen |
解密结果数据长度，单位:byte |
输出 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功 |
非0 |
参考 错误码 。 |
3.24. CVI_UNF_CIPHER_RsaSign¶
【描述】
使用 RSA 私钥签名一段文本。
【语法】
CVI_S32 CVI_UNF_CIPHER_RsaSign(CVI_UNF_CIPHER_RSA_SIGN_S *pstRsaSign, CVI_U8 *pu8InData, CVI_U32 u32InDataLen, CVI_U8 *pu8HashData,CVI_U8 *pu8OutSign, CVI_U32 *pu32OutSignLen);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
pstRsaSign |
签名属性结构体 |
输入 |
pu8InData |
待签名的数据, 如果 pu8HashData 不为空，则使用 pu8HashData 进行签名，该参数将被忽略。 |
输入 |
u32InDataLen |
待签名的数据长度，单位:byte |
输入 |
pu8HashData |
待签名文本的 HASH 摘要，如果为空，则自动计算 pu8InData 的 HASH 摘要进行签名 |
输入 |
pu8OutSign |
签名结果数据 |
输出 |
pu32OutSignLen |
签名结果数据长度，单位:byte |
输出 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功 |
非0 |
参考 错误码 。 |
3.25. CVI_UNF_CIPHER_RsaVerify¶
【描述】
使用 RSA 公钥签名验证一段文本。
【语法】
CVI_S32 CVI_UNF_CIPHER_RsaVerify(CVI_UNF_CIPHER_RSA_VERIFY_S *pstRsaVerify,CVI_U8 *pu8InData, CVI_U32 u32InDataLen, CVI_U8 *pu8HashData,CVI_U8 *pu8InSign, CVI_U32 u32InSignLen);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
pstRsaVerify |
签名验证属性结构体 |
输入 |
pu8InData |
待验证的数据, 如果 pu8HashData 不为空，则使用 pu8HashData 进行验证，该参数将被忽略 |
输入 |
u32InDataLen |
待验证的数据长度，单位:byte |
输入 |
pu8HashData |
待验证文本的的 HASH 摘要，如果为空，则自动计算 pu8InData 的 HASH 摘要进行验证 |
输入 |
pu8InSign |
待验证的签名数据 |
输入 |
u32InSignLen |
待验证的签名数据长度，单位:byte |
输入 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功 |
非0 |
参考 错误码 。 |
3.26. CVI_UNF_CIPHER_KladEncryptKey¶
【描述】
使用 KLAD 对透明密钥进行加密。
【语法】
CV_S32 CVI_UNF_CIPHER_KladEncryptKey(CVI_UNF_CIPHER_CA_TYPE_E enRootKey, CVI_UNF_CIPHER_KLAD_TARGET_E enTarget, CVI_U8 *pu8CleanKey, CVI_U8 *pu8EcnryptKey, CVI_U32 u32KeyLen);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
enRootKey |
KLAD 根密钥选择，只能选择 EFUSE Key |
输入 |
enTarget |
使用该密钥的模块 |
输入 |
pu8CleanKey |
透明密钥 |
输入 |
pu8EcnryptKey |
加密密钥 |
输出 |
u32KeyLen |
密钥的长度，必须是 16 整数倍 |
输入 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功 |
非0 |
参考 错误码 。 |