3. API Reference

CIPHER provides the following API：

• CVI_UNF_CIPHER_Init ：initialize CIPHER module.

• CVI_UNF_CIPHER_Deinit ：de-initialize CIPHER module.

• CVI_UNF_CIPHER_Open ：open CIPHER module.

• CVI_UNF_CIPHER_Close ：close CIPHER module.

• CVI_UNF_CIPHER_CreateHandle ：create CIPHER handle.

• CVI_UNF_CIPHER_DestroyHandle ：destroy existing CIPHER handle.

• CVI_UNF_CIPHER_ConfigHandle：configure CIPHER control information.

• CVI_UNF_CIPHER_ConfigHandleEx ：configure CIPHER control information (extended).

• CVI_UNF_CIPHER_GetHandleConfig ：get CIPHER configuration information.

• CVI_UNF_CIPHER_Encrypt ：single packet data encryption function.

• CVI_UNF_CIPHER_Decrypt ：single packet data decryption function.

• CVI_UNF_CIPHER_EncryptVir ：encrypt the data.

• CVI_UNF_CIPHER_DecryptVir ：decrypt the data.

• CVI_UNF_CIPHER_EncryptMulti ：multi packet data encryption function.

• CVI_UNF_CIPHER_DecryptMulti ：multi packet data decryption function.

• CVI_UNF_CIPHER_HashInit ：HASH, HMAC calculate initialization function.

• CVI_UNF_CIPHER_HashUpdate ：HASH, HMAC calculate data input function.

• CVI_UNF_CIPHER_HashFinal ：HASH, HMAC calculate the final result output function.

• CVI_UNF_CIPHER_GetRandomNumber ：get random number function.

• CVI_UNF_CIPHER_GetTag ：get TAG value.

• CVI_UNF_CIPHER_RsaPublicEncrypt ：use public key to encrypt the plaintext.

• CVI_UNF_CIPHER_RsaPrivateDecrypt ：use private key decrypt the ciphertext.

• CVI_UNF_CIPHER_RsaPublicDecrypt ：use public key decrypt the ciphertext.

• CVI_UNF_CIPHER_RsaSign ：use private key to sign the user data.

• CVI_UNF_CIPHER_RsaVerify ：use public key to verify the validity and integrity of user data.

• CVI_UNF_CIPHER_KladEncryptKey ：use KLAD to encrypt the transparent key.

3.1. CVI_UNF_CIPHER_Init

【Description】

Initialize CIPHER module.

【Syntax】

CVI_S32 CVI_UNF_CIPHER_Init(void);

【Parameter】

None.

【Return Value】

Return Value	Description
0	Success
Not 0	Refer to Error Codes.

3.2. CVI_UNF_CIPHER_Deinit

【Description】

De-initialize CIPHER module.

【Syntax】

CVI_S32 CVI_UNF_CIPHER_DeInit(void);

【Parameter】

None.

【Return Value】

Return Value	Description
0	Success
Not 0	Refer to Error Codes.

3.3. CVI_UNF_CIPHER_Open

【Description】

Open CIPHER module.

【Syntax】

#define CVI_UNF_CIPHER_Open(CVI_VOID)

CVI_UNF_CIPHER_Init(CVI_VOID);

【Parameter】

None.

【Return Value】

Return Value	Description
0	Success
Not 0	Refer to Error Codes.

3.4. CVI_UNF_CIPHER_Close

【Description】

Close CIPHER module.

【Syntax】

#define CVI_UNF_CIPHER_Close(CVI_VOID)

CVI_UNF_CIPHER_DeInit(CVI_VOID);

【Parameter】

None.

【Return Value】

Return Value	Description
0	Success
Not 0	Refer to Error Codes.

3.5. CVI_UNF_CIPHER_CreateHandle

【Description】

Create single-way Cipher handle.

【Syntax】

CVI_S32 CVI_UNF_CIPHER_CreateHandle(CVI_HANDLE * phCipher, const CVI_UNF_CIPHER_ATTS_S * pstCipherAttr);

【Parameter】

Parameter	Description	Input/Output
phCipher	CIPHER handle pointer	Output
pstCipherAtt	CIPHER property pointer	Input

【Return Value】

Return Value	Description
0	Success
Not 0	Refer to Error Codes.

3.6. CVI_UNF_CIPHER_DestroyHandle

