diff --git a/doc/crypto/api.db/psa/crypto.h b/doc/crypto/api.db/psa/crypto.h index d7f35295..c26a1e31 100644 --- a/doc/crypto/api.db/psa/crypto.h +++ b/doc/crypto/api.db/psa/crypto.h @@ -136,6 +136,10 @@ typedef struct psa_custom_key_parameters_t { #define PSA_ALG_IS_TLS12_PRF(alg) /* specification-defined value */ #define PSA_ALG_IS_TLS12_PSK_TO_MS(alg) /* specification-defined value */ #define PSA_ALG_IS_WILDCARD(alg) /* specification-defined value */ +#define PSA_ALG_IS_WPA3_SAE(alg) /* specification-defined value */ +#define PSA_ALG_IS_WPA3_SAE_FIXED(alg) /* specification-defined value */ +#define PSA_ALG_IS_WPA3_SAE_GDH(alg) /* specification-defined value */ +#define PSA_ALG_IS_WPA3_SAE_H2E(alg) /* specification-defined value */ #define PSA_ALG_IS_XOF(alg) /* specification-defined value */ #define PSA_ALG_JPAKE(hash_alg) /* specification-defined value */ #define PSA_ALG_KEY_AGREEMENT(ka_alg, kdf_alg) \ @@ -179,13 +183,17 @@ typedef struct psa_custom_key_parameters_t { /* specification-defined value */ #define PSA_ALG_SPAKE2P_CMAC(hash_alg) /* specification-defined value */ #define PSA_ALG_SPAKE2P_HMAC(hash_alg) /* specification-defined value */ -#define PSA_ALG_SPAKE2P_MATTER ((psa_algoirithm_t)0x0A000609) +#define PSA_ALG_SPAKE2P_MATTER ((psa_algorithm_t)0x0A000609) #define PSA_ALG_STREAM_CIPHER ((psa_algorithm_t)0x04800100) #define PSA_ALG_TLS12_ECJPAKE_TO_PMS ((psa_algorithm_t)0x08000609) #define PSA_ALG_TLS12_PRF(hash_alg) /* specification-defined value */ #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)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 */ #define PSA_ALG_XCHACHA20_POLY1305 ((psa_algorithm_t)0x05100600) #define PSA_ALG_XTS ((psa_algorithm_t)0x0440ff00) #define PSA_ASYMMETRIC_DECRYPT_OUTPUT_MAX_SIZE \ @@ -219,6 +227,7 @@ typedef struct psa_custom_key_parameters_t { #define PSA_CRYPTO_API_VERSION_MAJOR 1 #define PSA_CRYPTO_API_VERSION_MINOR 4 #define PSA_CUSTOM_KEY_PARAMETERS_INIT { 0 } +#define PSA_DH_FAMILY_RFC3526 ((psa_dh_family_t) 0x05) #define PSA_DH_FAMILY_RFC7919 ((psa_dh_family_t) 0x03) #define PSA_ECC_FAMILY_BRAINPOOL_P_R1 ((psa_ecc_family_t) 0x30) #define PSA_ECC_FAMILY_FRP ((psa_ecc_family_t) 0x33) @@ -317,6 +326,8 @@ typedef struct psa_custom_key_parameters_t { #define PSA_KEY_TYPE_IS_SPAKE2P_PUBLIC_KEY(type) \ /* specification-defined value */ #define PSA_KEY_TYPE_IS_UNSTRUCTURED(type) /* specification-defined value */ +#define PSA_KEY_TYPE_IS_WPA3_SAE_DH(type) /* specification-defined value */ +#define PSA_KEY_TYPE_IS_WPA3_SAE_ECC(type) /* specification-defined value */ #define PSA_KEY_TYPE_KEY_PAIR_OF_PUBLIC_KEY(type) \ /* specification-defined value */ #define PSA_KEY_TYPE_NONE ((psa_key_type_t)0x0000) @@ -333,6 +344,12 @@ typedef struct psa_custom_key_parameters_t { #define PSA_KEY_TYPE_SPAKE2P_KEY_PAIR(curve) /* specification-defined value */ #define PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY(curve) \ /* specification-defined value */ +#define PSA_KEY_TYPE_WPA3_SAE_DH(group) /* specification-defined value */ +#define PSA_KEY_TYPE_WPA3_SAE_DH_GET_FAMILY(type) \ + /* specification-defined value */ +#define PSA_KEY_TYPE_WPA3_SAE_ECC(curve) /* specification-defined value */ +#define PSA_KEY_TYPE_WPA3_SAE_ECC_GET_FAMILY(type) \ + /* specification-defined value */ #define PSA_KEY_TYPE_XCHACHA20 ((psa_key_type_t)0x2007) #define PSA_KEY_USAGE_CACHE ((psa_key_usage_t)0x00000004) #define PSA_KEY_USAGE_COPY ((psa_key_usage_t)0x00000002) @@ -376,8 +393,12 @@ typedef struct psa_custom_key_parameters_t { #define PSA_PAKE_ROLE_NONE ((psa_pake_role_t)0x00) #define PSA_PAKE_ROLE_SECOND ((psa_pake_role_t)0x02) #define PSA_PAKE_ROLE_SERVER ((psa_pake_role_t)0x12) +#define PSA_PAKE_STEP_COMMIT ((psa_pake_step_t)0x06) #define PSA_PAKE_STEP_CONFIRM ((psa_pake_step_t)0x04) +#define PSA_PAKE_STEP_CONFIRM_COUNT ((psa_pake_step_t)0x07) +#define PSA_PAKE_STEP_KEY_ID ((psa_pake_step_t)0x08) #define PSA_PAKE_STEP_KEY_SHARE ((psa_pake_step_t)0x01) +#define PSA_PAKE_STEP_SALT ((psa_pake_step_t)0x05) #define PSA_PAKE_STEP_ZK_PROOF ((psa_pake_step_t)0x03) #define PSA_PAKE_STEP_ZK_PUBLIC ((psa_pake_step_t)0x02) #define PSA_PAKE_UNCONFIRMED_KEY 1 diff --git a/doc/crypto/api/keys/policy.rst b/doc/crypto/api/keys/policy.rst index 1e312c22..40dc7704 100644 --- a/doc/crypto/api/keys/policy.rst +++ b/doc/crypto/api/keys/policy.rst @@ -37,6 +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 `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. diff --git a/doc/crypto/api/keys/types.rst b/doc/crypto/api/keys/types.rst index f54f1dfb..e545a701 100644 --- a/doc/crypto/api/keys/types.rst +++ b/doc/crypto/api/keys/types.rst @@ -7,17 +7,17 @@ .. _key-types: Key types -========= +--------- Key type encoding ------------------ +~~~~~~~~~~~~~~~~~ .. typedef:: uint16_t psa_key_type_t .. summary:: Encoding of a key type. - This is a structured bitfield that identifies the category and type of key. The range of key type values is divided as follows: + This is a structured bit field that identifies the category and type of key. The range of key type values is divided as follows: :code:`PSA_KEY_TYPE_NONE == 0` Reserved as an invalid key type. @@ -41,7 +41,18 @@ Key type encoding Zero is not the encoding of any key type. Key categories --------------- +~~~~~~~~~~~~~~ + +In the |API|, keys are typically used to store secrets that are specific to a set of related cryptographic algorithms. +Keys can also be used to store non-cryptographic secrets or other data. +The key type is used to identify what the key value is, and what can be used for. + +* :secref:`unstructured-keys` --- defines types for non-key data and unstructured symmetric keys. + For example, passwords, key-derivation secrets, or AES keys. +* :secref:`structured-keys` --- defines types for structured symmetric keys. + For example, WPA3-SAE password tokens. +* :secref:`asymmetric-keys` --- defines types for asymmetric keys. + For example, elliptic curve or SPAKE2+ keys. .. macro:: PSA_KEY_TYPE_IS_UNSTRUCTURED :definition: /* specification-defined value */ @@ -54,7 +65,7 @@ Key categories This encompasses both symmetric keys and non-key data. - See :secref:`symmetric-keys` for a list of symmetric key types. + See :secref:`unstructured-keys` for a list of unstructured key types. .. macro:: PSA_KEY_TYPE_IS_ASYMMETRIC :definition: /* specification-defined value */ @@ -86,74 +97,379 @@ Key categories A key type: a value of type `psa_key_type_t`. -.. _symmetric-keys: +Elliptic curve families +~~~~~~~~~~~~~~~~~~~~~~~ -Symmetric keys --------------- +.. typedef:: uint8_t psa_ecc_family_t -.. macro:: PSA_KEY_TYPE_RAW_DATA - :definition: ((psa_key_type_t)0x1001) + .. summary:: + The type of identifiers of an elliptic curve family. + + The curve family identifier is required to create a number of key types: + + * ECC keys using `PSA_KEY_TYPE_ECC_KEY_PAIR()` or `PSA_KEY_TYPE_ECC_PUBLIC_KEY()`. + These keys are used in various asymmetric signature, key-encapsulation, and key-agreement algorithms. + * SPAKE2+ keys using the `PSA_KEY_TYPE_SPAKE2P_KEY_PAIR()` or `PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY()`. + These keys are used in the SPAKE2+ PAKE algorithms. + * WPA3-SAE password tokens using `PSA_KEY_TYPE_WPA3_SAE_ECC()`. + These keys are used in the WPA3-SAE PAKE algorithms. + + Elliptic curve family identifiers are also used to construct PAKE primitives for cipher suites based on elliptic curve groups. + See :secref:`pake-primitive`. + + The specific ECC curve within a family is identified by the ``key_bits`` attribute of the key. + + The range of elliptic curve family identifier values is divided as follows: + + :code:`0x00` + Reserved. + Not allocated to an elliptic curve family. + :code:`0x01 - 0x7f` + Elliptic curve family identifiers defined by this standard. + Unallocated values in this range are reserved for future use. + :code:`0x80 - 0xff` + Invalid. + Values in this range must not be used. + + The least significant bit of a elliptic curve family identifier is a parity bit for the whole key type. + See :secref:`asymmetric-key-encoding` for details of the encoding of asymmetric key types. + + .. admonition:: Implementation note + + To provide other elliptic curve families, it is recommended that an implementation defines a key type with bit 15 set, which indicates an :scterm:`implementation defined` key type. + +.. macro:: PSA_ECC_FAMILY_SECP_K1 + :definition: ((psa_ecc_family_t) 0x17) .. summary:: - Raw data. + SEC Koblitz curves over prime fields. - A "key" of this type cannot be used for any cryptographic operation. Applications can use this type to store arbitrary data in the keystore. + This family comprises the following curves: - The bit size of a raw key must be a non-zero multiple of 8. The maximum size of a raw key is :scterm:`IMPLEMENTATION DEFINED`. + * secp192k1 : ``key_bits = 192`` + * secp224k1 : ``key_bits = 225`` + * secp256k1 : ``key_bits = 256`` - .. subsection:: Compatible algorithms + They are defined in :cite-title:`SEC2`. - A key of this type can also be used as a non-secret input to the following key-derivation algorithms: +.. macro:: PSA_ECC_FAMILY_SECP_R1 + :definition: ((psa_ecc_family_t) 0x12) - .. hlist:: + .. summary:: + SEC random curves over prime fields. - * `PSA_ALG_HKDF` - * `PSA_ALG_HKDF_EXPAND` - * `PSA_ALG_HKDF_EXTRACT` - * `PSA_ALG_SP800_108_COUNTER_HMAC` - * `PSA_ALG_SP800_108_COUNTER_CMAC` - * `PSA_ALG_TLS12_PRF` - * `PSA_ALG_TLS12_PSK_TO_MS` + This family comprises the following curves: - .. subsection:: Key format + * secp192r1 : ``key_bits = 192`` + * secp224r1 : ``key_bits = 224`` + * secp256r1 : ``key_bits = 256`` + * secp384r1 : ``key_bits = 384`` + * secp521r1 : ``key_bits = 521`` - The data format for import and export of the key is the raw bytes of the key. + They are defined in :cite:`SEC2`. - .. subsection:: Key derivation +.. macro:: PSA_ECC_FAMILY_SECP_R2 + :definition: ((psa_ecc_family_t) 0x1b) - A call to `psa_key_derivation_output_key()` will draw :math:`m/8` bytes of output and use these as the key data, where :math:`m` is the bit-size of the key. + .. summary:: + .. warning:: + This family of curves is weak and deprecated. -.. macro:: PSA_KEY_TYPE_HMAC - :definition: ((psa_key_type_t)0x1100) + This family comprises the following curves: + + * secp160r2 : ``key_bits = 160`` *(Deprecated)* + + It is defined in the superseded :cite-title:`SEC2v1`. + +.. macro:: PSA_ECC_FAMILY_SECT_K1 + :definition: ((psa_ecc_family_t) 0x27) .. summary:: - HMAC key. + SEC Koblitz curves over binary fields. - HMAC keys can be used in HMAC, or HMAC-based, algorithms. - Although HMAC is parameterized by a specific hash algorithm, for example SHA-256, the hash algorithm is not specified in the key type. - The permitted-algorithm policy for the key must specify a particular hash algorithm. + This family comprises the following curves: - The bit size of an HMAC key must be a non-zero multiple of 8. - An HMAC key is typically the same size as the output of the underlying hash algorithm. - An HMAC key that is longer than the block size of the underlying hash algorithm will be hashed before use, see :RFC-title:`2104#2`. + * sect163k1 : ``key_bits = 163`` *(Deprecated)* + * sect233k1 : ``key_bits = 233`` + * sect239k1 : ``key_bits = 239`` + * sect283k1 : ``key_bits = 283`` + * sect409k1 : ``key_bits = 409`` + * sect571k1 : ``key_bits = 571`` - It is recommended that an application does not construct HMAC keys that are longer than the block size of the hash algorithm that will be used. - It is :scterm:`implementation defined` whether an HMAC key that is longer than the hash block size is supported. + They are defined in :cite:`SEC2`. - If the application does not control the length of the data used to construct the HMAC key, it is recommended that the application hashes the key data, when it exceeds the hash block length, before constructing the HMAC key. + .. warning:: + The 163-bit curve sect163k1 is weak and deprecated and is only recommended for use in legacy applications. - .. note:: +.. macro:: PSA_ECC_FAMILY_SECT_R1 + :definition: ((psa_ecc_family_t) 0x22) - :code:`PSA_HASH_LENGTH(alg)` provides the output size of hash algorithm ``alg``, in bytes. + .. summary:: + SEC random curves over binary fields. - :code:`PSA_HASH_BLOCK_LENGTH(alg)` provides the block size of hash algorithm ``alg``, in bytes. + This family comprises the following curves: + + * sect163r1 : ``key_bits = 163`` *(Deprecated)* + * sect233r1 : ``key_bits = 233`` + * sect283r1 : ``key_bits = 283`` + * sect409r1 : ``key_bits = 409`` + * sect571r1 : ``key_bits = 571`` + + They are defined in :cite:`SEC2`. + + .. warning:: + The 163-bit curve sect163r1 is weak and deprecated and is only recommended for use in legacy applications. + +.. macro:: PSA_ECC_FAMILY_SECT_R2 + :definition: ((psa_ecc_family_t) 0x2b) + + .. summary:: + SEC additional random curves over binary fields. + + This family comprises the following curves: + + * sect163r2 : ``key_bits = 163`` *(Deprecated)* + + It is defined in :cite:`SEC2`. + + .. warning:: + The 163-bit curve sect163r2 is weak and deprecated and is only recommended for use in legacy applications. + +.. macro:: PSA_ECC_FAMILY_BRAINPOOL_P_R1 + :definition: ((psa_ecc_family_t) 0x30) + + .. summary:: + Brainpool P random curves. + + This family comprises the following curves: + + * brainpoolP160r1 : ``key_bits = 160`` *(Deprecated)* + * brainpoolP192r1 : ``key_bits = 192`` + * brainpoolP224r1 : ``key_bits = 224`` + * brainpoolP256r1 : ``key_bits = 256`` + * brainpoolP320r1 : ``key_bits = 320`` + * brainpoolP384r1 : ``key_bits = 384`` + * brainpoolP512r1 : ``key_bits = 512`` + + They are defined in :rfc-title:`5639`. + + .. warning:: + The 160-bit curve brainpoolP160r1 is weak and deprecated and is only recommended for use in legacy applications. + +.. macro:: PSA_ECC_FAMILY_FRP + :definition: ((psa_ecc_family_t) 0x33) + + .. summary:: + Curve used primarily in France and elsewhere in Europe. + + This family comprises one 256-bit curve: + + * FRP256v1 : ``key_bits = 256`` + + This is defined by :cite-title:`FRP`. + +.. macro:: PSA_ECC_FAMILY_MONTGOMERY + :definition: ((psa_ecc_family_t) 0x41) + + .. summary:: + Montgomery curves. + + This family comprises the following Montgomery curves: + + * Curve25519 : ``key_bits = 255`` + * Curve448 : ``key_bits = 448`` + + Curve25519 is defined in :cite-title:`Curve25519`. Curve448 is defined in :cite-title:`Curve448`. + +.. macro:: PSA_ECC_FAMILY_TWISTED_EDWARDS + :definition: ((psa_ecc_family_t) 0x42) + + .. summary:: + Twisted Edwards curves. + + .. versionadded:: 1.1 + + This family comprises the following twisted Edwards curves: + + * Edwards25519 : ``key_bits = 255``. This curve is birationally equivalent to Curve25519. + * Edwards448 : ``key_bits = 448``. This curve is birationally equivalent to Curve448. + + Edwards25519 is defined in :cite-title:`Ed25519`. Edwards448 is defined in :cite-title:`Curve448`. + + +Finite field Diffie-Hellman families +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. typedef:: uint8_t psa_dh_family_t + + .. summary:: + The type of identifiers of a finite field Diffie-Hellman group family. + + The group family identifier is required to create a number of key types: + + * Diffie-Hellman keys using `PSA_KEY_TYPE_DH_KEY_PAIR()` or `PSA_KEY_TYPE_DH_PUBLIC_KEY()`. + These keys are used in the FFDH key-agreement algorithm. + * WPA3-SAE password tokens using `PSA_KEY_TYPE_WPA3_SAE_DH()`. + These keys are used in the WPA3-SAE PAKE algorithms. + + Finite field Diffie-Hellman group identifiers are also used to construct PAKE primitives for cipher suites based on finite field groups. + See :secref:`pake-primitive`. + + The specific finite field Diffie-Hellman group within a family is identified by the ``key_bits`` attribute of the key. + + The range of finite field Diffie-Hellman group family identifier values is divided as follows: + + :code:`0x00` + Reserved. + Not allocated to a Diffie-Hellman group family. + :code:`0x01 - 0x7f` + Diffie-Hellman group family identifiers defined by this standard. + Unallocated values in this range are reserved for future use. + :code:`0x80 - 0xff` + Invalid. + Values in this range must not be used. + + The least significant bit of a finite field Diffie-Hellman group family identifier is a parity bit for the whole key type. + See :secref:`asymmetric-key-encoding` for details of the encoding of asymmetric key types. + + .. admonition:: Implementation note + + To provide other finite field Diffie-Hellman group families, it is recommended that an implementation defines a key type with bit 15 set, which indicates an :scterm:`implementation defined` key type. + +.. macro:: PSA_DH_FAMILY_RFC7919 + :definition: ((psa_dh_family_t) 0x03) + + .. summary:: + Finite field Diffie-Hellman groups defined for TLS in RFC 7919. + + This family includes groups with the following key sizes (in bits): 2048, 3072, 4096, 6144, 8192. + An implementation can support all of these sizes or only a subset. + + Groups in this family can be used with the `PSA_ALG_FFDH` key-agreement algorithm. + + These groups are defined by :rfc-title:`7919#A`. + +.. macro:: PSA_DH_FAMILY_RFC3526 + :definition: ((psa_dh_family_t) 0x05) + + .. summary:: + Finite field Diffie-Hellman groups defined for IKE2 in RFC 3526. + + .. versionadded:: 1.4 + + This family includes groups with the following key sizes (in bits): 2048, 3072, 4096, 6144, 8192. + An implementation can support all of these sizes or only a subset. + + Groups in this family can be used with the `PSA_ALG_FFDH` key-agreement algorithm, or with the `PSA_ALG_WPA3_SAE_FIXED` and `PSA_ALG_WPA3_SAE_GDH` PAKE algorithms. + + These groups are defined by :rfc-title:`3526`. + + +Attribute accessors +~~~~~~~~~~~~~~~~~~~ + +.. function:: psa_set_key_type + + .. summary:: + Declare the type of a key. + + .. param:: psa_key_attributes_t * attributes + The attribute object to write to. + .. param:: psa_key_type_t type + The key type to write. If this is `PSA_KEY_TYPE_NONE`, the key type in ``attributes`` becomes unspecified. + + .. return:: void + + This function overwrites any key type previously set in ``attributes``. + + .. admonition:: Implementation note + + This is a simple accessor function that is not required to validate its inputs. It can be efficiently implemented as a ``static inline`` function or a function-like-macro. + + +.. function:: psa_get_key_type + + .. summary:: + Retrieve the key type from key attributes. + + .. param:: const psa_key_attributes_t * attributes + The key attribute object to query. + + .. return:: psa_key_type_t + The key type stored in the attribute object. + + .. admonition:: Implementation note + + This is a simple accessor function that is not required to validate its inputs. It can be efficiently implemented as a ``static inline`` function or a function-like-macro. + + +.. function:: psa_get_key_bits + + .. summary:: + Retrieve the key size from key attributes. + + .. param:: const psa_key_attributes_t * attributes + The key attribute object to query. + + .. return:: size_t + The key size stored in the attribute object, in bits. + + .. admonition:: Implementation note + + This is a simple accessor function that is not required to validate its inputs. It can be efficiently implemented as a ``static inline`` function or a function-like-macro. + + +.. function:: psa_set_key_bits + + .. summary:: + Declare the size of a key. + + .. param:: psa_key_attributes_t * attributes + The attribute object to write to. + .. param:: size_t bits + The key size in bits. If this is ``0``, the key size in ``attributes`` becomes unspecified. Keys of size ``0`` are not supported. + + .. return:: void + + This function overwrites any key size previously set in ``attributes``. + + .. admonition:: Implementation note + + This is a simple accessor function that is not required to validate its inputs. It can be efficiently implemented as a ``static inline`` function or a function-like-macro. + +.. _unstructured-keys: + +Unstructured key types +---------------------- + +.. _non-key-data: + +Non-key data +~~~~~~~~~~~~ + +.. macro:: PSA_KEY_TYPE_RAW_DATA + :definition: ((psa_key_type_t)0x1001) + + .. summary:: + Raw data. + + A "key" of this type cannot be used for any cryptographic operation. Applications can use this type to store arbitrary data in the keystore. + + The bit size of a raw key must be a non-zero multiple of 8. The maximum size of a raw key is :scterm:`IMPLEMENTATION DEFINED`. .. subsection:: Compatible algorithms + A key of this type can also be used as a non-secret input to the following key-derivation algorithms: + .. hlist:: - * `PSA_ALG_HMAC` - * `PSA_ALG_SP800_108_COUNTER_HMAC` (secret input) + * `PSA_ALG_HKDF` + * `PSA_ALG_HKDF_EXPAND` + * `PSA_ALG_HKDF_EXTRACT` + * `PSA_ALG_SP800_108_COUNTER_HMAC` + * `PSA_ALG_SP800_108_COUNTER_CMAC` + * `PSA_ALG_TLS12_PRF` + * `PSA_ALG_TLS12_PSK_TO_MS` .. subsection:: Key format @@ -287,6 +603,50 @@ Symmetric keys A call to `psa_key_derivation_output_key()` will draw :math:`m/8` bytes of output and use these as the key data, where :math:`m` is the bit-size of the key. +Symmetric cryptographic keys +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. macro:: PSA_KEY_TYPE_HMAC + :definition: ((psa_key_type_t)0x1100) + + .. summary:: + HMAC key. + + HMAC keys can be used in HMAC, or HMAC-based, algorithms. + Although HMAC is parameterized by a specific hash algorithm, for example SHA-256, the hash algorithm is not specified in the key type. + The permitted-algorithm policy for the key must specify a particular hash algorithm. + + The bit size of an HMAC key must be a non-zero multiple of 8. + An HMAC key is typically the same size as the output of the underlying hash algorithm. + An HMAC key that is longer than the block size of the underlying hash algorithm will be hashed before use, see :RFC-title:`2104#2`. + + It is recommended that an application does not construct HMAC keys that are longer than the block size of the hash algorithm that will be used. + It is :scterm:`implementation defined` whether an HMAC key that is longer than the hash block size is supported. + + If the application does not control the length of the data used to construct the HMAC key, it is recommended that the application hashes the key data, when it exceeds the hash block length, before constructing the HMAC key. + + .. note:: + + :code:`PSA_HASH_LENGTH(alg)` provides the output size of hash algorithm ``alg``, in bytes. + + :code:`PSA_HASH_BLOCK_LENGTH(alg)` provides the block size of hash algorithm ``alg``, in bytes. + + .. subsection:: Compatible algorithms + + .. hlist:: + + * `PSA_ALG_HMAC` + * `PSA_ALG_SP800_108_COUNTER_HMAC` (secret input) + + .. subsection:: Key format + + The data format for import and export of the key is the raw bytes of the key. + + .. subsection:: Key derivation + + A call to `psa_key_derivation_output_key()` will draw :math:`m/8` bytes of output and use these as the key data, where :math:`m` is the bit-size of the key. + + .. macro:: PSA_KEY_TYPE_AES :definition: ((psa_key_type_t)0x2400) @@ -529,82 +889,257 @@ Symmetric keys The ARC4 cipher supports key sizes between 40 and 2048 bits, that are multiples of 8. (5 to 256 bytes) - Use algorithm `PSA_ALG_STREAM_CIPHER` to use this key with the ARC4 cipher. + Use algorithm `PSA_ALG_STREAM_CIPHER` to use this key with the ARC4 cipher. + + .. subsection:: Compatible algorithms + + .. hlist:: + + * `PSA_ALG_STREAM_CIPHER` + + .. subsection:: Key format + + The data format for import and export of the key is the raw bytes of the key. + + .. subsection:: Key derivation + + A call to `psa_key_derivation_output_key()` will draw :math:`m/8` bytes of output and use these as the key data, where :math:`m` is the bit-size of the key. + +.. macro:: PSA_KEY_TYPE_CHACHA20 + :definition: ((psa_key_type_t)0x2004) + + .. summary:: + Key for the ChaCha20 stream cipher or the ChaCha20-Poly1305 AEAD algorithm. + + The ChaCha20 key size is 256 bits (32 bytes). + + * Use algorithm `PSA_ALG_STREAM_CIPHER` to use this key with the ChaCha20 cipher for unauthenticated encryption. See `PSA_ALG_STREAM_CIPHER` for details of this algorithm. + + * Use algorithm `PSA_ALG_CHACHA20_POLY1305` to use this key with the ChaCha20 cipher and Poly1305 authenticator for AEAD. See `PSA_ALG_CHACHA20_POLY1305` for details of this algorithm. + + .. subsection:: Compatible algorithms + + .. hlist:: + + * `PSA_ALG_STREAM_CIPHER` + * `PSA_ALG_CHACHA20_POLY1305` + + .. subsection:: Key format + + The data format for import and export of the key is the raw bytes of the key. + + .. subsection:: Key derivation + + A call to `psa_key_derivation_output_key()` will draw 32 bytes of output and use these as the key data. + +.. macro:: PSA_KEY_TYPE_XCHACHA20 + :definition: ((psa_key_type_t)0x2007) + + .. summary:: + Key for the XChaCha20 stream cipher or the XChaCha20-Poly1305 AEAD algorithm. + + .. versionadded:: 1.2 + + The XChaCha20 key size is 256 bits (32 bytes). + + * Use algorithm `PSA_ALG_STREAM_CIPHER` to use this key with the XChaCha20 cipher for unauthenticated encryption. See `PSA_ALG_STREAM_CIPHER` for details of this algorithm. + + * Use algorithm `PSA_ALG_XCHACHA20_POLY1305` to use this key with the XChaCha20 cipher and Poly1305 authenticator for AEAD. See `PSA_ALG_XCHACHA20_POLY1305` for details of this algorithm. + + .. subsection:: Compatible algorithms + + .. hlist:: + + * `PSA_ALG_STREAM_CIPHER` + * `PSA_ALG_XCHACHA20_POLY1305` + + .. subsection:: Key format + + The data format for import and export of the key is the raw bytes of the key. + + .. subsection:: Key derivation + + A call to `psa_key_derivation_output_key()` will draw 32 bytes of output and use these as the key data. + + +.. _structured-keys: + +Structured key types +-------------------- + +.. _wpa3-sae-keys: + +WPA3-SAE password tokens +~~~~~~~~~~~~~~~~~~~~~~~~ + +The WPA3-SAE PAKE defines two techniques for generating the password element used during the PAKE protocol. +The recommended hash-2-curve method is used to generate an intermediate password token, which is an element of the cyclic group used in the PAKE cipher suite. +The password token can be stored as a key object, and later used in the PAKE operation when performing the WPA3-SAE protocol. + +WPA3-SAE password tokens are defined for both elliptic curve and finite field groups. + +See :secref:`wpa3-sae-passwords`. + +.. macro:: PSA_KEY_TYPE_WPA3_SAE_ECC + :definition: /* specification-defined value */ + + .. summary:: + WPA3-SAE password token using elliptic curves. + + .. versionadded:: 1.4 + + .. param:: curve + A value of type `psa_ecc_family_t` that identifies the elliptic curve family to be used. + + The bit-size of a WPA3-SAE password token is the bit size associated with the specific curve within the elliptic curve family. + See the documentation of the elliptic curve family for details. + + 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:: + + * `PSA_ALG_WPA3_SAE_FIXED` + * `PSA_ALG_WPA3_SAE_GDH` + + .. subsection:: Key format + + The password token is an element of the elliptic curve group, with value :math:`(x,y)`. + + The data format for import and export of the password token is the concatenation of: + + * :math:`x` encoded as a big-endian :math:`m`-byte string; + * :math:`y` encoded as a big-endian :math:`m`-byte string. + + For an elliptic curve over :math:`\mathbb{F}_p`, :math:`m` is the integer for which :math:`2^{8m-1} \leq p < 2^{8m}`. + + .. note:: + + This is the same format as the one used for group elements in the commit phase of the WPA3-SAE protocol, defined in `[IEEE-802.11]` §12.4.7.2.4. + + .. rationale:: + + There is no protocol use case for exporting or importing the password token. + However, the ability to extract a derived token, or import a known-value token, can help development and testing of an implementation. + + .. subsection:: Key derivation + + A elliptic curve-based WPA3-SAE password token can only be derived using the `PSA_ALG_WPA3_SAE_H2E` algorithm. + The call to `psa_key_derivation_output_key()` uses the method defined in `[IEEE-802.11]` §12.4.4.2.3 to generate the key value. + +.. macro:: PSA_KEY_TYPE_WPA3_SAE_DH + :definition: /* specification-defined value */ + + .. summary:: + WPA3-SAE password token using finite fields. + + .. versionadded:: 1.4 + + .. param:: group + A value of type `psa_dh_family_t` that identifies the finite field Diffie-Hellman family to be used. + + The bit-size of the WPA3-SAE password token is the bit size associated with the specific group within the finite field Diffie-Hellman family. + See the documentation of the selected Diffie-Hellman family for details. + + 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:: - * `PSA_ALG_STREAM_CIPHER` + * `PSA_ALG_WPA3_SAE_FIXED` + * `PSA_ALG_WPA3_SAE_GDH` .. subsection:: Key format - The data format for import and export of the key is the raw bytes of the key. + The password token is a finite-field group element :math:`y \in [1, p - 1]`, where :math:`p` is the group's prime modulus. - .. subsection:: Key derivation + The data format for import and export of the password token is :math:`y` encoded as a big-endian :math:`m`-byte string, where :math:`m` is the integer for which :math:`2^{8m-1} \leq p < 2^{8m}`. - A call to `psa_key_derivation_output_key()` will draw :math:`m/8` bytes of output and use these as the key data, where :math:`m` is the bit-size of the key. + .. note:: -.. macro:: PSA_KEY_TYPE_CHACHA20 - :definition: ((psa_key_type_t)0x2004) + This is the same format as the one used for group elements in the commit phase of the WPA3-SAE protocol, defined in `[IEEE-802.11]` §12.4.7.2.4. - .. summary:: - Key for the ChaCha20 stream cipher or the ChaCha20-Poly1305 AEAD algorithm. + .. rationale:: - The ChaCha20 key size is 256 bits (32 bytes). + There is no protocol use case for exporting or importing the password token. + However, the ability to extract a derived token, or import a known-value token, can help development and testing of an implementation. - * Use algorithm `PSA_ALG_STREAM_CIPHER` to use this key with the ChaCha20 cipher for unauthenticated encryption. See `PSA_ALG_STREAM_CIPHER` for details of this algorithm. + .. subsection:: Key derivation - * Use algorithm `PSA_ALG_CHACHA20_POLY1305` to use this key with the ChaCha20 cipher and Poly1305 authenticator for AEAD. See `PSA_ALG_CHACHA20_POLY1305` for details of this algorithm. + A finite field-based WPA3-SAE password token can only be derived using the `PSA_ALG_WPA3_SAE_H2E` algorithm. + The call to `psa_key_derivation_output_key()` uses the method defined in `[IEEE-802.11]` §12.4.4.3.3 to generate the key value. - .. subsection:: Compatible algorithms +.. macro:: PSA_KEY_TYPE_IS_WPA3_SAE_ECC + :definition: /* specification-defined value */ - .. hlist:: + .. summary:: + Whether a key type is a WPA3-SAE password token using elliptic curves. - * `PSA_ALG_STREAM_CIPHER` - * `PSA_ALG_CHACHA20_POLY1305` + .. versionadded:: 1.4 - .. subsection:: Key format + .. param:: type + A key type: a value of type `psa_key_type_t`. - The data format for import and export of the key is the raw bytes of the key. +.. macro:: PSA_KEY_TYPE_WPA3_SAE_ECC_GET_FAMILY + :definition: /* specification-defined value */ - .. subsection:: Key derivation + .. summary:: + Extract the curve family from a WPA3-SAE password token using elliptic curves. - A call to `psa_key_derivation_output_key()` will draw 32 bytes of output and use these as the key data. + .. versionadded:: 1.4 -.. macro:: PSA_KEY_TYPE_XCHACHA20 - :definition: ((psa_key_type_t)0x2007) + .. param:: type + A WPA3-SAE password token using elliptic curve key type: a value of type `psa_key_type_t` such that :code:`PSA_KEY_TYPE_IS_WPA3_SAE_ECC(type)` is true. - .. summary:: - Key for the XChaCha20 stream cipher or the XChaCha20-Poly1305 AEAD algorithm. + .. return:: psa_ecc_family_t + The elliptic curve family id, if ``type`` is a supported WPA3-SAE password token using elliptic curve key. Unspecified if ``type`` is not a supported WPA3-SAE password token using elliptic curve key. - .. versionadded:: 1.2 +.. macro:: PSA_KEY_TYPE_IS_WPA3_SAE_DH + :definition: /* specification-defined value */ - The XChaCha20 key size is 256 bits (32 bytes). + .. summary:: + Whether a key type is a WPA3-SAE password token using elliptic curves. - * Use algorithm `PSA_ALG_STREAM_CIPHER` to use this key with the XChaCha20 cipher for unauthenticated encryption. See `PSA_ALG_STREAM_CIPHER` for details of this algorithm. + .. versionadded:: 1.4 - * Use algorithm `PSA_ALG_XCHACHA20_POLY1305` to use this key with the XChaCha20 cipher and Poly1305 authenticator for AEAD. See `PSA_ALG_XCHACHA20_POLY1305` for details of this algorithm. + .. param:: type + A key type: a value of type `psa_key_type_t`. - .. subsection:: Compatible algorithms +.. macro:: PSA_KEY_TYPE_WPA3_SAE_DH_GET_FAMILY + :definition: /* specification-defined value */ - .. hlist:: + .. summary:: + Extract the finite field group family from a WPA3-SAE password token using finite fields. - * `PSA_ALG_STREAM_CIPHER` - * `PSA_ALG_XCHACHA20_POLY1305` + .. versionadded:: 1.4 - .. subsection:: Key format + .. param:: type + A WPA3-SAE password token using finite fields key type: a value of type `psa_key_type_t` such that :code:`PSA_KEY_TYPE_IS_WPA3_SAE_DH(type)` is true. - The data format for import and export of the key is the raw bytes of the key. + .. return:: psa_ecc_family_t + The finite field group family id, if ``type`` is a supported WPA3-SAE password token using finite fields key. Unspecified if ``type`` is not a supported WPA3-SAE password token using finite fields key. - .. subsection:: Key derivation +.. _asymmetric-keys: - A call to `psa_key_derivation_output_key()` will draw 32 bytes of output and use these as the key data. +Asymmetric key types +-------------------- -.. _asymmetric-keys: +Asymmetric keys come in pairs. +One is a private or secret key, which must be kept confidential. +The other is a public key, which is meant to be shared with other participants in the protocol. -Asymmetric keys ---------------- +.. note:: + Depending on the type of cryptographic scheme, the private key can be referred to as the *prover key* or the *decapsulation key*, and the public key can be referred to as the *verifier key* or the *encapsulation key*. The |API| defines the following types of asymmetric key: @@ -613,10 +1148,16 @@ The |API| defines the following types of asymmetric key: * :secref:`dh-keys` * :secref:`spake2p-keys` +In the |API|, key objects can either be a key pair, providing both the private and public key, or just a public key. +The difference in the key type values for a key pair and a public key for the same scheme is common across all asymmetric keys. + +The `PSA_KEY_TYPE_KEY_PAIR_OF_PUBLIC_KEY()` and `PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR()` macros convert from one type to the other. + + .. _rsa-keys: RSA keys --------- +~~~~~~~~ .. macro:: PSA_KEY_TYPE_RSA_KEY_PAIR :definition: ((psa_key_type_t)0x7001) @@ -721,10 +1262,11 @@ RSA keys .. param:: type A key type: a value of type `psa_key_type_t`. + .. _ecc-keys: Elliptic Curve keys -------------------- +~~~~~~~~~~~~~~~~~~~ Elliptic curve keys are grouped into families of related curves. A keys for a specific curve is specified by a combination of the elliptic curve family and the bit-size of the key. @@ -762,34 +1304,6 @@ The curve type affects the key format, the key-derivation procedure, and the alg * - Twisted Edwards - `PSA_ECC_FAMILY_TWISTED_EDWARDS` -.. typedef:: uint8_t psa_ecc_family_t - - .. summary:: - The type of identifiers of an elliptic curve family. - - The curve identifier is required to create an ECC key using the `PSA_KEY_TYPE_ECC_KEY_PAIR()` or `PSA_KEY_TYPE_ECC_PUBLIC_KEY()` macros. - - The specific ECC curve within a family is identified by the ``key_bits`` attribute of the key. - - The range of elliptic curve family identifier values is divided as follows: - - :code:`0x00` - Reserved. - Not allocated to an ECC family. - :code:`0x01 - 0x7f` - ECC family identifiers defined by this standard. - Unallocated values in this range are reserved for future use. - :code:`0x80 - 0xff` - Invalid. - Values in this range must not be used. - - The least significant bit of a elliptic curve family identifier is a parity bit for the whole key type. - See :secref:`asymmetric-key-encoding` for details of the encoding of asymmetric key types. - - .. admonition:: Implementation note - - To provide other elliptic curve families, it is recommended that an implementation defines a key type with bit 15 set, which indicates an :scterm:`implementation defined` key type. - .. macro:: PSA_KEY_TYPE_ECC_KEY_PAIR :definition: /* specification-defined value */ @@ -901,263 +1415,105 @@ The curve type affects the key format, the key-derivation procedure, and the alg This method allows compliance to NIST standards, specifically the methods titled *Key-Pair Generation by Testing Candidates* in :cite:`SP800-56A` §5.6.1.2.2 or :cite-title:`FIPS186-4` §B.4.2. - * - Montgomery - - Draw a byte string whose length is determined by the curve, and set the mandatory bits accordingly. - That is: - - * Curve25519 (`PSA_ECC_FAMILY_MONTGOMERY`, 255 bits): draw a 32-byte string and process it as specified in :RFC-title:`7748#5`. - * Curve448 (`PSA_ECC_FAMILY_MONTGOMERY`, 448 bits): draw a 56-byte string and process it as specified in :RFC:`7748#5`. - - * - Twisted Edwards - - Draw a byte string whose length is determined by the curve, and use this as the private key. - That is: - - * Ed25519 (`PSA_ECC_FAMILY_MONTGOMERY`, 255 bits): draw a 32-byte string. - * Ed448 (`PSA_ECC_FAMILY_MONTGOMERY`, 448 bits): draw a 57-byte string. - -.. macro:: PSA_KEY_TYPE_ECC_PUBLIC_KEY - :definition: /* specification-defined value */ - - .. summary:: - Elliptic curve public key. - - .. param:: curve - A value of type `psa_ecc_family_t` that identifies the ECC curve family to be used. - - The size of an elliptic curve public key is the same as the corresponding private key. See `PSA_KEY_TYPE_ECC_KEY_PAIR()` and the documentation of each elliptic curve family for details. - - .. subsection:: Compatible algorithms - - :numref:`tab-ecc-public-key-algorithms` shows the compatible algorithms for each type of elliptic curve public key. - - .. note:: - - For key agreement, the public key of the peer is provided to the |API| as a buffer. - This avoids the need to import the public-key data that is received from the peer, just to carry out the key-agreement algorithm. - - .. list-table:: Compatible algorithms for elliptic curve public keys - :name: tab-ecc-public-key-algorithms - :class: longtable - :widths: 1,4 - :header-rows: 1 - - * - Curve type - - Compatible algorithms - * - Weierstrass - - Weierstrass curve public keys can be used in asymmetric signature and key-encapsulation algorithms. - - `PSA_ALG_DETERMINISTIC_ECDSA` - - `PSA_ALG_ECDSA` - - `PSA_ALG_ECDSA_ANY` - - `PSA_ALG_ECIES_SEC1` - - * - Montgomery - - Montgomery curve public keys can only be used in key-encapsulation algorithms. - - `PSA_ALG_ECIES_SEC1` - - * - Twisted Edwards - - Twisted Edwards curve public keys can only be used in asymmetric signature algorithms. - - `PSA_ALG_PURE_EDDSA` - - `PSA_ALG_ED25519PH` (Edwards25519 only) - - `PSA_ALG_ED448PH` (Edwards448 only) - - .. subsection:: Key format - - The data format for import and export of the public key depends on the type of elliptic curve. - :numref:`tab-ecc-public-key-format` shows the format for each type of elliptic curve public key. - - .. list-table:: Public-key formats for elliptic curve keys - :name: tab-ecc-public-key-format - :class: longtable - :widths: 1,4 - :header-rows: 1 - - * - Curve type - - Public-key format - * - Weierstrass - - The key data is the uncompressed representation of an elliptic curve point as an octet string defined in :cite-title:`SEC1` §2.3.3. - If :math:`m` is the bit size associated with the curve, i.e. the bit size of :math:`q` for a curve over :math:`\mathbb{F}_q`, then the representation of point :math:`P` consists of: - - * The byte ``0x04``; - * :math:`x_P` as a :math:`\lceil{m/8}\rceil`-byte string, big-endian; - * :math:`y_P` as a :math:`\lceil{m/8}\rceil`-byte string, big-endian. - - * - Montgomery - - The key data is the scalar value of the 'public key' in little-endian order as defined by :RFC-title:`7748#6`. - This is a :math:`\lceil{m/8}\rceil`-byte string where :math:`m` is the key size in bits. - - * This is 32 bytes for Curve25519, computed as ``X25519(private_key, 9)``. - * This is 56 bytes for Curve448, computed as ``X448(private_key, 5)``. - - * - Twisted Edwards - - The key data is the public key, as defined by :RFC-title:`8032`. - - This is a 32-byte string for Edwards25519, and a 57-byte string for Edwards448. - -.. macro:: PSA_ECC_FAMILY_SECP_K1 - :definition: ((psa_ecc_family_t) 0x17) - - .. summary:: - SEC Koblitz curves over prime fields. - - This family comprises the following curves: - - * secp192k1 : ``key_bits = 192`` - * secp224k1 : ``key_bits = 225`` - * secp256k1 : ``key_bits = 256`` - - They are defined in :cite-title:`SEC2`. - -.. macro:: PSA_ECC_FAMILY_SECP_R1 - :definition: ((psa_ecc_family_t) 0x12) - - .. summary:: - SEC random curves over prime fields. - - This family comprises the following curves: - - * secp192r1 : ``key_bits = 192`` - * secp224r1 : ``key_bits = 224`` - * secp256r1 : ``key_bits = 256`` - * secp384r1 : ``key_bits = 384`` - * secp521r1 : ``key_bits = 521`` - - They are defined in :cite:`SEC2`. - -.. macro:: PSA_ECC_FAMILY_SECP_R2 - :definition: ((psa_ecc_family_t) 0x1b) - - .. summary:: - .. warning:: - This family of curves is weak and deprecated. - - This family comprises the following curves: - - * secp160r2 : ``key_bits = 160`` *(Deprecated)* - - It is defined in the superseded :cite-title:`SEC2v1`. - -.. macro:: PSA_ECC_FAMILY_SECT_K1 - :definition: ((psa_ecc_family_t) 0x27) - - .. summary:: - SEC Koblitz curves over binary fields. - - This family comprises the following curves: - - * sect163k1 : ``key_bits = 163`` *(Deprecated)* - * sect233k1 : ``key_bits = 233`` - * sect239k1 : ``key_bits = 239`` - * sect283k1 : ``key_bits = 283`` - * sect409k1 : ``key_bits = 409`` - * sect571k1 : ``key_bits = 571`` - - They are defined in :cite:`SEC2`. - - .. warning:: - The 163-bit curve sect163k1 is weak and deprecated and is only recommended for use in legacy applications. - -.. macro:: PSA_ECC_FAMILY_SECT_R1 - :definition: ((psa_ecc_family_t) 0x22) - - .. summary:: - SEC random curves over binary fields. - - This family comprises the following curves: + * - Montgomery + - Draw a byte string whose length is determined by the curve, and set the mandatory bits accordingly. + That is: - * sect163r1 : ``key_bits = 163`` *(Deprecated)* - * sect233r1 : ``key_bits = 233`` - * sect283r1 : ``key_bits = 283`` - * sect409r1 : ``key_bits = 409`` - * sect571r1 : ``key_bits = 571`` + * Curve25519 (`PSA_ECC_FAMILY_MONTGOMERY`, 255 bits): draw a 32-byte string and process it as specified in :RFC-title:`7748#5`. + * Curve448 (`PSA_ECC_FAMILY_MONTGOMERY`, 448 bits): draw a 56-byte string and process it as specified in :RFC:`7748#5`. - They are defined in :cite:`SEC2`. + * - Twisted Edwards + - Draw a byte string whose length is determined by the curve, and use this as the private key. + That is: - .. warning:: - The 163-bit curve sect163r1 is weak and deprecated and is only recommended for use in legacy applications. + * Ed25519 (`PSA_ECC_FAMILY_MONTGOMERY`, 255 bits): draw a 32-byte string. + * Ed448 (`PSA_ECC_FAMILY_MONTGOMERY`, 448 bits): draw a 57-byte string. -.. macro:: PSA_ECC_FAMILY_SECT_R2 - :definition: ((psa_ecc_family_t) 0x2b) +.. macro:: PSA_KEY_TYPE_ECC_PUBLIC_KEY + :definition: /* specification-defined value */ .. summary:: - SEC additional random curves over binary fields. + Elliptic curve public key. - This family comprises the following curves: + .. param:: curve + A value of type `psa_ecc_family_t` that identifies the ECC curve family to be used. - * sect163r2 : ``key_bits = 163`` *(Deprecated)* + The size of an elliptic curve public key is the same as the corresponding private key. See `PSA_KEY_TYPE_ECC_KEY_PAIR()` and the documentation of each elliptic curve family for details. - It is defined in :cite:`SEC2`. + .. subsection:: Compatible algorithms - .. warning:: - The 163-bit curve sect163r2 is weak and deprecated and is only recommended for use in legacy applications. + :numref:`tab-ecc-public-key-algorithms` shows the compatible algorithms for each type of elliptic curve public key. -.. macro:: PSA_ECC_FAMILY_BRAINPOOL_P_R1 - :definition: ((psa_ecc_family_t) 0x30) + .. note:: - .. summary:: - Brainpool P random curves. + For key agreement, the public key of the peer is provided to the |API| as a buffer. + This avoids the need to import the public-key data that is received from the peer, just to carry out the key-agreement algorithm. - This family comprises the following curves: + .. list-table:: Compatible algorithms for elliptic curve public keys + :name: tab-ecc-public-key-algorithms + :class: longtable + :widths: 1,4 + :header-rows: 1 - * brainpoolP160r1 : ``key_bits = 160`` *(Deprecated)* - * brainpoolP192r1 : ``key_bits = 192`` - * brainpoolP224r1 : ``key_bits = 224`` - * brainpoolP256r1 : ``key_bits = 256`` - * brainpoolP320r1 : ``key_bits = 320`` - * brainpoolP384r1 : ``key_bits = 384`` - * brainpoolP512r1 : ``key_bits = 512`` + * - Curve type + - Compatible algorithms + * - Weierstrass + - Weierstrass curve public keys can be used in asymmetric signature and key-encapsulation algorithms. - They are defined in :rfc-title:`5639`. + `PSA_ALG_DETERMINISTIC_ECDSA` - .. warning:: - The 160-bit curve brainpoolP160r1 is weak and deprecated and is only recommended for use in legacy applications. + `PSA_ALG_ECDSA` -.. macro:: PSA_ECC_FAMILY_FRP - :definition: ((psa_ecc_family_t) 0x33) + `PSA_ALG_ECDSA_ANY` - .. summary:: - Curve used primarily in France and elsewhere in Europe. + `PSA_ALG_ECIES_SEC1` - This family comprises one 256-bit curve: + * - Montgomery + - Montgomery curve public keys can only be used in key-encapsulation algorithms. - * FRP256v1 : ``key_bits = 256`` + `PSA_ALG_ECIES_SEC1` - This is defined by :cite-title:`FRP`. + * - Twisted Edwards + - Twisted Edwards curve public keys can only be used in asymmetric signature algorithms. -.. macro:: PSA_ECC_FAMILY_MONTGOMERY - :definition: ((psa_ecc_family_t) 0x41) + `PSA_ALG_PURE_EDDSA` - .. summary:: - Montgomery curves. + `PSA_ALG_ED25519PH` (Edwards25519 only) - This family comprises the following Montgomery curves: + `PSA_ALG_ED448PH` (Edwards448 only) - * Curve25519 : ``key_bits = 255`` - * Curve448 : ``key_bits = 448`` + .. subsection:: Key format - Curve25519 is defined in :cite-title:`Curve25519`. Curve448 is defined in :cite-title:`Curve448`. + The data format for import and export of the public key depends on the type of elliptic curve. + :numref:`tab-ecc-public-key-format` shows the format for each type of elliptic curve public key. -.. macro:: PSA_ECC_FAMILY_TWISTED_EDWARDS - :definition: ((psa_ecc_family_t) 0x42) + .. list-table:: Public-key formats for elliptic curve keys + :name: tab-ecc-public-key-format + :class: longtable + :widths: 1,4 + :header-rows: 1 - .. summary:: - Twisted Edwards curves. + * - Curve type + - Public-key format + * - Weierstrass + - The key data is the uncompressed representation of an elliptic curve point as an octet string defined in :cite-title:`SEC1` §2.3.3. + If :math:`m` is the bit size associated with the curve, i.e. the bit size of :math:`q` for a curve over :math:`\mathbb{F}_q`, then the representation of point :math:`P` consists of: - .. versionadded:: 1.1 + * The byte ``0x04``; + * :math:`x_P` as a :math:`\lceil{m/8}\rceil`-byte string, big-endian; + * :math:`y_P` as a :math:`\lceil{m/8}\rceil`-byte string, big-endian. - This family comprises the following twisted Edwards curves: + * - Montgomery + - The key data is the scalar value of the 'public key' in little-endian order as defined by :RFC-title:`7748#6`. + This is a :math:`\lceil{m/8}\rceil`-byte string where :math:`m` is the key size in bits. - * Edwards25519 : ``key_bits = 255``. This curve is birationally equivalent to Curve25519. - * Edwards448 : ``key_bits = 448``. This curve is birationally equivalent to Curve448. + * This is 32 bytes for Curve25519, computed as ``X25519(private_key, 9)``. + * This is 56 bytes for Curve448, computed as ``X448(private_key, 5)``. - Edwards25519 is defined in :cite-title:`Ed25519`. Edwards448 is defined in :cite-title:`Curve448`. + * - Twisted Edwards + - The key data is the public key, as defined by :RFC-title:`8032`. + + This is a 32-byte string for Edwards25519, and a 57-byte string for Edwards448. .. macro:: PSA_KEY_TYPE_IS_ECC :definition: /* specification-defined value */ @@ -1198,47 +1554,20 @@ The curve type affects the key format, the key-derivation procedure, and the alg .. return:: psa_ecc_family_t The elliptic curve family id, if ``type`` is a supported elliptic curve key. Unspecified if ``type`` is not a supported elliptic curve key. + .. _dh-keys: Diffie Hellman keys -------------------- - -.. typedef:: uint8_t psa_dh_family_t - - .. summary:: - The type of identifiers of a finite-field Diffie-Hellman group family. - - The group family identifier is required to create a finite-field Diffie-Hellman key using the `PSA_KEY_TYPE_DH_KEY_PAIR()` or `PSA_KEY_TYPE_DH_PUBLIC_KEY()` macros. - - The specific Diffie-Hellman group within a family is identified by the ``key_bits`` attribute of the key. - - The range of Diffie-Hellman group family identifier values is divided as follows: - - :code:`0x00` - Reserved. - Not allocated to a DH group family. - :code:`0x01 - 0x7f` - DH group family identifiers defined by this standard. - Unallocated values in this range are reserved for future use. - :code:`0x80 - 0xff` - Invalid. - Values in this range must not be used. - - The least significant bit of a Diffie-Hellman group family identifier is a parity bit for the whole key type. - See :secref:`asymmetric-key-encoding` for details of the encoding of asymmetric key types. - - .. admonition:: Implementation note - - To provide other Diffie-Hellman group families, it is recommended that an implementation defines a key type with bit 15 set, which indicates an :scterm:`implementation defined` key type. +~~~~~~~~~~~~~~~~~~~ .. macro:: PSA_KEY_TYPE_DH_KEY_PAIR :definition: /* specification-defined value */ .. summary:: - Finite-field Diffie-Hellman key pair: both the private key and public key. + Finite field Diffie-Hellman key pair: both the private key and public key. .. param:: group - A value of type `psa_dh_family_t` that identifies the Diffie-Hellman group family to be used. + A value of type `psa_dh_family_t` that identifies the finite field Diffie-Hellman group family to be used. .. subsection:: Compatible algorithms @@ -1257,7 +1586,7 @@ Diffie Hellman keys A call to `psa_key_derivation_output_key()` will use the following process, defined in *Key-Pair Generation by Testing Candidates* in :cite-title:`SP800-56A` §5.6.1.1.4. - A Diffie-Hellman private key is :math:`x \in [1, p - 1]`, where :math:`p` is the group's prime modulus. + A finite field Diffie-Hellman private key is :math:`x \in [1, p - 1]`, where :math:`p` is the group's prime modulus. Let :math:`m` be the bit size of :math:`p`, such that :math:`2^{m-1} \leq p < 2^m`. This function generates the private key using the following process: @@ -1272,66 +1601,25 @@ Diffie Hellman keys :definition: /* specification-defined value */ .. summary:: - Finite-field Diffie-Hellman public key. + Finite field Diffie-Hellman public key. .. param:: group - A value of type `psa_dh_family_t` that identifies the Diffie-Hellman group family to be used. + A value of type `psa_dh_family_t` that identifies the finite field Diffie-Hellman group family to be used. .. subsection:: Compatible algorithms - None: Finite-field Diffie-Hellman public keys are exported to use in a key-agreement algorithm, and the peer key is provided to the `PSA_ALG_FFDH` key-agreement algorithm as a buffer of key data. + None: Finite field Diffie-Hellman public keys are exported to use in a key-agreement algorithm, and the peer key is provided to the `PSA_ALG_FFDH` key-agreement algorithm as a buffer of key data. .. subsection:: Key format The data format for export of the public key is the representation of the public key :math:`y = g^x\!\mod p` as a big-endian byte string. The length of the byte string is the length of the base prime :math:`p` in bytes. -.. macro:: PSA_DH_FAMILY_RFC7919 - :definition: ((psa_dh_family_t) 0x03) - - .. summary:: - Finite-field Diffie-Hellman groups defined for TLS in RFC 7919. - - This family includes groups with the following key sizes (in bits): 2048, 3072, 4096, 6144, 8192. - An implementation can support all of these sizes or only a subset. - - Keys is this group can only be used with the `PSA_ALG_FFDH` key-agreement algorithm. - - These groups are defined by :rfc-title:`7919#A`. - -.. macro:: PSA_KEY_TYPE_KEY_PAIR_OF_PUBLIC_KEY - :definition: /* specification-defined value */ - - .. summary:: - The key-pair type corresponding to a public-key type. - - .. param:: type - A public-key type or key-pair type. - - .. return:: - The corresponding key-pair type. If ``type`` is not a public key or a key pair, the return value is undefined. - - If ``type`` is a key-pair type, it will be left unchanged. - -.. macro:: PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR - :definition: /* specification-defined value */ - - .. summary:: - The public-key type corresponding to a key-pair type. - - .. param:: type - A public-key type or key-pair type. - - .. return:: - The corresponding public-key type. If ``type`` is not a public key or a key pair, the return value is undefined. - - If ``type`` is a public-key type, it will be left unchanged. - .. macro:: PSA_KEY_TYPE_IS_DH :definition: /* specification-defined value */ .. summary:: - Whether a key type is a Diffie-Hellman key, either a key pair or a public key. + Whether a key type is a finite field Diffie-Hellman key, either a key pair or a public key. .. param:: type A key type: a value of type `psa_key_type_t`. @@ -1340,7 +1628,7 @@ Diffie Hellman keys :definition: /* specification-defined value */ .. summary:: - Whether a key type is a Diffie-Hellman key pair. + Whether a key type is a finite field Diffie-Hellman key pair. .. param:: type A key type: a value of type `psa_key_type_t`. @@ -1349,7 +1637,7 @@ Diffie Hellman keys :definition: /* specification-defined value */ .. summary:: - Whether a key type is a Diffie-Hellman public key. + Whether a key type is a finite field Diffie-Hellman public key. .. param:: type A key type: a value of type `psa_key_type_t`. @@ -1358,18 +1646,19 @@ Diffie Hellman keys :definition: /* specification-defined value */ .. summary:: - Extract the group family from a Diffie-Hellman key type. + Extract the group family from a finite field Diffie-Hellman key type. .. param:: type - A Diffie-Hellman key type: a value of type `psa_key_type_t` such that :code:`PSA_KEY_TYPE_IS_DH(type)` is true. + A finite field Diffie-Hellman key type: a value of type `psa_key_type_t` such that :code:`PSA_KEY_TYPE_IS_DH(type)` is true. .. return:: psa_dh_family_t - The Diffie-Hellman group family id, if ``type`` is a supported Diffie-Hellman key. Unspecified if ``type`` is not a supported Diffie-Hellman key. + The finite field Diffie-Hellman group family id, if ``type`` is a supported finite field Diffie-Hellman key. Unspecified if ``type`` is not a supported finite field Diffie-Hellman key. + .. _spake2p-keys: SPAKE2+ keys ------------- +~~~~~~~~~~~~ .. macro:: PSA_KEY_TYPE_SPAKE2P_KEY_PAIR :definition: /* specification-defined value */ @@ -1527,74 +1816,34 @@ SPAKE2+ keys .. return:: psa_ecc_family_t The elliptic curve family id, if ``type`` is a supported SPAKE2+ key. Unspecified if ``type`` is not a supported SPAKE2+ key. -Attribute accessors -------------------- - -.. function:: psa_set_key_type - - .. summary:: - Declare the type of a key. - - .. param:: psa_key_attributes_t * attributes - The attribute object to write to. - .. param:: psa_key_type_t type - The key type to write. If this is `PSA_KEY_TYPE_NONE`, the key type in ``attributes`` becomes unspecified. - - .. return:: void - - This function overwrites any key type previously set in ``attributes``. - - .. admonition:: Implementation note - - This is a simple accessor function that is not required to validate its inputs. It can be efficiently implemented as a ``static inline`` function or a function-like-macro. - - -.. function:: psa_get_key_type - - .. summary:: - Retrieve the key type from key attributes. - - .. param:: const psa_key_attributes_t * attributes - The key attribute object to query. - - .. return:: psa_key_type_t - The key type stored in the attribute object. - - .. admonition:: Implementation note - - This is a simple accessor function that is not required to validate its inputs. It can be efficiently implemented as a ``static inline`` function or a function-like-macro. +Support macros +~~~~~~~~~~~~~~ -.. function:: psa_get_key_bits +.. macro:: PSA_KEY_TYPE_KEY_PAIR_OF_PUBLIC_KEY + :definition: /* specification-defined value */ .. summary:: - Retrieve the key size from key attributes. - - .. param:: const psa_key_attributes_t * attributes - The key attribute object to query. - - .. return:: size_t - The key size stored in the attribute object, in bits. + The key-pair type corresponding to a public-key type. - .. admonition:: Implementation note + .. param:: type + A public-key type or key-pair type. - This is a simple accessor function that is not required to validate its inputs. It can be efficiently implemented as a ``static inline`` function or a function-like-macro. + .. return:: + The corresponding key-pair type. If ``type`` is not a public key or a key pair, the return value is undefined. + If ``type`` is a key-pair type, it will be left unchanged. -.. function:: psa_set_key_bits +.. macro:: PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR + :definition: /* specification-defined value */ .. summary:: - Declare the size of a key. - - .. param:: psa_key_attributes_t * attributes - The attribute object to write to. - .. param:: size_t bits - The key size in bits. If this is ``0``, the key size in ``attributes`` becomes unspecified. Keys of size ``0`` are not supported. - - .. return:: void + The public-key type corresponding to a key-pair type. - This function overwrites any key size previously set in ``attributes``. + .. param:: type + A public-key type or key-pair type. - .. admonition:: Implementation note + .. return:: + The corresponding public-key type. If ``type`` is not a public key or a key pair, the return value is undefined. - This is a simple accessor function that is not required to validate its inputs. It can be efficiently implemented as a ``static inline`` function or a function-like-macro. + If ``type`` is a public-key type, it will be left unchanged. diff --git a/doc/crypto/api/ops/key-agreement.rst b/doc/crypto/api/ops/key-agreement.rst index eb15add6..cba8619e 100644 --- a/doc/crypto/api/ops/key-agreement.rst +++ b/doc/crypto/api/ops/key-agreement.rst @@ -32,7 +32,7 @@ Key-agreement algorithms :definition: ((psa_algorithm_t)0x09010000) .. summary:: - The finite-field Diffie-Hellman (DH) key-agreement algorithm. + The finite field Diffie-Hellman (DH) key-agreement algorithm. This standalone key-agreement algorithm can be used directly in a call to `psa_key_agreement()` or `psa_raw_key_agreement()`, or combined with a key-derivation operation using `PSA_ALG_KEY_AGREEMENT()` for use with `psa_key_derivation_key_agreement()`. @@ -41,7 +41,7 @@ Key-agreement algorithms * In a call to `psa_key_agreement()` or `psa_raw_key_agreement()`, with algorithm `PSA_ALG_FFDH`. * In a call to `psa_key_derivation_key_agreement()`, with any combined key-agreement and key-derivation algorithm constructed with `PSA_ALG_FFDH`. - When used as part of a multi-part key-derivation operation, this implements a Diffie-Hellman key-agreement scheme using a single Diffie-Hellman key pair for each participant. This includes the *dhEphem*, *dhOneFlow*, and *dhStatic* schemes. The input step `PSA_KEY_DERIVATION_INPUT_SECRET` is used when providing the secret and peer keys to the operation. + When used as part of a multi-part key-derivation operation, this implements a Diffie-Hellman key-agreement scheme using a single finite field Diffie-Hellman key pair for each participant. This includes the *dhEphem*, *dhOneFlow*, and *dhStatic* schemes. The input step `PSA_KEY_DERIVATION_INPUT_SECRET` is used when providing the secret and peer keys to the operation. The shared secret produced by this key-agreement algorithm is :math:`g^{ab}` in big-endian format. It is :math:`\lceil{(m / 8)}\rceil` bytes long where :math:`m` is the size of the prime :math:`p` in bits. @@ -226,7 +226,7 @@ Standalone key agreement This key can be used as input to a key-derivation operation using `psa_key_derivation_input_key()`. .. warning:: - The shared secret resulting from a key-agreement algorithm such as finite-field Diffie-Hellman or elliptic curve Diffie-Hellman has biases. This makes it unsuitable for use as key material, for example, as an AES key. Instead, it is recommended that a key-derivation algorithm is applied to the result, to derive unbiased cryptographic keys. + The shared secret resulting from a key-agreement algorithm such as finite field Diffie-Hellman or elliptic curve Diffie-Hellman has biases. This makes it unsuitable for use as key material, for example, as an AES key. Instead, it is recommended that a key-derivation algorithm is applied to the result, to derive unbiased cryptographic keys. .. function:: psa_raw_key_agreement @@ -288,7 +288,7 @@ Standalone key agreement A key-agreement algorithm takes two inputs: a private key ``private_key``, and a public key ``peer_key``. The result of this function is a shared secret, returned in the ``output`` buffer. .. warning:: - The result of a key-agreement algorithm such as finite-field Diffie-Hellman or elliptic curve Diffie-Hellman has biases, and is not suitable for direct use as key material, for example, as an AES key. Instead it is recommended that the result is used as input to a key-derivation algorithm. + The result of a key-agreement algorithm such as finite field Diffie-Hellman or elliptic curve Diffie-Hellman has biases, and is not suitable for direct use as key material, for example, as an AES key. Instead it is recommended that the result is used as input to a key-derivation algorithm. To chain a key agreement with a key derivation, either use `psa_key_agreement()` to obtain the result of the key agreement as a derivation key, or use `psa_key_derivation_key_agreement()` and other functions from the key-derivation interface. @@ -428,7 +428,7 @@ Support macros .. return:: ``1`` if ``alg`` is a finite field Diffie-Hellman algorithm, ``0`` otherwise. This macro can return either ``0`` or ``1`` if ``alg`` is not a supported key-agreement algorithm identifier. - This includes the standalone finite field Diffie-Hellman algorithm, as well as finite-field Diffie-Hellman combined with any supported key-derivation algorithm. + This includes the standalone finite field Diffie-Hellman algorithm, as well as finite field Diffie-Hellman combined with any supported key-derivation algorithm. .. macro:: PSA_ALG_IS_ECDH :definition: /* specification-defined value */ diff --git a/doc/crypto/api/ops/key-derivation.rst b/doc/crypto/api/ops/key-derivation.rst index 5a1d1250..c3cffcbb 100644 --- a/doc/crypto/api/ops/key-derivation.rst +++ b/doc/crypto/api/ops/key-derivation.rst @@ -359,6 +359,45 @@ Key-derivation algorithms | `PSA_KEY_TYPE_DERIVE` --- the secret key is extracted from a PAKE operation by calling :code:`psa_pake_get_shared_key()`. +.. macro:: PSA_ALG_WPA3_SAE_H2E + :definition: /* specification-defined value */ + + .. summary:: + The WPA3-SAE hash-to-element password token key-derivation algorithm. + + .. versionadded:: 1.4 + + .. param:: hash_alg + A hash algorithm: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_HASH(hash_alg)` is true. + This includes `PSA_ALG_ANY_HASH` when specifying the algorithm in a key policy. + + This KDF is defined in :cite-title:`IEEE-802.11` §12.4.4. + This specifies the hash-to-element procedures for deriving a WPA3-SAE password token from a network SSID and password. + The resulting password token is then used during a WPA3-SAE PAKE operation. + + This key-derivation algorithm uses the following inputs, which must be passed in the order given here: + + * `PSA_KEY_DERIVATION_INPUT_SALT` is the network SSID. + * `PSA_KEY_DERIVATION_INPUT_PASSWORD` is the password. + * `PSA_KEY_DERIVATION_INPUT_INFO` is the password identifier. + It is optional. + + This key derivation algorithm can only be used to derive and output a single key, which is obtained by a call to `psa_key_derivation_output_key()`. + The output has to be read as a key of type `PSA_KEY_TYPE_WPA3_SAE_DH` or `PSA_KEY_TYPE_WPA3_SAE_ECC`. + Requesting any other key type, or calling `psa_key_derivation_output_bytes()`, returns an error status. + + The ``hash_alg`` parameter to `PSA_ALG_WPA3_SAE_H2E()` determines the hash function used for the derivation. + The key attributes of the output key indicate the elliptic curve or finite field group used for the derivation. + + If the elliptic curve or finite field group specified in the key attributes is not compatible with the hash function used for the derivation, `psa_key_derivation_output_bytes()` returns :code:`PSA_ERROR_INVALID_ARGUMENT`. + See :secref:`wpa3-sae-cipher-suites`. + + :secref:`wpa3-sae-keys` provides details of the derivation procedures. + + .. 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 */ @@ -1323,6 +1362,21 @@ Support macros .. return:: ``1`` if ``alg`` is a PBKDF2-HMAC algorithm, ``0`` otherwise. This macro can return either ``0`` or ``1`` if ``alg`` is not a supported key-derivation algorithm identifier. +.. macro:: PSA_ALG_IS_WPA3_SAE_H2E + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is a WPA3-SAE hash-to-element key-derivation algorithm + + .. versionadded:: 1.4 + + .. param:: alg + An algorithm identifier: a value of type `psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is a WPA3-SAE hash-to-element algorithm, ``0`` otherwise. + This macro can return either ``0`` or ``1`` if ``alg`` is not a supported key-derivation algorithm identifier. + .. macro:: PSA_KEY_DERIVATION_UNLIMITED_CAPACITY :definition: /* implementation-defined value */ diff --git a/doc/crypto/api/ops/pake.rst b/doc/crypto/api/ops/pake.rst index 6fa518b0..0b07737c 100644 --- a/doc/crypto/api/ops/pake.rst +++ b/doc/crypto/api/ops/pake.rst @@ -18,6 +18,7 @@ This chapter is divided into the following sections: * :secref:`pake-common-api` --- the common interface elements, including the PAKE operation. * :secref:`pake-jpake` --- the J-PAKE protocol, and the associated interface elements. * :secref:`pake-spake2p` --- the SPAKE2+ protocols, and the associated interface elements. +* :secref:`pake-wpa3-sae` --- the WPA3-SAE protocol, and the associated interface elements. .. _pake-common-api: @@ -114,19 +115,19 @@ A PAKE primitive is required when constructing a PAKE cipher-suite object, `psa_ :definition: ((psa_pake_primitive_type_t)0x02) .. summary:: - The PAKE primitive type indicating the use of Diffie-Hellman groups. + The PAKE primitive type indicating the use of a finite field Diffie-Hellman group. .. versionadded:: 1.1 - The values of the ``family`` and ``bits`` components of the PAKE primitive identify a specific Diffie-Hellman group, using the same mapping that is used for Diffie-Hellman keys. + The values of the ``family`` and ``bits`` components of the PAKE primitive identify a specific finite field Diffie-Hellman group, using the same mapping that is used for finite field Diffie-Hellman keys. See the definition of ``psa_dh_family_t``. Here ``family`` and ``bits`` refer to the values used to construct the PAKE primitive using `PSA_PAKE_PRIMITIVE()`. Input and output during the operation can involve group elements and scalar values: - * The format for group elements is the same as that for public keys in the specific Diffie-Hellman group. + * The format for group elements is the same as that for public keys in the specific finite field Diffie-Hellman group. See *Key format* within the definition of `PSA_KEY_TYPE_DH_PUBLIC_KEY()`. - * The format for scalars is the same as that for private keys in the specific Diffie-Hellman group. + * The format for scalars is the same as that for private keys in the specific finite field Diffie-Hellman group. See *Key format* within the definition of `PSA_KEY_TYPE_DH_PUBLIC_KEY()`. @@ -289,7 +290,7 @@ A PAKE cipher suite is required when setting up a PAKE operation in `psa_pake_se - Value * - algorithm - - :code:`PSA_ALG_NONE` --- an invalid algorithm identifier. + - `PSA_ALG_NONE` --- an invalid algorithm identifier. * - primitive - ``0`` --- an invalid PAKE primitive. * - key confirmation @@ -351,7 +352,7 @@ A PAKE cipher suite is required when setting up a PAKE operation in `psa_pake_se .. param:: psa_pake_cipher_suite_t* cipher_suite The cipher suite object to write to. .. param:: psa_algorithm_t alg - The PAKE algorithm to write: a value of type :code:`psa_algorithm_t` such that :code:`PSA_ALG_IS_PAKE(alg)` is true. + The PAKE algorithm to write: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_PAKE(alg)` is true. .. return:: void @@ -565,13 +566,13 @@ PAKE step types :definition: ((psa_pake_step_t)0x01) .. summary:: - The key share being sent to or received from the peer. + A key share being sent to or received from a PAKE participant. .. versionadded:: 1.1 The format for both input and output using this step is the same as the format for public keys on the group specified by the PAKE operation's primitive. - The public-key formats are defined in the documentation for :code:`psa_export_public_key()`. + The public-key formats are defined in the documentation for `psa_export_public_key()`. For information regarding how the group is determined, consult the documentation `PSA_PAKE_PRIMITIVE()`. @@ -579,7 +580,7 @@ PAKE step types :definition: ((psa_pake_step_t)0x02) .. summary:: - A Schnorr NIZKP public key. + A Schnorr NIZKP public key being sent to or received from a PAKE participant. .. versionadded:: 1.1 @@ -587,7 +588,7 @@ PAKE step types The format for both input and output at this step is the same as that for public keys on the group specified by the PAKE operation's primitive. - For more information on the format, consult the documentation of :code:`psa_export_public_key()`. + For more information on the format, consult the documentation of `psa_export_public_key()`. For information regarding how the group is determined, consult the documentation `PSA_PAKE_PRIMITIVE()`. @@ -595,7 +596,7 @@ PAKE step types :definition: ((psa_pake_step_t)0x03) .. summary:: - A Schnorr NIZKP proof. + A Schnorr NIZKP proof being sent to or received from a PAKE participant. .. versionadded:: 1.1 @@ -605,7 +606,7 @@ PAKE step types The format depends on the group as well: * For Montgomery curves, the encoding is little endian. - * For other elliptic curves, and for Diffie-Hellman groups, the encoding is big endian. See :cite:`SEC1` §2.3.8. + * For other elliptic curves, and for finite field Diffie-Hellman groups, the encoding is big endian. See :cite:`SEC1` §2.3.8. In both cases leading zeroes are permitted as long as the length in bytes does not exceed the byte length of the group order. @@ -615,13 +616,81 @@ PAKE step types :definition: ((psa_pake_step_t)0x04) .. summary:: - The key confirmation value. + A key confirmation value being sent to or received from a PAKE participant. .. versionadded:: 1.2 - This value is used during the key confirmation phase of a PAKE protocol. The format of the value depends on the algorithm and cipher suite: + This value is used during the key confirmation phase of a PAKE protocol. + The use of this step, and format of the value depends on the algorithm and cipher suite: - * For :code:`PSA_ALG_SPAKE2P`, the format for both input and output at this step is the same as the output of the MAC algorithm specified in the cipher suite. + * For a SPAKE2+ algorithm, the format for both input and output at this step is the same as the output of the MAC algorithm specified in the cipher suite. + See :secref:`spake2p-operation`. + + * For a WPA3-SAE algorithm, the format for both input and output at this step is a 2-byte little-endian *send-confirm* counter, followed by the *confirm* value, which is the output from the hash algorithm specified in the cipher suite. + See :secref:`wpa3-sae-operation`. + +.. macro:: PSA_PAKE_STEP_SALT + :definition: ((psa_pake_step_t)0x05) + + .. summary:: + A salt value used for deriving shared secrets within a PAKE operation. + + .. versionadded:: 1.4 + + This input can be used during the key exchange phase of a PAKE protocol. + The use of this step, and format of the value depends on the algorithm and cipher suite: + + * For a WPA3-SAE algorithm, a salt value must be provided as defined in `[IEEE-802.11]` §12.4.5.4. + See :secref:`wpa3-sae-operation`. + +.. macro:: PSA_PAKE_STEP_COMMIT + :definition: ((psa_pake_step_t)0x06) + + .. summary:: + A commitment value being sent to or received from a PAKE participant. + + .. versionadded:: 1.4 + + This input and output is used during the key exchange phase of a PAKE protocol. + The use of this step, and format of the value depends on the algorithm and cipher suite: + + * For a WPA3-SAE algorithm, the format for input and output at this step is a concatenation of the *commit-scalar* and *COMMIT-ELEMENT* values, as defined in `[IEEE-802.11]` §12.4.7.3. + + See :secref:`wpa3-sae-operation`. + + .. note:: + + These values are adjacent in the WPA3-SAE Authentication frame defined in `[IEEE-802.11]` §9.3.3.11. + The concatenated value can be output directly to, or input directly from, the frame buffer. + +.. macro:: PSA_PAKE_STEP_CONFIRM_COUNT + :definition: ((psa_pake_step_t)0x07) + + .. summary:: + A counter used as part of key confirmation. + + .. versionadded:: 1.4 + + This value is input during the key confirmation phase of a PAKE protocol. + It enables multiple confirmation attempts to result in distinct confirmation values. + The use of this step, and format of the value depends on the algorithm and cipher suite: + + * For a WPA3-SAE algorithm, the format for input at this step is the 2-byte little-endian *send-confirm* counter. + See :secref:`wpa3-sae-operation`. + +.. macro:: PSA_PAKE_STEP_KEY_ID + :definition: ((psa_pake_step_t)0x08) + + .. summary:: + A key identifier value from a PAKE operation. + + .. versionadded:: 1.4 + + This value can be output from a PAKE operation following key confirmation. + The use of this step, and format of the value depends on the algorithm and cipher suite: + + * For a WPA3-SAE algorithm, the format of the output at this step is the 16-byte PMKID. + See :secref:`wpa3-sae-operation`. .. _pake-operation: @@ -702,7 +771,7 @@ Multi-part PAKE operations The valid key types depend on the PAKE algorithm, and participant role. Refer to the documentation of individual PAKE algorithms for more information. - The key must permit the usage :code:`PSA_KEY_USAGE_DERIVE`. + The key must permit the usage `PSA_KEY_USAGE_DERIVE`. .. param:: const psa_pake_cipher_suite_t * cipher_suite The cipher suite to use. A PAKE cipher suite fully characterizes a PAKE algorithm, including the PAKE algorithm. @@ -716,11 +785,11 @@ Multi-part PAKE operations The following conditions can result in this error: * The operation state is not valid: it must be inactive. - * The library requires initializing by a call to :code:`psa_crypto_init()`. + * The library requires initializing by a call to `psa_crypto_init()`. .. retval:: PSA_ERROR_INVALID_HANDLE ``password_key`` is not a valid key identifier. .. retval:: PSA_ERROR_NOT_PERMITTED - ``psssword_key`` does not have the :code:`PSA_KEY_USAGE_DERIVE` flag, or it does not permit the algorithm in ``cipher_suite``. + ``password_key`` does not have the `PSA_KEY_USAGE_DERIVE` flag, or it does not permit the algorithm in ``cipher_suite``. .. retval:: PSA_ERROR_INVALID_ARGUMENT The following conditions can result in this error: @@ -746,7 +815,7 @@ Multi-part PAKE operations 1. Allocate a PAKE operation object which will be passed to all the functions listed here. #. Initialize the operation object with one of the methods described in the documentation for `psa_pake_operation_t`. For example, using `PSA_PAKE_OPERATION_INIT`. - #. Call `psa_pake_setup()` to specify the cipher suite. + #. Call `psa_pake_setup()` to specify the cipher suite and provide the password or password-derived key. #. Call ``psa_pake_set_xxx()`` functions on the operation to complete the setup. The exact sequence of ``psa_pake_set_xxx()`` functions that needs to be called depends on the algorithm in use. @@ -793,7 +862,7 @@ Multi-part PAKE operations The following conditions can result in this error: * The operation state is not valid: it must be active, and `psa_pake_set_role()`, `psa_pake_input()`, and `psa_pake_output()` must not have been called yet. - * The library requires initializing by a call to :code:`psa_crypto_init()`. + * The library requires initializing by a call to `psa_crypto_init()`. .. retval:: PSA_ERROR_INVALID_ARGUMENT The following conditions can result in this error: @@ -836,7 +905,7 @@ Multi-part PAKE operations The following conditions can result in this error: * The operation state is not valid: it must be active, and `psa_pake_set_user()`, `psa_pake_input()`, and `psa_pake_output()` must not have been called yet. - * The library requires initializing by a call to :code:`psa_crypto_init()`. + * The library requires initializing by a call to `psa_crypto_init()`. .. retval:: PSA_ERROR_INVALID_ARGUMENT ``user_id`` is not valid for the operation's algorithm and cipher suite. .. retval:: PSA_ERROR_NOT_SUPPORTED @@ -873,7 +942,7 @@ Multi-part PAKE operations * The operation state is not valid: it must be active, and `psa_pake_set_peer()`, `psa_pake_input()`, and `psa_pake_output()` must not have been called yet. * Calling `psa_pake_set_peer()` is invalid with the operation's algorithm. - * The library requires initializing by a call to :code:`psa_crypto_init()`. + * The library requires initializing by a call to `psa_crypto_init()`. .. retval:: PSA_ERROR_INVALID_ARGUMENT ``peer_id`` is not valid for the operation's algorithm and cipher suite. .. retval:: PSA_ERROR_NOT_SUPPORTED @@ -910,7 +979,7 @@ Multi-part PAKE operations * The operation state is not valid: it must be active, and `psa_pake_set_context()`, `psa_pake_input()`, and `psa_pake_output()` must not have been called yet. * Calling `psa_pake_set_context()` is invalid with the operation's algorithm. - * The library requires initializing by a call to :code:`psa_crypto_init()`. + * The library requires initializing by a call to `psa_crypto_init()`. .. retval:: PSA_ERROR_INVALID_ARGUMENT ``context`` is not valid for the operation's algorithm and cipher suite. .. retval:: PSA_ERROR_NOT_SUPPORTED @@ -955,7 +1024,7 @@ Multi-part PAKE operations The following conditions can result in this error: * The operation state is not valid: it must be active and fully set up, and this call must conform to the algorithm's requirements for ordering of input and output steps. - * The library requires initializing by a call to :code:`psa_crypto_init()`. + * The library requires initializing by a call to `psa_crypto_init()`. .. retval:: PSA_ERROR_INVALID_ARGUMENT ``step`` is not compatible with the operation's algorithm. .. retval:: PSA_ERROR_NOT_SUPPORTED @@ -1002,7 +1071,7 @@ Multi-part PAKE operations The following conditions can result in this error: * The operation state is not valid: it must be active and fully set up, and this call must conform to the algorithm's requirements for ordering of input and output steps. - * The library requires initializing by a call to :code:`psa_crypto_init()`. + * The library requires initializing by a call to `psa_crypto_init()`. .. retval:: PSA_ERROR_INVALID_ARGUMENT The following conditions can result in this error: @@ -1046,8 +1115,8 @@ Multi-part PAKE operations The following attributes are required for all keys: * The key type. - All PAKE algorithms can output a key of type :code:`PSA_KEY_TYPE_DERIVE` or :code:`PSA_KEY_TYPE_HMAC`. - PAKE algorithms that produce a pseudorandom shared secret, can also output block-cipher key types, for example :code:`PSA_KEY_TYPE_AES`. + All PAKE algorithms can output a key of type `PSA_KEY_TYPE_DERIVE` or `PSA_KEY_TYPE_HMAC`. + PAKE algorithms that produce a pseudorandom shared secret, can also output block-cipher key types, for example `PSA_KEY_TYPE_AES`. Refer to the documentation of individual PAKE algorithms for more information. The following attributes must be set for keys used in cryptographic operations: @@ -1069,7 +1138,7 @@ Multi-part PAKE operations The final attributes of the new key can be queried by calling `psa_get_key_attributes()` with the key's identifier. .. param:: psa_key_id_t * key - On success, an identifier for the newly created key. :code:`PSA_KEY_ID_NULL` on failure. + On success, an identifier for the newly created key. `PSA_KEY_ID_NULL` on failure. .. return:: psa_status_t .. retval:: PSA_SUCCESS @@ -1083,7 +1152,7 @@ Multi-part PAKE operations For an unconfirmed key, this will be when the key-exchange output and input steps are complete, but prior to any key-confirmation output and input steps. For a confirmed key, this will be when all key-exchange and key-confirmation output and input steps are complete. - * The library requires initializing by a call to :code:`psa_crypto_init()`. + * The library requires initializing by a call to `psa_crypto_init()`. .. retval:: PSA_ERROR_ALREADY_EXISTS This is an attempt to create a persistent key, and there is already a persistent key with the given identifier. .. retval:: PSA_ERROR_NOT_SUPPORTED @@ -1140,9 +1209,6 @@ Multi-part PAKE operations Following key confirmation, the PAKE algorithm provides a cryptographic guarantee that the peer used the same password and identity inputs, and has computed the identical shared secret key. - Since the peer is not authenticated, no action should be taken that assumes that the peer is who it claims to be. - For example, do not access restricted resources on the peer's behalf until an explicit authentication has succeeded. - .. note:: Some PAKE algorithms do not include any key-confirmation steps. @@ -1169,7 +1235,7 @@ Multi-part PAKE operations .. retval:: PSA_ERROR_COMMUNICATION_FAILURE .. retval:: PSA_ERROR_CORRUPTION_DETECTED .. retval:: PSA_ERROR_BAD_STATE - The library requires initializing by a call to :code:`psa_crypto_init()`. + The library requires initializing by a call to `psa_crypto_init()`. Aborting an operation frees all associated resources except for the ``operation`` object itself. Once aborted, the operation object can be reused for another operation by calling `psa_pake_setup()` again. @@ -1193,7 +1259,7 @@ PAKE support macros .. versionadded:: 1.1 .. param:: alg - A PAKE algorithm: a value of type :code:`psa_algorithm_t` such that :code:`PSA_ALG_IS_PAKE(alg)` is true. + A PAKE algorithm: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_PAKE(alg)` is true. .. param:: primitive A primitive of type `psa_pake_primitive_t` that is compatible with algorithm ``alg``. .. param:: output_step @@ -1230,7 +1296,7 @@ PAKE support macros .. versionadded:: 1.1 .. param:: alg - A PAKE algorithm: a value of type :code:`psa_algorithm_t` such that :code:`PSA_ALG_IS_PAKE(alg)` is true. + A PAKE algorithm: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_PAKE(alg)` is true. .. param:: primitive A primitive of type `psa_pake_primitive_t` that is compatible with algorithm ``alg``. .. param:: input_step @@ -1277,7 +1343,7 @@ J-PAKE cipher suites When setting up a PAKE cipher suite to use the J-PAKE protocol: -* Use the :code:`PSA_ALG_JPAKE()` algorithm, parameterized by the required hash algorithm. +* Use the `PSA_ALG_JPAKE()` algorithm, parameterized by the required hash algorithm. * Use a PAKE primitive for the required elliptic curve, or finite field group. * J-PAKE does not confirm the shared secret key that results from the key exchange. @@ -1293,14 +1359,14 @@ For example, the following code creates a cipher suite to select J-PAKE using P- PSA_ECC_FAMILY_SECP_R1, 256)); psa_pake_cs_set_key_confirmation(&cipher_suite, PSA_PAKE_UNCONFIRMED_KEY); -More information on selecting a specific elliptic curve or Diffie-Hellman field is provided with the `PSA_PAKE_PRIMITIVE_TYPE_ECC` and `PSA_PAKE_PRIMITIVE_TYPE_DH` constants. +More information on selecting a specific elliptic curve or finite field Diffie-Hellman group is provided with the `PSA_PAKE_PRIMITIVE_TYPE_ECC` and `PSA_PAKE_PRIMITIVE_TYPE_DH` constants. .. _jpake-passwords: J-PAKE password processing ~~~~~~~~~~~~~~~~~~~~~~~~~~ -The PAKE operation for J-PAKE expects a key of type type :code:`PSA_KEY_TYPE_PASSWORD` or :code:`PSA_KEY_TYPE_PASSWORD_HASH`. +The PAKE operation for J-PAKE expects a key of type type `PSA_KEY_TYPE_PASSWORD` or PSA_KEY_TYPE_PASSWORD_HASH`. The same key value must be provided to the PAKE operation in both participants. The key can be the password text itself, in an agreed character encoding, or some value derived from the password, as required by a higher level protocol. @@ -1335,7 +1401,7 @@ A call to `psa_pake_set_context()` for a J-PAKE operation will fail with :code:` The following steps demonstrate the application code for 'User' in :numref:`fig-jpake`. The code flow for the 'Peer' is the same as for 'User', as J-PAKE is a balanced PAKE. -1. To prepare a J-PAKE operation, initialize and set up a :code:`psa_pake_operation_t` object by calling the following functions: +1. To prepare a J-PAKE operation, initialize and set up a `psa_pake_operation_t` object by calling the following functions: .. code-block:: xref @@ -1360,67 +1426,71 @@ After setup, the key exchange flow for J-PAKE is as follows: The application can either extract the round one output values first, and then provide the round one inputs that are received from the Peer; or provide the peer inputs first, and then extract the outputs. - * To get the first round data that needs to be sent to the peer, make the following calls to `psa_pake_output()`, in the order shown: + To get the first round data that needs to be sent to the peer, make the following calls to `psa_pake_output()`, in the order shown: - .. code-block:: xref + .. code-block:: xref - // Get g1 - psa_pake_output(&jpake, PSA_PAKE_STEP_KEY_SHARE, ...); - // Get V1, the ZKP public key for x1 - psa_pake_output(&jpake, PSA_PAKE_STEP_ZK_PUBLIC, ...); - // Get r1, the ZKP proof for x1 - psa_pake_output(&jpake, PSA_PAKE_STEP_ZK_PROOF, ...); - // Get g2 - psa_pake_output(&jpake, PSA_PAKE_STEP_KEY_SHARE, ...); - // Get V2, the ZKP public key for x2 - psa_pake_output(&jpake, PSA_PAKE_STEP_ZK_PUBLIC, ...); - // Get r2, the ZKP proof for x2 - psa_pake_output(&jpake, PSA_PAKE_STEP_ZK_PROOF, ...); - - * To provide the first round data received from the peer to the operation, make the following calls to `psa_pake_input()`, in the order shown: + // Get g1 + psa_pake_output(&jpake, PSA_PAKE_STEP_KEY_SHARE, ...); + // Get V1, the ZKP public key for x1 + psa_pake_output(&jpake, PSA_PAKE_STEP_ZK_PUBLIC, ...); + // Get r1, the ZKP proof for x1 + psa_pake_output(&jpake, PSA_PAKE_STEP_ZK_PROOF, ...); + // Get g2 + psa_pake_output(&jpake, PSA_PAKE_STEP_KEY_SHARE, ...); + // Get V2, the ZKP public key for x2 + psa_pake_output(&jpake, PSA_PAKE_STEP_ZK_PUBLIC, ...); + // Get r2, the ZKP proof for x2 + psa_pake_output(&jpake, PSA_PAKE_STEP_ZK_PROOF, ...); + + To provide the first round data received from the peer to the operation, make the following calls to `psa_pake_input()`, in the order shown: - .. code-block:: xref + .. code-block:: xref - // Set g3 - psa_pake_input(&jpake, PSA_PAKE_STEP_KEY_SHARE, ...); - // Set V3, the ZKP public key for x3 - psa_pake_input(&jpake, PSA_PAKE_STEP_ZK_PUBLIC, ...); - // Set r3, the ZKP proof for x3 - psa_pake_input(&jpake, PSA_PAKE_STEP_ZK_PROOF, ...); - // Set g4 - psa_pake_input(&jpake, PSA_PAKE_STEP_KEY_SHARE, ...); - // Set V4, the ZKP public key for x4 - psa_pake_input(&jpake, PSA_PAKE_STEP_ZK_PUBLIC, ...); - // Set r4, the ZKP proof for x4 - psa_pake_input(&jpake, PSA_PAKE_STEP_ZK_PROOF, ...); - -#. Round two. + // Set g3 + psa_pake_input(&jpake, PSA_PAKE_STEP_KEY_SHARE, ...); + // Set V3, the ZKP public key for x3 + psa_pake_input(&jpake, PSA_PAKE_STEP_ZK_PUBLIC, ...); + // Set r3, the ZKP proof for x3 + psa_pake_input(&jpake, PSA_PAKE_STEP_ZK_PROOF, ...); + // Set g4 + psa_pake_input(&jpake, PSA_PAKE_STEP_KEY_SHARE, ...); + // Set V4, the ZKP public key for x4 + psa_pake_input(&jpake, PSA_PAKE_STEP_ZK_PUBLIC, ...); + // Set r4, the ZKP proof for x4 + psa_pake_input(&jpake, PSA_PAKE_STEP_ZK_PROOF, ...); + +3. Round two. The application can either extract the round two output values first, and then provide the round two inputs that are received from the Peer; or provide the peer inputs first, and then extract the outputs. - * To get the second round data that needs to be sent to the peer, make the following calls to `psa_pake_output()`, in the order shown: + To get the second round data that needs to be sent to the peer, make the following calls to `psa_pake_output()`, in the order shown: - .. code-block:: xref + .. code-block:: xref - // Get A - psa_pake_output(&jpake, PSA_PAKE_STEP_KEY_SHARE, ...); - // Get V5, the ZKP public key for x2*s - psa_pake_output(&jpake, PSA_PAKE_STEP_ZK_PUBLIC, ...); - // Get r5, the ZKP proof for x2*s - psa_pake_output(&jpake, PSA_PAKE_STEP_ZK_PROOF, ...); + // Get A + psa_pake_output(&jpake, PSA_PAKE_STEP_KEY_SHARE, ...); + // Get V5, the ZKP public key for x2*s + psa_pake_output(&jpake, PSA_PAKE_STEP_ZK_PUBLIC, ...); + // Get r5, the ZKP proof for x2*s + psa_pake_output(&jpake, PSA_PAKE_STEP_ZK_PROOF, ...); - * To provide the second round data received from the peer to the operation, make the following calls to `psa_pake_input()`, in the order shown: + To provide the second round data received from the peer to the operation, make the following calls to `psa_pake_input()`, in the order shown: - .. code-block:: xref + .. code-block:: xref - // Set B - psa_pake_input(&jpake, PSA_PAKE_STEP_KEY_SHARE, ...); - // Set V6, the ZKP public key for x4*s - psa_pake_input(&jpake, PSA_PAKE_STEP_ZK_PUBLIC, ...); - // Set r6, the ZKP proof for x4*s - psa_pake_input(&jpake, PSA_PAKE_STEP_ZK_PROOF, ...); + // Set B + psa_pake_input(&jpake, PSA_PAKE_STEP_KEY_SHARE, ...); + // Set V6, the ZKP public key for x4*s + psa_pake_input(&jpake, PSA_PAKE_STEP_ZK_PUBLIC, ...); + // Set r6, the ZKP proof for x4*s + psa_pake_input(&jpake, PSA_PAKE_STEP_ZK_PROOF, ...); -#. To use the shared secret, extract it as a key-derivation key. For example, to extract a derivation key for HKDF-SHA-256: +Extract shared secret +^^^^^^^^^^^^^^^^^^^^^ + +4. To use the shared secret, extract it as a key-derivation key. + For example, to extract a derivation key for HKDF-SHA-256: .. code-block:: xref @@ -1465,7 +1535,7 @@ J-PAKE algorithms .. versionchanged:: 1.2 Parameterize J-PAKE algorithm by hash. .. param:: hash_alg - A hash algorithm: a value of type :code:`psa_algorithm_t` such that :code:`PSA_ALG_IS_HASH(hash_alg)` is true. + A hash algorithm: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_HASH(hash_alg)` is true. .. return:: A J-PAKE algorithm, parameterized by a specific hash. @@ -1487,8 +1557,8 @@ J-PAKE algorithms .. subsection:: Compatible key types - | :code:`PSA_KEY_TYPE_PASSWORD` - | :code:`PSA_KEY_TYPE_PASSWORD_HASH` + | `PSA_KEY_TYPE_PASSWORD` + | `PSA_KEY_TYPE_PASSWORD_HASH` .. macro:: PSA_ALG_IS_JPAKE :definition: /* specification-defined value */ @@ -1499,7 +1569,7 @@ J-PAKE algorithms .. versionadded:: 1.2 .. param:: alg - An algorithm identifier: a value of type :code:`psa_algorithm_t`. + An algorithm identifier: a value of type `psa_algorithm_t`. .. return:: ``1`` if ``alg`` is a J-PAKE algorithm, ``0`` otherwise. @@ -1536,8 +1606,8 @@ Valid combinations of these parameters are defined in the table of cipher suites When setting up a PAKE cipher suite to use the SPAKE2+ protocol defined in :rfc:`9383`: -* For cipher-suites that use HMAC for key confirmation, use the :code:`PSA_ALG_SPAKE2P_HMAC()` algorithm, parameterized by the required hash algorithm. -* For cipher-suites that use CMAC-AES-128 for key confirmation, use the :code:`PSA_ALG_SPAKE2P_CMAC()` algorithm, parameterized by the required hash algorithm. +* For cipher-suites that use HMAC for key confirmation, use the `PSA_ALG_SPAKE2P_HMAC()` algorithm, parameterized by the required hash algorithm. +* For cipher-suites that use CMAC-AES-128 for key confirmation, use the `PSA_ALG_SPAKE2P_CMAC()` algorithm, parameterized by the required hash algorithm. * Use a PAKE primitive for the required elliptic curve. For example, the following code creates a cipher suite to select SPAKE2+ using edwards25519 with the SHA-256 hash function: @@ -1553,7 +1623,7 @@ For example, the following code creates a cipher suite to select SPAKE2+ using e When setting up a PAKE cipher suite to use the SPAKE2+ protocol used by :cite:`MATTER`: -* Use the :code:`PSA_ALG_SPAKE2P_MATTER` algorithm. +* Use the `PSA_ALG_SPAKE2P_MATTER` algorithm. * Use the :code:`PSA_PAKE_PRIMITIVE(PSA_PAKE_PRIMITIVE_TYPE_ECC, PSA_ECC_FAMILY_SECP_R1, 256)` PAKE primitive. The following code creates a cipher suite to select the :cite:`MATTER` variant of SPAKE2+: @@ -1678,7 +1748,7 @@ In SPAKE2+, the Prover uses the `PSA_PAKE_ROLE_CLIENT` role, and the Verifier us The key passed to the Prover must be a SPAKE2+ key pair, which is derived as recommended in :secref:`spake2p-registration`. The key passed to the Verifier can either be a SPAKE2+ key pair, or a SPAKE2+ public key. -A SPAKE2+ public key is imported from data that is output by calling :code:`psa_export_public_key()` on a SPAKE2+ key pair. +A SPAKE2+ public key is imported from data that is output by calling `psa_export_public_key()` on a SPAKE2+ key pair. Both participants in SPAKE2+ have an optional identity. If no identity value is provided, then a zero-length string is used for that identity in the protocol. @@ -1696,7 +1766,7 @@ If the participants do not supply the same context value to the protocol, the co The following steps demonstrate the application code for both Prover and Verifier in :numref:`fig-spake2p`. **Prover** - To prepare a SPAKE2+ operation for the Prover, initialize and set up a :code:`psa_pake_operation_t` object by calling the following functions: + To prepare a SPAKE2+ operation for the Prover, initialize and set up a `psa_pake_operation_t` object by calling the following functions: .. code-block:: xref @@ -1718,7 +1788,7 @@ The following steps demonstrate the application code for both Prover and Verifie psa_pake_set_context(&spake2p_p, ...); // Optional context **Verifier** - To prepare a SPAKE2+ operation for the Verifier, initialize and set up a :code:`psa_pake_operation_t` object by calling the following functions: + To prepare a SPAKE2+ operation for the Verifier, initialize and set up a `psa_pake_operation_t` object by calling the following functions: .. code-block:: xref @@ -1739,8 +1809,8 @@ The following steps demonstrate the application code for both Prover and Verifie psa_pake_set_peer(&spake2p_v, ...); // Prover identity psa_pake_set_context(&spake2p_v, ...); // Optional context -Key exchange -^^^^^^^^^^^^ +Key exchange and confirmation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ After setup, the key exchange and confirmation flow for SPAKE2+ is as follows. @@ -1800,6 +1870,9 @@ After setup, the key exchange and confirmation flow for SPAKE2+ is as follows. // Set confirmP psa_pake_input(&spake2p_v, PSA_PAKE_STEP_CONFIRM, ...); +Extract shared secret +^^^^^^^^^^^^^^^^^^^^^ + **Prover** To use the shared secret, extract it as a key-derivation key. For example, to extract a derivation key for HKDF-SHA-256: @@ -1848,7 +1921,7 @@ SPAKE2+ algorithms .. versionadded:: 1.2 .. param:: hash_alg - A hash algorithm: a value of type :code:`psa_algorithm_t` such that :code:`PSA_ALG_IS_HASH(hash_alg)` is true. + A hash algorithm: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_HASH(hash_alg)` is true. .. return:: A SPAKE2+ algorithm, using HMAC for key confirmation, parameterized by a specific hash. @@ -1857,7 +1930,7 @@ SPAKE2+ algorithms This is SPAKE2+, as defined by :RFC-title:`9383`, for cipher suites that use HMAC for key confirmation. SPAKE2+ cipher suites are specified in :rfc:`9383#4`. - The cipher suite's hash algorithm is used as input to `PSA_ALG_SPAKE2P_HMAC()`. + See :secref:`spake2p-cipher-suites`. The shared secret that is produced by SPAKE2+ is pseudorandom. Although it can be used directly as an encryption key, it is recommended to use the shared secret as an input to a key-derivation operation to produce additional cryptographic keys. @@ -1866,8 +1939,8 @@ SPAKE2+ algorithms .. subsection:: Compatible key types - | :code:`PSA_KEY_TYPE_SPAKE2P_KEY_PAIR` - | :code:`PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY` (verification only) + | `PSA_KEY_TYPE_SPAKE2P_KEY_PAIR` + | `PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY` (verification only) .. macro:: PSA_ALG_SPAKE2P_CMAC :definition: /* specification-defined value */ @@ -1878,7 +1951,7 @@ SPAKE2+ algorithms .. versionadded:: 1.2 .. param:: hash_alg - A hash algorithm: a value of type :code:`psa_algorithm_t` such that :code:`PSA_ALG_IS_HASH(hash_alg)` is true. + A hash algorithm: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_HASH(hash_alg)` is true. .. return:: A SPAKE2+ algorithm, using CMAC for key confirmation, parameterized by a specific hash. @@ -1897,11 +1970,11 @@ SPAKE2+ algorithms .. subsection:: Compatible key types - | :code:`PSA_KEY_TYPE_SPAKE2P_KEY_PAIR` - | :code:`PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY` (verification only) + | `PSA_KEY_TYPE_SPAKE2P_KEY_PAIR` + | `PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY` (verification only) .. macro:: PSA_ALG_SPAKE2P_MATTER - :definition: ((psa_algoirithm_t)0x0A000609) + :definition: ((psa_algorithm_t)0x0A000609) .. summary:: The SPAKE2+ algorithm, as used by the Matter v1 specification. @@ -1935,8 +2008,8 @@ SPAKE2+ algorithms .. subsection:: Compatible key types - | :code:`PSA_KEY_TYPE_SPAKE2P_KEY_PAIR` - | :code:`PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY` (verification only) + | `PSA_KEY_TYPE_SPAKE2P_KEY_PAIR` + | `PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY` (verification only) .. macro:: PSA_ALG_IS_SPAKE2P :definition: /* specification-defined value */ @@ -1947,7 +2020,7 @@ SPAKE2+ algorithms .. versionadded:: 1.2 .. param:: alg - An algorithm identifier: a value of type :code:`psa_algorithm_t`. + An algorithm identifier: a value of type `psa_algorithm_t`. .. return:: ``1`` if ``alg`` is a SPAKE2+ algorithm, ``0`` otherwise. @@ -1964,7 +2037,7 @@ SPAKE2+ algorithms .. versionadded:: 1.2 .. param:: alg - An algorithm identifier: a value of type :code:`psa_algorithm_t`. + An algorithm identifier: a value of type `psa_algorithm_t`. .. return:: ``1`` if ``alg`` is a SPAKE2+ algorithm that uses a HMAC-based key confirmation, ``0`` otherwise. @@ -1981,10 +2054,482 @@ SPAKE2+ algorithms .. versionadded:: 1.2 .. param:: alg - An algorithm identifier: a value of type :code:`psa_algorithm_t`. + An algorithm identifier: a value of type `psa_algorithm_t`. .. return:: ``1`` if ``alg`` is a SPAKE2+ algorithm that uses a CMAC-based key confirmation, ``0`` otherwise. This macro can return either ``0`` or ``1`` if ``alg`` is not a supported PAKE algorithm identifier. SPAKE2+ algorithms, using CMAC-based key confirmation, are constructed using :code:`PSA_ALG_SPAKE2P_CMAC(hash_alg)`. + + +.. _pake-wpa3-sae: + +The WPA3-SAE protocol +--------------------- + +WPA3-SAE is a balanced, password-authenticated key exchange protocol, defined by :cite-title:`IEEE-802.11`. +It is used as the authentication and key exchange protocol for WLAN access points and mesh networks. +WPA3-SAE includes confirmation of the shared secret key that results from the key exchange. + +.. _wpa3-sae-cipher-suites: + +WPA3-SAE cipher suites +~~~~~~~~~~~~~~~~~~~~~~ + +WPA3-SAE is instantiated with the following parameters: + +* An elliptic curve group or a finite field cyclic group. +* A cryptographic hash function. + +`[IEEE-802.11]` describes three variants of the WPA3-SAE algorithm. +These differ in the method used to generate a password element (PWE) from the password, and in the size of the key confirmation key (SAE-KCK) and pairwise master key (PMK). + +:numref:`tab-wpa3-sae-variants` summarizes the properties of the different algorithm variants. + +.. list-table:: WPA3-SAE algorithm variants + :name: tab-wpa3-sae-variants + :header-rows: 1 + :widths: 4 3 3 2 2 + + * - Algorithm variant + - PWE method + - Hash algorithm + - SAE-KCK size + - PMK size + + * - Looping + - Looping + - SHA-256 + - 256 + - 256 + * - Hash-to-element + - Hash-to-element + - SHA-256 + + SHA-384 + + SHA-512 + - 256 + + 384 + + 512 + - 256 + + 256 + + 256 + * - Group-dependent-hash + - Hash-to-element + - SHA-256 + + SHA-384 + + SHA-512 + - 256 + + 384 + + 512 + - 256 + + 384 + + 512 + +When setting up a PAKE cipher suite to use the WPA3-SAE protocol: + +* For the looping variant, use the :code:`PSA_ALG_WPA3_SAE_FIXED(PSA_ALG_SHA_256)` algorithm. +* For the hash-to-element variant, use the :code:`PSA_ALG_WPA3_SAE_FIXED(hash_alg)` algorithm, where ``hash_alg`` is the required hash algorithm. +* For the group-dependent-hash variant, use the :code:`PSA_ALG_WPA3_SAE_GDH(hash_alg)` algorithm, where ``hash_alg`` is the required hash algorithm. +* Use a PAKE primitive for the required elliptic curve or finite field group. + +Valid elliptic curves and finite field groups for WPA3-SAE are defined in `[IEEE-802.11]` §12.4.4.1. +For the hash-to-element and group-dependent-hash variants, the required hash algorithm is determined from the size of the prime for the cyclic group. +See Table 12-1 in `[IEEE-802.11]` §12.4.2. + +If the hash algorithm in the cipher suite is not compatible with the WPA3-SAE algorithm and PAKE primitive, the call to `psa_pake_setup()` will fail with :code:`PSA_ERROR_INVALID_ARGUMENT`. + +For example, the following code creates a PAKE cipher suite for WPA3-SAE using hash-to-element over the secp256r1 elliptic curve (IANA group 19): + +.. code-block:: xref + + psa_pake_cipher_suite_t cipher_suite = PSA_PAKE_CIPHER_SUITE_INIT; + + psa_pake_cs_set_algorithm(&cipher_suite, PSA_ALG_WPA3_SAE_FIXED(PSA_ALG_SHA_256)); + psa_pake_cs_set_primitive(&cipher_suite, + PSA_PAKE_PRIMITIVE(PSA_PAKE_PRIMITIVE_TYPE_ECC, + PSA_ECC_FAMILY_SECP_R1, 256)); + + +.. _wpa3-sae-passwords: + +WPA3-SAE password processing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +WPA3-SAE defines the following two methods for deriving the password element PWE from the password: + +.. list-table:: + :widths: 1 4 + :class: borderless + + * - Looping method + - Repeatedly sample candidate element values using a hash computed from the password, until a valid element is found. + This derivation occurs as part of the authentication flow. + + * - Hash-to-element method + - Derive a password token element PT from the password, using the hash-to-curve procedure for elliptic curve groups, and a direct method for finite field groups. + This derivation can be carried out when the network SSID and password is provisioned to the device, and PT is stored as part of the configuration. + + During authentication, PWE is derived from PT. + +The hash-to-element method is recommended, as it is less vulnerable to timing-based attacks, and reduces the authentication time. + +:numref:`fig-wpa3-sae-pt` illustrates the password processing required prior to the WPA3-SAE authentication flow. + +.. figure:: /figure/pake/wpa3-sae-pt.* + :name: fig-wpa3-sae-pt + + 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 + +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. 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()`. + The key type is parameterized by the elliptic curve or finite field Diffie-Hellman group used in the required WPA3-SAE cipher suite. + + The password token key must be protected at least as well as the password. + +#. Pass the password token key to the WPA3-SAE PAKE operation in the call to `psa_pake_setup()`. + +.. 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. + +1. Allocate and initialize a key-derivation object: + + .. code-block:: xref + + psa_key_derivation_operation_t h2e_kdf = PSA_KEY_DERIVATION_OPERATION_INIT; + +#. Setup the key derivation from the WPA3-SAE password, ``password_key``, with network SSID ``ssid``: + + .. code-block:: xref + + psa_key_derivation_setup(&h2e_kdf, PSA_ALG_WPA3_SAE_H2E(PSA_ALG_SHA_384)); + psa_key_derivation_input_bytes(&h2e_kdf, PSA_KEY_DERIVATION_INPUT_SALT, ssid, ssid_len); + psa_key_derivation_input_key(&h2e_kdf, PSA_KEY_DERIVATION_INPUT_PASSWORD, password_key); + +#. Allocate and initialize a key attributes object: + + .. code-block:: xref + + psa_key_attributes_t pt_att = PSA_KEY_ATTRIBUTES_INIT; + +#. Set the key type, size, and policy: + + .. code-block:: xref + + psa_set_key_type(&pt_att, + PSA_KEY_TYPE_WPA3_SAE_ECC(PSA_ECC_FAMILY_SECP_R1)); + psa_set_key_bits(&pt_att, 384); + psa_set_key_usage_flags(&pt_att, PSA_KEY_USAGE_DERIVE); + psa_set_key_algorithm(&pt_att, PSA_ALG_WPA3_SAE_GDH(PSA_ALG_SHA_384)); + +#. Derive the password token key: + + .. code-block:: xref + + psa_key_id_t pt_key; + psa_key_derivation_output_key(&pt_att, &h2e_kdf, &pt_key); + psa_key_derivation_abort(&h2e_kdf); + +See :secref:`wpa3-sae-keys` for details of the key types and key derivation. + +.. _wpa3-sae-operation: + +WPA3-SAE operation +~~~~~~~~~~~~~~~~~~ + +The WPA3-SAE authentication operation follows the protocol shown in :numref:`fig-wpa3-sae`. + +.. figure:: /figure/pake/wpa3-sae.* + :name: fig-wpa3-sae + + The WPA3-SAE authentication and key confirmation protocol + + The variable names *commit-scalar*, *COMMIT-ELEMENT*, *peer-commit-scalar*, and so on, are taken from the description of WPA3-SAE in `[IEEE-802.11]` §12.4.5. + +Setup +^^^^^ + +The type of keys used to set up a PAKE multi-part operation for WPA3-SAE depends on the variant of WPA3-SAE that is required: + +* For the *Looping* variant, use a `PSA_KEY_TYPE_PASSWORD` key containing the secret password. +* For the *Hash-to-element* and *Group-dependent-hash* variants, use a `PSA_KEY_TYPE_WPA3_SAE_ECC` or `PSA_KEY_TYPE_WPA3_SAE_DH` key that is derived from the secret password, as described in :secref:`wpa3-sae-passwords`. + +WPA-SAE does not assign roles to the participants, so it is not necessary to call `psa_pake_set_role()`. + +WPA-SAE requires the MAC addresses of both participants, which are provided to the PAKE multi-part operation as the user and peer identities. + +WPA-SAE does not use a context. +A call to `psa_pake_set_context()` for a WPA-SAE operation will fail with :code:`PSA_ERROR_BAD_STATE`. + +The following steps demonstrate the application code for STA-A in :numref:`fig-wpa3-sae`. +The flow for STA-B is the same as for STA-A, as WPA3-SAE is a balanced PAKE. + +1. To prepare a WPA3-SAE operation, initialize and set up a `psa_pake_operation_t` object by calling the following functions: + + .. code-block:: xref + + psa_pake_operation_t wpa3_sae = PSA_PAKE_OPERATION_INIT; + + psa_pake_setup(&wpa3_sae, pt_key, &cipher_suite); + psa_pake_set_user(&wpa3_sae, &sta_a_mac, mac_length); + psa_pake_set_peer(&wpa3_sae, &sta_b_mac, mac_length); + + See :secref:`wpa3-sae-cipher-suites` and :secref:`wpa3-sae-passwords` for details on the requirements for the cipher suite and key. + +Commit +^^^^^^ + +2. Exchange commitment values to establish shared secret and confirmation keys. + + The application can either extract the commitment values first, and then provide the commitment values that are received from the peer; or provide the peer inputs first, and then extract the outputs. + + To get the commitment values to send to STA-B, call: + + .. code-block:: xref + + // Get commit-scalar || COMMIT-ELEMENT + psa_pake_output(&wpa3_sae, PSA_PAKE_STEP_COMMIT, ...); + + To provide and validate the commitment values from STA-B, call: + + .. code-block:: xref + + // Set peer-commit-scalar || PEER-COMMIT-ELEMENT + psa_pake_input(&wpa3_sae, PSA_PAKE_STEP_COMMIT, ...); + +3. Provide the salt used for shared secret derivation, as described in `[IEEE-802.11]` §12.4.5.4. + For Hash-to-element and Group-dependent-hash variants, this is the list of rejected groups. + + .. code-block:: xref + + // Set salt + psa_pake_input(&wpa3_sae, PSA_PAKE_STEP_SALT, ...); + +Confirm +^^^^^^^ + +4. Exchange and verify confirmation values. + + WPA3-SAE can make multiple attempts to confirm key establishment, to mitigate frame losses that can occur. + To prevent replay of confirmation messages, each attempt generates a distinct confirmation value by including a confirmation counter value. + + The application can either extract a confirmation value first, and then provide a confirmation value received from the peer; or provide the peer input first, and then extract the output. + + To get a confirmation value to send to STA-B, the confirmation counter value :math:`send{-}confirm` must be updated before extracting the combined *send-confirm* || *confirm* value, as follows: + + .. code-block:: xref + + // Set send-confirm counter + psa_pake_input(&wpa3_sae, PSA_PAKE_STEP_SEND_CONFIRM, ...); + // Get combined send-confirm || confirm value + psa_pake_output(&wpa3_sae, PSA_PAKE_STEP_CONFIRM, ...); + + To verify a confirmation value received from the peer, call: + + .. code-block:: xref + + // Set combined peer-send-confirm || peer-confirm value + psa_pake_input(&wpa3_sae, PSA_PAKE_STEP_CONFIRM, ...); + + .. note:: + + The application is permitted to request new confirmation values, or verify additional peer confirmation values, even after a peer confirmation value has been successfully verified. + +Extract shared secret +^^^^^^^^^^^^^^^^^^^^^ + +5. Optionally, to extract the identity of the shared secret key, PMKID, call: + + .. code-block:: xref + + // Get PMKID + psa_pake_output(&wpa3_sae, PSA_PAKE_STEP_KEY_ID, ...); + +6. To use the shared secret, extract it as a key-derivation key. + For example, to extract a derivation key for HKDF-SHA-256: + + .. code-block:: xref + + // Set up the key attributes + psa_key_attributes_t att = PSA_KEY_ATTRIBUTES_INIT; + psa_set_key_type(&att, PSA_KEY_TYPE_DERIVE); + psa_set_key_usage_flags(&att, PSA_KEY_USAGE_DERIVE); + psa_set_key_algorithm(&att, PSA_ALG_HKDF(PSA_ALG_SHA_256)); + + // Get K_shared + psa_key_id_t shared_key; + psa_pake_get_shared_key(&spake2p_p, &att, &shared_key); + +The shared secret that is produced by WPA3-SAE is pseudorandom. +Although it can be used directly as an encryption key, it is recommended to use the shared secret as an input to a key-derivation operation to produce additional cryptographic keys. + +For more information about the format of the values which are passed for each step, see :secref:`pake-steps`. + +If the validation of a commitment value fails, then the corresponding call to `psa_pake_input()` for the `PSA_PAKE_STEP_COMMIT` step will return :code:`PSA_ERROR_INVALID_ARGUMENT`. +If the verification of a confirmation value fails, then the corresponding call to `psa_pake_input()` for the `PSA_PAKE_STEP_CONFIRM` step will return :code:`PSA_ERROR_INVALID_SIGNATURE`. + +.. _wpa3-sae-algorithms: + +WPA3-SAE algorithms +------------------- + + +.. macro:: PSA_ALG_WPA3_SAE_FIXED + :definition: /* specification-defined value */ + + .. summary:: + Macro to build the WPA3-SAE algorithm, with fixed-sized PMK output key. + + .. versionadded:: 1.4 + + .. param:: hash_alg + A hash algorithm: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_HASH(hash_alg)` is true. + + .. return:: + A WPA3-SAE algorithm, for the Looping or Hash-to-element variants, parameterized by a specific hash. + + Unspecified if ``hash_alg`` is not a supported hash algorithm. + + This is WPA3-SAE, as defined by :cite-title:`IEEE-802.11` §12.4, using the Looping or Hash-to-element password element derivation procedure, with fixed-sized PMK output key. + + The hash algorithm specified must match one of the supported WPA3-SAE cipher suites. + See :secref:`wpa3-sae-cipher-suites`. + + The shared secret that is produced by WPA3-SAE is pseudorandom. + Although it can be used directly as an encryption key, it is recommended to use the shared secret as an input to a key-derivation operation to produce additional cryptographic keys. + + See :secref:`pake-wpa3-sae` for the WPA3-SAE protocol flow and how to implement it with the |API|. + + .. subsection:: Compatible key types + + | `PSA_KEY_TYPE_PASSWORD` + | `PSA_KEY_TYPE_WPA3_SAE_ECC` + | `PSA_KEY_TYPE_WPA3_SAE_DH` + +.. macro:: PSA_ALG_WPA3_SAE_GDH + :definition: /* specification-defined value */ + + .. summary:: + Macro to build the WPA3-SAE algorithm, with group-dependent size of the PMK output key. + + .. versionadded:: 1.4 + + .. param:: hash_alg + A hash algorithm: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_HASH(hash_alg)` is true. + + .. return:: + A WPA3-SAE algorithm, for the group-dependent-hash variant, parameterized by a specific hash. + + Unspecified if ``hash_alg`` is not a supported hash algorithm. + + This is WPA3-SAE, as defined by :cite-title:`IEEE-802.11` §12.4, using the hash-to-element password element derivation procedure, with group-dependent size for the PMK output key. + + The hash algorithm specified must match one of the supported WPA3-SAE cipher suites. + See :secref:`wpa3-sae-cipher-suites`. + + The shared secret that is produced by WPA3-SAE is pseudorandom. + Although it can be used directly as an encryption key, it is recommended to use the shared secret as an input to a key-derivation operation to produce additional cryptographic keys. + + See :secref:`pake-wpa3-sae` for the WPA3-SAE protocol flow and how to implement it with the |API|. + + .. subsection:: Compatible key types + + | `PSA_KEY_TYPE_WPA3_SAE_ECC` + | `PSA_KEY_TYPE_WPA3_SAE_DH` + +.. macro:: PSA_ALG_IS_WPA3_SAE + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is a WPA3-SAE algorithm. + + .. versionadded:: 1.4 + + .. param:: alg + An algorithm identifier: a value of type `psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is a WPA3-SAE algorithm, ``0`` otherwise. + This macro can return either ``0`` or ``1`` if ``alg`` is not a supported PAKE algorithm identifier. + + WPA3-SAE algorithms are constructed using :code:`PSA_ALG_WPA3_SAE_FIXED(hash_alg)` or :code:`PSA_ALG_WPA3_SAE_GDH(hash_alg)`. + +.. macro:: PSA_ALG_IS_WPA3_SAE_FIXED + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is a WPA3-SAE algorithm with a fixed-sized output key. + + .. versionadded:: 1.4 + + .. param:: alg + An algorithm identifier: a value of type `psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is a WPA3-SAE algorithm with a fixed-sized output key, ``0`` otherwise. + This macro can return either ``0`` or ``1`` if ``alg`` is not a supported PAKE algorithm identifier. + + WPA3-SAE algorithms with a fixed-sized output key, are constructed using :code:`PSA_ALG_WPA3_SAE_FIXED(hash_alg)`. + +.. macro:: PSA_ALG_IS_WPA3_SAE_GDH + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is a WPA3-SAE algorithm with a group-dependent size for the output key. + + .. versionadded:: 1.4 + + .. param:: alg + An algorithm identifier: a value of type `psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is a WPA3-SAE algorithm with a group-dependent size for the output key, ``0`` otherwise. + This macro can return either ``0`` or ``1`` if ``alg`` is not a supported PAKE algorithm identifier. + + 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)0x0a0088ff) + + .. summary:: + A wildcard algorithm for WPA3-SAE password keys and password token keys. + + .. versionadded:: 1.4 + + 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. + + 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. diff --git a/doc/crypto/appendix/encodings.rst b/doc/crypto/appendix/encodings.rst index 50bfb290..17c26d6d 100644 --- a/doc/crypto/appendix/encodings.rst +++ b/doc/crypto/appendix/encodings.rst @@ -335,6 +335,7 @@ The permitted values of HASH-TYPE (see :numref:`table-hash-type`) depend on the SP 800-108 Counter CMAC, 0, ``0x08``, :code:`PSA_ALG_SP800_108_COUNTER_CMAC`, ``0x08000800`` PBKDF2-HMAC, 1, ``0x01``, :code:`PSA_ALG_PBKDF2_HMAC(hash)`, ``0x088001hh`` :sup:`a` PBKDF2-AES-CMAC-PRF-128, 1, ``0x02``, :code:`PSA_ALG_PBKDF2_AES_CMAC_PRF_128`, ``0x08800200`` + WPA3-SAE Hash-to-element, 1, ``0x04``, :code:`PSA_ALG_WPA3_SAE_H2E(hash)`, ``0x088004hh`` :sup:`a` a. ``hh`` is the HASH-TYPE for the hash algorithm, ``hash``, used to construct the key-derivation algorithm. @@ -489,9 +490,16 @@ The permitted values of HASH-TYPE (see :numref:`table-hash-type`) depend on the SPAKE2+ with HMAC, ``0x04``, :code:`PSA_ALG_SPAKE2P_HMAC(hash)`, ``0x0A0004hh`` :sup:`a` SPAKE2+ with CMAC, ``0x05``, :code:`PSA_ALG_SPAKE2P_CMAC(hash)`, ``0x0A0005hh`` :sup:`a` 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 @@ -555,6 +563,7 @@ The A and CAT fields in a key type take the values shown in :numref:`table-key-t None, 0, 0, See `PSA_KEY_TYPE_NONE` Raw data, 0, 1, See :secref:`raw-key-encoding` Symmetric key, 0, 2, See :secref:`symmetric-key-encoding` + Structured key, 0, 3, See :secref:`structured-key-encoding` Asymmetric public key, 1, 0, See :secref:`asymmetric-key-encoding` Asymmetric key pair, 1, 3, See :secref:`asymmetric-key-encoding` @@ -618,6 +627,86 @@ The defined values for BLK, SYM-TYPE and P are shown in :numref:`table-symmetric SM4, 4, 2, 1, `PSA_KEY_TYPE_SM4`, ``0x2405`` ARIA, 4, 3, 0, `PSA_KEY_TYPE_ARIA`, ``0x2406`` +.. _structured-key-encoding: + +Structured key encoding +~~~~~~~~~~~~~~~~~~~~~~~ + +The key type for structured keys defined in this specification are encoded as shown in :numref:`fig-structured-key-fields`. + +.. figure:: ../figure/encoding/structured_key.* + :name: fig-structured-key-fields + + Encoding of structured keys + +The defined values for STRUCT-TYPE are shown in :numref:`table-structured-type`. + +The defined values for FAMILY depend on the STRUCT-TYPE value. See the details for each structured key sub-type. + +.. csv-table:: Structured key sub-type values + :name: table-structured-type + :header-rows: 1 + :align: left + :widths: auto + + Structured key type, STRUCT-TYPE, Details + WPA3-SAE password token, "5, 6", See :secref:`wpa3-sae-key-encoding` + +.. _wpa3-sae-key-encoding: + +WPA3-SAE password token encoding +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +WPA3-SAE is defined to use either elliptic curve or finite field groups. +These use distinct STRUCT-TYPE values, and use the same FAMILY values as elliptic curve and finite field Diffie-Hellman key types. + +.. rubric:: WPA3-SAE password tokens using elliptic curves + +The key type for WPA3-SAE password tokens using elliptic curves defined in this specification are encoded as shown in :numref:`fig-wpa3-sae-ecc-fields`. + +.. figure:: ../figure/encoding/wpa3_sae_ecc_key.* + :name: fig-wpa3-sae-ecc-fields + + Encoding of WPA3-SAE password token using elliptic curves + +The defined values for ECC-FAMILY and P are shown in :numref:`table-wpa3-sae-ecc-type`. + +.. csv-table:: WPA3-SAE password token ECC family values + :name: table-wpa3-sae-ecc-type + :header-rows: 1 + :align: left + :widths: auto + + WPA3-SAE suite, ECC-FAMILY, P, ECC family :sup:`a`, Key value + SECP R1, 0x09, 0, `PSA_ECC_FAMILY_SECP_R1`, ``0x3292`` + Brainpool-P R1, 0x18, 0, `PSA_ECC_FAMILY_BRAINPOOL_P_R1`, ``0x32b0`` + +a. The elliptic curve family values defined in the API also include the parity bit. The password token key type value is constructed from the elliptic curve family using :code:`PSA_KEY_TYPE_WPA3_SAE_ECC(family)`. + +.. rubric:: WPA3-SAE password tokens using finite fields + +The key type for WPA3-SAE password tokens using finite fields defined in this specification are encoded as shown in :numref:`fig-wpa3-sae-dh-fields`. + +.. figure:: ../figure/encoding/wpa3_sae_dh_key.* + :name: fig-wpa3-sae-dh-fields + + Encoding of WPA3-SAE password token using finite fields + +The defined values for DH-FAMILY and P are shown in :numref:`table-wpa3-sae-dh-type`. + +RFC3526 defines a set of FF groups that are recommended for use with WPA3-SAE (those with primes >=3072 bits) + +.. csv-table:: WPA3-SAE password token finite field Diffie-Hellman family values + :name: table-wpa3-sae-dh-type + :header-rows: 1 + :align: left + :widths: auto + + WPA3-SAE suite, DH-FAMILY, P, DH family :sup:`a`, Key value + RFC3526, 0x02, 1, `PSA_DH_FAMILY_RFC3526`, ``0x3305`` + +a. The finite field Diffie Hellman family values defined in the API also include the parity bit. The password token key type value is constructed from the finite field Diffie Hellman family using :code:`PSA_KEY_TYPE_WPA3_SAE_DH(family)`. + .. _asymmetric-key-encoding: Asymmetric key encoding @@ -712,30 +801,30 @@ a. The elliptic curve family values defined in the API also include the parity .. _dh-key-encoding: -Diffie Hellman key encoding -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Finite field Diffie Hellman key encoding +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The key type for Diffie Hellman keys defined in this specification are encoded as shown in :numref:`fig-dh-key-fields`. +The key type for finite field Diffie Hellman keys defined in this specification are encoded as shown in :numref:`fig-dh-key-fields`. .. figure:: ../figure/encoding/dh_key.* :name: fig-dh-key-fields - Diffie Hellman key encoding + Finite field Diffie Hellman key encoding PAIR is either 0 for a public key, or 3 for a key pair. The defined values for DH-FAMILY and P are shown in :numref:`table-dh-type`. -.. csv-table:: Diffie Hellman key group values +.. csv-table:: Finite field Diffie Hellman key group values :name: table-dh-type :header-rows: 1 :align: left :widths: auto - DH key group, DH-FAMILY, P, DH group :sup:`a`, Public-key value, Key-pair value + DH key group, DH-FAMILY, P, DH family :sup:`a`, Public-key value, Key-pair value RFC7919, 0x01, 1, `PSA_DH_FAMILY_RFC7919`, ``0x4203``, ``0x7203`` -a. The Diffie Hellman family values defined in the API also include the parity bit. The key type value is constructed from the Diffie Hellman family using either :code:`PSA_KEY_TYPE_DH_PUBLIC_KEY(family)` or :code:`PSA_KEY_TYPE_DH_KEY_PAIR(family)` as required. +a. The finite field Diffie Hellman group family values defined in the API also include the parity bit. The key type value is constructed from the finite field Diffie Hellman family using either :code:`PSA_KEY_TYPE_DH_PUBLIC_KEY(family)` or :code:`PSA_KEY_TYPE_DH_KEY_PAIR(family)` as required. .. _spakep2-key-encoding: diff --git a/doc/crypto/appendix/history.rst b/doc/crypto/appendix/history.rst index 8f36ac0e..855929d8 100644 --- a/doc/crypto/appendix/history.rst +++ b/doc/crypto/appendix/history.rst @@ -14,6 +14,8 @@ This section provides the detailed changes made between published version of the Changes between *1.3.2* and *1.4.0* ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:issue:`TBD` + Changes to the API ~~~~~~~~~~~~~~~~~~ @@ -24,6 +26,16 @@ Changes to the API * Added support for key wrapping using key-wrapping algorithms. See :secref:`key-wrapping`. +* Added support for the WPA3-SAE PAKE: + + - Add `PSA_KEY_TYPE_WPA3_SAE_ECC` and `PSA_KEY_TYPE_WPA3_SAE_DH` key types for WPA3-SAE password tokens. + - 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`. + Clarifications and fixes ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -32,7 +44,8 @@ Clarifications and fixes Other changes ~~~~~~~~~~~~~ -* TBD +* Reorganised the chapter on key types. + See :secref:`key-types`. Changes between *1.3.1* and *1.3.2* ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/doc/crypto/appendix/specdef_values.rst b/doc/crypto/appendix/specdef_values.rst index cc331b3c..235920ff 100644 --- a/doc/crypto/appendix/specdef_values.rst +++ b/doc/crypto/appendix/specdef_values.rst @@ -190,9 +190,22 @@ Algorithm macros (((alg) & ~0x000000ff) == 0x08000300) #define PSA_ALG_IS_WILDCARD(alg) \ - ((PSA_ALG_GET_HASH(alg) == PSA_ALG_ANY_HASH) || \ - (((alg) & 0x7f008000) == 0x03008000) || \ - (((alg) & 0x7f008000) == 0x05008000)) + (PSA_ALG_GET_HASH(alg) == PSA_ALG_ANY_HASH || \ + ((alg) & 0x7f008000) == 0x03008000 || \ + ((alg) & 0x7f008000) == 0x05008000 || \ + (alg) == PSA_ALG_CCM_STAR_ANY_TAG) + + #define PSA_ALG_IS_WPA3_SAE(alg) \ + (((alg) & ~0x000001ff) == 0x0a000800) + + #define PSA_ALG_IS_WPA3_SAE_FIXED(alg) \ + (((alg) & ~0x000000ff) == 0x0a000800) + + #define PSA_ALG_IS_WPA3_SAE_GDH(alg) \ + (((alg) & ~0x000000ff) == 0x0a000900) + + #define PSA_ALG_IS_WPA3_SAE_H2E(alg) \ + (((alg) & ~0x000000ff) == 0x08800400) #define PSA_ALG_IS_XOF(alg) \ (((alg) & 0x7f000000) == 0x0D000000) @@ -204,25 +217,25 @@ Algorithm macros ((ka_alg) | (kdf_alg)) #define PSA_ALG_KEY_AGREEMENT_GET_BASE(alg) \ - ((psa_algorithm_t)((alg) & 0xff7f0000)) + ((psa_algorithm_t) ((alg) & 0xff7f0000)) #define PSA_ALG_KEY_AGREEMENT_GET_KDF(alg) \ - ((psa_algorithm_t)((alg) & 0xfe80ffff)) + ((psa_algorithm_t) ((alg) & 0xfe80ffff)) #define PSA_ALG_PBKDF2_HMAC(hash_alg) \ - ((psa_algorithm_t)(0x08800100 | ((hash_alg) & 0x000000ff))) + ((psa_algorithm_t) (0x08800100 | ((hash_alg) & 0x000000ff))) #define PSA_ALG_RSA_OAEP(hash_alg) \ - ((psa_algorithm_t)(0x07000300 | ((hash_alg) & 0x000000ff))) + ((psa_algorithm_t) (0x07000300 | ((hash_alg) & 0x000000ff))) #define PSA_ALG_RSA_PKCS1V15_SIGN(hash_alg) \ - ((psa_algorithm_t)(0x06000200 | ((hash_alg) & 0x000000ff))) + ((psa_algorithm_t) (0x06000200 | ((hash_alg) & 0x000000ff))) #define PSA_ALG_RSA_PSS(hash_alg) \ - ((psa_algorithm_t)(0x06000300 | ((hash_alg) & 0x000000ff))) + ((psa_algorithm_t) (0x06000300 | ((hash_alg) & 0x000000ff))) #define PSA_ALG_RSA_PSS_ANY_SALT(hash_alg) \ - ((psa_algorithm_t)(0x06001300 | ((hash_alg) & 0x000000ff))) + ((psa_algorithm_t) (0x06001300 | ((hash_alg) & 0x000000ff))) #define PSA_ALG_SP800_108_COUNTER_HMAC(hash_alg) \ ((psa_algorithm_t) (0x08000700 | ((hash_alg) & 0x000000ff))) @@ -242,6 +255,15 @@ Algorithm macros #define PSA_ALG_TRUNCATED_MAC(mac_alg, mac_length) \ ((psa_algorithm_t) (((mac_alg) & ~0x003f8000) | (((mac_length) & 0x3f) << 16))) + #define PSA_ALG_WPA3_SAE_FIXED(hash_alg) \ + ((psa_algorithm_t) (0x0a000800 | ((hash_alg) & 0x000000ff))) + + #define PSA_ALG_WPA3_SAE_GDH(hash_alg) \ + ((psa_algorithm_t) (0x0a000900 | ((hash_alg) & 0x000000ff))) + + #define PSA_ALG_WPA3_SAE_H2E(hash_alg) \ + ((psa_algorithm_t) (0x08800400 | ((hash_alg) & 0x000000ff))) + #define PSA_PAKE_PRIMITIVE(pake_type, pake_family, pake_bits) \ ((pake_bits & 0xFFFF) != pake_bits) ? 0 : \ ((psa_pake_primitive_t) (((pake_type) << 24 | \ @@ -326,6 +348,12 @@ Key type macros #define PSA_KEY_TYPE_IS_UNSTRUCTURED(type) \ (((type) & 0x7000) == 0x1000 || ((type) & 0x7000) == 0x2000) + #define PSA_KEY_TYPE_IS_WPA3_SAE_DH(type) \ + (((type) & 0xff80) == 0x3300) + + #define PSA_KEY_TYPE_IS_WPA3_SAE_ECC(type) \ + (((type) & 0xff80) == 0x3280) + #define PSA_KEY_TYPE_KEY_PAIR_OF_PUBLIC_KEY(type) \ ((psa_key_type_t) ((type) | 0x3000)) @@ -341,6 +369,18 @@ Key type macros #define PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY(curve) \ ((psa_key_type_t) (0x4400 | ((curve) & 0x007f))) + #define PSA_KEY_TYPE_WPA3_SAE_DH_GET_FAMILY(type) \ + ((psa_dh_family_t) ((type) & 0x007f)) + + #define PSA_KEY_TYPE_WPA3_SAE_DH(family) \ + ((psa_key_type_t) (0x3300 | ((family) & 0x007f))) + + #define PSA_KEY_TYPE_WPA3_SAE_ECC_GET_FAMILY(type) \ + ((psa_ecc_family_t) ((type) & 0x007f)) + + #define PSA_KEY_TYPE_WPA3_SAE_ECC(curve) \ + ((psa_key_type_t) (0x3280 | ((curve) & 0x007f))) + Hash suspend state macros ~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/crypto/figure/encoding/structured_key.json b/doc/crypto/figure/encoding/structured_key.json new file mode 100644 index 00000000..c43097a8 --- /dev/null +++ b/doc/crypto/figure/encoding/structured_key.json @@ -0,0 +1,18 @@ +{ + "reg": [ + { "name": "P", "bits": 1 }, + { "name": "FAMILY", "bits": 6 }, + { "name": "STRUCT-TYPE", "bits": 5 }, + { "name": "3", "bits": 2 }, + { "name": "0", "bits": 1 }, + { "name": "0", "bits": 1 } + ], + "config": { + "lanes": 1, + "fontfamily": "lato", + "fontsize": 11, + "bits": 16, + "vspace": 52, + "hspace": 300 + } +} diff --git a/doc/crypto/figure/encoding/structured_key.json.license b/doc/crypto/figure/encoding/structured_key.json.license new file mode 100644 index 00000000..b66dc6de --- /dev/null +++ b/doc/crypto/figure/encoding/structured_key.json.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright 2025 Arm Limited and/or its affiliates +SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license diff --git a/doc/crypto/figure/encoding/structured_key.pdf b/doc/crypto/figure/encoding/structured_key.pdf new file mode 100644 index 00000000..a27a2c8a Binary files /dev/null and b/doc/crypto/figure/encoding/structured_key.pdf differ diff --git a/doc/crypto/figure/encoding/structured_key.pdf.license b/doc/crypto/figure/encoding/structured_key.pdf.license new file mode 100644 index 00000000..b66dc6de --- /dev/null +++ b/doc/crypto/figure/encoding/structured_key.pdf.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright 2025 Arm Limited and/or its affiliates +SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license diff --git a/doc/crypto/figure/encoding/structured_key.svg b/doc/crypto/figure/encoding/structured_key.svg new file mode 100644 index 00000000..64e12cf6 --- /dev/null +++ b/doc/crypto/figure/encoding/structured_key.svg @@ -0,0 +1,2 @@ + +01671112131415PFAMILYSTRUCT-TYPE300 \ No newline at end of file diff --git a/doc/crypto/figure/encoding/structured_key.svg.license b/doc/crypto/figure/encoding/structured_key.svg.license new file mode 100644 index 00000000..b66dc6de --- /dev/null +++ b/doc/crypto/figure/encoding/structured_key.svg.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright 2025 Arm Limited and/or its affiliates +SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license diff --git a/doc/crypto/figure/encoding/wpa3_sae_dh_key.json b/doc/crypto/figure/encoding/wpa3_sae_dh_key.json new file mode 100644 index 00000000..bdb3eb86 --- /dev/null +++ b/doc/crypto/figure/encoding/wpa3_sae_dh_key.json @@ -0,0 +1,18 @@ +{ + "reg": [ + { "name": "P", "bits": 1 }, + { "name": "DH-FAMILY", "bits": 6 }, + { "name": "6", "bits": 5 }, + { "name": "3", "bits": 2 }, + { "name": "0", "bits": 1 }, + { "name": "0", "bits": 1 } + ], + "config": { + "lanes": 1, + "fontfamily": "lato", + "fontsize": 11, + "bits": 16, + "vspace": 52, + "hspace": 300 + } +} diff --git a/doc/crypto/figure/encoding/wpa3_sae_dh_key.json.license b/doc/crypto/figure/encoding/wpa3_sae_dh_key.json.license new file mode 100644 index 00000000..b66dc6de --- /dev/null +++ b/doc/crypto/figure/encoding/wpa3_sae_dh_key.json.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright 2025 Arm Limited and/or its affiliates +SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license diff --git a/doc/crypto/figure/encoding/wpa3_sae_dh_key.pdf b/doc/crypto/figure/encoding/wpa3_sae_dh_key.pdf new file mode 100644 index 00000000..fbfb90f2 Binary files /dev/null and b/doc/crypto/figure/encoding/wpa3_sae_dh_key.pdf differ diff --git a/doc/crypto/figure/encoding/wpa3_sae_dh_key.pdf.license b/doc/crypto/figure/encoding/wpa3_sae_dh_key.pdf.license new file mode 100644 index 00000000..b66dc6de --- /dev/null +++ b/doc/crypto/figure/encoding/wpa3_sae_dh_key.pdf.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright 2025 Arm Limited and/or its affiliates +SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license diff --git a/doc/crypto/figure/encoding/wpa3_sae_dh_key.svg b/doc/crypto/figure/encoding/wpa3_sae_dh_key.svg new file mode 100644 index 00000000..4387f5ea --- /dev/null +++ b/doc/crypto/figure/encoding/wpa3_sae_dh_key.svg @@ -0,0 +1,2 @@ + +01671112131415PDH-FAMILY6300 \ No newline at end of file diff --git a/doc/crypto/figure/encoding/wpa3_sae_dh_key.svg.license b/doc/crypto/figure/encoding/wpa3_sae_dh_key.svg.license new file mode 100644 index 00000000..b66dc6de --- /dev/null +++ b/doc/crypto/figure/encoding/wpa3_sae_dh_key.svg.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright 2025 Arm Limited and/or its affiliates +SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license diff --git a/doc/crypto/figure/encoding/wpa3_sae_ecc_key.json b/doc/crypto/figure/encoding/wpa3_sae_ecc_key.json new file mode 100644 index 00000000..60891c1d --- /dev/null +++ b/doc/crypto/figure/encoding/wpa3_sae_ecc_key.json @@ -0,0 +1,18 @@ +{ + "reg": [ + { "name": "P", "bits": 1 }, + { "name": "ECC-FAMILY", "bits": 6 }, + { "name": "5", "bits": 5 }, + { "name": "3", "bits": 2 }, + { "name": "0", "bits": 1 }, + { "name": "0", "bits": 1 } + ], + "config": { + "lanes": 1, + "fontfamily": "lato", + "fontsize": 11, + "bits": 16, + "vspace": 52, + "hspace": 300 + } +} diff --git a/doc/crypto/figure/encoding/wpa3_sae_ecc_key.json.license b/doc/crypto/figure/encoding/wpa3_sae_ecc_key.json.license new file mode 100644 index 00000000..b66dc6de --- /dev/null +++ b/doc/crypto/figure/encoding/wpa3_sae_ecc_key.json.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright 2025 Arm Limited and/or its affiliates +SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license diff --git a/doc/crypto/figure/encoding/wpa3_sae_ecc_key.pdf b/doc/crypto/figure/encoding/wpa3_sae_ecc_key.pdf new file mode 100644 index 00000000..00cf9690 Binary files /dev/null and b/doc/crypto/figure/encoding/wpa3_sae_ecc_key.pdf differ diff --git a/doc/crypto/figure/encoding/wpa3_sae_ecc_key.pdf.license b/doc/crypto/figure/encoding/wpa3_sae_ecc_key.pdf.license new file mode 100644 index 00000000..b66dc6de --- /dev/null +++ b/doc/crypto/figure/encoding/wpa3_sae_ecc_key.pdf.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright 2025 Arm Limited and/or its affiliates +SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license diff --git a/doc/crypto/figure/encoding/wpa3_sae_ecc_key.svg b/doc/crypto/figure/encoding/wpa3_sae_ecc_key.svg new file mode 100644 index 00000000..de523792 --- /dev/null +++ b/doc/crypto/figure/encoding/wpa3_sae_ecc_key.svg @@ -0,0 +1,2 @@ + +01671112131415PECC-FAMILY5300 \ No newline at end of file diff --git a/doc/crypto/figure/encoding/wpa3_sae_ecc_key.svg.license b/doc/crypto/figure/encoding/wpa3_sae_ecc_key.svg.license new file mode 100644 index 00000000..b66dc6de --- /dev/null +++ b/doc/crypto/figure/encoding/wpa3_sae_ecc_key.svg.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright 2025 Arm Limited and/or its affiliates +SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license diff --git a/doc/crypto/figure/pake/wpa3-sae-pt.pdf b/doc/crypto/figure/pake/wpa3-sae-pt.pdf new file mode 100644 index 00000000..fc41d3a9 Binary files /dev/null and b/doc/crypto/figure/pake/wpa3-sae-pt.pdf differ diff --git a/doc/crypto/figure/pake/wpa3-sae-pt.pdf.license b/doc/crypto/figure/pake/wpa3-sae-pt.pdf.license new file mode 100644 index 00000000..b66dc6de --- /dev/null +++ b/doc/crypto/figure/pake/wpa3-sae-pt.pdf.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright 2025 Arm Limited and/or its affiliates +SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license diff --git a/doc/crypto/figure/pake/wpa3-sae-pt.puml b/doc/crypto/figure/pake/wpa3-sae-pt.puml new file mode 100644 index 00000000..596c0102 --- /dev/null +++ b/doc/crypto/figure/pake/wpa3-sae-pt.puml @@ -0,0 +1,31 @@ +' SPDX-FileCopyrightText: Copyright 2025 Arm Limited and/or its affiliates +' SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license + +@startuml + + !include atg-spec.pumh + + participant "station (STA)" as Participant + + note over Participant: Initial information : cipher suite, //SSID//, //password// [, //password-identifier//] + + alt Hash-to-element generation of password element + + Participant -> Participant: ""psa_key_derivation_setup(WPA3_SAE_H2E)""\n""psa_key_derivation_input_bytes(SALT = SSID)""\n""psa_key_derivation_input_key(PASSWORD = password)"" + opt + Participant -> Participant: ""psa_key_derivation_input_bytes(INFO = password-identifier)"" + end + + Participant -> Participant: ""psa_key_derivation_output_key(WPA3_SAE_XX)"" + + note left: Compute password token //PT// + + note over Participant: Use //PT// for authentication flow + + else Generation of the password element by looping + + note over Participant: Use //password// for authentication flow + + end + +@enduml diff --git a/doc/crypto/figure/pake/wpa3-sae-pt.svg b/doc/crypto/figure/pake/wpa3-sae-pt.svg new file mode 100644 index 00000000..7287cd9b --- /dev/null +++ b/doc/crypto/figure/pake/wpa3-sae-pt.svg @@ -0,0 +1 @@ +station (STA)station (STA)Initial information : cipher suite,SSID,password[,password-identifier]alt[Hash-to-element generation of password element]psa_key_derivation_setup(WPA3_SAE_H2E)psa_key_derivation_input_bytes(SALT = SSID)psa_key_derivation_input_key(PASSWORD = password)optpsa_key_derivation_input_bytes(INFO = password-identifier)psa_key_derivation_output_key(WPA3_SAE_XX)Compute password tokenPTUsePTfor authentication flow[Generation of the password element by looping]Usepasswordfor authentication flow \ No newline at end of file diff --git a/doc/crypto/figure/pake/wpa3-sae-pt.svg.license b/doc/crypto/figure/pake/wpa3-sae-pt.svg.license new file mode 100644 index 00000000..b66dc6de --- /dev/null +++ b/doc/crypto/figure/pake/wpa3-sae-pt.svg.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright 2025 Arm Limited and/or its affiliates +SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license diff --git a/doc/crypto/figure/pake/wpa3-sae.pdf b/doc/crypto/figure/pake/wpa3-sae.pdf new file mode 100644 index 00000000..a8f84edf Binary files /dev/null and b/doc/crypto/figure/pake/wpa3-sae.pdf differ diff --git a/doc/crypto/figure/pake/wpa3-sae.pdf.license b/doc/crypto/figure/pake/wpa3-sae.pdf.license new file mode 100644 index 00000000..b66dc6de --- /dev/null +++ b/doc/crypto/figure/pake/wpa3-sae.pdf.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright 2025 Arm Limited and/or its affiliates +SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license diff --git a/doc/crypto/figure/pake/wpa3-sae.puml b/doc/crypto/figure/pake/wpa3-sae.puml new file mode 100644 index 00000000..4718e614 --- /dev/null +++ b/doc/crypto/figure/pake/wpa3-sae.puml @@ -0,0 +1,55 @@ +' SPDX-FileCopyrightText: Copyright 2025 Arm Limited and/or its affiliates +' SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license + +@startuml + + !include atg-spec.pumh + + participant "STA-A" as STAA + participant "STA-B" as STAB + + note over STAA, STAB + Shared information: cipher suite, //STA-A-MAC//, //STA-B-MAC// + If generating PWE by looping: //password// + If generating PWE by hash-to-element: //PT// + end note + + STAA -> STAA: ""psa_pake_setup()""\n""psa_pake_set_user(STA-A-MAC)""\n""psa_pake_set_peer(STA-B-MAC)"" + note left: Provide either //password// or //PT// to\n""psa_pake_setup()"" depending\non PWE generation method + + STAA -> STAA: ""psa_pake_output()"" for //commit-scalar// || //COMMIT-ELEMENT// + note left: Generate //rand//, //mask//; compute\n//commit-scalar//, //COMMIT-ELEMENT// + + + STAA ->> STAB: //SAE Commit// frame //(commit-scalar, COMMIT-ELEMENT)// + + STAB ->> STAA: //SAE Commit// frame //(peer-commit-scalar, PEER-COMMIT-ELEMENT)// + + STAA -> STAA: ""psa_pake_input()"" for //peer-commit-scalar// || //PEER-COMMIT-ELEMENT// + note left: Validate inputs; compute //k// + + STAA -> STAA: ""psa_pake_input()"" for //salt// + note left: Compute //SAE-KCK//, //PMK// + + loop Until //SAE Confirm// frame is successfully delivered to STA-B + STAA -> STAA: ""psa_pake_input()"" for //send-confirm// counter + + STAA -> STAA: ""psa_pake_output()"" for //send-confirm// || //confirm// + note left: Compute //confirm// + + STAA ->> STAB: //SAE Confirm// frame //(send-confirm, confirm)// + + end + + STAB ->> STAA: //SAE Confirm// frame //(peer-send-confirm, peer-confirm)// + + STAA -> STAA: ""psa_pake_input()"" for //peer-send-confirm// || //peer-confirm// + note left: Compute and validate\n//peer-verify// = //peer-confirm// + + opt + STAA -> STAA: ""psa_pake_output()"" for //PMKID// + end + + STAA -> STAA: ""psa_pake_get_shared_key()"" to extract //PMK// + +@enduml diff --git a/doc/crypto/figure/pake/wpa3-sae.svg b/doc/crypto/figure/pake/wpa3-sae.svg new file mode 100644 index 00000000..f10f160b --- /dev/null +++ b/doc/crypto/figure/pake/wpa3-sae.svg @@ -0,0 +1 @@ +STA-ASTA-BSTA-ASTA-BShared information: cipher suite,STA-A-MAC,STA-B-MACIf generating PWE by looping:passwordIf generating PWE by hash-to-element:PTpsa_pake_setup()psa_pake_set_user(STA-A-MAC)psa_pake_set_peer(STA-B-MAC)Provide eitherpasswordorPTtopsa_pake_setup()dependingon PWE generation methodpsa_pake_output()forcommit-scalar||COMMIT-ELEMENTGeneraterand,mask; computecommit-scalar,COMMIT-ELEMENTSAE Commitframe(commit-scalar, COMMIT-ELEMENT)SAE Commitframe(peer-commit-scalar, PEER-COMMIT-ELEMENT)psa_pake_input()forpeer-commit-scalar||PEER-COMMIT-ELEMENTValidate inputs; computekpsa_pake_input()forsaltComputeSAE-KCK,PMKloop[UntilSAE Confirmframe is successfully delivered to STA-B]psa_pake_input()forsend-confirmcounterpsa_pake_output()forsend-confirm||confirmComputeconfirmSAE Confirmframe(send-confirm, confirm)SAE Confirmframe(peer-send-confirm, peer-confirm)psa_pake_input()forpeer-send-confirm||peer-confirmCompute and validatepeer-verify=peer-confirmoptpsa_pake_output()forPMKIDpsa_pake_get_shared_key()to extractPMK \ No newline at end of file diff --git a/doc/crypto/figure/pake/wpa3-sae.svg.license b/doc/crypto/figure/pake/wpa3-sae.svg.license new file mode 100644 index 00000000..b66dc6de --- /dev/null +++ b/doc/crypto/figure/pake/wpa3-sae.svg.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright 2025 Arm Limited and/or its affiliates +SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license diff --git a/doc/crypto/references b/doc/crypto/references index 6c2e31d6..5dc3aad7 100644 --- a/doc/crypto/references +++ b/doc/crypto/references @@ -425,3 +425,15 @@ :author: NIST :publication: December 2012 :url: doi.org/10.6028/NIST.SP.800-38F + +.. reference:: RFC3526 + :title: More Modular Exponential (MODP) Diffie-Hellman groups for Internet Key Exchange (IKE) + :author: IETF + :publication: May 2003 + :url: tools.ietf.org/html/rfc3526.html + +.. reference:: IEEE-802.11 + :title: IEEE 802.11-2024: Wireless LAN Medium Access Control (MAC) and Physical Layer (PHY) Specifications + :author: IEEE + :publication: 2024 + :url: standards.ieee.org/ieee/802.11/10548/