Cipher API#
Cipher is a cryptographic technique used to secure information by transforming message into a cryptic form that can only be read by those with the key to decipher it.
Data Structures#
-
struct alc_cipher_handle_t#
Handle for maintaining session.
- Param alc_cipher_context_p:
pointer to the user allocated context of the cipher
Functions#
-
Uint64 alcp_cipher_context_size(void)#
Gets the size of the context for a session.
This API should be called before alcp_cipher_request to identify the memory to be allocated for context
- Returns:
Size of Context
-
alc_error_t alcp_cipher_request(const alc_cipher_mode_t cipherMode, const Uint64 keyLen, alc_cipher_handle_p pCipherHandle)#
Request for populating handle with algorithm specified by cipher mode and key Length.
This API can be called after alcp_cipher_context_size is called
Note
Error needs to be checked for each call. Valid only if alcp_is_error (ret) is false
- Parameters:
cipherMode – [in] cipher mode to be set
keyLen – [in] key length in bits
pCipherHandle – [out] Library populated session handle for future cipher operations.
- Returns:
Error Code for the API called.
-
alc_error_t alcp_cipher_init(const alc_cipher_handle_p pCipherHandle, const Uint8 *pKey, Uint64 keyLen, const Uint8 *pIv, Uint64 ivLen)#
Cipher init.
This API can be called after alcp_cipher_request is called.
- Parameters:
pCipherHandle – [in] Session handle for cipher operation
pKey – [in] Key
keyLen – [in] key Length in bits
pIv – [in] IV/Nonce
ivLen – [in] iv Length in bits
- Returns:
Error Code for the API called. If alc_error_t is not ALC_ERROR_NONE then an error has occurred and handle will be invalid for future operations
-
alc_error_t alcp_cipher_encrypt(const alc_cipher_handle_p pCipherHandle, const Uint8 *pPlainText, Uint8 *pCipherText, Uint64 datalen)#
Encrypt plain text and write it to cipher text with provided handle.
This API can be called after alcp_cipher_request and before alcp_cipher_finish API is meant to be used with CBC,CTR,CFB,OFB,XTS mode.
Note
Error needs to be checked for each call, valid only if alcp_is_error (ret) is false
- Parameters:
pCipherHandle – [in] Session handle for future encrypt/decrypt operation
pPlainText – [in] Pointer to Plain Text
pCipherText – [out] Pointer to Cipher Text
datalen – [in] Length of cipher/plain text
- Returns:
Error Code for the API called.
-
alc_error_t alcp_cipher_decrypt(const alc_cipher_handle_p pCipherHandle, const Uint8 *pCipherText, Uint8 *pPlainText, Uint64 datalen)#
Decrypt the cipher text and write it to plain text with provided handle.
This API can be called after alcp_cipher_request and before alcp_cipher_finish API is meant to be used with CBC,CTR,CFB,OFB,XTS mode.
Note
Error needs to be checked for each call, valid only if alcp_is_error (ret) is false
- Parameters:
pCipherHandle – [in] Session handle for future encrypt decrypt operation
pPlainText – [in] Pointer to Plain Text
pCipherText – [out] Pointer to Cipher Text
datalen – [in] Length of cipher/plain text
- Returns:
Error Code for the API called.
-
void alcp_cipher_finish(const alc_cipher_handle_p pCipherHandle)#
Release resources allocated by alcp_cipher_request.
This API is called to free the session resources
Note
alcp_cipher_finish has to be called at the end of the transaction. Context will be unusable after this call.
- Parameters:
pCipherHandle – [in] Session handle for future encrypt/decrypt operation
- Returns:
None
-
alc_error_t alcp_cipher_segment_init(const alc_cipher_handle_p pCipherHandle, const Uint8 *pKey, Uint64 keyLen, const Uint8 *pIv, Uint64 ivLen)#
Cipher Segment init.
This API can be called after alcp_cipher_request is called.
- Parameters:
pCipherHandle – [in] Session handle for cipher operation
pKey – [in] Key
keyLen – [in] key Length in bits
pIv – [in] IV/Nonce
ivLen – [in] iv Length in bits
- Returns:
Error Code for the API called. If alc_error_t is not ALC_ERROR_NONE then an error has occurred and handle will be invalid for future operations
-
alc_error_t alcp_cipher_segment_request(const alc_cipher_mode_t cipherMode, const Uint64 keyLen, alc_cipher_handle_p pCipherHandle)#
Request for populating handle with algorithm specified by cipher mode and key Length.
This API can be called after alcp_cipher_context_size is called
Note
Error needs to be checked for each call, valid only if alcp_is_error (ret) is false, ctx to be considered valid.
- Parameters:
cipherMode – [in] cipher mode to be set
keyLen – [in] key length in bits
pCipherHandle – [out] Library populated session handle for future cipher operations.
- Returns:
Error Code for the API called.
-
alc_error_t alcp_cipher_segment_encrypt_xts(const alc_cipher_handle_p pCipherHandle, const Uint8 *pPlainText, Uint8 *pCipherText, Uint64 currPlainTextLen, Uint64 startBlockNum)#
Encrypt plain text and write it to cipher text with provided handle.
This XTS specific API should be called only after alcp_cipher_segment_request and alcp_cipher_segment_init. API is meant to be used with XTS mode.
Note
Error needs to be checked for each call, valid only if alcp_is_error (ret) is false
Note
XTS: Argument currPlainTextLen should be multiple of 16bytes unless it’s the last call. By the last call,if there is a paritial block, both partial and a complete block has to be included in the last call to this function.
- Parameters:
pCipherHandle – [in] Session handle for future encrypt decrypt operation
pPlainText – [in] Pointer to Plain Text
pCipherText – [out] Pointer to Cipher Text
currPlainTextLen – [in] Length of the given plaintext
startBlockNum – [in] Start block number of given plaintext
- Returns:
Error Code for the API called.
-
alc_error_t alcp_cipher_segment_decrypt_xts(const alc_cipher_handle_p pCipherHandle, const Uint8 *pCipherText, Uint8 *pPlainText, Uint64 currCipherTextLen, Uint64 startBlockNum)#
Decryption of cipher text and write it to plain text with provided handle.
This XTS specific API should be called only after alcp_cipher_segment_init. API is meant to be used with XTS mode.
Note
Error needs to be checked for each call, valid only if alcp_is_error (ret) is false
Note
XTS: Argument currCipherTextLen should be multiple of 16bytes unless it’s the last call. By the last call,if there is a paritial block, both partial and a complete block has to be included in the last call to this function.
- Parameters:
pCipherHandle – [in] Session handle for future encrypt decrypt operation
pPlainText – [out] Pointer to Plain Text
pCipherText – [in] Pointer to Cipher Text
startBlockNum – [in] Start block number of given plaintext
currCipherTextLen – [in] Length of the given Cipher Text
- Returns:
Error Code for the API called.
-
void alcp_cipher_segment_finish(const alc_cipher_handle_p pCipherHandle)#
Release resources allocated by alcp_cipher_request.
This API is called to free the session resources
Note
alcp_cipher_finish to be called at the end of the transaction. Context will be unusable after this call.
- Parameters:
pCipherHandle – [in] Session handle for completed encrypt/decrypt operations whose resources has to be freed.
- Returns:
None
-
Uint64 alcp_cipher_aead_context_size(void)#
Gets the size of the context for a session.
This AEAD API should be called before alcp_cipher_aead_request to identify the memory to be allocated for context
- Returns:
Size of Context
-
alc_error_t alcp_cipher_aead_request(const alc_cipher_mode_t cipherMode, const Uint64 keyLen, alc_cipher_handle_p pCipherHandle)#
Request for populating handle with algorithm specified by cipher mode and key length info.
This AEAD API can be called after alcp_cipher_aead_context_size is called
Note
Error needs to be checked for each call, valid only if alcp_is_error (ret) is false
- Parameters:
cipherMode – [in] AEAD cipher mode to be set
keyLen – [in] key length in bits
pCipherHandle – [out] Library populated session handle for future cipher operations.
- Returns:
Error Code for the API called. If alc_error_t is not ALC_ERROR_NONE then an error has occurred and handle will be invalid for future operations
-
alc_error_t alcp_cipher_aead_init(const alc_cipher_handle_p pCipherHandle, const Uint8 *pKey, Uint64 keyLen, const Uint8 *pIv, Uint64 ivLen)#
Cipher aead init.
This API can be called after alcp_cipher_aead_request is called. For SIV decrypt, the IV passed should be the tag generated by alcp_cipher_aead_get_tag during encrypt call.
- Parameters:
pCipherHandle – [in] Session handle for future encrypt/decrypt operation
pKey – [in] Key
keyLen – [in] key Length in bits
pIv – [in] IV/Nonce
ivLen – [in] iv Length in bits
- Returns:
Error Code for the API called. If alc_error_t is not ALC_ERROR_NONE then an error has occurred and handle will be invalid for future operations
-
alc_error_t alcp_cipher_aead_encrypt(const alc_cipher_handle_p pCipherHandle, const Uint8 *pInput, Uint8 *pOutput, Uint64 len)#
AEAD encryption of plain text and write it to cipher text with provided handle.
This AEAD API can be called after alcp_cipher_aead_request and before alcp_cipher_aead_finish
Note
Error needs to be checked for each call, valid only if alcp_is_error (ret) is false
- Parameters:
pCipherHandle – [in] Session handle for future encrypt decrypt operation
pInput – [in] Pointer to plainText
pOutput – [out] Pointer to cipherText
len – [in] Length of plainText/cipherText
- Returns:
Error Code for the API called. If alc_error_t is not ALC_ERROR_NONE then an error has occurred and handle will be invalid for future operations
-
alc_error_t alcp_cipher_aead_decrypt(const alc_cipher_handle_p pCipherHandle, const Uint8 *pInput, Uint8 *pOutput, Uint64 len)#
AEAD decryption of cipher text and write it to plain text with provided handle.
This AEAD API can be called after alcp_cipher_aead_request and before alcp_cipher_aead_finish
Note
Error needs to be checked for each call, valid only if alcp_is_error (ret) is false
- Parameters:
pCipherHandle – [in] Session handle for future encrypt/decrypt operation
pInput – [in] Pointer to CipherText
pOutput – [out] Pointer to PlainText
len – [in] Length of PlainText/CipherText
- Returns:
Error Code for the API called. If alc_error_t is not ALC_ERROR_NONE then an error has occurred and handle will be invalid for future operations
-
alc_error_t alcp_cipher_aead_set_aad(const alc_cipher_handle_p pCipherHandle, const Uint8 *pInput, Uint64 len)#
AEAD set Additonal Data for the Tag Generation.
This AEAD API can be called after alcp_cipher_aead_init.
- Parameters:
pCipherHandle – [in] Session handle for encrypt/decrypt operation
pInput – [in] Additional Data in Bytes
len – [in] Length in bytes of Additional Data
- Returns:
Error Code for the API called. If alc_error_t is not ALC_ERROR_NONE, then an error has occurred and handle will be invalid for future operations
-
alc_error_t alcp_cipher_aead_get_tag(const alc_cipher_handle_p pCipherHandle, Uint8 *pOutput, Uint64 tagLen)#
AEAD get a copy of Tag generated.
This AEAD API can be called after alcp_cipher_aead_request and before alcp_cipher_aead_finish
- Parameters:
pCipherHandle – [in] Session handle for encrypt/decrypt operation
pOutput – [out] Byte addressable memory to write tag into
tagLen – [in] Length of Tag in bytes
- Returns:
Error Code for the API called. If alc_error_t is not ALC_ERROR_NONE then an error has occurred and handle will be invalid for future operations
-
alc_error_t alcp_cipher_aead_set_tag_length(const alc_cipher_handle_p pCipherHandle, Uint64 tagLen)#
AEAD set the tag length.
This AEAD API is meant specifically for CCM and have to be called after alcp_cipher_aead_request and before alcp_cipher_aead_init
- Parameters:
pCipherHandle – [in] Session handle for encrypt/decrypt operation
tagLen – [in] Length of Tag in bytes
- Returns:
Error Code for the API called. If alc_error_t is not ALC_ERROR_NONE then an error has occurred and handle will be invalid for future operations
-
alc_error_t alcp_cipher_aead_set_ccm_plaintext_length(const alc_cipher_handle_p pCipherHandle, Uint64 plaintextLength)#
AEAD set the total plaintext length which is to be encrypted for CCM mode.
This AEAD API is meant specifically for CCM and have to be called after alcp_cipher_aead_request and before alcp_cipher_aead_init
- Parameters:
pCipherHandle – [in] Session handle for encrypt/decrypt operation
plaintextLength – [in] Length in bytes of plaintext in bytes
- Returns:
Error Code for the API called. If alc_error_t is not ALC_ERROR_NONE then an error has occurred and handle will be invalid for future operations
-
void alcp_cipher_aead_finish(const alc_cipher_handle_p pCipherHandle)#
Release resources allocated by alcp_cipher_aead_request.
This AEAD API is called to free session resources
Note
Need to be called at the end of the transaction, context will be unusable after this call.
- Parameters:
pCipherHandle – [in] Session handle for the completed encrypt/decrypt operations whose resources has to be freed.
- Returns:
None
Variables#
-
enum _alc_cipher_mode alc_cipher_mode_t#
Specify which Mode of AES to be used for encrypt and decrypt.
-
enum alc_key_len alc_key_len_t#
Stores length of key.
-
void alc_cipher_context_t#
Opaque type of a cipher context, comes from the library.