Merge pull request #177 from athoelke/crypto-1.3-integrate-pake

Integrate the PAKE Extension into the Crypto API specification

Author: athoelke

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,

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:

doc/crypto/api/keys/ids.rst

@@ -1,4 +1,4 @@
-.. SPDX-FileCopyrightText: Copyright 2018-2022 Arm Limited and/or its affiliates <[email protected]>
+.. SPDX-FileCopyrightText: Copyright 2018-2022, 2024 Arm Limited and/or its affiliates <[email protected]>
 .. 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
 

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
 

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