Kenji Arai / mbed-os_TYBLE16

Dependents:   TYBLE16_simple_data_logger TYBLE16_MP3_Air

Embed: (wiki syntax)

« Back to documentation index

Hardware-Accelerated Block Ciphers

Hardware-Accelerated Block Ciphers

Encryption and Decryption using hardware-acceleration in block modes other than ECB must be done in multiple parts, using the following flow:

  • `psa_drv_accel_ciphersetup_t`
  • `psa_drv_accel_cipher_set_iv_t` (optional depending upon block mode)
  • `psa_drv_accel_cipher_update_t`
  • `psa_drv_accel_cipher_update_t`
  • ...
More...

Typedefs

typedef struct
psa_drv_accel_cipher_context_s 
psa_drv_accel_cipher_context_t
 The hardware-accelerator-specific cipher context structure.
typedef psa_status_t(* psa_drv_accel_cipher_setup_t )(psa_drv_accel_cipher_context_t *p_context, psa_encrypt_or_decrypt_t direction, const uint8_t *p_key_data, size_t key_data_size)
 The function prototype for the setup operation of hardware-accelerated block cipher operations.
typedef psa_status_t(* psa_drv_accel_cipher_set_iv_t )(psa_drv_accel_cipher_context_t *p_context, const uint8_t *p_iv, size_t iv_length)
 The function prototype for the set initialization vector operation of hardware-accelerated block cipher operations Functions that implement this prototype should be named in the following convention: ~~~~~~~~~~~~~{.c} psa_drv_accel_cipher_set_iv_<CIPHER_NAME>_<MODE> ~~~~~~~~~~~~~ Where

  • `CIPHER_NAME` is the name of the underlying block cipher (i.e.

typedef psa_status_t(* psa_drv_accel_cipher_update_t )(psa_drv_accel_cipher_context_t *p_context, const uint8_t *p_input, size_t input_size, uint8_t *p_output, size_t output_size, size_t *p_output_length)
 The function prototype for the update operation of hardware-accelerated block cipher operations.
typedef psa_status_t(* psa_drv_accel_cipher_finish_t )(psa_drv_accel_cipher_context_t *p_context, uint8_t *p_output, size_t output_size, size_t *p_output_length)
 The function prototype for the finish operation of hardware-accelerated block cipher operations.
typedef psa_status_t(* psa_drv_accel_cipher_abort_t )(psa_drv_accel_cipher_context_t *p_context)
 The function prototype for the abort operation of hardware-accelerated block cipher operations.

Detailed Description

Encryption and Decryption using hardware-acceleration in block modes other than ECB must be done in multiple parts, using the following flow:

  • `psa_drv_accel_ciphersetup_t`
  • `psa_drv_accel_cipher_set_iv_t` (optional depending upon block mode)
  • `psa_drv_accel_cipher_update_t`
  • `psa_drv_accel_cipher_update_t`
  • ...
  • `psa_drv_accel_cipher_finish_t`

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


Typedef Documentation

The function prototype for the abort operation of hardware-accelerated block cipher operations.

Functions that implement the following prototype should be named in the following convention: ~~~~~~~~~~~~~{.c} psa_drv_accel_cipher_abort_<CIPHER_NAME>_<MODE> ~~~~~~~~~~~~~ Where

  • `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES)
  • `MODE` is the block mode of the cipher operation (i.e. CBC or CTR)
Parameters:
[in,out]p_contextA hardware-specific structure for the previously started cipher operation
Return values:
PSA_SUCCESS

Definition at line 504 of file crypto_accel_driver.h.

typedef struct psa_drv_accel_cipher_context_s psa_drv_accel_cipher_context_t

The hardware-accelerator-specific cipher context structure.

The contents of this structure are implementation dependent and are therefore not described here.

Definition at line 372 of file crypto_accel_driver.h.

typedef psa_status_t(* psa_drv_accel_cipher_finish_t)(psa_drv_accel_cipher_context_t *p_context, uint8_t *p_output, size_t output_size, size_t *p_output_length)

The function prototype for the finish operation of hardware-accelerated block cipher operations.

Functions that implement this prototype should be named in the following convention: ~~~~~~~~~~~~~{.c} psa_drv_accel_cipher_finish_<CIPHER_NAME>_<MODE> ~~~~~~~~~~~~~ Where

  • `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES)
  • `MODE` is the block mode of the cipher operation (i.e. CBC or CTR)
