PSA PAKE: make cipher suite opaque

Hiding the structure of the cipher suite implementation allows for
greater flexibility.

To preserve maximum flexibility, the constructor is replaced by
individual setter/getter functions.

Convenience macros and or functions can be added later.

Signed-off-by: Janos Follath <janos.follath@arm.com>

include/psa/crypto.h

@@ -4140,37 +4140,187 @@ psa_status_t psa_generate_key(const psa_key_attributes_t *attributes,
  */
 typedef struct psa_pake_cipher_suite_s psa_pake_cipher_suite_t;
 
-/** Construct a cipher suite for a password-authenticated key exchange.
+/** Retrieve the PAKE algorithm from a PAKE cipher suite.
  *
- * \param primitive          The primitive used in the cipher suite.
+ * This function may be declared as `static` (i.e. without external
- * \param hash               The hash involved in the cipher suite.
+ * linkage). This function may be provided as a function-like macro,
+ * but in this case it must evaluate its argument exactly once.
+ *
+ * \param[in] cipher_suite     The cipher suite structure to query.
+ *
+ * \return The PAKE algorithm stored in the cipher suite structure.
+ */
+static psa_algorithm_t psa_pake_cs_get_algorithm(
+                           const psa_pake_cipher_suite_t* cipher_suite
+                           );
+
+/** Declare the PAKE algorithm for the cipher suite.
+ *
+ * This function overwrites any PAKE algorithm
+ * previously set in \p cipher_suite.
+ *
+ * This function may be declared as `static` (i.e. without external
+ * linkage). This function may be provided as a function-like macro,
+ * but in this case it must evaluate each of its arguments exactly once.
+ *
+ * \param[out] cipher_suite    The cipher suite structure to write to.
+ * \param algorithm            The PAKE algorithm to write.
  *                             (`PSA_ALG_XXX` values of type ::psa_algorithm_t
- *                           such that #PSA_ALG_IS_HASH(\c alg) is true.)
+ *                             such that #PSA_ALG_IS_PAKE(\c alg) is true.)
- * \param algorithm1         Additional algorithm if needed in the cipher suite,
+ *                             If this is 0, the PAKE algorithm in
- *                           0 otherwise.
+ *                             \p cipher_suite becomes unspecified.
- * \param bits1              A bit size qualifier if needed for \p algorithm1,
+ */
- *                           0 otherwise.
+static void psa_pake_cs_set_algorithm(
- * \param algorithm2         Additional algorithm if needed in the cipher suite,
+                           psa_pake_cipher_suite_t* cipher_suite,
- *                           0 otherwise.
+                           psa_algorithm_t algorithm
- * \param bits2              A bit size qualifier if needed for \p algorithm2,
+                           );
- *                           0 otherwise.
+
- * \param options            Additional options to be included with the cipher
+/** Retrieve the primitive type from a PAKE cipher suite.
- *                           suite if needed, 0 otherwise.
+ *
+ * This function may be declared as `static` (i.e. without external linkage).
+ * This function may be provided as a function-like macro, but in this case it
+ * must evaluate its argument exactly once.
  *
  * Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX`
  * values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true)
  * for more information.
  *
- * \retval The constructed cipher suite.
+ * \param[in] cipher_suite     The cipher suite structure to query.
+ *
+ * \return The primitive type stored in the cipher suite structure.
  */
-static psa_pake_cipher_suite_t psa_pake_cipher_suite(
+static psa_pake_primitive_type_t psa_pake_cs_get_type(
-                                    psa_pake_primitive_t primitive,
+                           const psa_pake_cipher_suite_t* cipher_suite
-                                    psa_algorithm_t hash,
+                           );
-                                    psa_algorithm_t algorithm1,
+
-                                    psa_pake_bits_t bits1,
+/** Declare the primitive type for a PAKE cipher suite.
-                                    psa_algorithm_t algorithm2,
+ *
-                                    psa_pake_bits_t bits2,
+ * This function overwrites any primitive type
-                                    psa_pake_cipher_suite_options_t options
+ * previously set in \p cipher_suite.
+ *
+ * This function may be declared as `static` (i.e. without external
+ * linkage). This function may be provided as a function-like macro,
+ * but in this case it must evaluate each of its arguments exactly once.
+ *
+ * \param[out] cipher_suite    The cipher suite structure to write to.
+ * \param type                 The primitive type to write.
+ *                             If this is 0, the primitive type in
+ *                             \p cipher_suite becomes unspecified.
+ */
+static void psa_pake_cs_set_type(
+                           psa_pake_cipher_suite_t* cipher_suite,
+                           psa_pake_primitive_type_t type
+                           );
+
+/** Retrieve the primitive family from a PAKE cipher suite.
+ *
+ * This function may be declared as `static` (i.e. without external
+ * linkage). This function may be provided as a function-like macro,
+ * but in this case it must evaluate its argument exactly once.
+ *
+ * \param[in] cipher_suite      The cipher suite structure to query.
+ *
+ * \return The primitive family stored in the cipher suite structure.
+ */
+static uint8_t psa_pake_cs_get_family(
+                           const psa_pake_cipher_suite_t* cipher_suite
+                           );
+
+/** Declare the primitive family for a PAKE cipher suite.
+ *
+ * This function overwrites any primitive family
+ * previously set in \p cipher_suite.
+ *
+ * This function may be declared as `static` (i.e. without external
+ * linkage). This function may be provided as a function-like macro,
+ * but in this case it must evaluate each of its arguments exactly once.
+ *
+ * \param[out] cipher_suite     The cipher suite structure to write to.
+ * \param family                The primitive family to write.
+ *                              If this is 0, the primitive family in
+ *                              \p cipher_suite becomes unspecified. The
+ *                              interpretation of this parameter depends on
+ *                              the primitive type, for more information consult the
+ *                              documentation of individual
+ *                              ::psa_pake_primitive_type_t constants).
+ */
+static void psa_pake_cs_set_family(
+                           psa_pake_cipher_suite_t* cipher_suite,
+                           uint8_t family
+                           );
+
+/** Retrieve the primitive bits from a PAKE cipher suite.
+ *
+ * This function may be declared as `static` (i.e. without external
+ * linkage). This function may be provided as a function-like macro,
+ * but in this case it must evaluate its argument exactly once.
+ *
+ * \param[in] cipher_suite      The cipher suite structure to query.
+ *
+ * \return The primitive bits stored in the cipher suite structure.
+ */
+static size_t psa_pake_cs_get_bits(const psa_pake_cipher_suite_t* cipher_suite);
+
+/** Declare the primitive bits for a PAKE cipher suite.
+ *
+ * This function overwrites any primitive bits
+ * previously set in \p cipher_suite.
+ *
+ * This function may be declared as `static` (i.e. without external
+ * linkage). This function may be provided as a function-like macro,
+ * but in this case it must evaluate each of its arguments exactly once.
+ *
+ * \param[out] cipher_suite     The cipher suite structure to write to.
+ * \param bits                  The primitive bits to write.
+ *                              If this is 0, the primitive bits in
+ *                              \p cipher_suite becomes unspecified. The
+ *                              interpretation of this parameter depends on
+ *                              the family, for more information consult the
+ *                              documentation of individual
+ *                              ::psa_pake_primitive_type_t constants).
+ */
+static void psa_pake_cs_set_bits(
+                           psa_pake_cipher_suite_t* cipher_suite,
+                           size_t bits
+                           );
+
+/** Retrieve the hash algorithm from a PAKE cipher suite.
+ *
+ * This function may be declared as `static` (i.e. without external
+ * linkage). This function may be provided as a function-like macro,
+ * but in this case it must evaluate its argument exactly once.
+ *
+ * \param[in] cipher_suite      The cipher suite structure to query.
+ *
+ * \return The hash algorithm stored in the cipher suite structure.
+ */
+static psa_algorithm_t psa_pake_cs_get_hash(
+                           const psa_pake_cipher_suite_t* cipher_suite
+                           );
+
+/** Declare the hash algorithm for a PAKE cipher suite.
+ *
+ * This function overwrites any hash algorithm
+ * previously set in \p cipher_suite.
+ *
+ * This function may be declared as `static` (i.e. without external
+ * linkage). This function may be provided as a function-like macro,
+ * but in this case it must evaluate each of its arguments exactly once.
+ *
+ * Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX`
+ * values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true)
+ * for more information.
+ *
+ * \param[out] cipher_suite     The cipher suite structure to write to.
+ * \param hash                  The hash involved in the cipher suite.
+ *                              (`PSA_ALG_XXX` values of type ::psa_algorithm_t
+ *                              such that #PSA_ALG_IS_HASH(\c alg) is true.)
+ *                              If this is 0, the hash algorithm in
+ *                              \p cipher_suite becomes unspecified.
+ */
+static void psa_pake_cs_set_hash(
+                           psa_pake_cipher_suite_t* cipher_suite,
+                           psa_algorithm_t hash
                            );
 
 /** The type of the state data structure for PAKE operations.

include/psa/crypto_struct.h

@@ -463,36 +463,82 @@ static inline size_t psa_get_key_bits(
 
 struct psa_pake_cipher_suite_s
 {
-    psa_pake_primitive_t primitive;
+    psa_algorithm_t algorithm;
+    psa_pake_primitive_type_t type;
+    uint8_t family;
+    size_t  bits;
     psa_algorithm_t hash;
-    psa_algorithm_t algorithm1;
-    psa_pake_bits_t bits1;
-    psa_algorithm_t algorithm2;
-    psa_pake_bits_t bits2;
-    psa_pake_cipher_suite_options_t options;
 };
 
-static inline struct psa_pake_cipher_suite_s psa_pake_cipher_suite(
+static inline void psa_pake_cs_set_algorithm(
-                                    psa_pake_primitive_t primitive,
+    psa_pake_cipher_suite_t *cipher_suite,
-                                    psa_algorithm_t hash,
+    psa_algorithm_t algorithm)
-                                    psa_algorithm_t algorithm1,
-                                    psa_pake_bits_t bits1,
-                                    psa_algorithm_t algorithm2,
-                                    psa_pake_bits_t bits2,
-                                    psa_pake_cipher_suite_options_t options
-                                    )
 {
-    struct psa_pake_cipher_suite_s cipher_suite;
+    if( !PSA_ALG_IS_PAKE(algorithm) )
+        cipher_suite->algorithm = 0;
+    else
+        cipher_suite->algorithm = algorithm;
+}
 
-    cipher_suite.primitive = primitive;
+static inline psa_algorithm_t psa_pake_cs_get_algorithm(
-    cipher_suite.hash = hash;
+    const psa_pake_cipher_suite_t *cipher_suite)
-    cipher_suite.algorithm1 = algorithm1;
+{
-    cipher_suite.bits1 = bits1;
+    return( cipher_suite->algorithm );
-    cipher_suite.algorithm2 = algorithm2;
+}
-    cipher_suite.bits2 = bits2;
-    cipher_suite.options = options;
 
-    return cipher_suite;
+static inline psa_pake_primitive_type_t psa_pake_cs_get_type(
+    const psa_pake_cipher_suite_t *cipher_suite)
+{
+    return( cipher_suite->type );
+}
+
+static inline void psa_pake_cs_set_type(
+    psa_pake_cipher_suite_t *cipher_suite,
+    psa_pake_primitive_type_t type)
+{
+    cipher_suite->type = type;
+}
+
+static inline uint8_t psa_pake_cs_get_family(
+    const psa_pake_cipher_suite_t *cipher_suite)
+{
+    return( cipher_suite->family );
+}
+
+static inline void psa_pake_cs_set_family(
+    psa_pake_cipher_suite_t *cipher_suite,
+    uint8_t family)
+{
+    cipher_suite->family = family;
+}
+
+static inline size_t psa_pake_cs_get_bits(
+    const psa_pake_cipher_suite_t *cipher_suite)
+{
+    return( cipher_suite->bits );
+}
+
+static inline void psa_pake_cs_set_bits(
+    psa_pake_cipher_suite_t *cipher_suite,
+    size_t bits)
+{
+    cipher_suite->bits = bits;
+}
+
+static inline psa_algorithm_t psa_pake_cs_get_hash(
+    const psa_pake_cipher_suite_t *cipher_suite)
+{
+    return( cipher_suite->hash );
+}
+
+static inline void psa_pake_cs_set_hash(
+    psa_pake_cipher_suite_t *cipher_suite,
+    psa_algorithm_t hash)
+{
+    if( !PSA_ALG_IS_HASH(hash) )
+        cipher_suite->hash = 0;
+    else
+        cipher_suite->hash = hash;
 }
 
 struct psa_pake_operation_s

include/psa/crypto_values.h

@@ -1969,21 +1969,22 @@
 /** The Password-authenticated key exchange by juggling (J-PAKE) algorithm.
  *
  * J-PAKE can be instantiated over finite fields or elliptic curves. This can
- * be achieved by passing either #PSA_PAKE_PRIMITIVE_TYPE_DH or
+ * be achieved by setting either #PSA_PAKE_PRIMITIVE_TYPE_DH or
- * #PSA_PAKE_PRIMITIVE_TYPE_ECC to #PSA_PAKE_PRIMITIVE respectively, when
+ * #PSA_PAKE_PRIMITIVE_TYPE_ECC respectively in the cipher suite (see
- * creating the cipher suite.
+ * ::psa_pake_cipher_suite_t) via psa_pake_cs_set_type(). (Before using the
+ * cipher suite the field or curve must be fully specified by calling
+ * psa_pake_cs_set_family() and psa_pake_cs_set_bits() as well. For more
+ * information refer to the documentation of the individual
+ * `PSA_PAKE_PRIMITIVE_TYPE_XXX` constants.)
+ *
+ * J-PAKE can be used with any secure cryptographic hash function. The choice
+ * of hash must be supplied to the cipher suite by calling
+ * psa_pake_cs_set_hash().
  *
  * In theory the algorithm works with any non-interactive zero-knowledge proof.
  * Implementations of the present specification use Schnorr NIZKP and this does
  * not need to be configured in the cipher suites.
  *
- * J-PAKE can be used with any secure cryptographic hash function, the choice
- * of hash must be supplied to the psa_pake_cipher_suite() as the second
- * parameter (\p hash).
- *
- * All the remaining parameters passed to psa_pake_cipher_suite() when creating
- * the cipher suite must be 0.
- *
  * The key exchange flow for JPAKE is as follows:
  * -# To get the first round data that needs to be sent to the peer, call
  *      // Get g1