Add XChaCha20 keys and algorithms

Author: athoelke

doc/crypto/api.db/psa/crypto.h

@@ -155,6 +155,7 @@ typedef /* implementation-defined type */ psa_mac_operation_t;
 #define PSA_ALG_TLS12_PSK_TO_MS(hash_alg) /* specification-defined value */
 #define PSA_ALG_TRUNCATED_MAC(mac_alg, mac_length) \
     /* specification-defined value */
+#define PSA_ALG_XCHACHA20_POLY1305 ((psa_algorithm_t)0x05100600)
 #define PSA_ALG_XTS ((psa_algorithm_t)0x0440ff00)
 #define PSA_ASYMMETRIC_DECRYPT_OUTPUT_MAX_SIZE \
     /* implementation-defined value */
@@ -287,6 +288,7 @@ typedef /* implementation-defined type */ psa_mac_operation_t;
 #define PSA_KEY_TYPE_RSA_KEY_PAIR ((psa_key_type_t)0x7001)
 #define PSA_KEY_TYPE_RSA_PUBLIC_KEY ((psa_key_type_t)0x4001)
 #define PSA_KEY_TYPE_SM4 ((psa_key_type_t)0x2405)
+#define PSA_KEY_TYPE_XCHACHA20 ((psa_key_type_t)0x2007)
 #define PSA_KEY_USAGE_CACHE ((psa_key_usage_t)0x00000004)
 #define PSA_KEY_USAGE_COPY ((psa_key_usage_t)0x00000002)
 #define PSA_KEY_USAGE_DECRYPT ((psa_key_usage_t)0x00000200)

doc/crypto/api/keys/types.rst

@@ -1,4 +1,4 @@
-.. SPDX-FileCopyrightText: Copyright 2018-2022 Arm Limited and/or its affiliates <open-source-office@arm.com>
+.. SPDX-FileCopyrightText: Copyright 2018-2023 Arm Limited and/or its affiliates <open-source-office@arm.com>
 .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
 
 .. header:: psa/crypto
@@ -401,6 +401,23 @@ Symmetric keys
         | `PSA_ALG_STREAM_CIPHER`
         | `PSA_ALG_CHACHA20_POLY1305`
 
+.. macro:: PSA_KEY_TYPE_XCHACHA20
+    :definition: ((psa_key_type_t)0x2007)
+
+    .. summary::
+        Key for the XChaCha20 stream cipher or the XChaCha20-Poly1305 AEAD algorithm.
+
+    The XChaCha20 key size is 256 bits (32 bytes).
+
+    *   Use algorithm `PSA_ALG_STREAM_CIPHER` to use this key with the XChaCha20 cipher for unauthenticated encryption. See `PSA_ALG_STREAM_CIPHER` for details of this algorithm.
+
+    *   Use algorithm `PSA_ALG_XCHACHA20_POLY1305` to use this key with the XChaCha20 cipher and Poly1305 authenticator for AEAD. See `PSA_ALG_XCHACHA20_POLY1305` for details of this algorithm.
+
+    .. subsection:: Compatible algorithms
+
+        | `PSA_ALG_STREAM_CIPHER`
+        | `PSA_ALG_XCHACHA20_POLY1305`
+
 
 .. _asymmetric-keys:
 

doc/crypto/api/ops/aead.rst

@@ -121,6 +121,24 @@ AEAD algorithms
 
         | `PSA_KEY_TYPE_CHACHA20`
 
+.. macro:: PSA_ALG_XCHACHA20_POLY1305
+    :definition: ((psa_algorithm_t)0x05100600)
+
+    .. summary::
+        The XChaCha20-Poly1305 AEAD algorithm.
+
+    XChaCha20-Poly1305 is a variation of the ChaCha20-Poly1305 AEAD algorithm, but uses a 192-bit nonce. The larger nonce provides much lower probability of nonce misuse.
+
+    XChaCha20-Poly1305 requires a 24-byte nonce.
+
+    Implementations must support 16-byte tags. It is recommended that truncated tag sizes are rejected.
+
+    XChaCha20-Poly1305 is defined in :cite-title:`XCHACHA`.
+
+    .. subsection:: Compatible key types
+
+        | `PSA_KEY_TYPE_XCHACHA20`
+
 .. macro:: PSA_ALG_AEAD_WITH_SHORTENED_TAG
     :definition: /* specification-defined value */
 

doc/crypto/api/ops/ciphers.rst

@@ -44,7 +44,7 @@ Cipher algorithms
     .. summary::
         The stream cipher mode of a stream cipher algorithm.
 
-    The underlying stream cipher is determined by the key type. The ARC4 and ChaCha20 ciphers use this algorithm identifier.
+    The underlying stream cipher is determined by the key type. The ARC4, ChaCha20, and XChaCha20 ciphers use this algorithm identifier.
 
     .. subsection:: ARC4
 
@@ -72,14 +72,38 @@ Cipher algorithms
         *   A call to `psa_cipher_set_iv()` on a multi-part cipher operation can support the following IV sizes:
 
             -   12 bytes: the provided IV is used as the nonce, and the counter value is set to zero.
-            -   16 bytes: the first four bytes of the IV are used as the counter value (encoded as little-endian), and the remaining 12 bytes is used as the nonce.
+            -   16 bytes: the first four bytes of the IV are used as the counter value (encoded as little-endian), and the remaining 12 bytes are used as the nonce.
             -   8 bytes: the cipher operation uses the original :cite:`CHACHA20` definition of ChaCha20: the provided IV is used as the 64-bit nonce, and the 64-bit counter value is set to zero.
             -   It is recommended that implementations do not support other sizes of IV.
 
