Platform Security Architecture — cryptography and keystore interface  Working draft
Typedefs | Functions
Symmetric ciphers

Typedefs

typedef struct psa_cipher_operation_s psa_cipher_operation_t
 

Functions

psa_status_t psa_cipher_encrypt_setup (psa_cipher_operation_t *operation, psa_key_slot_t key, psa_algorithm_t alg)
 
psa_status_t psa_cipher_decrypt_setup (psa_cipher_operation_t *operation, psa_key_slot_t key, psa_algorithm_t alg)
 
psa_status_t psa_cipher_generate_iv (psa_cipher_operation_t *operation, unsigned char *iv, size_t iv_size, size_t *iv_length)
 
psa_status_t psa_cipher_set_iv (psa_cipher_operation_t *operation, const unsigned char *iv, size_t iv_length)
 
psa_status_t psa_cipher_update (psa_cipher_operation_t *operation, const uint8_t *input, size_t input_length, unsigned char *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)
 

Detailed Description

Typedef Documentation

◆ psa_cipher_operation_t

typedef struct psa_cipher_operation_s psa_cipher_operation_t

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

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.

Function Documentation

◆ psa_cipher_abort()

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 by any of the following methods:

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_BAD_STATEoperation is not an active cipher operation.
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_TAMPERING_DETECTED

◆ psa_cipher_decrypt_setup()

psa_status_t psa_cipher_decrypt_setup ( psa_cipher_operation_t operation,
psa_key_slot_t  key,
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. Call psa_cipher_decrypt_setup() to specify the algorithm and key. The key remains associated with the operation even if the content of the key slot changes.
  3. Call psa_cipher_update() 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.
  4. Call psa_cipher_update() zero, one or more times, passing a fragment of the message each time.
  5. Call psa_cipher_finish().

The application may call psa_cipher_abort() at any time after the operation has been initialized with psa_cipher_decrypt_setup().

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

Parameters
[out]operationThe operation object to use.
keySlot containing the key to use for the operation.
algThe cipher algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_CIPHER(alg) is true).
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_EMPTY_SLOT
PSA_ERROR_NOT_PERMITTED
PSA_ERROR_INVALID_ARGUMENTkey 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_TAMPERING_DETECTED

◆ psa_cipher_encrypt_setup()

psa_status_t psa_cipher_encrypt_setup ( psa_cipher_operation_t operation,
psa_key_slot_t  key,
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. Call psa_cipher_encrypt_setup() to specify the algorithm and key. The key remains associated with the operation even if the content of the key slot changes.
  3. 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.
  4. Call psa_cipher_update() zero, one or more times, passing a fragment of the message each time.
  5. Call psa_cipher_finish().

The application may call psa_cipher_abort() at any time after the operation has been initialized with psa_cipher_encrypt_setup().

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

Parameters
[out]operationThe operation object to use.
keySlot containing the key to use for the operation.
algThe cipher algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_CIPHER(alg) is true).
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_EMPTY_SLOT
PSA_ERROR_NOT_PERMITTED
PSA_ERROR_INVALID_ARGUMENTkey 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_TAMPERING_DETECTED

◆ psa_cipher_finish()

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, the operation becomes inactive.

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_BAD_STATEThe operation state is not valid (not started, IV required but not set, or already completed).
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_TAMPERING_DETECTED

◆ psa_cipher_generate_iv()

psa_status_t psa_cipher_generate_iv ( psa_cipher_operation_t operation,
unsigned char *  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 becomes inactive.

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 (not started, or IV already 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_TAMPERING_DETECTED

◆ psa_cipher_set_iv()

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

Set the IV for a symmetric encryption or decryption operation.

This function sets the random 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 becomes inactive.

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 (not started, or IV already 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_TAMPERING_DETECTED

◆ psa_cipher_update()

psa_status_t psa_cipher_update ( psa_cipher_operation_t operation,
const uint8_t *  input,
size_t  input_length,
unsigned char *  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 becomes inactive.

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 (not started, IV required but not set, or already completed).
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_TAMPERING_DETECTED