PSA PAKE: Add cipher suite structure

PAKE protocols make use of a range of cryptographic schemes and
primitives. Standards allow for several options to use for each of them.
They call the combination of specific algorithms cipher suites,
configurations or options.

Cipher suites are represented by a separate data type for several
reasons:
1. To allow for individual PAKE protocols to provide pre-defined cipher
   suites.
2. To organise cipher suites into a unit that can be handled separately
   from the operation context. The PAKE operation flow is already
   complex, will be even more so when key confirmation is added.
   Handling them separately should reduce the surface of the interface
   the application developer needs to pay attention at any given time.

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

include/psa/crypto.h

@@ -4131,6 +4131,47 @@ psa_status_t psa_generate_key(const psa_key_attributes_t *attributes,
  * @{
  */
 
+/** The type of the data strucure for PAKE cipher suites.
+ *
+ * This is an implementation-defined \c struct. Applications should not
+ * make any assumptions about the content of this structure except
+ * as directed by the documentation of a specific implementation.
+ */
+typedef struct psa_pake_cipher_suite_s psa_pake_cipher_suite_t;
+
+/** Construct a cipher suite for a password-authenticated key exchange.
+ *
+ * \param primitive          The primitive used in the cipher suite.
+ * \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.)
+ * \param algorithm1         Additional algorithm if needed in the cipher suite,
+ *                           0 otherwise.
+ * \param bits1              A bit size qualifier if needed for \p algorithm1,
+ *                           0 otherwise.
+ * \param algorithm2         Additional algorithm if needed in the cipher suite,
+ *                           0 otherwise.
+ * \param bits2              A bit size qualifier if needed for \p algorithm2,
+ *                           0 otherwise.
+ * \param options            Additional options to be included with the cipher
+ *                           suite if needed, 0 otherwise.
+ *
+ * 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.
+ */
+static psa_pake_cipher_suite_t psa_pake_cipher_suite(
+                                    psa_pake_primitive_t primitive,
+                                    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
+                                    );
+
 /** The type of the state data structure for PAKE operations.
  *
  * Before calling any function on a PAKE operation object, the application

include/psa/crypto_struct.h

@@ -461,6 +461,39 @@ static inline size_t psa_get_key_bits(
     return( attributes->core.bits );
 }
 
+struct psa_pake_cipher_suite_s
+{
+    psa_pake_primitive_t primitive;
+    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(
+                                    psa_pake_primitive_t primitive,
+                                    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
+                                    )
+{
+    struct psa_pake_cipher_suite_s cipher_suite;
+
+    cipher_suite.primitive = primitive;
+    cipher_suite.hash = hash;
+    cipher_suite.algorithm1 = algorithm1;
+    cipher_suite.bits1 = bits1;
+    cipher_suite.algorithm2 = algorithm2;
+    cipher_suite.bits2 = bits2;
+    cipher_suite.options = options;
+
+    return cipher_suite;
+}
 #ifdef __cplusplus
 }
 #endif

include/psa/crypto_types.h

@@ -380,7 +380,7 @@ typedef uint16_t psa_key_derivation_step_t;
 
 /**@}*/
 
-/** \defgroup pake Password-authenticated key exchange
+/** \defgroup pake Password-authenticated key exchange (PAKE)
  * @{
  */
 
@@ -412,5 +412,13 @@ typedef uint16_t psa_pake_bits_t;
  */
 typedef uint32_t psa_pake_primitive_t;
 
+/** Encoding of additional options for PAKE.
+ *
+ * This type is for encoding additional options into PAKE cipher suites.
+ * (Options like for example EnvelopeMode in OPAQUE or "Per-User M and N" in
+ * SPAKE2.)
+ */
+typedef uint32_t psa_pake_cipher_suite_options_t;
+
 /**@}*/
 #endif /* PSA_CRYPTO_TYPES_H */