NCBI C++ ToolKit
Functions
psa_crypto_aead.h File Reference
#include <psa/crypto.h>
+ Include dependency graph for psa_crypto_aead.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Go to the SVN repository for this file.

Functions

psa_status_t mbedtls_psa_aead_encrypt (const psa_key_attributes_t *attributes, const uint8_t *key_buffer, size_t key_buffer_size, psa_algorithm_t alg, const uint8_t *nonce, size_t nonce_length, const uint8_t *additional_data, size_t additional_data_length, const uint8_t *plaintext, size_t plaintext_length, uint8_t *ciphertext, size_t ciphertext_size, size_t *ciphertext_length)
 Process an authenticated encryption operation. More...
 
psa_status_t mbedtls_psa_aead_decrypt (const psa_key_attributes_t *attributes, const uint8_t *key_buffer, size_t key_buffer_size, psa_algorithm_t alg, const uint8_t *nonce, size_t nonce_length, const uint8_t *additional_data, size_t additional_data_length, const uint8_t *ciphertext, size_t ciphertext_length, uint8_t *plaintext, size_t plaintext_size, size_t *plaintext_length)
 Process an authenticated decryption operation. More...
 
psa_status_t mbedtls_psa_aead_encrypt_setup (mbedtls_psa_aead_operation_t *operation, const psa_key_attributes_t *attributes, const uint8_t *key_buffer, size_t key_buffer_size, psa_algorithm_t alg)
 Set the key for a multipart authenticated encryption operation. More...
 
psa_status_t mbedtls_psa_aead_decrypt_setup (mbedtls_psa_aead_operation_t *operation, const psa_key_attributes_t *attributes, const uint8_t *key_buffer, size_t key_buffer_size, psa_algorithm_t alg)
 Set the key for a multipart authenticated decryption operation. More...
 
psa_status_t mbedtls_psa_aead_set_nonce (mbedtls_psa_aead_operation_t *operation, const uint8_t *nonce, size_t nonce_length)
 Set the nonce for an authenticated encryption or decryption operation. More...
 
psa_status_t mbedtls_psa_aead_set_lengths (mbedtls_psa_aead_operation_t *operation, size_t ad_length, size_t plaintext_length)
 Declare the lengths of the message and additional data for AEAD. More...
 
psa_status_t mbedtls_psa_aead_update_ad (mbedtls_psa_aead_operation_t *operation, const uint8_t *input, size_t input_length)
 Pass additional data to an active AEAD operation. More...
 
