[DRAFT v1] Define the SPAKE2+ algorithms #126

athoelke · 2023-11-15T22:17:42Z

[Edited] : This is the first draft. An revised and reorganised version of this PR is now available: #129

This PR merges the 'best guess' result of the other PAKE and SPAKE2+ PRs (#114, #119, #120, #124), before defining the SPAKE2+ algorithms.

The Algorithm definition begins in commit e784de8, in case you have reviewed the other pieces already.

For a draft of the whole spec: Crypto_API-1.2_PAKE_Extension-bet.2-draft-spake2plus.pdf

DO NOT MERGE

There remain open issues in the preceding PRs. Once there is broad agreement on the open API design issues, I will merge the PR changes, to permit a second pass editorial review and rework of the result.

I am not convinced that the document structure is quite right. SPAKE2+ benefits from significant explanatory text for how the keys, algorithms, and operation work together - but this material is shared by three algorithm and two key API identifiers, and is currently somewhat scattered. This material cannot be delegated to other sources (as is the case for most other algorithms in the API), because the asymmetric key approach used here is novel, and we [reasonably] constrain some SPAKE2+ options in order to conform to the Matter specification.

* Add key encodings * Define public key format * Define key derivation procedure

* Moved the hash algorithm parameter to the PAKE cipher suite into the PAKE algorithm identifier, instead of a separate attribute of the cipher suite. * This also makes the hash algorithm value available to the `PSA_PAKE_OUTPUT_SIZE()` and `PSA_PAKE_INPUT_SIZE()` macros.

* Replace psa_pake_get_implicit_key() with psa_pake_get_shared_key() * Add key confirmation attribute to the PAKE cipher suite

* The shared secret is always output as a single key * Removed the input key size, key size is determined by operation * Removed key-size helper macro as unnecessary

* Recognise that not all PAKE algorithms produce a secret that is suitable for use as an encryption key * Encourage the use of PAKE output as a key-derivation key

* Supporting both RFC 9393 and Matter * New APIs: - `PSA_ALG_SPAKE2P_HMAC()` - `PSA_ALG_SPAKE2P_CMAC()` - `PSA_ALG_SPAKE2P_MATTER` - `PSA_ALG_IS_SPAKE2P()` - `PSA_ALG_IS_SPAKE2P_HMAC()` - `PSA_ALG_IS_SPAKE2P_CMAC()`

athoelke · 2023-11-15T22:26:21Z

@silabs-Kusumit, @silabs-hannes, @oberon-sk, @yanesca: this might be the PR you have been waiting for?

athoelke · 2023-11-22T15:13:28Z

Reviewing the flow:

It seems slightly odd that the key is provided during the psa_pake_setup(), and the role is set afterward, even though the role (for SPAKE2+) dictates what kind of key can be used. For example, if the operation is setup with a SPAKE2+ public key, then a subsequent call to psa_pake_set_role(..., PSA_PAKE_ROLE_CLIENT) would have to fail with PSA_ERROR_INVALID_ARGUMENT.

It seems it might feel more logical for the role to be declared as part of the setup (see #115 where the key input was moved to the setup function) so the combination of cipher-suite, key and role can be validated together.

On the other hand, it is possible to call psa_pake_set_role() with other roles (e.g. PSA_PAKE_ROLE_FIRST), that are invalid for the cipher-suite. So maybe this is not as odd as it first seemed to me?

silabs-Kusumit · 2023-11-23T10:40:57Z

I think that psa_pake_set_role() should be a separate function from psa_pake_setup(). The set_role() function is similar to set_user(), set_peer() functions and it doesn't feel right to add set_role to the setup function for only one PAKE algorithm.

silabs-Kusumit · 2023-11-27T14:08:51Z

doc/ext-pake/api/pake.rst

+
+The SPAKE2+ key types can be output from a key derivation using :code:`psa_key_derivation_output_key()`. The SPAKE2+ protocol recommends that a key-stretching kdf, such as PBKDF2, is used to hash the SPAKE2+ password. See RFC 9383 for details.
+
+For example, after setting up the PBKDF2 operation, the following process will derive the SPAKE2+ key pair for use with the P-256 Elliptic curve group :issue:`(This example may be more than necessary in the specification?)`:


We can add the flow with exact steps in the registration phase diagram. And reference the same here.

This is what I have done in Draft-2, as part of the reorganisation. See #129

silabs-Kusumit · 2023-11-27T14:19:17Z

doc/ext-pake/api/pake.rst

+*   A SPAKE2+ public key is the pair (w0, L).
+
+.. todo::
+    Would a table of required w0s/w1s lengths for each of the supported SPAKE2+ elliptic curve groups be useful here?


I think the table would be helpful for implementations

I have done this in the updated #119, and so in Draft-2 (#129).

silabs-Kusumit · 2023-11-27T15:48:56Z

I am not convinced that the document structure is quite right. SPAKE2+ benefits from significant explanatory text for how the keys, algorithms, and operation work together - but this material is shared by three algorithm and two key API identifiers, and is currently somewhat scattered. This material cannot be delegated to other sources (as is the case for most other algorithms in the API), because the asymmetric key approach used here is novel, and we [reasonably] constrain some SPAKE2+ options in order to conform to the Matter specification.

Maybe adding a document in the appendix folder for the details on SPAKE2+ would be helpful

athoelke · 2023-11-29T19:09:07Z

Maybe adding a document in the appendix folder for the details on SPAKE2+ would be helpful

I've thought about this a bit more, and think there are approximately three main ways to slice this:

Split the API definition into three parts: SPAKE2+ section, JPAKE section, common section.

The algorithm-specific sections would provide an introduction to the protocol, how to use the API for the protocol (the flows), the key types, formats & derivations; and the algorithm identifiers. The common section would provide the definition of the shared parts of the API (primitives, cipher-suites, roles, and the operation itself).

Given that the protocol descriptions only make proper sense with an understanding of the common API, it might be better to define the common section first, and then introduce the protocols?
Maintain something like the first draft, where the how-to for a protocol is described as part of the various elements that make it up.
Move the how-to material to an appendix.

The last option would mostly work in this Extension specification. However, when integrated into the main specification, I would be concerned that they would become detached from the PAKE API definition, and lose value as a result.

On the whole I have been trending toward moving the summaries for each category of algorithm into the section that defines that API. For example, the change in v1.1 where most of that material from the Functionality overview was moved into the intro to each cryptographic operation section of the API.

I'm going to draft something like (1) above for the next revision, to see how that looks...

athoelke · 2024-01-10T15:34:48Z

This PR has been superseded by the alternative document layout in the [v2] PR #129.

athoelke added 18 commits November 3, 2023 12:14

Add new asymmetric key types for SPAKE2+

b593449

* Add key encodings * Define public key format * Define key derivation procedure

Add a PAKE step for input and output of key confirmation

09f5f55

Add psa_pake_set_context()

3390fc8

pake: change the key output function

8982329

* Replace psa_pake_get_implicit_key() with psa_pake_get_shared_key() * Add key confirmation attribute to the PAKE cipher suite

Update J-PAKE flow graphic

8fb03e4

Reversed the definitions for PAKE key confirmation values

65dab72

Fix typo

4fe9d49

Tidy up resolved issues.

2e780a9

Removed uncertainty about behavior or psa_pake_get_shared_key()

0540976

* The shared secret is always output as a single key * Removed the input key size, key size is determined by operation * Removed key-size helper macro as unnecessary

Removed redundant (legacy) paragraph

2774133

Specify key types output by psa_pake_get_shared_key()

9d4f2c0

* Recognise that not all PAKE algorithms produce a secret that is suitable for use as an encryption key * Encourage the use of PAKE output as a key-derivation key

Update copyrights

4f3c56f

Merge branch 'pake-get-shared-key' into pake-spake2p

23ffab8

Merge branch 'pake-SIZE-macros-v2' into pake-spake2p

cf4e681

Merge branch 'pake-spake2p-support' (early part) into pake-spake2p

26e3be1

Merge branch 'pake-spake2p-keys' into pake-spake2p

6bb2d15

Added SPAKE2+ algorithms

e784de8

* Supporting both RFC 9393 and Matter * New APIs: - `PSA_ALG_SPAKE2P_HMAC()` - `PSA_ALG_SPAKE2P_CMAC()` - `PSA_ALG_SPAKE2P_MATTER` - `PSA_ALG_IS_SPAKE2P()` - `PSA_ALG_IS_SPAKE2P_HMAC()` - `PSA_ALG_IS_SPAKE2P_CMAC()`

athoelke added enhancement New feature or request API design Related the design of the API Crypto API Issue or PR related to the Cryptography API DO NOT MERGE labels Nov 15, 2023

athoelke added this to the Crypto API 1.2 PAKE Extension milestone Nov 15, 2023

athoelke requested review from gilles-peskine-arm, ndevillard and MarcusJGStreets November 15, 2023 22:17

athoelke self-assigned this Nov 15, 2023

silabs-Kusumit reviewed Nov 27, 2023

View reviewed changes

athoelke mentioned this pull request Dec 1, 2023

[v2] Define the SPAKE2+ algorithms #129

Merged

athoelke changed the title ~~Define the SPAKE2+ algorithms~~ [DRAFT v1] Define the SPAKE2+ algorithms Dec 1, 2023

athoelke marked this pull request as draft December 4, 2023 15:44

athoelke closed this Jan 10, 2024

athoelke deleted the pake-spake2p branch January 10, 2024 15:34

athoelke removed this from the Crypto API 1.2 PAKE Extension Beta-2 milestone Jan 10, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[DRAFT v1] Define the SPAKE2+ algorithms #126

[DRAFT v1] Define the SPAKE2+ algorithms #126

athoelke commented Nov 15, 2023 •

edited

Loading

athoelke commented Nov 15, 2023

athoelke commented Nov 22, 2023

silabs-Kusumit commented Nov 23, 2023

silabs-Kusumit Nov 27, 2023 •

edited

Loading

athoelke Dec 1, 2023 •

edited

Loading

silabs-Kusumit Nov 27, 2023

athoelke Dec 1, 2023

silabs-Kusumit commented Nov 27, 2023

athoelke commented Nov 29, 2023

athoelke commented Jan 10, 2024


		The SPAKE2+ key types can be output from a key derivation using :code:`psa_key_derivation_output_key()`. The SPAKE2+ protocol recommends that a key-stretching kdf, such as PBKDF2, is used to hash the SPAKE2+ password. See RFC 9383 for details.

		For example, after setting up the PBKDF2 operation, the following process will derive the SPAKE2+ key pair for use with the P-256 Elliptic curve group :issue:`(This example may be more than necessary in the specification?)`:

[DRAFT v1] Define the SPAKE2+ algorithms #126

[DRAFT v1] Define the SPAKE2+ algorithms #126

Conversation

athoelke commented Nov 15, 2023 • edited Loading

DO NOT MERGE

athoelke commented Nov 15, 2023

athoelke commented Nov 22, 2023

silabs-Kusumit commented Nov 23, 2023

silabs-Kusumit Nov 27, 2023 • edited Loading

Choose a reason for hiding this comment

athoelke Dec 1, 2023 • edited Loading

Choose a reason for hiding this comment

silabs-Kusumit Nov 27, 2023

Choose a reason for hiding this comment

athoelke Dec 1, 2023

Choose a reason for hiding this comment

silabs-Kusumit commented Nov 27, 2023

athoelke commented Nov 29, 2023

athoelke commented Jan 10, 2024

athoelke commented Nov 15, 2023 •

edited

Loading

silabs-Kusumit Nov 27, 2023 •

edited

Loading

athoelke Dec 1, 2023 •

edited

Loading