【Description】

Destroy single-way CIPHER.

【Syntax】

CVI_S32 CVI_UNF_CIPHER_DestroyHandle(CVI_HANDLE hCipher);

【Parameter】

Parameter	Description	Input/Output
hCipher	CIPHER handle	Input

【Return Value】

Return Value	Description
0	Success
Not 0	Refer to Error Codes.

3.7. CVI_UNF_CIPHER_ConfigHandle

【Description】

Configure CIPHER control information. Please refer to structure CVI_UNF_CIPHER_CTRL_S.

【Syntax】

CVI_S32 CVI_UNF_CIPHER_ConfigHandle(CVI_HANDLE hCipher, CVI_UNF_CIPHER_CTRL_S* pstCtrl);

【Parameter】

Parameter	Description	Input/Output
hCipher	CIPHER handle	Input
pstCtrl	Control information pointer	Input

【Return Value】

Return Value	Description
0	Success
Not 0	Refer to Error Codes.

3.8. CVI_UNF_CIPHER_ConfigHandleEx

【Description】

Configure CIPHER control information. Please refer to structure CVI_UNF_CIPHER_CTRL_EX_S.

【Syntax】

CVI_S32 CVI_UNF_CIPHER_ConfigHandleEx(CVI_HANDLE hCipher, CVI_UNF_CIPHER_CTRL_EX_S* pstExCtrl);

【Parameter】

Parameter	Description	Input/Output
hCipher	CIPHER handle	Input
pstExCtrl	Control extended information pointer	Input

【Return Value】

Return Value	Description
0	Success
Not 0	Refer to Error Codes.

3.9. CVI_UNF_CIPHER_GetHandleConfig

【Description】

Get channel CIPHER corresponding configuration information.

【Syntax】

CVI_S32 CVI_UNF_CIPHER_GetHandleConfig(CVI_HANDLE hCipher, CVI_UNF_CIPHER_CTRL_S* pstCtrl);

【Parameter】

Parameter	Description	Input/Output
hCipher	CIPHER handle	Input
pstCtrl	CIPHER channel configuration information	Output

【Return Value】

Return Value	Description
0	Success
Not 0	Refer to Error Codes.

3.10. CVI_UNF_CIPHER_Encrypt

【Description】

Encrypt the data.

【Syntax】

CVI_S32 CVI_UNF_CIPHER_Encrypt(CVI_HANDLE hCipher, CVI_U32 u32SrcPhyAddr, CVI_U32 u32DestPhyAddr, CVI_U32 u32ByteLength);

【Parameter】

Parameter	Description	Input/Output
hCipher	CIPHER handle	Input
u32SrcPhyAddr	The physical address of the source data (the data to be encrypted)	Input
u32DestPhyAddr	The physical address where the encryption results are stored	Input
u32ByteLength	The length of the data (in bytes)	Input

【Return Value】

Return Value	Description
0	Success
Not 0	Refer to Error Codes.

3.11. CVI_UNF_CIPHER_Decrypt

【Description】

Decrypt the data.

【Syntax】

CVI_S32 CVI_UNF_CIPHER_Decrypt(CVI_HANDLE hCipher, CVI_U32 u32SrcPhyAddr, CVI_U32 u32DestPhyAddr, CVI_U32 u32ByteLength);

【Parameter】

Parameter	Description	Input/Output
hCipher	CIPHER handle	Input
u32SrcPhyAddr	The physical address of the source data (the data to be decrypted)	Input
u32DestPhyAddr	The physical address where the decryption results are stored	Input
u32ByteLength	The length of the data (in bytes)	Input

【Return Value】

Return Value	Description
0	Success
Not 0	Refer to Error Codes.

3.12. CVI_UNF_CIPHER_EncryptVir

【Description】

Encrypt the data.

【Syntax】

CVI_S32 CVI_UNF_CIPHER_EncryptVir(CVI_HANDLE hCipher, const CVI_U8 * pu8SrcData, CVI_U8 * pu8DestData, CVI_U32 u32ByteLength);

【Parameter】

Parameter	Description	Input/Output
hCipher	CIPHER handle	Input
*pu8SrcData	The virtual address of the source data (the data to be encrypted)	Input
*pu8DestData	The virtual address where the encryption results are stored	Output
u32ByteLength	The length of the data (in bytes)	Input

