From e442840529e29304cdea9e99225eaed68dabeee2 Mon Sep 17 00:00:00 2001
From: Andrew Thoelke <andrew.thoelke@arm.com>
Date: Thu, 10 Aug 2023 16:14:52 +0100
Subject: [PATCH 1/7] Add citation for zigbee Specification

---
 doc/crypto/references | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/doc/crypto/references b/doc/crypto/references
index 2b65b65d..e0ad2166 100644
--- a/doc/crypto/references
+++ b/doc/crypto/references
@@ -353,3 +353,9 @@
     :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

From b2e13e35b3c46314b1b1d6b949c00acdcd9524dd Mon Sep 17 00:00:00 2001
From: Andrew Thoelke <andrew.thoelke@arm.com>
Date: Thu, 10 Aug 2023 16:15:20 +0100
Subject: [PATCH 2/7] Add zigbee AES-MMO hash function

---
 doc/crypto/api.db/psa/crypto.h    |  1 +
 doc/crypto/api/ops/hashes.rst     | 14 ++++++++++++++
 doc/crypto/appendix/encodings.rst |  1 +
 3 files changed, 16 insertions(+)

diff --git a/doc/crypto/api.db/psa/crypto.h b/doc/crypto/api.db/psa/crypto.h
index cc2e5ffc..6299bbda 100644
--- a/doc/crypto/api.db/psa/crypto.h
+++ b/doc/crypto/api.db/psa/crypto.h
@@ -47,6 +47,7 @@ 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)0x02000006)
 #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 */
diff --git a/doc/crypto/api/ops/hashes.rst b/doc/crypto/api/ops/hashes.rst
index 388d6249..8e9143ac 100644
--- a/doc/crypto/api/ops/hashes.rst
+++ b/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)0x02000006)
+
+    .. summary::
+        The *zigbee* 1.0 hash function based on a Matyas-Meyer-Oseas (MMO) construction of AES-128.
+
+    zigbee specifies a cryptographic hash function based on the MMO hash construction using the AES-128 block cipher. This is 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)
 
diff --git a/doc/crypto/appendix/encodings.rst b/doc/crypto/appendix/encodings.rst
index 1760d731..ad037ed5 100644
--- a/doc/crypto/appendix/encodings.rst
+++ b/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), ``0x06``, `PSA_ALG_AES_MMO_ZIGBEE`, ``0x02000006``
     SHA-224, ``0x08``, `PSA_ALG_SHA_224`, ``0x02000008``
     SHA-256, ``0x09``, `PSA_ALG_SHA_256`, ``0x02000009``
     SHA-384, ``0x0A``, `PSA_ALG_SHA_384`, ``0x0200000A``

From 21a3b8caf49d31bd8f73a7b6148e2a3dfb2a8c97 Mon Sep 17 00:00:00 2001
From: Andrew Thoelke <andrew.thoelke@arm.com>
Date: Thu, 10 Aug 2023 23:04:58 +0100
Subject: [PATCH 3/7] Add support for CCM* as used in zigbee

---
 doc/crypto/api.db/psa/crypto.h    |  2 ++
 doc/crypto/api/keys/policy.rst    |  1 +
 doc/crypto/api/ops/aead.rst       |  4 +++
 doc/crypto/api/ops/ciphers.rst    | 41 +++++++++++++++++++++++++++++++
 doc/crypto/appendix/encodings.rst |  4 +++
 doc/crypto/appendix/history.rst   |  2 ++
 doc/crypto/references             |  6 +++++
 7 files changed, 60 insertions(+)

diff --git a/doc/crypto/api.db/psa/crypto.h b/doc/crypto/api.db/psa/crypto.h
index 6299bbda..7846d43b 100644
--- a/doc/crypto/api.db/psa/crypto.h
+++ b/doc/crypto/api.db/psa/crypto.h
@@ -55,6 +55,8 @@ typedef /* implementation-defined type */ psa_mac_operation_t;
 #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)
diff --git a/doc/crypto/api/keys/policy.rst b/doc/crypto/api/keys/policy.rst
index 0a1f4d17..fdbbe250 100644
--- a/doc/crypto/api/keys/policy.rst
+++ b/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.
 
diff --git a/doc/crypto/api/ops/aead.rst b/doc/crypto/api/ops/aead.rst
index 4f685cbc..7de01f30 100644
--- a/doc/crypto/api/ops/aead.rst
+++ b/doc/crypto/api/ops/aead.rst
@@ -70,6 +70,10 @@ AEAD algorithms
 
     The CCM block cipher mode is defined in :RFC-title:`3610`.
 
+    .. subsection:: Usage in zigbee
+
+        `PSA_ALG_CCM`, and its truncated variants, can be used to implement CCM* for non-zero tag lengths. CCM* is required by the :cite-title:`ZIGBEE`. For unauthenticated CCM*, the `PSA_ALG_CCM_STAR_NO_TAG` cipher algorithm can be used.
+
     .. subsection:: Compatible key types
 
         | `PSA_KEY_TYPE_AES`
