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.

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

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

[athoelke]

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

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

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

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

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

[athoelke]

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