【Return Value】

Return Value	Description
0	Success
Not 0	Refer to Error Codes.

3.13. CVI_UNF_CIPHER_DecryptVir

【Description】

Decrypt the data.

【Syntax】

CVI_S32 CVI_UNF_CIPHER_DecryptVir(CVI_HANDLE hCipher, const CVI_U8 * pu8SrcData, CVI_U8 * pu8DestData, CVI_U32 u32ByteLength);

【Parameter】

Parameter	Description	Input/Output
hCipher	CIPHER handle	Input
*pu8SrcData	The virtual address of the source data (the data to be decrypted)	Input
*pu8DestData	The virtual address where the decryption results are stored	Output
u32ByteLength	The length of the data (in bytes)	Input

【Return Value】

Return Value	Description
0	Success
Not 0	Refer to Error Codes.

3.14. CVI_UNF_CIPHER_EncryptMulti

【Description】

Encrypt multiple packet data.

【Syntax】

CVI_S32 CVI_UNF_CIPHER_EncryptMulti(CVI_HANDLE hCipher, CVI_UNF_CIPHER_DATA_S * pstDataPkg, CVI_U32 u32DataPkgNum);

【Parameter】

Parameter	Description	Input/Output
hCipher	CIPHER handle	Input
*pstDataPkg	Packets to be encrypted	Input
u32DataPkgNum	The number of packets to be encrypted	Input

【Return Value】

Return Value	Description
0	Success
Not 0	Refer to Error Codes.

3.15. CVI_UNF_CIPHER_DecryptMulti

【Description】

Decrypt multiple packet data.

【Syntax】

CVI_S32 CVI_UNF_CIPHER_DecryptMulti(CVI_HANDLE hCipher, CVI_UNF_CIPHER_DATA_S * pstDataPkg, CVI_U32 u32DataPkgNum);

【Parameter】

Parameter	Description	Input/Output
hCipher	CIPHER handle	Input
*pstDataPkg	Packets to be decrypted	Input
u32DataPkgNum	The number of packets to be decrypted	Input

【Return Value】

Return Value	Description
0	Success
Not 0	Refer to Error Codes.

3.16. CVI_UNF_CIPHER_HashInit

【Description】

Initialize HASH module.

【Syntax】

CVI_S32 CVI_UNF_CIPHER_HashInit(CVI_UNF_CIPHER_HASH_ATTS_S * pstHashAttr, CVI_HANDLE * pHashHandle);

【Parameter】

Parameter	Description	Input/Output
pstHashAttr	Structure parameters for hash calculation	Input
pHashHandle	The hash handle of the output	Output

【Return Value】

Return Value	Description
0	Success
Not 0	Refer to Error Codes.

3.17. CVI_UNF_CIPHER_HashUpdate

【Description】

Calculate hash value.

【Syntax】

CVI_S32 CVI_UNF_CIPHER_HashUpdate(CVI_HANDLE hHashHandle, CVI_U8 * pu8InputData, CVI_U32 u32InputDataLen);

【Parameter】

Parameter	Description	Input/Output
hHashHandl	Hash handle	Input
pu8InputData	Input data buffer	Input
u32InputDataLen	The length of the input data (in bytes)	Input

【Return Value】

Return Value	Description
0	Success
Not 0	Refer to Error Codes.

3.18. CVI_UNF_CIPHER_HashFinal

【Description】

Get hash value.

【Syntax】

CVI_S32 CVI_UNF_CIPHER_HashFinal(CVI_HANDLE hHashHandle, CVI_U8 * pu8OutputHash);

【Parameter】

Parameter	Description	Input/Output
hHashHandl	Hash handle	Input
pu8OutputHash	Output的 hash	Output

【Return Value】

Return Value	Description
0	Success
Not 0	Refer to Error Codes.

3.19. CVI_UNF_CIPHER_GetRandomNumber

【Description】

Generate random numbers.

【Syntax】

CVI_S32 CVI_UNF_CIPHER_GetRandomNumber(CVI_U32 * pu32RandomNumber);

【Parameter】

Parameter	Description	Input/Output
pu32RandomNumber	Random number of output	Output

【Return Value】

Return Value	Description
0	Success
Not 0	Refer to Error Codes.

3.20. CVI_UNF_CIPHER_GetTag

【Description】

The TAG value is obtained after encryption and decryption in CCM / GCM mode.

