diff --git a/include/psa/crypto.h b/include/psa/crypto.h index 0992a65109..a0f5b135ed 100644 --- a/include/psa/crypto.h +++ b/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 diff --git a/include/psa/crypto_struct.h b/include/psa/crypto_struct.h index 47012fdd00..a4e6cca8e2 100644 --- a/include/psa/crypto_struct.h +++ b/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 diff --git a/include/psa/crypto_types.h b/include/psa/crypto_types.h index 1c40f5bf7c..8031c9d27c 100644 --- a/include/psa/crypto_types.h +++ b/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 */