Miscellaneous SPAKE2+ support APIs

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

@@ -28,6 +28,7 @@ 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)
@@ -51,6 +52,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/api/pake.rst

@@ -610,6 +610,15 @@ PAKE step types
 
     For information regarding how the group is determined, consult the documentation `PSA_PAKE_PRIMITIVE()`.
 
+.. macro:: PSA_PAKE_STEP_CONFIRM
+    :definition: ((psa_pake_step_t)0x04)
+
+    .. summary::
+        The key confirmation value.
+
+    This value is used during the key confirmation phase of a PAKE protocol. The format of the value depends on the algorithm and cipher suite:
+
+    *   For :code:`PSA_ALG_SPAKE2P`, the format for both input and output at this step is the same as the output of the MAC algorithm specified in the cipher suite.
 
 .. _pake-operation:
 
@@ -851,6 +860,41 @@ Multi-part PAKE operations
     Refer to the documentation of individual PAKE algorithms for more information.
     See :secref:`pake-algorithms`.
 
+.. function:: psa_pake_set_context
+
+    .. summary::
+        Set the context data for a password-authenticated key exchange.
+
+    .. param:: psa_pake_operation_t *operation
+        Active PAKE operation.
+    .. param:: const uint8_t *context
+        The peer's ID to authenticate.
+    .. param:: size_t context_len
+        Size of the ``context`` buffer in bytes.
+
+    .. 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_context()`, `psa_pake_input()`, and `psa_pake_output()` must not have been called yet.
+        *   Calling `psa_pake_set_context()` is invalid with the operation's algorithm.
+        *   The library requires initializing by a call to :code:`psa_crypto_init()`.
+    .. retval:: PSA_ERROR_INVALID_ARGUMENT
+        ``context`` is not valid for the operation's algorithm and cipher suite.
+    .. retval:: PSA_ERROR_NOT_SUPPORTED
+        The value of ``context`` is not supported by the implementation.
+    .. retval:: PSA_ERROR_NOT_SUPPORTED
+    .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY
+    .. retval:: PSA_ERROR_COMMUNICATION_FAILURE
+    .. retval:: PSA_ERROR_CORRUPTION_DETECTED
+
+    Call this function for PAKE algorithms that accept additional context data as part of the protocol setup.
+
+    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

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