From ad7ef6a36d2d3fcc1e0edf983cf926b559063f79 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Mon, 30 Oct 2023 19:40:10 +0000 Subject: [PATCH 01/10] pake: change the key output function * Replace psa_pake_get_implicit_key() with psa_pake_get_shared_key() * Add key confirmation attribute to the PAKE cipher suite --- doc/ext-pake/api.db/psa/crypto-pake.h | 12 +- doc/ext-pake/api/pake.rst | 258 ++++++++++++++++++++++---- doc/ext-pake/appendix/history.rst | 3 + 3 files changed, 236 insertions(+), 37 deletions(-) diff --git a/doc/ext-pake/api.db/psa/crypto-pake.h b/doc/ext-pake/api.db/psa/crypto-pake.h index 8cf35615..f19641b9 100644 --- a/doc/ext-pake/api.db/psa/crypto-pake.h +++ b/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 1 #define PSA_PAKE_INPUT_MAX_SIZE /* implementation-defined value */ #define PSA_PAKE_INPUT_SIZE(alg, primitive, input_step) \ /* implementation-defined value */ @@ -28,20 +29,27 @@ 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_SECRET_KEY_BITS(alg, primitive, hash_alg) \ + /* implementation-defined value */ #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) +#define PSA_PAKE_UNCONFIRMED_KEY 0 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, diff --git a/doc/ext-pake/api/pake.rst b/doc/ext-pake/api/pake.rst index 3f99bbcd..c8ca94b3 100644 --- a/doc/ext-pake/api/pake.rst +++ b/doc/ext-pake/api/pake.rst @@ -105,9 +105,11 @@ PAKE algorithms This is J-PAKE as defined by :RFC-title:`8236`, instantiated with the following parameters: * The group can be either an elliptic curve or defined over a finite field. - * Schnorr NIZK proof as defined by :RFC-title:`8235`, using the same group as the J-PAKE algorithm. + * Schnorr Non-Interactive Zero-Knowledge Proof (NIZKP) as defined by :RFC-title:`8235`, using the same group as the J-PAKE algorithm. * A cryptographic hash function, ``hash_alg``. + J-PAKE does not confirm the shared secret key that results from the key exchange. + To select these parameters and set up the cipher suite, initialize a `psa_pake_cipher_suite_t` object, and call the following functions in any order: .. code-block:: xref @@ -211,18 +213,19 @@ PAKE algorithms // Set r6, the ZKP proof for x4*s psa_pake_input(&jpake, PSA_PAKE_STEP_ZK_PROOF, ...); - #. To use the shared secret, set up a key derivation operation and transfer the computed value: + #. To use the shared secret, extract it as a key. For example, to extract a derivation key for HKDF-SHA-256: .. code-block:: xref - // Set up the KDF - psa_key_derivation_operation_t kdf = PSA_KEY_DERIVATION_OPERATION_INIT; - psa_key_derivation_setup(&kdf, ...); - psa_key_derivation_input_bytes(&kdf, PSA_KEY_DERIVATION_INPUT_CONTEXT, ...); - psa_key_derivation_input_bytes(&kdf, PSA_KEY_DERIVATION_INPUT_LABEL, ...); + // Set up the key attributes + psa_key_attributes_t att = PSA_KEY_ATTRIBUTES_INIT; + psa_key_set_type(&att, PSA_KEY_TYPE_DERIVE); + psa_key_set_usage_flags(&att, PSA_KEY_USAGE_DERIVE); + psa_key_set_algorithm(&att, PSA_ALG_HKDF(PSA_ALG_SHA256)); // Get Ka=Kb=K - psa_pake_get_implicit_key(&jpake, &kdf) + psa_key_id_t shared_key; + psa_pake_get_shared_key(&jpake, &att, &shared_key); For more information about the format of the values which are passed for each step, see :secref:`pake-steps`. @@ -357,9 +360,13 @@ A PAKE primitive is required when constructing a PAKE cipher-suite object, `psa_ PAKE cipher suites ~~~~~~~~~~~~~~~~~~ -A PAKE algorithm uses a specific cryptographic primitive for key establishment, specified using a `PAKE primitive `. PAKE algorithms also require a cryptographic hash algorithm, which is agreed between the participants. +Most PAKE algorithms have parameters that must be specified by the application. These parameters include: + +* The cryptographic primitive used for for key establishment, specified using a `PAKE primitive `. +* A cryptographic hash algorithm. +* Whether the application requires the shared secret before, or after, it is confirmed. -The hash algorithm is encoded into the PAKE algorithm identifier. The `psa_pake_cipher_suite_t` object is used to fully specify a PAKE operation, combining the PAKE and hash algorithm, and the PAKE primitive. +The hash algorithm is encoded into the PAKE algorithm identifier. The `psa_pake_cipher_suite_t` object is used to fully specify a PAKE operation, combining the PAKE protocol with all of the above parameters. A PAKE cipher suite is required when setting up a PAKE operation in `psa_pake_setup()`. @@ -374,11 +381,7 @@ A PAKE cipher suite is required when setting up a PAKE operation in `psa_pake_se * The PAKE algorithm itself. * The hash algorithm, encoded within the PAKE algorithm. * The PAKE primitive, which identifies the prime order group used for the key exchange operation. See :secref:`pake-primitive`. - - .. note:: - Implementations are recommended to define the cipher-suite object as a simple data structure, with fields corresponding to the individual cipher suite attributes. In such an implementation, each function ``psa_pake_cs_set_xxx()`` sets a field and the corresponding function ``psa_pake_cs_get_xxx()`` retrieves the value of the field. - - An implementations can report attribute values that are equivalent to the original one, but have a different encoding. For example, an implementation can use a more compact representation for attributes where many bit-patterns are invalid or not supported, and store all values that it does not support as a special marker value. In such an implementation, after setting an invalid value, the corresponding get function returns an invalid value which might not be the one that was originally stored. + * Whether to confirm the shared secret. This is an implementation-defined type. Applications that make assumptions about the content of this object will result in implementation-specific behavior, and are non-portable. @@ -410,6 +413,33 @@ A PAKE cipher suite is required when setting up a PAKE operation in `psa_pake_se psa_pake_cipher_suite_t cipher_suite; cipher_suite = psa_pake_cipher_suite_init(); + Following initialization, the cipher-suite object contains the following values: + + .. list-table:: + :header-rows: 1 + :widths: auto + :align: left + + * - Attribute + - Value + + * - algorithm + - :code:`PSA_ALG_NONE` --- an invalid algorithm identifier. + * - primitive + - ``0`` --- an invalid PAKE primitive. + * - key confirmation + - `PSA_PAKE_UNCONFIRMED_KEY` --- requesting that the unconfirmed secret key is returned. + + The algorithm and primitive values must be set for all PAKE algorithms, the key confirmation values is only required for some PAKE algorithms. + + .. admonition:: Implementation note + + Implementations are recommended to define the cipher-suite object as a simple data structure, with fields corresponding to the individual cipher suite attributes. + In such an implementation, each function ``psa_pake_cs_set_xxx()`` sets a field and the corresponding function ``psa_pake_cs_get_xxx()`` retrieves the value of the field. + + An implementations can report attribute values that are equivalent to the original one, but have a different encoding. + For example, an implementation can use a more compact representation for attributes where many bit-patterns are invalid or not supported, and store all values that it does not support as a special marker value. + In such an implementation, after setting an invalid value, the corresponding get function returns an invalid value which might not be the one that was originally stored. .. macro:: PSA_PAKE_CIPHER_SUITE_INIT :definition: /* implementation-defined value */ @@ -491,6 +521,62 @@ A PAKE cipher suite is required when setting up a PAKE operation in `psa_pake_se This is a simple accessor function that is not required to validate its inputs. It can be efficiently implemented as a ``static inline`` function or a function-like macro. +.. macro:: PSA_PAKE_UNCONFIRMED_KEY + :definition: 0 + + .. summary:: A key confirmation value that indicates an unconfirmed key in a PAKE cipher suite. + + This key confirmation value will result in the PAKE algorithm terminating prior to confirming that the resulting shared key is identical for both parties. + Some algorithms do not support returning an unconfirmed shared key. + + .. warning:: + + When the shared key is not confirmed as part of the PAKE operation, the application is responsible for mitigating risks that arise from the possible mismatch in the output keys. + +.. macro:: PSA_PAKE_CONFIRMED_KEY + :definition: 1 + + .. summary:: A key confirmation value that indicates an confirmed key in a PAKE cipher suite. + + This key confirmation value will result in the PAKE algorithm exchanging data to verify that the shared key is identical for both parties. + Some algorithms do not include confirmation of the shared key. + +.. function:: psa_pake_cs_get_key_confirmation + + .. summary:: + Retrieve the key confirmation from a PAKE cipher suite. + + .. param:: const psa_pake_cipher_suite_t* cipher_suite + The cipher suite object to query. + + .. return:: uint32_t + A key confirmation value: either `PSA_PAKE_UNCONFIRMED_KEY` or `PSA_PAKE_CONFIRMED_KEY`. + + .. admonition:: Implementation note + + This is a simple accessor function that is not required to validate its inputs. + It can be efficiently implemented as a ``static inline`` function or a function-like macro. + +.. function:: psa_pake_cs_set_key_confirmation + + .. summary:: + Declare the key confirmation from a PAKE cipher suite. + + .. param:: psa_pake_cipher_suite_t* cipher_suite + The cipher suite object to write to. + .. param:: uint32_t key_confirmation + The key confirmation value to write: either `PSA_PAKE_UNCONFIRMED_KEY` or `PSA_PAKE_CONFIRMED_KEY`. + + .. return:: void + + This function overwrites any key confirmation previously set in ``cipher_suite``. + + The documentation of individual PAKE algorithms specifies which key confirmation values are valid for the algorithm. + + .. admonition:: Implementation note + + This is a simple accessor function that is not required to validate its inputs. + It can be efficiently implemented as a ``static inline`` function or a function-like macro. .. _pake-roles: @@ -709,6 +795,7 @@ Multi-part PAKE operations * The algorithm in ``cipher_suite`` is not a PAKE algorithm, or encodes an invalid hash algorithm. * The PAKE primitive in ``cipher_suite`` is not compatible with the PAKE algorithm. + * The key confirmation value in ``cipher_suite`` is 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 @@ -716,6 +803,7 @@ Multi-part PAKE operations * The algorithm in ``cipher_suite`` is not a supported PAKE algorithm, or encodes an unsupported hash algorithm. * The PAKE primitive in ``cipher_suite`` is not supported or not compatible with the PAKE algorithm. + * The key confirmation value in ``cipher_suite`` is not supported, or not compatible, with the PAKE algorithm and primitive. * 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 @@ -737,14 +825,14 @@ Multi-part PAKE operations 1. Call :code:`psa_pake_output(operation, PSA_PAKE_STEP_KEY_SHARE, ...)` to get the key share that needs to be sent to the peer. #. Call :code:`psa_pake_input(operation, PSA_PAKE_STEP_KEY_SHARE, ...)` to provide the key share that was received from the peer. #. 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. + #. Call `psa_pake_get_shared_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, 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: - * A successful call to `psa_pake_get_implicit_key()`. + * A successful call to `psa_pake_get_shared_key()`. * A call to `psa_pake_abort()`. If `psa_pake_setup()` returns an error, the operation object is unchanged. If a subsequent function call with an active operation returns an error, the operation enters an error state. @@ -752,7 +840,7 @@ Multi-part PAKE operations To abandon an active operation, or reset an operation in an error state, call `psa_pake_abort()`. .. - See :secref:`multi-part-operations`. + See :secref:`multi-part-operations`. :issue:`add this when integrated to main specification` .. function:: psa_pake_set_role @@ -1000,30 +1088,83 @@ Multi-part PAKE operations If this function returns an error status, the operation enters an error state and must be aborted by calling `psa_pake_abort()`. -.. function:: psa_pake_get_implicit_key +.. function:: psa_pake_get_shared_key + + .. todo:: + + Decide whether `psa_pake_get_shared_key()` can be called only once (and this terminates the operation), or if the application can sequentially extract multiple keys from the shared secret (much like can be done with a key derivation operation). + + If there are no use cases for multiple key extraction, then we should keep it simple and have a successful key extraction result in terminating the operation. This is the currently described behavior. + + Related: Does all of the shared secret need to be used to construct the output key? .. summary:: - Pass the implicitly confirmed shared secret from a PAKE into a key derivation operation. + Extract the shared secret from the PAKE as a key. .. param:: psa_pake_operation_t *operation Active PAKE operation. - .. param:: psa_key_derivation_operation_t *output - A key derivation operation that is ready for an input step of type :code:`PSA_KEY_DERIVATION_INPUT_SECRET`. + .. param:: const psa_key_attributes_t * attributes + + .. todo:: + Decide where this parameter should go - :code:`psa_key_derivation_output_key()` has this as 1st parameter, before the operation object. + + The attributes for the new key. + This function uses the attributes as follows: + + * The key type is required. It cannot be an asymmetric public key. :issue:`Should we place other restrictions - e.g. forbidding key types that consume a variable amount of input?` + * The key size is always determined from the PAKE shared secret. If the key size in ``attributes`` is nonzero, it must be equal to the size of the shared secret, in bits. + + The bit-size of the shared secret is :code:`PSA_PAKE_SECRET_KEY_BITS(alg, primitive, hash_alg)`, where ``alg``, ``primitive``, and ``hash_alg`` are the PAKE algorithm, primitive, and hash in the operation's cipher suite. + + * The key permitted-algorithm policy is required for keys that will be used for a cryptographic operation. + + .. see :secref:`permitted-algorithms`. + + * The key usage flags define what operations are permitted with the key. + + .. see :secref:`key-usage-flags`. + + * The key lifetime and identifier are required for a persistent key. + + .. note:: + This is an input parameter: it is not updated with the final key attributes. + The final attributes of the new key can be queried by calling :code:`psa_get_key_attributes()` with the key's identifier. + + .. param:: psa_key_id_t * key + On success, an identifier for the newly created key. :code:`PSA_KEY_ID_NULL` on failure. + .. return:: psa_status_t .. retval:: PSA_SUCCESS Success. - Use the ``output`` key derivation operation to continue with derivation of keys or data. + If the key is persistent, the key material and the key's metadata have been saved to persistent storage. .. retval:: PSA_ERROR_BAD_STATE The following conditions can result in this error: - * The state of PAKE operation ``operation`` is not valid: it must be active, with all setup, input, and output steps complete. - * The state of key derivation operation ``output`` is not valid for the :code:`PSA_KEY_DERIVATION_INPUT_SECRET` step. + * The state of PAKE operation ``operation`` is not valid: it must be ready to return the shared secret. + + For an unconfirmed key, this will be when the key-exchange output and input steps are complete, but prior to any key-confirmation output and input steps. + + For a confirmed key, this will be when all key-exchange and key-confirmation output and input steps are complete. * The library requires initializing by a call to :code:`psa_crypto_init()`. - .. retval:: PSA_ERROR_INVALID_ARGUMENT - :code:`PSA_KEY_DERIVATION_INPUT_SECRET` is not compatible with the algorithm in the ``output`` key derivation operation. + .. retval:: PSA_ERROR_ALREADY_EXISTS + This is an attempt to create a persistent key, and there is already a persistent key with the given identifier. + .. retval:: PSA_ERROR_INSUFFICIENT_DATA + There was not enough data to create the desired key. :issue:`Is this the appropriate error for this condition?` .. retval:: PSA_ERROR_NOT_SUPPORTED - Input from a PAKE is not supported by the algorithm in the ``output`` key derivation operation. + The key attributes, as a whole, are not supported for creation from a PAKE secret, either by the implementation in general or in the specified storage location. + .. retval:: PSA_ERROR_INVALID_ARGUMENT + The following conditions can result in this error: + + * The key type is not valid for a PAKE output. + * The key size is nonzero, and is not the size of the shared secret. + * The key lifetime is invalid. + * The key identifier is not valid for the key lifetime. + * The key usage flags include invalid values. + * The key's permitted-usage algorithm is invalid. + * The key attributes, as a whole, are invalid. + .. retval:: PSA_ERROR_NOT_PERMITTED + The implementation does not permit creating a key with the specified attributes due to some implementation-specific policy. .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY .. retval:: PSA_ERROR_COMMUNICATION_FAILURE .. retval:: PSA_ERROR_CORRUPTION_DETECTED @@ -1031,12 +1172,37 @@ Multi-part PAKE operations .. retval:: PSA_ERROR_DATA_CORRUPT .. retval:: PSA_ERROR_DATA_INVALID - At this step in the PAKE operation there is a cryptographic guarantee that only an authenticated participant who used the same password is able to compute the key. - But there is no guarantee that the peer is the participant it claims to be, and was able to compute the same key. + This is the final call in a PAKE operation, which retrieves the shared secret as a key. + This key can be used directly in cryptographic operations such as encryption, but is more typically used as an input to key derivation operations to produce additional cryptographic keys. + + Depending on the key confirmation requested in the cipher suite, `psa_pake_get_shared_key()` must be called either before or after the key-confirmation output and input steps for the PAKE algorithm. + The key confirmation affects the guarantees that can be made about the shared key: + + .. list-table:: + :class: borderless + :widths: 1 4 - In this situation, the authentication is only implicit. - Since the peer is not authenticated, no action should be taken that assumes that the peer is who it claims to be - For example, do not access restricted files on the peer's behalf until an explicit authentication has succeeded. + * - **Unconfirmed key** + - If the cipher suite used to set up the operation requested an unconfirmed key, the application must call `psa_pake_get_shared_key()` after the key-exchange output and input steps are completed. + The PAKE algorithm provides a cryptographic guarantee that only a peer who used the same password, and identity inputs, is able to compute the same key. + However, there is no guarantee that the peer is the participant it claims to be, and was able to compute the same key. + + Since the peer is not authenticated, no action should be taken that assumes that the peer is who it claims to be. + For example, do not access restricted files on the peer's behalf until an explicit authentication has succeeded. + + .. note:: + Some PAKE algorithms do not enable the output of the shared secret until it has been confirmed. + + * - **Confirmed key** + - If the cipher suite used to set up the operation requested a confirmed key, the application must call `psa_pake_get_shared_key()` after the key-exchange and key-confirmation output and input steps are completed. + + Following key confirmation, the PAKE algorithm provides a cryptographic guarantee that the peer used the same password and identity inputs, and has computed the identical shared secret key. + + Since the peer is not authenticated, no action should be taken that assumes that the peer is who it claims to be. + For example, do not access restricted files on the peer's behalf until an explicit authentication has succeeded. + + .. note:: + Some PAKE algorithms do not include any key-confirmation steps. This function can be called after the key exchange phase of the operation has completed. It injects the shared secret output of the PAKE into the provided key derivation operation. @@ -1047,7 +1213,7 @@ Multi-part PAKE operations See :secref:`pake-algorithms`. When this function returns successfully, ``operation`` becomes inactive. - If this function returns an error status, both the ``operation`` and the ``key_derivation`` operations enter an error state and must be aborted by calling `psa_pake_abort()` and :code:`psa_key_derivation_abort()` respectively. + If this function returns an error status, the operation enters an error state and must be aborted by calling `psa_pake_abort()`. .. function:: psa_pake_abort @@ -1071,7 +1237,7 @@ Multi-part PAKE operations This function can be called 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. + In particular, calling `psa_pake_abort()` after the operation has been terminated by a call to `psa_pake_abort()` or `psa_pake_get_shared_key()` is safe and has no effect. Support macros @@ -1156,3 +1322,25 @@ Support macros This macro can be useful when transferring inputs from the peer into the PAKE operation. See also `PSA_PAKE_INPUT_SIZE()`. + +.. macro:: PSA_PAKE_SECRET_KEY_BITS + :definition: /* implementation-defined value */ + + .. summary:: + The size of the secret key output from a PAKE algorithm, in bits. + + .. param:: alg + A PAKE algorithm: a value of type :code:`psa_algorithm_t` such that :code:`PSA_ALG_IS_PAKE(alg)` is true. + .. param:: primitive + A primitive of type `psa_pake_primitive_t` that is compatible with algorithm ``alg``. + .. param:: hash_alg + A hash algorithm: value of type :code:`psa_algorithm_t` such that :code:`PSA_ALG_IS_HASH(alg)` is true. + + .. return:: + The size, in bits, of the shared secret produced by the specified PAKE algorithm, primitive, and associated hash algorithm. + An implementation can return either ``0`` or a correct size for a PAKE algorithm, primitive, and hash algorithm that it recognizes, but does not support. + If the parameters are not valid, the return value is unspecified. + + When extracting the shared secret using `psa_pake_get_shared_key()`, the application is not required to set the key size in the attributes. + + :issue:`Do we actually need this, if the only option is to extract all of the bits into the key?` diff --git a/doc/ext-pake/appendix/history.rst b/doc/ext-pake/appendix/history.rst index d7847982..b2166175 100644 --- a/doc/ext-pake/appendix/history.rst +++ b/doc/ext-pake/appendix/history.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 ~~~~~~~~~~~~~~ From 6478ed577ffc5be8a22b9082feed17d790826a7d Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Tue, 31 Oct 2023 17:19:23 +0000 Subject: [PATCH 02/10] Update J-PAKE flow graphic --- doc/ext-pake/figure/j-pake.pdf | Bin 29446 -> 29304 bytes doc/ext-pake/figure/j-pake.pdf.license | 2 +- doc/ext-pake/figure/j-pake.puml | 4 ++-- doc/ext-pake/figure/j-pake.svg | 2 +- doc/ext-pake/figure/j-pake.svg.license | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/ext-pake/figure/j-pake.pdf b/doc/ext-pake/figure/j-pake.pdf index 96a090f51306715e73b0bfff7d06e75c4d2aff58..ab7a94f50c9298d46f7f1f706b3ce4376075cbf7 100644 GIT binary patch delta 11819 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 ALI3~& diff --git a/doc/ext-pake/figure/j-pake.pdf.license b/doc/ext-pake/figure/j-pake.pdf.license index 70c4b2a6..a2d0bf3f 100644 --- a/doc/ext-pake/figure/j-pake.pdf.license +++ b/doc/ext-pake/figure/j-pake.pdf.license @@ -1,2 +1,2 @@ -SPDX-FileCopyrightText: Copyright 2022 Arm Limited and/or its affiliates +SPDX-FileCopyrightText: Copyright 2022-2023 Arm Limited and/or its affiliates SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license diff --git a/doc/ext-pake/figure/j-pake.puml b/doc/ext-pake/figure/j-pake.puml index 0f3de674..2cea977a 100644 --- a/doc/ext-pake/figure/j-pake.puml +++ b/doc/ext-pake/figure/j-pake.puml @@ -1,4 +1,4 @@ -' SPDX-FileCopyrightText: Copyright 2022 Arm Limited and/or its affiliates +' SPDX-FileCopyrightText: Copyright 2022-2023 Arm Limited and/or its affiliates ' 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 diff --git a/doc/ext-pake/figure/j-pake.svg b/doc/ext-pake/figure/j-pake.svg index ba33637f..1f13635b 100644 --- a/doc/ext-pake/figure/j-pake.svg +++ b/doc/ext-pake/figure/j-pake.svg @@ -1 +1 @@ -UserPeerShared information: cipher suite, secrets,UserId, andPeerIdpsa_pake_setup()psa_pake_set_user()psa_pake_set_peer()Generatex1andx2Compute public keysg1andg2Compute ZKP(V1, r1)forg1and(V2, r2)forg2Generatex3andx4Compute public keysg3andg4Compute ZKPs(V3, r3)forg3and(V4, r4)forg4psa_pake_output()forg1, V1, r1, g2, V2, andr2(g1, V1, r1, g2, V2, r2)(g3, V3, r3, g4, V4, r4)psa_pake_input()forg3, V3, r3, g4, V4, andr4Verify ZKPs and computeAand ZKP(V5, r5)forx2*sVerify ZKPs and computeBand ZKP(V6, r6)forx4*spsa_pake_output()forA, V5, andr5(A, V5, r5)(B, V6, r6)psa_pake_input()forB, V6, andr6Verify ZKP and computeKaVerify ZKP and computeKbIf both sides used the same secrets, thenKa=Kbpsa_pake_get_implicit_key()to extractKa \ No newline at end of file +UserPeerShared information: cipher suite, secrets,UserId, andPeerIdpsa_pake_setup()psa_pake_set_user()psa_pake_set_peer()Generatex1andx2Compute public keysg1andg2Compute ZKP(V1, r1)forg1and(V2, r2)forg2Generatex3andx4Compute public keysg3andg4Compute ZKPs(V3, r3)forg3and(V4, r4)forg4psa_pake_output()forg1, V1, r1, g2, V2, andr2(g1, V1, r1, g2, V2, r2)(g3, V3, r3, g4, V4, r4)psa_pake_input()forg3, V3, r3, g4, V4, andr4Verify ZKPs and computeAand ZKP(V5, r5)forx2*sVerify ZKPs and computeBand ZKP(V6, r6)forx4*spsa_pake_output()forA, V5, andr5(A, V5, r5)(B, V6, r6)psa_pake_input()forB, V6, andr6Verify ZKP and computeKaVerify ZKP and computeKbIf both sides used the same secrets, thenKa=Kbpsa_pake_get_shared_key()to extractKa \ No newline at end of file diff --git a/doc/ext-pake/figure/j-pake.svg.license b/doc/ext-pake/figure/j-pake.svg.license index 70c4b2a6..a2d0bf3f 100644 --- a/doc/ext-pake/figure/j-pake.svg.license +++ b/doc/ext-pake/figure/j-pake.svg.license @@ -1,2 +1,2 @@ -SPDX-FileCopyrightText: Copyright 2022 Arm Limited and/or its affiliates +SPDX-FileCopyrightText: Copyright 2022-2023 Arm Limited and/or its affiliates SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license From bcc76cf45e8c8b9cbf419f762a011955e203b56d Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Tue, 31 Oct 2023 17:31:35 +0000 Subject: [PATCH 03/10] Reversed the definitions for PAKE key confirmation values --- doc/ext-pake/api.db/psa/crypto-pake.h | 4 ++-- doc/ext-pake/api/pake.rst | 33 +++++++++++++++------------ 2 files changed, 20 insertions(+), 17 deletions(-) diff --git a/doc/ext-pake/api.db/psa/crypto-pake.h b/doc/ext-pake/api.db/psa/crypto-pake.h index f19641b9..699ce1ed 100644 --- a/doc/ext-pake/api.db/psa/crypto-pake.h +++ b/doc/ext-pake/api.db/psa/crypto-pake.h @@ -12,7 +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 1 +#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 */ @@ -35,7 +35,7 @@ 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 0 +#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); diff --git a/doc/ext-pake/api/pake.rst b/doc/ext-pake/api/pake.rst index c8ca94b3..15182842 100644 --- a/doc/ext-pake/api/pake.rst +++ b/doc/ext-pake/api/pake.rst @@ -116,9 +116,10 @@ PAKE algorithms psa_pake_cipher_suite_t cipher_suite = PSA_PAKE_CIPHER_SUITE_INIT; - psa_pake_cs_set_algorithm(cipher_suite, PSA_ALG_JPAKE(hash)); - psa_pake_cs_set_primitive(cipher_suite, + psa_pake_cs_set_algorithm(&cipher_suite, PSA_ALG_JPAKE(hash)); + psa_pake_cs_set_primitive(&cipher_suite, PSA_PAKE_PRIMITIVE(type, family, bits)); + psa_pake_cs_set_key_confirmation(&cipher_suite, PSA_PAKE_UNCONFIRMED_KEY); More information on selecting a specific Elliptic curve or Diffie-Hellman field is provided with the `PSA_PAKE_PRIMITIVE_TYPE_ECC` and `PSA_PAKE_PRIMITIVE_TYPE_DH` constants. @@ -417,7 +418,7 @@ A PAKE cipher suite is required when setting up a PAKE operation in `psa_pake_se .. list-table:: :header-rows: 1 - :widths: auto + :widths: 1 4 :align: left * - Attribute @@ -428,7 +429,7 @@ A PAKE cipher suite is required when setting up a PAKE operation in `psa_pake_se * - primitive - ``0`` --- an invalid PAKE primitive. * - key confirmation - - `PSA_PAKE_UNCONFIRMED_KEY` --- requesting that the unconfirmed secret key is returned. + - `PSA_PAKE_CONFIRMED_KEY` --- requesting that the secret key is confirmed before it can be returned. The algorithm and primitive values must be set for all PAKE algorithms, the key confirmation values is only required for some PAKE algorithms. @@ -521,26 +522,28 @@ A PAKE cipher suite is required when setting up a PAKE operation in `psa_pake_se This is a simple accessor function that is not required to validate its inputs. It can be efficiently implemented as a ``static inline`` function or a function-like macro. -.. macro:: PSA_PAKE_UNCONFIRMED_KEY +.. macro:: PSA_PAKE_CONFIRMED_KEY :definition: 0 + .. summary:: A key confirmation value that indicates an confirmed key in a PAKE cipher suite. + + This key confirmation value will result in the PAKE algorithm exchanging data to verify that the shared key is identical for both parties. This is the default key confirmation value in an initialized PAKE cipher suite object. + + Some algorithms do not include confirmation of the shared key. + +.. macro:: PSA_PAKE_UNCONFIRMED_KEY + :definition: 1 + .. summary:: A key confirmation value that indicates an unconfirmed key in a PAKE cipher suite. This key confirmation value will result in the PAKE algorithm terminating prior to confirming that the resulting shared key is identical for both parties. + Some algorithms do not support returning an unconfirmed shared key. .. warning:: When the shared key is not confirmed as part of the PAKE operation, the application is responsible for mitigating risks that arise from the possible mismatch in the output keys. -.. macro:: PSA_PAKE_CONFIRMED_KEY - :definition: 1 - - .. summary:: A key confirmation value that indicates an confirmed key in a PAKE cipher suite. - - This key confirmation value will result in the PAKE algorithm exchanging data to verify that the shared key is identical for both parties. - Some algorithms do not include confirmation of the shared key. - .. function:: psa_pake_cs_get_key_confirmation .. summary:: @@ -550,7 +553,7 @@ A PAKE cipher suite is required when setting up a PAKE operation in `psa_pake_se The cipher suite object to query. .. return:: uint32_t - A key confirmation value: either `PSA_PAKE_UNCONFIRMED_KEY` or `PSA_PAKE_CONFIRMED_KEY`. + A key confirmation value: either `PSA_PAKE_CONFIRMED_KEY` or `PSA_PAKE_UNCONFIRMED_KEY`. .. admonition:: Implementation note @@ -565,7 +568,7 @@ A PAKE cipher suite is required when setting up a PAKE operation in `psa_pake_se .. param:: psa_pake_cipher_suite_t* cipher_suite The cipher suite object to write to. .. param:: uint32_t key_confirmation - The key confirmation value to write: either `PSA_PAKE_UNCONFIRMED_KEY` or `PSA_PAKE_CONFIRMED_KEY`. + The key confirmation value to write: either `PSA_PAKE_CONFIRMED_KEY` or `PSA_PAKE_UNCONFIRMED_KEY`. .. return:: void From 311ae2c2e43852ab9c6f2aaa0de1acee03e8f9fe Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Wed, 1 Nov 2023 10:38:47 +0000 Subject: [PATCH 04/10] Fix typo --- doc/ext-pake/api/pake.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/ext-pake/api/pake.rst b/doc/ext-pake/api/pake.rst index 15182842..ffcf3e75 100644 --- a/doc/ext-pake/api/pake.rst +++ b/doc/ext-pake/api/pake.rst @@ -361,9 +361,9 @@ A PAKE primitive is required when constructing a PAKE cipher-suite object, `psa_ PAKE cipher suites ~~~~~~~~~~~~~~~~~~ -Most PAKE algorithms have parameters that must be specified by the application. These parameters include: +Most PAKE algorithms have parameters that must be specified by the application. These parameters include the following: -* The cryptographic primitive used for for key establishment, specified using a `PAKE primitive `. +* The cryptographic primitive used for key establishment, specified using a `PAKE primitive `. * A cryptographic hash algorithm. * Whether the application requires the shared secret before, or after, it is confirmed. From 79c0d7ca9bb2be8b523c336fbabbd0bcbd5599ae Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Wed, 1 Nov 2023 10:40:22 +0000 Subject: [PATCH 05/10] Tidy up resolved issues. --- doc/ext-pake/api/pake.rst | 6 ------ 1 file changed, 6 deletions(-) diff --git a/doc/ext-pake/api/pake.rst b/doc/ext-pake/api/pake.rst index ffcf3e75..1fe73534 100644 --- a/doc/ext-pake/api/pake.rst +++ b/doc/ext-pake/api/pake.rst @@ -1107,10 +1107,6 @@ Multi-part PAKE operations .. param:: psa_pake_operation_t *operation Active PAKE operation. .. param:: const psa_key_attributes_t * attributes - - .. todo:: - Decide where this parameter should go - :code:`psa_key_derivation_output_key()` has this as 1st parameter, before the operation object. - The attributes for the new key. This function uses the attributes as follows: @@ -1152,8 +1148,6 @@ Multi-part PAKE operations * The library requires initializing by a call to :code:`psa_crypto_init()`. .. retval:: PSA_ERROR_ALREADY_EXISTS This is an attempt to create a persistent key, and there is already a persistent key with the given identifier. - .. retval:: PSA_ERROR_INSUFFICIENT_DATA - There was not enough data to create the desired key. :issue:`Is this the appropriate error for this condition?` .. retval:: PSA_ERROR_NOT_SUPPORTED The key attributes, as a whole, are not supported for creation from a PAKE secret, either by the implementation in general or in the specified storage location. .. retval:: PSA_ERROR_INVALID_ARGUMENT From ad84a2bf8be340b230d694bc4c56b7f54fd6367d Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Mon, 13 Nov 2023 15:21:50 +0000 Subject: [PATCH 06/10] Removed uncertainty about behavior or psa_pake_get_shared_key() * The shared secret is always output as a single key * Removed the input key size, key size is determined by operation * Removed key-size helper macro as unnecessary --- doc/ext-pake/api.db/psa/crypto-pake.h | 2 -- doc/ext-pake/api/pake.rst | 40 ++------------------------- 2 files changed, 3 insertions(+), 39 deletions(-) diff --git a/doc/ext-pake/api.db/psa/crypto-pake.h b/doc/ext-pake/api.db/psa/crypto-pake.h index 699ce1ed..21a84e9c 100644 --- a/doc/ext-pake/api.db/psa/crypto-pake.h +++ b/doc/ext-pake/api.db/psa/crypto-pake.h @@ -29,8 +29,6 @@ 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_SECRET_KEY_BITS(alg, primitive, hash_alg) \ - /* implementation-defined value */ #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) diff --git a/doc/ext-pake/api/pake.rst b/doc/ext-pake/api/pake.rst index 1fe73534..f65f669a 100644 --- a/doc/ext-pake/api/pake.rst +++ b/doc/ext-pake/api/pake.rst @@ -1093,14 +1093,6 @@ Multi-part PAKE operations .. function:: psa_pake_get_shared_key - .. todo:: - - Decide whether `psa_pake_get_shared_key()` can be called only once (and this terminates the operation), or if the application can sequentially extract multiple keys from the shared secret (much like can be done with a key derivation operation). - - If there are no use cases for multiple key extraction, then we should keep it simple and have a successful key extraction result in terminating the operation. This is the currently described behavior. - - Related: Does all of the shared secret need to be used to construct the output key? - .. summary:: Extract the shared secret from the PAKE as a key. @@ -1110,11 +1102,8 @@ Multi-part PAKE operations The attributes for the new key. This function uses the attributes as follows: - * The key type is required. It cannot be an asymmetric public key. :issue:`Should we place other restrictions - e.g. forbidding key types that consume a variable amount of input?` - * The key size is always determined from the PAKE shared secret. If the key size in ``attributes`` is nonzero, it must be equal to the size of the shared secret, in bits. - - The bit-size of the shared secret is :code:`PSA_PAKE_SECRET_KEY_BITS(alg, primitive, hash_alg)`, where ``alg``, ``primitive``, and ``hash_alg`` are the PAKE algorithm, primitive, and hash in the operation's cipher suite. - + * The key type is required. It must be an unstructured key type that can be constructed directly from the PAKE shared secret. For example, :code:`PSA_KEY_TYPE_DERIVE`, :code:`PSA_KEY_TYPE_HMAC`, or :code:`PSA_KEY_TYPE_AES`. + * The key size in ``attributes`` must be zero. The returned key size is always determined from the PAKE shared secret. * The key permitted-algorithm policy is required for keys that will be used for a cryptographic operation. .. see :secref:`permitted-algorithms`. @@ -1128,7 +1117,6 @@ Multi-part PAKE operations .. note:: This is an input parameter: it is not updated with the final key attributes. The final attributes of the new key can be queried by calling :code:`psa_get_key_attributes()` with the key's identifier. - .. param:: psa_key_id_t * key On success, an identifier for the newly created key. :code:`PSA_KEY_ID_NULL` on failure. @@ -1154,7 +1142,7 @@ Multi-part PAKE operations The following conditions can result in this error: * The key type is not valid for a PAKE output. - * The key size is nonzero, and is not the size of the shared secret. + * The key size is nonzero. * The key lifetime is invalid. * The key identifier is not valid for the key lifetime. * The key usage flags include invalid values. @@ -1319,25 +1307,3 @@ Support macros This macro can be useful when transferring inputs from the peer into the PAKE operation. See also `PSA_PAKE_INPUT_SIZE()`. - -.. macro:: PSA_PAKE_SECRET_KEY_BITS - :definition: /* implementation-defined value */ - - .. summary:: - The size of the secret key output from a PAKE algorithm, in bits. - - .. param:: alg - A PAKE algorithm: a value of type :code:`psa_algorithm_t` such that :code:`PSA_ALG_IS_PAKE(alg)` is true. - .. param:: primitive - A primitive of type `psa_pake_primitive_t` that is compatible with algorithm ``alg``. - .. param:: hash_alg - A hash algorithm: value of type :code:`psa_algorithm_t` such that :code:`PSA_ALG_IS_HASH(alg)` is true. - - .. return:: - The size, in bits, of the shared secret produced by the specified PAKE algorithm, primitive, and associated hash algorithm. - An implementation can return either ``0`` or a correct size for a PAKE algorithm, primitive, and hash algorithm that it recognizes, but does not support. - If the parameters are not valid, the return value is unspecified. - - When extracting the shared secret using `psa_pake_get_shared_key()`, the application is not required to set the key size in the attributes. - - :issue:`Do we actually need this, if the only option is to extract all of the bits into the key?` From 91e841bbc4bb34f464dda0af5279b7d7d71310bd Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Mon, 13 Nov 2023 15:22:26 +0000 Subject: [PATCH 07/10] Removed redundant (legacy) paragraph --- doc/ext-pake/api/pake.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/doc/ext-pake/api/pake.rst b/doc/ext-pake/api/pake.rst index f65f669a..ed917ad5 100644 --- a/doc/ext-pake/api/pake.rst +++ b/doc/ext-pake/api/pake.rst @@ -1189,10 +1189,6 @@ Multi-part PAKE operations .. note:: Some PAKE algorithms do not include any key-confirmation steps. - This function can be called after the key exchange phase of the operation has completed. - It injects the shared secret output of the PAKE into the provided key derivation operation. - The input step :code:`PSA_KEY_DERIVATION_INPUT_SECRET` is used to input the shared key material into the key derivation operation. - The exact sequence of calls to perform a password-authenticated key exchange depends on the algorithm in use. Refer to the documentation of individual PAKE algorithms for more information. See :secref:`pake-algorithms`. From cdf041c4853c47cd7de8bfa01531327a4bbdca47 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Tue, 14 Nov 2023 11:53:15 +0000 Subject: [PATCH 08/10] Specify key types output by psa_pake_get_shared_key() * Recognise that not all PAKE algorithms produce a secret that is suitable for use as an encryption key * Encourage the use of PAKE output as a key-derivation key --- doc/ext-pake/api/pake.rst | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/doc/ext-pake/api/pake.rst b/doc/ext-pake/api/pake.rst index ed917ad5..a269c0e6 100644 --- a/doc/ext-pake/api/pake.rst +++ b/doc/ext-pake/api/pake.rst @@ -134,7 +134,11 @@ PAKE algorithms J-PAKE does not assign roles to the participants, so it is not necessary to call `psa_pake_set_role()`. - J-PAKE requires both an application and a peer identity. If the peer identity provided to `psa_pake_set_peer()` does not match the data received from the peer, then the call to `psa_pake_input()` for the `PSA_PAKE_STEP_ZK_PROOF` step will fail with :code:`PSA_ERROR_INVALID_SIGNATURE`. + J-PAKE requires both an application and a peer identity. + If the peer identity provided to `psa_pake_set_peer()` does not match the data received from the peer, then the call to `psa_pake_input()` for the `PSA_PAKE_STEP_ZK_PROOF` step will fail with :code:`PSA_ERROR_INVALID_SIGNATURE`. + + The shared secret that is produced by J-PAKE is not suitable for use as an encryption key. + It must be used as an input to a key derivation operation to produce additional cryptographic keys. The following steps demonstrate the application code for 'User' in :numref:`fig-jpake`. The input and output steps must be carried out in exactly the same sequence as shown. @@ -214,7 +218,7 @@ PAKE algorithms // Set r6, the ZKP proof for x4*s psa_pake_input(&jpake, PSA_PAKE_STEP_ZK_PROOF, ...); - #. To use the shared secret, extract it as a key. For example, to extract a derivation key for HKDF-SHA-256: + #. To use the shared secret, extract it as a key-derivation key. For example, to extract a derivation key for HKDF-SHA-256: .. code-block:: xref @@ -1102,8 +1106,14 @@ Multi-part PAKE operations The attributes for the new key. This function uses the attributes as follows: - * The key type is required. It must be an unstructured key type that can be constructed directly from the PAKE shared secret. For example, :code:`PSA_KEY_TYPE_DERIVE`, :code:`PSA_KEY_TYPE_HMAC`, or :code:`PSA_KEY_TYPE_AES`. - * The key size in ``attributes`` must be zero. The returned key size is always determined from the PAKE shared secret. + * The key type is required. + All PAKE algorithms can output a key of type :code:`PSA_KEY_TYPE_DERIVE` or :code:`PSA_KEY_TYPE_HMAC`. + PAKE algorithms that produce a pseudo-random shared secret, can also output block-cipher key types, for example :code:`PSA_KEY_TYPE_AES`. + + Refer to the documentation of individual PAKE algorithms for more information. + See :secref:`pake-algorithms`. + * The key size in ``attributes`` must be zero. + The returned key size is always determined from the PAKE shared secret. * The key permitted-algorithm policy is required for keys that will be used for a cryptographic operation. .. see :secref:`permitted-algorithms`. @@ -1141,7 +1151,7 @@ Multi-part PAKE operations .. retval:: PSA_ERROR_INVALID_ARGUMENT The following conditions can result in this error: - * The key type is not valid for a PAKE output. + * The key type is not valid for output from this operation's algorithm. * The key size is nonzero. * The key lifetime is invalid. * The key identifier is not valid for the key lifetime. @@ -1158,7 +1168,9 @@ Multi-part PAKE operations .. retval:: PSA_ERROR_DATA_INVALID This is the final call in a PAKE operation, which retrieves the shared secret as a key. - This key can be used directly in cryptographic operations such as encryption, but is more typically used as an input to key derivation operations to produce additional cryptographic keys. + It is recommended that this key is used as an input to a key derivation operation to produce additional cryptographic keys. + For some PAKE algorithms, the shared secret is also suitable for use as a key in cryptographic operations such as encryption. + Refer to the documentation of individual PAKE algorithms for more information, see :secref:`pake-algorithms`. Depending on the key confirmation requested in the cipher suite, `psa_pake_get_shared_key()` must be called either before or after the key-confirmation output and input steps for the PAKE algorithm. The key confirmation affects the guarantees that can be made about the shared key: From afeddf7541c4655132411f1b9e25e55c459f7475 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Tue, 21 Nov 2023 16:22:12 +0000 Subject: [PATCH 09/10] Remove unwanted blank line --- doc/ext-pake/api/pake.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/ext-pake/api/pake.rst b/doc/ext-pake/api/pake.rst index a269c0e6..cbe89584 100644 --- a/doc/ext-pake/api/pake.rst +++ b/doc/ext-pake/api/pake.rst @@ -1109,7 +1109,6 @@ Multi-part PAKE operations * The key type is required. All PAKE algorithms can output a key of type :code:`PSA_KEY_TYPE_DERIVE` or :code:`PSA_KEY_TYPE_HMAC`. PAKE algorithms that produce a pseudo-random shared secret, can also output block-cipher key types, for example :code:`PSA_KEY_TYPE_AES`. - Refer to the documentation of individual PAKE algorithms for more information. See :secref:`pake-algorithms`. * The key size in ``attributes`` must be zero. From 1be189671a4955a630e8ea22fdd8b90f46d72f1e Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Wed, 29 Nov 2023 18:54:35 +0000 Subject: [PATCH 10/10] Correct statement about cipher suite attributes --- doc/ext-pake/api/pake.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/ext-pake/api/pake.rst b/doc/ext-pake/api/pake.rst index cbe89584..99886c7b 100644 --- a/doc/ext-pake/api/pake.rst +++ b/doc/ext-pake/api/pake.rst @@ -435,7 +435,7 @@ A PAKE cipher suite is required when setting up a PAKE operation in `psa_pake_se * - key confirmation - `PSA_PAKE_CONFIRMED_KEY` --- requesting that the secret key is confirmed before it can be returned. - The algorithm and primitive values must be set for all PAKE algorithms, the key confirmation values is only required for some PAKE algorithms. + Valid algorithm, primitive, and key confirmation values must be set when using a PAKE cipher suite. .. admonition:: Implementation note @@ -1304,7 +1304,6 @@ Support macros See also `PSA_PAKE_INPUT_MAX_SIZE` - .. macro:: PSA_PAKE_INPUT_MAX_SIZE :definition: /* implementation-defined value */