psa_status_t mbedtls_psa_aead_update (mbedtls_psa_aead_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 AEAD operation. More...
 
psa_status_t mbedtls_psa_aead_finish (mbedtls_psa_aead_operation_t *operation, uint8_t *ciphertext, size_t ciphertext_size, size_t *ciphertext_length, uint8_t *tag, size_t tag_size, size_t *tag_length)
 Finish encrypting a message in an AEAD operation. More...
 
psa_status_t mbedtls_psa_aead_abort (mbedtls_psa_aead_operation_t *operation)
 Abort an AEAD operation. More...
 

Function Documentation

◆ mbedtls_psa_aead_abort()

psa_status_t mbedtls_psa_aead_abort ( mbedtls_psa_aead_operation_t operation)

Abort an AEAD operation.

Note
The signature of this function is that of a PSA driver aead_abort entry point. This function behaves as an aead_abort entry point as defined in the PSA driver interface specification for transparent drivers.

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 the PSA core by it calling mbedtls_psa_aead_encrypt_setup() or mbedtls_psa_aead_decrypt_setup() again.

The PSA core may call this function any time after the operation object has been initialized as described in mbedtls_psa_aead_operation_t.

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

Parameters
[in,out]operationInitialized AEAD operation.
Return values
PSA_SUCCESSSuccess.

◆ mbedtls_psa_aead_decrypt()

psa_status_t mbedtls_psa_aead_decrypt ( const psa_key_attributes_t attributes,
const uint8_t key_buffer,
size_t  key_buffer_size,
psa_algorithm_t  alg,
const uint8_t nonce,
size_t  nonce_length,
const uint8_t additional_data,
size_t  additional_data_length,
const uint8_t ciphertext,
size_t  ciphertext_length,
uint8_t plaintext,
size_t  plaintext_size,
size_t *  plaintext_length 
)

Process an authenticated decryption operation.

Note
The signature of this function is that of a PSA driver aead_decrypt entry point. This function behaves as an aead_decrypt entry point as defined in the PSA driver interface specification for transparent drivers.
Parameters
[in]attributesThe attributes of the key to use for the operation.
[in]key_bufferThe buffer containing the key context.
key_buffer_sizeSize of the key_buffer buffer in bytes.
algThe AEAD algorithm to compute.
[in]nonceNonce or IV to use.
nonce_lengthSize of the nonce buffer in bytes. This must be appropriate for the selected algorithm. The default nonce size is PSA_AEAD_NONCE_LENGTH(key_type, alg) where key_type is the type of key.
[in]additional_dataAdditional data that has been authenticated but not encrypted.
additional_data_lengthSize of additional_data in bytes.
[in]ciphertextData that has been authenticated and encrypted. For algorithms where the encrypted data and the authentication tag are defined as separate inputs, the buffer contains encrypted data followed by the authentication tag.
ciphertext_lengthSize of ciphertext in bytes.
[out]plaintextOutput buffer for the decrypted data.
plaintext_sizeSize of the plaintext buffer in bytes. This must be appropriate for the selected algorithm and key:
  • A sufficient output size is PSA_AEAD_DECRYPT_OUTPUT_SIZE(key_type, alg, ciphertext_length) where key_type is the type of key.
  • PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE( ciphertext_length) evaluates to the maximum plaintext size of any supported AEAD decryption.
[out]plaintext_lengthOn success, the size of the output in the plaintext buffer.
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_INVALID_SIGNATUREThe cipher is not authentic.
PSA_ERROR_NOT_SUPPORTEDalg is not supported.
PSA_ERROR_INSUFFICIENT_MEMORY\emptydescription
PSA_ERROR_BUFFER_TOO_SMALLplaintext_size is too small.
PSA_ERROR_CORRUPTION_DETECTED\emptydescription

◆ mbedtls_psa_aead_decrypt_setup()

psa_status_t mbedtls_psa_aead_decrypt_setup ( mbedtls_psa_aead_operation_t operation,
const psa_key_attributes_t attributes,
const uint8_t key_buffer,
size_t  key_buffer_size,
psa_algorithm_t  alg 
)

Set the key for a multipart authenticated decryption operation.

Note
The signature of this function is that of a PSA driver aead_decrypt_setup entry point. This function behaves as an aead_decrypt_setup entry point as defined in the PSA driver interface specification for transparent drivers.

If an error occurs at any step after a call to mbedtls_psa_aead_decrypt_setup(), the PSA core resets the operation by a call to mbedtls_psa_aead_abort(). The PSA core may call mbedtls_psa_aead_abort() at any time after the operation has been initialized, and is required to when the operation is no longer needed.

Parameters
[in,out]operationThe operation object to set up. It must have been initialized as per the documentation for mbedtls_psa_aead_operation_t and not yet in use.
[in]attributesThe attributes of the key to use for the operation.
[in]key_bufferThe buffer containing the key context.
key_buffer_sizeSize of the key_buffer buffer in bytes. It must be consistent with the size in bits recorded in attributes.
algThe AEAD algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_AEAD(alg) is true).
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_INVALID_ARGUMENTAn invalid block length was supplied.
PSA_ERROR_NOT_SUPPORTEDalg is not supported.
PSA_ERROR_INSUFFICIENT_MEMORYFailed to allocate memory for key material

◆ mbedtls_psa_aead_encrypt()

psa_status_t mbedtls_psa_aead_encrypt ( const psa_key_attributes_t attributes,
const uint8_t key_buffer,
size_t  key_buffer_size,
psa_algorithm_t  alg,
const uint8_t nonce,
size_t  nonce_length,
const uint8_t additional_data,
size_t  additional_data_length,
const uint8_t plaintext,
size_t  plaintext_length,
uint8_t ciphertext,
size_t  ciphertext_size,
size_t *  ciphertext_length 
)

Process an authenticated encryption operation.

Note
The signature of this function is that of a PSA driver aead_encrypt entry point. This function behaves as an aead_encrypt entry point as defined in the PSA driver interface specification for transparent drivers.
Parameters
[in]attributesThe attributes of the key to use for the operation.
[in]key_bufferThe buffer containing the key context.
key_buffer_sizeSize of the key_buffer buffer in bytes.
algThe AEAD algorithm to compute.
[in]nonceNonce or IV to use.
nonce_lengthSize of the nonce buffer in bytes. This must be appropriate for the selected algorithm. The default nonce size is PSA_AEAD_NONCE_LENGTH(key_type, alg) where key_type is the type of key.
[in]additional_dataAdditional data that will be authenticated but not encrypted.
additional_data_lengthSize of additional_data in bytes.
[in]plaintextData that will be authenticated and encrypted.
plaintext_lengthSize of plaintext in bytes.
[out]ciphertextOutput buffer for the authenticated and encrypted data. The additional data is not part of this output. For algorithms where the encrypted data and the authentication tag are defined as separate outputs, the authentication tag is appended to the encrypted data.
ciphertext_sizeSize of the ciphertext buffer in bytes. This must be appropriate for the selected algorithm and key:
  • A sufficient output size is PSA_AEAD_ENCRYPT_OUTPUT_SIZE(key_type, alg, plaintext_length) where key_type is the type of key.
  • PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE( plaintext_length) evaluates to the maximum ciphertext size of any supported AEAD encryption.
