se_cipher

# Secure Element Symmetric Ciphers

psa_drv_se_cipher_t
psa_status_t(* typedef psa_status_t(* psa_drv_se_cipher_setup_t) (psa_drv_se_context_t *drv_context, void *op_context, psa_key_slot_number_t key_slot, psa_algorithm_t algorithm, psa_encrypt_or_decrypt_t direction) )(psa_drv_se_context_t *drv_context, void *op_context, psa_key_slot_number_t key_slot, psa_algorithm_t algorithm, psa_encrypt_or_decrypt_t direction) psa_drv_se_cipher_setup_t

A function that provides the cipher setup function for a secure element driver.

drv_context

The driver context structure.

op_context

A structure that will contain the hardware-specific cipher context.

key_slot

The slot of the key to be used for the operation

algorithm

The algorithm to be used in the cipher operation

direction

Indicates whether the operation is an encrypt or decrypt

PSA_SUCCESS

PSA_ERROR_NOT_SUPPORTED

psa_status_t(* typedef psa_status_t(* psa_drv_se_cipher_set_iv_t) (void *op_context, const uint8_t *p_iv, size_t iv_length) )(void *op_context, const uint8_t *p_iv, size_t iv_length) psa_drv_se_cipher_set_iv_t

A function that sets the initialization vector (if necessary) for a secure element cipher operation.

Rationale: The `psa_se_cipher_*` operation in the PSA Cryptographic API has two IV functions: one to set the IV, and one to generate it internally. The generate function is not necessary for the drivers to implement as the PSA Crypto implementation can do the generation using its RNG features.

op_context

A structure that contains the previously set up hardware-specific cipher context

p_iv

A buffer containing the initialization vector

iv_length

The size (in bytes) of the `p_iv` buffer

PSA_SUCCESS

psa_status_t(* typedef psa_status_t(* psa_drv_se_cipher_update_t) (void *op_context, const uint8_t *p_input, size_t input_size, uint8_t *p_output, size_t output_size, size_t *p_output_length) )(void *op_context, const uint8_t *p_input, size_t input_size, uint8_t *p_output, size_t output_size, size_t *p_output_length) psa_drv_se_cipher_update_t

A function that continues a previously started secure element cipher operation.

op_context

A hardware-specific structure for the previously started cipher operation

p_input

A buffer containing the data to be encrypted/decrypted

input_size

The size in bytes of the buffer pointed to by `p_input`

p_output

The caller-allocated buffer where the output will be placed

output_size

The allocated size in bytes of the `p_output` buffer

p_output_length

After completion, will contain the number of bytes placed in the `p_output` buffer

PSA_SUCCESS

psa_status_t(* typedef psa_status_t(* psa_drv_se_cipher_finish_t) (void *op_context, uint8_t *p_output, size_t output_size, size_t *p_output_length) )(void *op_context, uint8_t *p_output, size_t output_size, size_t *p_output_length) psa_drv_se_cipher_finish_t

A function that completes a previously started secure element cipher operation.

op_context

A hardware-specific structure for the previously started cipher operation

p_output

The caller-allocated buffer where the output will be placed

output_size

The allocated size in bytes of the `p_output` buffer

p_output_length

After completion, will contain the number of bytes placed in the `p_output` buffer

PSA_SUCCESS

psa_status_t(* typedef psa_status_t(* psa_drv_se_cipher_abort_t) (void *op_context) )(void *op_context) psa_drv_se_cipher_abort_t

A function that aborts a previously started secure element cipher operation.

op_context

A hardware-specific structure for the previously started cipher operation

psa_status_t(* typedef psa_status_t(* psa_drv_se_cipher_ecb_t) (psa_drv_se_context_t *drv_context, psa_key_slot_number_t key_slot, psa_algorithm_t algorithm, psa_encrypt_or_decrypt_t direction, const uint8_t *p_input, size_t input_size, uint8_t *p_output, size_t output_size) )(psa_drv_se_context_t *drv_context, psa_key_slot_number_t key_slot, psa_algorithm_t algorithm, psa_encrypt_or_decrypt_t direction, const uint8_t *p_input, size_t input_size, uint8_t *p_output, size_t output_size) psa_drv_se_cipher_ecb_t

A function that performs the ECB block mode for secure element cipher operations.

Note: this function should only be used with implementations that do not provide a needed higher-level operation.

drv_context

The driver context structure.

key_slot

The slot of the key to be used for the operation

algorithm

The algorithm to be used in the cipher operation

direction

Indicates whether the operation is an encrypt or decrypt

p_input

A buffer containing the data to be encrypted/decrypted

input_size

The size in bytes of the buffer pointed to by `p_input`

p_output

The caller-allocated buffer where the output will be placed

output_size

The allocated size in bytes of the `p_output` buffer

PSA_SUCCESS

PSA_ERROR_NOT_SUPPORTED

Encryption and Decryption using secure element keys in block modes other than ECB must be done in multiple parts, using the following flow:

- `psa_drv_se_cipher_setup_t`

- `psa_drv_se_cipher_set_iv_t` (optional depending upon block mode)

- `psa_drv_se_cipher_update_t`

- `psa_drv_se_cipher_update_t`

- ...

- `psa_drv_se_cipher_finish_t`

If a previously started secure element Cipher operation needs to be terminated, it should be done so by the `psa_drv_se_cipher_abort_t`. Failure to do so may result in allocated resources not being freed or in other undefined behavior.

In situations where a PSA Cryptographic API implementation is using a block mode not-supported by the underlying hardware or driver, it can construct the block mode itself, while calling the `psa_drv_se_cipher_ecb_t` function for the cipher operations.