Cipher#

Symmetric encryption, AEAD and MAC.

API for performing symmetric encryption, Authenticated Encryption and Additional Data (AEAD) operations, and computing Message Authentication Codes (MACs) using the Secure Engine.

Modules#

sl_se_cmac_multipart_context_t

sl_se_ccm_multipart_context_t

sl_se_gcm_multipart_context_t

Enumerations#

enum
SL_SE_ENCRYPT
SL_SE_DECRYPT
}

Cipher operation types.

Functions#

sl_status_t
sl_se_aes_crypt_ecb(sl_se_command_context_t *cmd_ctx, const sl_se_key_descriptor_t *key, sl_se_cipher_operation_t mode, size_t length, const unsigned char *input, unsigned char *output)

AES-ECB block encryption/decryption.

sl_status_t
sl_se_aes_crypt_cbc(sl_se_command_context_t *cmd_ctx, const sl_se_key_descriptor_t *key, sl_se_cipher_operation_t mode, size_t length, unsigned char iv[16], const unsigned char *input, unsigned char *output)

AES-CBC buffer encryption/decryption.

sl_status_t
sl_se_aes_crypt_cfb128(sl_se_command_context_t *cmd_ctx, const sl_se_key_descriptor_t *key, sl_se_cipher_operation_t mode, size_t length, uint32_t *iv_off, unsigned char iv[16], const unsigned char *input, unsigned char *output)

AES-CFB128 buffer encryption/decryption.

sl_status_t
sl_se_aes_crypt_cfb8(sl_se_command_context_t *cmd_ctx, const sl_se_key_descriptor_t *key, sl_se_cipher_operation_t mode, size_t length, unsigned char iv[16], const unsigned char *input, unsigned char *output)

AES-CFB8 buffer encryption/decryption.

sl_status_t
sl_se_aes_crypt_ctr(sl_se_command_context_t *cmd_ctx, const sl_se_key_descriptor_t *key, size_t length, uint32_t *nc_off, unsigned char nonce_counter[16], unsigned char stream_block[SLI_SE_AES_CTR_NUM_BLOCKS_BUFFERED *SL_SE_AES_BLOCK_SIZE], const unsigned char *input, unsigned char *output)

AES-CTR buffer encryption/decryption.

sl_status_t
sl_se_ccm_encrypt_and_tag(sl_se_command_context_t *cmd_ctx, const sl_se_key_descriptor_t *key, size_t length, const unsigned char *iv, size_t iv_len, const unsigned char *add, size_t add_len, const unsigned char *input, unsigned char *output, unsigned char *tag, size_t tag_len)

AES-CCM buffer encryption.

sl_status_t
sl_se_ccm_auth_decrypt(sl_se_command_context_t *cmd_ctx, const sl_se_key_descriptor_t *key, size_t length, const unsigned char *iv, size_t iv_len, const unsigned char *add, size_t add_len, const unsigned char *input, unsigned char *output, const unsigned char *tag, size_t tag_len)

AES-CCM buffer decryption.

sl_status_t
sl_se_ccm_multipart_starts(sl_se_ccm_multipart_context_t *ccm_ctx, sl_se_command_context_t *cmd_ctx, const sl_se_key_descriptor_t *key, sl_se_cipher_operation_t mode, uint32_t total_message_length, const uint8_t *iv, size_t iv_len, const uint8_t *add, size_t add_len, size_t tag_len)

Prepare a CCM streaming command context object.

sl_status_t
sl_se_ccm_multipart_update(sl_se_ccm_multipart_context_t *ccm_ctx, sl_se_command_context_t *cmd_ctx, const sl_se_key_descriptor_t *key, size_t length, const uint8_t *input, uint8_t *output, size_t *output_length)

This function feeds an input buffer into an ongoing CCM computation.

sl_status_t
sl_se_ccm_multipart_finish(sl_se_ccm_multipart_context_t *ccm_ctx, sl_se_command_context_t *cmd_ctx, const sl_se_key_descriptor_t *key, uint8_t *tag, uint8_t tag_size, uint8_t *output, uint8_t output_size, uint8_t *output_length)

Finish a CCM streaming operation and return the resulting CCM tag.

sl_status_t
sl_se_gcm_crypt_and_tag(sl_se_command_context_t *cmd_ctx, const sl_se_key_descriptor_t *key, sl_se_cipher_operation_t mode, size_t length, const unsigned char *iv, size_t iv_len, const unsigned char *add, size_t add_len, const unsigned char *input, unsigned char *output, size_t tag_len, unsigned char *tag)

This function performs GCM encryption or decryption of a buffer.

sl_status_t
sl_se_gcm_auth_decrypt(sl_se_command_context_t *cmd_ctx, const sl_se_key_descriptor_t *key, size_t length, const unsigned char *iv, size_t iv_len, const unsigned char *add, size_t add_len, const unsigned char *input, unsigned char *output, size_t tag_len, const unsigned char *tag)