[out]ciphertext_lengthOn success, the size of the output in the ciphertext buffer.
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_NOT_SUPPORTEDalg is not supported.
PSA_ERROR_INSUFFICIENT_MEMORY\emptydescription
PSA_ERROR_BUFFER_TOO_SMALLciphertext_size is too small.
PSA_ERROR_CORRUPTION_DETECTED\emptydescription

◆ mbedtls_psa_aead_encrypt_setup()

psa_status_t mbedtls_psa_aead_encrypt_setup ( mbedtls_psa_aead_operation_t operation,
const psa_key_attributes_t attributes,
const uint8_t key_buffer,
size_t  key_buffer_size,
psa_algorithm_t  alg 
)

Set the key for a multipart authenticated encryption operation.

Note
The signature of this function is that of a PSA driver aead_encrypt_setup entry point. This function behaves as an aead_encrypt_setup entry point as defined in the PSA driver interface specification for transparent drivers.

If an error occurs at any step after a call to mbedtls_psa_aead_encrypt_setup(), the operation is reset by the PSA core by a call to mbedtls_psa_aead_abort(). The PSA core may call mbedtls_psa_aead_abort() at any time after the operation has been initialized, and is required to when the operation is no longer needed.

Parameters
[in,out]operationThe operation object to set up. It must have been initialized as per the documentation for mbedtls_psa_aead_operation_t and not yet in use.
[in]attributesThe attributes of the key to use for the operation.
[in]key_bufferThe buffer containing the key context.
key_buffer_sizeSize of the key_buffer buffer in bytes. It must be consistent with the size in bits recorded in attributes.
algThe AEAD algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_AEAD(alg) is true).
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_INVALID_ARGUMENTAn invalid block length was supplied.
PSA_ERROR_NOT_SUPPORTEDalg is not supported.
PSA_ERROR_INSUFFICIENT_MEMORYFailed to allocate memory for key material

◆ mbedtls_psa_aead_finish()

psa_status_t mbedtls_psa_aead_finish ( mbedtls_psa_aead_operation_t operation,
uint8_t ciphertext,
size_t  ciphertext_size,
size_t *  ciphertext_length,
uint8_t tag,
size_t  tag_size,
size_t *  tag_length 
)

Finish encrypting a message in an AEAD operation.

Note
The signature of this function is that of a PSA driver aead_finish entry point. This function behaves as an aead_finish entry point as defined in the PSA driver interface specification for transparent drivers.

The operation must have been set up by the PSA core with mbedtls_psa_aead_encrypt_setup().

This function finishes the authentication of the additional data formed by concatenating the inputs passed to preceding calls to mbedtls_psa_aead_update_ad() with the plaintext formed by concatenating the inputs passed to preceding calls to mbedtls_psa_aead_update().

This function has two output buffers:

  • ciphertext contains trailing ciphertext that was buffered from preceding calls to mbedtls_psa_aead_update().
  • tag contains the authentication tag.

Whether or not this function returns successfully, the PSA core subsequently calls mbedtls_psa_aead_abort() to deactivate the operation.

Parameters
[in,out]operationActive AEAD operation.
[out]ciphertextBuffer where the last part of the ciphertext is to be written.
ciphertext_sizeSize of the ciphertext buffer in bytes. This must be appropriate for the selected algorithm and key:
[out]ciphertext_lengthOn success, the number of bytes of returned ciphertext.
[out]tagBuffer where the authentication tag is to be written.
tag_sizeSize of the tag buffer in bytes. This must be appropriate for the selected algorithm and key:
[out]tag_lengthOn success, the number of bytes that make up the returned tag.
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_BUFFER_TOO_SMALLThe size of the tag buffer is too small. PSA_AEAD_TAG_LENGTH(key_type, key_bits, alg) or PSA_AEAD_TAG_MAX_SIZE can be used to determine the required tag buffer size.

◆ mbedtls_psa_aead_set_lengths()

psa_status_t mbedtls_psa_aead_set_lengths ( mbedtls_psa_aead_operation_t operation,
size_t  ad_length,
size_t  plaintext_length 
)

Declare the lengths of the message and additional data for AEAD.

Note
The signature of this function is that of a PSA driver aead_set_lengths entry point. This function behaves as an aead_set_lengths entry point as defined in the PSA driver interface specification for transparent drivers.

The PSA core calls this function before calling mbedtls_psa_aead_update_ad() or mbedtls_psa_aead_update() if the algorithm for the operation requires it. If the algorithm does not require it, calling this function is optional, but if this function is called then the implementation must enforce the lengths.

