Hardware-Accelerated Block Ciphers

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.

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. Functions that implement this prototype should be named in the following conventions:
 
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:
 
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.
 

Typedef Documentation

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.

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.