Symmetric ciphers

Macros

#define PSA_CIPHER_OPERATION_INIT   {0, 0, 0, 0, 0, 0, 0, {0}}
 

Typedefs

typedef struct psa_cipher_operation_s psa_cipher_operation_t
 

Functions

psa_status_t psa_cipher_encrypt (psa_key_handle_t handle, psa_algorithm_t alg, const uint8_t *input, size_t input_length, uint8_t *output, size_t output_size, size_t *output_length)
 
psa_status_t psa_cipher_decrypt (psa_key_handle_t handle, psa_algorithm_t alg, const uint8_t *input, size_t input_length, uint8_t *output, size_t output_size, size_t *output_length)
 
static psa_cipher_operation_t psa_cipher_operation_init (void)
 
psa_status_t psa_cipher_encrypt_setup (psa_cipher_operation_t *operation, psa_key_handle_t handle, psa_algorithm_t alg)
 
psa_status_t psa_cipher_decrypt_setup (psa_cipher_operation_t *operation, psa_key_handle_t handle, psa_algorithm_t alg)
 
psa_status_t psa_cipher_generate_iv (psa_cipher_operation_t *operation, uint8_t *iv, size_t iv_size, size_t *iv_length)
 
psa_status_t psa_cipher_set_iv (psa_cipher_operation_t *operation, const uint8_t *iv, size_t iv_length)
 
psa_status_t psa_cipher_update (psa_cipher_operation_t *operation, const uint8_t *input, size_t input_length, uint8_t *output, size_t output_size, size_t *output_length)
 
psa_status_t psa_cipher_finish (psa_cipher_operation_t *operation, uint8_t *output, size_t output_size, size_t *output_length)
 
psa_status_t psa_cipher_abort (psa_cipher_operation_t *operation)
 

Macro Definition Documentation

#define PSA_CIPHER_OPERATION_INIT   {0, 0, 0, 0, 0, 0, 0, {0}}

This macro returns a suitable initializer for a cipher operation object of type psa_cipher_operation_t.

Definition at line 213 of file crypto_struct.h.

Referenced by psa_cipher_operation_init().

Typedef Documentation

The type of the state data structure for multipart cipher operations.

Before calling any function on a cipher operation object, the application must initialize it by any of the following means:

  • Set the structure to all-bits-zero, for example:
    1 psa_cipher_operation_t operation;
    2 memset(&operation, 0, sizeof(operation));
  • Initialize the structure to logical zero values, for example:
    1 psa_cipher_operation_t operation = {0};
  • Initialize the structure to the initializer PSA_CIPHER_OPERATION_INIT, for example:
    1 psa_cipher_operation_t operation = PSA_CIPHER_OPERATION_INIT;
  • Assign the result of the function psa_cipher_operation_init() to the structure, for example:
    1 psa_cipher_operation_t operation;
    2 operation = psa_cipher_operation_init();

This is an implementation-defined struct. Applications should not make any assumptions about the content of this structure except as directed by the documentation of a specific implementation.

Definition at line 1757 of file crypto.h.

Function Documentation

psa_status_t psa_cipher_abort ( psa_cipher_operation_t operation)

Abort a cipher operation.

Aborting an operation frees all associated resources except for the operation structure itself. Once aborted, the operation object can be reused for another operation by calling psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup() again.

You may call this function any time after the operation object has been initialized as described in psa_cipher_operation_t.

In particular, calling psa_cipher_abort() after the operation has been terminated by a call to psa_cipher_abort() or psa_cipher_finish() is safe and has no effect.

Parameters
[in,out]operationInitialized cipher operation.
Return values
PSA_SUCCESS
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_BAD_STATEThe library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.
psa_status_t psa_cipher_decrypt ( psa_key_handle_t  handle,
psa_algorithm_t  alg,
const uint8_t *  input,
size_t  input_length,
uint8_t *  output,
size_t  output_size,
size_t *  output_length 
)

Decrypt a message using a symmetric cipher.

This function decrypts a message encrypted with a symmetric cipher.

Parameters
handleHandle to the key to use for the operation. It must remain valid until the operation terminates.
algThe cipher algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_CIPHER(alg) is true).
[in]inputBuffer containing the message to decrypt. This consists of the IV followed by the ciphertext proper.
input_lengthSize of the input buffer in bytes.
[out]outputBuffer where the plaintext is to be written.
output_sizeSize of the output buffer in bytes.
[out]output_lengthOn success, the number of bytes that make up the output.
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_INVALID_HANDLE
PSA_ERROR_NOT_PERMITTED
PSA_ERROR_INVALID_ARGUMENThandle is not compatible with alg.
PSA_ERROR_NOT_SUPPORTEDalg is not supported or is not a cipher algorithm.
PSA_ERROR_BUFFER_TOO_SMALL
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_BAD_STATEThe library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.
psa_status_t psa_cipher_decrypt_setup ( psa_cipher_operation_t operation,
psa_key_handle_t  handle,
psa_algorithm_t  alg 
)

