Add support for the WPA3-SAE PAKE (part of 802.11)

[athoelke]

This is the full documentation PR for WPA3-SAE, building on the outline for the API in #230 contributed by Oberon.

It provides support for all cipher-suites and operational variants that are defined in IEEE-802.11-2024 §12.4:

• Password element derivation via looping or use of the hash-to-element procedure
• Fixed-size or group-dependent-hash-sized Key confirmation key (SAE-KCK) and Pairwise master key (PMK)
• Elliptic curve and finite field PAKE primitives

Open items

• 1. The password token key type names currently have a _PT suffix, following the contributed design. This is not required to distinguish the types, as there are no non-password-token key types for WPA3-SAE. I suggest removing them.

• 2. Done

• 3. Done

• 4. The evolution of the WPA3-SAE protocol over 3 versions of IEEE-802.11 results in the password value being used in more than one type of algorithm:

  • If the looping method is used, the password is passed directly to the PAKE operation using PSA_ALG_WPA3_SAE_FIXED(PSA_ALG_SHA256).
  • If the hash-to-element or group-dependent-hash variants are used, the password is used in a PSA_ALG_WPA3_SAE_H2E() KDF operation, parameterized by a hash related to the PAKE primitive in use.

  Either we will require the application (the 802.11 implementation of SAE) to store the password, and import a volatile password key with an appropriate policy once the variant and cipher suite is determined; or we would need a wildcard algorithm identifier for use in the password key policy.

  It might be sufficient to permit PSA_ALG_ANY_HASH to be used in PSA_ALG_WPA3_SAE_H2E() as a wildcard policy when using the password to derive the password token, and not provide support for looping vs hash-to-element use of a password key?

• 5. A password token that is derived through the hash-to-element procedure is specific to the PAKE primitive (type of cyclic group, selected family, and size). The same password token can be used in both the PSA_ALG_WPA3_SAE_FIXED() and PSA_ALG_WPA3_SAE_GDH() algorithms - noting that the hash algorithm is effectively determined by the PAKE primitive.

  Is it valuable to have a wildcard permitted-algorithm policy for WPA3-SAE password token keys, so that the same key could be used in either the fixed-sized or group-dependent-hash-sized variants of WPA3-SAE?

Fixes #203

[athoelke]

@stevew817, @oberon-sk - as previous requesters of this functionality:

1. Sorry about the delay in finishing the PR
2. Please can you review the API definition and provide some feedback on the open issues above.

Do you have specific use cases that would help to determine the answer for open issues 2, 4, and 5?

[athoelke]

Ooops! - The following comment by @bheeb was a response to a mispost by me on the wrong PR. Copied to this PR to ensure it is addressed here.

I am dusting off my 75%-complete PR for adding this to the specification, and have a small number of things to resolve:

1. Key formats. The Password token key is expected to be stored and used - there is no WPA3-related use case to export or import these items. (This key is constructed via derivation from the shared password, for later use in the PAKE operation). I plan to define the import/export format as implementation-specific.
   We could instead make export/import invalid, or define the format (as being the same as the public key of the cyclic group (ECC or FFDH) for which the password token is computed.

An implementation specific import/export format is problematic because the standard export format is also the standard key format used by the driver.
Key import/export is needed for testing. Without import/export it is impossible to use known answer tests to validate the algorithms.
We would prefer to use a point format without the leading 0x04 for ECC keys to keep it aligned with the format used in the Commit step.

2. Key exchange (commit) phase inputs and outputs. WPA3-SAE exchanges a scalar (integer modulo group prime) and a group element during the first part of the exchange. These are packaged in separate fields within the commit messages.
   To align with J-PAKE, the commit-scalar and COMMIT-ELEMENT values should require two calls to the pake output and input functions. The scalar would need a new step type value, e.g. PSA_PAKE_STEP_COMMIT_VALUE, but the ELEMENT could reuse the existing PSA_PAKE_STEP_KEY_SHARE, with a small caveat.
   The group element in the WPA3-SAE commit message is formatted very similarly to the cyclic group public key format. For FFDH it is the same. For ECC the element format is the concatenation of the x and y coordinates encoded as non-truncated big-endian integers, which is the same as the uncompressed Weierstrass public key in SEC1, but without the `0x04` prefix octet. The documentation for PSA_PAKE_STEP_KEY_SHARE currently says that the input/output format is the same as the public key format. We could leave as is (and force applications to add/remove the `0x04` prefix); make the format of this step dependent on the PAKE algorithm (and remove the prefix for WPA3-SAE); or add a new PAKE step for the WPA3-SAE COMMIT-ELEMENT.
   An entirely different approach would be to encode both commit-scalar and COMMIT-ELEMENT in a single input/output step, and have the application split these on output, or concatenate on input when processing the WPA3-SAE 802.11 frames.

We would like to use the approach with the scalar and the element (without the 0x04) in a single input/output step. There is no need for splitting or concatenation in the application, the combination of the two can be copied directly to/from the WPA3-SAE 802.11 frame.
An additional question is whether we should add the "Finite Cyclic Group" field in front of the scalar and element fields. This could as well be added by the application but we would prefer to include it to make the data more self consistent.

A similar question arises in the Confirm step: should we include the Send-Confirm field in front of the Confirm value?
Including it makes the handling of the input step easier because all relevant values are in the input data. For the output however, a separate input step is needed for the Send-Confirm value because it must be provided by the application.
If the Send-Confirm field is not included in the Confirm step. it must be provided in a separate Send-Confirm input step for the both the Confirm input and output steps because it is needed for the calculation of the Confirm value.
We would prefer to include the Send-Confirm values.

3. Ordering: it seems that the commitment outputs and inputs could occur in any order (e.g. the peer values can be input before extracting the commitment outputs); likewise for the confirmation values (although the counter has to be set prior to output of the confirmation value); the salt could in theory be input at any time before the confirmation phase starts; and the key id can be output at any time after the commitment phase is complete. However, requiring flexibility might be costly for an implementation, but demanding a rigid ordering may also add costs for an application and unnecessary validation overheads in an implementation. Is there a sweet spot?

To keep the implementation simple, we currently use the following rules:
After psa_pake_setup(), psa_pake_set_user(), and psa_pake_set_peer() there is a Commit phase with all Commit inputs and outputs in any order.
Then there is a Confirm phase with all other steps (Salt, Send-Confirm, Confirm, KeyId) in any order except that Salt and Send-Confirm must be supplied before the corresponding Confirm.
Providing Salt or Send-Confirm before or during the Commit phase does not bring any advantage for the application.
Be aware that the Confirm steps may be used multiple times with varying Send-Confirm values.

[athoelke]

@bheeb - thanks for the feedback (via my misposted questions in #178).

On ordering (comment item 3)

The current text basically reflects this approach, although I have not specified flexibility in providing the salt value after the send-confirm counter value. Mostly because the latter might be done multiple times in case of lost confirmation frames - so easiter to specify that salt is provided just once between the commit and confirm phases.

On export key format (comment item 1/PR open issue 2)

Testability is good enough reason to define the format for the password token, implementing support for exportable password tokens is then an implementation decision. Using the same format as that used for COMMIT-ELEMENT makes sense (as defined in 802-11 §12.4.7.2).

On Commit-phase PAKE steps (comment item 2/PR open issue 3)

I've read the details of the 802-11 frame formats for authentication, which does indicate that the commit-scalar and COMMIT-ELEMENT values are adjacent in the frame body for all messages in which they appear, and that the size of these elements is fixed by the PAKE primitive being used.

If we defined a PSA_PAKE_STEP_COMMIT to be the concatenation commit-scalar || COMMIT-ELEMENT, it could be output directly into, or input directly from, the SAE frame buffer, without needing an intermediate copy to assemble/disassemble the two values. So my objection to this approach is gone, and think this is a sound approach.

I would prefer to not include the Finite Cyclic Group value in the input or output for two reasons:

1. This is not part of the parameter set used in the API for WPA3-SAE, we use the existing PAKE primitive definition to communicate this. The application already has to map between 802-11 enumerations and PSA encodings for this, and I don't think it is valuable to also add such a mapping inside the PAKE implementation.
2. In some cases, the Finite Cyclic Group field is not adjacent to the Scalar and FFE fields, when an Anti-Clogging Token field has to be provided in a retry of a commit frame. An output/input that concatenated all three fields would not always be usable directly from the SAE frame buffer.

[athoelke]

I've update the PR to incorporate those changes (and updated the PR description to remove the related open issues).

We now need to conclude on the key type name and wildcard items.

[oberon-sk]

1. The password token key type names currently have a _PT suffix, following the contributed design. This is not required to distinguish the types, as there are no non-password-token key types for WPA3-SAE. I suggest removing them.

Removing them should be fine.

4. The evolution of the WPA3-SAE protocol over 3 versions of IEEE-802.11 results in the password value being used in more than one type of algorithm:

• If the looping method is used, the password is passed directly to the PAKE operation using PSA_ALG_WPA3_SAE_FIXED(PSA_ALG_SHA256).
• If the hash-to-element or group-dependent-hash variants are used, the password is used in a PSA_ALG_WPA3_SAE_H2E() KDF operation, parameterized by a hash related to the PAKE primitive in use.

Either we will require the application (the 802.11 implementation of SAE) to store the password, and import a volatile password key with an appropriate policy once the variant and cipher suite is determined; or we would need a wildcard algorithm identifier for use in the password key policy.
It might be sufficient to permit PSA_ALG_ANY_HASH to be used in PSA_ALG_WPA3_SAE_H2E() as a wildcard policy when using the password to derive the password token, and not provide support for looping vs hash-to-element use of a password key?

Yes, permitting PSA_ALG_ANY_HASH is sufficient.

5. A password token that is derived through the hash-to-element procedure is specific to the PAKE primitive (type of cyclic group, selected family, and size). The same password token can be used in both the PSA_ALG_WPA3_SAE_FIXED() and PSA_ALG_WPA3_SAE_GDH() algorithms - noting that the hash algorithm is effectively determined by the PAKE primitive.
   Is it valuable to have a wildcard permitted-algorithm policy for WPA3-SAE password token keys, so that the same key could be used in either the fixed-sized or group-dependent-hash-sized variants of WPA3-SAE?

Probably yes.

[athoelke]

Thinking about the wildcard policies:

• For H2E, it would be sufficient to permit PSA_ALG_WPA3_SAE_H2E(PSA_ALG_ANY_HASH) so that a password could be used with H2E for any WPA3 ciphe-suite
• For the password token being used with either the FIXED or GDH variants of WPA3-SAE, we could minimally define PSA_ALG_WPA3_SAE_ANY(hash_alg), and require a specific hash algorithm.

This does not enable a single password key object to be used for both H2E and Looping derivation methods (the latter passes the password directly to the PAKE).

However, there are strict constraints already in place on which hash algorithm must be used in both the H2E KDF and the WPA3-SAE PAKE algorithms (they must match a valid cipher suite that is based on the PAKE primitive's cyclic group). Thus defining a wildcard key policy that appears to be more relaxed, does not actually permit additional usage.

Instead we could just define a single PSA_ALG_WPA3_SAE_ANY wildcard key policy that can be used:

1. With password keys, for use with a PSA_ALG_WPA3_SAE_H2E() KDF, or with a PSA_ALG_WPA3_SAE_FIXED() PAKE.
2. With WP3-SAE password token keys, for use with a PSA_ALG_WPA3_SAE_FIXED() or PSA_ALG_WPA3_SAE_GDH() PAKE. The hash is fully determined by the key type/size (which must match the PAKE primitive) - no real benefit to parameterize the policy.

[athoelke]

Instead we could just define a single PSA_ALG_WPA3_SAE_ANY wildcard key policy that can be used:

1. With password keys, for use with a PSA_ALG_WPA3_SAE_H2E() KDF, or with a PSA_ALG_WPA3_SAE_FIXED() PAKE.
2. With WP3-SAE password token keys, for use with a PSA_ALG_WPA3_SAE_FIXED() or PSA_ALG_WPA3_SAE_GDH() PAKE. The hash is fully determined by the key type/size (which must match the PAKE primitive) - no real benefit to parameterize the policy.

That leads to a question of what value to use. It cannot match both the KDF and the PAKE category, but we have a precedent that suggests that the PSA_ALG_IS_XXX() category macros do not necessarily work on wildcards: PSA_ALG_CCM_STAR_ANY_TAG is in the cipher category, with a distinct encoding value to the CCM* algorithms (it is PSA_ALG_CCM_STAR_NO_TAG | (1UL<<15)) - but this also permits the PSA_ALG_CCM AEAD algorithm.

We could use a distinct value in the PAKE category, that is perhaps related to the PAKE algorithms. For example 0x0a0088ff, which is PSA_ALG_WPA3_SAE_FIXED(PSA_ALG_ANY_HASH) | (1UL<<15). This follows both patterns in other wildcards: use bit 15 to indicate a wildcard value (AEAD and MAC at-least-this-length-tag), and use a hash encoding of 0xff (signature any-hash wildcards).