diff --git a/doc/ext-pake/api.db/psa/crypto-pake.h b/doc/ext-pake/api.db/psa/crypto-pake.h index 7e0a3c7e..2a3b235a 100644 --- a/doc/ext-pake/api.db/psa/crypto-pake.h +++ b/doc/ext-pake/api.db/psa/crypto-pake.h @@ -8,8 +8,9 @@ typedef uint32_t psa_pake_primitive_t; typedef uint8_t psa_pake_primitive_type_t; typedef uint8_t psa_pake_role_t; typedef uint8_t psa_pake_step_t; +#define PSA_ALG_IS_JPAKE(alg) /* specification-defined value */ #define PSA_ALG_IS_PAKE(alg) /* specification-defined value */ -#define PSA_ALG_JPAKE ((psa_algorithm_t)0x0a000100) +#define PSA_ALG_JPAKE(hash_alg) /* specification-defined value */ #define PSA_PAKE_CIPHER_SUITE_INIT /* implementation-defined value */ #define PSA_PAKE_INPUT_MAX_SIZE /* implementation-defined value */ #define PSA_PAKE_INPUT_SIZE(alg, primitive, input_step) \ @@ -33,12 +34,9 @@ typedef uint8_t psa_pake_step_t; 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); -psa_pake_primitive_t psa_pake_cs_get_hash(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_hash(psa_pake_cipher_suite_t* cipher_suite, - psa_algorithm_t hash_alg); 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, diff --git a/doc/ext-pake/api/pake.rst b/doc/ext-pake/api/pake.rst index ec1c5bbc..79b00881 100644 --- a/doc/ext-pake/api/pake.rst +++ b/doc/ext-pake/api/pake.rst @@ -39,6 +39,11 @@ The algorithm identifier for PAKE algorithms defined in this specification are e The defined values for PAKE-TYPE are shown in :numref:`table-pake-type`. +The permitted values of HASH-TYPE depend on the specific KDF algorithm. + +.. + The permitted values of HASH-TYPE (see :numref:`table-hash-type`) depend on the specific KDF algorithm. + .. csv-table:: PAKE algorithm sub-type values :name: table-pake-type :header-rows: 1 @@ -46,7 +51,9 @@ The defined values for PAKE-TYPE are shown in :numref:`table-pake-type`. :widths: auto PAKE algorithm, PAKE-TYPE, Algorithm identifier, Algorithm value - J-PAKE, ``0x01``, `PSA_ALG_JPAKE`, ``0x0A000100`` + J-PAKE, ``0x01``, :code:`PSA_ALG_JPAKE(hash)`, ``0x0A0001hh`` :sup:`a` + +a. ``hh`` is the HASH-TYPE for the hash algorithm, ``hash``, used to construct the key derivation algorithm. Changes and additions to the Programming API -------------------------------------------- @@ -81,16 +88,25 @@ PAKE algorithms This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. .. macro:: PSA_ALG_JPAKE - :definition: ((psa_algorithm_t)0x0a000100) + :definition: /* specification-defined value */ .. summary:: - The Password-authenticated key exchange by juggling (J-PAKE) algorithm. + Macro to build the Password-authenticated key exchange by juggling (J-PAKE) algorithm. + + .. param:: hash_alg + A hash algorithm: a value of type :code:`psa_algorithm_t` such that :code:`PSA_ALG_IS_HASH(hash_alg)` is true. + + .. return:: + A J-PAKE algorithm, parameterized by a specific hash. + + Unspecified if ``hash_alg`` is not a supported hash algorithm. + 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. - * A cryptographic hash function. + * A cryptographic hash function, ``hash_alg``. 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: @@ -98,10 +114,9 @@ PAKE algorithms psa_pake_cipher_suite_t cipher_suite = PSA_PAKE_CIPHER_SUITE_INIT; - psa_pake_cs_set_algorithm(cipher_suite, PSA_ALG_JPAKE); + 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_hash(cipher_suite, hash); 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. @@ -344,7 +359,7 @@ 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. -The `psa_pake_cipher_suite_t` object is used to fully specify a PAKE operation, combining the PAKE algorithm, the PAKE primitive, the hash or any other algorithm that parametrises the PAKE in question. +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. A PAKE cipher suite is required when setting up a PAKE operation in `psa_pake_setup()`. @@ -357,8 +372,8 @@ A PAKE cipher suite is required when setting up a PAKE operation in `psa_pake_se This is the object that represents the cipher suite used for a PAKE algorithm. The PAKE cipher suite specifies the PAKE algorithm, and the options selected for that algorithm. The cipher suite includes the following attributes: * 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`. - * The hash algorithm to use in the operation. .. 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. @@ -395,25 +410,6 @@ 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(); - .. Do we need anything like the following? - - .. rubric:: Usage - - A typical sequence to create a key is as follows: - - 1. Create and initialize an attribute object. - #. If the key is persistent, call `psa_set_key_id()`. Also call `psa_set_key_lifetime()` to place the key in a non-default location. - #. Set the key policy with `psa_set_key_usage_flags()` and `psa_set_key_algorithm()`. - #. Set the key type with `psa_set_key_type()`. Skip this step if copying an existing key with `psa_copy_key()`. - #. When generating a random key with `psa_generate_key()` or deriving a key with `psa_key_derivation_output_key()`, set the desired key size with `psa_set_key_bits()`. - #. Call a key creation function: `psa_import_key()`, `psa_generate_key()`, `psa_key_derivation_output_key()` or `psa_copy_key()`. This function reads the attribute object, creates a key with these attributes, and outputs an identifier for the newly created key. - #. Optionally call `psa_reset_key_attributes()`, now that the attribute object is no longer needed. Currently this call is not required as the attributes defined in this specification do not require additional resources beyond the object itself. - - A typical sequence to query a key's attributes is as follows: - - 1. Call `psa_get_key_attributes()`. - #. Call ``psa_get_key_xxx()`` functions to retrieve the required attribute(s). - #. Call `psa_reset_key_attributes()` to free any resources that can be used by the attribute object. .. macro:: PSA_PAKE_CIPHER_SUITE_INIT :definition: /* implementation-defined value */ @@ -495,43 +491,6 @@ 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. -.. function:: psa_pake_cs_get_hash - - .. summary:: - Retrieve the hash algorithm from a PAKE cipher suite. - - .. param:: const psa_pake_cipher_suite_t* cipher_suite - The cipher suite object to query. - - .. return:: psa_pake_primitive_t - The hash algorithm stored in the cipher suite object. - The return value is :code:`PSA_ALG_NONE` if the PAKE is not parametrized by a hash algorithm, or if the hash algorithm is not set. - - .. 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_hash - - .. summary:: - Declare the hash algorithm for a PAKE cipher suite. - - .. param:: psa_pake_cipher_suite_t* cipher_suite - The cipher suite object to write to. - .. param:: psa_algorithm_t hash_alg - The hash algorithm to write: a value of type :code:`psa_algorithm_t` such that :code:`PSA_ALG_IS_HASH(hash_alg)` is true. - If this is :code:`PSA_ALG_NONE`, the hash algorithm in ``cipher_suite`` becomes unspecified. - - .. return:: void - - This function overwrites any hash algorithm previously set in ``cipher_suite``. - - The documentation of individual PAKE algorithms specifies which hash algorithms are compatible, or if no hash algorithm is required. - - .. 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: @@ -739,17 +698,15 @@ Multi-part PAKE operations .. retval:: PSA_ERROR_INVALID_ARGUMENT The following conditions can result in this error: - * The algorithm in ``cipher_suite`` is not a PAKE algorithm. + * 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 hash algorithm in ``cipher_suite`` is invalid, or not compatible with the PAKE algorithm and primitive. * The key type for ``password_key`` is not :code:`PSA_KEY_TYPE_PASSWORD` or :code:`PSA_KEY_TYPE_PASSWORD_HASH`. * ``password_key`` is not compatible with ``cipher_suite``. .. retval:: PSA_ERROR_NOT_SUPPORTED The following conditions can result in this error: - * The algorithm in ``cipher_suite`` is not a supported PAKE algorithm. + * The 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 hash algorithm 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 @@ -1076,6 +1033,18 @@ Multi-part PAKE operations Support macros ~~~~~~~~~~~~~~ +.. macro:: PSA_ALG_IS_JPAKE + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is a J-PAKE algorithm (:code:`PSA_ALG_JPAKE(hash_alg)`). + + .. param:: alg + An algorithm identifier: a value of type :code:`psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is a J-PAKE algorithm, ``0`` otherwise. This macro can return either ``0`` or ``1`` if ``alg`` is not a supported PAKE algorithm identifier. + .. macro:: PSA_PAKE_OUTPUT_SIZE :definition: /* implementation-defined value */ diff --git a/doc/ext-pake/appendix/history.rst b/doc/ext-pake/appendix/history.rst index 8b22b27e..cffea7b2 100644 --- a/doc/ext-pake/appendix/history.rst +++ b/doc/ext-pake/appendix/history.rst @@ -19,6 +19,8 @@ API changes * Combined :code:`psa_pake_set_password_key()` with :code:`psa_pake_setup()`. This aligns the API better with other multi-part operations, and also enables an implementation to identify the key location when setting up the operation. +* 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. + Clarifications ~~~~~~~~~~~~~~ diff --git a/doc/ext-pake/appendix/specdef_values.rst b/doc/ext-pake/appendix/specdef_values.rst index d13eb041..e204e8ad 100644 --- a/doc/ext-pake/appendix/specdef_values.rst +++ b/doc/ext-pake/appendix/specdef_values.rst @@ -15,9 +15,15 @@ The examples here provide correct results for the valid inputs defined by each A .. code-block:: xref + #define PSA_ALG_IS_JPAKE(alg) \ + (((alg) & ~0x000000ff) == 0x0a000100) + #define PSA_ALG_IS_PAKE(alg) \ (((alg) & 0x7f000000) == 0x0a000000) + #define PSA_ALG_JPAKE(hash_alg) \ + ((psa_algorithm_t) (0x0a000100 | ((hash_alg) & 0x000000ff))) + #define PSA_PAKE_PRIMITIVE(pake_type, pake_family, pake_bits) \ ((pake_bits & 0xFFFF) != pake_bits) ? 0 : \ ((psa_pake_primitive_t) (((pake_type) << 24 | \ diff --git a/doc/ext-pake/figure/pake_encoding.json b/doc/ext-pake/figure/pake_encoding.json index 1032c146..6c40cb13 100644 --- a/doc/ext-pake/figure/pake_encoding.json +++ b/doc/ext-pake/figure/pake_encoding.json @@ -1,6 +1,6 @@ { "reg": [ - { "name": "0", "bits": 8 }, + { "name": "HASH-TYPE", "bits": 8 }, { "name": "PAKE-TYPE", "bits": 8 }, { "name": "0", "bits": 6 }, { "name": "0", "bits": 1 }, @@ -15,4 +15,4 @@ "vspace": 52, "hspace": 600 } -} \ No newline at end of file +} diff --git a/doc/ext-pake/figure/pake_encoding.json.license b/doc/ext-pake/figure/pake_encoding.json.license index 70c4b2a6..a2d0bf3f 100644 --- a/doc/ext-pake/figure/pake_encoding.json.license +++ b/doc/ext-pake/figure/pake_encoding.json.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/pake_encoding.pdf b/doc/ext-pake/figure/pake_encoding.pdf index 11f2c480..33add152 100644 Binary files a/doc/ext-pake/figure/pake_encoding.pdf and b/doc/ext-pake/figure/pake_encoding.pdf differ diff --git a/doc/ext-pake/figure/pake_encoding.pdf.license b/doc/ext-pake/figure/pake_encoding.pdf.license index 70c4b2a6..a2d0bf3f 100644 --- a/doc/ext-pake/figure/pake_encoding.pdf.license +++ b/doc/ext-pake/figure/pake_encoding.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/pake_encoding.svg b/doc/ext-pake/figure/pake_encoding.svg index 9ba39b3c..0cfe596b 100644 --- a/doc/ext-pake/figure/pake_encoding.svg +++ b/doc/ext-pake/figure/pake_encoding.svg @@ -1,2 +1,2 @@ -07815162122232430310PAKE-TYPE0000x0A0 \ No newline at end of file +0781516212223243031HASH-TYPEPAKE-TYPE0000x0A0 \ No newline at end of file diff --git a/doc/ext-pake/figure/pake_encoding.svg.license b/doc/ext-pake/figure/pake_encoding.svg.license index 70c4b2a6..a2d0bf3f 100644 --- a/doc/ext-pake/figure/pake_encoding.svg.license +++ b/doc/ext-pake/figure/pake_encoding.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