This function performs a GCM authenticated decryption of a buffer.

sl_status_t
sl_se_cmac(sl_se_command_context_t *cmd_ctx, const sl_se_key_descriptor_t *key, const unsigned char *input, size_t input_len, unsigned char *output)

This function calculates the full generic CMAC on the input buffer with the provided key.

sl_status_t
sl_se_cmac_multipart_starts(sl_se_cmac_multipart_context_t *cmac_ctx, sl_se_command_context_t *cmd_ctx, const sl_se_key_descriptor_t *key)

Prepare a CMAC streaming command context object.

sl_status_t
sl_se_cmac_multipart_update(sl_se_cmac_multipart_context_t *cmac_ctx, sl_se_command_context_t *cmd_ctx, const sl_se_key_descriptor_t *key, const uint8_t *input, size_t input_len)

This function feeds an input buffer into an ongoing CMAC computation.

sl_status_t
sl_se_cmac_multipart_finish(sl_se_cmac_multipart_context_t *cmac_ctx, sl_se_command_context_t *cmd_ctx, const sl_se_key_descriptor_t *key, uint8_t *output)

Finish a CMAC streaming operation and return the resulting CMAC tag.

sl_status_t
sl_se_gcm_multipart_starts(sl_se_gcm_multipart_context_t *gcm_ctx, sl_se_command_context_t *cmd_ctx, const sl_se_key_descriptor_t *key, sl_se_cipher_operation_t mode, const uint8_t *iv, size_t iv_len, const uint8_t *add, size_t add_len)

Prepare a GCM streaming command context object.

sl_status_t
sl_se_gcm_multipart_update(sl_se_gcm_multipart_context_t *gcm_ctx, sl_se_command_context_t *cmd_ctx, const sl_se_key_descriptor_t *key, size_t length, const uint8_t *input, uint8_t *output, size_t *output_length)

This function feeds an input buffer into an ongoing GCM computation.

sl_status_t
sl_se_gcm_multipart_finish(sl_se_gcm_multipart_context_t *gcm_ctx, sl_se_command_context_t *cmd_ctx, const sl_se_key_descriptor_t *key, uint8_t *tag, uint8_t tag_length, uint8_t *output, uint8_t output_size, uint8_t *output_length)

Finish a GCM streaming operation and return the resulting GCM tag.

sl_status_t
sl_se_hmac(sl_se_command_context_t *cmd_ctx, const sl_se_key_descriptor_t *key, sl_se_hash_type_t hash_type, const uint8_t *message, size_t message_len, uint8_t *output, size_t output_len)

Compute a HMAC on a full message.

sl_status_t
sl_se_chacha20_crypt(sl_se_command_context_t *cmd_ctx, sl_se_cipher_operation_t mode, const sl_se_key_descriptor_t *key, size_t length, const unsigned char initial_counter[4], const unsigned char nonce[12], const unsigned char *input, unsigned char *output)

ChaCha20 buffer encryption/decryption, as defined by RFC8439 section 2.4.

sl_status_t
sl_se_chacha20_poly1305_encrypt_and_tag(sl_se_command_context_t *cmd_ctx, const sl_se_key_descriptor_t *key, size_t length, const unsigned char nonce[12], const unsigned char *add, size_t add_len, const unsigned char *input, unsigned char *output, unsigned char *tag)

ChaCha20-Poly1305 authenticated encryption with additional data, as defined by RFC8439 section 2.8.

sl_status_t
sl_se_chacha20_poly1305_auth_decrypt(sl_se_command_context_t *cmd_ctx, const sl_se_key_descriptor_t *key, size_t length, const unsigned char nonce[12], const unsigned char *add, size_t add_len, const unsigned char *input, unsigned char *output, const unsigned char tag[16])

ChaCha20-Poly1305 authenticated decryption with additional data, as defined by RFC8439 section 2.8.

sl_status_t
sl_se_poly1305_genkey_tag(sl_se_command_context_t *cmd_ctx, const sl_se_key_descriptor_t *key, size_t length, const unsigned char nonce[12], const unsigned char *input, unsigned char *tag)

Generate a Poly1305 MAC (message authentication code) for a given message using an ephemeral key derived using ChaCha20.

Macros#

#define
SL_SE_CMAC_STREAMING_INIT_DEFAULT { NULL, { 0 }, { 0 }, 0 }

Initial values for CMAC streaming context struct sl_se_cmac_streaming_context_t.

#define

Initial values for AES-GCM streaming context struct sl_se_gcm_streaming_context_t.

#define

Block size for the AES.

Enumeration Documentation#

sl_se_cipher_operation_t#

sl_se_cipher_operation_t

Cipher operation types.

