Cipher
Secure Engine Manager

Description

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.

Data Structures

struct sl_se_cmac_multipart_context_t
CMAC streaming context.
struct sl_se_ccm_multipart_context_t
CCM streaming context.
struct sl_se_gcm_multipart_context_t

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[16], 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 SL_SE_GCM_STREAMING_INIT_DEFAULT
Initial values for AES-GCM streaming context struct sl_se_gcm_streaming_context_t.

Enumerations

enum sl_se_cipher_operation_t {
SL_SE_ENCRYPT ,
SL_SE_DECRYPT
}
Cipher operation types.

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.

◆ 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[16],
const unsigned char * input,
unsigned char * output
)

AES-CBC buffer encryption/decryption.

Note
Length should be a multiple of the block size (16 bytes).
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,out] 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.

◆ 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[16],
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.
[in,out] iv_off Offset in IV (updated after use).
[in,out] 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.

◆ 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[16],
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.
[in,out] 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.

◆ 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[16],
unsigned char stream_block[16],
const unsigned char * input,
unsigned char * output
)

AES-CTR buffer encryption/decryption.

Warning
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
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.
[in,out] nonce_counter The 128-bit nonce and counter.
[in,out] 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.
Returns
Status code, sl_status.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.
[in,out] 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.

◆ 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.

◆ 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.

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

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.
Returns
Status code, sl_status.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.

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

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.
Returns
Status code, sl_status.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.

It is called after sl_se_ccm_multipart_update() .

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.
[in,out] 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.
Returns
Returns SL_SE_INVALID_SIGNATURE if authentication step fails. Status code, sl_status.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.

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.
Warning
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.
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.
Returns
SL_STATUS_OK when the command was executed successfully, otherwise an appropriate error code (sl_status.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.

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.
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] tag The buffer holding the tag to verify.
[in] tag_len The length of the tag to verify (in bytes).
[in] input The buffer holding the ciphertext. Its size is length bytes.
[out] output The buffer for holding the decrypted plaintext. It must have room for length bytes.
Returns
SL_STATUS_OK when the command was executed successfully, otherwise an appropriate error code (sl_status.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.

◆ 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.

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

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.
Returns
Status code, sl_status.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.

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

Parameters
[in,out] 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.
Returns
Status code, sl_status.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.

It is called after sl_se_cmac_multipart_update() .

Parameters
[in,out] 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.
Returns
Status code, sl_status.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.

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

Parameters
[in,out] 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.
Returns
Status code, sl_status.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.

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

Parameters
[in,out] gcm_ctx Pointer to a GCM streaming context object.
[in] length The length of the input data.
[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.
Returns
Status code, sl_status.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.

It is called after sl_se_gcm_multipart_update() .

Parameters
[in,out] gcm_ctx Pointer to a GCM streaming context object.
[in,out] tag Encryption: The buffer for holding the tag. Decryption: The tag to authenticate.
[in] tag_length Encryption: Length of the output tag. Decryption: Length of tag to verify
[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_gcm_multipart_update (stored data is maximum 16 bytes).
[out] output_length Length of data that has been encrypted/decrypted.
Returns
Returns SL_SE_INVALID_SIGNATURE if authentication step fails. Status code, sl_status.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.

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.

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.
Returns
Status code, sl_status.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[4],
const unsigned char nonce[12],
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.

◆ 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[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.

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.

◆ 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[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.

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.

◆ 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[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.

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.
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.
Returns
Status code, sl_status.h.

Macro Definition Documentation

◆ SL_SE_CMAC_STREAMING_INIT_DEFAULT

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

Initial values for CMAC streaming context struct sl_se_cmac_streaming_context_t.

◆ 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.

Enumeration Type Documentation

◆ sl_se_cipher_operation_t

enum sl_se_cipher_operation_t

Cipher operation types.