diff --git a/doc/crypto/api.db/psa/crypto.h b/doc/crypto/api.db/psa/crypto.h index cc2e5ffc..f70d8ddd 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)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 */ @@ -54,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..ec21883e 100644 --- a/doc/crypto/api/ops/aead.rst +++ b/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 ` under `PSA_ALG_CCM_STAR_NO_TAG`. + .. 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..20341d4e 100644 --- a/doc/crypto/api/ops/ciphers.rst +++ b/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 */ diff --git a/doc/crypto/api/ops/hashes.rst b/doc/crypto/api/ops/hashes.rst index 388d6249..d7d55d7f 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)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) diff --git a/doc/crypto/appendix/encodings.rst b/doc/crypto/appendix/encodings.rst index 1760d731..cd10ef39 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), ``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 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 2b65b65d..2c2baeaf 100644 --- a/doc/crypto/references +++ b/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