Enumerator
SL_SE_ENCRYPT
SL_SE_DECRYPT

Definition at line 333 of file platform/security/sl_component/se_manager/inc/sl_se_manager_types.h

Function Documentation#

sl_se_aes_crypt_ecb#

sl_status_t sl_se_aes_crypt_ecb (sl_se_command_context_t * cmd_ctx, const sl_se_key_descriptor_t * key, sl_se_cipher_operation_t mode, size_t length, const unsigned char * input, unsigned char * output)

AES-ECB block encryption/decryption.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]key

Pointer to sl_se_key_descriptor_t structure.

[in]mode

Crypto operation type (encryption or decryption).

[in]length

Length of the input data.

[in]input

Buffer holding the input data.

[out]output

Buffer holding the output data.

Returns

  • Status code, sl_status.h.


Definition at line 94 of file platform/security/sl_component/se_manager/inc/sl_se_manager_cipher.h

sl_se_aes_crypt_cbc#

sl_status_t sl_se_aes_crypt_cbc (sl_se_command_context_t * cmd_ctx, const sl_se_key_descriptor_t * key, sl_se_cipher_operation_t mode, size_t length, unsigned char iv, const unsigned char * input, unsigned char * output)

AES-CBC buffer encryption/decryption.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]key

Pointer to sl_se_key_descriptor_t structure.

[in]mode

Crypto operation type (encryption or decryption).

[in]length

Length of the input data.

[inout]iv

Initialization vector (updated after use).

[in]input

Buffer holding the input data.

[out]output

Buffer holding the output data.

Note

  • Length should be a multiple of the block size (16 bytes).

Returns

  • Status code, sl_status.h.


Definition at line 132 of file platform/security/sl_component/se_manager/inc/sl_se_manager_cipher.h

sl_se_aes_crypt_cfb128#

sl_status_t sl_se_aes_crypt_cfb128 (sl_se_command_context_t * cmd_ctx, const sl_se_key_descriptor_t * key, sl_se_cipher_operation_t mode, size_t length, uint32_t * iv_off, unsigned char iv, const unsigned char * input, unsigned char * output)

AES-CFB128 buffer encryption/decryption.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]key

Pointer to sl_se_key_descriptor_t structure.

[in]mode

Crypto operation type (encryption or decryption).

[in]length

Length of the input data.

[inout]iv_off

Offset in IV (updated after use).

[inout]iv

Initialization vector (updated after use).

[in]input

Buffer holding the input data.

[out]output

Buffer holding the output data.

Returns

  • Status code, sl_status.h.


Definition at line 171 of file platform/security/sl_component/se_manager/inc/sl_se_manager_cipher.h

sl_se_aes_crypt_cfb8#

sl_status_t sl_se_aes_crypt_cfb8 (sl_se_command_context_t * cmd_ctx, const sl_se_key_descriptor_t * key, sl_se_cipher_operation_t mode, size_t length, unsigned char iv, const unsigned char * input, unsigned char * output)

AES-CFB8 buffer encryption/decryption.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]key

Pointer to sl_se_key_descriptor_t structure.

[in]mode

Crypto operation type (encryption or decryption).

[in]length

Length of the input data.

[inout]iv

Initialization vector (updated after use).

[in]input

Buffer holding the input data.

[out]output

Buffer holding the output data.

Returns

  • Status code, sl_status.h.


Definition at line 208 of file platform/security/sl_component/se_manager/inc/sl_se_manager_cipher.h

sl_se_aes_crypt_ctr#

sl_status_t sl_se_aes_crypt_ctr (sl_se_command_context_t * cmd_ctx, const sl_se_key_descriptor_t * key, size_t length, uint32_t * nc_off, unsigned char nonce_counter, unsigned char stream_block, const unsigned char * input, unsigned char * output)

AES-CTR buffer encryption/decryption.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]key

Pointer to sl_se_key_descriptor_t structure.

[in]length

Length of the input data.

[in]nc_off

The offset in the current stream_block (for resuming within current cipher stream). The offset pointer to should be 0 at the start of a stream.

[inout]nonce_counter

The 128-bit nonce and counter.

[inout]stream_block

The saved stream-block for resuming (updated after use).

[in]input

Buffer holding the input data.

[out]output

Buffer holding the output data.

Warnings

  • Avoid passing in the same buffer for nonce_counter and stream_block as the incrementation operation of nonce_counter can lead to corruption of the ciphertext

Returns

  • Status code, sl_status.h.


Definition at line 254 of file platform/security/sl_component/se_manager/inc/sl_se_manager_cipher.h

sl_se_ccm_encrypt_and_tag#

sl_status_t sl_se_ccm_encrypt_and_tag (sl_se_command_context_t * cmd_ctx, const sl_se_key_descriptor_t * key, size_t length, const unsigned char * iv, size_t iv_len, const unsigned char * add, size_t add_len, const unsigned char * input, unsigned char * output, unsigned char * tag, size_t tag_len)

