Merge pull request #114 from athoelke/pake-get-shared-key

Change the PAKE output function to return a key

Author: athoelke

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

@@ -12,6 +12,7 @@ typedef uint8_t psa_pake_step_t;
 #define PSA_ALG_IS_PAKE(alg) /* specification-defined value */
 #define PSA_ALG_JPAKE(hash_alg) /* 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 */
@@ -32,16 +33,21 @@ typedef uint8_t psa_pake_step_t;
 #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_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,

doc/ext-pake/api/pake.rst

@@ -24,6 +24,9 @@ API changes
 *   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`.
+
 Clarifications
 ~~~~~~~~~~~~~~
 

doc/ext-pake/appendix/history.rst

@@ -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.pdf

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