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>
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 81e1f28..98de335 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -2113,9 +2113,16 @@
* 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 @@
* \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 @@
* \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 @@
* 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 @@
* 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 @@
* \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 @@
* 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 @@
* 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 @@
* 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
diff --git a/include/psa/crypto_sizes.h b/include/psa/crypto_sizes.h
index 10151c6..e4c5a36 100644
--- a/include/psa/crypto_sizes.h
+++ b/include/psa/crypto_sizes.h
@@ -117,17 +117,26 @@
*/
#define PSA_MAC_MAX_SIZE PSA_HASH_MAX_SIZE
-/** The tag size for an AEAD algorithm, in bytes.
+/** The length of a tag for an AEAD algorithm, in bytes.
*
+ * This macro can be used to allocate a buffer of sufficient size to store the
+ * tag output from psa_aead_finish().
+ *
+ * See also #PSA_AEAD_TAG_MAX_SIZE.
+ *
+ * \param key_type The type of the AEAD key.
+ * \param key_bits The size of the AEAD key in bits.
* \param alg An AEAD algorithm
* (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_AEAD(\p alg) is true).
*
- * \return The tag size for the specified algorithm.
+ * \return The tag size for the specified algorithm and key.
* If the AEAD algorithm does not have an identified
* tag that can be distinguished from the rest of
* the ciphertext, return 0.
- * If the AEAD algorithm is not recognized, return 0.
+ * If the key type or AEAD algorithm is not
+ * recognized, or the parameters are incompatible,
+ * return 0.
*/
#define PSA_AEAD_TAG_LENGTH(key_type, key_bits, alg) \
(PSA_AEAD_NONCE_LENGTH(key_type, alg) ? \
@@ -136,7 +145,7 @@
/** The maximum tag size for all supported AEAD algorithms, in bytes.
*
- * See also #PSA_AEAD_TAG_LENGTH(\p alg).
+ * See also #PSA_AEAD_TAG_LENGTH(\p key_type, \p key_bits, \p alg).
*/
#define PSA_AEAD_TAG_MAX_SIZE 16
@@ -241,10 +250,14 @@
* insufficient buffer size. Depending on the algorithm, the actual size of
* the ciphertext may be smaller.
*
+ * See also #PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE(\p plaintext_length).
+ *
* \warning This macro may evaluate its arguments multiple times or
* zero times, so you should not pass arguments that contain
* side effects.
*
+ * \param key_type A symmetric key type that is
+ * compatible with algorithm \p alg.
* \param alg An AEAD algorithm
* (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_AEAD(\p alg) is true).
@@ -252,7 +265,9 @@
*
* \return The AEAD ciphertext size for the specified
* algorithm.
- * If the AEAD algorithm is not recognized, return 0.
+ * If the key type or AEAD algorithm is not
+ * recognized, or the parameters are incompatible,
+ * return 0.
*/
#define PSA_AEAD_ENCRYPT_OUTPUT_SIZE(key_type, alg, plaintext_length) \
(PSA_AEAD_NONCE_LENGTH(key_type, alg) ? \
@@ -268,7 +283,8 @@
* \note This macro returns a compile-time constant if its arguments are
* compile-time constants.
*
- * See also #PSA_AEAD_ENCRYPT_OUTPUT_SIZE(\p alg, \p plaintext_length).
+ * See also #PSA_AEAD_ENCRYPT_OUTPUT_SIZE(\p key_type, \p alg,
+ * \p plaintext_length).
*
* \param plaintext_length Size of the plaintext in bytes.
*
@@ -287,10 +303,14 @@
* insufficient buffer size. Depending on the algorithm, the actual size of
* the plaintext may be smaller.
*
+ * See also #PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE(\p ciphertext_length).
+ *
* \warning This macro may evaluate its arguments multiple times or
* zero times, so you should not pass arguments that contain
* side effects.
*
+ * \param key_type A symmetric key type that is
+ * compatible with algorithm \p alg.
* \param alg An AEAD algorithm
* (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_AEAD(\p alg) is true).
@@ -298,7 +318,9 @@
*
* \return The AEAD ciphertext size for the specified
* algorithm.
- * If the AEAD algorithm is not recognized, return 0.
+ * If the key type or AEAD algorithm is not
+ * recognized, or the parameters are incompatible,
+ * return 0.
*/
#define PSA_AEAD_DECRYPT_OUTPUT_SIZE(key_type, alg, ciphertext_length) \
(PSA_AEAD_NONCE_LENGTH(key_type, alg) ? \
@@ -314,7 +336,8 @@
* \note This macro returns a compile-time constant if its arguments are
* compile-time constants.
*
- * See also #PSA_AEAD_DECRYPT_OUTPUT_SIZE(\p alg, \p ciphertext_length).
+ * See also #PSA_AEAD_DECRYPT_OUTPUT_SIZE(\p key_type, \p alg,
+ * \p ciphertext_length).
*
* \param ciphertext_length Size of the ciphertext in bytes.
*
@@ -379,10 +402,14 @@
* insufficient buffer size. The actual size of the output may be smaller
* in any given call.
*
+ * See also #PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE(\p input_length).
+ *
* \warning This macro may evaluate its arguments multiple times or
* zero times, so you should not pass arguments that contain
* side effects.
*
+ * \param key_type A symmetric key type that is
+ * compatible with algorithm \p alg.
* \param alg An AEAD algorithm
* (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_AEAD(\p alg) is true).
@@ -390,7 +417,9 @@
*
* \return A sufficient output buffer size for the specified
* algorithm.
- * If the AEAD algorithm is not recognized, return 0.
+ * If the key type or AEAD algorithm is not
+ * recognized, or the parameters are incompatible,
+ * return 0.
*/
/* For all the AEAD modes defined in this specification, it is possible
* to emit output without delay. However, hardware may not always be
@@ -409,7 +438,7 @@
* If the size of the output buffer is at least this large, it is guaranteed
* that psa_aead_update() will not fail due to an insufficient buffer size.
*
- * See also #PSA_AEAD_UPDATE_OUTPUT_SIZE(\p alg, \p input_length).
+ * See also #PSA_AEAD_UPDATE_OUTPUT_SIZE(\p key_type, \p alg, \p input_length).
*
* \param input_length Size of the input in bytes.
*/
@@ -423,13 +452,19 @@
* insufficient ciphertext buffer size. The actual size of the output may
* be smaller in any given call.
*
+ * See also #PSA_AEAD_FINISH_OUTPUT_MAX_SIZE.
+ *
+ * \param key_type A symmetric key type that is
+ compatible with algorithm \p alg.
* \param alg An AEAD algorithm
* (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_AEAD(\p alg) is true).
*
* \return A sufficient ciphertext buffer size for the
* specified algorithm.
- * If the AEAD algorithm is not recognized, return 0.
+ * If the key type or AEAD algorithm is not
+ * recognized, or the parameters are incompatible,
+ * return 0.
*/
#define PSA_AEAD_FINISH_OUTPUT_SIZE(key_type, alg) \
(PSA_AEAD_NONCE_LENGTH(key_type, alg) && PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ? \
@@ -439,7 +474,7 @@
/** A sufficient ciphertext buffer size for psa_aead_finish(), for any of the
* supported key types and AEAD algorithms.
*
- * See also #PSA_AEAD_FINISH_OUTPUT_SIZE(\p alg).
+ * See also #PSA_AEAD_FINISH_OUTPUT_SIZE(\p key_type, \p alg).
*/
#define PSA_AEAD_FINISH_OUTPUT_MAX_SIZE (PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE)
@@ -450,13 +485,19 @@
* insufficient plaintext buffer size. The actual size of the output may
* be smaller in any given call.
*
+ * See also #PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE.
+ *
+ * \param key_type A symmetric key type that is
+ * compatible with algorithm \p alg.
* \param alg An AEAD algorithm
* (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_AEAD(\p alg) is true).
*
* \return A sufficient plaintext buffer size for the
* specified algorithm.
- * If the AEAD algorithm is not recognized, return 0.
+ * If the key type or AEAD algorithm is not
+ * recognized, or the parameters are incompatible,
+ * return 0.
*/
#define PSA_AEAD_VERIFY_OUTPUT_SIZE(key_type, alg) \
(PSA_AEAD_NONCE_LENGTH(key_type, alg) && PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ? \
@@ -466,7 +507,7 @@
/** A sufficient plaintext buffer size for psa_aead_verify(), for any of the
* supported key types and AEAD algorithms.
*
- * See also #PSA_AEAD_VERIFY_OUTPUT_SIZE(\p alg).
+ * See also #PSA_AEAD_VERIFY_OUTPUT_SIZE(\p key_type, \p alg).
*/
#define PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE (PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE)