Combine psa_pake_set_password_key() with psa_pake_setup()

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

@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText: Copyright 2018-2022 Arm Limited and/or its affiliates <open-source-office@arm.com>
+// SPDX-FileCopyrightText: Copyright 2018-2023 Arm Limited and/or its affiliates <open-source-office@arm.com>
 // SPDX-License-Identifier: Apache-2.0
 
 typedef /* implementation-defined type */ psa_pake_cipher_suite_t;
@@ -53,8 +53,6 @@ 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_password_key(psa_pake_operation_t *operation,
-                                       psa_key_id_t password);
 psa_status_t psa_pake_set_peer(psa_pake_operation_t *operation,
                                const uint8_t *peer_id,
                                size_t peer_id_len);
@@ -64,4 +62,5 @@ 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);

doc/ext-pake/api/pake.rst

@@ -56,7 +56,7 @@ Changes and additions to the Programming API
     :license: Apache-2.0
 
     /* This file contains reference definitions for implementation of the
-     * PSA Certified Crypto API v1.1 PAKE Extension beta.1
+     * PSA Certified Crypto API v1.2 PAKE Extension beta.2
      *
      * These definitions must be embedded in, or included by, psa/crypto.h
      */
@@ -127,17 +127,16 @@ PAKE algorithms
 
             psa_pake_operation_t jpake = PSA_PAKE_OPERATION_INIT;
 
-            psa_pake_setup(&jpake, &cipher_suite);
+            psa_pake_setup(&jpake, pake_key, &cipher_suite);
             psa_pake_set_user(&jpake, ...);
             psa_pake_set_peer(&jpake, ...);
-            psa_pake_set_password_key(&jpake, ...);
 
-        The password is provided as a key.
+        The password is provided as key ``pake_key``, with type :code:`PSA_KEY_TYPE_PASSWORD` or :code:`PSA_KEY_TYPE_PASSWORD_HASH`.
         This can be the password text itself, in an agreed character encoding, or some value derived from the password as required by a higher level protocol.
 
         The key material is used as an array of bytes, which is converted to an integer as described in :cite-title:`SEC1` §2.3.8, before reducing it modulo *q*.
         Here, *q* is the order of the group defined by the cipher-suite primitive.
-        `psa_pake_set_password_key()` will return an error if the result of the conversion and reduction is ``0``.
+        `psa_pake_setup()` will return an error if the result of the conversion and reduction is ``0``.
 
     After setup, the key exchange flow for J-PAKE is as follows:
 
@@ -709,15 +708,22 @@ Multi-part PAKE operations
 .. function:: psa_pake_setup
 
     .. summary::
-        Set the session information for a password-authenticated key exchange.
+        Setup a password-authenticated key exchange.
 
     .. param:: psa_pake_operation_t *operation
         The operation object to set up.
         It must have been initialized as per the documentation for `psa_pake_operation_t` and not yet in use.
+    .. param:: psa_key_id_t password_key
+        Identifier of the key holding the password or a value derived from the password.
+        It must remain valid until the operation terminates.
+        It must be of type :code:`PSA_KEY_TYPE_PASSWORD` or :code:`PSA_KEY_TYPE_PASSWORD_HASH`.
+        It must permit the usage :code:`PSA_KEY_USAGE_DERIVE`.
     .. param:: const psa_pake_cipher_suite_t *cipher_suite
         The cipher suite to use.
         A PAKE cipher suite fully characterizes a PAKE algorithm, including the PAKE algorithm.
 
+        The cipher suite must be compatible with the key type of ``password_key``.
+
     .. return:: psa_status_t
     .. retval:: PSA_SUCCESS
         Success. The operation is now active.
@@ -726,20 +732,30 @@ Multi-part PAKE operations
 
         *   The operation state is not valid: it must be inactive.
         *   The library requires initializing by a call to :code:`psa_crypto_init()`.
