Update documentation references to the AEAD macros
Where a change was necessary, the new documentation was copied from the PSA Crypto API spec exactly, with the exception of PSA_AEAD_TAG_LENGTH, which needed some adjustment. Signed-off-by: Bence Szépkúti <bence.szepkuti@arm.com>
This commit is contained in:
Bence Szépkúti
parent
12116bc3bb
commit
eb1a301321
2 changed files with 129 additions and 49 deletions
|
|
@ -2113,9 +2113,16 @@ psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation);
|
|||
* authentication tag is appended to the
|
||||
* encrypted data.
|
||||
* \param ciphertext_size Size of the \p ciphertext buffer in bytes.
|
||||
* This must be at least
|
||||
* #PSA_AEAD_ENCRYPT_OUTPUT_SIZE(\p alg,
|
||||
* \p plaintext_length).
|
||||
* This must be appropriate for the selected
|
||||
* algorithm and key:
|
||||
* - A sufficient output size is
|
||||
* #PSA_AEAD_ENCRYPT_OUTPUT_SIZE(\c key_type,
|
||||
* \p alg, \p plaintext_length) where
|
||||
* \c key_type is the type of \p key.
|
||||
* - #PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE(\p
|
||||
* plaintext_length) evaluates to the maximum
|
||||
* ciphertext size of any supported AEAD
|
||||
* encryption.
|
||||
* \param[out] ciphertext_length On success, the size of the output
|
||||
* in the \p ciphertext buffer.
|
||||
*
|
||||
|
|
@ -2173,9 +2180,16 @@ psa_status_t psa_aead_encrypt(mbedtls_svc_key_id_t key,
|
|||
* \param ciphertext_length Size of \p ciphertext in bytes.
|
||||
* \param[out] plaintext Output buffer for the decrypted data.
|
||||
* \param plaintext_size Size of the \p plaintext buffer in bytes.
|
||||
* This must be at least
|
||||
* #PSA_AEAD_DECRYPT_OUTPUT_SIZE(\p alg,
|
||||
* \p ciphertext_length).
|
||||
* This must be appropriate for the selected
|
||||
* algorithm and key:
|
||||
* - A sufficient output size is
|
||||
* #PSA_AEAD_DECRYPT_OUTPUT_SIZE(\c key_type,
|
||||
* \p alg, \p ciphertext_length) where
|
||||
* \c key_type is the type of \p key.
|
||||
* - #PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE(\p
|
||||
* ciphertext_length) evaluates to the maximum
|
||||
* plaintext size of any supported AEAD
|
||||
* decryption.
|
||||
* \param[out] plaintext_length On success, the size of the output
|
||||
* in the \p plaintext buffer.
|
||||
*
|
||||
|
|
@ -2612,10 +2626,18 @@ psa_status_t psa_aead_update_ad(psa_aead_operation_t *operation,
|
|||
* \param input_length Size of the \p input buffer in bytes.
|
||||
* \param[out] output Buffer where the output is to be written.
|
||||
* \param output_size Size of the \p output buffer in bytes.
|
||||
* This must be at least
|
||||
* #PSA_AEAD_UPDATE_OUTPUT_SIZE(\c alg,
|
||||
* \p input_length) where \c alg is the
|
||||
* algorithm that is being calculated.
|
||||
* This must be appropriate for the selected
|
||||
* algorithm and key:
|
||||
* - A sufficient output size is
|
||||
* #PSA_AEAD_UPDATE_OUTPUT_SIZE(\c key_type,
|
||||
* \c alg, \p input_length) where
|
||||
* \c key_type is the type of key and \c alg is
|
||||
* the algorithm that were used to set up the
|
||||
* operation.
|
||||
* - #PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE(\p
|
||||
* input_length) evaluates to the maximum
|
||||
* output size of any supported AEAD
|
||||
* algorithm.
|
||||
* \param[out] output_length On success, the number of bytes
|
||||
* that make up the returned output.
|
||||
*
|
||||
|
|
@ -2626,9 +2648,9 @@ psa_status_t psa_aead_update_ad(psa_aead_operation_t *operation,
|
|||
* set, and have lengths set if required by the algorithm).
|
||||
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
|
||||
* The size of the \p output buffer is too small.
|
||||
* You can determine a sufficient buffer size by calling
|
||||
* #PSA_AEAD_UPDATE_OUTPUT_SIZE(\c alg, \p input_length)
|
||||
* where \c alg is the algorithm that is being calculated.
|
||||
* #PSA_AEAD_UPDATE_OUTPUT_SIZE(\c key_type, \c alg, \p input_length) or
|
||||
* #PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE(\p input_length) can be used to
|
||||
* determine the required buffer size.
|
||||
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
||||
* The total length of input to psa_aead_update_ad() so far is
|
||||
* less than the additional data length that was previously
|
||||
|
|
@ -2665,9 +2687,7 @@ psa_status_t psa_aead_update(psa_aead_operation_t *operation,
|
|||
* This function has two output buffers:
|
||||
* - \p ciphertext contains trailing ciphertext that was buffered from
|
||||
* preceding calls to psa_aead_update().
|
||||
* - \p tag contains the authentication tag. Its length is always
|
||||
* #PSA_AEAD_TAG_LENGTH(\c alg) where \c alg is the AEAD algorithm
|
||||
* that the operation performs.
|
||||
* - \p tag contains the authentication tag.
|
||||
*
|
||||
* When this function returns successfuly, the operation becomes inactive.
|
||||
* If this function returns an error status, the operation enters an error
|
||||
|
|
@ -2677,18 +2697,32 @@ psa_status_t psa_aead_update(psa_aead_operation_t *operation,
|
|||
* \param[out] ciphertext Buffer where the last part of the ciphertext
|
||||
* is to be written.
|
||||
* \param ciphertext_size Size of the \p ciphertext buffer in bytes.
|
||||
* This must be at least
|
||||
* #PSA_AEAD_FINISH_OUTPUT_SIZE(\c alg) where
|
||||
* \c alg is the algorithm that is being
|
||||
* calculated.
|
||||
* This must be appropriate for the selected
|
||||
* algorithm and key:
|
||||
* - A sufficient output size is
|
||||
* #PSA_AEAD_FINISH_OUTPUT_SIZE(\c key_type,
|
||||
* \c alg) where \c key_type is the type of key
|
||||
* and \c alg is the algorithm that were used to
|
||||
* set up the operation.
|
||||
* - #PSA_AEAD_FINISH_OUTPUT_MAX_SIZE evaluates to
|
||||
* the maximum output size of any supported AEAD
|
||||
* algorithm.
|
||||
* \param[out] ciphertext_length On success, the number of bytes of
|
||||
* returned ciphertext.
|
||||
* \param[out] tag Buffer where the authentication tag is
|
||||
* to be written.
|
||||
* \param tag_size Size of the \p tag buffer in bytes.
|
||||
* This must be at least
|
||||
* #PSA_AEAD_TAG_LENGTH(\c alg) where \c alg is
|
||||
* the algorithm that is being calculated.
|
||||
* This must be appropriate for the selected
|
||||
* algorithm and key:
|
||||
* - The exact tag size is #PSA_AEAD_TAG_LENGTH(\c
|
||||
* key_type, \c key_bits, \c alg) where
|
||||
* \c key_type and \c key_bits are the type and
|
||||
* bit-size of the key, and \c alg is the
|
||||
* algorithm that were used in the call to
|
||||
* psa_aead_encrypt_setup().
|
||||
* - #PSA_AEAD_TAG_MAX_SIZE evaluates to the
|
||||
* maximum tag size of any supported AEAD
|
||||
* algorithm.
|
||||
* \param[out] tag_length On success, the number of bytes
|
||||
* that make up the returned tag.
|
||||
*
|
||||
|
|
@ -2699,11 +2733,11 @@ psa_status_t psa_aead_update(psa_aead_operation_t *operation,
|
|||
* operation with a nonce set).
|
||||
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
|
||||
* The size of the \p ciphertext or \p tag buffer is too small.
|
||||
* You can determine a sufficient buffer size for \p ciphertext by
|
||||
* calling #PSA_AEAD_FINISH_OUTPUT_SIZE(\c alg)
|
||||
* where \c alg is the algorithm that is being calculated.
|
||||
* You can determine a sufficient buffer size for \p tag by
|
||||
* calling #PSA_AEAD_TAG_LENGTH(\c alg).
|
||||
* #PSA_AEAD_FINISH_OUTPUT_SIZE(\c key_type, \c alg) or
|
||||
* #PSA_AEAD_FINISH_OUTPUT_MAX_SIZE can be used to determine the
|
||||
* required \p ciphertext buffer size. #PSA_AEAD_TAG_LENGTH(\c key_type,
|
||||
* \c key_bits, \c alg) or #PSA_AEAD_TAG_MAX_SIZE can be used to
|
||||
* determine the required \p tag buffer size.
|
||||
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
||||
* The total length of input to psa_aead_update_ad() so far is
|
||||
* less than the additional data length that was previously
|
||||
|
|
@ -2762,10 +2796,15 @@ psa_status_t psa_aead_finish(psa_aead_operation_t *operation,
|
|||
* that could not be processed until the end
|
||||
* of the input.
|
||||
* \param plaintext_size Size of the \p plaintext buffer in bytes.
|
||||
* This must be at least
|
||||
* #PSA_AEAD_VERIFY_OUTPUT_SIZE(\c alg) where
|
||||
* \c alg is the algorithm that is being
|
||||
* calculated.
|
||||
* This must be appropriate for the selected algorithm and key:
|
||||
* - A sufficient output size is
|
||||
* #PSA_AEAD_VERIFY_OUTPUT_SIZE(\c key_type,
|
||||
* \c alg) where \c key_type is the type of key
|
||||
* and \c alg is the algorithm that were used to
|
||||
* set up the operation.
|
||||
* - #PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE evaluates to
|
||||
* the maximum output size of any supported AEAD
|
||||
* algorithm.
|
||||
* \param[out] plaintext_length On success, the number of bytes of
|
||||
* returned plaintext.
|
||||
* \param[in] tag Buffer containing the authentication tag.
|
||||
|
|
@ -2781,9 +2820,9 @@ psa_status_t psa_aead_finish(psa_aead_operation_t *operation,
|
|||
* operation with a nonce set).
|
||||
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
|
||||
* The size of the \p plaintext buffer is too small.
|
||||
* You can determine a sufficient buffer size for \p plaintext by
|
||||
* calling #PSA_AEAD_VERIFY_OUTPUT_SIZE(\c alg)
|
||||
* where \c alg is the algorithm that is being calculated.
|
||||
* #PSA_AEAD_VERIFY_OUTPUT_SIZE(\c key_type, \c alg) or
|
||||
* #PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE can be used to determine the
|
||||
* required buffer size.
|
||||
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
||||
* The total length of input to psa_aead_update_ad() so far is
|
||||
* less than the additional data length that was previously
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue