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

[athoelke]

I am starting to write this up for a draft PR against the specification, and a number of small details have emerged. Please see the the specific comments and questions.

[athoelke]

In other KDFs, we typically use a SECRET input step for high-entropy secrets, and prefer to use a PASSWORD input step to indicate a low-entropy secret (such as a password). As the password for an SSID in WPA3 is typically a low entropy value, I would prefer to use PSA_KEY_DERIVATION_INPUT_PASSWORD for this element.

[oberon-sk]

Agreed. We already use PSA_KEY_DERIVATION_INPUT_PASSWORD but the comment on PSA_ALG_WPA3_SAE_PT was wrong.

[athoelke]

Thank you for confirming

[athoelke]

Can/should we specify that if the selected hash does not match the one specified in §12.4.2 in the IEEE specification (SHA256 for generation of PWE by looping, following Table 12-1 for generation using hash-to-curve), the algorithm identifier will be rejected as invalid?

This might be detected during password-token generation (the hash in the H2E KDF dos not match the cyclic group specified in the output key type); or during PAKE protocol flow if the hash WPA3-SAE algorithm identifier does not match with the cyclic group specified in the PAKE primitive.

[oberon-sk]

Can/should we specify that if the selected hash does not match the one specified in §12.4.2 in the IEEE specification (SHA256 for generation of PWE by looping, following Table 12-1 for generation using hash-to-curve), the algorithm identifier will be rejected as invalid?

Agreed.

This might be detected during password-token generation (the hash in the H2E KDF dos not match the cyclic group specified in the output key type); or during PAKE protocol flow if the hash WPA3-SAE algorithm identifier does not match with the cyclic group specified in the PAKE primitive.

We think it should be during password-token generation.

[athoelke]

We think it should be during password-token generation

Yes. I think I meant to say that the verification should occur in both places, not a choice of one or the other.

[athoelke]

But this is only true if we keep the parameterization (see later comments)

[athoelke]

Presumably the user and peer identities for WPA3-SAE are the STA-A-MAC and STA-B-MAC values? Is the format of these evident? - or would a reference to the format of these values within 802.11 by valueable?

[oberon-sk]

User and peer are 6 byte MAC addresses. But we have not found any reference to the format in the spec.

[athoelke]

§9.2.4.3.2 says a MAC address is represented as defined in 802 Clause 8, when present in MAC frame headers.

Presumably the STA-X-MAC octet-strings used in the SAE protocol would have this format.

[athoelke]

The format here is obviously the one defined in 802.11 for the salt in the key derivation schedule.

[oberon-sk]

Yes. Defined in 802.11 IEEE standard specification P802.11-REVme/D7.0, Part 11, Aug 2024 chapter 12.4.5.4, on page 3014.

[athoelke]

The cyclic group is already selected for the PAKE by the cipher-suite used to set up the operation. If the PAKE protocol is initiated following receipt of an SAE Commit frame, the group will already have to be converted into a PAKE primitive and WPA3-SAE algorithm to set up the operation: so passing the group value in the STEP_COMMIT input or output does not seem to be valuable.

I would prefer to leave the conversion from AKN groups to and from PSA cipher suite values outside of the implementation.

[oberon-sk]

LGTM.

[athoelke]

Should we make the commit-scalar and COMMIT_ELEMENT components of the commit frames separate outputs/inputs (as we do for the separate values in J-PAKE)?

Does concatenating them make it easier for the caller to assemble/disassemble the SAE Commit frames in 802.11?

[oberon-sk]

We do not think it makes a big difference for the caller.
However, more STEP constants would be needed.

[athoelke]

Although the prefix counter is redundant in the output, as the caller has just passed this as an input prior; it makes sense to keep this value symmetric for output and input, and it is required for input when verifying the peer's confirmation value using the peer's confirmation counter.

[oberon-sk]

Agreed.

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

[athoelke]

I am trying to decide if we need to parameterize the KDF, and the WPA3-SAE algorithms with a hash function at all. I think for implementations that follow the 80.11 spec precisely we could drop the explicit parameterization:

• The KDF implies the use of the hash-to-curve password token generation - and for this, the specification §12.4.2 is unambiguous about the mapping from cyclic group to hash function. So the hash function to use can be determined from the cyclic group specified in the output key type.

• When setting up the PAKE operation, the cipher suite specifies the cyclic group, and the type of key (PASSWORD or WPA_SAE_XX_PT) determines the choice of looping vs H2E generation of the PWE.

  • For looping, the hash function is fixed as SHA-256.
  • For H2E, the hash function is specified in Table 12-1. In this case, the PAKE set up must also verify that the key type matches the primitive in the cyclic group.

If we keep the parameterization, then we would either:

1. Require the implementation to verify that the hash matches the specification requirement. This is only valuable if we anticipate a future change in the standard to use other hash algorithms.
2. OR, we permit non-standard hash algorithms to be used with the selected cyclic group/PWE-generation method.

In either of those approaches, it becomes an application problem to select and specify the correct hash algorithm for the KDF and the PAKE operations. In (1), an incorrect value will result in a runtime error, in (2) it will result in an invalid, and possibly vulnerable authentication protocol.

[oberon-sk]

This is no problem for the PAKE operation.

For the KDF there is a problem regarding an efficient implementation:

The ECC or DH family is needed to fix the hash size. The family is provided as part of the key type contained in the attributes argument of the psa_key_derivation_output_key() function. This is the last call in a sequence of calls to KDF functions. This means the whole KDF calculations have to be delayed and executed in the psa_pake_output_key function because the Hash (and MAC) to be used is not known before. All inputs at the other steps have to be buffered in the operation object which is very undesirable for an efficient implementation.

This is why we strongly suggest to keep the hash argument in the KDF algorithm.

[athoelke]

Ok - a valid counter-argument - the HKDF-Extract phase could consume the other inputs as they are provided - as long as we know the Hash function from the start.

[athoelke]

See comment against L44 regarding the need to explicitly specify the hash parameter?

[oberon-sk]

see above

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