diff --git a/doc/crypto/api/ops/ciphers.rst b/doc/crypto/api/ops/ciphers.rst
index 7430f0c1..51b53ba4 100644
--- a/doc/crypto/api/ops/ciphers.rst
+++ b/doc/crypto/api/ops/ciphers.rst
@@ -150,6 +150,39 @@ 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.
+
+    .. 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()`.
+
+            An implementation of zigbee cannot use the single-part cipher functions, as these generate 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]`.
+
+        *   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 +866,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 */
 
diff --git a/doc/crypto/appendix/encodings.rst b/doc/crypto/appendix/encodings.rst
index ad037ed5..b3b328d2 100644
--- a/doc/crypto/appendix/encodings.rst
+++ b/doc/crypto/appendix/encodings.rst
@@ -198,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``
@@ -207,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
diff --git a/doc/crypto/appendix/history.rst b/doc/crypto/appendix/history.rst
index f4040b80..1fbe1040 100644
--- a/doc/crypto/appendix/history.rst
+++ b/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
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/doc/crypto/references b/doc/crypto/references
index e0ad2166..2c2baeaf 100644
--- a/doc/crypto/references
+++ b/doc/crypto/references
@@ -359,3 +359,9 @@
     :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

From 7c2434d5f6995288eef21ae766d78545e92da124 Mon Sep 17 00:00:00 2001
From: Andrew Thoelke <andrew.thoelke@arm.com>
Date: Tue, 16 Jan 2024 17:50:52 +0000
Subject: [PATCH 4/7] Correct capitalization of Zigbee

---
 doc/crypto/api/ops/aead.rst       | 2 +-
 doc/crypto/api/ops/ciphers.rst    | 6 +++---
 doc/crypto/api/ops/hashes.rst     | 6 +++---
 doc/crypto/appendix/encodings.rst | 2 +-
 4 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/doc/crypto/api/ops/aead.rst b/doc/crypto/api/ops/aead.rst
index 7de01f30..f0053dcc 100644
--- a/doc/crypto/api/ops/aead.rst
+++ b/doc/crypto/api/ops/aead.rst
@@ -70,7 +70,7 @@ AEAD algorithms
 
     The CCM block cipher mode is defined in :RFC-title:`3610`.
 
-    .. subsection:: Usage in zigbee
+    .. subsection:: Usage in Zigbee
 
         `PSA_ALG_CCM`, and its truncated variants, can be used to implement CCM* for non-zero tag lengths. CCM* is required by the :cite-title:`ZIGBEE`. For unauthenticated CCM*, the `PSA_ALG_CCM_STAR_NO_TAG` cipher algorithm can be used.
 
diff --git a/doc/crypto/api/ops/ciphers.rst b/doc/crypto/api/ops/ciphers.rst
index 51b53ba4..e799a2ab 100644
--- a/doc/crypto/api/ops/ciphers.rst
+++ b/doc/crypto/api/ops/ciphers.rst
@@ -164,13 +164,13 @@ Cipher algorithms
 
     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.
 
-    .. subsection:: Usage in zigbee
+    .. 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.
+        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()`.
 
-            An implementation of zigbee cannot use the single-part cipher functions, as these generate a random IV, which is not valid for the zigbee protocol.
+            An implementation of Zigbee cannot use the single-part cipher functions, as these generate 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]`.
 
diff --git a/doc/crypto/api/ops/hashes.rst b/doc/crypto/api/ops/hashes.rst
index 8e9143ac..0703592e 100644
--- a/doc/crypto/api/ops/hashes.rst
+++ b/doc/crypto/api/ops/hashes.rst
@@ -77,15 +77,15 @@ Hash algorithms
     :definition: ((psa_algorithm_t)0x02000006)
 
     .. summary::
-        The *zigbee* 1.0 hash function based on a Matyas-Meyer-Oseas (MMO) construction of AES-128.
+        The *Zigbee* 1.0 hash function based on a Matyas-Meyer-Oseas (MMO) construction of AES-128.
 
