From 52e69978b7275377ca5b9bbc9bf2ec064f59ac23 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Fri, 3 Nov 2023 16:11:32 +0000 Subject: [PATCH 1/2] Add a PAKE step for input and output of key confirmation --- doc/ext-pake/api.db/psa/crypto-pake.h | 1 + doc/ext-pake/api/pake.rst | 9 +++++++++ doc/ext-pake/appendix/history.rst | 2 ++ 3 files changed, 12 insertions(+) diff --git a/doc/ext-pake/api.db/psa/crypto-pake.h b/doc/ext-pake/api.db/psa/crypto-pake.h index 2a3b235a..74f4c00f 100644 --- a/doc/ext-pake/api.db/psa/crypto-pake.h +++ b/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) diff --git a/doc/ext-pake/api/pake.rst b/doc/ext-pake/api/pake.rst index 79b00881..211e8620 100644 --- a/doc/ext-pake/api/pake.rst +++ b/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: diff --git a/doc/ext-pake/appendix/history.rst b/doc/ext-pake/appendix/history.rst index cffea7b2..a72335f3 100644 --- a/doc/ext-pake/appendix/history.rst +++ b/doc/ext-pake/appendix/history.rst @@ -21,6 +21,8 @@ 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. + Clarifications ~~~~~~~~~~~~~~ From 8f33664b76b980efd001947b6af4019ca0b1e1e9 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Fri, 3 Nov 2023 16:21:28 +0000 Subject: [PATCH 2/2] Add psa_pake_set_context() --- doc/ext-pake/api.db/psa/crypto-pake.h | 3 +++ doc/ext-pake/api/pake.rst | 35 +++++++++++++++++++++++++++ doc/ext-pake/appendix/history.rst | 1 + 3 files changed, 39 insertions(+) diff --git a/doc/ext-pake/api.db/psa/crypto-pake.h b/doc/ext-pake/api.db/psa/crypto-pake.h index 74f4c00f..8cf35615 100644 --- a/doc/ext-pake/api.db/psa/crypto-pake.h +++ b/doc/ext-pake/api.db/psa/crypto-pake.h @@ -52,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); diff --git a/doc/ext-pake/api/pake.rst b/doc/ext-pake/api/pake.rst index 211e8620..21461aa1 100644 --- a/doc/ext-pake/api/pake.rst +++ b/doc/ext-pake/api/pake.rst @@ -860,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:: diff --git a/doc/ext-pake/appendix/history.rst b/doc/ext-pake/appendix/history.rst index a72335f3..98f112e5 100644 --- a/doc/ext-pake/appendix/history.rst +++ b/doc/ext-pake/appendix/history.rst @@ -22,6 +22,7 @@ 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 ~~~~~~~~~~~~~~