AES-CCM buffer encryption.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]key

Pointer to sl_se_key_descriptor_t structure.

[in]length

The length of the input data in Bytes.

[in]iv

Initialization vector (nonce).

[in]iv_len

The length of the IV in Bytes: 7, 8, 9, 10, 11, 12, or 13.

[in]add

The additional data field.

[in]add_len

The length of additional data in Bytes.

[in]input

The buffer holding the input data.

[out]output

The buffer holding the output data. Must be at least length Bytes wide.

[inout]tag

The buffer holding the tag.

[in]tag_len

The length of the tag to generate in Bytes: 4, 6, 8, 10, 12, 14 or 16.

Returns

  • Status code, sl_status.h.


Definition at line 303 of file platform/security/sl_component/se_manager/inc/sl_se_manager_cipher.h

sl_se_ccm_auth_decrypt#

sl_status_t sl_se_ccm_auth_decrypt (sl_se_command_context_t * cmd_ctx, const sl_se_key_descriptor_t * key, size_t length, const unsigned char * iv, size_t iv_len, const unsigned char * add, size_t add_len, const unsigned char * input, unsigned char * output, const unsigned char * tag, size_t tag_len)

AES-CCM buffer decryption.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]key

Pointer to sl_se_key_descriptor_t structure.

[in]length

The length of the input data in Bytes.

[in]iv

Initialization vector.

[in]iv_len

The length of the IV in Bytes: 7, 8, 9, 10, 11, 12, or 13.

[in]add

The additional data field.

[in]add_len

The length of additional data in Bytes.

[in]input

The buffer holding the input data.

[out]output

The buffer holding the output data. Must be at least length Bytes wide.

[in]tag

The buffer holding the tag.

[in]tag_len

The length of the tag in Bytes. Must be 4, 6, 8, 10, 12, 14 or 16.

Returns

  • Status code, sl_status.h.


Definition at line 352 of file platform/security/sl_component/se_manager/inc/sl_se_manager_cipher.h

sl_se_ccm_multipart_starts#

sl_status_t sl_se_ccm_multipart_starts (sl_se_ccm_multipart_context_t * ccm_ctx, sl_se_command_context_t * cmd_ctx, const sl_se_key_descriptor_t * key, sl_se_cipher_operation_t mode, uint32_t total_message_length, const uint8_t * iv, size_t iv_len, const uint8_t * add, size_t add_len, size_t tag_len)

Prepare a CCM streaming command context object.

Parameters
[in]ccm_ctx

Pointer to a CCM streaming context object.

[in]cmd_ctx

Pointer to a SE command context object.

[in]key

Pointer to sl_se_key_descriptor_t structure.

[in]mode

The operation to perform: SL_SE_ENCRYPT or SL_SE_DECRYPT.

[in]total_message_length

The total length of the text to encrypt/decrypt

[in]iv

The initialization vector (commonly referred to as nonce for CCM).

[in]iv_len

The length of the IV.

[in]add

The buffer holding the additional data.

[in]add_len

The length of the additional data.

[in]tag_len

Encryption: The length of the tag to generate. Must be 0, 4, 6, 8, 10, 12, 14 or 16. Decryption: The length of the tag to authenticate. Must be 0, 4, 6, 8, 10, 12, 14 or 16.

Prepare a CCM streaming command context object to be used in subsequent CCM streaming function calls.

Returns

  • Status code, sl_status.h.


Definition at line 403 of file platform/security/sl_component/se_manager/inc/sl_se_manager_cipher.h

sl_se_ccm_multipart_update#

sl_status_t sl_se_ccm_multipart_update (sl_se_ccm_multipart_context_t * ccm_ctx, sl_se_command_context_t * cmd_ctx, const sl_se_key_descriptor_t * key, size_t length, const uint8_t * input, uint8_t * output, size_t * output_length)

This function feeds an input buffer into an ongoing CCM computation.

Parameters
[in]ccm_ctx

Pointer to a CCM streaming context object.

[in]cmd_ctx

Pointer to a SE command context object.

[in]key

Pointer to sl_se_key_descriptor_t structure.

[in]length

The length of the input data. This must be a multiple of 16 except in the last call before sl_se_ccm_multipart_finish().

[in]input

Buffer holding the input data, must be at least length bytes wide.

[out]output

Buffer for holding the output data, must be at least length bytes wide.

[out]output_length

Length of data that has been encrypted/decrypted.

It is called between sl_se_ccm_multipart_starts() and sl_se_ccm_multipart_finish(). Can be called repeatedly.

Returns

  • Status code, sl_status.h.


Definition at line 447 of file platform/security/sl_component/se_manager/inc/sl_se_manager_cipher.h