+    .. subsection:: XChaCha20
+
+        To use XChaCha20, use a key type of `PSA_KEY_TYPE_XCHACHA20` and algorithm id `PSA_ALG_STREAM_CIPHER`.
+
+        XChaCha20 is a variation of ChaCha20 that uses a 192-bit nonce and a 64-bit counter. The larger nonce provides much lower probability of nonce misuse.
+
+        When using an XChaCha20 key with the `PSA_ALG_STREAM_CIPHER` algorithm, the nonce and an initial counter values are provided using the initialization vector (IV) functions in the following ways:
+
+        *   A call to `psa_cipher_encrypt()` will generate a random 24-byte nonce, and set the counter value to zero. The random nonce is output as a 24-byte IV value in the output.
+
+        *   A call to `psa_cipher_decrypt()` will use first 24 bytes of the input buffer as the nonce and set the counter value to zero.
+
+        *   A call to `psa_cipher_generate_iv()` on a multi-part cipher operation will generate and return a random 24-byte nonce and set the counter value to zero.
+
+        *   A call to `psa_cipher_set_iv()` on a multi-part cipher operation can support the following IV sizes:
+
+            -   24 bytes: the provided IV is used as the nonce, and the counter value is set to zero.
+            -   32 bytes: the first 8 bytes of the IV are used as the counter value (encoded as little-endian), and the remaining 24 bytes are used as the nonce.
+
+            Other sizes of IV are invalid.
+
+        XChaCha20 is defined in :cite-title:`XCHACHA`.
+
     .. subsection:: Compatible key types
 
         | `PSA_KEY_TYPE_ARC4`
         | `PSA_KEY_TYPE_CHACHA20`
+        | `PSA_KEY_TYPE_XCHACHA20`
 
 .. macro:: PSA_ALG_CTR
     :definition: ((psa_algorithm_t)0x04c01000)

doc/crypto/appendix/encodings.rst

@@ -1,4 +1,4 @@
-.. SPDX-FileCopyrightText: Copyright 2023 Arm Limited and/or its affiliates <open-source-office@arm.com>
+.. SPDX-FileCopyrightText: Copyright 2022-2023 Arm Limited and/or its affiliates <open-source-office@arm.com>
 .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
 
 .. _appendix-encodings:
@@ -236,7 +236,8 @@ W is a flag to indicate a wildcard permitted-algorithm policy:
     AEAD algorithm, B, AEAD-TYPE, Algorithm identifier, Algorithm value
     CCM :sup:`a`, 1, ``0x01``, `PSA_ALG_CCM`, ``0x05500100`` :sup:`b`
     GCM :sup:`a`, 1, ``0x02``, `PSA_ALG_GCM`, ``0x05500200`` :sup:`b`
-    ChaCha20-poly1305, 0, ``0x05``, `PSA_ALG_CHACHA20_POLY1305`, ``0x05100500`` :sup:`b`
+    ChaCha20-Poly1305, 0, ``0x05``, `PSA_ALG_CHACHA20_POLY1305`, ``0x05100500`` :sup:`b`
+    XChaCha20-Poly1305, 0, ``0x06``, `PSA_ALG_XCHACHA20_POLY1305`, ``0x05100600`` :sup:`b`
 
 a.  This is an AEAD mode of an underlying block cipher. The block cipher is determined by the key type that is provided to the AEAD operation.
 
@@ -499,6 +500,7 @@ The defined values for BLK, SYM-TYPE and P are shown in :numref:`table-symmetric
     Symmetric key type, BLK, SYM-TYPE, P, Key type, Key type value
     ARC4, 0, 1, 0, `PSA_KEY_TYPE_ARC4`, ``0x2002``
     ChaCha20, 0, 2, 0, `PSA_KEY_TYPE_CHACHA20`, ``0x2004``
+    XChaCha20, 0, 3, 1, `PSA_KEY_TYPE_XCHACHA20`, ``0x2007``
     DES, 3, 0, 1, `PSA_KEY_TYPE_DES`, ``0x2301``
     AES, 4, 0, 0, `PSA_KEY_TYPE_AES`, ``0x2400``
     CAMELLIA, 4, 1, 1, `PSA_KEY_TYPE_CAMELLIA`, ``0x2403``

doc/crypto/appendix/history.rst

@@ -24,6 +24,8 @@ Changes to the API
 
 *   Added `psa_key_agreement()` for standalone key agreement that outputs to a new key object. Also added `PSA_ALG_IS_STANDALONE_KEY_AGREEMENT()` as a synonym for `PSA_ALG_IS_RAW_KEY_AGREEMENT()`.
 
+*   Added support for the XChaCha20 cipher and XChaCha20-Poly1305 AEAD algorithms. See `PSA_KEY_TYPE_XCHACHA20` and `PSA_ALG_XCHACHA20_POLY1305`.
+
 Clarifications and fixes
 ~~~~~~~~~~~~~~~~~~~~~~~~
 

doc/crypto/references

@@ -336,6 +336,12 @@
     :url: http://cr.yp.to/chacha/chacha-20080128.pdf
     :publication: January 2008
 
+.. reference:: XCHACHA
+    :title: XChaCha: eXtended-nonce ChaCha and AEAD_XChaCha20_Poly1305
+    :author: Arciszewski
+    :publication: January 2020
+    :url: datatracker.ietf.org/doc/html/draft-irtf-cfrg-xchacha-03
+
 .. reference:: CLULOW
     :author: Clulow, Jolyon
     :title: On the Security of PKCS #11