diff --git a/doc/crypto/api.db/psa/crypto.h b/doc/crypto/api.db/psa/crypto.h index 7f993076..63b2aa91 100644 --- a/doc/crypto/api.db/psa/crypto.h +++ b/doc/crypto/api.db/psa/crypto.h @@ -17,6 +17,13 @@ typedef uint8_t psa_key_persistence_t; typedef uint16_t psa_key_type_t; typedef uint32_t psa_key_usage_t; typedef /* implementation-defined type */ psa_mac_operation_t; +typedef /* implementation-defined type */ psa_pake_cipher_suite_t; +typedef uint8_t psa_pake_family_t; +typedef /* implementation-defined type */ psa_pake_operation_t; +typedef uint32_t psa_pake_primitive_t; +typedef uint8_t psa_pake_primitive_type_t; +typedef uint8_t psa_pake_role_t; +typedef uint8_t psa_pake_step_t; #define PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE(ciphertext_length) \ /* implementation-defined value */ #define PSA_AEAD_DECRYPT_OUTPUT_SIZE(key_type, alg, ciphertext_length) \ @@ -92,11 +99,13 @@ typedef /* implementation-defined type */ psa_mac_operation_t; #define PSA_ALG_IS_HKDF_EXPAND(alg) /* specification-defined value */ #define PSA_ALG_IS_HKDF_EXTRACT(alg) /* specification-defined value */ #define PSA_ALG_IS_HMAC(alg) /* specification-defined value */ +#define PSA_ALG_IS_JPAKE(alg) /* specification-defined value */ #define PSA_ALG_IS_KEY_AGREEMENT(alg) /* specification-defined value */ #define PSA_ALG_IS_KEY_DERIVATION(alg) /* specification-defined value */ #define PSA_ALG_IS_KEY_DERIVATION_STRETCHING(alg) \ /* specification-defined value */ #define PSA_ALG_IS_MAC(alg) /* specification-defined value */ +#define PSA_ALG_IS_PAKE(alg) /* specification-defined value */ #define PSA_ALG_IS_PBKDF2_HMAC(alg) /* specification-defined value */ #define PSA_ALG_IS_RANDOMIZED_ECDSA(alg) /* specification-defined value */ #define PSA_ALG_IS_RAW_KEY_AGREEMENT(alg) \ @@ -111,12 +120,16 @@ typedef /* implementation-defined type */ psa_mac_operation_t; #define PSA_ALG_IS_SIGN_MESSAGE(alg) /* specification-defined value */ #define PSA_ALG_IS_SP800_108_COUNTER_HMAC(alg) \ /* specification-defined value */ +#define PSA_ALG_IS_SPAKE2P(alg) /* specification-defined value */ +#define PSA_ALG_IS_SPAKE2P_CMAC(alg) /* specification-defined value */ +#define PSA_ALG_IS_SPAKE2P_HMAC(alg) /* specification-defined value */ #define PSA_ALG_IS_STANDALONE_KEY_AGREEMENT(alg) \ /* specification-defined value */ #define PSA_ALG_IS_STREAM_CIPHER(alg) /* specification-defined value */ #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_JPAKE(hash_alg) /* specification-defined value */ #define PSA_ALG_KEY_AGREEMENT(ka_alg, kdf_alg) \ /* specification-defined value */ #define PSA_ALG_KEY_AGREEMENT_GET_BASE(alg) /* specification-defined value */ @@ -152,6 +165,9 @@ typedef /* implementation-defined type */ psa_mac_operation_t; #define PSA_ALG_SP800_108_COUNTER_CMAC ((psa_algorithm_t)0x08000800) #define PSA_ALG_SP800_108_COUNTER_HMAC(hash_alg) \ /* 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_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 */ @@ -189,7 +205,7 @@ typedef /* implementation-defined type */ psa_mac_operation_t; #define PSA_CIPHER_UPDATE_OUTPUT_SIZE(key_type, alg, input_length) \ /* implementation-defined value */ #define PSA_CRYPTO_API_VERSION_MAJOR 1 -#define PSA_CRYPTO_API_VERSION_MINOR 2 +#define PSA_CRYPTO_API_VERSION_MINOR 3 #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) @@ -278,6 +294,11 @@ typedef /* implementation-defined type */ psa_mac_operation_t; #define PSA_KEY_TYPE_IS_KEY_PAIR(type) /* specification-defined value */ #define PSA_KEY_TYPE_IS_PUBLIC_KEY(type) /* specification-defined value */ #define PSA_KEY_TYPE_IS_RSA(type) /* specification-defined value */ +#define PSA_KEY_TYPE_IS_SPAKE2P(type) /* specification-defined value */ +#define PSA_KEY_TYPE_IS_SPAKE2P_KEY_PAIR(type) \ + /* specification-defined value */ +#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_KEY_PAIR_OF_PUBLIC_KEY(type) \ /* specification-defined value */ @@ -291,6 +312,10 @@ typedef /* implementation-defined type */ psa_mac_operation_t; #define PSA_KEY_TYPE_RSA_KEY_PAIR ((psa_key_type_t)0x7001) #define PSA_KEY_TYPE_RSA_PUBLIC_KEY ((psa_key_type_t)0x4001) #define PSA_KEY_TYPE_SM4 ((psa_key_type_t)0x2405) +#define PSA_KEY_TYPE_SPAKE2P_GET_FAMILY(type) /* specification-defined value */ +#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_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) @@ -307,6 +332,35 @@ typedef /* implementation-defined type */ psa_mac_operation_t; /* implementation-defined value */ #define PSA_MAC_MAX_SIZE /* implementation-defined value */ #define PSA_MAC_OPERATION_INIT /* implementation-defined value */ +#define PSA_PAKE_CIPHER_SUITE_INIT /* implementation-defined value */ +#define PSA_PAKE_CONFIRMED_KEY 0 +#define PSA_PAKE_INPUT_MAX_SIZE /* implementation-defined value */ +#define PSA_PAKE_INPUT_SIZE(alg, primitive, input_step) \ + /* implementation-defined value */ +#define PSA_PAKE_OPERATION_INIT /* implementation-defined value */ +#define PSA_PAKE_OUTPUT_MAX_SIZE /* implementation-defined value */ +#define PSA_PAKE_OUTPUT_SIZE(alg, primitive, output_step) \ + /* implementation-defined value */ +#define PSA_PAKE_PRIMITIVE(pake_type, pake_family, pake_bits) \ + /* specification-defined value */ +#define PSA_PAKE_PRIMITIVE_GET_BITS(pake_primitive) \ + /* specification-defined value */ +#define PSA_PAKE_PRIMITIVE_GET_FAMILY(pake_primitive) \ + /* specification-defined value */ +#define PSA_PAKE_PRIMITIVE_GET_TYPE(pake_primitive) \ + /* specification-defined value */ +#define PSA_PAKE_PRIMITIVE_TYPE_DH ((psa_pake_primitive_type_t)0x02) +#define PSA_PAKE_PRIMITIVE_TYPE_ECC ((psa_pake_primitive_type_t)0x01) +#define PSA_PAKE_ROLE_CLIENT ((psa_pake_role_t)0x11) +#define PSA_PAKE_ROLE_FIRST ((psa_pake_role_t)0x01) +#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_CONFIRM ((psa_pake_step_t)0x04) +#define PSA_PAKE_STEP_KEY_SHARE ((psa_pake_step_t)0x01) +#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 #define PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE \ /* implementation-defined value */ #define PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE(key_type, key_bits) \ @@ -570,6 +624,44 @@ psa_status_t psa_mac_verify_finish(psa_mac_operation_t * operation, psa_status_t psa_mac_verify_setup(psa_mac_operation_t * operation, psa_key_id_t key, psa_algorithm_t alg); +psa_status_t psa_pake_abort(psa_pake_operation_t * operation); +psa_pake_cipher_suite_t psa_pake_cipher_suite_init(void); +psa_algorithm_t psa_pake_cs_get_algorithm(const psa_pake_cipher_suite_t* cipher_suite); +uint32_t psa_pake_cs_get_key_confirmation(const psa_pake_cipher_suite_t* cipher_suite); +psa_pake_primitive_t psa_pake_cs_get_primitive(const psa_pake_cipher_suite_t* cipher_suite); +void psa_pake_cs_set_algorithm(psa_pake_cipher_suite_t* cipher_suite, + psa_algorithm_t alg); +void psa_pake_cs_set_key_confirmation(psa_pake_cipher_suite_t* cipher_suite, + uint32_t key_confirmation); +void psa_pake_cs_set_primitive(psa_pake_cipher_suite_t* cipher_suite, + psa_pake_primitive_t primitive); +psa_status_t psa_pake_get_shared_key(psa_pake_operation_t *operation, + const psa_key_attributes_t * attributes, + psa_key_id_t * key); +psa_status_t psa_pake_input(psa_pake_operation_t *operation, + psa_pake_step_t step, + const uint8_t *input, + size_t input_length); +psa_pake_operation_t psa_pake_operation_init(void); +psa_status_t psa_pake_output(psa_pake_operation_t *operation, + psa_pake_step_t step, + uint8_t *output, + size_t output_size, + size_t *output_length); +psa_status_t psa_pake_set_context(psa_pake_operation_t *operation, + const uint8_t *context, + size_t context_len); +psa_status_t psa_pake_set_peer(psa_pake_operation_t *operation, + const uint8_t *peer_id, + size_t peer_id_len); +psa_status_t psa_pake_set_role(psa_pake_operation_t *operation, + psa_pake_role_t role); +psa_status_t psa_pake_set_user(psa_pake_operation_t *operation, + const uint8_t *user_id, + size_t user_id_len); +psa_status_t psa_pake_setup(psa_pake_operation_t *operation, + psa_key_id_t password_key, + const psa_pake_cipher_suite_t *cipher_suite); psa_status_t psa_purge_key(psa_key_id_t key); psa_status_t psa_raw_key_agreement(psa_algorithm_t alg, psa_key_id_t private_key, diff --git a/doc/crypto/api/keys/attributes.rst b/doc/crypto/api/keys/attributes.rst index 5cc69fc7..fc886c30 100644 --- a/doc/crypto/api/keys/attributes.rst +++ b/doc/crypto/api/keys/attributes.rst @@ -112,7 +112,7 @@ Managing key attributes #. Set the key policy with `psa_set_key_usage_flags()` and `psa_set_key_algorithm()`. #. Set the key type with `psa_set_key_type()`. Skip this step if copying an existing key with `psa_copy_key()`. #. When generating a random key with `psa_generate_key()` or deriving a key with `psa_key_derivation_output_key()`, set the desired key size with `psa_set_key_bits()`. - #. Call a key creation function: `psa_import_key()`, `psa_generate_key()`, `psa_key_derivation_output_key()`, `psa_key_agreement()`, or `psa_copy_key()`. This function reads the attribute object, creates a key with these attributes, and outputs an identifier for the newly created key. + #. Call a key creation function: `psa_import_key()`, `psa_generate_key()`, `psa_key_derivation_output_key()`, `psa_key_agreement()`, `psa_pake_get_shared_key()`, or `psa_copy_key()`. This function reads the attribute object, creates a key with these attributes, and outputs an identifier for the newly created key. #. Optionally call `psa_reset_key_attributes()`, now that the attribute object is no longer needed. Currently this call is not required as the attributes defined in this specification do not require additional resources beyond the object itself. A typical sequence to query a key's attributes is as follows: diff --git a/doc/crypto/api/keys/ids.rst b/doc/crypto/api/keys/ids.rst index fd937050..9e9ce070 100644 --- a/doc/crypto/api/keys/ids.rst +++ b/doc/crypto/api/keys/ids.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: Copyright 2018-2022 Arm Limited and/or its affiliates +.. SPDX-FileCopyrightText: Copyright 2018-2022, 2024 Arm Limited and/or its affiliates .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license .. _key-identifiers: @@ -92,7 +92,7 @@ Attribute accessors If the attribute object currently declares the key as volatile, which is the default lifetime of an attribute object, this function sets the lifetime attribute to `PSA_KEY_LIFETIME_PERSISTENT`. - This function does not access storage, it merely stores the given value in the attribute object. The persistent key will be written to storage when the attribute object is passed to a key creation function such as `psa_import_key()`, `psa_generate_key()`, `psa_key_derivation_output_key()` or `psa_copy_key()`. + This function does not access storage, it merely stores the given value in the attribute object. The persistent key will be written to storage when the attribute object is passed to a key creation function such as `psa_import_key()`, `psa_generate_key()`, `psa_key_derivation_output_key()`, `psa_key_agreement()`, `psa_pake_get_shared_key()`, or `psa_copy_key()`. .. admonition:: Implementation note diff --git a/doc/crypto/api/keys/lifetimes.rst b/doc/crypto/api/keys/lifetimes.rst index 8cb13845..b57d09b8 100644 --- a/doc/crypto/api/keys/lifetimes.rst +++ b/doc/crypto/api/keys/lifetimes.rst @@ -273,7 +273,7 @@ Attribute accessors To make a key persistent, give it a persistent key identifier by using `psa_set_key_id()`. By default, a key that has a persistent identifier is stored in the default storage area identifier by `PSA_KEY_LIFETIME_PERSISTENT`. Call this function to choose a storage area, or to explicitly declare the key as volatile. - This function does not access storage, it merely stores the given value in the attribute object. The persistent key will be written to storage when the attribute object is passed to a key creation function such as `psa_import_key()`, `psa_generate_key()`, `psa_key_derivation_output_key()`, `psa_key_agreement()`, or `psa_copy_key()`. + This function does not access storage, it merely stores the given value in the attribute object. The persistent key will be written to storage when the attribute object is passed to a key creation function such as `psa_import_key()`, `psa_generate_key()`, `psa_key_derivation_output_key()`, `psa_key_agreement()`, `psa_pake_get_shared_key()`, or `psa_copy_key()`. .. admonition:: Implementation note diff --git a/doc/crypto/api/keys/management.rst b/doc/crypto/api/keys/management.rst index 18c68458..8b71442b 100644 --- a/doc/crypto/api/keys/management.rst +++ b/doc/crypto/api/keys/management.rst @@ -18,6 +18,7 @@ New keys can be created in the following ways: * `psa_generate_key()` creates a key from randomly generated data. * `psa_key_derivation_output_key()` creates a key from data generated by a pseudorandom derivation process. See :secref:`kdf`. * `psa_key_agreement()` creates a key from the shared secret result of a key agreement process. See :secref:`key-agreement`. +* `psa_pake_get_shared_key()` creates a key from the shared secret result of a password-authenticated key exchange. See :secref:`pake`. * `psa_copy_key()` duplicates an existing key with a different lifetime or with a more restrictive usage policy. When creating a key, the attributes for the new key are specified in a `psa_key_attributes_t` object. Each key creation function defines how it uses the attributes. @@ -670,3 +671,36 @@ This section defines the format of the key data that an implementation is requir - :code:`PSA_KEY_TYPE_DH_PUBLIC_KEY(dh_family)` where ``dh_family`` designates any Diffie-Hellman family. The key data 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. + + * - SPAKE2+ key pair + - :code:`PSA_KEY_TYPE_SPAKE2P_KEY_PAIR(ecc_family)` where ``ecc_family`` designates an elliptic curve family. + + The key consists of the two values :math:`w0` and :math:`w1`, which result from the SPAKE2+ registration phase, see :secref:`spake2p-registration`. + :math:`w0` and :math:`w1` are scalars in the same range as an elliptic curve private key from the group used as the SPAKE2+ primitive group. + + For the |API|, the default format for a SPAKE2+ key pair is the concatenation of the formatted values for :math:`w0` and :math:`w1`, using the standard formats for elliptic curve keys used by the |API|. + For example, for SPAKE2+ over P-256 (secp256r1), the output from :code:`psa_export_key()` would be the concatenation of: + + * The P-256 private key :math:`w0`. + This is a 32-byte big-endian encoding of the integer :math:`w0`. + * The P-256 private key :math:`w1`. + This is a 32-byte big-endian encoding of the integer :math:`w1`. + + * - SPAKE2+ public key + - :code:`PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY(ecc_family)` where ``ecc_family`` designates an elliptic curve family. + + The public key consists of the two values :math:`w0` and :math:`L`, which result from the SPAKE2+ registration phase, see :secref:`spake2p-registration`. + :math:`w0` is a scalar in the same range as a elliptic curve private key from the group used as the SPAKE2+ primitive group. + :math:`L` is a point on the curve, similar to a public key from the same group, corresponding to the :math:`w1` value in the key pair. + + For the |API|, the default format for a SPAKE2+ public key is the concatenation of the formatted values for :math:`w0` and :math:`L`, using the standard formats for elliptic curve keys used by the |API|. + For example, for SPAKE2+ over P-256 (secp256r1), the output from :code:`psa_export_public_key()` would be the concatenation of: + + * The P-256 private key :math:`w0`. + This is a 32-byte big-endian encoding of the integer :math:`w0`. + * The P-256 public key :math:`L`. + This is a 65-byte concatenation of: + + - The byte ``0x04``. + - The 32-byte big-endian encoding of the x-coordinate of :math:`L`. + - The 32-byte big-endian encoding of the y-coordinate of :math:`L`. diff --git a/doc/crypto/api/keys/types.rst b/doc/crypto/api/keys/types.rst index 9eef6fbb..5d816902 100644 --- a/doc/crypto/api/keys/types.rst +++ b/doc/crypto/api/keys/types.rst @@ -428,6 +428,18 @@ Symmetric keys .. _asymmetric-keys: +Asymmetric keys +--------------- + +The |API| defines the following types of asymmetric key: + +* :secref:`rsa-keys` +* :secref:`ecc-keys` +* :secref:`dh-keys` +* :secref:`spake2p-keys` + +.. _rsa-keys: + RSA keys -------- @@ -474,6 +486,8 @@ RSA keys .. param:: type A key type: a value of type `psa_key_type_t`. +.. _ecc-keys: + Elliptic Curve keys ------------------- @@ -486,7 +500,7 @@ Elliptic Curve keys 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: + The range of elliptic curve family identifier values is divided as follows: :code:`0x00` Reserved. Not allocated to an ECC family. @@ -502,16 +516,16 @@ Elliptic Curve keys .. summary:: Elliptic curve key pair: both the private and public key. - The size of an elliptic curve key is the bit size associated with the curve, that is, the bit size of :math:`q`` for a curve over a field :math:`\mathbb{F}_q`. See the documentation of each Elliptic curve family for details. + The size of an elliptic curve key is the bit size associated with the curve, that is, the bit size of :math:`q`` for a curve over a field :math:`\mathbb{F}_q`. See the documentation of each elliptic curve family for details. .. param:: curve A value of type `psa_ecc_family_t` that identifies the ECC curve family to be used. .. subsection:: Compatible algorithms - Elliptic curve key pairs can be used in Asymmetric signature and Key agreement algorithms. + elliptic curve key pairs can be used in Asymmetric signature and Key agreement algorithms. - The set of compatible algorithms depends on the Elliptic curve key family. See the Elliptic curve family for details. + The set of compatible algorithms depends on the elliptic curve key family. See the elliptic curve family for details. .. macro:: PSA_KEY_TYPE_ECC_PUBLIC_KEY :definition: /* specification-defined value */ @@ -522,13 +536,13 @@ Elliptic Curve keys .. 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. + 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 Elliptic curve public keys can be used for verification in Asymmetric signature algorithms. - The set of compatible algorithms depends on the Elliptic curve key family. See each Elliptic curve family for details. + The set of compatible algorithms depends on the elliptic curve key family. See each elliptic curve family for details. .. macro:: PSA_ECC_FAMILY_SECP_K1 :definition: ((psa_ecc_family_t) 0x17) @@ -792,6 +806,8 @@ Elliptic Curve keys .. 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 ------------------- @@ -920,6 +936,97 @@ Diffie Hellman keys .. 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. +.. _spake2p-keys: + +SPAKE2+ keys +~~~~~~~~~~~~ + +.. macro:: PSA_KEY_TYPE_SPAKE2P_KEY_PAIR + :definition: /* specification-defined value */ + + .. summary:: + SPAKE2+ key pair: both the prover and verifier key. + + .. param:: curve + A value of type :code:`psa_ecc_family_t` that identifies the elliptic curve family to be used. + + The bit-size of a SPAKE2+ key is the size associated with the elliptic curve group, that is, :math:`\lceil{log_2(q)}\rceil` for a curve over a field :math:`\mathbb{F}_q`. + See :secref:`ecc-keys` for details of each elliptic curve family. + + To create a new SPAKE2+ key pair, use :code:`psa_key_derivation_output_key()` as described in :secref:`spake2p-registration`. + The SPAKE2+ protocol recommends that a key-stretching key-derivation function, such as PBKDF2, is used to hash the SPAKE2+ password. + This follows the recommended process described in :rfc:`9383`. + + A SPAKE2+ key pair can also be imported from a previously exported SPAKE2+ key pair. + + The corresponding public key can be exported using :code:`psa_export_public_key()`. + See also `PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY()`. + + .. subsection:: Compatible algorithms + + | `PSA_ALG_SPAKE2P_HMAC` + | `PSA_ALG_SPAKE2P_CMAC` + | `PSA_ALG_SPAKE2P_MATTER` + +.. macro:: PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY + :definition: /* specification-defined value */ + + .. summary:: + SPAKE2+ public key: the verifier key. + + .. param:: curve + A value of type :code:`psa_ecc_family_t` that identifies the elliptic curve family to be used. + + The bit-size of an SPAKE2+ public key is the same as the corresponding private key. + See `PSA_KEY_TYPE_SPAKE2P_KEY_PAIR()` and the documentation of each elliptic curve family for details. + + To construct a SPAKE2+ public key, it must be imported. + + .. subsection:: Compatible algorithms + + | `PSA_ALG_SPAKE2P_HMAC` (verification only) + | `PSA_ALG_SPAKE2P_CMAC` (verification only) + | `PSA_ALG_SPAKE2P_MATTER` (verification only) + +.. macro:: PSA_KEY_TYPE_IS_SPAKE2P + :definition: /* specification-defined value */ + + .. summary:: + Whether a key type is a SPAKE2+ key, either a key pair or a public key. + + .. param:: type + A key type: a value of type :code:`psa_key_type_t`. + +.. macro:: PSA_KEY_TYPE_IS_SPAKE2P_KEY_PAIR + :definition: /* specification-defined value */ + + .. summary:: + Whether a key type is a SPAKE2+ key pair. + + .. param:: type + A key type: a value of type :code:`psa_key_type_t`. + +.. macro:: PSA_KEY_TYPE_IS_SPAKE2P_PUBLIC_KEY + :definition: /* specification-defined value */ + + .. summary:: + Whether a key type is a SPAKE2+ public key. + + .. param:: type + A key type: a value of type :code:`psa_key_type_t`. + +.. macro:: PSA_KEY_TYPE_SPAKE2P_GET_FAMILY + :definition: /* specification-defined value */ + + .. summary:: + Extract the curve family from a SPAKE2+ key type. + + .. param:: type + A SPAKE2+ key type: a value of type :code:`psa_key_type_t` such that :code:`PSA_KEY_TYPE_IS_SPAKE2P(type)` is true. + + .. 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 ------------------- diff --git a/doc/crypto/api/library/library.rst b/doc/crypto/api/library/library.rst index 71d17dc7..2d734f67 100644 --- a/doc/crypto/api/library/library.rst +++ b/doc/crypto/api/library/library.rst @@ -14,7 +14,7 @@ :include: psa/error.h /* This file is a reference template for implementation of the - * PSA Certified Crypto API v1.2 + * PSA Certified Crypto API v1.3 */ diff --git a/doc/crypto/api/ops/algorithms.rst b/doc/crypto/api/ops/algorithms.rst index 8e1c6989..1a601b44 100644 --- a/doc/crypto/api/ops/algorithms.rst +++ b/doc/crypto/api/ops/algorithms.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: Copyright 2018-2023 Arm Limited and/or its affiliates +.. SPDX-FileCopyrightText: Copyright 2018-2024 Arm Limited and/or its affiliates .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license .. _algorithms: @@ -23,6 +23,7 @@ The specific algorithm identifiers are described alongside the cryptographic ope * :secref:`sign-algorithms` * :secref:`asymmetric-encryption-algorithms` * :secref:`key-agreement-algorithms` +* :secref:`pake` Algorithm encoding @@ -123,6 +124,20 @@ Algorithm categories See :secref:`aead-algorithms` for a list of defined AEAD algorithms. +.. macro:: PSA_ALG_IS_KEY_DERIVATION + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is a key derivation algorithm. + + .. param:: alg + An algorithm identifier: a value of type `psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is a key derivation algorithm, ``0`` otherwise. This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + + See :secref:`key-derivation-algorithms` for a list of defined key derivation algorithms. + .. macro:: PSA_ALG_IS_SIGN :definition: /* specification-defined value */ @@ -165,19 +180,21 @@ Algorithm categories See :secref:`key-agreement-algorithms` for a list of defined key agreement algorithms. -.. macro:: PSA_ALG_IS_KEY_DERIVATION +.. macro:: PSA_ALG_IS_PAKE :definition: /* specification-defined value */ .. summary:: - Whether the specified algorithm is a key derivation algorithm. + Whether the specified algorithm is a password-authenticated key exchange. .. param:: alg - An algorithm identifier: a value of type `psa_algorithm_t`. + An algorithm identifier: a value of type :code:`psa_algorithm_t`. .. return:: - ``1`` if ``alg`` is a key derivation algorithm, ``0`` otherwise. This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + ``1`` if ``alg`` is a password-authenticated key exchange (PAKE) algorithm, ``0`` otherwise. + This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. - See :secref:`key-derivation-algorithms` for a list of defined key derivation algorithms. +Support macros +-------------- .. macro:: PSA_ALG_IS_WILDCARD :definition: /* specification-defined value */ @@ -215,15 +232,20 @@ Algorithm categories The following composite algorithms require a hash algorithm: + * `PSA_ALG_DETERMINISTIC_ECDSA()` * `PSA_ALG_ECDSA()` * `PSA_ALG_HKDF()` * `PSA_ALG_HKDF_EXPAND()` * `PSA_ALG_HKDF_EXTRACT()` * `PSA_ALG_HMAC()` + * `PSA_ALG_JPAKE()` + * `PSA_ALG_PBKDF2_HMAC()` * `PSA_ALG_RSA_OAEP()` * `PSA_ALG_RSA_PKCS1V15_SIGN()` * `PSA_ALG_RSA_PSS()` * `PSA_ALG_RSA_PSS_ANY_SALT()` + * `PSA_ALG_SP800_108_COUNTER_HMAC()` + * `PSA_ALG_SPAKE2P_CMAC()` + * `PSA_ALG_SPAKE2P_HMAC()` * `PSA_ALG_TLS12_PRF()` * `PSA_ALG_TLS12_PSK_TO_MS()` - * `PSA_ALG_PBKDF2_HMAC()` diff --git a/doc/crypto/api/ops/ciphers.rst b/doc/crypto/api/ops/cipher.rst similarity index 100% rename from doc/crypto/api/ops/ciphers.rst rename to doc/crypto/api/ops/cipher.rst diff --git a/doc/crypto/api/ops/hashes.rst b/doc/crypto/api/ops/hash.rst similarity index 100% rename from doc/crypto/api/ops/hashes.rst rename to doc/crypto/api/ops/hash.rst diff --git a/doc/crypto/api/ops/index.rst b/doc/crypto/api/ops/index.rst index 2b2c03e8..903c79cf 100644 --- a/doc/crypto/api/ops/index.rst +++ b/doc/crypto/api/ops/index.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: Copyright 2018-2022 Arm Limited and/or its affiliates +.. SPDX-FileCopyrightText: Copyright 2018-2022, 2024 Arm Limited and/or its affiliates .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license .. _crypto-operations: @@ -10,12 +10,13 @@ Cryptographic operation reference .. toctree:: algorithms - hashes - macs - ciphers + hash + mac + cipher aead - kdf - sign - pke - ka + key-derivation + signature + pk-encryption + key-agreement + pake rng diff --git a/doc/crypto/api/ops/ka.rst b/doc/crypto/api/ops/key-agreement.rst similarity index 100% rename from doc/crypto/api/ops/ka.rst rename to doc/crypto/api/ops/key-agreement.rst diff --git a/doc/crypto/api/ops/kdf.rst b/doc/crypto/api/ops/key-derivation.rst similarity index 97% rename from doc/crypto/api/ops/kdf.rst rename to doc/crypto/api/ops/key-derivation.rst index 81e2d5bd..fe31fc8e 100644 --- a/doc/crypto/api/ops/kdf.rst +++ b/doc/crypto/api/ops/key-derivation.rst @@ -331,7 +331,7 @@ Key derivation algorithms .. summary:: The TLS 1.2 ECJPAKE-to-PMS key-derivation algorithm. - This KDF is defined in :cite-title:`TLS-ECJPAKE` §8.7. This specifies the use of a KDF to derive the TLS 1.2 session secrets from the output of EC J-PAKE over the secp256r1 Elliptic curve (the 256-bit curve in `PSA_ECC_FAMILY_SECP_R1`). EC J-PAKE operations can be performed using the extension to the |API| defined in :cite-title:`PSA-PAKE`. + This KDF is defined in :cite-title:`TLS-ECJPAKE` §8.7. This specifies the use of a KDF to derive the TLS 1.2 session secrets from the output of EC J-PAKE over the secp256r1 Elliptic curve (the 256-bit curve in `PSA_ECC_FAMILY_SECP_R1`). EC J-PAKE operations can be performed using a PAKE operation, see :secref:`pake`. This KDF takes the shared secret :math:`K`` (an uncompressed EC point in case of EC J-PAKE) and calculates :math:`\text{SHA256}(K.x)`. @@ -339,7 +339,7 @@ Key derivation algorithms * `PSA_KEY_DERIVATION_INPUT_SECRET` is the shared secret :math:`K` from EC J-PAKE. For secp256r1, the input is exactly 65 bytes. - The shared secret can be obtained by calling :code:`psa_pake_get_shared_key()` on a PAKE operation that is performing the EC J-PAKE algorithm. These are defined in the PAKE extension API, see :cite:`PSA-PAKE`. + The shared secret can be obtained by calling :code:`psa_pake_get_shared_key()` on a PAKE operation that is performing the EC J-PAKE algorithm. See :secref:`pake`. The 32-byte output has to be read in a single call to either `psa_key_derivation_output_bytes()` or `psa_key_derivation_output_key()`. The size of the output is defined as `PSA_TLS12_ECJPAKE_TO_PMS_OUTPUT_SIZE`. @@ -1022,6 +1022,29 @@ Key derivation functions * 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`. + * - SPAKE2+ key pairs + - :code:`PSA_KEY_TYPE_SPAKE2P_KEY_PAIR(ecc_family)` where ``ecc_family`` designates an elliptic curve family. + + The SPAKE2+ key derivation process follows the recommendations for the registration process in :rfc-title:`9383`, and matches the specification of this process in :cite-title:`MATTER`. + + The derivation of SPAKE2+ keys extracts :math:`\lceil{log_2(p)/8}\rceil+8` bytes from the PBKDF for each of :math:`w0s` and :math:`w1s`, where :math:`p` is the prime factor of the order of the elliptic curve group. + The following sizes are used for extracting :math:`w0s` and :math:`w1s`, depending on the elliptic curve: + + * P-256: 40 bytes + * P-384: 56 bytes + * P-521: 74 bytes + * edwards25519: 40 bytes + * edwards448: 64 bytes + + The calculation of :math:`w0`, :math:`w1`, and :math:`L` then proceeds as described in :rfc:`9383`. + + .. admonition:: Implementation note + + The values of :math:`w0` and :math:`w1` are required as part of the SPAKE2+ key pair. + + It is :scterm:`implementation defined` whether :math:`L` is computed during key derivation, and stored as part of the key pair; or only computed when required from the key pair. + + * - *Other key types* - This includes `PSA_KEY_TYPE_RSA_KEY_PAIR`. diff --git a/doc/crypto/api/ops/macs.rst b/doc/crypto/api/ops/mac.rst similarity index 100% rename from doc/crypto/api/ops/macs.rst rename to doc/crypto/api/ops/mac.rst diff --git a/doc/ext-pake/api/pake.rst b/doc/crypto/api/ops/pake.rst similarity index 88% rename from doc/ext-pake/api/pake.rst rename to doc/crypto/api/ops/pake.rst index 1d2229fe..9c4584cb 100644 --- a/doc/ext-pake/api/pake.rst +++ b/doc/crypto/api/ops/pake.rst @@ -1,12 +1,17 @@ .. SPDX-FileCopyrightText: Copyright 2022-2024 Arm Limited and/or its affiliates .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license +.. header:: psa/crypto + :seq: 30 + +.. _pake: + Password-authenticated key exchange (PAKE) ========================================== -.. note:: +PAKE protocols provide an interactive method for two or more parties to establish cryptographic keys based on knowledge of a low entropy secret, such as a password. - The API defined in this specification will be integrated into a future version of :cite:`PSA-CRYPT`. +These can provide strong security for communication from a weak password, because the password is not directly communicated as part of the key exchange. This chapter is divided into the following sections: @@ -14,34 +19,13 @@ This chapter is divided into the following sections: * :secref:`pake-jpake` --- the J-PAKE protocol, and the associated interface elements. * :secref:`pake-spake2p` --- the SPAKE2+ protocols, and the associated interface elements. -PAKE also introduces additional algorithm identifiers and key types to the |API|. -See :secref:`pake-encodings` for the encoding of these values. - -.. rationale:: - - PAKE protocols are more complex operations, when compared with the other types of cryptographic operation in the |API|. - PAKE protocols can also have multiple phases, some of which are carried out prior to the PAKE operation itself, using other parts of the |API|. - - To improve the understanding and correct use of PAKE protocols, it helps to show the protocol flow, and to demonstrate how to implement this with this API. - .. _pake-common-api: Common API for PAKE ------------------- -.. header:: psa/crypto-pake - :copyright: Copyright 2018-2024 Arm Limited and/or its affiliates - :license: Apache-2.0 - - /* This file contains reference definitions for implementation of the - * PSA Certified Crypto API v1.2 PAKE Extension - * - * These definitions must be embedded in, or included by, psa/crypto.h - */ - This section defines all of the common interfaces used to carry out a PAKE protocol: -* :secref:`pake-algorithms` * :secref:`pake-primitive` * :secref:`pake-cipher-suite` * :secref:`pake-roles` @@ -49,24 +33,6 @@ This section defines all of the common interfaces used to carry out a PAKE proto * :secref:`pake-operation` * :secref:`pake-support` -.. _pake-algorithms: - -PAKE algorithms -~~~~~~~~~~~~~~~ - -.. macro:: PSA_ALG_IS_PAKE - :definition: /* specification-defined value */ - - .. summary:: - Whether the specified algorithm is a password-authenticated key exchange. - - .. param:: alg - An algorithm identifier: a value of type :code:`psa_algorithm_t`. - - .. return:: - ``1`` if ``alg`` is a password-authenticated key exchange (PAKE) algorithm, ``0`` otherwise. - This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. - .. _pake-primitive: PAKE primitives @@ -88,7 +54,7 @@ A PAKE primitive is required when constructing a PAKE cipher-suite object, `psa_ :numref:`fig-pake-primitive` shows how the components of the primitive are encoded into a `psa_pake_primitive_t` value. - .. figure:: /figure/pake_primitive.* + .. figure:: /figure/pake/pake_primitive.* :name: fig-pake-primitive PAKE primitive encoding @@ -111,11 +77,11 @@ A PAKE primitive is required when constructing a PAKE cipher-suite object, `psa_ :code:`0x00` Reserved as an invalid primitive type. - :code:`0x01 – 0x7f` + :code:`0x01 - 0x7f` Specification-defined primitive type. Primitive types defined by this standard always have bit 7 clear. Unallocated primitive type values in this range are reserved for future use. - :code:`0x80 – 0xff` + :code:`0x80 - 0xff` Implementation-defined primitive type. Implementations that define additional primitive types must use an encoding with bit 7 set. @@ -133,10 +99,10 @@ A PAKE primitive is required when constructing a PAKE cipher-suite object, `psa_ 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 on the specific Elliptic curve. - For more information, consult the documentation of key formats in `[PSA-CRYPT]`. - * The format for scalars is the same as that for private keys on the specific Elliptic curve. - For more information, consult the documentation of key formats in `[PSA-CRYPT]`. + * The format for group elements is the same as that for public keys on the specific elliptic curve. + See :secref:`key_formats`. + * The format for scalars is the same as that for private keys on the specific elliptic curve. + See :secref:`key_formats`. .. macro:: PSA_PAKE_PRIMITIVE_TYPE_DH @@ -152,9 +118,9 @@ A PAKE primitive is required when constructing a PAKE cipher-suite object, `psa_ 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. - For more information, consult the documentation of key formats in `[PSA-CRYPT]`. + See :secref:`key_formats`. * The format for scalars is the same as that for private keys in the specific Diffie-Hellman group. - For more information, consult the documentation of key formats in `[PSA-CRYPT]`. + See :secref:`key_formats`. .. typedef:: uint8_t psa_pake_family_t @@ -578,7 +544,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 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. @@ -625,7 +591,7 @@ Multi-part PAKE operations psa_pake_operation_t operation = PSA_PAKE_OPERATION_INIT; - * Assign the result of the function `psa_pake_cipher_suite_init()` to the object, for example: + * Assign the result of the function `psa_pake_operation_init()` to the object, for example: .. code-block:: xref @@ -661,7 +627,7 @@ Multi-part PAKE operations It must remain valid until the operation terminates. The valid key types depend on the PAKE algorithm, and participant role. - Refer to the documentation of individual PAKE algorithms for more information, see :secref:`pake-algorithms`. + Refer to the documentation of individual PAKE algorithms for more information. The key must permit the usage :code:`PSA_KEY_USAGE_DERIVE`. .. param:: const psa_pake_cipher_suite_t *cipher_suite @@ -719,7 +685,6 @@ Multi-part PAKE operations #. Call `psa_pake_get_shared_key()` to access the shared secret. Refer to the documentation of individual PAKE algorithms for details on the required set up and operation for each algorithm, and for constraints on the format and content of valid passwords. - See :secref:`pake-algorithms`. After a successful call to `psa_pake_setup()`, the operation is active, and the application must eventually terminate the operation. The following events terminate an operation: @@ -732,8 +697,7 @@ Multi-part PAKE operations To abandon an active operation, or reset an operation in an error state, call `psa_pake_abort()`. - .. - See :secref:`multi-part-operations`. :issue:`add this when integrated to main specification` + See :secref:`multi-part-operations`. .. function:: psa_pake_set_role @@ -774,7 +738,6 @@ Multi-part PAKE operations * Call `psa_pake_set_role()` with the `PSA_PAKE_ROLE_NONE` role. Refer to the documentation of individual PAKE algorithms for more information. - See :secref:`pake-algorithms`. .. function:: psa_pake_set_user @@ -809,7 +772,6 @@ Multi-part PAKE operations For PAKE algorithms that associate a single user identifier with the session, call `psa_pake_set_user()` only. Refer to the documentation of individual PAKE algorithms for more information. - See :secref:`pake-algorithms`. .. function:: psa_pake_set_peer @@ -845,7 +807,6 @@ Multi-part PAKE operations For PAKE algorithms that associate a single user identifier with the session, call `psa_pake_set_user()` only. Refer to the documentation of individual PAKE algorithms for more information. - See :secref:`pake-algorithms`. .. function:: psa_pake_set_context @@ -880,7 +841,6 @@ Multi-part PAKE operations Call this function for PAKE algorithms that accept additional context data as part of the protocol setup. Refer to the documentation of individual PAKE algorithms for more information. - See :secref:`pake-algorithms`. .. function:: psa_pake_output @@ -931,7 +891,6 @@ Multi-part PAKE operations The exact sequence of calls to perform a password-authenticated key exchange depends on the algorithm in use. Refer to the documentation of individual PAKE algorithms for more information. - See :secref:`pake-algorithms`. If this function returns an error status, the operation enters an error state and must be aborted by calling `psa_pake_abort()`. @@ -981,7 +940,6 @@ Multi-part PAKE operations The exact sequence of calls to perform a password-authenticated key exchange depends on the algorithm in use. Refer to the documentation of individual PAKE algorithms for more information. - See :secref:`pake-algorithms`. `PSA_PAKE_INPUT_SIZE()` or `PSA_PAKE_INPUT_MAX_SIZE` can be used to allocate buffers of sufficient size to transfer inputs that are received from the peer into the operation. @@ -1002,17 +960,12 @@ Multi-part PAKE operations 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 pseudo-random shared secret, can also output block-cipher key types, for example :code:`PSA_KEY_TYPE_AES`. Refer to the documentation of individual PAKE algorithms for more information. - See :secref:`pake-algorithms`. * The key size in ``attributes`` must be zero. The returned key size is always determined from the PAKE shared secret. * The key permitted-algorithm policy is required for keys that will be used for a cryptographic operation. - - .. see :secref:`permitted-algorithms`. - + See :secref:`permitted-algorithms`. * The key usage flags define what operations are permitted with the key. - - .. see :secref:`key-usage-flags`. - + See :secref:`key-usage-flags`. * The key lifetime and identifier are required for a persistent key. .. note:: @@ -1021,7 +974,6 @@ Multi-part PAKE operations .. param:: psa_key_id_t * key On success, an identifier for the newly created key. :code:`PSA_KEY_ID_NULL` on failure. - .. return:: psa_status_t .. retval:: PSA_SUCCESS Success. @@ -1061,7 +1013,7 @@ Multi-part PAKE operations This is the final call in a PAKE operation, which retrieves the shared secret as a key. It is recommended that this key is used as an input to a key derivation operation to produce additional cryptographic keys. For some PAKE algorithms, the shared secret is also suitable for use as a key in cryptographic operations such as encryption. - Refer to the documentation of individual PAKE algorithms for more information, see :secref:`pake-algorithms`. + Refer to the documentation of individual PAKE algorithms for more information. Depending on the key confirmation requested in the cipher suite, `psa_pake_get_shared_key()` must be called either before or after the key-confirmation output and input steps for the PAKE algorithm. The key confirmation affects the guarantees that can be made about the shared key: @@ -1094,7 +1046,6 @@ Multi-part PAKE operations The exact sequence of calls to perform a password-authenticated key exchange depends on the algorithm in use. Refer to the documentation of individual PAKE algorithms for more information. - See :secref:`pake-algorithms`. When this function returns successfully, ``operation`` becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling `psa_pake_abort()`. @@ -1230,7 +1181,7 @@ 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 Diffie-Hellman field is provided with the `PSA_PAKE_PRIMITIVE_TYPE_ECC` and `PSA_PAKE_PRIMITIVE_TYPE_DH` constants. .. _jpake-passwords: @@ -1248,7 +1199,7 @@ J-PAKE operation The J-PAKE operation follows the protocol shown in :numref:`fig-jpake`. -.. figure:: /figure/j-pake.* +.. figure:: /figure/pake/j-pake.* :name: fig-jpake The J-PAKE protocol @@ -1526,7 +1477,7 @@ The resulting SPAKE2+ key-pair must be protected at least as well as the passwor The public key, exported from the key pair, does not need to be kept confidential. It is recommended that the Verifier stores only the public key, because disclosure of the public key does not enable an attacker to impersonate the Prover. -.. figure:: /figure/spake2plus-reg.* +.. figure:: /figure/pake/spake2plus-reg.* :name: fig-spake2p-reg Examples of SPAKE2+ key derivation procedures @@ -1588,7 +1539,7 @@ SPAKE2+ operation The SPAKE2+ operation follows the protocol shown in :numref:`fig-spake2p`. -.. figure:: /figure/spake2plus.* +.. figure:: /figure/pake/spake2plus.* :name: fig-spake2p The SPAKE2+ authentication and key confirmation protocol @@ -1751,168 +1702,6 @@ For more information about the format of the values which are passed for each st If the validation of a key share fails, then the corresponding call to `psa_pake_input()` for the `PSA_PAKE_STEP_KEY_SHARE` step will return :code:`PSA_ERROR_INVALID_ARGUMENT`. If the verification of a key 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`. -.. _spake2p-keys: - -SPAKE2+ keys -~~~~~~~~~~~~ - -.. macro:: PSA_KEY_TYPE_SPAKE2P_KEY_PAIR - :definition: /* specification-defined value */ - - .. summary:: - SPAKE2+ key pair: both the prover and verifier key. - - .. param:: curve - A value of type :code:`psa_ecc_family_t` that identifies the Elliptic curve family to be used. - - The bit size of a SPAKE2+ key is the size associated with the Elliptic curve group, that is, :math:`\lceil{log_2(q)}\rceil` for a curve over a field :math:`\mathbb{F}_q`. - See the documentation of each Elliptic curve family for details. - - To construct a SPAKE2+ key pair, it must either be output from a key derivation operation, or imported. - - The corresponding public key can be exported using :code:`psa_export_public_key()`. - See also `PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY()`. - - .. subsection:: Key derivation - - A SPAKE2+ key pair can be output from a key derivation using :code:`psa_key_derivation_output_key()`. - The SPAKE2+ protocol recommends that a key-stretching key-derivation function, such as PBKDF2, is used to hash the SPAKE2+ password. - See :rfc:`9383` for details. - - The key derivation process in :code:`psa_key_derivation_output_key()` follows the recommendations for the registration process in :rfc:`9383`, and matches the specification of this process in :cite:`MATTER`. - - For the |API|: - - * The derivation of SPAKE2+ keys extracts :math:`\lceil{log_2(p)/8}\rceil+8` bytes from the PBKDF for each of :math:`w0s` and :math:`w1s`, where :math:`p` is the prime factor of the order of the elliptic curve group. - The following sizes are used for extracting :math:`w0s` and :math:`w1s`, depending on the elliptic curve: - - .. csv-table:: - :header-rows: 1 - :widths: auto - :align: left - - Elliptic curve, "Size of :math:`w0s` and :math:`w1s`, in bytes" - P-256, 40 - P-384, 56 - P-521, 74 - edwards25519, 40 - edwards448, 64 - - * The calculation of :math:`w0`, :math:`w1`, and :math:`L` then proceeds as described in the RFC. - - .. admonition:: Implementation note - - The values of :math:`w0` and :math:`w1` are required as part of the SPAKE2+ key pair. - - It is :scterm:`implementation defined` whether :math:`L` is computed during key derivation, and stored as part of the key pair; or only computed when required from the key pair. - - .. subsection:: Key-pair format - - A SPAKE2+ key pair can be exported and imported. - - .. warning:: - - To create a new SPAKE2+ key pair, use :code:`psa_key_derivation_output_key()` as described in :secref:`spake2p-registration`. - This follows the recommended process described in :rfc:`9383`. - - Do not call :code:`psa_import_key()` with data extracted from a key derivation operation using :code:`psa_key_derivation_output_bytes()`. If the data is not considered invalid by :code:`psa_import_key()`, this will result in a different, insecure key pair. - - The key consists of the two values :math:`w0` and :math:`w1`, which result from the SPAKE2+ registration phase. - :math:`w0` and :math:`w1` are scalars in the same range as an Elliptic curve private key from the group used as the SPAKE2+ primitive group. - - For the |API|, the default format for a SPAKE2+ key pair is the concatenation of the formatted values for :math:`w0` and :math:`w1`, using the standard formats for Elliptic curve keys used by the |API|. - For example, for SPAKE2+ over P-256 (secp256r1), the output from :code:`psa_export_key()` would be the concatenation of: - - * The P-256 private key :math:`w0`. - This is a 32-byte big-endian encoding of the integer :math:`w0`. - * The P-256 private key :math:`w1`. - This is a 32-byte big-endian encoding of the integer :math:`w1`. - - .. subsection:: Compatible algorithms - - | `PSA_ALG_SPAKE2P_HMAC` - | `PSA_ALG_SPAKE2P_CMAC` - | `PSA_ALG_SPAKE2P_MATTER` - -.. macro:: PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY - :definition: /* specification-defined value */ - - .. summary:: - SPAKE2+ public key: the verifier key. - - .. param:: curve - A value of type :code:`psa_ecc_family_t` that identifies the Elliptic curve family to be used. - - The size of an SPAKE2+ public key is the same as the corresponding private key. - See `PSA_KEY_TYPE_SPAKE2P_KEY_PAIR()` and the documentation of each Elliptic curve family for details. - - To construct a SPAKE2+ public key, it must be imported. - - .. subsection:: Public key format - - A SPAKE2+ public key can be exported and imported, to enable use cases that require offline registration. - - The public key consists of the two values :math:`w0` and :math:`L`, which result from the SPAKE2+ registration phase. - :math:`w0` is a scalar in the same range as a Elliptic curve private key from the group used as the SPAKE2+ primitive group. - :math:`L` is a point on the curve, similar to a public key from the same group, corresponding to the :math:`w1` value in the key pair. - - For the |API|, the default format for a SPAKE2+ public key is the concatenation of the formatted values for :math:`w0` and :math:`L`, using the standard formats for Elliptic curve keys used by the |API|. - For example, for SPAKE2+ over P-256 (secp256r1), the output from :code:`psa_export_public_key()` would be the concatenation of: - - * The P-256 private key :math:`w0`. - This is a 32-byte big-endian encoding of the integer :math:`w0`. - * The P-256 public key :math:`L`. - This is a 65-byte concatenation of: - - - The byte ``0x04``. - - The 32-byte big-endian encoding of the x-coordinate of :math:`L`. - - The 32-byte big-endian encoding of the y-coordinate of :math:`L`. - - .. subsection:: Compatible algorithms - - | `PSA_ALG_SPAKE2P_HMAC` (verification only) - | `PSA_ALG_SPAKE2P_CMAC` (verification only) - | `PSA_ALG_SPAKE2P_MATTER` (verification only) - -.. macro:: PSA_KEY_TYPE_IS_SPAKE2P - :definition: /* specification-defined value */ - - .. summary:: - Whether a key type is a SPAKE2+ key, either a key pair or a public key. - - .. param:: type - A key type: a value of type :code:`psa_key_type_t`. - -.. macro:: PSA_KEY_TYPE_IS_SPAKE2P_KEY_PAIR - :definition: /* specification-defined value */ - - .. summary:: - Whether a key type is a SPAKE2+ key pair. - - .. param:: type - A key type: a value of type :code:`psa_key_type_t`. - -.. macro:: PSA_KEY_TYPE_IS_SPAKE2P_PUBLIC_KEY - :definition: /* specification-defined value */ - - .. summary:: - Whether a key type is a SPAKE2+ public key. - - .. param:: type - A key type: a value of type :code:`psa_key_type_t`. - -.. macro:: PSA_KEY_TYPE_SPAKE2P_GET_FAMILY - :definition: /* specification-defined value */ - - .. summary:: - Extract the curve family from a SPAKE2+ key type. - - .. param:: type - A SPAKE2+ key type: a value of type :code:`psa_key_type_t` such that :code:`PSA_KEY_TYPE_IS_SPAKE2P(type)` is true. - - .. 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. - .. _spake2p-algorithms: SPAKE2+ algorithms @@ -1946,7 +1735,6 @@ SPAKE2+ algorithms | :code:`PSA_KEY_TYPE_SPAKE2P_KEY_PAIR` | :code:`PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY` (verification only) - .. macro:: PSA_ALG_SPAKE2P_CMAC :definition: /* specification-defined value */ diff --git a/doc/crypto/api/ops/pke.rst b/doc/crypto/api/ops/pk-encryption.rst similarity index 100% rename from doc/crypto/api/ops/pke.rst rename to doc/crypto/api/ops/pk-encryption.rst diff --git a/doc/crypto/api/ops/rng.rst b/doc/crypto/api/ops/rng.rst index 91a96f31..86d7022b 100644 --- a/doc/crypto/api/ops/rng.rst +++ b/doc/crypto/api/ops/rng.rst @@ -1,8 +1,8 @@ -.. SPDX-FileCopyrightText: Copyright 2018-2022 Arm Limited and/or its affiliates +.. SPDX-FileCopyrightText: Copyright 2018-2022, 2024 Arm Limited and/or its affiliates .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license .. header:: psa/crypto - :seq: 29 + :seq: 30 Other cryptographic services ============================ diff --git a/doc/crypto/api/ops/sign.rst b/doc/crypto/api/ops/signature.rst similarity index 100% rename from doc/crypto/api/ops/sign.rst rename to doc/crypto/api/ops/signature.rst diff --git a/doc/crypto/appendix/encodings.rst b/doc/crypto/appendix/encodings.rst index 765fd654..79959901 100644 --- a/doc/crypto/appendix/encodings.rst +++ b/doc/crypto/appendix/encodings.rst @@ -83,6 +83,7 @@ The CAT field in an algorithm identifier takes the values shown in :numref:`tabl Asymmetric signature, ``0x06``, See :secref:`sign-encoding` Asymmetric encryption, ``0x07``, See :secref:`pke-encoding` Key agreement, ``0x09``, See :secref:`ka-encoding` + PAKE, ``0x0A``, See :secref:`pake-encoding` .. rationale:: @@ -385,6 +386,35 @@ A combined key agreement is constructed by a bitwise OR of the standalone key ag The underlying standalone key agreement algorithm can be extracted from the KA-TYPE field, and the key derivation algorithm from the KDF-TYPE and HASH-TYPE fields. +.. _pake-encoding: + +PAKE algorithm encoding +~~~~~~~~~~~~~~~~~~~~~~~ + +The algorithm identifier for PAKE algorithms defined in this specification are encoded as shown in :numref:`fig-pake-encoding`. + +.. figure:: /figure/encoding/pake_encoding.* + :name: fig-pake-encoding + + PAKE algorithm encoding + +The defined values for PAKE-TYPE are shown in :numref:`table-pake-type`. + +The permitted values of HASH-TYPE (see :numref:`table-hash-type`) depend on the specific PAKE algorithm. + +.. csv-table:: PAKE algorithm sub-type values + :name: table-pake-type + :header-rows: 1 + :align: left + :widths: auto + + PAKE algorithm, PAKE-TYPE, Algorithm identifier, Algorithm value + J-PAKE, ``0x01``, :code:`PSA_ALG_JPAKE(hash)`, ``0x0A0001hh`` :sup:`a` + 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`` + +a. ``hh`` is the HASH-TYPE for the hash algorithm, ``hash``, used to construct the key derivation algorithm. .. _key-type-encoding: @@ -538,6 +568,7 @@ The defined values for ASYM-TYPE are shown in :numref:`table-asymmetric-type`. RSA, 0, See :secref:`rsa-key-encoding` Elliptic Curve, 1, See :secref:`ecc-key-encoding` Diffie-Hellman, 2, See :secref:`dh-key-encoding` + SPAKE2+, 4, See :secref:`spakep2-key-encoding` .. _rsa-key-encoding: @@ -627,3 +658,31 @@ The defined values for DH-FAMILY and P are shown in :numref:`table-dh-type`. RFC7919, 0x01, 1, `PSA_DH_FAMILY_RFC7919`, ``0x4203``, ``0x7203`` a. 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. + +.. _spakep2-key-encoding: + +SPAKE2+ key encoding +~~~~~~~~~~~~~~~~~~~~ + +The key type for SPAKE2+ keys defined in this specification are encoded as shown in :numref:`fig-spake2p-key-fields`. + +.. figure:: ../figure/encoding/spake2p_key.* + :name: fig-spake2p-key-fields + + SPAKE2+ key encoding + +PAIR is either 0 for a public key, or 3 for a key pair. + +The defined values for ECC-FAMILY and P are shown in :numref:`table-spake2p-type`. + +.. csv-table:: SPAKE2+ key family values + :name: table-spake2p-type + :header-rows: 1 + :align: left + :widths: auto + + SPAKE2+ group, ECC-FAMILY, P, ECC family :sup:`a`, Public key value, Key pair value + SECP R1, 0x09, 0, :code:`PSA_ECC_FAMILY_SECP_R1`, ``0x4412``, ``0x7412`` + Twisted Edwards, 0x21, 0, :code:`PSA_ECC_FAMILY_TWISTED_EDWARDS`, ``0x4442``, ``0x7442`` + +a. The key type value is constructed from the Elliptic Curve family using either :code:`PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY(family)` or :code:`PSA_KEY_TYPE_SPAKE2P_KEY_PAIR(family)` as required. diff --git a/doc/crypto/appendix/history.rst b/doc/crypto/appendix/history.rst index b4aea203..ffa6eb22 100644 --- a/doc/crypto/appendix/history.rst +++ b/doc/crypto/appendix/history.rst @@ -11,6 +11,16 @@ Document change history This section provides the detailed changes made between published version of the document. +Changes between *1.2.1* and *1.3.0* +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:issue:`TBD` + +Other changes +~~~~~~~~~~~~~ + +* Integrated the PAKE Extension with the main specification for the |API|. + Changes between *1.2.0* and *1.2.1* ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/doc/crypto/appendix/specdef_values.rst b/doc/crypto/appendix/specdef_values.rst index 284edd7a..a6b4996d 100644 --- a/doc/crypto/appendix/specdef_values.rst +++ b/doc/crypto/appendix/specdef_values.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: Copyright 2020-2023 Arm Limited and/or its affiliates +.. SPDX-FileCopyrightText: Copyright 2020-2024 Arm Limited and/or its affiliates .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license .. _appendix-specdef-values: @@ -109,6 +109,9 @@ Algorithm macros #define PSA_ALG_IS_HMAC(alg) \ (((alg) & 0x7fc0ff00) == 0x03800000) + #define PSA_ALG_IS_JPAKE(alg) \ + (((alg) & ~0x000000ff) == 0x0a000100) + #define PSA_ALG_IS_KEY_AGREEMENT(alg) \ (((alg) & 0x7f000000) == 0x09000000) @@ -121,6 +124,9 @@ Algorithm macros #define PSA_ALG_IS_MAC(alg) \ (((alg) & 0x7f000000) == 0x03000000) + #define PSA_ALG_IS_PAKE(alg) \ + (((alg) & 0x7f000000) == 0x0a000000) + #define PSA_ALG_IS_PBKDF2_HMAC(alg) \ (((alg) & ~0x000000ff) == 0x08800100) @@ -155,6 +161,15 @@ Algorithm macros #define PSA_ALG_IS_SP800_108_COUNTER_HMAC(alg) \ (((alg) & ~0x000000ff) == 0x08000700) + #define PSA_ALG_IS_SPAKE2P(alg) \ + (((alg) & ~0x000003ff) == 0x0a000400) + + #define PSA_ALG_IS_SPAKE2P_CMAC(alg) \ + (((alg) & ~0x000000ff) == 0x0a000500) + + #define PSA_ALG_IS_SPAKE2P_HMAC(alg) \ + (((alg) & ~0x000000ff) == 0x0a000400) + #define PSA_ALG_IS_STANDALONE_KEY_AGREEMENT(alg) \ (((alg) & 0x7f00ffff) == 0x09000000) @@ -172,6 +187,9 @@ Algorithm macros (((alg) & 0x7f008000) == 0x03008000) || \ (((alg) & 0x7f008000) == 0x05008000)) + #define PSA_ALG_JPAKE(hash_alg) \ + ((psa_algorithm_t) (0x0a000100 | ((hash_alg) & 0x000000ff))) + #define PSA_ALG_KEY_AGREEMENT(ka_alg, kdf_alg) \ ((ka_alg) | (kdf_alg)) @@ -199,6 +217,12 @@ Algorithm macros #define PSA_ALG_SP800_108_COUNTER_HMAC(hash_alg) \ ((psa_algorithm_t) (0x08000700 | ((hash_alg) & 0x000000ff))) + #define PSA_ALG_SPAKE2P_CMAC(hash_alg) \ + ((psa_algorithm_t) (0x0a000500 | ((hash_alg) & 0x000000ff))) + + #define PSA_ALG_SPAKE2P_HMAC(hash_alg) \ + ((psa_algorithm_t) (0x0a000400 | ((hash_alg) & 0x000000ff))) + #define PSA_ALG_TLS12_PRF(hash_alg) \ ((psa_algorithm_t) (0x08000200 | ((hash_alg) & 0x000000ff))) @@ -208,6 +232,20 @@ Algorithm macros #define PSA_ALG_TRUNCATED_MAC(mac_alg, mac_length) \ ((psa_algorithm_t) (((mac_alg) & ~0x003f8000) | (((mac_length) & 0x3f) << 16))) + #define PSA_PAKE_PRIMITIVE(pake_type, pake_family, pake_bits) \ + ((pake_bits & 0xFFFF) != pake_bits) ? 0 : \ + ((psa_pake_primitive_t) (((pake_type) << 24 | \ + (pake_family) << 16) | (pake_bits))) + + #define PSA_PAKE_PRIMITIVE_GET_BITS(pake_primitive) \ + ((size_t)(pake_primitive & 0xFFFF)) + + #define PSA_PAKE_PRIMITIVE_GET_FAMILY(pake_primitive) \ + ((psa_pake_family_t)((pake_primitive >> 16) & 0xFF)) + + #define PSA_PAKE_PRIMITIVE_GET_TYPE(pake_primitive) \ + ((psa_pake_primitive_type_t)((pake_primitive >> 24) & 0xFF)) + Key type macros ~~~~~~~~~~~~~~~ @@ -264,6 +302,15 @@ Key type macros #define PSA_KEY_TYPE_IS_RSA(type) \ (PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) == 0x4001) + #define PSA_KEY_TYPE_IS_SPAKE2P(type) \ + ((PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) & 0xff00) == 0x4400) + + #define PSA_KEY_TYPE_IS_SPAKE2P_KEY_PAIR(type) \ + (((type) & 0xff00) == 0x7400) + + #define PSA_KEY_TYPE_IS_SPAKE2P_PUBLIC_KEY(type) \ + (((type) & 0xff00) == 0x4400) + #define PSA_KEY_TYPE_IS_UNSTRUCTURED(type) \ (((type) & 0x7000) == 0x1000 || ((type) & 0x7000) == 0x2000) @@ -273,6 +320,15 @@ Key type macros #define PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) \ ((psa_key_type_t) ((type) & ~0x3000)) + #define PSA_KEY_TYPE_SPAKE2P_GET_FAMILY(type) \ + ((psa_ecc_family_t) ((type) & 0x00ff)) + + #define PSA_KEY_TYPE_SPAKE2P_KEY_PAIR(curve) \ + ((psa_key_type_t) (0x7400 | (curve))) + + #define PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY(curve) \ + ((psa_key_type_t) (0x4400 | (curve))) + Hash suspend state macros ~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/crypto/conf.py b/doc/crypto/conf.py index be2bb2fa..9c84c1ca 100644 --- a/doc/crypto/conf.py +++ b/doc/crypto/conf.py @@ -22,17 +22,17 @@ 'doc_id': 'IHI 0086', # The short X.Y version. MANDATORY - 'version': '1.2', + 'version': '1.3', # Arm document quality status, marked as open issue if not provided 'quality': 'REL', # Arm document issue number (within that version and quality status) # Marked as open issue if not provided - 'issue_no': 1, + 'issue_no': 0, # Identifies the sequence number of a release candidate of the same issue # default to None 'release_candidate': 0, # Draft status - use this to indicate the document is not ready for publication - 'draft': False, + 'draft': True, # Arm document confidentiality. Must be either Non-confidential or Confidential # Marked as open issue if not provided @@ -43,7 +43,7 @@ 'license': 'psa-certified-api-license', # Document date, default to build date - 'date': '28/03/2024', + #'date': '28/03/2024', # Default header file for API definitions # default to None, and can be set in documentation source diff --git a/doc/ext-pake/figure/pake_encoding.json b/doc/crypto/figure/encoding/pake_encoding.json similarity index 100% rename from doc/ext-pake/figure/pake_encoding.json rename to doc/crypto/figure/encoding/pake_encoding.json diff --git a/doc/ext-pake/figure/pake_encoding.json.license b/doc/crypto/figure/encoding/pake_encoding.json.license similarity index 100% rename from doc/ext-pake/figure/pake_encoding.json.license rename to doc/crypto/figure/encoding/pake_encoding.json.license diff --git a/doc/ext-pake/figure/pake_encoding.pdf b/doc/crypto/figure/encoding/pake_encoding.pdf similarity index 100% rename from doc/ext-pake/figure/pake_encoding.pdf rename to doc/crypto/figure/encoding/pake_encoding.pdf diff --git a/doc/ext-pake/figure/pake_encoding.pdf.license b/doc/crypto/figure/encoding/pake_encoding.pdf.license similarity index 100% rename from doc/ext-pake/figure/pake_encoding.pdf.license rename to doc/crypto/figure/encoding/pake_encoding.pdf.license diff --git a/doc/ext-pake/figure/pake_encoding.svg b/doc/crypto/figure/encoding/pake_encoding.svg similarity index 100% rename from doc/ext-pake/figure/pake_encoding.svg rename to doc/crypto/figure/encoding/pake_encoding.svg diff --git a/doc/ext-pake/figure/pake_encoding.svg.license b/doc/crypto/figure/encoding/pake_encoding.svg.license similarity index 100% rename from doc/ext-pake/figure/pake_encoding.svg.license rename to doc/crypto/figure/encoding/pake_encoding.svg.license diff --git a/doc/ext-pake/figure/spake2p_key.json b/doc/crypto/figure/encoding/spake2p_key.json similarity index 100% rename from doc/ext-pake/figure/spake2p_key.json rename to doc/crypto/figure/encoding/spake2p_key.json diff --git a/doc/ext-pake/figure/spake2p_key.json.license b/doc/crypto/figure/encoding/spake2p_key.json.license similarity index 100% rename from doc/ext-pake/figure/spake2p_key.json.license rename to doc/crypto/figure/encoding/spake2p_key.json.license diff --git a/doc/ext-pake/figure/spake2p_key.pdf b/doc/crypto/figure/encoding/spake2p_key.pdf similarity index 100% rename from doc/ext-pake/figure/spake2p_key.pdf rename to doc/crypto/figure/encoding/spake2p_key.pdf diff --git a/doc/ext-pake/figure/spake2p_key.pdf.license b/doc/crypto/figure/encoding/spake2p_key.pdf.license similarity index 100% rename from doc/ext-pake/figure/spake2p_key.pdf.license rename to doc/crypto/figure/encoding/spake2p_key.pdf.license diff --git a/doc/ext-pake/figure/spake2p_key.svg b/doc/crypto/figure/encoding/spake2p_key.svg similarity index 100% rename from doc/ext-pake/figure/spake2p_key.svg rename to doc/crypto/figure/encoding/spake2p_key.svg diff --git a/doc/ext-pake/figure/spake2p_key.svg.license b/doc/crypto/figure/encoding/spake2p_key.svg.license similarity index 100% rename from doc/ext-pake/figure/spake2p_key.svg.license rename to doc/crypto/figure/encoding/spake2p_key.svg.license diff --git a/doc/ext-pake/figure/j-pake.pdf b/doc/crypto/figure/pake/j-pake.pdf similarity index 100% rename from doc/ext-pake/figure/j-pake.pdf rename to doc/crypto/figure/pake/j-pake.pdf diff --git a/doc/ext-pake/figure/j-pake.pdf.license b/doc/crypto/figure/pake/j-pake.pdf.license similarity index 100% rename from doc/ext-pake/figure/j-pake.pdf.license rename to doc/crypto/figure/pake/j-pake.pdf.license diff --git a/doc/ext-pake/figure/j-pake.puml b/doc/crypto/figure/pake/j-pake.puml similarity index 100% rename from doc/ext-pake/figure/j-pake.puml rename to doc/crypto/figure/pake/j-pake.puml diff --git a/doc/ext-pake/figure/j-pake.svg b/doc/crypto/figure/pake/j-pake.svg similarity index 100% rename from doc/ext-pake/figure/j-pake.svg rename to doc/crypto/figure/pake/j-pake.svg diff --git a/doc/ext-pake/figure/j-pake.svg.license b/doc/crypto/figure/pake/j-pake.svg.license similarity index 100% rename from doc/ext-pake/figure/j-pake.svg.license rename to doc/crypto/figure/pake/j-pake.svg.license diff --git a/doc/ext-pake/figure/pake_primitive.json b/doc/crypto/figure/pake/pake_primitive.json similarity index 100% rename from doc/ext-pake/figure/pake_primitive.json rename to doc/crypto/figure/pake/pake_primitive.json diff --git a/doc/ext-pake/figure/pake_primitive.json.license b/doc/crypto/figure/pake/pake_primitive.json.license similarity index 100% rename from doc/ext-pake/figure/pake_primitive.json.license rename to doc/crypto/figure/pake/pake_primitive.json.license diff --git a/doc/ext-pake/figure/pake_primitive.pdf b/doc/crypto/figure/pake/pake_primitive.pdf similarity index 100% rename from doc/ext-pake/figure/pake_primitive.pdf rename to doc/crypto/figure/pake/pake_primitive.pdf diff --git a/doc/ext-pake/figure/pake_primitive.pdf.license b/doc/crypto/figure/pake/pake_primitive.pdf.license similarity index 100% rename from doc/ext-pake/figure/pake_primitive.pdf.license rename to doc/crypto/figure/pake/pake_primitive.pdf.license diff --git a/doc/ext-pake/figure/pake_primitive.svg b/doc/crypto/figure/pake/pake_primitive.svg similarity index 100% rename from doc/ext-pake/figure/pake_primitive.svg rename to doc/crypto/figure/pake/pake_primitive.svg diff --git a/doc/ext-pake/figure/pake_primitive.svg.license b/doc/crypto/figure/pake/pake_primitive.svg.license similarity index 100% rename from doc/ext-pake/figure/pake_primitive.svg.license rename to doc/crypto/figure/pake/pake_primitive.svg.license diff --git a/doc/ext-pake/figure/spake2plus-reg.pdf b/doc/crypto/figure/pake/spake2plus-reg.pdf similarity index 100% rename from doc/ext-pake/figure/spake2plus-reg.pdf rename to doc/crypto/figure/pake/spake2plus-reg.pdf diff --git a/doc/ext-pake/figure/spake2plus-reg.pdf.license b/doc/crypto/figure/pake/spake2plus-reg.pdf.license similarity index 100% rename from doc/ext-pake/figure/spake2plus-reg.pdf.license rename to doc/crypto/figure/pake/spake2plus-reg.pdf.license diff --git a/doc/ext-pake/figure/spake2plus-reg.puml b/doc/crypto/figure/pake/spake2plus-reg.puml similarity index 100% rename from doc/ext-pake/figure/spake2plus-reg.puml rename to doc/crypto/figure/pake/spake2plus-reg.puml diff --git a/doc/ext-pake/figure/spake2plus-reg.svg b/doc/crypto/figure/pake/spake2plus-reg.svg similarity index 100% rename from doc/ext-pake/figure/spake2plus-reg.svg rename to doc/crypto/figure/pake/spake2plus-reg.svg diff --git a/doc/ext-pake/figure/spake2plus-reg.svg.license b/doc/crypto/figure/pake/spake2plus-reg.svg.license similarity index 100% rename from doc/ext-pake/figure/spake2plus-reg.svg.license rename to doc/crypto/figure/pake/spake2plus-reg.svg.license diff --git a/doc/ext-pake/figure/spake2plus.pdf b/doc/crypto/figure/pake/spake2plus.pdf similarity index 100% rename from doc/ext-pake/figure/spake2plus.pdf rename to doc/crypto/figure/pake/spake2plus.pdf diff --git a/doc/ext-pake/figure/spake2plus.pdf.license b/doc/crypto/figure/pake/spake2plus.pdf.license similarity index 100% rename from doc/ext-pake/figure/spake2plus.pdf.license rename to doc/crypto/figure/pake/spake2plus.pdf.license diff --git a/doc/ext-pake/figure/spake2plus.puml b/doc/crypto/figure/pake/spake2plus.puml similarity index 100% rename from doc/ext-pake/figure/spake2plus.puml rename to doc/crypto/figure/pake/spake2plus.puml diff --git a/doc/ext-pake/figure/spake2plus.svg b/doc/crypto/figure/pake/spake2plus.svg similarity index 100% rename from doc/ext-pake/figure/spake2plus.svg rename to doc/crypto/figure/pake/spake2plus.svg diff --git a/doc/ext-pake/figure/spake2plus.svg.license b/doc/crypto/figure/pake/spake2plus.svg.license similarity index 100% rename from doc/ext-pake/figure/spake2plus.svg.license rename to doc/crypto/figure/pake/spake2plus.svg.license diff --git a/doc/crypto/overview/functionality.rst b/doc/crypto/overview/functionality.rst index efa9d230..7be012c7 100644 --- a/doc/crypto/overview/functionality.rst +++ b/doc/crypto/overview/functionality.rst @@ -4,7 +4,7 @@ .. _functionality-overview: Functionality overview ----------------------- +====================== This section provides a high-level overview of the functionality provided by the interface defined in this specification. Refer to the @@ -17,7 +17,7 @@ Due to the modularity of the interface, almost every part of the library is optional. The only mandatory function is `psa_crypto_init()`. Library management -~~~~~~~~~~~~~~~~~~ +------------------ Applications must call `psa_crypto_init()` to initialize the library before using any other function. @@ -25,7 +25,7 @@ using any other function. .. _key-overview: Key management -~~~~~~~~~~~~~~ +-------------- Applications always access keys indirectly via an identifier, and can perform operations using a key without accessing the key material. This allows keys to @@ -50,6 +50,7 @@ Keys are created using one of the *key creation functions*: * `psa_generate_key()` * `psa_key_derivation_output_key()` * `psa_key_agreement()` +* `psa_pake_get_shared_key()` * `psa_copy_key()` These output the key identifier, that is used to access the key in all other parts of the API. @@ -67,7 +68,7 @@ application is prepared to handle a failure of the operation. .. _key-types-intro: Key types -^^^^^^^^^ +~~~~~~~~~ Each cryptographic algorithm requires a key that has the right form, in terms of the size of the key material and its numerical properties. The key type and key size encode that information about a key, and determine whether the key is compatible with a cryptographic algorithm. @@ -78,7 +79,7 @@ See :secref:`key-types`. .. _key-ids: Key identifiers -^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~ Key identifiers are integral values that act as permanent names for persistent keys, or as transient references to volatile keys. Key identifiers are defined by the application for persistent keys, and by the implementation for volatile keys and for built-in keys. @@ -93,7 +94,7 @@ See :secref:`key-identifiers`. .. _key-life: Key lifetimes -^^^^^^^^^^^^^ +~~~~~~~~~~~~~ The lifetime of a key indicates where it is stored and which application and system actions will create and destroy it. @@ -108,12 +109,12 @@ See :secref:`key-lifetimes`. .. _key-usage-policies: Key policies -^^^^^^^^^^^^ +~~~~~~~~~~~~ All keys have an associated policy that regulates which operations are permitted on the key. Each key policy is a set of usage flags and a specific algorithm that is permitted with the key. See :secref:`key-policy`. Recommendations of minimum standards for key management -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Most implementations provide the following functions: @@ -134,28 +135,16 @@ Most implementations provide the following functions: designed to work only with short-term keys, or only with long-term non-extractable keys, do not need to provide this function. -Symmetric cryptography -~~~~~~~~~~~~~~~~~~~~~~ +Cryptographic operations +------------------------ -This specification defines interfaces for the following types of symmetric -cryptographic operation: +For each type of cryptographic operation, the API can include: -* Message digests, commonly known as hash functions. See :secref:`hashes`. -* Message authentication codes (MAC). See :secref:`macs`. -* Symmetric ciphers. See :secref:`ciphers`. -* Authenticated encryption with associated data (AEAD). See :secref:`aead`. -* Key derivation. See :secref:`kdf`. - -For each type of symmetric cryptographic operation, the API can include: - -* A pair of *single-part* functions. For example, compute and verify, or - encrypt and decrypt. -* A series of functions that permit *multi-part operations*. - -Key derivation only provides multi-part operation, to support the flexibility required by these type of algorithms. +* One or more *single-part* functions, which perform a whole operation in a single function call. For example, compute, verify, encrypt or decrypt. +* A *multi-part operation* --- which is a series of functions that work with a stored operation state. Single-part Functions -^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~ Single-part functions are APIs that implement the cryptographic operation in a single function call. This is the easiest API to use when all of the inputs and @@ -168,7 +157,7 @@ use of a `multi-part operation `. .. _multi-part-operations: Multi-part operations -^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~ Multi-part operations are APIs which split a single cryptographic operation into a sequence of separate steps. This enables fine control over the configuration @@ -180,6 +169,7 @@ the use of a multi-part operation: * Using a deterministic IV for unauthenticated encryption. * Providing the IV separately for unauthenticated encryption or decryption. * Separating the AEAD authentication tag from the cipher text. +* Password-authenticated key exchange (PAKE) is a multi-step process. Each multi-part operation defines a specific object type to maintain the state of the operation. These types are implementation-defined. @@ -220,9 +210,9 @@ The typical sequence of actions with a multi-part operation is as follows: On success, a setup function will put an operation object into an *active* state. On failure, the operation object will remain *inactive*. -#. **Update:** Update an *active* operation object. The update function can - provide additional parameters, supply data for processing or generate - outputs. +#. **Update:** Update an *active* operation object. Each operation object + defines one or more update functions, which are used to provide additional + parameters, supply data for processing or generate outputs. On success, the operation object remains *active*. On failure, the operation object will enter an *error* state. @@ -263,7 +253,6 @@ The typical sequence of actions with a multi-part operation is as follows: For many applications, there is also (non-psa/crypto) local activity during a multipart operation that can give rise to errors that would result in the application choosing to abort the operation. Thus, requiring the application to always call ``psa_xxx_abort()`` on an error does not automatically lead to extra code in the application, and may have no effect on the application code size. - Once an operation object is returned to the *inactive* state, it can be reused by calling one of the applicable setup functions again. @@ -294,6 +283,20 @@ Each type of multi-part operation can have multiple *active* states. Documentation for the specific operation describes the configuration and update functions, and any requirements about their usage and ordering. +Symmetric cryptography +~~~~~~~~~~~~~~~~~~~~~~ + +This specification defines interfaces for the following types of symmetric +cryptographic operation: + +* Message digests, commonly known as hash functions. See :secref:`hashes`. +* Message authentication codes (MAC). See :secref:`macs`. +* Symmetric ciphers. See :secref:`ciphers`. +* Authenticated encryption with associated data (AEAD). See :secref:`aead`. +* Key derivation. See :secref:`kdf`. + +Key derivation only provides multi-part operation, to support the flexibility required by these type of algorithms. + .. _symmetric-crypto-example: Example of the symmetric cryptography API @@ -339,12 +342,12 @@ This specification defines interfaces for the following types of asymmetric cryp * Asymmetric encryption (also known as public key encryption). See :secref:`pke`. * Asymmetric signature. See :secref:`sign`. * Two-way key agreement (also known as key establishment). See :secref:`key-agreement`. +* Password-authenticated key exchange (PAKE). See :secref:`pake`. -For asymmetric encryption and signature, the API provides *single-part* functions. For key agreement, the API provides single-part functions and an additional input method for a key derivation operation. - +For asymmetric encryption and signature, the API provides *single-part* functions. For key agreement, the API provides single-part functions and an additional input method for a key derivation operation. For PAKE, the API provides a multi-part operation. Randomness and key generation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------------- We strongly recommended that implementations include a random generator, consisting of a cryptographically secure pseudo-random generator (CSPRNG), which diff --git a/doc/crypto/overview/intro.rst b/doc/crypto/overview/intro.rst index cd117611..7c2306c1 100644 --- a/doc/crypto/overview/intro.rst +++ b/doc/crypto/overview/intro.rst @@ -26,8 +26,6 @@ This document includes: * General considerations for implementers of this specification, and for applications that use the interface defined in this specification. See :secref:`implementation-considerations` and :secref:`usage-considerations`. * A detailed definition of the API. See :secref:`library-management`, :secref:`key-management`, and :secref:`crypto-operations`. -:cite-title:`PSA-PAKE` is a companion document for version |docversion| of this specification. :cite:`PSA-PAKE` defines an API for Password Authenticated Key Establishment (PAKE) algorithms. The PAKE API is now at FINAL status, and will be included in a future version of the |API| specification. - -In future, other companion documents will define *profiles* for this specification. A profile is +In future, companion documents will define *profiles* for this specification. A profile is a minimum mandatory subset of the interface that a compliant implementation must provide. diff --git a/doc/crypto/references b/doc/crypto/references index 3f5c5eda..196e15df 100644 --- a/doc/crypto/references +++ b/doc/crypto/references @@ -1,11 +1,6 @@ .. SPDX-FileCopyrightText: Copyright 2020-2024 Arm Limited and/or its affiliates .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license -.. reference:: PSA-PAKE - :title: PSA Certified Crypto API 1.2 PAKE Extension - :doc_no: ARM AES 0058 - :url: arm-software.github.io/psa-api/crypto - .. reference:: PSM :title: Platform Security Model :doc_no: ARM DEN 0128 @@ -365,3 +360,39 @@ :title: IEEE Standard for Low-Rate Wireless Networks :url: standards.ieee.org/ieee/802.15.4/7029/ :publication: 2020 + +.. reference:: MATTER + :title: Matter Specification, Version 1.2 + :author: CSA + :publication: October 2023 + :url: csa-iot.org/all-solutions/matter/ + +.. reference:: RFC8235 + :title: Schnorr Non-interactive Zero-Knowledge Proof + :author: IETF + :publication: September 2017 + :url: tools.ietf.org/html/rfc8235.html + +.. reference:: RFC8236 + :title: J-PAKE: Password-Authenticated Key Exchange by Juggling + :author: IETF + :publication: September 2017 + :url: tools.ietf.org/html/rfc8236.html + +.. reference:: RFC9383 + :title: SPAKE2+, an Augmented Password-Authenticated Key Exchange (PAKE) Protocol + :author: IETF + :publication: September 2023 + :url: tools.ietf.org/html/rfc9383.html + +.. reference:: SPAKE2P-2 + :title: SPAKE2+, an Augmented PAKE (Draft 02) + :author: IETF + :publication: December 2020 + :url: datatracker.ietf.org/doc/draft-bar-cfrg-spake2plus-02 + +.. reference:: THREAD + :title: Thread Specification 1.3.0 + :author: Thread Group + :publication: July 2022 + :url: www.threadgroup.org/ThreadSpec diff --git a/doc/crypto/releases b/doc/crypto/releases index b2ec2f6a..4a5bdf16 100644 --- a/doc/crypto/releases +++ b/doc/crypto/releases @@ -66,3 +66,9 @@ :confidentiality: Non-confidential Clarifications and fixes + +.. release:: 1.3.0 Final + :date: ? 2024 + :confidentiality: Non-confidential + + Integrated the PAKE extension. diff --git a/doc/ext-pake/README.md b/doc/ext-pake/README.md deleted file mode 100644 index 55ade1bf..00000000 --- a/doc/ext-pake/README.md +++ /dev/null @@ -1,20 +0,0 @@ - - -# PSA Certified Crypto API PAKE Extension — specification sources - -The Crypto API PAKE Extension specification source files are organized as follows: - -Folder | Content --- | -- -Current directory | Configuration and front-matter -`overview` | Informative chapter 1 -`api` | API reference chapter 2 -`appendix` | Appendix chapters -`figure` | Image files - ----- - -*Copyright 2022, Arm Limited and/or its affiliates* diff --git a/doc/ext-pake/about.rst b/doc/ext-pake/about.rst deleted file mode 100644 index ed120396..00000000 --- a/doc/ext-pake/about.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. SPDX-FileCopyrightText: Copyright 2022, 2024 Arm Limited and/or its affiliates -.. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license - -.. include:: releases - -.. include:: references - -.. include:: terms - -.. release-info:: - :extend: - - The detailed changes in each release are described in :secref:`changes`. - -.. potential-for-change:: - - The contents of this specification are stable for version |docversion|. - - The following may change in updates to the version |docversion| specification: - - * Small optional feature additions. - * Clarifications. - - Significant additions, or any changes that affect the compatibility of the interfaces defined in this specification will only be included in a new major or minor version of the specification. - -.. current-status:: - - This document is at Release/Final quality status. - -.. about:: diff --git a/doc/ext-pake/api.db/psa/crypto-pake.h b/doc/ext-pake/api.db/psa/crypto-pake.h deleted file mode 100644 index 8b48acf5..00000000 --- a/doc/ext-pake/api.db/psa/crypto-pake.h +++ /dev/null @@ -1,95 +0,0 @@ -// SPDX-FileCopyrightText: Copyright 2018-2024 Arm Limited and/or its affiliates -// SPDX-License-Identifier: Apache-2.0 - -typedef /* implementation-defined type */ psa_pake_cipher_suite_t; -typedef uint8_t psa_pake_family_t; -typedef /* implementation-defined type */ psa_pake_operation_t; -typedef uint32_t psa_pake_primitive_t; -typedef uint8_t psa_pake_primitive_type_t; -typedef uint8_t psa_pake_role_t; -typedef uint8_t psa_pake_step_t; -#define PSA_ALG_IS_JPAKE(alg) /* specification-defined value */ -#define PSA_ALG_IS_PAKE(alg) /* specification-defined value */ -#define PSA_ALG_IS_SPAKE2P(alg) /* specification-defined value */ -#define PSA_ALG_IS_SPAKE2P_CMAC(alg) /* specification-defined value */ -#define PSA_ALG_IS_SPAKE2P_HMAC(alg) /* specification-defined value */ -#define PSA_ALG_JPAKE(hash_alg) /* 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_KEY_TYPE_IS_SPAKE2P(type) /* specification-defined value */ -#define PSA_KEY_TYPE_IS_SPAKE2P_KEY_PAIR(type) \ - /* specification-defined value */ -#define PSA_KEY_TYPE_IS_SPAKE2P_PUBLIC_KEY(type) \ - /* specification-defined value */ -#define PSA_KEY_TYPE_SPAKE2P_GET_FAMILY(type) /* specification-defined value */ -#define PSA_KEY_TYPE_SPAKE2P_KEY_PAIR(curve) /* specification-defined value */ -#define PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY(curve) \ - /* specification-defined value */ -#define PSA_PAKE_CIPHER_SUITE_INIT /* implementation-defined value */ -#define PSA_PAKE_CONFIRMED_KEY 0 -#define PSA_PAKE_INPUT_MAX_SIZE /* implementation-defined value */ -#define PSA_PAKE_INPUT_SIZE(alg, primitive, input_step) \ - /* implementation-defined value */ -#define PSA_PAKE_OPERATION_INIT /* implementation-defined value */ -#define PSA_PAKE_OUTPUT_MAX_SIZE /* implementation-defined value */ -#define PSA_PAKE_OUTPUT_SIZE(alg, primitive, output_step) \ - /* implementation-defined value */ -#define PSA_PAKE_PRIMITIVE(pake_type, pake_family, pake_bits) \ - /* specification-defined value */ -#define PSA_PAKE_PRIMITIVE_GET_BITS(pake_primitive) \ - /* specification-defined value */ -#define PSA_PAKE_PRIMITIVE_GET_FAMILY(pake_primitive) \ - /* specification-defined value */ -#define PSA_PAKE_PRIMITIVE_GET_TYPE(pake_primitive) \ - /* specification-defined value */ -#define PSA_PAKE_PRIMITIVE_TYPE_DH ((psa_pake_primitive_type_t)0x02) -#define PSA_PAKE_PRIMITIVE_TYPE_ECC ((psa_pake_primitive_type_t)0x01) -#define PSA_PAKE_ROLE_CLIENT ((psa_pake_role_t)0x11) -#define PSA_PAKE_ROLE_FIRST ((psa_pake_role_t)0x01) -#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_CONFIRM ((psa_pake_step_t)0x04) -#define PSA_PAKE_STEP_KEY_SHARE ((psa_pake_step_t)0x01) -#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 -psa_status_t psa_pake_abort(psa_pake_operation_t * operation); -psa_pake_cipher_suite_t psa_pake_cipher_suite_init(void); -psa_algorithm_t psa_pake_cs_get_algorithm(const psa_pake_cipher_suite_t* cipher_suite); -uint32_t psa_pake_cs_get_key_confirmation(const psa_pake_cipher_suite_t* cipher_suite); -psa_pake_primitive_t psa_pake_cs_get_primitive(const psa_pake_cipher_suite_t* cipher_suite); -void psa_pake_cs_set_algorithm(psa_pake_cipher_suite_t* cipher_suite, - psa_algorithm_t alg); -void psa_pake_cs_set_key_confirmation(psa_pake_cipher_suite_t* cipher_suite, - uint32_t key_confirmation); -void psa_pake_cs_set_primitive(psa_pake_cipher_suite_t* cipher_suite, - psa_pake_primitive_t primitive); -psa_status_t psa_pake_get_shared_key(psa_pake_operation_t *operation, - const psa_key_attributes_t * attributes, - psa_key_id_t * key); -psa_status_t psa_pake_input(psa_pake_operation_t *operation, - psa_pake_step_t step, - const uint8_t *input, - size_t input_length); -psa_pake_operation_t psa_pake_operation_init(void); -psa_status_t psa_pake_output(psa_pake_operation_t *operation, - psa_pake_step_t step, - uint8_t *output, - size_t output_size, - size_t *output_length); -psa_status_t psa_pake_set_context(psa_pake_operation_t *operation, - const uint8_t *context, - size_t context_len); -psa_status_t psa_pake_set_peer(psa_pake_operation_t *operation, - const uint8_t *peer_id, - size_t peer_id_len); -psa_status_t psa_pake_set_role(psa_pake_operation_t *operation, - psa_pake_role_t role); -psa_status_t psa_pake_set_user(psa_pake_operation_t *operation, - const uint8_t *user_id, - size_t user_id_len); -psa_status_t psa_pake_setup(psa_pake_operation_t *operation, - psa_key_id_t password_key, - const psa_pake_cipher_suite_t *cipher_suite); diff --git a/doc/ext-pake/api/encodings.rst b/doc/ext-pake/api/encodings.rst deleted file mode 100644 index bd79abef..00000000 --- a/doc/ext-pake/api/encodings.rst +++ /dev/null @@ -1,106 +0,0 @@ -.. SPDX-FileCopyrightText: Copyright 2022-2023 Arm Limited and/or its affiliates -.. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license - -.. _pake-encodings: - -Algorithm and key type encoding -=============================== - -These are encodings for a PAKE interface for :cite-title:`PSA-CRYPT`. - -.. note:: - - These encodings will be integrated into a future version of :cite:`PSA-CRYPT`. - -Algorithm encoding ------------------- - -A new algorithm category is added for PAKE algorithms. The algorithm category table in `[PSA-CRYPT]` Appendix B is extended with the information in :numref:`table-pake-algorithm-category`. - -.. csv-table:: New algorithm identifier categories - :name: table-pake-algorithm-category - :header-rows: 1 - :align: left - :widths: auto - - Algorithm category, CAT, Category details - PAKE, ``0x0A``, See :secref:`pake-encoding` - -.. _pake-encoding: - -PAKE algorithm encoding -~~~~~~~~~~~~~~~~~~~~~~~ - -The algorithm identifier for PAKE algorithms defined in this specification are encoded as shown in :numref:`fig-pake-encoding`. - -.. figure:: /figure/pake_encoding.* - :name: fig-pake-encoding - - PAKE algorithm encoding - -The defined values for PAKE-TYPE are shown in :numref:`table-pake-type`. - -The permitted values of HASH-TYPE depend on the specific PAKE algorithm. - -.. - The permitted values of HASH-TYPE (see :numref:`table-hash-type`) depend on the specific PAKE algorithm. - -.. csv-table:: PAKE algorithm sub-type values - :name: table-pake-type - :header-rows: 1 - :align: left - :widths: auto - - PAKE algorithm, PAKE-TYPE, Algorithm identifier, Algorithm value - J-PAKE, ``0x01``, :code:`PSA_ALG_JPAKE(hash)`, ``0x0A0001hh`` :sup:`a` - 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`` - -a. ``hh`` is the HASH-TYPE for the hash algorithm, ``hash``, used to construct the key derivation algorithm. - -Key encoding ------------- - -A new type of asymmetric key is added for the SPAKE2+ algorithms. The Asymmetric key sub-type values table in `[PSA-CRYPT]` Appendix B is extended with the information in :numref:`table-spake2p-keys`. - -.. csv-table:: New SPAKE2+ asymmetric key sub-type - :name: table-spake2p-keys - :header-rows: 1 - :align: left - :widths: auto - - Asymmetric key type, ASYM-TYPE, Details - SPAKE2+, 4, See :secref:`spakep2-key-encoding` - -.. rationale:: - - The ASYM-TYPE value 4 is selected as this has the same parity as the ECC sub-type, which have the value 1. The enables the same ECC-FAMILY and P values to be used when encoding a SPAKE2+ key type, as is used in the Elliptic Curve key types. - -.. _spakep2-key-encoding: - -SPAKE2+ key encoding -~~~~~~~~~~~~~~~~~~~~ - -The key type for SPAKE2+ keys defined in this specification are encoded as shown in :numref:`fig-spake2p-key-fields`. - -.. figure:: ../figure/spake2p_key.* - :name: fig-spake2p-key-fields - - SPAKE2+ key encoding - -PAIR is either 0 for a public key, or 3 for a key pair. - -The defined values for ECC-FAMILY and P are shown in :numref:`table-spake2p-type`. - -.. csv-table:: SPAKE2+ key family values - :name: table-spake2p-type - :header-rows: 1 - :align: left - :widths: auto - - SPAKE2+ group, ECC-FAMILY, P, ECC family :sup:`a`, Public key value, Key pair value - SECP R1, 0x09, 0, :code:`PSA_ECC_FAMILY_SECP_R1`, ``0x4412``, ``0x7412`` - Twisted Edwards, 0x21, 0, :code:`PSA_ECC_FAMILY_TWISTED_EDWARDS`, ``0x4442``, ``0x7442`` - -a. The key type value is constructed from the Elliptic Curve family using either :code:`PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY(family)` or :code:`PSA_KEY_TYPE_SPAKE2P_KEY_PAIR(family)` as required. diff --git a/doc/ext-pake/appendix/example_header.rst b/doc/ext-pake/appendix/example_header.rst deleted file mode 100644 index fce5c167..00000000 --- a/doc/ext-pake/appendix/example_header.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. SPDX-FileCopyrightText: Copyright 2022 Arm Limited and/or its affiliates -.. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license - -.. _example-header: - -Example header file -------------------- - -The API elements in this specification, once finalized, will be defined in :file:`psa/crypto.h`. - -This is an example of the header file definition of the PAKE API elements. This can be used as a starting point or reference for an implementation. - -.. note:: - Not all of the API elements are fully defined. An implementation must provide the full definition. - - The header will not compile without these missing definitions, and might require reordering to satisfy C compilation rules. - -psa/crypto.h -~~~~~~~~~~~~ - -.. insert-header:: psa/crypto-pake diff --git a/doc/ext-pake/appendix/history.rst b/doc/ext-pake/appendix/history.rst deleted file mode 100644 index a9f0a864..00000000 --- a/doc/ext-pake/appendix/history.rst +++ /dev/null @@ -1,55 +0,0 @@ -.. SPDX-FileCopyrightText: Copyright 2022-2024 Arm Limited and/or its affiliates -.. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license - -Changes to the API -================== - -.. _changes: - -Document change history ------------------------ - -This section provides the detailed changes made between published version of the document. - -Changes between *Final* and *Final.1* -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Clarifications and fixes -~~~~~~~~~~~~~~~~~~~~~~~~ - -* Fixed the sample code that demonstrates extracting the shared key for J-PAKE and SPAKE2+ operations. - -Changes between *Beta 1* and *Final* -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -API changes -~~~~~~~~~~~ - -* Combined :code:`psa_pake_set_password_key()` with :code:`psa_pake_setup()`. This aligns the API better with other multi-part operations, and also enables an implementation to identify the key location when setting up the operation. -* Moved the hash algorithm parameter for the PAKE cipher suite into the PAKE algorithm identifier, instead of a separate attribute of the cipher suite. This also makes the hash algorithm value available to the `PSA_PAKE_OUTPUT_SIZE()` and `PSA_PAKE_INPUT_SIZE()` macros. -* Add the `PSA_PAKE_STEP_CONFIRM` PAKE step for input and output of key confirmation values. -* Add `psa_pake_set_context()` to set context data for a PAKE operation. -* Replaced :code:`psa_pake_get_implicit_key()` with :code:`psa_pake_get_shared_key()`. This returns a new key containing the shared secret, instead of injecting the shared secret into a key derivation operation. -* Added a key confirmation attribute to the PAKE cipher suite. This indicates whether the application wants to extract the shared secret before, or after, key confirmation. See :secref:`pake-cipher-suite`. -* Added asymmetric key types for SPAKE2+ registration, `PSA_KEY_TYPE_SPAKE2P_KEY_PAIR()` and `PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY()`. Documented the import/export public key format and key derivation process for these keys. -* Added SPAKE2+ algorithms, supporting both :rfc-title:`9383` and :cite-title:`MATTER`. Added the following APIs: - - - `PSA_ALG_SPAKE2P_HMAC()` - - `PSA_ALG_SPAKE2P_CMAC()` - - `PSA_ALG_SPAKE2P_MATTER` - - `PSA_ALG_IS_SPAKE2P()` - - `PSA_ALG_IS_SPAKE2P_HMAC()` - - `PSA_ALG_IS_SPAKE2P_CMAC()` - -Clarifications -~~~~~~~~~~~~~~ - -* Clarified the behavior of the PAKE operation following a call to `psa_pake_setup()`. - -Changes between *Beta 0* and *Beta 1* -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Other changes -~~~~~~~~~~~~~ - -* Relicensed the document under Attribution-ShareAlike 4.0 International with a patent license derived from Apache License 2.0. See :secref:`license`. diff --git a/doc/ext-pake/appendix/specdef_values.rst b/doc/ext-pake/appendix/specdef_values.rst deleted file mode 100644 index 46066667..00000000 --- a/doc/ext-pake/appendix/specdef_values.rst +++ /dev/null @@ -1,72 +0,0 @@ -.. SPDX-FileCopyrightText: Copyright 2022-2023 Arm Limited and/or its affiliates -.. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license - -.. _specification-defined-value: - -Example macro implementations ------------------------------ - -This section provides example implementations of the function-like macros that have specification-defined values. - -.. note:: - In a future version of this specification, these example implementations will be replaced with a pseudo-code representation of the macro's computation in the macro description. - -The examples here provide correct results for the valid inputs defined by each API, for an implementation that supports all of the defined algorithms and key types. An implementation can provide alternative definitions of these macros: - -.. code-block:: xref - - #define PSA_ALG_IS_JPAKE(alg) \ - (((alg) & ~0x000000ff) == 0x0a000100) - - #define PSA_ALG_IS_PAKE(alg) \ - (((alg) & 0x7f000000) == 0x0a000000) - - #define PSA_ALG_IS_SPAKE2P(alg) \ - (((alg) & ~0x000003ff) == 0x0a000400) - - #define PSA_ALG_IS_SPAKE2P_CMAC(alg) \ - (((alg) & ~0x000000ff) == 0x0a000500) - - #define PSA_ALG_IS_SPAKE2P_HMAC(alg) \ - (((alg) & ~0x000000ff) == 0x0a000400) - - #define PSA_ALG_JPAKE(hash_alg) \ - ((psa_algorithm_t) (0x0a000100 | ((hash_alg) & 0x000000ff))) - - #define PSA_ALG_SPAKE2P_CMAC(hash_alg) \ - ((psa_algorithm_t) (0x0a000500 | ((hash_alg) & 0x000000ff))) - - #define PSA_ALG_SPAKE2P_HMAC(hash_alg) \ - ((psa_algorithm_t) (0x0a000400 | ((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 | \ - (pake_family) << 16) | (pake_bits))) - - #define PSA_PAKE_PRIMITIVE_GET_BITS(pake_primitive) \ - ((size_t)(pake_primitive & 0xFFFF)) - - #define PSA_PAKE_PRIMITIVE_GET_FAMILY(pake_primitive) \ - ((psa_pake_family_t)((pake_primitive >> 16) & 0xFF)) - - #define PSA_PAKE_PRIMITIVE_GET_TYPE(pake_primitive) \ - ((psa_pake_primitive_type_t)((pake_primitive >> 24) & 0xFF)) - - #define PSA_KEY_TYPE_SPAKE2P_GET_FAMILY(type) \ - ((psa_ecc_family_t) ((type) & 0x00ff)) - - #define PSA_KEY_TYPE_SPAKE2P_KEY_PAIR(curve) \ - ((psa_key_type_t) (0x7400 | (curve))) - - #define PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY(curve) \ - ((psa_key_type_t) (0x4400 | (curve))) - - #define PSA_KEY_TYPE_IS_SPAKE2P(type) \ - ((PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) & 0xff00) == 0x4400) - - #define PSA_KEY_TYPE_IS_SPAKE2P_KEY_PAIR(type) \ - (((type) & 0xff00) == 0x7400) - - #define PSA_KEY_TYPE_IS_SPAKE2P_PUBLIC_KEY(type) \ - (((type) & 0xff00) == 0x4400) diff --git a/doc/ext-pake/conf.py b/doc/ext-pake/conf.py deleted file mode 100644 index abc999a8..00000000 --- a/doc/ext-pake/conf.py +++ /dev/null @@ -1,119 +0,0 @@ -# SPDX-FileCopyrightText: Copyright 2022-2024 Arm Limited and/or its affiliates -# SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license - -# PSA Certified API document configuration -# -# This is used to generate all of the sphinx configuration data and determine -# the document file name etc. - -doc_info = { - # Document template - 'template': 'psa-api-2022', - - # Document title, MANDATORY - 'title': 'PSA Certified\nCrypto API', - 'author': 'Arm Limited', - - # Document copyright date, default to year of 'date' - 'copyright_date': '2022-2024', - 'copyright': 'Arm Limited and/or its affiliates', - - # Arm document identifier, marked as open issue if not provided - 'doc_id': 'AES 0058', - - # The short X.Y version. MANDATORY - 'version': '1.2', - 'extension_doc': 'PAKE Extension', - - # Arm document quality status, marked as open issue if not provided - 'quality': 'REL', - # Arm document issue number (within that version and quality status) - # Marked as open issue if not provided - 'issue_no': 1, - # Identifies the sequence number of a release candidate of the same issue - # default to None - 'release_candidate': 0, - # Draft status - use this to indicate the document is not ready for publication - 'draft': False, - - # Arm document confidentiality. Must be either Non-confidential or Confidential - # Marked as open issue if not provided - 'confidentiality': 'Non-confidential', - - # Id of the legal notice for this document - # Marked as open issue if not provided - 'license': 'psa-certified-api-license', - - # Document date, default to build date - 'date': '28/03/2024', - - # Default header file for API definitions - # default to None, and can be set in documentation source -# 'header': 'psa/crypto', - - # Doxygen annotation level of the generated header - # 0 : None (default) - # 1 : Primary API elements - # 2 : Sub-elements of API - parameters, fields, values - 'header_doxygen': 2, - - # Declare a watermark for the PDF output - #'watermark': 'DRAFT', - - # List of optional content that should be included in the build. - # Valid options are: - # 'rationale' : This enables output of ..rationale:: directives - # 'banner' : This enables output of the title page banner - # 'todo' : This enables output of ..todo:: directives - 'include_content': ['banner','rationale'], - - # Optional ordering of return error values - # This list is used to create a standard ordering of return value responses - # throughout the document, irrespective of their ordering in the source text - # Return values that are not in the ordering are sorted above any that are in - # the list and appear in source text order. - - 'error_order': [ - 'PSA_SUCCESS', - 'PSA_ERROR_BAD_STATE', - 'PSA_ERROR_INVALID_HANDLE', - 'PSA_ERROR_NOT_PERMITTED', - 'PSA_ERROR_INVALID_SIGNATURE', - 'PSA_ERROR_ALREADY_EXISTS', - 'PSA_ERROR_INSUFFICIENT_DATA', - 'PSA_ERROR_BUFFER_TOO_SMALL', - 'PSA_ERROR_INVALID_PADDING', - 'PSA_ERROR_INVALID_ARGUMENT', - 'PSA_ERROR_NOT_SUPPORTED', - 'PSA_ERROR_INSUFFICIENT_ENTROPY', - 'PSA_ERROR_INSUFFICIENT_MEMORY', - 'PSA_ERROR_INSUFFICIENT_STORAGE', - 'PSA_ERROR_COMMUNICATION_FAILURE', - 'PSA_ERROR_CORRUPTION_DETECTED', - 'PSA_ERROR_STORAGE_FAILURE', - 'PSA_ERROR_DATA_CORRUPT', - 'PSA_ERROR_DATA_INVALID' - ], - - # Include the C Identifier index. Default to True - 'identifier_index': True, - - # Specify where to add page breaks in main/appendix - # 'none' : no page breaks - # 'appendix' : just before the appendices - # 'chapter' : before every chapter - # Default to 'appendix' - 'page_break': 'chapter', - } - -# absolute or relative path to the psa_spec material from this file -# atg_sphinx_spec_dir = '../atg-sphinx-spec' - -# Set up and run the atg-sphinx-spec configuration - -import os - -atg_sphinx_spec_dir = os.environ.get('ATG_SPHINX_SPEC') or atg_sphinx_spec_dir -exec(compile(open(os.path.join(atg_sphinx_spec_dir,'atg-sphinx-conf.py'), - encoding='utf-8').read(), - 'atg-sphinx-conf.py', 'exec')) diff --git a/doc/ext-pake/index.rst b/doc/ext-pake/index.rst deleted file mode 100644 index 31689078..00000000 --- a/doc/ext-pake/index.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. SPDX-FileCopyrightText: Copyright 2022-2024 Arm Limited and/or its affiliates -.. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license - -.. title:: - - .. banner:: FINAL RELEASE - - This is an extension to the :cite-title:`PSA-CRYPT` specification. - - This is a FINAL release: the proposed changes and interfaces are complete and finalized, and suitable for product development. - - .. abstract:: - - This document is part of the PSA Certified API specifications. It defines an extension to the Crypto API, to introduce support for Password-authenticated key exchange (PAKE) algorithms. - -.. front-matter:: - - about - -.. maintoc:: - - overview/intro - api/pake - api/encodings - -.. appendix:: - - appendix/example_header - appendix/specdef_values - appendix/history diff --git a/doc/ext-pake/overview/intro.rst b/doc/ext-pake/overview/intro.rst deleted file mode 100644 index 93b4457c..00000000 --- a/doc/ext-pake/overview/intro.rst +++ /dev/null @@ -1,181 +0,0 @@ -.. SPDX-FileCopyrightText: Copyright 2022-2024 Arm Limited and/or its affiliates -.. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license - -Introduction -============ - -About Platform Security Architecture ------------------------------------- - -This document is one of a set of resources provided by Arm that can help organizations develop products that meet the security requirements of PSA Certified on Arm-based platforms. The PSA Certified scheme provides a framework and methodology that helps silicon manufacturers, system software providers and OEMs to develop more secure products. Arm resources that support PSA Certified range from threat models, standard architectures that simplify development and increase portability, and open-source partnerships that provide ready-to-use software. You can read more about PSA Certified here at :url:`www.psacertified.org` and find more Arm resources here at :url:`developer.arm.com/platform-security-resources`. - -About the |API| PAKE Extension ------------------------------- - -This document defines an extension to the :cite-title:`PSA-CRYPT` specification, to provide support for :term:`Password-authenticated key exchange` (PAKE) protocols, and specifically for the J-PAKE and SPAKE2+ protocols. - -This extension API is now classed as Final, and it will be integrated into a future version of `[PSA-CRYPT]`. - -This specification must be read and implemented in conjunction with `[PSA-CRYPT]`. All of the conventions, design considerations, and implementation considerations that are described in `[PSA-CRYPT]` apply to this specification. - -.. rationale:: Note - - This version of the document includes *Rationale* commentary that provides background information relating to the API design. This enables the reader to understand the wider context and alternative approaches that have been considered. - - -Objectives for the PAKE Extension ---------------------------------- - -Scheme review -~~~~~~~~~~~~~ - -There are a number of PAKE protocols in circulation, but none of them are used widely in practice, and they are very different in scope and mechanics. -The API proposed for the |API| focuses on schemes that are most likely to be needed by users. A number of factors are used to identify important PAKE algorithms. - -Wide deployment -^^^^^^^^^^^^^^^ - -Considering PAKE schemes with already wide deployment allows users with existing applications to migrate to the |API|. -Currently there is only one scheme with non-negligible success in the industry: Secure Remote Password (SRP). - -Requests -^^^^^^^^ - -Some PAKE schemes have been requested by the community and need to be supported. -Currently, these are: - -* SPAKE2+ --- used in :cite-title:`MATTER` -* J-PAKE (in particular the Elliptic Curve based variant, sometimes known as ECJPAKE) --- used in :cite-title:`THREAD`. - -Standardization -^^^^^^^^^^^^^^^ - -There are PAKE schemes that are being standardized and will be recommended for use in future protocols. -To ensure that the API is future proof, we need to consider these. -The CFRG recommends CPace and OPAQUE for use in IETF protocols. -These are also recommended for use in TLS and IKE in the future. - -Applications -^^^^^^^^^^^^ - -Some of these schemes are used in popular protocols. This information confirms the choices already made and can help to extend the list in future: - -.. list-table:: - :header-rows: 1 - :widths: auto - :align: left - - * - PAKE scheme - - Protocols - * - J-PAKE - - TLS, THREAD v1 - * - SPAKE2+ - - MATTER - * - SRP - - TLS - * - OPAQUE - - TLS, IKE - * - CPace - - TLS, IKE - * - Dragonfly - - WPA3 (Before including the Dragonblood attack should be considered as well.) - * - SPAKE - - Kerberos 5 v1.17 - * - PACE - - IKEv2 - * - AugPAKE - - IKEv2 - - -Scope of the PAKE Extension -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The following PAKE schemes are considered in the |API| design: - -.. list-table:: - :header-rows: 1 - :widths: auto - :align: left - - * - Balanced - - Augmented - * - J-PAKE - - SPAKE2 - - CPace - - SRP - - SPAKE2+ - - OPAQUE - -Scope of this specification -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The current API proposal provides the general interface for PAKE algorithms, and the specific interface for J-PAKE and SPAKE2+. - -Out of scope -^^^^^^^^^^^^ - -PAKE protocols that do not fit into any of the above categories are not taken into consideration in the proposed API. -Such schemes include: - -.. list-table:: - :header-rows: 1 - :class: longtable - :widths: auto - :align: left - - * - PAKE scheme - - Specification - * - AMP - - IEEE 1363.2, ISO/IEC 11770-4 - * - BSPEKE2 - - IEEE 1363.2 - * - PAKZ - - IEEE 1363.2 - * - PPK - - IEEE 1363.2 - * - SPEKE - - IEEE 1363.2 - * - WSPEKE - - IEEE 1363.2 - * - SPEKE - - IEEE 1363.2 - * - PAK - - IEEE 1363.2, X.1035, RFC 5683 - * - EAP-PWD - - RFC 5931 - * - EAP-EKE - - RFC 6124 - * - IKE-PSK - - RFC 6617 - * - PACE for IKEv2 - - RFC 6631 - * - AugPAKE for IKEv2 - - RFC 6628 - * - PAR - - IEEE 1363.2 - * - SESPAKE - - RFC 8133 - * - ITU-T - - X.1035 - * - SPAKE1 - - - * - Dragonfly - - - * - B-SPEKE - - - * - PKEX - - - * - EKE - - - * - Augmented-EKE - - - * - PAK-X - - - * - PAKE - - - -The exception is SPAKE2, because of it is related to SPAKE2+. diff --git a/doc/ext-pake/references b/doc/ext-pake/references deleted file mode 100644 index 9591ce0d..00000000 --- a/doc/ext-pake/references +++ /dev/null @@ -1,49 +0,0 @@ -.. SPDX-FileCopyrightText: Copyright 2023 Arm Limited and/or its affiliates -.. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license - -.. reference:: PSA-CRYPT - :title: PSA Certified Crypto API - :doc_no: IHI 0086 - :url: arm-software.github.io/psa-api/crypto - -.. reference:: MATTER - :title: Matter Specification, Version 1.2 - :author: CSA - :publication: October 2023 - :url: csa-iot.org/all-solutions/matter/ - -.. reference:: RFC8235 - :title: Schnorr Non-interactive Zero-Knowledge Proof - :author: IETF - :publication: September 2017 - :url: tools.ietf.org/html/rfc8235.html - -.. reference:: RFC8236 - :title: J-PAKE: Password-Authenticated Key Exchange by Juggling - :author: IETF - :publication: September 2017 - :url: tools.ietf.org/html/rfc8236.html - -.. reference:: RFC9383 - :title: SPAKE2+, an Augmented Password-Authenticated Key Exchange (PAKE) Protocol - :author: IETF - :publication: September 2023 - :url: tools.ietf.org/html/rfc9383.html - -.. reference:: SEC1 - :title: SEC 1: Elliptic Curve Cryptography - :author: Standards for Efficient Cryptography - :publication: May 2009 - :url: www.secg.org/sec1-v2.pdf - -.. reference:: SPAKE2P-2 - :title: SPAKE2+, an Augmented PAKE (Draft 02) - :author: IETF - :publication: December 2020 - :url: datatracker.ietf.org/doc/draft-bar-cfrg-spake2plus-02 - -.. reference:: THREAD - :title: Thread Specification 1.3.0 - :author: Thread Group - :publication: July 2022 - :url: www.threadgroup.org/ThreadSpec diff --git a/doc/ext-pake/releases b/doc/ext-pake/releases deleted file mode 100644 index 4c1b5468..00000000 --- a/doc/ext-pake/releases +++ /dev/null @@ -1,30 +0,0 @@ -.. SPDX-FileCopyrightText: Copyright 2022, 2024 Arm Limited and/or its affiliates -.. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license - -.. release:: Beta 0 - :date: February 2022 - :confidentiality: Non-confidential - - Initial release of the 1.1 PAKE Extension specification - -.. release:: Beta 1 - :date: October 2022 - :confidentiality: Non-confidential - - Relicensed as open source under CC BY-SA 4.0. - -.. release:: Final - :date: February 2024 - :confidentiality: Non-confidential - - Add support for the SPAKE2+ protocol. - - Rework the API to support augmented PAKE protocols, improve ease of use and implementation. - - API status is now Final/Release. - -.. release:: Final 1 - :date: March 2024 - :confidentiality: Non-confidential - - Clarifications and fixes diff --git a/doc/ext-pake/terms b/doc/ext-pake/terms deleted file mode 100644 index e9598a69..00000000 --- a/doc/ext-pake/terms +++ /dev/null @@ -1,162 +0,0 @@ -.. SPDX-FileCopyrightText: Copyright 2022 Arm Limited and/or its affiliates -.. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license - -.. term:: Algorithm - - A finite sequence of steps to perform a particular operation. - - In this specification, an algorithm is a :term:`cipher` or a related function. - Other texts call this a cryptographic mechanism. - -.. term:: Byte - - In this specification, a unit of storage comprising eight bits, also called an octet. - -.. term:: API - - Application Programming Interface. - -.. term:: Cipher - - An algorithm used for encryption or decryption with a :term:`symmetric` key. - -.. term:: Key agreement - - An algorithm for two or more parties to establish a common secret key. - -.. term:: Key identifier - - A reference to a cryptographic key. Key identifiers in the |API| are 32-bit integers. - -.. term:: Key type - - Key metadata that describes the structure and content of a key. - -.. term:: Key policy - - Key metadata that describes and restricts what a key can be used for. - -.. term:: Lifetime - - Key metadata that describes when a key is destroyed. - -.. scterm:: Implementation defined - - Behavior that is not defined by the architecture, but is defined and documented by individual implementations. - -.. scterm:: Specification defined - - Behavior that is defined by this specification. - -.. term:: Multi-part operation - - An :term:`API` which splits a single cryptographic operation into a sequence of separate steps. - -.. term:: Single-part function - - An :term:`API` that implements the cryptographic operation in a single function call. - -.. term:: Keystore - - A hardware or software component that protects, stores, and manages cryptographic keys. - -.. term:: Nonce - - Used as an input for certain :term:`AEAD` algorithms. - Nonces must not be reused with the same key because this can break a cryptographic protocol. - -.. term:: Authenticated Encryption with Associated Data - :abbr: AEAD - - A type of encryption that - provides confidentiality and authenticity of data using :term:`symmetric` keys. - -.. term:: Initialization vector - :abbr: IV - - An additional input that is not part of the message. It is used to prevent an attacker from making any - correlation between cipher text and plain text. - - This specification uses the term for such initial inputs - in all contexts. For example, the initial counter in CTR mode is called the IV. - -.. term:: Cryptoprocessor - - The component that performs cryptographic operations. - A cryptoprocessor might contain a :term:`keystore` and countermeasures against a range of physical and timing attacks. - -.. term:: Hash - - A cryptographic hash function, or the value returned by such a function. - -.. term:: Message digest - - A :term:`hash` of a message. Used to determine if a message has been tampered. - -.. term:: Signature - - The output of a digital signature scheme that uses an :term:`asymmetric` keypair. Used to establish who produced a message. - -.. term:: Key size - - The size of a key as defined by common conventions for each key type. - For keys that are built from several numbers of strings, this is the size of a particular one of these numbers or strings. - - This specification expresses key sizes in bits. - -.. term:: Key Derivation Function - :abbr: KDF - - Key Derivation Function. An algorithm for deriving keys from secret material. - -.. term:: PSA - - Platform Security Architecture - -.. term:: Message Authentication Code - :abbr: MAC - - A short piece of information used to authenticate a message. - It is created and verified using a :term:`symmetric` key. - -.. term:: HMAC - - A type of :term:`MAC` that uses a cryptographic key with a :term:`hash` function. - -.. term:: Non-extractable key - - A key with a :term:`key policy` that prevents it from being read by ordinary means. - -.. term:: Persistent key - - A key that is stored in protected non-volatile memory. - -.. term:: Salt - - Used as an input for certain algorithms, such as key derivations. - -.. term:: Symmetric - - A type of cryptographic algorithm that uses a single key. A symmetric key can be used with - a block cipher or a stream cipher. - -.. term:: Asymmetric - - See :term:`Public-key cryptography`. - -.. term:: Public-key cryptography - - A type of cryptographic system that uses key pairs. A keypair consists of a (secret) private key - and a public key (not secret). A public key cryptographic algorithm can be used for key distribution - and for digital signatures. - -.. term:: Volatile key - - A key that has a short lifespan and is guaranteed not to exist after a restart of an application instance. - -.. term:: Password-authenticated key exchange - :abbr: PAKE - - An interactive method for two or more parties to establish cryptographic keys based on knowledge of a low entropy secret, such as a password. - - This can provide strong security for communication from a weak password, because the password is not directly communicated as part of the key exchange.