sl_se_ccm_multipart_finish#

sl_status_t sl_se_ccm_multipart_finish (sl_se_ccm_multipart_context_t * ccm_ctx, sl_se_command_context_t * cmd_ctx, const sl_se_key_descriptor_t * key, uint8_t * tag, uint8_t tag_size, uint8_t * output, uint8_t output_size, uint8_t * output_length)

Finish a CCM streaming operation and return the resulting CCM tag.

Parameters
[in]ccm_ctx

Pointer to a CCM streaming context object.

[in]cmd_ctx

Pointer to an SE command context object.

[in]key

Pointer to sl_se_key_descriptor_t structure.

[inout]tag

Encryption: The buffer for holding the tag. Decryption: The tag to authenticate.

[in]tag_size

The size of the tag buffer. Must be equal or greater to the length of the expected tag.

[out]output

Buffer for holding the output data.

[in]output_size

Output buffer size. Must be equal or greater to the stored data from sl_se_ccm_multipart_update (maximum 16 bytes).

[out]output_length

Length of data that has been encrypted/decrypted.

It is called after sl_se_ccm_multipart_update().

Returns

  • Returns SL_SE_INVALID_SIGNATURE if authentication step fails. Status code, sl_status.h.


Definition at line 491 of file platform/security/sl_component/se_manager/inc/sl_se_manager_cipher.h

sl_se_gcm_crypt_and_tag#

sl_status_t sl_se_gcm_crypt_and_tag (sl_se_command_context_t * cmd_ctx, const sl_se_key_descriptor_t * key, sl_se_cipher_operation_t mode, size_t length, const unsigned char * iv, size_t iv_len, const unsigned char * add, size_t add_len, const unsigned char * input, unsigned char * output, size_t tag_len, unsigned char * tag)

This function performs GCM encryption or decryption of a buffer.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]key

Pointer to sl_se_key_descriptor_t structure.

[in]mode

Crypto operation type (encryption or decryption).

  • SL_SE_ENCRYPT: The ciphertext is written to output and the authentication tag is written to tag.

  • SL_SE_DECRYPT: The plaintext is written to output and the authentication tag is written to tag. Note that this mode is not recommended, because it does not verify the authenticity of the data. For this reason, you should use sl_se_gcm_auth_decrypt() instead.

[in]length

The length of the input data, which is equal to the length of the output data.

[in]iv

The initialization vector.

[in]iv_len

The length of the iv. Must be 12 bytes.

[in]add

The buffer holding the additional data.

[in]add_len

The length of the additional data in bytes.

[in]input

The buffer holding the input data. Its size is length bytes.

[out]output

The buffer for holding the output data. It must have room for length bytes.

[in]tag_len

The length of the tag to generate (in bytes).

[out]tag

The buffer for holding the tag.

Note

  • For encryption, the output buffer can be the same as the input buffer. For decryption, the output buffer cannot be the same as input buffer. If the buffers overlap, the output buffer must trail at least 8 bytes behind the input buffer.

Warnings

  • When this function performs a decryption, it outputs the authentication tag and does not verify that the data is authentic. You should use this function to perform encryption only. For decryption, use sl_se_gcm_auth_decrypt() instead.

Returns

  • SL_STATUS_OK when the command was executed successfully, otherwise an appropriate error code (sl_status.h).


Definition at line 565 of file platform/security/sl_component/se_manager/inc/sl_se_manager_cipher.h

sl_se_gcm_auth_decrypt#

sl_status_t sl_se_gcm_auth_decrypt (sl_se_command_context_t * cmd_ctx, const sl_se_key_descriptor_t * key, size_t length, const unsigned char * iv, size_t iv_len, const unsigned char * add, size_t add_len, const unsigned char * input, unsigned char * output, size_t tag_len, const unsigned char * tag)

This function performs a GCM authenticated decryption of a buffer.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]key

Pointer to sl_se_key_descriptor_t structure.

[in]length

The length of the ciphertext to decrypt, which is also the length of the decrypted plaintext.

[in]iv

The initialization vector.

[in]iv_len

The length of the iv. Must be 12 bytes.

[in]add

The buffer holding the additional data.

[in]add_len

The length of the additional data in bytes.

[in]input

The buffer holding the tag to verify.

[in]output

The length of the tag to verify (in bytes).

[in]tag_len

The buffer holding the ciphertext. Its size is length bytes.

[out]tag

The buffer for holding the decrypted plaintext. It must have room for length bytes.

Note

  • The output buffer cannot be the same as input buffer. If the buffers overlap, the output buffer must trail at least 8 bytes behind the input buffer.

Returns

  • SL_STATUS_OK when the command was executed successfully, otherwise an appropriate error code (sl_status.h).


Definition at line 626 of file platform/security/sl_component/se_manager/inc/sl_se_manager_cipher.h

