Multipart AEAD buffer output sizes

include/psa/crypto.h

@@ -2495,12 +2495,24 @@ psa_status_t psa_aead_update_ad(psa_aead_operation_t *operation,
  *          - In particular, do not copy the output anywhere but to a
  *            memory or storage space that you have exclusive access to.
  *
+ * 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 psa_aead_update(), psa_aead_finish() or psa_aead_verify()
+ * provides sufficient input. The amount of data that can be delayed
+ * in this way is bounded by #PSA_AEAD_UPDATE_OUTPUT_SIZE.
+ *
  * \param[in,out] operation     Active AEAD operation.
  * \param[in] input             Buffer containing the message fragment to
  *                              encrypt or decrypt.
  * \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.
  * \param[out] output_length    On success, the number of bytes
  *                              that make up the returned output.
  *
@@ -2511,6 +2523,9 @@ psa_status_t psa_aead_update_ad(psa_aead_operation_t *operation,
  *         or already completed).
  * \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.
  * \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
@@ -2541,9 +2556,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(). For all standard AEAD algorithms,
- *   psa_aead_update() does not buffer any output and therefore \p ciphertext
- *   will not contain any output and can be a 0-sized buffer.
+ *   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.
@@ -2554,11 +2567,18 @@ 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.
  * \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.
  * \param[out] tag_length       On success, the number of bytes
  *                              that make up the returned tag.
  *
@@ -2569,6 +2589,11 @@ psa_status_t psa_aead_update(psa_aead_operation_t *operation,
  *         decryption, or already completed).
  * \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).
  * \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