+    .. retval:: PSA_ERROR_INVALID_HANDLE
+        ``password_key`` is not a valid key identifier.
+    .. retval:: PSA_ERROR_NOT_PERMITTED
+        ``psssword_key`` does not have the :code:`PSA_KEY_USAGE_DERIVE` flag, or it does not permit the algorithm in ``cipher_suite``.
     .. retval:: PSA_ERROR_INVALID_ARGUMENT
         The following conditions can result in this error:
 
         *   The algorithm in ``cipher_suite`` is not a PAKE algorithm.
         *   The PAKE primitive in ``cipher_suite`` is not compatible with the PAKE algorithm.
         *   The hash algorithm in ``cipher_suite`` is invalid, or not compatible with the PAKE algorithm and primitive.
+        *   The key type for ``password_key`` is not :code:`PSA_KEY_TYPE_PASSWORD` or :code:`PSA_KEY_TYPE_PASSWORD_HASH`.
+        *   ``password_key`` is not compatible with ``cipher_suite``.
     .. retval:: PSA_ERROR_NOT_SUPPORTED
         The following conditions can result in this error:
 
         *   The algorithm in ``cipher_suite`` is not a supported PAKE algorithm.
         *   The PAKE primitive in ``cipher_suite`` is not supported or not compatible with the PAKE algorithm.
         *   The hash algorithm in ``cipher_suite`` is not supported, or not compatible with the PAKE algorithm and primitive.
-    .. retval:: PSA_ERROR_COMMUNICATION_FAILURE
+        *   The key type or key size of ``password_key`` is not supported with ``cipher suite``.
     .. retval:: PSA_ERROR_CORRUPTION_DETECTED
+    .. retval:: PSA_ERROR_COMMUNICATION_FAILURE
+    .. retval:: PSA_ERROR_STORAGE_FAILURE
+    .. retval:: PSA_ERROR_DATA_CORRUPT
+    .. retval:: PSA_ERROR_DATA_INVALID
 
     The sequence of operations to set up a password-authenticated key exchange operation is as follows:
 
@@ -757,7 +773,7 @@ Multi-part PAKE operations
     #.  Depending on the algorithm additional calls to `psa_pake_output()` and `psa_pake_input()` might be necessary.
     #.  Call `psa_pake_get_implicit_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.
+    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:
@@ -772,45 +788,39 @@ Multi-part PAKE operations
     ..
         See :secref:`multi-part-operations`.
 
-.. function:: psa_pake_set_password_key
+.. function:: psa_pake_set_role
 
     .. summary::
-        Set the password for a password-authenticated key exchange using a key.
+        Set the application role for a password-authenticated key exchange.
 
     .. param:: psa_pake_operation_t *operation
         Active PAKE operation.
-    .. param:: psa_key_id_t password
-        Identifier of the key holding the password or a value derived from the password.
-        It must remain valid until the operation terminates.
-        It must be of type :code:`PSA_KEY_TYPE_PASSWORD` or :code:`PSA_KEY_TYPE_PASSWORD_HASH`.
-        It must permit the usage :code:`PSA_KEY_USAGE_DERIVE`.
+    .. param:: psa_pake_role_t role
+        A value of type `psa_pake_role_t` indicating the application role in the PAKE algorithm.
+        See :secref:`pake-roles`.
 
     .. return:: psa_status_t
     .. retval:: PSA_SUCCESS
         Success.
     .. retval:: PSA_ERROR_BAD_STATE
         The following conditions can result in this error:
 
-        *   The operation state is not valid: it must be active, and `psa_pake_set_password_key()`, `psa_pake_input()`, and `psa_pake_output()` must not have been called yet.
+        *   The operation state is not valid: it must be active, and `psa_pake_set_role()`, `psa_pake_input()`, and `psa_pake_output()` must not have been called yet.
         *   The library requires initializing by a call to :code:`psa_crypto_init()`.
-    .. retval:: PSA_ERROR_CORRUPTION_DETECTED
-    .. retval:: PSA_ERROR_INVALID_HANDLE
-        ``password`` is not a valid key identifier.
     .. retval:: PSA_ERROR_INVALID_ARGUMENT
-        The following conditions can result in this error:
-
-        *   The key type for ``password`` is not :code:`PSA_KEY_TYPE_PASSWORD` or :code:`PSA_KEY_TYPE_PASSWORD_HASH`.
-        *   ``password`` is not compatible with the operation's cipher suite.
+        ``role`` is not a valid PAKE role in the operation's algorithm.
     .. retval:: PSA_ERROR_NOT_SUPPORTED