sl_se_cmac#

sl_status_t sl_se_cmac (sl_se_command_context_t * cmd_ctx, const sl_se_key_descriptor_t * key, const unsigned char * input, size_t input_len, unsigned char * output)

This function calculates the full generic CMAC on the input buffer with the provided key.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]key

Pointer to sl_se_key_descriptor_t structure.

[in]input

Buffer holding the input data, must be at least input_len bytes wide.

[in]input_len

The length of the input data in bytes.

[out]output

Buffer holding the 16-byte output data, must be at least 16 bytes wide.

Returns

  • Status code, sl_status.h.


Definition at line 661 of file platform/security/sl_component/se_manager/inc/sl_se_manager_cipher.h

sl_se_cmac_multipart_starts#

sl_status_t sl_se_cmac_multipart_starts (sl_se_cmac_multipart_context_t * cmac_ctx, sl_se_command_context_t * cmd_ctx, const sl_se_key_descriptor_t * key)

Prepare a CMAC streaming command context object.

Parameters
[in]cmac_ctx

Pointer to a CMAC streaming context object.

[in]cmd_ctx

Pointer to an SE command context object.

[in]key

Pointer to sl_se_key_descriptor_t structure.

Prepare a CMAC streaming command context object to be used in subsequent CMAC streaming function calls.

Returns

  • Status code, sl_status.h.


Definition at line 687 of file platform/security/sl_component/se_manager/inc/sl_se_manager_cipher.h

sl_se_cmac_multipart_update#

sl_status_t sl_se_cmac_multipart_update (sl_se_cmac_multipart_context_t * cmac_ctx, sl_se_command_context_t * cmd_ctx, const sl_se_key_descriptor_t * key, const uint8_t * input, size_t input_len)

This function feeds an input buffer into an ongoing CMAC computation.

Parameters
[inout]cmac_ctx

Pointer to a CMAC streaming context object.

[in]cmd_ctx

Pointer to an SE command context object.

[in]key

Pointer to sl_se_key_descriptor_t structure.

[in]input

Buffer holding the input data, must be at least input_len bytes wide.

[in]input_len

The length of the input data in bytes.

It is called between sl_se_cmac_multipart_starts() and sl_se_cmac_multipart_finish(). Can be called repeatedly.

Returns

  • Status code, sl_status.h.


Definition at line 717 of file platform/security/sl_component/se_manager/inc/sl_se_manager_cipher.h

sl_se_cmac_multipart_finish#

sl_status_t sl_se_cmac_multipart_finish (sl_se_cmac_multipart_context_t * cmac_ctx, sl_se_command_context_t * cmd_ctx, const sl_se_key_descriptor_t * key, uint8_t * output)

Finish a CMAC streaming operation and return the resulting CMAC tag.

Parameters
[inout]cmac_ctx

Pointer to a CMAC streaming context object.

[in]cmd_ctx

Pointer to an SE command context object.

[in]key

Pointer to sl_se_key_descriptor_t structure.

[out]output

Buffer holding the 16-byte CMAC tag, must be at least 16 bytes wide.

It is called after sl_se_cmac_multipart_update().

Returns

  • Status code, sl_status.h.


Definition at line 745 of file platform/security/sl_component/se_manager/inc/sl_se_manager_cipher.h

sl_se_gcm_multipart_starts#

sl_status_t sl_se_gcm_multipart_starts (sl_se_gcm_multipart_context_t * gcm_ctx, sl_se_command_context_t * cmd_ctx, const sl_se_key_descriptor_t * key, sl_se_cipher_operation_t mode, const uint8_t * iv, size_t iv_len, const uint8_t * add, size_t add_len)

Prepare a GCM streaming command context object.

Parameters
[inout]gcm_ctx

Pointer to a GCM streaming context object.

[in]cmd_ctx

Pointer to an SE command context object.

[in]key

Pointer to sl_se_key_descriptor_t structure.

[in]mode

The operation to perform: SL_SE_ENCRYPT or SL_SE_DECRYPT.

[in]iv

The initialization vector.

[in]iv_len

The length of the IV.

[in]add

The buffer holding the additional data, or NULL if add_len is 0.

[in]add_len

The length of the additional data. If 0, add is NULL.

Prepare a GCM streaming command context object to be used in subsequent GCM streaming function calls.

Returns

  • Status code, sl_status.h.


Definition at line 785 of file platform/security/sl_component/se_manager/inc/sl_se_manager_cipher.h

sl_se_gcm_multipart_update#

sl_status_t sl_se_gcm_multipart_update (sl_se_gcm_multipart_context_t * gcm_ctx, sl_se_command_context_t * cmd_ctx, const sl_se_key_descriptor_t * key, size_t length, const uint8_t * input, uint8_t * output, size_t * output_length)