Set the key for a multipart symmetric decryption operation.

The sequence of operations to decrypt a message with a symmetric cipher is as follows:

  1. Allocate an operation object which will be passed to all the functions listed here.
  2. Initialize the operation object with one of the methods described in the documentation for psa_cipher_operation_t, e.g. PSA_CIPHER_OPERATION_INIT.
  3. Call psa_cipher_decrypt_setup() to specify the algorithm and key.
  4. Call psa_cipher_set_iv() with the IV (initialization vector) for the decryption. If the IV is prepended to the ciphertext, you can call psa_cipher_update() on a buffer containing the IV followed by the beginning of the message.
  5. Call psa_cipher_update() zero, one or more times, passing a fragment of the message each time.
  6. Call psa_cipher_finish().

If an error occurs at any step after a call to psa_cipher_decrypt_setup(), the operation will need to be reset by a call to psa_cipher_abort(). The application may call psa_cipher_abort() at any time after the operation has been initialized.

After a successful call to psa_cipher_decrypt_setup(), the application must eventually terminate the operation. The following events terminate an operation:

Parameters
[in,out]operationThe operation object to set up. It must have been initialized as per the documentation for psa_cipher_operation_t and not yet in use.
handleHandle to the key to use for the operation. It must remain valid until the operation terminates.
algThe cipher algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_CIPHER(alg) is true).
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_INVALID_HANDLE
PSA_ERROR_NOT_PERMITTED
PSA_ERROR_INVALID_ARGUMENThandle is not compatible with alg.
PSA_ERROR_NOT_SUPPORTEDalg is not supported or is not a cipher algorithm.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_BAD_STATEThe operation state is not valid (it must be inactive).
PSA_ERROR_BAD_STATEThe library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.
psa_status_t psa_cipher_encrypt ( psa_key_handle_t  handle,
psa_algorithm_t  alg,
const uint8_t *  input,
size_t  input_length,
uint8_t *  output,
size_t  output_size,
size_t *  output_length 
)

Encrypt a message using a symmetric cipher.

This function encrypts a message with a random IV (initialization vector). Use the multipart operation interface with a psa_cipher_operation_t object to provide other forms of IV.

Parameters
handleHandle to the key to use for the operation. It must remain valid until the operation terminates.
algThe cipher algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_CIPHER(alg) is true).
[in]inputBuffer containing the message to encrypt.
input_lengthSize of the input buffer in bytes.
[out]outputBuffer where the output is to be written. The output contains the IV followed by the ciphertext proper.
output_sizeSize of the output buffer in bytes.
[out]output_lengthOn success, the number of bytes that make up the output.
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_INVALID_HANDLE
PSA_ERROR_NOT_PERMITTED
PSA_ERROR_INVALID_ARGUMENThandle is not compatible with alg.
PSA_ERROR_NOT_SUPPORTEDalg is not supported or is not a cipher algorithm.
PSA_ERROR_BUFFER_TOO_SMALL
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_BAD_STATEThe library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.
psa_status_t psa_cipher_encrypt_setup ( psa_cipher_operation_t operation,
psa_key_handle_t  handle,
psa_algorithm_t  alg 
)

Set the key for a multipart symmetric encryption operation.

The sequence of operations to encrypt a message with a symmetric cipher is as follows:

  1. Allocate an operation object which will be passed to all the functions listed here.
  2. Initialize the operation object with one of the methods described in the documentation for psa_cipher_operation_t, e.g. PSA_CIPHER_OPERATION_INIT.
  3. Call psa_cipher_encrypt_setup() to specify the algorithm and key.
  4. Call either psa_cipher_generate_iv() or psa_cipher_set_iv() to generate or set the IV (initialization vector). You should use psa_cipher_generate_iv() unless the protocol you are implementing requires a specific IV value.
  5. Call psa_cipher_update() zero, one or more times, passing a fragment of the message each time.
  6. Call psa_cipher_finish().

If an error occurs at any step after a call to psa_cipher_encrypt_setup(), the operation will need to be reset by a call to psa_cipher_abort(). The application may call psa_cipher_abort() at any time after the operation has been initialized.

After a successful call to psa_cipher_encrypt_setup(), the application must eventually terminate the operation. The following events terminate an operation:

Parameters
[in,out]operationThe operation object to set up. It must have been initialized as per the documentation for psa_cipher_operation_t and not yet in use.
handleHandle to the key to use for the operation. It must remain valid until the operation terminates.
algThe cipher algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_CIPHER(alg) is true).
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_INVALID_HANDLE
PSA_ERROR_NOT_PERMITTED
PSA_ERROR_INVALID_ARGUMENThandle is not compatible with alg.
PSA_ERROR_NOT_SUPPORTEDalg is not supported or is not a cipher algorithm.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_BAD_STATEThe operation state is not valid (it must be inactive).
PSA_ERROR_BAD_STATEThe library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.
psa_status_t psa_cipher_finish ( psa_cipher_operation_t operation,
uint8_t *  output,
size_t  output_size,
size_t *  output_length 
)

Finish encrypting or decrypting a message in a cipher operation.

The application must call psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup() before calling this function. The choice of setup function determines whether this function encrypts or decrypts its input.

This function finishes the encryption or decryption of the message formed by concatenating the inputs passed to preceding calls to psa_cipher_update().

When this function returns successfuly, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_cipher_abort().

Parameters
[in,out]operationActive cipher operation.
[out]outputBuffer where the output is to be written.
output_sizeSize of the output buffer in bytes.
[out]output_lengthOn success, the number of bytes that make up the returned output.
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_INVALID_ARGUMENTThe total input size passed to this operation is not valid for this particular algorithm. For example, the algorithm is a based on block cipher and requires a whole number of blocks, but the total input size is not a multiple of the block size.
PSA_ERROR_INVALID_PADDINGThis is a decryption operation for an algorithm that includes padding, and the ciphertext does not contain valid padding.
PSA_ERROR_BAD_STATEThe operation state is not valid (it must be active, with an IV set if required for the algorithm).
PSA_ERROR_BUFFER_TOO_SMALLThe size of the output buffer is too small.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_BAD_STATEThe library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.
psa_status_t psa_cipher_generate_iv ( psa_cipher_operation_t operation,
uint8_t *  iv,
size_t  iv_size,
size_t *  iv_length 
)

Generate an IV for a symmetric encryption operation.

This function generates a random IV (initialization vector), nonce or initial counter value for the encryption operation as appropriate for the chosen algorithm, key type and key size.

The application must call psa_cipher_encrypt_setup() before calling this function.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_cipher_abort().

Parameters
[in,out]operationActive cipher operation.
[out]ivBuffer where the generated IV is to be written.
iv_sizeSize of the iv buffer in bytes.
[out]iv_lengthOn success, the number of bytes of the generated IV.
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_BAD_STATEThe operation state is not valid (it must be active, with no IV set).
PSA_ERROR_BUFFER_TOO_SMALLThe size of the iv buffer is too small.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_BAD_STATEThe library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.
static psa_cipher_operation_t psa_cipher_operation_init ( void  )
static

Return an initial value for a cipher operation object.

psa_status_t psa_cipher_set_iv ( psa_cipher_operation_t operation,
const uint8_t *  iv,
size_t  iv_length 
)

Set the IV for a symmetric encryption or decryption operation.

This function sets the IV (initialization vector), nonce or initial counter value for the encryption or decryption operation.

The application must call psa_cipher_encrypt_setup() before calling this function.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_cipher_abort().

Note
When encrypting, applications should use psa_cipher_generate_iv() instead of this function, unless implementing a protocol that requires a non-random IV.
Parameters
[in,out]operationActive cipher operation.
[in]ivBuffer containing the IV to use.
iv_lengthSize of the IV in bytes.
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_BAD_STATEThe operation state is not valid (it must be an active cipher encrypt operation, with no IV set).
PSA_ERROR_INVALID_ARGUMENTThe size of iv is not acceptable for the chosen algorithm, or the chosen algorithm does not use an IV.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_BAD_STATEThe library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.
psa_status_t psa_cipher_update ( psa_cipher_operation_t operation,
const uint8_t *  input,
size_t  input_length,
uint8_t *  output,
size_t  output_size,
size_t *  output_length 
)

Encrypt or decrypt a message fragment in an active cipher operation.

Before calling this function, you must:

  1. Call either psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup(). The choice of setup function determines whether this function encrypts or decrypts its input.
  2. If the algorithm requires an IV, call psa_cipher_generate_iv() (recommended when encrypting) or psa_cipher_set_iv().

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_cipher_abort().

Parameters
[in,out]operationActive cipher operation.
[in]inputBuffer containing the message fragment to encrypt or decrypt.
input_lengthSize of the input buffer in bytes.
[out]outputBuffer where the output is to be written.
output_sizeSize of the output buffer in bytes.
[out]output_lengthOn success, the number of bytes that make up the returned output.
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_BAD_STATEThe operation state is not valid (it must be active, with an IV set if required for the algorithm).
PSA_ERROR_BUFFER_TOO_SMALLThe size of the output buffer is too small.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_BAD_STATEThe library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.