Add definitions required by WPA3-SAE and WPA3-SAE-PT

[oberon-sk]

The PSA Certified Crypto API v1.2 PAKE Extension requires some additional definitions to support WPA3-SAE and WPA3-SAE-PT as defined in IEEE standard specification P802.11-REVme/D7.0, Part 11, Aug 2024 to be embedded in, or included by, psa/crypto.h.

This PR provides a proposal.

[athoelke]

The 2024 update to 802.11 is now finalized (late September) - I presume that contains all of the required specification now?

[oberon-sk]

The 2024 update to 802.11 is now finalized (late September) - I presume that contains all of the required specification now?

IEEE Std 802.11™-2024 was approved on September 26, 2024. Publication expected soon.

[athoelke]

Thank you for contributing these definitions. I would like to suggest some changes to the proposal:

1. A different name for the KDF used to calculate the password token from the password.
2. A different encoding of the password-token key types

Password-token KDF name

In WPA3-SAE, the password token is computed using the hash-to-element procedure. My suggestion is to name the KDF after the procedure, rather than the result:

#define PSA_ALG_WPA3_SAE_H2E(hash_alg) ((psa_alogrithm_t) 0x08800400 | (0xff & hash_alg))

I presume the selection of the hash algorithm should follow the 802.11 specification, and match with the hash in the selected WPA3-SAE ciphersuite.

Password token keys

There are two separate issues to address here:

1. The password token (PT) in WPA3-SAE is a group element, which is also the structure of an asymmetric public key in the same group. Which I guess is why the proposal encodes the password-token key as an asymmetric public key?

   However, for WPA3-SAE, the PT is not part of an asymmetric key, so a different key type encoding would be preferred. But, unlike other key types in the Symmetric key category (key_type & 0xf000 == 0x2000), a PT key is not just unstructured bytes of key material, so that is also not preferred.

   I suggest that we allocate the currently unused encodings key_type & 0xf000 == 0x3000 for 'structured keys' [that are not key-pairs or parts of key pairs].

   To be able to directly use the DH and ECC 'family' encodings, the final 12 bits would be split, similarly to Asymmetric keys, into a 5-bit structured-key-type value, a 6-bit family, and the 1-bit parity P bit.

2. The proposal allocates DH and ECC groups into the same key type. This just happens to work with the current specification because none of the allocated DH and ECC family values collide. However, the intention for these families is to be independently allocated, which includes the possibility of overlap in future.

   To preserve the intended independence, the password-token key types for DH-based WPA3-SAE and ECC-based WPA3-SAE need to have distinct encodings. To reuse the family encodings for ECC and DH keys, we need to match parity in the most-significant 9 bits with the ECC and DH key types. This means that the structured-key-type value must have an even number of 1-bits for both ECC and DH.

   I suggest we allocate a structured-key-type of 5 for ECC and 6 for DH:

   • The ECC-based WPA3-SAE password token key encoding would be 0x3000 | (5 << 7) | ec_family
   • The DH-based WPA3-SAE password token key encoding would be 0x3000 | (6 << 7) | dh_family

We also need to qualify the key type identifiers by group type. My suggestion would be:

#define PSA_KEY_TYPE_WPA3_SAE_ECC_PT(ec_family) ((psa_key_type_t)(0x3280 | (ec_family)))
#define PSA_KEY_TYPE_WPA3_SAE_DH_PT(dh_family)  ((psa_key_type_t)(0x3300 | (dh_family)))

[oberon-sk]

Questioning the value in explicitly specifying the hash parameter.

An implementation that only supports the standard can determine the correct hash function from the cyclic group and PWE-generation method.

We used the hash parameter for consistency with the PSA_ALG_WPA3_SAE_PT KDF and other PAKE algorithms. We agree it is not strictly necessary.

[athoelke]

Questioning the value in explicitly specifying the hash parameter. An implementation that only supports the standard can determine the correct hash function from the cyclic group and PWE-generation method.

We used the hash parameter for consistency with the PSA_ALG_WPA3_SAE_PT KDF and other PAKE algorithms. We agree it is not strictly necessary.

My inclination at this point is to remove the explicit parameterization - because it provides no benefit to the caller of the API, but does incur cost to the caller in determining what the correct value should be.

[athoelke]

The effect of the incremental changes to WPA3-SAE (2016 -> 2020 -> 2024) is that there are notionally 3 distinct variants:

1. PWE generation by looping, using SHA-256 as H() for all cipher suites. len(PMK) = len(KCK) = 256
2. PWE generation using hash-to-element, determining H() from the size of the group prime. len(PMK) = 256. len(KCK) = len(H())
3. PWE generation using hash-to-element, determining H() from the size of the group prime. len(PMK) = len(KCK) = len(H())