This function feeds an input buffer into an ongoing GCM computation.

Parameters
[inout]gcm_ctx

Pointer to a GCM streaming context object.

[in]cmd_ctx

The length of the input data.

[in]key

Buffer holding the input data, must be at least length bytes wide.

[out]length

Buffer for holding the output data, must be at least length bytes wide.

[out]input

Length of data that has been encrypted/decrypted.

N/Aoutput
N/Aoutput_length

It is called between sl_se_gcm_multipart_starts() and sl_se_gcm_multiapart_finish(). Can be called repeatedly.

Returns

  • Status code, sl_status.h.


Definition at line 819 of file platform/security/sl_component/se_manager/inc/sl_se_manager_cipher.h

sl_se_gcm_multipart_finish#

sl_status_t sl_se_gcm_multipart_finish (sl_se_gcm_multipart_context_t * gcm_ctx, sl_se_command_context_t * cmd_ctx, const sl_se_key_descriptor_t * key, uint8_t * tag, uint8_t tag_length, uint8_t * output, uint8_t output_size, uint8_t * output_length)

Finish a GCM streaming operation and return the resulting GCM tag.

Parameters
[inout]gcm_ctx

Pointer to a GCM streaming context object.

[inout]cmd_ctx

Encryption: The buffer for holding the tag. Decryption: The tag to authenticate.

[in]key

Encryption: Length of the output tag. Decryption: Length of tag to verify

[out]tag

Buffer for holding the output data.

[in]tag_length

Output buffer size. Must be equal or greater to the stored data from sl_se_gcm_multipart_update (stored data is maximum 16 bytes).

[out]output

Length of data that has been encrypted/decrypted.

N/Aoutput_size
N/Aoutput_length

It is called after sl_se_gcm_multipart_update().

Returns

  • Returns SL_SE_INVALID_SIGNATURE if authentication step fails. Status code, sl_status.h.


Definition at line 858 of file platform/security/sl_component/se_manager/inc/sl_se_manager_cipher.h

sl_se_hmac#

sl_status_t sl_se_hmac (sl_se_command_context_t * cmd_ctx, const sl_se_key_descriptor_t * key, sl_se_hash_type_t hash_type, const uint8_t * message, size_t message_len, uint8_t * output, size_t output_len)

Compute a HMAC on a full message.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]key

Pointer to sl_se_key_descriptor_t structure specifying the key to use in the HMAC computation.

[in]hash_type

Which hashing algorithm to use.

[in]message

Pointer to the message buffer to compute the hash/digest from.

[in]message_len

Number of bytes in message.

[out]output

Pointer to memory buffer to store the final HMAC output.

[in]output_len

The length of the HMAC output memory buffer, must be at least the size of the corresponding hash type.

This function computes a Keyed-Hashed Message Authentication Code (HMAC) for the given input message. HMAC can be used with any iterative cryptographic hash function, e.g., SHA-1 in combination with a secret shared key. The cryptographic strength of HMAC depends on the properties of the underlying hash function. For instance, if the algorithm is chosen to be SHA-256, it will generate a 32 bytes HMAC. This function supports SHA-1, SHA-224, SHA-256, SHA-384 and SHA-512. The key can be of any length. If the key is shorter than the block size of the hash function the SE will append zeros to the key so the key size matches the block size of the hash function. If the key is longer than the block size of the hash function the key will be hashed to produce a key digest, then append zeros so the resulting 'hashed' key size matches the block size of the hash function. In any case the minimal recommended key length is the digest size of the hash function.

Returns

  • Status code, sl_status.h.


Definition at line 912 of file platform/security/sl_component/se_manager/inc/sl_se_manager_cipher.h

sl_se_chacha20_crypt#

sl_status_t sl_se_chacha20_crypt (sl_se_command_context_t * cmd_ctx, sl_se_cipher_operation_t mode, const sl_se_key_descriptor_t * key, size_t length, const unsigned char initial_counter, const unsigned char nonce, const unsigned char * input, unsigned char * output)

ChaCha20 buffer encryption/decryption, as defined by RFC8439 section 2.4.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]mode

Crypto operation type (encryption or decryption).

[in]key

Pointer to sl_se_key_descriptor_t structure.

[in]length

Length of the input data.

[in]initial_counter

The initial counter value as defined in RFC8439 section 2.4.

[in]nonce

The nonce, also called initialisation vector, as defined in RFC8439 section 2.4.

[in]input

Buffer holding the input data.

[out]output

Buffer holding the output data.

Returns

  • Status code, sl_status.h.


Definition at line 953 of file platform/security/sl_component/se_manager/inc/sl_se_manager_cipher.h

sl_se_chacha20_poly1305_encrypt_and_tag#