Parameters:
[in,out]p_contextA hardware-specific structure for the previously started cipher operation
[out]p_outputA caller-allocated buffer where the generated output will be placed
[in]output_sizeThe size in bytes of the `p_output` buffer
[out]p_output_lengthAfter completion, will contain the number of bytes placed in the `p_output` buffer
Return values:
PSA_SUCCESS

Definition at line 482 of file crypto_accel_driver.h.

typedef psa_status_t(* psa_drv_accel_cipher_set_iv_t)(psa_drv_accel_cipher_context_t *p_context, const uint8_t *p_iv, size_t iv_length)

The function prototype for the set initialization vector operation of hardware-accelerated block cipher operations Functions that implement this prototype should be named in the following convention: ~~~~~~~~~~~~~{.c} psa_drv_accel_cipher_set_iv_<CIPHER_NAME>_<MODE> ~~~~~~~~~~~~~ Where

  • `CIPHER_NAME` is the name of the underlying block cipher (i.e.

AES or DES)

  • `MODE` is the block mode of the cipher operation (i.e. CBC or CTR)
Parameters:
[in,out]p_contextA structure that contains the previously setup hardware-specific cipher context
[in]p_ivA buffer containing the initialization vecotr
[in]iv_lengthThe size in bytes of the contents of `p_iv`
Return values:
PSA_SUCCESS

Definition at line 424 of file crypto_accel_driver.h.

typedef psa_status_t(* psa_drv_accel_cipher_setup_t)(psa_drv_accel_cipher_context_t *p_context, psa_encrypt_or_decrypt_t direction, const uint8_t *p_key_data, size_t key_data_size)

The function prototype for the setup operation of hardware-accelerated block cipher operations.

Functions that implement this prototype should be named in the following conventions: ~~~~~~~~~~~~~{.c} psa_drv_accel_cipher_setup_<CIPHER_NAME>_<MODE> ~~~~~~~~~~~~~ Where

  • `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES)
  • `MODE` is the block mode of the cipher operation (i.e. CBC or CTR)

For stream ciphers: ~~~~~~~~~~~~~{.c} psa_drv_accel_cipher_setup_<CIPHER_NAME> ~~~~~~~~~~~~~ Where `CIPHER_NAME` is the name of a stream cipher (i.e. RC4)

Parameters:
[in,out]p_contextA structure that will contain the hardware-specific cipher context
[in]directionIndicates if the operation is an encrypt or a decrypt
[in]p_key_dataA buffer containing the cleartext key material to be used in the operation
[in]key_data_sizeThe size in bytes of the key material
Return values:
PSA_SUCCESS

Definition at line 401 of file crypto_accel_driver.h.

typedef psa_status_t(* psa_drv_accel_cipher_update_t)(psa_drv_accel_cipher_context_t *p_context, const uint8_t *p_input, size_t input_size, uint8_t *p_output, size_t output_size, size_t *p_output_length)

The function prototype for the update operation of hardware-accelerated block cipher operations.

Functions that implement this prototype should be named in the following convention: ~~~~~~~~~~~~~{.c} psa_drv_accel_cipher_update_<CIPHER_NAME>_<MODE> ~~~~~~~~~~~~~ Where

  • `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES)
  • `MODE` is the block mode of the cipher operation (i.e. CBC or CTR)
Parameters:
[in,out]p_contextA hardware-specific structure for the previously started cipher operation
[in]p_inputA buffer containing the data to be encrypted or decrypted
[in]input_sizeThe size in bytes of the `p_input` buffer
[out]p_outputA caller-allocated buffer where the generated output will be placed
[in]output_sizeThe size in bytes of the `p_output` buffer
[out]p_output_lengthAfter completion, will contain the number of bytes placed in the `p_output` buffer
Return values:
PSA_SUCCESS

Definition at line 453 of file crypto_accel_driver.h.