From fb993027261841b6d5cd5cc0895ac1d3f5fae337 Mon Sep 17 00:00:00 2001
From: Neil Armstrong <narmstrong@baylibre.com>
Date: Fri, 20 May 2022 10:08:58 +0200
Subject: [PATCH 01/29] Add missing PSA_PAKE_CIPHER_SUITE_INIT

Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
---
 include/psa/crypto_extra.h | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index 76e71bf8c..79a7dc0b3 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -1731,6 +1731,11 @@ psa_status_t psa_pake_get_implicit_key(psa_pake_operation_t *operation,
  */
 #define PSA_PAKE_INPUT_MAX_SIZE 0
 
+/** Returns a suitable initializer for a PAKE cipher suite object of type
+ * psa_pake_cipher_suite_t.
+ */
+#define PSA_PAKE_CIPHER_SUITE_INIT {PSA_ALG_NONE, 0, 0, 0, PSA_ALG_NONE}
+
 struct psa_pake_cipher_suite_s
 {
     psa_algorithm_t algorithm;

From 5ff6a7fa978a03557d0cd89995808ef222dcf7b7 Mon Sep 17 00:00:00 2001
From: Neil Armstrong <narmstrong@baylibre.com>
Date: Fri, 20 May 2022 10:12:01 +0200
Subject: [PATCH 02/29] Add missing psa_pake_cipher_suite_init()

Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
---
 include/psa/crypto_extra.h | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index 79a7dc0b3..a0d6feb6c 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -1153,6 +1153,10 @@ typedef uint32_t psa_pake_primitive_t;
  */
 typedef struct psa_pake_cipher_suite_s psa_pake_cipher_suite_t;
 
+/** Return an initial value for a PAKE cipher suite object.
+ */
+static psa_pake_cipher_suite_t psa_pake_cipher_suite_init(void);
+
 /** Retrieve the PAKE algorithm from a PAKE cipher suite.
  *
  * This function may be declared as `static` (i.e. without external
@@ -1803,6 +1807,12 @@ struct psa_pake_operation_s
     } ctx;
 };
 
+static inline struct psa_pake_cipher_suite_s psa_pake_cipher_suite_init(void)
+{
+    const struct psa_pake_cipher_suite_s v = PSA_PAKE_CIPHER_SUITE_INIT;
+    return(v);
+}
+
 /* This only zeroes out the first byte in the union, the rest is unspecified. */
 #define PSA_PAKE_OPERATION_INIT {0, {0}}
 static inline struct psa_pake_operation_s psa_pake_operation_init(void)

From 0151c55b5629ccba33a613966bcf57eadcd39abd Mon Sep 17 00:00:00 2001
From: Neil Armstrong <narmstrong@baylibre.com>
Date: Fri, 20 May 2022 10:13:53 +0200
Subject: [PATCH 03/29] Add documentation of PSA_PAKE_OPERATION_INIT

Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
---
 include/psa/crypto_extra.h | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index a0d6feb6c..a1096b521 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -1740,6 +1740,11 @@ psa_status_t psa_pake_get_implicit_key(psa_pake_operation_t *operation,
  */
 #define PSA_PAKE_CIPHER_SUITE_INIT {PSA_ALG_NONE, 0, 0, 0, PSA_ALG_NONE}
 
+/** Returns a suitable initializer for a PAKE operation object of type
+ * psa_pake_operation_t.
+ */
+#define PSA_PAKE_OPERATION_INIT {0, {0}}
+
 struct psa_pake_cipher_suite_s
 {
     psa_algorithm_t algorithm;
@@ -1814,7 +1819,6 @@ static inline struct psa_pake_cipher_suite_s psa_pake_cipher_suite_init(void)
 }
 
 /* This only zeroes out the first byte in the union, the rest is unspecified. */
-#define PSA_PAKE_OPERATION_INIT {0, {0}}
 static inline struct psa_pake_operation_s psa_pake_operation_init(void)
 {
     const struct psa_pake_operation_s v = PSA_PAKE_OPERATION_INIT;

From 47e700e7de4ced6c5b16eb853b2b384706b0375d Mon Sep 17 00:00:00 2001
From: Neil Armstrong <narmstrong@baylibre.com>
Date: Fri, 20 May 2022 10:16:41 +0200
Subject: [PATCH 04/29] Pass cipher_suite parameter of psa_pake_setup() by
 const reference

Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
---
 include/psa/crypto_extra.h | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index a1096b521..0244d4a42 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -1344,7 +1344,7 @@ static psa_pake_operation_t psa_pake_operation_init(void);
  *
  * \param[in,out] operation     The operation object to set up. It must have
  *                              been initialized but not set up yet.
- * \param cipher_suite          The cipher suite to use. (A cipher suite fully
+ * \param[in] cipher_suite      The cipher suite to use. (A cipher suite fully
  *                              characterizes a PAKE algorithm and determines
  *                              the algorithm as well.)
  *
@@ -1362,7 +1362,7 @@ static psa_pake_operation_t psa_pake_operation_init(void);
  *         results in this error code.
  */
 psa_status_t psa_pake_setup(psa_pake_operation_t *operation,
-                            psa_pake_cipher_suite_t cipher_suite);
+                            const psa_pake_cipher_suite_t *cipher_suite);
 
 /** Set the password for a password-authenticated key exchange from key ID.
  *
@@ -1818,7 +1818,6 @@ static inline struct psa_pake_cipher_suite_s psa_pake_cipher_suite_init(void)
     return(v);
 }
 
-/* This only zeroes out the first byte in the union, the rest is unspecified. */
 static inline struct psa_pake_operation_s psa_pake_operation_init(void)
 {
     const struct psa_pake_operation_s v = PSA_PAKE_OPERATION_INIT;

From 799106b4414f7da3975edd391ef8850022270aae Mon Sep 17 00:00:00 2001
From: Neil Armstrong <narmstrong@baylibre.com>
Date: Fri, 20 May 2022 10:18:53 +0200
Subject: [PATCH 05/29] Pass input as const reference and fix documentation of
 psa_pake_input()

Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
---
 include/psa/crypto_extra.h | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index 0244d4a42..eccc190be 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -1588,12 +1588,12 @@ psa_status_t psa_pake_output(psa_pake_operation_t *operation,
  *
  * \param[in,out] operation    Active PAKE operation.
  * \param step                 The step for which the input is provided.
- * \param[out] input           Buffer containing the input in the format
+ * \param[in] input            Buffer containing the input in the format
  *                             appropriate for this \p step. Refer to the
  *                             documentation of the individual
  *                             \c PSA_PAKE_STEP_XXX constants for more
  *                             information.
- * \param[out] input_length    Size of the \p input buffer in bytes.
+ * \param input_length         Size of the \p input buffer in bytes.
  *
  * \retval #PSA_SUCCESS
  *         Success.
@@ -1613,7 +1613,7 @@ psa_status_t psa_pake_output(psa_pake_operation_t *operation,
  */
 psa_status_t psa_pake_input(psa_pake_operation_t *operation,
                             psa_pake_step_t step,
-                            uint8_t *input,
+                            const uint8_t *input,
                             size_t input_length);
 
 /** Get implicitly confirmed shared secret from a PAKE.

From 0c8ef93c8e2c64c72eba3062b652227e0d9e41a2 Mon Sep 17 00:00:00 2001
From: Neil Armstrong <narmstrong@baylibre.com>
Date: Fri, 20 May 2022 10:23:51 +0200
Subject: [PATCH 06/29] Add missing psa_pake_abort()

Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
---
 include/psa/crypto_extra.h | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index eccc190be..0db525835 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -1673,6 +1673,31 @@ psa_status_t psa_pake_input(psa_pake_operation_t *operation,
 psa_status_t psa_pake_get_implicit_key(psa_pake_operation_t *operation,
                                        psa_key_derivation_operation_t *output);
 
+/** Abort a PAKE operation.
+ *
+ * Aborting an operation frees all associated resources except for the \c
+ * operation structure itself. Once aborted, the operation object can be reused
+ * for another operation by calling psa_pake_setup() again.
+ *
+ * This function may be called at any time after the operation
+ * object has been initialized as described in #psa_pake_operation_t.
+ *
+ * In particular, calling psa_pake_abort() after the operation has been
+ * terminated by a call to psa_pake_abort() or psa_pake_get_implicit_key()
+ * is safe and has no effect.
+ *
+ * \param[in,out] operation    The operation to abort.
+ *
+ * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
+ */
+psa_status_t psa_pake_abort(psa_pake_operation_t * operation);
+
 /**@}*/
 
 /** A sufficient output buffer size for psa_pake_output().

From ff9cac72e7501c0a193f0d539f9f4b40faf67180 Mon Sep 17 00:00:00 2001
From: Neil Armstrong <narmstrong@baylibre.com>
Date: Fri, 20 May 2022 10:25:15 +0200
Subject: [PATCH 07/29] Add missing psa_pake_cs_get_family()

Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
---
 include/psa/crypto_extra.h | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index 0db525835..53c1b4a2b 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -1224,6 +1224,20 @@ static void psa_pake_cs_set_primitive(
                            psa_pake_primitive_t primitive
                            );
 
+/** Retrieve the PAKE family from a PAKE cipher suite.
+ *
+ * This function may be declared as `static` (i.e. without external
+ * linkage). This function may be provided as a function-like macro,
+ * but in this case it must evaluate its argument exactly once.
+ *
+ * \param[in] cipher_suite     The cipher suite structure to query.
+ *
+ * \return The PAKE family stored in the cipher suite structure.
+ */
+static psa_pake_family_t psa_pake_cs_get_family(
+                           const psa_pake_cipher_suite_t* cipher_suite
+                           );
+
 /** Retrieve the hash algorithm from a PAKE cipher suite.
  *
  * This function may be declared as `static` (i.e. without external
@@ -1811,6 +1825,12 @@ static inline void psa_pake_cs_set_primitive(
     cipher_suite->bits = (uint16_t) (0xFFFF & primitive);
 }
 
+static inline psa_pake_family_t psa_pake_cs_get_family(
+    const psa_pake_cipher_suite_t *cipher_suite)
+{
+    return(cipher_suite->family);
+}
+
 static inline psa_algorithm_t psa_pake_cs_get_hash(
     const psa_pake_cipher_suite_t *cipher_suite)
 {

From d5a4825b84b3516a3478446dfc243839094aa101 Mon Sep 17 00:00:00 2001
From: Neil Armstrong <narmstrong@baylibre.com>
Date: Fri, 20 May 2022 10:26:36 +0200
Subject: [PATCH 08/29] Add missing psa_pake_cs_get_bits()

Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
---
 include/psa/crypto_extra.h | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index 53c1b4a2b..2bb1a0452 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -1238,6 +1238,20 @@ static psa_pake_family_t psa_pake_cs_get_family(
                            const psa_pake_cipher_suite_t* cipher_suite
                            );
 
+/** Retrieve the PAKE primitive bit-size from a PAKE cipher suite.
+ *
+ * This function may be declared as `static` (i.e. without external
+ * linkage). This function may be provided as a function-like macro,
+ * but in this case it must evaluate its argument exactly once.
+ *
+ * \param[in] cipher_suite     The cipher suite structure to query.
+ *
+ * \return The PAKE primitive bit-size stored in the cipher suite structure.
+ */
+static uint16_t psa_pake_cs_get_bits(
+                           const psa_pake_cipher_suite_t* cipher_suite
+                           );
+
 /** Retrieve the hash algorithm from a PAKE cipher suite.
  *
  * This function may be declared as `static` (i.e. without external
@@ -1831,6 +1845,12 @@ static inline psa_pake_family_t psa_pake_cs_get_family(
     return(cipher_suite->family);
 }
 
+static inline uint16_t psa_pake_cs_get_bits(
+    const psa_pake_cipher_suite_t *cipher_suite)
+{
+    return(cipher_suite->bits);
+}
+
 static inline psa_algorithm_t psa_pake_cs_get_hash(
     const psa_pake_cipher_suite_t *cipher_suite)
 {

From cd974d590b11e5e1533c9d6cb030f3086a28d7f2 Mon Sep 17 00:00:00 2001
From: Neil Armstrong <narmstrong@baylibre.com>
Date: Fri, 20 May 2022 10:30:12 +0200
Subject: [PATCH 09/29] Fix return documentation of PSA_PAKE_OUTPUT_SIZE

Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
---
 include/psa/crypto_extra.h | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index 2bb1a0452..67b95048a 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -1743,9 +1743,10 @@ psa_status_t psa_pake_abort(psa_pake_operation_t * operation);
  * \param output_step   A value of type ::psa_pake_step_t that is valid for the
  *                      algorithm \p alg.
  * \return              A sufficient output buffer size for the specified
- *                      output, cipher suite and algorithm. If the cipher suite,
- *                      the output type or PAKE algorithm is not recognized, or
- *                      the parameters are incompatible, return 0.
+ *                      PAKE algorithm, primitive, and output step. If the
+ *                      PAKE algorithm, primitive, or output step is not
+ *                      recognized, or the parameters are incompatible,
+ *                      return 0.
  */
 #define PSA_PAKE_OUTPUT_SIZE(alg, primitive, output_step) 0
 

From 7bc71e9c0447828deadf26f1f646124a6f9884cb Mon Sep 17 00:00:00 2001
From: Neil Armstrong <narmstrong@baylibre.com>
Date: Fri, 20 May 2022 10:36:14 +0200
Subject: [PATCH 10/29] Fix output_size documentation of psa_pake_output()

Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
---
 include/psa/crypto_extra.h | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index 67b95048a..f1cba7b34 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -1572,8 +1572,11 @@ psa_status_t psa_pake_set_side(psa_pake_operation_t *operation,
  *                             \c PSA_PAKE_STEP_XXX constants for more
  *                             information.
  * \param output_size          Size of the \p output buffer in bytes. This must
- *                             be at least #PSA_PAKE_OUTPUT_SIZE(\p alg, \c
- *                             cipher_suite, \p type).
+ *                             be at least #PSA_PAKE_OUTPUT_SIZE(\p alg, \p
+ *                             primitive, \p step) where \p alg and
+ *                             \p primitive are the PAKE algorithm and primitive
+ *                             in the operation's cipher suite, and \p step is
+ *                             the output step.
  *
  * \param[out] output_length   On success, the number of bytes of the returned
  *                             output.

From 16145376974bbac3653530be3448d284edc51564 Mon Sep 17 00:00:00 2001
From: Neil Armstrong <narmstrong@baylibre.com>
Date: Fri, 20 May 2022 10:42:36 +0200
Subject: [PATCH 11/29] Fix password wording in PSA_ALG_JPAKE documentation

Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
---
 include/psa/crypto_extra.h | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index f1cba7b34..ba7468027 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -862,15 +862,15 @@ psa_status_t mbedtls_psa_platform_get_builtin_key(
  * psa_pake_set_password_key(operation, ...);
  * \endcode
  *
- * The password is read as a byte array and must be non-empty. This can be the
- * password itself (in some pre-defined character encoding) or some value
- * derived from the password as mandated by some higher level protocol.
+ * The password is provided as a key. 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 implementation converts this byte array to a number as described in
+ * (The implementation converts the key material to a number as described in
  * Section 2.3.8 of _SEC 1: Elliptic Curve Cryptography_
  * (https://www.secg.org/sec1-v2.pdf), before reducing it modulo \c q. Here
  * \c q is order of the group defined by the primitive set in the cipher suite.
- * The \c psa_pake_set_password_xxx() functions return an error if the result
+ * The \c psa_pake_set_password() functions return an error if the result
  * of the reduction is 0.)
  *
  * The key exchange flow for J-PAKE is as follows:

From 4721a6f33ea1cba78af7c30f1d61098b064b0e87 Mon Sep 17 00:00:00 2001
From: Neil Armstrong <narmstrong@baylibre.com>
Date: Fri, 20 May 2022 10:53:00 +0200
Subject: [PATCH 12/29] Update return documentation of psa_pake_setup()

Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
---
 include/psa/crypto_extra.h | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index ba7468027..7f6d570e0 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -1378,10 +1378,18 @@ static psa_pake_operation_t psa_pake_operation_init(void);
  *
  * \retval #PSA_SUCCESS
  *         Success.
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ *         The algorithm in \p cipher_suite is not a PAKE algorithm, or the
+ *         PAKE primitive in \p cipher_suite is not compatible with the
+ *         PAKE algorithm, or the hash algorithm in \p cipher_suite is invalid
+ *         or not compatible with the PAKE algorithm and primitive.
  * \retval #PSA_ERROR_NOT_SUPPORTED
- *         The \p cipher_suite is not supported or is not valid.
+ *         The algorithm in \p cipher_suite is not a supported PAKE algorithm,
+ *         or the PAKE primitive in \p cipher_suite is not supported or not
+ *         compatible with the PAKE algorithm, or the hash algorithm in
+ *         \p cipher_suite is not supported or not compatible with the PAKE
+ *         algorithm and primitive.
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
- * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
  * \retval #PSA_ERROR_BAD_STATE
  *         The operation state is not valid, or

From 71cae6121d722863cdc78a2714e6463d5f4a09f8 Mon Sep 17 00:00:00 2001
From: Neil Armstrong <narmstrong@baylibre.com>
Date: Fri, 20 May 2022 11:00:49 +0200
Subject: [PATCH 13/29] Update return documentation of
 psa_pake_set_password_key()

Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
---
 include/psa/crypto_extra.h | 21 +++++++++++++++------
 1 file changed, 15 insertions(+), 6 deletions(-)

diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index 7f6d570e0..f9fc0c0dc 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -1422,14 +1422,23 @@ psa_status_t psa_pake_setup(psa_pake_operation_t *operation,
  *
  * \retval #PSA_SUCCESS
  *         Success.
- * \retval #PSA_ERROR_INVALID_ARGUMENT
- *         \p key is not compatible with the algorithm or the cipher suite.
- * \retval #PSA_ERROR_CORRUPTION_DETECTED
  * \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_COMMUNICATION_FAILURE
- * \retval #PSA_ERROR_HARDWARE_FAILURE
- * \retval #PSA_ERROR_STORAGE_FAILURE
+ *         \p password is not a valid key identifier.
  * \retval #PSA_ERROR_NOT_PERMITTED
+ *         The key does not have the #PSA_KEY_USAGE_DERIVE flag, or it does not
+ *         permit the \p operation's algorithm.
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ *         The key type for \p password is not #PSA_KEY_TYPE_PASSWORD or
+ *         #PSA_KEY_TYPE_PASSWORD_HASH, or \p password is not compatible with
+ *         the \p operation's cipher suite.
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ *         The key type or key size of \p password is not supported with the
+ *         \p operation's cipher suite.
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_DATA_CORRUPT
+ * \retval #PSA_ERROR_DATA_INVALID
  * \retval #PSA_ERROR_BAD_STATE
  *         The operation state is not valid (it must have been set up.), or
  *         the library has not been previously initialized by psa_crypto_init().

From 35851682596edfec37ae277b570698b94a532e03 Mon Sep 17 00:00:00 2001
From: Neil Armstrong <narmstrong@baylibre.com>
Date: Fri, 20 May 2022 11:02:37 +0200
Subject: [PATCH 14/29] Update return documentation of psa_pake_set_user()

Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
---
 include/psa/crypto_extra.h | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index f9fc0c0dc..53ac19dbe 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -1472,10 +1472,12 @@ psa_status_t psa_pake_set_password_key(psa_pake_operation_t *operation,
  * \retval #PSA_SUCCESS
  *         Success.
  * \retval #PSA_ERROR_INVALID_ARGUMENT
- *         \p user_id is NULL.
+ *         \p user_id is not valid for the \p operation's algorithm and cipher
+ *         suite.
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ *         The value of \p user_id is not supported by the implementation.
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
- * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
  * \retval #PSA_ERROR_BAD_STATE
  *         The operation state is not valid, or

From 16ff788f9dd45deaf085dc169864b03ff5d90ffd Mon Sep 17 00:00:00 2001
From: Neil Armstrong <narmstrong@baylibre.com>
Date: Fri, 20 May 2022 11:04:20 +0200
Subject: [PATCH 15/29] Update return documentation of psa_pake_set_peer()

Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
---
 include/psa/crypto_extra.h | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index 53ac19dbe..9ce5e55c7 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -1512,13 +1512,13 @@ psa_status_t psa_pake_set_user(psa_pake_operation_t *operation,
  *
  * \retval #PSA_SUCCESS
  *         Success.
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ *         \p user_id is not valid for the \p operation's algorithm and cipher
+ *         suite.
  * \retval #PSA_ERROR_NOT_SUPPORTED
  *         The algorithm doesn't associate a second identity with the session.
- * \retval #PSA_ERROR_INVALID_ARGUMENT
- *         \p user_id is NULL.
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
- * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
  * \retval #PSA_ERROR_BAD_STATE
  *         The operation state is not valid, or the library has not

From 2a6dd9c2a8d3a0f70ee740834450fc30c56d9cb7 Mon Sep 17 00:00:00 2001
From: Neil Armstrong <narmstrong@baylibre.com>
Date: Fri, 20 May 2022 11:17:10 +0200
Subject: [PATCH 16/29] Rename & update documentation of function, types, and
 macros for psa_pake_set_role() and associated

Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
---
 include/psa/crypto_extra.h | 66 ++++++++++++++++++++++----------------
 1 file changed, 38 insertions(+), 28 deletions(-)

diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index 9ce5e55c7..d3aa63695 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -961,12 +961,13 @@ psa_status_t mbedtls_psa_platform_get_builtin_key(
  * @{
  */
 
-/** \brief Encoding of the side of PAKE
+/** \brief Encoding of the application role of PAKE
  *
- * Encodes which side of the algorithm is being executed. For more information
- * see the documentation of individual \c PSA_PAKE_SIDE_XXX constants.
+ * Encodes the application's role in the algorithm is being executed. For more
+ * information see the documentation of individual \c PSA_PAKE_ROLE_XXX
+ * constants.
  */
-typedef uint8_t psa_pake_side_t;
+typedef uint8_t psa_pake_role_t;
 
 /** Encoding of input and output indicators for PAKE.
  *
@@ -999,35 +1000,41 @@ typedef uint8_t psa_pake_family_t;
  */
 typedef uint32_t psa_pake_primitive_t;
 
+/** A value to indicate no role in a PAKE algorithm.
+ * This value can be used in a call to psa_pake_set_role() for symmetric PAKE
+ * algorithms which do not assign roles.
+ */
+#define PSA_PAKE_ROLE_NONE                  ((psa_pake_role_t)0x00)
+
 /** The first peer in a balanced PAKE.
  *
  * Although balanced PAKE algorithms are symmetric, some of them needs an
  * ordering of peers for the transcript calculations. If the algorithm does not
- * need this, both #PSA_PAKE_SIDE_FIRST and #PSA_PAKE_SIDE_SECOND are
+ * need this, both #PSA_PAKE_ROLE_FIRST and #PSA_PAKE_ROLE_SECOND are
  * accepted.
  */
-#define PSA_PAKE_SIDE_FIRST                ((psa_pake_side_t)0x01)
+#define PSA_PAKE_ROLE_FIRST                ((psa_pake_role_t)0x01)
 
 /** The second peer in a balanced PAKE.
  *
  * Although balanced PAKE algorithms are symmetric, some of them needs an
  * ordering of peers for the transcript calculations. If the algorithm does not
- * need this, either #PSA_PAKE_SIDE_FIRST or #PSA_PAKE_SIDE_SECOND are
+ * need this, either #PSA_PAKE_ROLE_FIRST or #PSA_PAKE_ROLE_SECOND are
  * accepted.
  */
-#define PSA_PAKE_SIDE_SECOND                ((psa_pake_side_t)0x02)
+#define PSA_PAKE_ROLE_SECOND                ((psa_pake_role_t)0x02)
 
 /** The client in an augmented PAKE.
  *
  * Augmented PAKE algorithms need to differentiate between client and server.
  */
-#define PSA_PAKE_SIDE_CLIENT                ((psa_pake_side_t)0x11)
+#define PSA_PAKE_ROLE_CLIENT                ((psa_pake_role_t)0x11)
 
 /** The server in an augmented PAKE.
  *
  * Augmented PAKE algorithms need to differentiate between client and server.
  */
-#define PSA_PAKE_SIDE_SERVER                ((psa_pake_side_t)0x12)
+#define PSA_PAKE_ROLE_SERVER                ((psa_pake_role_t)0x12)
 
 /** The PAKE primitive type indicating the use of elliptic curves.
  *
@@ -1530,34 +1537,37 @@ psa_status_t psa_pake_set_peer(psa_pake_operation_t *operation,
                                const uint8_t *peer_id,
                                size_t peer_id_len);
 
-/** Set the side for a password-authenticated key exchange.
+/** Set the application role for a password-authenticated key exchange.
  *
  * Not all PAKE algorithms need to differentiate the communicating entities.
- * It is optional to call this function for PAKEs that don't require a side
- * parameter. For such PAKEs the side parameter is ignored.
+ * It is optional to call this function for PAKEs that don't require a role
+ * to be specified. For such PAKEs the application role parameter is ignored,
+ * or #PSA_PAKE_ROLE_NONE can be passed as \c role.
  *
  * Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX`
  * values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true)
  * for more information.
  *
- * \param[in,out] operation     The operation object to set the side for. It
- *                              must have been set up by psa_pake_setup() and
- *                              not yet in use (neither psa_pake_output() nor
- *                              psa_pake_input() has been called yet). It must
- *                              be on operation for which the side hasn't been
- *                              set (psa_pake_set_side() hasn't been called
- *                              yet).
- * \param side                  A value of type ::psa_pake_side_t signaling the
- *                              side of the algorithm that is being set up. For
- *                              more information see the documentation of
- *                              \c PSA_PAKE_SIDE_XXX constants.
+ * \param[in,out] operation     The operation object to specificy the
+ *                              application's role for. It must have been set up
+ *                              by psa_pake_setup() and not yet in use (neither
+ *                              psa_pake_output() nor psa_pake_input() has been
+ *                              called yet). It must be on operation for which
+ *                              the application's role hasn't been specified
+ *                              (psa_pake_set_role() hasn't been called yet).
+ * \param role                  A value of type ::psa_pake_role_t indicating the
+ *                              application's role in the PAKE the algorithm
+ *                              that is being set up. For more information see
+ *                              the documentation of \c PSA_PAKE_ROLE_XXX
+ *                              constants.
  *
  * \retval #PSA_SUCCESS
  *         Success.
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ *         The \p role is not a valid PAKE role in the \p operation’s algorithm.
  * \retval #PSA_ERROR_NOT_SUPPORTED
- *         The \p side for this algorithm is not supported or is not valid.
+ *         The \p role for this algorithm is not supported or is not valid.
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
- * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
  * \retval #PSA_ERROR_BAD_STATE
  *         The operation state is not valid, or
@@ -1565,8 +1575,8 @@ psa_status_t psa_pake_set_peer(psa_pake_operation_t *operation,
  *         It is implementation-dependent whether a failure to initialize
  *         results in this error code.
  */
-psa_status_t psa_pake_set_side(psa_pake_operation_t *operation,
-                               psa_pake_side_t side);
+psa_status_t psa_pake_set_role(psa_pake_operation_t *operation,
+                               psa_pake_role_t role);
 
 /** Get output for a step of a password-authenticated key exchange.
  *

From 664077e3ae3bdc8046e62320c23171130255ff88 Mon Sep 17 00:00:00 2001
From: Neil Armstrong <narmstrong@baylibre.com>
Date: Fri, 20 May 2022 11:24:41 +0200
Subject: [PATCH 17/29] Update return documentation of psa_pake_output()

Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
---
 include/psa/crypto_extra.h | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index d3aa63695..7c4edf3cb 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -1614,11 +1614,17 @@ psa_status_t psa_pake_set_role(psa_pake_operation_t *operation,
  *         Success.
  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
  *         The size of the \p output buffer is too small.
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ *         \p step is not compatible with the operation's algorithm.
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ *         \p step is not supported with the operation's algorithm.
+ * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
- * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
  * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_DATA_CORRUPT
+ * \retval #PSA_ERROR_DATA_INVALID
  * \retval #PSA_ERROR_BAD_STATE
  *         The operation state is not valid (it must be active, but beyond that
  *         validity is specific to the algorithm), or

From 407b27b5163636f40155da9bc130c1be3bacc354 Mon Sep 17 00:00:00 2001
From: Neil Armstrong <narmstrong@baylibre.com>
Date: Fri, 20 May 2022 11:28:23 +0200
Subject: [PATCH 18/29] Update return documentation of psa_pake_input()

Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
---
 include/psa/crypto_extra.h | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index 7c4edf3cb..fffed3243 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -1663,13 +1663,22 @@ psa_status_t psa_pake_output(psa_pake_operation_t *operation,
  *
  * \retval #PSA_SUCCESS
  *         Success.
+ * \retval #PSA_ERROR_INVALID_SIGNATURE
+ *         The verification fails for a #PSA_PAKE_STEP_ZK_PROOF input step.
  * \retval #PSA_ERROR_INVALID_ARGUMENT
- *         The input is not valid for the algorithm, ciphersuite or \p step.
+ *         \p is not compatible with the \p operation’s algorithm, or the
+ *         \p input is not valid for the \p operation's algorithm, cipher suite
+ *         or \p step.
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ *         \p step p is not supported with the \p operation's algorithm, or the
+ *         \p input is not supported for the \p operation's algorithm, cipher
+ *         suite or \p step.
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
- * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
  * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_DATA_CORRUPT
+ * \retval #PSA_ERROR_DATA_INVALID
  * \retval #PSA_ERROR_BAD_STATE
  *         The operation state is not valid (it must be active, but beyond that
  *         validity is specific to the algorithm), or

From 97d74b8abb9ea8e868ed89f72a5b5227ddea4064 Mon Sep 17 00:00:00 2001
From: Neil Armstrong <narmstrong@baylibre.com>
Date: Fri, 20 May 2022 11:30:31 +0200
Subject: [PATCH 19/29] Update return documentation of
 psa_pake_get_implicit_key()

Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
---
 include/psa/crypto_extra.h | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index fffed3243..a804b0686 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -1727,13 +1727,17 @@ psa_status_t psa_pake_input(psa_pake_operation_t *operation,
  * \retval #PSA_SUCCESS
  *         Success.
  * \retval #PSA_ERROR_INVALID_ARGUMENT
- *         #PSA_KEY_DERIVATION_INPUT_SECRET is not compatible with the output’s
- *         algorithm.
+ *         #PSA_KEY_DERIVATION_INPUT_SECRET is not compatible with the
+ *         algorithm in the \p output key derivation operation.
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ *         Input from a PAKE is not supported by the algorithm in the \p output
+ *         key derivation operation.
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
- * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
  * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_DATA_CORRUPT
+ * \retval #PSA_ERROR_DATA_INVALID
  * \retval #PSA_ERROR_BAD_STATE
  *         The PAKE operation state is not valid (it must be active, but beyond
  *         that validity is specific to the algorithm), or

From 59fa8ee090b8d86014b131205bd01568da581cec Mon Sep 17 00:00:00 2001
From: Neil Armstrong <narmstrong@baylibre.com>
Date: Fri, 20 May 2022 11:31:04 +0200
Subject: [PATCH 20/29] Update return documentation of psa_pake_abort()

Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
---
 include/psa/crypto_extra.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index a804b0686..2f1fefb38 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -1768,6 +1768,7 @@ psa_status_t psa_pake_get_implicit_key(psa_pake_operation_t *operation,
  * \param[in,out] operation    The operation to abort.
  *
  * \retval #PSA_SUCCESS
+ *         Success.
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
  * \retval #PSA_ERROR_BAD_STATE

From 0d24575ad060316b971e10cb062cc82156b1df0f Mon Sep 17 00:00:00 2001
From: Neil Armstrong <narmstrong@baylibre.com>
Date: Fri, 20 May 2022 11:35:40 +0200
Subject: [PATCH 21/29] Clarify BAD_STATE return documentation of
 psa_pake_set_peer()

Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
---
 include/psa/crypto_extra.h | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index 2f1fefb38..26d9d9c06 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -1528,7 +1528,8 @@ psa_status_t psa_pake_set_user(psa_pake_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
  * \retval #PSA_ERROR_BAD_STATE
- *         The operation state is not valid, or the library has not
+ *         Calling psa_pake_set_peer() is invalid with the \p operation's
+ *         algorithm, the operation state is not valid, or the library has not
  *         been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
  *         results in this error code.

From e9b4581b163869e291b24d845d5f139945882ce0 Mon Sep 17 00:00:00 2001
From: Neil Armstrong <narmstrong@baylibre.com>
Date: Fri, 20 May 2022 11:39:09 +0200
Subject: [PATCH 22/29] Clarify BAD_STATE return documentation on bad ordering
 of input and output steps for psa_pake_input() & psa_pake_output()

Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
---
 include/psa/crypto_extra.h | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index 26d9d9c06..3d974c7e1 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -1627,8 +1627,9 @@ psa_status_t psa_pake_set_role(psa_pake_operation_t *operation,
  * \retval #PSA_ERROR_DATA_CORRUPT
  * \retval #PSA_ERROR_DATA_INVALID
  * \retval #PSA_ERROR_BAD_STATE
- *         The operation state is not valid (it must be active, but beyond that
- *         validity is specific to the algorithm), or
+ *         The operation state is not valid (it must be active, and fully set
+ *         up, and this call must conform to the algorithm's requirements
+ *         for ordering of input and output steps), or
  *         the library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
  *         results in this error code.
@@ -1681,8 +1682,9 @@ psa_status_t psa_pake_output(psa_pake_operation_t *operation,
  * \retval #PSA_ERROR_DATA_CORRUPT
  * \retval #PSA_ERROR_DATA_INVALID
  * \retval #PSA_ERROR_BAD_STATE
- *         The operation state is not valid (it must be active, but beyond that
- *         validity is specific to the algorithm), or
+ *         The operation state is not valid (it must be active, and fully set
+ *         up, and this call must conform to the algorithm's requirements
+ *         for ordering of input and output steps), or
  *         the library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
  *         results in this error code.

From 2056ce511191f769bb92ab684266db8781727e73 Mon Sep 17 00:00:00 2001
From: Neil Armstrong <narmstrong@baylibre.com>
Date: Wed, 25 May 2022 11:38:15 +0200
Subject: [PATCH 23/29] Fix PSA_PAKE_OUTPUT_MAX_SIZE/PSA_PAKE_INPUT_MAX_SIZE
 commment about parameters to PSA_PAKE_OUTPUT_SIZE/PSA_PAKE_INPUT_SIZE

Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
---
 include/psa/crypto_extra.h | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index 3d974c7e1..8d55bc1a6 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -1826,21 +1826,21 @@ psa_status_t psa_pake_abort(psa_pake_operation_t * operation);
  */
 #define PSA_PAKE_INPUT_SIZE(alg, primitive, input_step) 0
 
-/** Output buffer size for psa_pake_output() for any of the supported cipher
- * suites and PAKE algorithms.
+/** Output buffer size for psa_pake_output() for any of the supported PAKE
+ * algorithm and primitive suites and output step.
  *
  * This macro must expand to a compile-time constant integer.
  *
- * See also #PSA_PAKE_OUTPUT_SIZE(\p alg, \p cipher_suite, \p output).
+ * See also #PSA_PAKE_OUTPUT_SIZE(\p alg, \p primitive, \p step).
  */
 #define PSA_PAKE_OUTPUT_MAX_SIZE 0
 
-/** Input buffer size for psa_pake_input() for any of the supported cipher
- * suites and PAKE algorithms.
+/** Input buffer size for psa_pake_input() for any of the supported PAKE
+ * algorithm and primitive suites and input step.
  *
  * This macro must expand to a compile-time constant integer.
  *
- * See also #PSA_PAKE_INPUT_SIZE(\p alg, \p cipher_suite, \p input).
+ * See also #PSA_PAKE_INPUT_SIZE(\p alg, \p primitive, \p step).
  */
 #define PSA_PAKE_INPUT_MAX_SIZE 0
 

From eb93a6f1d80a9a01bc6a8b3495d5e7fb769b4538 Mon Sep 17 00:00:00 2001
From: Neil Armstrong <narmstrong@baylibre.com>
Date: Wed, 25 May 2022 11:41:05 +0200
Subject: [PATCH 24/29] Use PSA_ALG_NONE in PSA_PAKE_OPERATION_INIT to init
 psa_algorithm_t

Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
---
 include/psa/crypto_extra.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index 8d55bc1a6..2b4b3416b 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -1852,7 +1852,7 @@ psa_status_t psa_pake_abort(psa_pake_operation_t * operation);
 /** Returns a suitable initializer for a PAKE operation object of type
  * psa_pake_operation_t.
  */
-#define PSA_PAKE_OPERATION_INIT {0, {0}}
+#define PSA_PAKE_OPERATION_INIT {PSA_ALG_NONE, {0}}
 
 struct psa_pake_cipher_suite_s
 {

From 72ab56a1fe3616eba4f5ee1f0b2c32df8196cea8 Mon Sep 17 00:00:00 2001
From: Neil Armstrong <narmstrong@baylibre.com>
Date: Wed, 25 May 2022 11:48:37 +0200
Subject: [PATCH 25/29] Overall PSA PAKE API style issues fixes

Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
---
 include/psa/crypto_extra.h | 128 +++++++++++++++++--------------------
 1 file changed, 58 insertions(+), 70 deletions(-)

diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index 2b4b3416b..04d33a2a8 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -1162,7 +1162,7 @@ typedef struct psa_pake_cipher_suite_s psa_pake_cipher_suite_t;
 
 /** Return an initial value for a PAKE cipher suite object.
  */
-static psa_pake_cipher_suite_t psa_pake_cipher_suite_init(void);
+static psa_pake_cipher_suite_t psa_pake_cipher_suite_init( void );
 
 /** Retrieve the PAKE algorithm from a PAKE cipher suite.
  *
@@ -1175,8 +1175,7 @@ static psa_pake_cipher_suite_t psa_pake_cipher_suite_init(void);
  * \return The PAKE algorithm stored in the cipher suite structure.
  */
 static psa_algorithm_t psa_pake_cs_get_algorithm(
-                           const psa_pake_cipher_suite_t* cipher_suite
-                           );
+                           const psa_pake_cipher_suite_t *cipher_suite );
 
 /** Declare the PAKE algorithm for the cipher suite.
  *
@@ -1194,10 +1193,8 @@ static psa_algorithm_t psa_pake_cs_get_algorithm(
  *                             If this is 0, the PAKE algorithm in
  *                             \p cipher_suite becomes unspecified.
  */
-static void psa_pake_cs_set_algorithm(
-                           psa_pake_cipher_suite_t* cipher_suite,
-                           psa_algorithm_t algorithm
-                           );
+static void psa_pake_cs_set_algorithm( psa_pake_cipher_suite_t *cipher_suite,
+                                       psa_algorithm_t algorithm );
 
 /** Retrieve the primitive from a PAKE cipher suite.
  *
@@ -1210,8 +1207,7 @@ static void psa_pake_cs_set_algorithm(
  * \return The primitive stored in the cipher suite structure.
  */
 static psa_pake_primitive_t psa_pake_cs_get_primitive(
-                           const psa_pake_cipher_suite_t* cipher_suite
-                           );
+                           const psa_pake_cipher_suite_t *cipher_suite );
 
 /** Declare the primitive for a PAKE cipher suite.
  *
@@ -1226,10 +1222,8 @@ static psa_pake_primitive_t psa_pake_cs_get_primitive(
  *                             primitive type in \p cipher_suite becomes
  *                             unspecified.
  */
-static void psa_pake_cs_set_primitive(
-                           psa_pake_cipher_suite_t* cipher_suite,
-                           psa_pake_primitive_t primitive
-                           );
+static void psa_pake_cs_set_primitive( psa_pake_cipher_suite_t *cipher_suite,
+                                       psa_pake_primitive_t primitive );
 
 /** Retrieve the PAKE family from a PAKE cipher suite.
  *
@@ -1242,8 +1236,7 @@ static void psa_pake_cs_set_primitive(
  * \return The PAKE family stored in the cipher suite structure.
  */
 static psa_pake_family_t psa_pake_cs_get_family(
-                           const psa_pake_cipher_suite_t* cipher_suite
-                           );
+                           const psa_pake_cipher_suite_t *cipher_suite );
 
 /** Retrieve the PAKE primitive bit-size from a PAKE cipher suite.
  *
@@ -1256,8 +1249,7 @@ static psa_pake_family_t psa_pake_cs_get_family(
  * \return The PAKE primitive bit-size stored in the cipher suite structure.
  */
 static uint16_t psa_pake_cs_get_bits(
-                           const psa_pake_cipher_suite_t* cipher_suite
-                           );
+                           const psa_pake_cipher_suite_t *cipher_suite );
 
 /** Retrieve the hash algorithm from a PAKE cipher suite.
  *
@@ -1272,8 +1264,7 @@ static uint16_t psa_pake_cs_get_bits(
  *         the hash algorithm is not set.
  */
 static psa_algorithm_t psa_pake_cs_get_hash(
-                           const psa_pake_cipher_suite_t* cipher_suite
-                           );
+                           const psa_pake_cipher_suite_t *cipher_suite );
 
 /** Declare the hash algorithm for a PAKE cipher suite.
  *
@@ -1295,10 +1286,8 @@ static psa_algorithm_t psa_pake_cs_get_hash(
  *                              If this is 0, the hash algorithm in
  *                              \p cipher_suite becomes unspecified.
  */
-static void psa_pake_cs_set_hash(
-                           psa_pake_cipher_suite_t* cipher_suite,
-                           psa_algorithm_t hash
-                           );
+static void psa_pake_cs_set_hash( psa_pake_cipher_suite_t *cipher_suite,
+                                  psa_algorithm_t hash );
 
 /** The type of the state data structure for PAKE operations.
  *
@@ -1332,7 +1321,7 @@ typedef struct psa_pake_operation_s psa_pake_operation_t;
 
 /** Return an initial value for an PAKE operation object.
  */
-static psa_pake_operation_t psa_pake_operation_init(void);
+static psa_pake_operation_t psa_pake_operation_init( void );
 
 /** Set the session information for a password-authenticated key exchange.
  *
@@ -1404,8 +1393,8 @@ static psa_pake_operation_t psa_pake_operation_init(void);
  *         It is implementation-dependent whether a failure to initialize
  *         results in this error code.
  */
-psa_status_t psa_pake_setup(psa_pake_operation_t *operation,
-                            const psa_pake_cipher_suite_t *cipher_suite);
+psa_status_t psa_pake_setup( psa_pake_operation_t *operation,
+                             const psa_pake_cipher_suite_t *cipher_suite );
 
 /** Set the password for a password-authenticated key exchange from key ID.
  *
@@ -1452,8 +1441,8 @@ psa_status_t psa_pake_setup(psa_pake_operation_t *operation,
  *         It is implementation-dependent whether a failure to initialize
  *         results in this error code.
  */
-psa_status_t psa_pake_set_password_key(psa_pake_operation_t *operation,
-                                       mbedtls_svc_key_id_t password);
+psa_status_t psa_pake_set_password_key( psa_pake_operation_t *operation,
+                                        mbedtls_svc_key_id_t password );
 
 /** Set the user ID for a password-authenticated key exchange.
  *
@@ -1492,9 +1481,9 @@ psa_status_t psa_pake_set_password_key(psa_pake_operation_t *operation,
  *         It is implementation-dependent whether a failure to initialize
  *         results in this error code.
  */
-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_set_user( psa_pake_operation_t *operation,
+                                const uint8_t *user_id,
+                                size_t user_id_len );
 
 /** Set the peer ID for a password-authenticated key exchange.
  *
@@ -1534,9 +1523,9 @@ psa_status_t psa_pake_set_user(psa_pake_operation_t *operation,
  *         It is implementation-dependent whether a failure to initialize
  *         results in this error code.
  */
-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_peer( psa_pake_operation_t *operation,
+                                const uint8_t *peer_id,
+                                size_t peer_id_len );
 
 /** Set the application role for a password-authenticated key exchange.
  *
@@ -1576,8 +1565,8 @@ psa_status_t psa_pake_set_peer(psa_pake_operation_t *operation,
  *         It is implementation-dependent whether a failure to initialize
  *         results in this error code.
  */
-psa_status_t psa_pake_set_role(psa_pake_operation_t *operation,
-                               psa_pake_role_t role);
+psa_status_t psa_pake_set_role( psa_pake_operation_t *operation,
+                                psa_pake_role_t role );
 
 /** Get output for a step of a password-authenticated key exchange.
  *
@@ -1634,11 +1623,11 @@ psa_status_t psa_pake_set_role(psa_pake_operation_t *operation,
  *         It is implementation-dependent whether a failure to initialize
  *         results in this error code.
  */
-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_output( psa_pake_operation_t *operation,
+                              psa_pake_step_t step,
+                              uint8_t *output,
+                              size_t output_size,
+                              size_t *output_length );
 
 /** Provide input for a step of a password-authenticated key exchange.
  *
@@ -1689,10 +1678,10 @@ psa_status_t psa_pake_output(psa_pake_operation_t *operation,
  *         It is implementation-dependent whether a failure to initialize
  *         results in this error code.
  */
-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_status_t psa_pake_input( psa_pake_operation_t *operation,
+                             psa_pake_step_t step,
+                             const uint8_t *input,
+                             size_t input_length );
 
 /** Get implicitly confirmed shared secret from a PAKE.
  *
@@ -1752,8 +1741,8 @@ psa_status_t psa_pake_input(psa_pake_operation_t *operation,
  *         It is implementation-dependent whether a failure to initialize
  *         results in this error code.
  */
-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_implicit_key( psa_pake_operation_t *operation,
+                                        psa_key_derivation_operation_t *output );
 
 /** Abort a PAKE operation.
  *
@@ -1779,7 +1768,7 @@ psa_status_t psa_pake_get_implicit_key(psa_pake_operation_t *operation,
  *         It is implementation-dependent whether a failure to initialize
  *         results in this error code.
  */
-psa_status_t psa_pake_abort(psa_pake_operation_t * operation);
+psa_status_t psa_pake_abort( psa_pake_operation_t * operation );
 
 /**@}*/
 
@@ -1864,31 +1853,31 @@ struct psa_pake_cipher_suite_s
 };
 
 static inline psa_algorithm_t psa_pake_cs_get_algorithm(
-    const psa_pake_cipher_suite_t *cipher_suite)
+                        const psa_pake_cipher_suite_t *cipher_suite )
 {
-    return(cipher_suite->algorithm);
+    return( cipher_suite->algorithm );
 }
 
 static inline void psa_pake_cs_set_algorithm(
     psa_pake_cipher_suite_t *cipher_suite,
     psa_algorithm_t algorithm)
 {
-    if(!PSA_ALG_IS_PAKE(algorithm))
+    if( !PSA_ALG_IS_PAKE(algorithm) )
         cipher_suite->algorithm = 0;
     else
         cipher_suite->algorithm = algorithm;
 }
 
 static inline psa_pake_primitive_t psa_pake_cs_get_primitive(
-    const psa_pake_cipher_suite_t *cipher_suite)
+                        const psa_pake_cipher_suite_t *cipher_suite )
 {
-    return(PSA_PAKE_PRIMITIVE(cipher_suite->type, cipher_suite->family,
-                cipher_suite->bits));
+    return( PSA_PAKE_PRIMITIVE(cipher_suite->type, cipher_suite->family,
+                               cipher_suite->bits) );
 }
 
 static inline void psa_pake_cs_set_primitive(
-    psa_pake_cipher_suite_t *cipher_suite,
-    psa_pake_primitive_t primitive)
+                        psa_pake_cipher_suite_t *cipher_suite,
+                        psa_pake_primitive_t primitive )
 {
     cipher_suite->type = (psa_pake_primitive_type_t) (primitive >> 24);
     cipher_suite->family = (psa_pake_family_t) (0xFF & (primitive >> 16));
@@ -1896,28 +1885,27 @@ static inline void psa_pake_cs_set_primitive(
 }
 
 static inline psa_pake_family_t psa_pake_cs_get_family(
-    const psa_pake_cipher_suite_t *cipher_suite)
+                        const psa_pake_cipher_suite_t *cipher_suite )
 {
-    return(cipher_suite->family);
+    return( cipher_suite->family );
 }
 
 static inline uint16_t psa_pake_cs_get_bits(
-    const psa_pake_cipher_suite_t *cipher_suite)
+                        const psa_pake_cipher_suite_t *cipher_suite )
 {
-    return(cipher_suite->bits);
+    return( cipher_suite->bits );
 }
 
 static inline psa_algorithm_t psa_pake_cs_get_hash(
-    const psa_pake_cipher_suite_t *cipher_suite)
+                        const psa_pake_cipher_suite_t *cipher_suite )
 {
-    return(cipher_suite->hash);
+    return( cipher_suite->hash );
 }
 
-static inline void psa_pake_cs_set_hash(
-    psa_pake_cipher_suite_t *cipher_suite,
-    psa_algorithm_t hash)
+static inline void psa_pake_cs_set_hash( psa_pake_cipher_suite_t *cipher_suite,
+                                         psa_algorithm_t hash )
 {
-    if(!PSA_ALG_IS_HASH(hash))
+    if( !PSA_ALG_IS_HASH(hash) )
         cipher_suite->hash = 0;
     else
         cipher_suite->hash = hash;
@@ -1933,16 +1921,16 @@ struct psa_pake_operation_s
     } ctx;
 };
 
-static inline struct psa_pake_cipher_suite_s psa_pake_cipher_suite_init(void)
+static inline struct psa_pake_cipher_suite_s psa_pake_cipher_suite_init( void )
 {
     const struct psa_pake_cipher_suite_s v = PSA_PAKE_CIPHER_SUITE_INIT;
-    return(v);
+    return( v );
 }
 
-static inline struct psa_pake_operation_s psa_pake_operation_init(void)
+static inline struct psa_pake_operation_s psa_pake_operation_init( void )
 {
     const struct psa_pake_operation_s v = PSA_PAKE_OPERATION_INIT;
-    return(v);
+    return( v );
 }
 
 #ifdef __cplusplus

From ef15751f08b577fab425afd3bb183673bae33d6f Mon Sep 17 00:00:00 2001
From: Neil Armstrong <narmstrong@baylibre.com>
Date: Wed, 25 May 2022 11:49:45 +0200
Subject: [PATCH 26/29] PSA PAKE API typos in documentation fixes

Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
---
 include/psa/crypto_extra.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index 04d33a2a8..d7bbeb929 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -870,7 +870,7 @@ psa_status_t mbedtls_psa_platform_get_builtin_key(
  * Section 2.3.8 of _SEC 1: Elliptic Curve Cryptography_
  * (https://www.secg.org/sec1-v2.pdf), before reducing it modulo \c q. Here
  * \c q is order of the group defined by the primitive set in the cipher suite.
- * The \c psa_pake_set_password() functions return an error if the result
+ * The \c psa_pake_set_password() function returns an error if the result
  * of the reduction is 0.)
  *
  * The key exchange flow for J-PAKE is as follows:
@@ -1538,7 +1538,7 @@ psa_status_t psa_pake_set_peer( psa_pake_operation_t *operation,
  * values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true)
  * for more information.
  *
- * \param[in,out] operation     The operation object to specificy the
+ * \param[in,out] operation     The operation object to specify the
  *                              application's role for. It must have been set up
  *                              by psa_pake_setup() and not yet in use (neither
  *                              psa_pake_output() nor psa_pake_input() has been

From 5892aa69e3881b3431ddd20c1fc8c5626309de5a Mon Sep 17 00:00:00 2001
From: Neil Armstrong <narmstrong@baylibre.com>
Date: Fri, 27 May 2022 09:44:47 +0200
Subject: [PATCH 27/29] Fix typo in PSA_ALG_JPAKE documentation

Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
---
 include/psa/crypto_extra.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index d7bbeb929..50ca25e4e 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -870,7 +870,7 @@ psa_status_t mbedtls_psa_platform_get_builtin_key(
  * Section 2.3.8 of _SEC 1: Elliptic Curve Cryptography_
  * (https://www.secg.org/sec1-v2.pdf), before reducing it modulo \c q. Here
  * \c q is order of the group defined by the primitive set in the cipher suite.
- * The \c psa_pake_set_password() function returns an error if the result
+ * The \c psa_pake_set_password_key() function returns an error if the result
  * of the reduction is 0.)
  *
  * The key exchange flow for J-PAKE is as follows:

From 5ed8a0ec73ad31ad67b995ebd9a8d7f8e1063702 Mon Sep 17 00:00:00 2001
From: Neil Armstrong <narmstrong@baylibre.com>
Date: Fri, 27 May 2022 09:47:53 +0200
Subject: [PATCH 28/29] Overall PSA PAKE API style issues fixes

Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
---
 include/psa/crypto_extra.h | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index 50ca25e4e..f6cf7514f 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -1862,7 +1862,7 @@ static inline void psa_pake_cs_set_algorithm(
     psa_pake_cipher_suite_t *cipher_suite,
     psa_algorithm_t algorithm)
 {
-    if( !PSA_ALG_IS_PAKE(algorithm) )
+    if( !PSA_ALG_IS_PAKE( algorithm ) )
         cipher_suite->algorithm = 0;
     else
         cipher_suite->algorithm = algorithm;
@@ -1871,8 +1871,8 @@ static inline void psa_pake_cs_set_algorithm(
 static inline psa_pake_primitive_t psa_pake_cs_get_primitive(
                         const psa_pake_cipher_suite_t *cipher_suite )
 {
-    return( PSA_PAKE_PRIMITIVE(cipher_suite->type, cipher_suite->family,
-                               cipher_suite->bits) );
+    return( PSA_PAKE_PRIMITIVE( cipher_suite->type, cipher_suite->family,
+                                cipher_suite->bits ) );
 }
 
 static inline void psa_pake_cs_set_primitive(
@@ -1905,7 +1905,7 @@ static inline psa_algorithm_t psa_pake_cs_get_hash(
 static inline void psa_pake_cs_set_hash( psa_pake_cipher_suite_t *cipher_suite,
                                          psa_algorithm_t hash )
 {
-    if( !PSA_ALG_IS_HASH(hash) )
+    if( !PSA_ALG_IS_HASH( hash ) )
         cipher_suite->hash = 0;
     else
         cipher_suite->hash = hash;

From ccffab38a307bc78969bc9caa555130b10a13e3e Mon Sep 17 00:00:00 2001
From: Neil Armstrong <narmstrong@baylibre.com>
Date: Mon, 30 May 2022 15:49:21 +0200
Subject: [PATCH 29/29] Remove linkage documentation on PAKE cipher-suite
 helpers

Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
---
 include/psa/crypto_extra.h | 32 --------------------------------
 1 file changed, 32 deletions(-)

diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index f6cf7514f..73da364bc 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -1165,10 +1165,6 @@ typedef struct psa_pake_cipher_suite_s psa_pake_cipher_suite_t;
 static psa_pake_cipher_suite_t psa_pake_cipher_suite_init( void );
 
 /** Retrieve the PAKE algorithm from a PAKE cipher suite.
- *
- * This function may be declared as `static` (i.e. without external
- * linkage). This function may be provided as a function-like macro,
- * but in this case it must evaluate its argument exactly once.
  *
  * \param[in] cipher_suite     The cipher suite structure to query.
  *
@@ -1182,10 +1178,6 @@ static psa_algorithm_t psa_pake_cs_get_algorithm(
  * This function overwrites any PAKE algorithm
  * previously set in \p cipher_suite.
  *
- * This function may be declared as `static` (i.e. without external
- * linkage). This function may be provided as a function-like macro,
- * but in this case it must evaluate each of its arguments exactly once.
- *
  * \param[out] cipher_suite    The cipher suite structure to write to.
  * \param algorithm            The PAKE algorithm to write.
  *                             (`PSA_ALG_XXX` values of type ::psa_algorithm_t
@@ -1197,10 +1189,6 @@ static void psa_pake_cs_set_algorithm( psa_pake_cipher_suite_t *cipher_suite,
                                        psa_algorithm_t algorithm );
 
 /** Retrieve the primitive from a PAKE cipher suite.
- *
- * This function may be declared as `static` (i.e. without external linkage).
- * This function may be provided as a function-like macro, but in this case it
- * must evaluate its argument exactly once.
  *
  * \param[in] cipher_suite     The cipher suite structure to query.
  *
@@ -1213,10 +1201,6 @@ static psa_pake_primitive_t psa_pake_cs_get_primitive(
  *
  * This function overwrites any primitive previously set in \p cipher_suite.
  *
- * This function may be declared as `static` (i.e. without external
- * linkage). This function may be provided as a function-like macro,
- * but in this case it must evaluate each of its arguments exactly once.
- *
  * \param[out] cipher_suite    The cipher suite structure to write to.
  * \param primitive            The primitive to write. If this is 0, the
  *                             primitive type in \p cipher_suite becomes
@@ -1226,10 +1210,6 @@ static void psa_pake_cs_set_primitive( psa_pake_cipher_suite_t *cipher_suite,
                                        psa_pake_primitive_t primitive );
 
 /** Retrieve the PAKE family from a PAKE cipher suite.
- *
- * This function may be declared as `static` (i.e. without external
- * linkage). This function may be provided as a function-like macro,
- * but in this case it must evaluate its argument exactly once.
  *
  * \param[in] cipher_suite     The cipher suite structure to query.
  *
@@ -1239,10 +1219,6 @@ static psa_pake_family_t psa_pake_cs_get_family(
                            const psa_pake_cipher_suite_t *cipher_suite );
 
 /** Retrieve the PAKE primitive bit-size from a PAKE cipher suite.
- *
- * This function may be declared as `static` (i.e. without external
- * linkage). This function may be provided as a function-like macro,
- * but in this case it must evaluate its argument exactly once.
  *
  * \param[in] cipher_suite     The cipher suite structure to query.
  *
@@ -1252,10 +1228,6 @@ static uint16_t psa_pake_cs_get_bits(
                            const psa_pake_cipher_suite_t *cipher_suite );
 
 /** Retrieve the hash algorithm from a PAKE cipher suite.
- *
- * This function may be declared as `static` (i.e. without external
- * linkage). This function may be provided as a function-like macro,
- * but in this case it must evaluate its argument exactly once.
  *
  * \param[in] cipher_suite      The cipher suite structure to query.
  *
@@ -1271,10 +1243,6 @@ static psa_algorithm_t psa_pake_cs_get_hash(
  * This function overwrites any hash algorithm
  * previously set in \p cipher_suite.
  *
- * This function may be declared as `static` (i.e. without external
- * linkage). This function may be provided as a function-like macro,
- * but in this case it must evaluate each of its arguments exactly once.
- *
  * Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX`
  * values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true)
  * for more information.