Move PAKE hash parameter to the PAKE algorithm identifier

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,

doc/ext-pake/api/pake.rst

@@ -39,14 +39,21 @@ 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
     :align: left
     :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,27 +88,35 @@ 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:
 
     .. code-block:: xref
 
         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-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 */
 

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
 ~~~~~~~~~~~~~~
 

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 |             \

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
     }
-}
+}

doc/ext-pake/figure/pake_encoding.json.license

@@ -1,2 +1,2 @@
-SPDX-FileCopyrightText: Copyright 2022 Arm Limited and/or its affiliates <open-source-office@arm.com>
+SPDX-FileCopyrightText: Copyright 2022-2023 Arm Limited and/or its affiliates <open-source-office@arm.com>
 SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license

doc/ext-pake/figure/pake_encoding.pdf.license

@@ -1,2 +1,2 @@
-SPDX-FileCopyrightText: Copyright 2022 Arm Limited and/or its affiliates <open-source-office@arm.com>
+SPDX-FileCopyrightText: Copyright 2022-2023 Arm Limited and/or its affiliates <open-source-office@arm.com>
 SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license