Add support for zigbee algorithms

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

@@ -47,13 +47,16 @@ typedef /* implementation-defined type */ psa_mac_operation_t;
     /* specification-defined value */
 #define PSA_ALG_AEAD_WITH_SHORTENED_TAG(aead_alg, tag_length) \
     /* specification-defined value */
+#define PSA_ALG_AES_MMO_ZIGBEE ((psa_algorithm_t)0x02000007)
 #define PSA_ALG_ANY_HASH ((psa_algorithm_t)0x020000ff)
 #define PSA_ALG_AT_LEAST_THIS_LENGTH_MAC(mac_alg, min_mac_length) \
     /* specification-defined value */
 #define PSA_ALG_CBC_MAC ((psa_algorithm_t)0x03c00100)
 #define PSA_ALG_CBC_NO_PADDING ((psa_algorithm_t)0x04404000)
 #define PSA_ALG_CBC_PKCS7 ((psa_algorithm_t)0x04404100)
 #define PSA_ALG_CCM ((psa_algorithm_t)0x05500100)
+#define PSA_ALG_CCM_STAR_ANY_TAG ((psa_algorithm_t)0x04c09300)
+#define PSA_ALG_CCM_STAR_NO_TAG ((psa_algorithm_t)0x04c01300)
 #define PSA_ALG_CFB ((psa_algorithm_t)0x04c01100)
 #define PSA_ALG_CHACHA20_POLY1305 ((psa_algorithm_t)0x05100500)
 #define PSA_ALG_CMAC ((psa_algorithm_t)0x03c00200)

doc/crypto/api/keys/policy.rst

@@ -36,6 +36,7 @@ The following algorithm policies are supported:
 *   A standalone key agreement algorithm also permits the specified key agreement scheme to be combined with any key derivation algorithm.
 *   An algorithm built from `PSA_ALG_AT_LEAST_THIS_LENGTH_MAC()` permits any MAC algorithm from the same base class (for example, CMAC) which computes or verifies a MAC length greater than or equal to the length encoded in the wildcard algorithm.
 *   An algorithm built from `PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG()` permits any AEAD algorithm from the same base class (for example, CCM) which computes or verifies a tag length greater than or equal to the length encoded in the wildcard algorithm.
+*   The `PSA_ALG_CCM_STAR_ANY_TAG` wildcard algorithm permits the `PSA_ALG_CCM_STAR_NO_TAG` cipher algorithm, the `PSA_ALG_CCM` AEAD algorithm, and the :code:`PSA_ALG_AEAD_WITH_SHORTENED_TAG(PSA_ALG_CCM, tag_length)` truncated-tag AEAD algorithm for ``tag_length`` equal to 4, 8 or 16.
 
 When a key is used in a cryptographic operation, the application must supply the algorithm to use for the operation. This algorithm is checked against the key's permitted-algorithm policy.
 

doc/crypto/api/ops/aead.rst

@@ -70,6 +70,15 @@ AEAD algorithms
 
     The CCM block cipher mode is defined in :RFC-title:`3610`.
 
+    .. subsection:: Usage in Zigbee
+
+        The CCM* algorithm is required by :cite-title:`ZIGBEE`.
+
+        *   `PSA_ALG_CCM`, and its truncated variants, can be used to implement CCM* for non-zero tag lengths.
+        *   For unauthenticated CCM*, with a zero-length tag, use the `PSA_ALG_CCM_STAR_NO_TAG` cipher algorithm.
+
+        See also :ref:`Usage in Zigbee <using-ccm-star-no-tag>` under `PSA_ALG_CCM_STAR_NO_TAG`.
+
     .. subsection:: Compatible key types
 
         | `PSA_KEY_TYPE_AES`

doc/crypto/api/ops/ciphers.rst

@@ -150,6 +150,45 @@ Cipher algorithms
         | `PSA_KEY_TYPE_CAMELLIA`
         | `PSA_KEY_TYPE_SM4`
 