-        The key type or key size of ``password`` is not supported with the operation's cipher suite.
-    .. retval:: PSA_ERROR_NOT_PERMITTED
-        The key does not have the :code:`PSA_KEY_USAGE_DERIVE` flag, or it does not permit the operation's algorithm.
+        ``role`` is not a valid PAKE role, or is not supported for the operation's algorithm.
     .. retval:: PSA_ERROR_COMMUNICATION_FAILURE
-    .. retval:: PSA_ERROR_STORAGE_FAILURE
-    .. retval:: PSA_ERROR_DATA_CORRUPT
-    .. retval:: PSA_ERROR_DATA_INVALID
+    .. retval:: PSA_ERROR_CORRUPTION_DETECTED
 
-    Refer to the documentation of individual PAKE algorithms for constraints on the format and content of valid passwords.
+    Not all PAKE algorithms need to differentiate the communicating participants.
+    For PAKE algorithms that do not require a role to be specified, the application can do either of the following:
+
+    *   Not call `psa_pake_set_role()` on the PAKE operation.
+    *   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
@@ -884,41 +894,6 @@ Multi-part PAKE operations
     Refer to the documentation of individual PAKE algorithms for more information.
     See :secref:`pake-algorithms`.
 
-.. function:: psa_pake_set_role
-
-    .. summary::
-        Set the application role for a password-authenticated key exchange.
-
-    .. param:: psa_pake_operation_t *operation
-        Active PAKE operation.
-    .. param:: psa_pake_role_t role
-        A value of type `psa_pake_role_t` indicating the application role in the PAKE algorithm.
-        See :secref:`pake-roles`.
-
-    .. return:: psa_status_t
-    .. retval:: PSA_SUCCESS
-        Success.
-    .. retval:: PSA_ERROR_BAD_STATE
-        The following conditions can result in this error:
-
-        *   The operation state is not valid: it must be active, and `psa_pake_set_role()`, `psa_pake_input()`, and `psa_pake_output()` must not have been called yet.
-        *   The library requires initializing by a call to :code:`psa_crypto_init()`.
-    .. retval:: PSA_ERROR_INVALID_ARGUMENT
-        ``role`` is not a valid PAKE role in the operation's algorithm.
-    .. retval:: PSA_ERROR_NOT_SUPPORTED
-        ``role`` is not a valid PAKE role, or is not supported for the operation's algorithm.
-    .. retval:: PSA_ERROR_COMMUNICATION_FAILURE
-    .. retval:: PSA_ERROR_CORRUPTION_DETECTED
-
-    Not all PAKE algorithms need to differentiate the communicating participants.
-    For PAKE algorithms that do not require a role to be specified, the application can do either of the following:
-
-    *   Not call `psa_pake_set_role()` on the PAKE operation.
-    *   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_output
 
     .. summary::

doc/ext-pake/appendix/history.rst

@@ -14,6 +14,11 @@ This section provides the detailed changes made between published version of the
 Changes between *Beta 1* and *Beta 2*
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+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.
+
 Clarifications
 ~~~~~~~~~~~~~~
 

doc/ext-pake/conf.py

@@ -22,7 +22,7 @@
     'doc_id': 'AES 0058',
 
     # The short X.Y version. MANDATORY
-    'version': '1.1',
+    'version': '1.2',
     'extension_doc': 'PAKE Extension',
 
     # Arm document quality status, marked as open issue if not provided

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

@@ -8,9 +8,9 @@
     participant User
     participant Peer
 
-    note over User, Peer: Shared information: cipher suite, //UserId//, //PeerId//, and secret //s//
+    note over User, Peer: Shared information: cipher suite, secret //s//, //UserId//, and //PeerId//
 
-    User -> User: ""psa_pake_setup()""\n""psa_pake_set_user()""\n""psa_pake_set_peer()""\n""psa_pake_set_password_key()""
+    User -> User: ""psa_pake_setup()""\n""psa_pake_set_user()""\n""psa_pake_set_peer()""
 
     note over User: Generate //x1// and //x2//\nCompute public keys //g1// and //g2//\nCompute ZKP //(V1, r1)// for //g1// and //(V2, r2)// for //g2//