Group se_cipher
- group se_cipher
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.Typedefs
-
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)
A function that provides the cipher setup function for a secure element driver.
- Param drv_context
[inout] The driver context structure.
- Param op_context
[inout] A structure that will contain the hardware-specific cipher context.
- Param key_slot
[in] The slot of the key to be used for the operation
- Param algorithm
[in] The algorithm to be used in the cipher operation
- Param direction
[in] Indicates whether the operation is an encrypt or decrypt
- Retval PSA_SUCCESS
- Retval PSA_ERROR_NOT_SUPPORTED
-
typedef psa_status_t (*psa_drv_se_cipher_set_iv_t)(void *op_context, const uint8_t *p_iv, size_t iv_length)
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.- Param op_context
[inout] A structure that contains the previously set up hardware-specific cipher context
- Param p_iv
[in] A buffer containing the initialization vector
- Param iv_length
[in] The size (in bytes) of the
p_iv
buffer- Retval PSA_SUCCESS
-
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)
A function that continues a previously started secure element cipher operation.
- Param op_context
[inout] A hardware-specific structure for the previously started cipher operation
- Param p_input
[in] A buffer containing the data to be encrypted/decrypted
- Param input_size
[in] The size in bytes of the buffer pointed to by
p_input
- Param p_output
[out] The caller-allocated buffer where the output will be placed
- Param output_size
[in] The allocated size in bytes of the
p_output
buffer- Param p_output_length
[out] After completion, will contain the number of bytes placed in the
p_output
buffer- Retval PSA_SUCCESS
-
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)
A function that completes a previously started secure element cipher operation.
- Param op_context
[inout] A hardware-specific structure for the previously started cipher operation
- Param p_output
[out] The caller-allocated buffer where the output will be placed
- Param output_size
[in] The allocated size in bytes of the
p_output
buffer- Param p_output_length
[out] After completion, will contain the number of bytes placed in the
p_output
buffer- Retval PSA_SUCCESS
-
typedef psa_status_t (*psa_drv_se_cipher_abort_t)(void *op_context)
A function that aborts a previously started secure element cipher operation.
- Param op_context
[inout] A hardware-specific structure for the previously started cipher operation
-
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)
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.
- Param drv_context
[inout] The driver context structure.
- Param key_slot
[in] The slot of the key to be used for the operation
- Param algorithm
[in] The algorithm to be used in the cipher operation
- Param direction
[in] Indicates whether the operation is an encrypt or decrypt
- Param p_input
[in] A buffer containing the data to be encrypted/decrypted
- Param input_size
[in] The size in bytes of the buffer pointed to by
p_input
- Param p_output
[out] The caller-allocated buffer where the output will be placed
- Param output_size
[in] The allocated size in bytes of the
p_output
buffer- Retval PSA_SUCCESS
- Retval PSA_ERROR_NOT_SUPPORTED
-
struct psa_drv_se_cipher_t
- #include <crypto_se_driver.h>
A struct containing all of the function pointers needed to implement cipher operations using secure elements.
PSA Crypto API implementations should populate instances of the table as appropriate upon startup or at build time.
If one of the functions is not implemented (such as
psa_drv_se_cipher_ecb_t
), it should be set to NULL.