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>
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 0992a65..a0f5b13 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -4131,6 +4131,47 @@
* @{
*/
+/** 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
diff --git a/include/psa/crypto_struct.h b/include/psa/crypto_struct.h
index 47012fd..a4e6cca 100644
--- a/include/psa/crypto_struct.h
+++ b/include/psa/crypto_struct.h
@@ -461,6 +461,39 @@
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
diff --git a/include/psa/crypto_types.h b/include/psa/crypto_types.h
index 1c40f5b..8031c9d 100644
--- a/include/psa/crypto_types.h
+++ b/include/psa/crypto_types.h
@@ -380,7 +380,7 @@
/**@}*/
-/** \defgroup pake Password-authenticated key exchange
+/** \defgroup pake Password-authenticated key exchange (PAKE)
* @{
*/
@@ -412,5 +412,13 @@
*/
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 */