diff --git a/include/psa/crypto.h b/include/psa/crypto.h index 074cc93e1..9220b2ea7 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -4140,38 +4140,188 @@ 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. - * \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. + * 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 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_PAKE(\c alg) is true.) + * If this is 0, the PAKE algorithm in + * \p cipher_suite becomes unspecified. + */ +static void psa_pake_cs_set_algorithm( + psa_pake_cipher_suite_t* cipher_suite, + psa_algorithm_t algorithm + ); + +/** Retrieve the primitive type 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. * * 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( - 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 psa_pake_primitive_type_t psa_pake_cs_get_type( + const psa_pake_cipher_suite_t* cipher_suite + ); + +/** Declare the primitive type for a PAKE cipher suite. + * + * This function overwrites any primitive type + * 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. * diff --git a/include/psa/crypto_struct.h b/include/psa/crypto_struct.h index f289caf16..881abcb2a 100644 --- a/include/psa/crypto_struct.h +++ b/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( - 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 void psa_pake_cs_set_algorithm( + psa_pake_cipher_suite_t *cipher_suite, + psa_algorithm_t algorithm) { - 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; - cipher_suite.hash = hash; - cipher_suite.algorithm1 = algorithm1; - cipher_suite.bits1 = bits1; - cipher_suite.algorithm2 = algorithm2; - cipher_suite.bits2 = bits2; - cipher_suite.options = options; +static inline psa_algorithm_t psa_pake_cs_get_algorithm( + const psa_pake_cipher_suite_t *cipher_suite) +{ + return( cipher_suite->algorithm ); +} - 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 diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h index 9a9f69e61..bed48f79c 100644 --- a/include/psa/crypto_values.h +++ b/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 - * #PSA_PAKE_PRIMITIVE_TYPE_ECC to #PSA_PAKE_PRIMITIVE respectively, when - * creating the cipher suite. + * be achieved by setting either #PSA_PAKE_PRIMITIVE_TYPE_DH or + * #PSA_PAKE_PRIMITIVE_TYPE_ECC respectively in the cipher suite (see + * ::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