sl_status_t sl_se_chacha20_poly1305_encrypt_and_tag (sl_se_command_context_t * cmd_ctx, const sl_se_key_descriptor_t * key, size_t length, const unsigned char nonce, const unsigned char * add, size_t add_len, const unsigned char * input, unsigned char * output, unsigned char * tag)

ChaCha20-Poly1305 authenticated encryption with additional data, as defined by RFC8439 section 2.8.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]key

Pointer to sl_se_key_descriptor_t structure.

[in]length

The length of the input data in bytes.

[in]nonce

The nonce, also called initialisation vector, as defined in RFC8439 section 2.8.

[in]add

The buffer holding additional authenticated data. Can be NULL if add_len equals 0.

[in]add_len

The length of the additional authenticated data in bytes.

[in]input

The buffer holding the plaintext input.

[out]output

The buffer holding the ciphertext output. Can be NULL, in which case the generated ciphertext will be discarded. Must be at least length bytes wide.

[out]tag

The buffer holding the tag. This function will produce a 128-bit tag, so this buffer must be at least 16 bytes wide. Can be NULL, in which case the generated tag will be discarded.

Returns

  • Status code, sl_status.h.


Definition at line 1003 of file platform/security/sl_component/se_manager/inc/sl_se_manager_cipher.h

sl_se_chacha20_poly1305_auth_decrypt#

sl_status_t sl_se_chacha20_poly1305_auth_decrypt (sl_se_command_context_t * cmd_ctx, const sl_se_key_descriptor_t * key, size_t length, const unsigned char nonce, const unsigned char * add, size_t add_len, const unsigned char * input, unsigned char * output, const unsigned char tag)

ChaCha20-Poly1305 authenticated decryption with additional data, as defined by RFC8439 section 2.8.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]key

Pointer to sl_se_key_descriptor_t structure.

[in]length

The length of the input data in Bytes.

[in]nonce

The nonce, also called initialisation vector, as defined in RFC8439 section 2.8.

[in]add

The buffer holding additional authenticated data. Can be NULL if add_len equals 0.

[in]add_len

The length of the additional authenticated data in bytes.

[in]input

The buffer holding the ciphertext to decrypt. Can be NULL if length equals 0.

[out]output

The buffer holding the plaintext output. Can be NULL, in which case the decrypted plaintext will be discarded, or when length equals 0. Must be at least length bytes wide.

[in]tag

The buffer holding the tag to verify.

Returns

  • Status code, sl_status.h.


Definition at line 1052 of file platform/security/sl_component/se_manager/inc/sl_se_manager_cipher.h

sl_se_poly1305_genkey_tag#

sl_status_t sl_se_poly1305_genkey_tag (sl_se_command_context_t * cmd_ctx, const sl_se_key_descriptor_t * key, size_t length, const unsigned char nonce, const unsigned char * input, unsigned char * tag)

Generate a Poly1305 MAC (message authentication code) for a given message using an ephemeral key derived using ChaCha20.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]key

Pointer to sl_se_key_descriptor_t structure containing a ChaCha20 key.

[in]length

The length of the input data in Bytes.

[in]nonce

The nonce, also called initialisation vector, as defined in RFC8439 section 2.6.

[in]input

The buffer holding the input data.

[out]tag

The buffer holding the tag. This function will produce a 128-bit tag, so this buffer must be at least 16 bytes wide.

Note

  • This function first derives a Poly1305 key based on a ChaCha20 key and nonce, which are input to this function. The key derivation adheres to RFC8439 section 2.6. The derived key is then used to calculate a MAC of the input data, according to RFC8439 section 2.5.

Returns

  • Status code, sl_status.h.


Definition at line 1095 of file platform/security/sl_component/se_manager/inc/sl_se_manager_cipher.h

Macro Definition Documentation#

SL_SE_CMAC_STREAMING_INIT_DEFAULT#

#define SL_SE_CMAC_STREAMING_INIT_DEFAULT
Value:
{ NULL, { 0 }, { 0 }, 0 }

Initial values for CMAC streaming context struct sl_se_cmac_streaming_context_t.


Definition at line 467 of file platform/security/sl_component/se_manager/inc/sl_se_manager_defines.h

SL_SE_GCM_STREAMING_INIT_DEFAULT#

#define SL_SE_GCM_STREAMING_INIT_DEFAULT
Value:
{ NULL, 0, 0, { 0 }, { 0 }, \
{ 0 }, 0, 0 }

Initial values for AES-GCM streaming context struct sl_se_gcm_streaming_context_t.


Definition at line 470 of file platform/security/sl_component/se_manager/inc/sl_se_manager_defines.h

SL_SE_AES_BLOCK_SIZE#

#define SL_SE_AES_BLOCK_SIZE
Value:
(16u)

Block size for the AES.


Definition at line 474 of file platform/security/sl_component/se_manager/inc/sl_se_manager_defines.h