Symmetric ciphers#

Functions#

psa_cipher_encrypt(mbedtls_svc_key_id_t key, 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.

psa_cipher_decrypt(mbedtls_svc_key_id_t key, 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.

psa_cipher_operation_t

Return an initial value for a cipher operation object.

psa_cipher_encrypt_setup(psa_cipher_operation_t *operation, mbedtls_svc_key_id_t key, psa_algorithm_t alg)

Set the key for a multipart symmetric encryption operation.

psa_cipher_decrypt_setup(psa_cipher_operation_t *operation, mbedtls_svc_key_id_t key, psa_algorithm_t alg)

Set the key for a multipart symmetric decryption operation.

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.

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.

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.

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.

psa_cipher_abort(psa_cipher_operation_t *operation)

Abort a cipher operation.

Function Documentation#

psa_cipher_encrypt#

psa_status_t psa_cipher_encrypt (mbedtls_svc_key_id_t key, 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.

Parameters
N/Akey

Identifier of the key to use for the operation. It must allow the usage PSA_KEY_USAGE_ENCRYPT.

N/Aalg

The cipher algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_CIPHER(alg) is true).

[in]input

Buffer containing the message to encrypt.

N/Ainput_length

Size of the input buffer in bytes.

[out]output

Buffer where the output is to be written. The output contains the IV followed by the ciphertext proper.

N/Aoutput_size

Size of the output buffer in bytes.

[out]output_length

On success, the number of bytes that make up the output.

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.


Definition at line 1632 of file util/third_party/mbedtls/include/psa/crypto.h

psa_cipher_decrypt#

psa_status_t psa_cipher_decrypt (mbedtls_svc_key_id_t key, 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.

Parameters
N/Akey

Identifier of the key to use for the operation. It must remain valid until the operation terminates. It must allow the usage PSA_KEY_USAGE_DECRYPT.

N/Aalg

The cipher algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_CIPHER(alg) is true).

[in]input

Buffer containing the message to decrypt. This consists of the IV followed by the ciphertext proper.

N/Ainput_length

Size of the input buffer in bytes.

[out]output

Buffer where the plaintext is to be written.

N/Aoutput_size

Size of the output buffer in bytes.

[out]output_length

On success, the number of bytes that make up the output.

This function decrypts a message encrypted with a symmetric cipher.


Definition at line 1679 of file util/third_party/mbedtls/include/psa/crypto.h

psa_cipher_operation_init#

static psa_cipher_operation_t psa_cipher_operation_init (void )

Return an initial value for a cipher operation object.

Parameters
N/A

Definition at line 1725 of file util/third_party/mbedtls/include/psa/crypto.h

psa_cipher_encrypt_setup#

psa_status_t psa_cipher_encrypt_setup (psa_cipher_operation_t * operation, mbedtls_svc_key_id_t key, psa_algorithm_t alg)

Set the key for a multipart symmetric encryption operation.

Parameters
[inout]operation

The operation object to set up. It must have been initialized as per the documentation for #psa_cipher_operation_t and not yet in use.

N/Akey

Identifier of the key to use for the operation. It must remain valid until the operation terminates. It must allow the usage PSA_KEY_USAGE_ENCRYPT.

N/Aalg

The cipher algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_CIPHER(alg) is true).

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:


Definition at line 1786 of file util/third_party/mbedtls/include/psa/crypto.h

psa_cipher_decrypt_setup#

psa_status_t psa_cipher_decrypt_setup (psa_cipher_operation_t * operation, mbedtls_svc_key_id_t key, psa_algorithm_t alg)

Set the key for a multipart symmetric decryption operation.

Parameters
[inout]operation

The operation object to set up. It must have been initialized as per the documentation for #psa_cipher_operation_t and not yet in use.

N/Akey

Identifier of the key to use for the operation. It must remain valid until the operation terminates. It must allow the usage PSA_KEY_USAGE_DECRYPT.

N/Aalg

The cipher algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_CIPHER(alg) is true).

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:


Definition at line 1849 of file util/third_party/mbedtls/include/psa/crypto.h

psa_cipher_generate_iv#

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.

Parameters
[inout]operation

Active cipher operation.

[out]iv

Buffer where the generated IV is to be written.

N/Aiv_size

Size of the iv buffer in bytes.

[out]iv_length

On success, the number of bytes of the generated IV.

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().


Definition at line 1887 of file util/third_party/mbedtls/include/psa/crypto.h

psa_cipher_set_iv#

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.

Parameters
[inout]operation

Active cipher operation.

[in]iv

Buffer containing the IV to use.

N/Aiv_length

Size of the IV in bytes.

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.


Definition at line 1928 of file util/third_party/mbedtls/include/psa/crypto.h

psa_cipher_update#

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.

Parameters
[inout]operation

Active cipher operation.

[in]input

Buffer containing the message fragment to encrypt or decrypt.

N/Ainput_length

Size of the input buffer in bytes.

[out]output

Buffer where the output is to be written.

N/Aoutput_size

Size of the output buffer in bytes.

[out]output_length

On success, the number of bytes that make up the returned output.

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().


Definition at line 1969 of file util/third_party/mbedtls/include/psa/crypto.h

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.

Parameters
[inout]operation

Active cipher operation.

[out]output

Buffer where the output is to be written.

N/Aoutput_size

Size of the output buffer in bytes.

[out]output_length

On success, the number of bytes that make up the returned output.

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 successfully, 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().


Definition at line 2021 of file util/third_party/mbedtls/include/psa/crypto.h

psa_cipher_abort#

psa_status_t psa_cipher_abort (psa_cipher_operation_t * operation)

Abort a cipher operation.

Parameters
[inout]operation

Initialized 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.


Definition at line 2051 of file util/third_party/mbedtls/include/psa/crypto.h