【Syntax】

CVI_S32 CVI_UNF_CIPHER_GetTag(CVI_HANDLE hCipher, CVI_U8 * pstTag);

【Parameter】

Parameter	Description	Input/Output
hCipher	CIPHER handle	Input
pstTag	TAG value	Output

【Return Value】

Return Value	Description
0	Success
Not 0	Refer to Error Codes.

3.21. CVI_UNF_CIPHER_RsaPublicEncrypt

【Description】

Use RSA public key to encrypt a piece of plaintext.

【Syntax】

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

【Parameter】

Parameter	Description	Input/Output
pstRsaEnc	Public key encryption attribute structure	Input
pu8Input	Data to be encrypted	Input
u32InLen	The length of the data to be encrypted (in bytes)	Input
pu8Output	Encrypted results data	Output
pu32OutLen	The length of the encrypted results data (in bytes)	Output

【Return Value】

Return Value	Description
0	Success
Not 0	Refer to Error Codes.

3.22. CVI_UNF_CIPHER_RsaPrivateDecrypt

【Description】

Use RSA private key to decrypt a ciphertext.

【Syntax】

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

【Parameter】

Parameter	Description	Input/Output
pstRsaEnc	Private key encryption attribute structure	Input
pu8Input	Data to be encrypted	Input
u32InLen	The length of the data to be encrypted (in bytes)	Input
pu8Output	Encrypted results data	Output
pu32OutLen	The length of the encrypted results data (in bytes)	Output

【Return Value】

Return Value	Description
0	Success
Not 0	Refer to Error Codes.

3.23. CVI_UNF_CIPHER_RsaPublicDecrypt

【Description】

Use RSA public key to decrypt a ciphertext.

【Syntax】

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

【Parameter】

Parameter	Description	Input/Output
pstRsaDec	Public key decryption attribute structure	Input
pu8Input	Data to be decrypted	Input
u32InLen	The length of the data to be decrypted (in bytes)	Input
pu8Output	Decrypted results data	Output
pu32OutLen	The length of the decrypted results data (in bytes)	Output

【Return Value】

Return Value	Description
0	Success
Not 0	Refer to Error Codes.

3.24. CVI_UNF_CIPHER_RsaSign

【Description】

Sign a piece of text with RSA private key.

【Syntax】

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

【Parameter】

Parameter	Description	Input/Output
pstRsaSign	Signature attribute structure	Input
pu8InData	The data to be signed, if pu8HashData is not empty, pu8HashData will be used for signing and this parameter will be ignored	Input
u32InDataLen	The length of the data to be signed (in bytes)	Input
pu8HashData	HASH digest of the text to be signed, if it is empty, the HASH digest of pu8InData is automatically calculated for signing	Input
pu8OutSign	Signature results data	Output
pu32OutSignLen	The length of the signature results data (in bytes)	Output

【Return Value】

Return Value	Description
0	Success
Not 0	Refer to Error Codes.

3.25. CVI_UNF_CIPHER_RsaVerify

【Description】

Use RSA public key signature to verify a piece of text.

【Syntax】

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

【Parameter】

Parameter	Description	Input/Output
pstRsaVerify	Signature verification attribute structure	Input
pu8InData	Data to be validated, if pu8HashData is not empty, then use pu8HashData for validation, this parameter will be ignored	Input
u32InDataLen	The length of the data to be verified (in bytes)	Input
pu8HashData	HASH digest of the text to be validated, if empty, the HASH digest of pu8InData is automatically calculated for validation	Input
pu8InSign	Signature data to be verified	Input
u32InSignLen	The length of the signature data to be verified (in bytes)	Input

【Return Value】

Return Value	Description
0	Success
Not 0	Refer to Error Codes.

3.26. CVI_UNF_CIPHER_KladEncryptKey

【Description】

Use KLAD to encrypt transparent keys.

【Syntax】

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

【Parameter】

Parameter	Description	Input/Output
enRootKey	KLAD root key selection, only EFUSE Key can be selected	Input
enTarget	Modules using this key	Input
pu8CleanKey	Transparent Key	Input
pu8EcnryptKey	Encryption Key	Output
u32KeyLen	The length of the key, which must be an integer multiple of 16	Input

【Return Value】

Return Value	Description
0	Success
Not 0	Refer to Error Codes.