@@ -2602,6 +2627,18 @@ psa_status_t psa_aead_finish(psa_aead_operation_t *operation,
  * When this function returns, the operation becomes inactive.
  *
  * \param[in,out] operation     Active AEAD operation.
+ * \param[out] plaintext        Buffer where the last part of the plaintext
+ *                              is to be written. This is the remaining data
+ *                              from previous calls to psa_aead_update()
+ *                              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.
+ * \param[out] plaintext_length On success, the number of bytes of
+ *                              returned plaintext.
  * \param[in] tag               Buffer containing the authentication tag.
  * \param tag_length            Size of the \p tag buffer in bytes.
  *
@@ -2610,6 +2647,11 @@ psa_status_t psa_aead_finish(psa_aead_operation_t *operation,
  * \retval #PSA_ERROR_BAD_STATE
  *         The operation state is not valid (not set up, nonce not set,
  *         encryption, or already completed).
+ * \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.
  * \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
@@ -2624,6 +2666,9 @@ psa_status_t psa_aead_finish(psa_aead_operation_t *operation,
  * \retval #PSA_ERROR_TAMPERING_DETECTED
  */
 psa_status_t psa_aead_verify(psa_aead_operation_t *operation,
+                             uint8_t *plaintext,
+                             size_t plaintext_size,
+                             size_t *plaintext_length,
                              const uint8_t *tag,
                              size_t tag_length);
 

include/psa/crypto_sizes.h

@@ -53,6 +53,9 @@
 #define PSA_BITS_TO_BYTES(bits) (((bits) + 7) / 8)
 #define PSA_BYTES_TO_BITS(bytes) ((bytes) * 8)
 
+#define PSA_ROUND_UP_TO_MULTIPLE(block_size, length) \
+    (((length) + (block_size) - 1) / (block_size) * (block_size))
+
 /** The size of the output of psa_hash_finish(), in bytes.
  *
  * This is also the hash size that psa_hash_verify() expects.
@@ -268,49 +271,102 @@
      (plaintext_length) + PSA_AEAD_TAG_LENGTH(alg) :              \
      0)
 
-/** The maximum size of the output of psa_aead_finish(), in bytes.
+/** The maximum size of the output of psa_aead_decrypt(), in bytes.
+ *
+ * If the size of the plaintext buffer is at least this large, it is
+ * guaranteed that psa_aead_decrypt() will not fail due to an
+ * insufficient buffer size. Depending on the algorithm, the actual size of
+ * the plaintext may be smaller.
+ *
+ * \param alg                 An AEAD algorithm
+ *                            (\c PSA_ALG_XXX value such that
+ *                            #PSA_ALG_IS_AEAD(\p alg) is true).
+ * \param ciphertext_length   Size of the plaintext in bytes.
+ *
+ * \return                    The AEAD ciphertext size for the specified
+ *                            algorithm.
+ *                            If the AEAD algorithm is not recognized, return 0.
+ *                            An implementation may return either 0 or a
+ *                            correct size for an AEAD algorithm that it
+ *                            recognizes, but does not support.
+ */
+#define PSA_AEAD_DECRYPT_OUTPUT_SIZE(alg, ciphertext_length)      \
+    (PSA_AEAD_TAG_LENGTH(alg) != 0 ?                              \
+     (ciphertext_length) - PSA_AEAD_TAG_LENGTH(alg) :             \
+     0)
+
+/** A sufficient output buffer size for psa_aead_update().
+ *
+ * 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. The actual size of the output may be smaller
+ * in any given call.
+ *
+ * \param alg                 An AEAD algorithm
+ *                            (\c PSA_ALG_XXX value such that
+ *                            #PSA_ALG_IS_AEAD(\p alg) is true).
+ * \param input_length        Size of the input in bytes.
+ *
+ * \return                    A sufficient output buffer size for the specified
+ *                            algorithm.
+ *                            If the AEAD algorithm is not recognized, return 0.
+ *                            An implementation may return either 0 or a
+ *                            correct size for an AEAD algorithm that it
+ *                            recognizes, but does not support.
+ */
+/* For all the AEAD modes defined in this specification, it is possible
+ * to emit output without delay. However, hardware may not always be
+ * capable of this. So for modes based on a block cipher, allow the
+ * implementation to delay the output until it has a full block. */
+#define PSA_AEAD_UPDATE_OUTPUT_SIZE(alg, input_length)                  \
+    (PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ?                             \
+     PSA_ROUND_UP_TO_MULTIPLE(PSA_MAX_BLOCK_CIPHER_BLOCK_SIZE, (input_length)) : \
+     (input_length))
+
+/** A sufficient ciphertext buffer size for psa_aead_finish().
  *
  * If the size of the ciphertext buffer is at least this large, it is
  * guaranteed that psa_aead_finish() will not fail due to an
- * insufficient buffer size. Depending on the algorithm, the actual size of
- * the ciphertext may be smaller.
+ * insufficient ciphertext buffer size. The actual size of the output may
+ * be smaller in any given call.
  *
  * \param alg                 An AEAD algorithm
  *                            (\c PSA_ALG_XXX value such that
  *                            #PSA_ALG_IS_AEAD(\p alg) is true).
  *
- * \return                    The maximum trailing ciphertext size for the
+ * \return                    A sufficient ciphertext buffer size for the
  *                            specified algorithm.
  *                            If the AEAD algorithm is not recognized, return 0.
  *                            An implementation may return either 0 or a
  *                            correct size for an AEAD algorithm that it
  *                            recognizes, but does not support.
  */
-#define PSA_AEAD_FINISH_OUTPUT_SIZE(alg)      \
-    ((size_t)0)
+#define PSA_AEAD_FINISH_OUTPUT_SIZE(alg)                                \
+    (PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ?                             \
+     PSA_MAX_BLOCK_CIPHER_BLOCK_SIZE :                                  \
+     0)
 
-/** The maximum size of the output of psa_aead_decrypt(), in bytes.
+/** A sufficient plaintext buffer size for psa_aead_verify().
  *
  * If the size of the plaintext buffer is at least this large, it is
- * guaranteed that psa_aead_decrypt() will not fail due to an
- * insufficient buffer size. Depending on the algorithm, the actual size of
- * the plaintext may be smaller.
+ * guaranteed that psa_aead_verify() will not fail due to an
+ * insufficient plaintext buffer size. The actual size of the output may
+ * be smaller in any given call.
  *
  * \param alg                 An AEAD algorithm
  *                            (\c PSA_ALG_XXX value such that
  *                            #PSA_ALG_IS_AEAD(\p alg) is true).
- * \param ciphertext_length   Size of the plaintext in bytes.
  *
- * \return                    The AEAD ciphertext size for the specified
- *                            algorithm.
+ * \return                    A sufficient plaintext buffer size for the
+ *                            specified algorithm.
  *                            If the AEAD algorithm is not recognized, return 0.
  *                            An implementation may return either 0 or a
  *                            correct size for an AEAD algorithm that it
  *                            recognizes, but does not support.
  */
-#define PSA_AEAD_DECRYPT_OUTPUT_SIZE(alg, ciphertext_length)      \
-    (PSA_AEAD_TAG_LENGTH(alg) != 0 ?                              \
-     (plaintext_length) - PSA_AEAD_TAG_LENGTH(alg) :              \
+#define PSA_AEAD_VERIFY_OUTPUT_SIZE(alg)                                \
+    (PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ?                             \
+     PSA_MAX_BLOCK_CIPHER_BLOCK_SIZE :                                  \
      0)
 
 #define PSA_RSA_MINIMUM_PADDING_SIZE(alg)                         \

include/psa/crypto_values.h

@@ -402,6 +402,15 @@
  * legacy protocols. */
 #define PSA_KEY_TYPE_ARC4                       ((psa_key_type_t)0x40000004)
 
+/** Key for the ChaCha20 stream cipher or the Chacha20-Poly1305 AEAD algorithm.
+ *
+ * ChaCha20 and the ChaCha20_Poly1305 construction are defined in RFC 7539.
+ *
+ * Implementations must support 12-byte nonces, may support 8-byte nonces,
+ * and should reject other sizes.
+ */
+#define PSA_KEY_TYPE_CHACHA20                   ((psa_key_type_t)0x40000005)
+
 /** RSA public key. */
 #define PSA_KEY_TYPE_RSA_PUBLIC_KEY             ((psa_key_type_t)0x60010000)
 /** RSA key pair (private and public key). */
@@ -836,6 +845,18 @@
  */
 #define PSA_ALG_ARC4                            ((psa_algorithm_t)0x04800001)
 
+/** The ChaCha20 stream cipher.
+ *
+ * ChaCha20 is defined in RFC 7539.
+ *
+ * The nonce size for psa_cipher_set_iv() or psa_cipher_generate_iv()
+ * must be 12.
+ *
+ * The initial block counter is always 0.
+ *
+ */
+#define PSA_ALG_CHACHA20                        ((psa_algorithm_t)0x04800005)
+
 /** The CTR stream cipher mode.
  *
  * CTR is a stream cipher which is built from a block cipher.
@@ -874,13 +895,39 @@
  */
 #define PSA_ALG_CBC_PKCS7                       ((psa_algorithm_t)0x04600101)
 
+#define PSA_ALG_AEAD_FROM_BLOCK_FLAG            ((psa_algorithm_t)0x00400000)
+
+/** Whether the specified algorithm is an AEAD mode on a block cipher.
+ *
+ * \param alg An algorithm identifier (value of type #psa_algorithm_t).
+ *
+ * \return 1 if \p alg is an AEAD algorithm which is an AEAD mode based on
+ *         a block cipher, 0 otherwise.
+ *         This macro may return either 0 or 1 if \p alg is not a supported
+ *         algorithm identifier.
+ */
+#define PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg)    \
+    (((alg) & (PSA_ALG_CATEGORY_MASK | PSA_ALG_AEAD_FROM_BLOCK_FLAG)) == \
+     (PSA_ALG_CATEGORY_AEAD | PSA_ALG_AEAD_FROM_BLOCK_FLAG))
+
 /** The CCM authenticated encryption algorithm.
  */
-#define PSA_ALG_CCM                             ((psa_algorithm_t)0x06001001)
+#define PSA_ALG_CCM                             ((psa_algorithm_t)0x06401001)
 
 /** The GCM authenticated encryption algorithm.
  */
-#define PSA_ALG_GCM                             ((psa_algorithm_t)0x06001002)
+#define PSA_ALG_GCM                             ((psa_algorithm_t)0x06401002)
+
+/** The Chacha20-Poly1305 AEAD algorithm.
+ *
+ * The ChaCha20_Poly1305 construction is defined in RFC 7539.
+ *
+ * Implementations must support 12-byte nonces, may support 8-byte nonces,
+ * and should reject other sizes.
+ *
+ * Implementations must support 16-byte tags and should reject other sizes.
+ */
+#define PSA_ALG_CHACHA20_POLY1305               ((psa_algorithm_t)0x06001005)
 
 /* In the encoding of a AEAD algorithm, the bits corresponding to
  * PSA_ALG_AEAD_TAG_LENGTH_MASK encode the length of the AEAD tag.
@@ -924,6 +971,7 @@
     (                                                                   \
         PSA__ALG_AEAD_WITH_DEFAULT_TAG_LENGTH__CASE(aead_alg, PSA_ALG_CCM) \
         PSA__ALG_AEAD_WITH_DEFAULT_TAG_LENGTH__CASE(aead_alg, PSA_ALG_GCM) \
+        PSA__ALG_AEAD_WITH_DEFAULT_TAG_LENGTH__CASE(aead_alg, PSA_ALG_CHACHA20_POLY1305) \
         0)
 #define PSA__ALG_AEAD_WITH_DEFAULT_TAG_LENGTH__CASE(aead_alg, ref)      \
     PSA_ALG_AEAD_WITH_TAG_LENGTH(aead_alg, 0) ==                        \