-    zigbee specifies a cryptographic hash function based on the MMO hash construction using the AES-128 block cipher. This is defined in :cite-title:`ZIGBEE` §B.6.
+    Zigbee specifies a cryptographic hash function based on the MMO hash construction using the AES-128 block cipher. This is 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)`.
+        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)
diff --git a/doc/crypto/appendix/encodings.rst b/doc/crypto/appendix/encodings.rst
index b3b328d2..932918e4 100644
--- a/doc/crypto/appendix/encodings.rst
+++ b/doc/crypto/appendix/encodings.rst
@@ -116,7 +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), ``0x06``, `PSA_ALG_AES_MMO_ZIGBEE`, ``0x02000006``
+    AES-MMO (Zigbee), ``0x06``, `PSA_ALG_AES_MMO_ZIGBEE`, ``0x02000006``
     SHA-224, ``0x08``, `PSA_ALG_SHA_224`, ``0x02000008``
     SHA-256, ``0x09``, `PSA_ALG_SHA_256`, ``0x02000009``
     SHA-384, ``0x0A``, `PSA_ALG_SHA_384`, ``0x0200000A``

From c4154da8c44f96e6bf6d4c7e9b96cf7ee6089b08 Mon Sep 17 00:00:00 2001
From: Andrew Thoelke <andrew.thoelke@arm.com>
Date: Tue, 16 Jan 2024 19:02:33 +0000
Subject: [PATCH 5/7] Improve the notes on Zigbee usage

---
 doc/crypto/api/ops/aead.rst    | 7 ++++++-
 doc/crypto/api/ops/ciphers.rst | 8 +++++++-
 2 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/doc/crypto/api/ops/aead.rst b/doc/crypto/api/ops/aead.rst
index f0053dcc..ec21883e 100644
--- a/doc/crypto/api/ops/aead.rst
+++ b/doc/crypto/api/ops/aead.rst
@@ -72,7 +72,12 @@ AEAD algorithms
 
     .. subsection:: Usage in Zigbee
 
-        `PSA_ALG_CCM`, and its truncated variants, can be used to implement CCM* for non-zero tag lengths. CCM* is required by the :cite-title:`ZIGBEE`. For unauthenticated CCM*, the `PSA_ALG_CCM_STAR_NO_TAG` cipher algorithm can be used.
+        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
 
diff --git a/doc/crypto/api/ops/ciphers.rst b/doc/crypto/api/ops/ciphers.rst
index e799a2ab..20341d4e 100644
--- a/doc/crypto/api/ops/ciphers.rst
+++ b/doc/crypto/api/ops/ciphers.rst
@@ -164,16 +164,22 @@ Cipher algorithms
 
     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()`.
 
-            An implementation of Zigbee cannot use the single-part cipher functions, as these generate a random IV, which is not valid for the Zigbee protocol.
+            .. 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

From c40baabeffc666b02ffac34bbedc8208c502f6a9 Mon Sep 17 00:00:00 2001
From: Andrew Thoelke <andrew.thoelke@arm.com>
Date: Tue, 16 Jan 2024 20:58:58 +0000
Subject: [PATCH 6/7] Tweak encoding of AES-MMO algorithm identifier

---
 doc/crypto/api.db/psa/crypto.h    | 2 +-
 doc/crypto/api/ops/hashes.rst     | 2 +-
 doc/crypto/appendix/encodings.rst | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/crypto/api.db/psa/crypto.h b/doc/crypto/api.db/psa/crypto.h
index 7846d43b..f70d8ddd 100644
--- a/doc/crypto/api.db/psa/crypto.h
+++ b/doc/crypto/api.db/psa/crypto.h
@@ -47,7 +47,7 @@ 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)0x02000006)
+#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 */
diff --git a/doc/crypto/api/ops/hashes.rst b/doc/crypto/api/ops/hashes.rst
index 0703592e..e8fbc1b6 100644
--- a/doc/crypto/api/ops/hashes.rst
+++ b/doc/crypto/api/ops/hashes.rst
@@ -74,7 +74,7 @@ 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)0x02000006)
+    :definition: ((psa_algorithm_t)0x02000007)
 
     .. summary::
         The *Zigbee* 1.0 hash function based on a Matyas-Meyer-Oseas (MMO) construction of AES-128.
diff --git a/doc/crypto/appendix/encodings.rst b/doc/crypto/appendix/encodings.rst
index 932918e4..cd10ef39 100644
--- a/doc/crypto/appendix/encodings.rst
+++ b/doc/crypto/appendix/encodings.rst
@@ -116,7 +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), ``0x06``, `PSA_ALG_AES_MMO_ZIGBEE`, ``0x02000006``
+    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``

From 6c6ccf84cb54289aa5eaf5388b341e3e8a0b73ec Mon Sep 17 00:00:00 2001
From: Andrew Thoelke <andrew.thoelke@arm.com>
Date: Tue, 16 Jan 2024 21:05:29 +0000
Subject: [PATCH 7/7] Improve definition of PSA_ALG_AES_MMO_ZIGBEE

---
 doc/crypto/api/ops/hashes.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/crypto/api/ops/hashes.rst b/doc/crypto/api/ops/hashes.rst
index e8fbc1b6..d7d55d7f 100644
--- a/doc/crypto/api/ops/hashes.rst
+++ b/doc/crypto/api/ops/hashes.rst
@@ -77,9 +77,9 @@ Hash algorithms
     :definition: ((psa_algorithm_t)0x02000007)
 
     .. summary::
-        The *Zigbee* 1.0 hash function based on a Matyas-Meyer-Oseas (MMO) construction of AES-128.
+        The *Zigbee* 1.0 hash function based on a Matyas-Meyer-Oseas (MMO) construction using AES-128.
 
-    Zigbee specifies a cryptographic hash function based on the MMO hash construction using the AES-128 block cipher. This is defined in :cite-title:`ZIGBEE` §B.6.
+    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.