Add support for zigbee algorithms by athoelke · Pull Request #94 · ARM-software/psa-api

athoelke · 2023-08-10T22:10:08Z

Add support for algorithms required by zigbee:

MMO hash construction over AES-128
CCM* optionally-authenticated variant of CCM

This PR adds a new hash function, and an unauthenticated cipher for the zero-length tag variant of CCM*. For non-zero-length tags, the existing support for CCM is adequate.

Fixes #14
Fixes #15

MarcusJGStreets

Looks OK

athoelke · 2024-01-11T10:13:12Z

Rebased this PR.

Last call for feedback, before this is merged to prepare for v1.2 release candidate.

gilles-peskine-arm

Correctness: looks good to me. I've checked against the Zigbee specification and the Mbed TLS draft implementation of CCM_STAR_NO_TAG, but not against the IEEE CCM* specification.

Writing: I left a couple of requests and suggestions.

gilles-peskine-arm · 2024-01-16T15:18:48Z


    The CCM block cipher mode is defined in :RFC-title:`3610`.

+    .. subsection:: Usage in zigbee


Editorial: “Zigbee” should be capitalized. (It used to be “ZigBee”, but that stopped years ago; permanently-uncapitalized “zigbee” seems to be the organization logo, not the name of the protocol suite).

I've corrected all references except the document citation: the spec itself uses the uncapitalized form for its title and publisher.

gilles-peskine-arm · 2024-01-16T15:20:51Z

+
+        *   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.


Single-part encryption is out due to the non-random IV, but what's wrong with single-part decryption?

Although, technically, the single-part decryption function can be used for an implementation of Zigbee, in practice requires that the caller concatenate the 13-byte nonce and the cipher-text into a single memory buffer before calling the API.

But maybe there is no harm in making the explanatory text more precise.

gilles-peskine-arm · 2024-01-16T15:22:43Z


+    .. 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.


Please add a hyperlink to the discussion of Zigbee usage under PSA_ALG_CCM_STAR_NO_TAG, since that discussion covers both CCM and CCM*-no-tag.

gilles-peskine-arm · 2024-01-16T15:24:03Z

+
+            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]`.


Please also list PSA_ALG_CCM as usable when the tag length is 16. It's logically redundant, but not didactically redundant.

gilles-peskine-arm · 2024-01-16T15:49:53Z

    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)


Minor: it might conceivably make sense to define a SHA1 variant that forbids inputs which might be exploiting known collision weaknesses, due to SHA1's persisting use in protocols such as git. (Currently we aren't in a hurry to do that because that algorithm is not used in our typical domain space, and can't be implemented on constrained devices due to the high code size.) If we ever do that then it would be slightly more convenient to use hash 6 (since SHA-1 is 5). So MMO_ZIGBEE could be 7 instead.

Ok - we can recode this as 0x02000007.

This was not already defined in Mbed TLS, unlike PSA_ALG_CCM_START_NO_TAG.

gilles-peskine-arm · 2024-01-16T15:51:57Z

+    :definition: ((psa_algorithm_t)0x02000006)
+
+    .. summary::
+        The *zigbee* 1.0 hash function based on a Matyas-Meyer-Oseas (MMO) construction of AES-128.


Editorial: “construction on AES-128”? over AES-128?

Decided on 'using', seems to make sense with the rewording of the full description.

gilles-peskine-arm · 2024-01-16T15:56:32Z

+    .. 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.


“MMO construction using AES-128” is ambiguous since this is a theory-level definition which leaves some parameters open (padding, IV). The formulation here doesn't make it very clear that we mean the specific parametrization in the Zigbee specification. I suggest something like

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.

Thank you - I have adopted the revised wording.

gilles-peskine-arm

LGTM

athoelke · 2024-01-17T17:02:42Z

Rebased for merge

athoelke added enhancement New feature or request Crypto API Issue or PR related to the Cryptography API labels Aug 10, 2023

athoelke added this to the Crypto API 1.2 milestone Aug 10, 2023

athoelke requested review from MarcusJGStreets and gilles-peskine-arm August 10, 2023 22:10

MarcusJGStreets approved these changes Aug 14, 2023

View reviewed changes

athoelke force-pushed the crypto-zigbee branch from 9668ccf to 5737f1e Compare January 11, 2024 10:12

gilles-peskine-arm mentioned this pull request Jan 16, 2024

Implement PSA_ALG_CCM_STAR_ANY_TAG algorithm policy Mbed-TLS/mbedtls#8706

Open

gilles-peskine-arm requested changes Jan 16, 2024

View reviewed changes

athoelke requested a review from gilles-peskine-arm January 16, 2024 21:06

gilles-peskine-arm approved these changes Jan 17, 2024

View reviewed changes

athoelke added 7 commits January 17, 2024 17:01

Add citation for zigbee Specification

e442840

Add zigbee AES-MMO hash function

b2e13e3

Add support for CCM* as used in zigbee

21a3b8c

Correct capitalization of Zigbee

7c2434d

Improve the notes on Zigbee usage

c4154da

Tweak encoding of AES-MMO algorithm identifier

c40baab

Improve definition of PSA_ALG_AES_MMO_ZIGBEE

6c6ccf8

athoelke force-pushed the crypto-zigbee branch from 2e53f12 to 6c6ccf8 Compare January 17, 2024 17:02

athoelke merged commit 83cec43 into ARM-software:main Jan 17, 2024

athoelke deleted the crypto-zigbee branch January 18, 2024 15:01


		The CCM block cipher mode is defined in :RFC-title:`3610`.

		.. subsection:: Usage in zigbee


		* 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.


		.. 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.


		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]`.

Conversation

athoelke commented Aug 10, 2023

Uh oh!

MarcusJGStreets left a comment

Choose a reason for hiding this comment

Uh oh!

athoelke commented Jan 11, 2024

Uh oh!

gilles-peskine-arm left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

athoelke Jan 16, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gilles-peskine-arm left a comment

Choose a reason for hiding this comment

Uh oh!

athoelke commented Jan 17, 2024

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

athoelke Jan 16, 2024 •

edited

Loading