[DRAFT v1] Define the SPAKE2+ algorithms

doc/ext-pake/api.db/psa/crypto-pake.h

@@ -8,9 +8,26 @@ 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_JPAKE ((psa_algorithm_t)0x0a000100)
+#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 */
@@ -27,22 +44,25 @@ typedef uint8_t psa_pake_step_t;
 #define PSA_PAKE_ROLE_NONE ((psa_pake_role_t)0x00)
 #define PSA_PAKE_ROLE_SECOND ((psa_pake_role_t)0x02)
 #define PSA_PAKE_ROLE_SERVER ((psa_pake_role_t)0x12)
+#define PSA_PAKE_STEP_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);
-psa_pake_primitive_t psa_pake_cs_get_hash(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_hash(psa_pake_cipher_suite_t* cipher_suite,
-                          psa_algorithm_t hash_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_implicit_key(psa_pake_operation_t *operation,
-                                       psa_key_derivation_operation_t *output);
+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,
@@ -53,6 +73,9 @@ psa_status_t psa_pake_output(psa_pake_operation_t *operation,
                              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);

doc/ext-pake/appendix/history.rst

@@ -14,10 +14,36 @@ This section provides the detailed changes made between published version of the
 Changes between *Beta 1* and *Beta 2*
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-API changes
-~~~~~~~~~~~
+Changes to the API
+~~~~~~~~~~~~~~~~~~
+
+*   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. This affects the following APIs:
+
+   -   Removed :code:`psa_pake_set_password_key()`
+   -   Changed :code:`psa_pake_setup()`: it now takes an additional parameter
+
+*   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`. This adds the APIs `PSA_PAKE_CONFIRMED_KEY`, `PSA_PAKE_UNCONFIRMED_KEY`, `psa_pake_cs_set_key_confirmation()`, and `psa_pake_cs_get_key_confirmation()`.
+
+*   Moved the hash algorithm parameter to 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. This affects the following APIs:
+
+   -   Removed :code:`psa_pake_cs_get_hash()` and :code:`psa_pake_cs_set_hash()`
+   -   Changed `PSA_ALG_JPAKE()`: it now requires a ``hash_alg`` parameter
+   -   Added `PSA_ALG_IS_JPAKE()`
+
+*   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.
+
+*   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:
 
-*   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.
+    -   `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
 ~~~~~~~~~~~~~~

doc/ext-pake/appendix/specdef_values.rst

@@ -15,10 +15,49 @@ The examples here provide correct results for the valid inputs defined by each A
 
 .. 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_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)

doc/ext-pake/figure/j-pake.pdf.license

@@ -1,2 +1,2 @@
-SPDX-FileCopyrightText: Copyright 2022 Arm Limited and/or its affiliates <open-source-office@arm.com>
+SPDX-FileCopyrightText: Copyright 2022-2023 Arm Limited and/or its affiliates <open-source-office@arm.com>
 SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license

doc/ext-pake/figure/j-pake.puml

@@ -1,4 +1,4 @@
-' SPDX-FileCopyrightText: Copyright 2022 Arm Limited and/or its affiliates <open-source-office@arm.com>
+' SPDX-FileCopyrightText: Copyright 2022-2023 Arm Limited and/or its affiliates <open-source-office@arm.com>
 ' SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
 
 @startuml
@@ -39,6 +39,6 @@
 
     note over User, Peer: If both sides used the same secret //s//, then //Ka// = //Kb//
 
-    User -> User: ""psa_pake_get_implicit_key()"" to extract //Ka//
+    User -> User: ""psa_pake_get_shared_key()"" to extract //Ka//
 
 @enduml

doc/ext-pake/figure/j-pake.svg.license

@@ -1,2 +1,2 @@
-SPDX-FileCopyrightText: Copyright 2022 Arm Limited and/or its affiliates <open-source-office@arm.com>
+SPDX-FileCopyrightText: Copyright 2022-2023 Arm Limited and/or its affiliates <open-source-office@arm.com>
 SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license

doc/ext-pake/figure/pake_encoding.json

@@ -1,6 +1,6 @@
 {
     "reg": [
-        { "name": "0", "bits": 8 },
+        { "name": "HASH-TYPE", "bits": 8 },
         { "name": "PAKE-TYPE", "bits": 8 },
         { "name": "0", "bits": 6 },
         { "name": "0", "bits": 1 },
@@ -15,4 +15,4 @@
         "vspace": 52,
         "hspace": 600
     }
-}
+}

doc/ext-pake/figure/pake_encoding.json.license

@@ -1,2 +1,2 @@
-SPDX-FileCopyrightText: Copyright 2022 Arm Limited and/or its affiliates <open-source-office@arm.com>
+SPDX-FileCopyrightText: Copyright 2023 Arm Limited and/or its affiliates <open-source-office@arm.com>
 SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license

doc/ext-pake/figure/pake_encoding.pdf.license

@@ -1,2 +1,2 @@
-SPDX-FileCopyrightText: Copyright 2022 Arm Limited and/or its affiliates <open-source-office@arm.com>
+SPDX-FileCopyrightText: Copyright 2023 Arm Limited and/or its affiliates <open-source-office@arm.com>
 SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license

doc/ext-pake/figure/pake_encoding.svg.license

@@ -1,2 +1,2 @@
-SPDX-FileCopyrightText: Copyright 2022 Arm Limited and/or its affiliates <open-source-office@arm.com>
+SPDX-FileCopyrightText: Copyright 2023 Arm Limited and/or its affiliates <open-source-office@arm.com>
 SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license

doc/ext-pake/figure/spake2p_key.json

@@ -0,0 +1,18 @@
+{
+    "reg": [
+        { "name": "P", "bits": 1 },
+        { "name": "ECC-FAMILY", "bits": 7 },
+        { "name": "4", "bits": 4 },
+        { "name": "PAIR", "bits": 2 },
+        { "name": "1", "bits": 1 },
+        { "name": "0", "bits": 1 }
+    ],
+    "options": {
+        "lanes": 1,
+        "fontfamily": "lato",
+        "fontsize": 11,
+        "bits": 16,
+        "vspace": 52,
+        "hspace": 300
+    }
+}