The PSA core may call this function before or after setting the nonce with mbedtls_psa_aead_set_nonce().

  • For PSA_ALG_CCM, calling this function is required.
  • For the other AEAD algorithms defined in this specification, calling this function is not required.

If this function returns an error status, the PSA core calls mbedtls_psa_aead_abort().

Parameters
[in,out]operationActive AEAD operation.
ad_lengthSize of the non-encrypted additional authenticated data in bytes.
plaintext_lengthSize of the plaintext to encrypt in bytes.
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_INVALID_ARGUMENTAt least one of the lengths is not acceptable for the chosen algorithm.
PSA_ERROR_NOT_SUPPORTEDAlgorithm previously set is not supported in this configuration of the library.

◆ mbedtls_psa_aead_set_nonce()

psa_status_t mbedtls_psa_aead_set_nonce ( mbedtls_psa_aead_operation_t operation,
const uint8_t nonce,
size_t  nonce_length 
)

Set the nonce for an authenticated encryption or decryption operation.

Note
The signature of this function is that of a PSA driver aead_set_nonce entry point. This function behaves as an aead_set_nonce entry point as defined in the PSA driver interface specification for transparent drivers.

This function sets the nonce for the authenticated encryption or decryption operation.

The PSA core calls mbedtls_psa_aead_encrypt_setup() or mbedtls_psa_aead_decrypt_setup() before calling this function.

If this function returns an error status, the PSA core will call mbedtls_psa_aead_abort().

Parameters
[in,out]operationActive AEAD operation.
[in]nonceBuffer containing the nonce to use.
nonce_lengthSize of the nonce in bytes.
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_INVALID_ARGUMENTThe size of nonce is not acceptable for the chosen algorithm.
PSA_ERROR_NOT_SUPPORTEDAlgorithm previously set is not supported in this configuration of the library.

◆ mbedtls_psa_aead_update()

psa_status_t mbedtls_psa_aead_update ( mbedtls_psa_aead_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 AEAD operation.

Note
The signature of this function is that of a PSA driver aead_update entry point. This function behaves as an aead_update entry point as defined in the PSA driver interface specification for transparent drivers.

Before calling this function, the PSA core will: 1. Call either mbedtls_psa_aead_encrypt_setup() or mbedtls_psa_aead_decrypt_setup(). The choice of setup function determines whether this function encrypts or decrypts its input. 2. Set the nonce with mbedtls_psa_aead_set_nonce(). 3. Call mbedtls_psa_aead_update_ad() to pass all the additional data.

If this function returns an error status, the PSA core will call mbedtls_psa_aead_abort().

This function does not require the input to be aligned to any particular block boundary. If the implementation can only process a whole block at a time, it must consume all the input provided, but it may delay the end of the corresponding output until a subsequent call to mbedtls_psa_aead_update(), mbedtls_psa_aead_finish() provides sufficient input. The amount of data that can be delayed in this way is bounded by PSA_AEAD_UPDATE_OUTPUT_SIZE.

Parameters
[in,out]operationActive AEAD 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. This must be appropriate for the selected algorithm and key:
  • A sufficient output size is PSA_AEAD_UPDATE_OUTPUT_SIZE(key_type, alg, input_length) where key_type is the type of key and alg is the algorithm that were used to set up the operation.
  • PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE(input_length) evaluates to the maximum output size of any supported AEAD algorithm.
[out]output_lengthOn success, the number of bytes that make up the returned output.
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_BUFFER_TOO_SMALLThe size of the output buffer is too small. PSA_AEAD_UPDATE_OUTPUT_SIZE(key_type, alg, input_length) or PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE(input_length) can be used to determine the required buffer size.

◆ mbedtls_psa_aead_update_ad()

psa_status_t mbedtls_psa_aead_update_ad ( mbedtls_psa_aead_operation_t operation,
const uint8_t input,
size_t  input_length 
)

Pass additional data to an active AEAD operation.

Note
The signature of this function is that of a PSA driver aead_update_ad entry point. This function behaves as an aead_update_ad entry point as defined in the PSA driver interface specification for transparent drivers.

Additional data is authenticated, but not encrypted.

The PSA core can call this function multiple times to pass successive fragments of the additional data. It will not call this function after passing data to encrypt or decrypt with mbedtls_psa_aead_update().

Before calling this function, the PSA core will: 1. Call either mbedtls_psa_aead_encrypt_setup() or mbedtls_psa_aead_decrypt_setup(). 2. Set the nonce with mbedtls_psa_aead_set_nonce().

If this function returns an error status, the PSA core will call mbedtls_psa_aead_abort().

Parameters
[in,out]operationActive AEAD operation.
[in]inputBuffer containing the fragment of additional data.
input_lengthSize of the input buffer in bytes.
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_NOT_SUPPORTEDAlgorithm previously set is not supported in this configuration of the library.
Modified on Thu Jul 18 15:59:48 2024 by modify_doxy.py rev. 669887