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.