+.. macro:: PSA_ALG_CCM_STAR_NO_TAG
+    :definition: ((psa_algorithm_t)0x04c01300)
+
+    .. summary::
+        The CCM* cipher mode without authentication.
+
+    This is CCM* as specified in :cite-title:`IEEE-CCM` §7, with a tag length of 0. For CCM* with a nonzero tag length, use the AEAD algorithm `PSA_ALG_CCM`.
+
+    The underlying block cipher is determined by the key type.
+
+    The IV generated or set in the cipher API is used as the nonce in the CCM* operation. An implementation must support the default IV length of 13. Support for setting a shorter IV is optional.
+
+    The maximum message length that can be encrypted is dependent on the length of the IV. See `PSA_ALG_CCM` for details of this relationship.
+
+    .. _using-ccm-star-no-tag:
+
+    .. subsection:: Usage in Zigbee
+
+        The Zigbee message encryption algorithm is based on CCM*. This is detailed in :cite-title:`ZIGBEE` §B.1.1 and §A.
+
+        *   For unauthenticated messages — when *M* = 0 --- the `PSA_ALG_CCM_STAR_NO_TAG` algorithm is used with an AES-128 key in a multi-part cipher operation. The 13-byte IV must be constructed as specified in `[ZIGBEE]`, and provided to the operation using `psa_cipher_set_iv()`.
+
+            .. note::
+
+                An implementation of Zigbee cannot use the single-part `psa_cipher_encrypt()` function, as this generates a random IV, which is not valid for the Zigbee protocol.
+
+        *   For authenticated messages — when *M* ∈ {4, 8, 16} --- the :code:`PSA_ALG_AEAD_WITH_SHORTENED_TAG(PSA_ALG_CCM, tag_length)` algorithm is used with an AES-128 key, where ``tag_length`` is the required value of *M*. The 13-byte nonce must be constructed as specified in `[ZIGBEE]`.
+
+            As the default tag length for CCM is 16, then `PSA_ALG_CCM` algorithm can be used when *M* = 16.
+
+        *   To enable a single AES-128 key to be used for both the `PSA_ALG_CCM_STAR_NO_TAG` cipher and `PSA_ALG_CCM` AEAD algorithm, the key can be defined with the wildcard `PSA_ALG_CCM_STAR_ANY_TAG` permitted algorithm.
+
+    .. subsection:: Compatible key types
+
+        | `PSA_KEY_TYPE_AES`
+        | `PSA_KEY_TYPE_ARIA`
+        | `PSA_KEY_TYPE_CAMELLIA`
+        | `PSA_KEY_TYPE_SM4`
+
 .. macro:: PSA_ALG_CFB
     :definition: ((psa_algorithm_t)0x04c01100)
 
@@ -833,6 +872,14 @@ Support macros
 
     A stream cipher is a symmetric cipher that encrypts or decrypts messages by applying a bitwise-xor with a stream of bytes that is generated from a key.
 
+.. macro:: PSA_ALG_CCM_STAR_ANY_TAG
+    :definition: ((psa_algorithm_t)0x04c09300)
+
+    .. summary::
+        A wildcard algorithm that permits the use of the key with CCM* as both an AEAD and an unauthenticated cipher algorithm.
+
+    If a block-cipher key specifies `PSA_ALG_CCM_STAR_ANY_TAG` as its permitted algorithm, then the key can be used with the `PSA_ALG_CCM_STAR_NO_TAG` unauthenticated cipher, the `PSA_ALG_CCM` AEAD algorithm, and truncated `PSA_ALG_CCM` AEAD algorithms.
+
 .. macro:: PSA_CIPHER_ENCRYPT_OUTPUT_SIZE
     :definition: /* implementation-defined value */
 

doc/crypto/api/ops/hashes.rst

@@ -73,6 +73,20 @@ Hash algorithms
 
     RIPEMD-160 is defined in :cite-title:`RIPEMD`, and also in :cite-title:`ISO10118`.
 
+.. macro:: PSA_ALG_AES_MMO_ZIGBEE
+    :definition: ((psa_algorithm_t)0x02000007)
+
+    .. summary::
+        The *Zigbee* 1.0 hash function based on a Matyas-Meyer-Oseas (MMO) construction using AES-128.
+
+    This is the cryptographic hash function based on the Merkle-Damgård construction over a Matyas-Meyer-Oseas one-way compression function and the AES-128 block cipher, with the parametrization defined in :cite-title:`ZIGBEE` §B.6.
+
+    This hash function can operate on input strings of up to 2\ :sup:`32` - 1 bits.
+
+    .. note::
+
+        The Zigbee keyed hash function from `[ZIGBEE]` §B.1.4 is :code:`PSA_ALG_HMAC(PSA_ALG_AES_MMO_ZIGBEE)`.
+
 .. macro:: PSA_ALG_SHA_1
     :definition: ((psa_algorithm_t)0x02000005)
 

