Use a single flexible wildcard for WPA3-SAE passwords and password tokens.

Author: athoelke

doc/crypto/api.db/psa/crypto.h

@@ -183,7 +183,7 @@ typedef struct psa_custom_key_parameters_t {
 #define PSA_ALG_TLS12_PSK_TO_MS(hash_alg) /* specification-defined value */
 #define PSA_ALG_TRUNCATED_MAC(mac_alg, mac_length) \
     /* specification-defined value */
-#define PSA_ALG_WPA3_SAE_ANY ((psa_algorithm_t)0x0a000800)
+#define PSA_ALG_WPA3_SAE_ANY ((psa_algorithm_t)0x0a0088ff)
 #define PSA_ALG_WPA3_SAE_FIXED(hash_alg) /* specification-defined value */
 #define PSA_ALG_WPA3_SAE_GDH(hash_alg) /* specification-defined value */
 #define PSA_ALG_WPA3_SAE_H2E(hash_alg) /* specification-defined value */

doc/crypto/api/keys/policy.rst

@@ -37,7 +37,7 @@ The following algorithm policies are supported:
 *   An algorithm built from `PSA_ALG_AT_LEAST_THIS_LENGTH_MAC()` permits any MAC algorithm from the same base class (for example, CMAC) which computes or verifies a MAC length greater than or equal to the length encoded in the wildcard algorithm.
 *   An algorithm built from `PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG()` permits any AEAD algorithm from the same base class (for example, CCM) which computes or verifies a tag length greater than or equal to the length encoded in the wildcard algorithm.
 *   The `PSA_ALG_CCM_STAR_ANY_TAG` wildcard algorithm permits the `PSA_ALG_CCM_STAR_NO_TAG` cipher algorithm, the `PSA_ALG_CCM` AEAD algorithm, and the :code:`PSA_ALG_AEAD_WITH_SHORTENED_TAG(PSA_ALG_CCM, tag_length)` truncated-tag AEAD algorithm for ``tag_length`` equal to 4, 8 or 16.
-*   The wildcard key policy :code:`PSA_ALG_WPA3_SAE_H2E(PSA_ALG_ANY_HASH)` permits a password key to be used with any WPA3-SAE cipher suite.
+*   The wildcard key policy `PSA_ALG_WPA3_SAE_ANY` permits a password key or WPA3-SAE password token key to be used with any WPA3-SAE cipher suite.
 
 When a key is used in a cryptographic operation, the application must supply the algorithm to use for the operation. This algorithm is checked against the key's permitted-algorithm policy.
 

doc/crypto/api/keys/types.rst

@@ -988,6 +988,10 @@ See :secref:`wpa3-sae-passwords`.
 
     To construct a WPA3-SAE password token, it must be output from key derivation operation using the `PSA_ALG_WPA3_SAE_H2E` algorithm.
 
+    .. note::
+
+        To use a password token key with both `PSA_ALG_WPA3_SAE_FIXED` and `PSA_ALG_WPA3_SAE_GDH` algorithms, create the key with the wildcard `PSA_ALG_WPA3_SAE_ANY` permitted algorithm.
+
     .. subsection:: Compatible algorithms
 
         .. hlist::
@@ -1036,6 +1040,10 @@ See :secref:`wpa3-sae-passwords`.
 
     To construct a WPA3-SAE password token, it must be output from key derivation operation using the `PSA_ALG_WPA3_SAE_H2E` algorithm.
 
+    .. note::
+
+        To use a password token key with both `PSA_ALG_WPA3_SAE_FIXED` and `PSA_ALG_WPA3_SAE_GDH` algorithms, create the key with the wildcard `PSA_ALG_WPA3_SAE_ANY` permitted algorithm.
+
     .. subsection:: Compatible algorithms
 
         .. hlist::

doc/crypto/api/ops/key-derivation.rst

@@ -394,7 +394,9 @@ Key-derivation algorithms
 
     :secref:`wpa3-sae-keys` provides details of the derivation procedures.
 
-    The wildcard key policy :code:`PSA_ALG_WPA3_SAE_H2E(PSA_ALG_ANY_HASH)` permits a password key to be used with any WPA3-SAE cipher suite.
+    .. note::
+
+        To use a single password key with `PSA_ALG_WPA3_SAE_H2E` for any WPA3-SAE cipher suite, create the key with the wildcard `PSA_ALG_WPA3_SAE_ANY` permitted algorithm.
 
 .. macro:: PSA_ALG_PBKDF2_HMAC
     :definition: /* specification-defined value */

doc/crypto/api/ops/pake.rst

@@ -2168,7 +2168,7 @@ For example, the following code creates a PAKE cipher suite for WPA3-SAE using h
 WPA3-SAE password processing
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-WPA3-SAE defines the following two methods for deriving the password element (PWE) from the password:
+WPA3-SAE defines the following two methods for deriving the password element PWE from the password:
 
 .. list-table::
     :widths: 1 4
@@ -2193,20 +2193,23 @@ The hash-to-element method is recommended, as it is less vulnerable to timing-ba
 
     WPA3-SAE password processing
 
+For both methods, the password must be imported as a key of type `PSA_KEY_TYPE_PASSWORD`.
+The password must be encoded as defined in `[IEEE-802.11]` §12.4.3.
+
+.. note::
+
+    `[IEEE-802.11]` specifies that the same password is used for any configured WPA3-SAE cipher suites, and with any configured PWE-derivation methods.
+    The wildcard key policy `PSA_ALG_WPA3_SAE_ANY` permits a password key to be used for any valid derivation method, and with any valid WPA3-SAE cipher suite.
+
 .. rubric:: Looping method
 
-To use the looping method, import the password into a key of type `PSA_KEY_TYPE_PASSWORD`.
-The password must be encoded as defined in `[IEEE-802.11]` §12.4.3.
-Provide this key to the WPA3-SAE PAKE operation in the call to `psa_pake_setup()`.
+Provide the password key directly to the WPA3-SAE PAKE operation in the call to `psa_pake_setup()`.
 
 .. rubric:: Hash-to-element method
 
 To use the hash-to-element method:
 
-1.  Import the password into a key of type `PSA_KEY_TYPE_PASSWORD`.
-    The password must be encoded as defined in `[IEEE-802.11]` §12.4.3.
-
-#.  A WPA3-SAE password token is derived from the WPA3-SAE password, using a key-derivation operation with the `PSA_ALG_WPA3_SAE_H2E()` algorithm.
+1.  A WPA3-SAE password token is derived from the WPA3-SAE password, using a key-derivation operation with the `PSA_ALG_WPA3_SAE_H2E()` algorithm.
     The `PSA_ALG_WPA3_SAE_H2E()` algorithm is parameterized by the hash used in the required WPA3-SAE cipher suite.
 
     The password token is output from the key-derivation operation as a key of type `PSA_KEY_TYPE_WPA3_SAE_ECC()` or `PSA_KEY_TYPE_WPA3_SAE_DH()`.
@@ -2216,7 +2219,9 @@ To use the hash-to-element method:
 
 #.  Pass the password token key to the WPA3-SAE PAKE operation in the call to `psa_pake_setup()`.
 
-The wildcard key policy `PSA_ALG_WPA3_SAE_ANY` permits a password token key to be used with both the `PSA_ALG_WPA3_SAE_FIXED()` and `PSA_ALG_WPA3_SAE_GDH()` PAKE algorithms.
+.. note::
+
+    The wildcard key policy `PSA_ALG_WPA3_SAE_ANY` permits a password token key to be used with both the `PSA_ALG_WPA3_SAE_FIXED()` and `PSA_ALG_WPA3_SAE_GDH()` PAKE algorithms.
 
 The following steps demonstrate the derivation of a password token for use with the group-dependent-hash variant of WPA3-SAE.
 The selected cipher suite in the example is IANA Group 20: ECC using secp384r1, hash function SHA-384.
@@ -2518,15 +2523,13 @@ WPA3-SAE algorithms
     WPA3-SAE algorithms with a group-dependent size for the output key, are constructed using :code:`PSA_ALG_WPA3_SAE_GDH(hash_alg)`.
 
 .. macro:: PSA_ALG_WPA3_SAE_ANY
-    :definition: ((psa_algorithm_t)0x0a000800)
+    :definition: ((psa_algorithm_t)0x0a0088ff)
 
     .. summary::
-        A wildcard algorithm that permits a WPA3-SAE password token key to be used in hash-to-element and group-dependent-hash variants of the WPA3-SAE PAKE algorithm.
+        A wildcard algorithm for WPA3-SAE password keys and password token keys.
 
         .. versionadded:: 1.4
 
-    If a WPA3-SAE password token key specifies `PSA_ALG_WPA3_SAE_ANY` as its permitted algorithm, then the key can be used with the `PSA_ALG_WPA3_SAE_FIXED()` and `PSA_ALG_WPA3_SAE_GDH()` PAKE algorithms.
-
-    .. todo::
+    If a password key (key type `PSA_KEY_TYPE_PASSWORD`) specifies `PSA_ALG_WPA3_SAE_ANY` as its permitted algorithm, then the key can be used for any WPA3-SAE cipher suite with the `PSA_ALG_WPA3_SAE_H2E` key-derivation algorithm, and with the `PSA_ALG_WPA3_SAE_FIXED` PAKE algorithm.
 
-        We could extend this wildcard key policy to also cover the cases for password keys being used in the PAKE and KDF algorithms for WPA3-SAE?
+    If a WPA3-SAE password token key specifies `PSA_ALG_WPA3_SAE_ANY` as its permitted algorithm, then the key can be used with both the `PSA_ALG_WPA3_SAE_FIXED()` and `PSA_ALG_WPA3_SAE_GDH()` PAKE algorithms.

doc/crypto/appendix/encodings.rst

@@ -440,9 +440,14 @@ The permitted values of HASH-TYPE (see :numref:`table-hash-type`) depend on the
     SPAKE2+ for Matter, ``0x06``, :code:`PSA_ALG_SPAKE2P_MATTER`, ``0x0A000609``
     WPA3-SAE, ``0x08``, :code:`PSA_ALG_WPA3_SAE_FIXED(hash)`, ``0x0A0008hh`` :sup:`a`
     WPA3-SAE (GDH), ``0x09``, :code:`PSA_ALG_WPA3_SAE_GDH(hash)`, ``0x0A0009hh`` :sup:`a`
+    *WPA3-SAE wildcard* :sup:`b c`, ``0x88``, `PSA_ALG_WPA3_SAE_ANY`, ``0x0A0088FF``
 
 a.  ``hh`` is the HASH-TYPE for the hash algorithm, ``hash``, used to construct the key-derivation algorithm.
 
+b.  The wildcard algorithm `PSA_ALG_WPA3_SAE_ANY` permits a password key to be used for any WPA3-SAE cipher suite with the `PSA_ALG_WPA3_SAE_H2E` key-derivation algorithm, and with the `PSA_ALG_WPA3_SAE_FIXED` PAKE algorithm.
+
+c.  The wildcard algorithm `PSA_ALG_WPA3_SAE_ANY` permits a WPA3-SAE password token key to be used for both the `PSA_ALG_WPA3_SAE_FIXED` and `PSA_ALG_WPA3_SAE_GDH` PAKE algorithms.
+
 .. _key-type-encoding:
 
 Key type encoding

doc/crypto/appendix/history.rst

@@ -27,6 +27,7 @@ Changes to the API
     -   Added the `PSA_ALG_WPA3_SAE_H2E()` KDF for generating a WPA3-SAE password token from a password.
     -   Added WPA3-SAE PAKE algorithms, `PSA_ALG_WPA3_SAE_FIXED()` and `PSA_ALG_WPA3_SAE_GDH()`.
     -   Added finite field Diffie-Hellman family `PSA_DH_FAMILY_RFC3526`, which provides cyclic groups used for WPA3-SAE.
+    -   Added wildcard key policy `PSA_ALG_WPA3_SAE_ANY` to permit password and password token keys to be used in any WPA3-SAE cipher suite.
 
     See :secref:`pake-wpa3-sae`.