At the moment, the proposal defines one algorithm for (1) and (2), differentiating by the key type of the key that is passed in to set up the PAKE operation. And a second algorithm for (3), to separate it from (2).

Would the API be clearer if we gave all three their own algorithm identifier instead?

[athoelke]

The 802.11-2024 specification suggests that for devices might support both looping and H2E methods for generating the PWE - and the method selected can vary between authentication instances.

That means the password must be usable with both the PSA_ALG_WPA3_SAE_FIXED algorithm in a PAKE operation (for looping method); and with the PSA_ALG_WPA3_SAE_H2E algorithm in a key derivation operation. A key of type PSA_KEY_TYPE_PASSWORD, cannot permit both of these algorithms. Do we need a wildcard algorithm for these keys?

A PSA_KEY_TYPE_WPA3_SAE_XX_PT key might be used with both PSA_ALG_WPA3_SAE_FIXED and PSA_ALG_WPA3_SAE_GDH, as these only differ in the size of the output PMK (and thus the KCK and PMK values). Do we need a wildcard algorithm for the password token keys?

[athoelke]

My inclination at this point is to remove the explicit parameterization - because it provides no benefit to the caller of the API, but does incur cost to the caller in determining what the correct value should be.

Spoke too soon - before you explained the benefit of knowing the Hash to start computing HKDF prior to knowing the cyclic group from the output key type.

[oberon-sk]

My inclination at this point is to remove the explicit parameterization - because it provides no benefit to the caller of the API, but does incur cost to the caller in determining what the correct value should be.

Spoke too soon - before you explained the benefit of knowing the Hash to start computing HKDF prior to knowing the cyclic group from the output key type.

The hash is strictly required only in the KDF algorithm. However, we would prefer if the parameterization would be used in both, the KDF algorithm and the PAKE algorithm.

[oberon-sk]

The effect of the incremental changes to WPA3-SAE (2016 -> 2020 -> 2024) is that there are notionally 3 distinct variants:

1. PWE generation by looping, using SHA-256 as H() for all cipher suites. len(PMK) = len(KCK) = 256

2. PWE generation using hash-to-element, determining H() from the size of the group prime. len(PMK) = 256. len(KCK) = len(H())

3. PWE generation using hash-to-element, determining H() from the size of the group prime. len(PMK) = len(KCK) = len(H())

At the moment, the proposal defines one algorithm for (1) and (2), differentiating by the key type of the key that is passed in to set up the PAKE operation. And a second algorithm for (3), to separate it from (2).

Would the API be clearer if we gave all three their own algorithm identifier instead?

We do not see an advantage in introducing another algorithm identifier.

[oberon-sk]

The 802.11-2024 specification suggests that for devices might support both looping and H2E methods for generating the PWE - and the method selected can vary between authentication instances.

That means the password must be usable with both the PSA_ALG_WPA3_SAE_FIXED algorithm in a PAKE operation (for looping method); and with the PSA_ALG_WPA3_SAE_H2E algorithm in a key derivation operation. A key of type PSA_KEY_TYPE_PASSWORD, cannot permit both of these algorithms. Do we need a wildcard algorithm for these keys?

A PSA_KEY_TYPE_WPA3_SAE_XX_PT key might be used with both PSA_ALG_WPA3_SAE_FIXED and PSA_ALG_WPA3_SAE_GDH, as these only differ in the size of the output PMK (and thus the KCK and PMK values). Do we need a wildcard algorithm for the password token keys?

Agreed. Both wildcards are needed to allow to use stored passwords and PT keys in all cases.

[athoelke]

I've now turned this into a complete documention PR (#293), which tries to include all of the contribution and discussion from here.

The result is similar to this proposal, but has the following differences:

1. The password token keys are a new category of key: 'structured'. They are not key pairs, so this approach makes better use of key type encoding space.
2. ECC and DH groups are encoded in a single family encoding - so to avoid future issues, there are separate password token keys for ECC and DH primitives.
3. The KDF for hash-to-element has a different name PSA_ALG_WPA3_SAE_H2E().
4. The commit values are output and input from the operation as separate steps, PSA_PAKE_STEP_KEY_SHARE is reused for the element values, PSA_PAKE_STEP_COMMIT_SCALAR is added for the scalar.

There are some open issues, including the handling of the commit values, the naming of the key types, and whether wildcard permitted-algorithm key policies are needed for the WPA3-SAE use cases.

[athoelke]

Closed, as this proposal is now superseded by #293.