doc/crypto/appendix/encodings.rst

@@ -116,6 +116,7 @@ The defined values for HASH-TYPE are shown in :numref:`table-hash-type`.
     MD5, ``0x03``, `PSA_ALG_MD5`, ``0x02000003``
     RIPEMD-160, ``0x04``, `PSA_ALG_RIPEMD160`, ``0x02000004``
     SHA1, ``0x05``, `PSA_ALG_SHA_1`, ``0x02000005``
+    AES-MMO (Zigbee), ``0x07``, `PSA_ALG_AES_MMO_ZIGBEE`, ``0x02000007``
     SHA-224, ``0x08``, `PSA_ALG_SHA_224`, ``0x02000008``
     SHA-256, ``0x09``, `PSA_ALG_SHA_256`, ``0x02000009``
     SHA-384, ``0x0A``, `PSA_ALG_SHA_384`, ``0x0200000A``
@@ -197,6 +198,8 @@ The defined values for S, B, and CIPHER-TYPE are shown in :numref:`table-cipher-
     CTR mode :sup:`b`, 1, 1, ``0x10``, `PSA_ALG_CTR`, ``0x04C01000``
     CFB mode :sup:`b`, 1, 1, ``0x11``, `PSA_ALG_CFB`, ``0x04C01100``
     OFB mode :sup:`b`, 1, 1, ``0x12``, `PSA_ALG_OFB`, ``0x04C01200``
+    CCM* with zero-length tag :sup:`b`, 1, 1, ``0x13``, `PSA_ALG_CCM_STAR_NO_TAG`, ``0x04C01300``
+    *CCM\* wildcard* :sup:`c`, 1, 1, ``0x93``, `PSA_ALG_CCM_STAR_ANY_TAG`, ``0x04c09300``
     XTS mode :sup:`b`, 0, 1, ``0xFF``, `PSA_ALG_XTS`, ``0x0440FF00``
     CBC mode without padding :sup:`b`, 0, 1, ``0x40``, `PSA_ALG_CBC_NO_PADDING`, ``0x04404000``
     CBC mode with PKCS#7 padding :sup:`b`, 0, 1, ``0x41``, `PSA_ALG_CBC_PKCS7`, ``0x04404100``
@@ -206,6 +209,8 @@ a.  The stream cipher algorithm identifier `PSA_ALG_STREAM_CIPHER` is used with
 
 b.  This is a cipher mode of an underlying block cipher. The block cipher is determined by the key type that is provided to the cipher operation.
 
+c.  The wildcard algorithm `PSA_ALG_CCM_STAR_ANY_TAG` permits a key to be used with any CCM\* algorithm: unauthenticated cipher `PSA_ALG_CCM_STAR_NO_TAG`, and AEAD algorithm `PSA_ALG_CCM`.
+
 .. _aead-encoding:
 
 AEAD algorithm encoding

doc/crypto/appendix/history.rst

@@ -26,6 +26,8 @@ Changes to the API
 
 *   Added support for the XChaCha20 cipher and XChaCha20-Poly1305 AEAD algorithms. See `PSA_KEY_TYPE_XCHACHA20` and `PSA_ALG_XCHACHA20_POLY1305`.
 
+*   Added support for :cite-title:`ZIGBEE` cryptographic algorithms. See `PSA_ALG_AES_MMO_ZIGBEE` and `PSA_ALG_CCM_STAR_NO_TAG`.
+
 Clarifications and fixes
 ~~~~~~~~~~~~~~~~~~~~~~~~
 

doc/crypto/references

@@ -353,3 +353,15 @@
     :author: Cragie, Hao
     :publication: June 2016
     :url: datatracker.ietf.org/doc/html/draft-cragie-tls-ecjpake-01
+
+.. reference:: ZIGBEE
+    :author: zigbee alliance
+    :title: zigbee Specification
+    :url: csa-iot.org/wp-content/uploads/2022/01/docs-05-3474-22-0csg-zigbee-specification-1.pdf
+    :publication: April 2017
+
+.. reference:: IEEE-CCM
+    :author: IEEE
+    :title: IEEE Standard for Low-Rate Wireless Networks
+    :url: standards.ieee.org/ieee/802.15.4/7029/
+    :publication: 2020