diff --git a/include/psa/crypto.h b/include/psa/crypto.h index e6e78eb1c..632006dfb 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -4232,10 +4232,10 @@ static psa_pake_operation_t psa_pake_operation_init(void); * * A typical sequence of calls to perform a password-authenticated key * exchange: - * -# Call psa_pake_get_key_share() to get the key share that needs to be sent - * to the peer. - * -# Call psa_pake_set_key_share() to provide the key share that was received - * from the peer. + * -# Call psa_pake_output(operation, #PSA_PAKE_DATA_KEY_SHARE, ...) to get the + * key share that needs to be sent to the peer. + * -# Call psa_pake_input(operation, #PSA_PAKE_DATA_KEY_SHARE, ...) to provide + * the key share that was received from the peer. * -# Call psa_pake_get_implicit_key() for accessing the shared secret. * * The exact sequence of calls to perform a password-authenticated key exchange @@ -4326,55 +4326,11 @@ psa_status_t psa_pake_setup(psa_pake_operation_t *operation, const uint8_t *session_data, size_t session_data_len); -/** Get the key share from a password-authenticated key exchange operation. - * - * This function returns a simple key share (eg. group element). - * - * The exact sequence of calls to perform a password-authenticated key - * exchange depends on the algorithm in use. 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. - * - * If this function returns an error status, the operation enters an error - * state and must be aborted by calling psa_pake_abort(). - * - * \param[in,out] operation Active PAKE operation. - * \param[out] key_share Buffer where the key share is to be written. - * \param key_share_size Size of the \p key_share buffer in bytes. - * \param[out] key_share_length On success, the number of bytes of the - * returned key_share. - * - * \retval #PSA_SUCCESS - * Success. - * \retval #PSA_ERROR_BAD_STATE - * The operation state is not valid (it must be active, but beyond that - * validity is specific to the algorithm). - * \retval #PSA_ERROR_BUFFER_TOO_SMALL - * The size of the \p key_share buffer is too small. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE - * \retval #PSA_ERROR_BAD_STATE - * The library has not been previously initialized by psa_crypto_init(). - * It is implementation-dependent whether a failure to initialize - * results in this error code. - */ -psa_status_t psa_pake_get_key_share(psa_pake_operation_t *operation, - uint8_t *key_share, - size_t key_share_size, - size_t *key_share_length); - /** Get additional key share from a password-authenticated key exchange. * * Depending on the algorithm being executed, you might need to call this * function several times or you might not need to call this at all. * - * Calling this function with PSA_PAKE_DATA_KEY_SHARE as \p type is equivalent - * to calling psa_pake_get_key_share(). - * * The exact sequence of calls to perform a password-authenticated key * exchange depends on the algorithm in use. Refer to the documentation of * individual PAKE algorithm types (`PSA_ALG_XXX` values of type @@ -4414,47 +4370,11 @@ psa_status_t psa_pake_output(psa_pake_operation_t *operation, size_t output_size, size_t *output_length); -/** Provide peer key share to a password-authenticated key exchange operation. - * - * This function inputs a simple key share (eg. group element). - * - * The exact sequence of calls to perform a password-authenticated key - * exchange depends on the algorithm in use. 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[in,out] operation Active PAKE operation. - * \param[in] key_share Buffer containing the peer's key share. - * \param key_share_length Size of the \p key_share buffer in bytes. - * - * \retval #PSA_SUCCESS - * Success. - * \retval #PSA_ERROR_BAD_STATE - * The operation state is not valid (it must be active, but beyond that - * validity is specific to the algorithm). - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE - * \retval #PSA_ERROR_BAD_STATE - * The library has not been previously initialized by psa_crypto_init(). - * It is implementation-dependent whether a failure to initialize - * results in this error code. - */ -psa_status_t psa_pake_set_key_share(psa_pake_operation_t *operation, - const uint8_t *key_share, - size_t key_share_length); - /** Provide additional peer key share for a password-authenticated key exchange. * * Depending on the algorithm being executed, you might need to call this * function several times or you might not need to call this at all. * - * Calling this function with PSA_PAKE_DATA_KEY_SHARE as \p type is equivalent - * to calling psa_pake_set_key_share(). - * * The exact sequence of calls to perform a password-authenticated key * exchange depends on the algorithm in use. Refer to the documentation of * individual PAKE algorithm types (`PSA_ALG_XXX` values of type diff --git a/include/psa/crypto_sizes.h b/include/psa/crypto_sizes.h index 8497b14d0..482ff6806 100644 --- a/include/psa/crypto_sizes.h +++ b/include/psa/crypto_sizes.h @@ -1132,26 +1132,6 @@ #define PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE \ (PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE) -/** A sufficient output buffer size for psa_pake_get_key_share(). - * - * If the size of the ciphertext buffer is at least this large, it is - * guaranteed that psa_pake_get_key_share() will not fail due to an - * insufficient ciphertext buffer size. The actual size of the output might be - * smaller in any given call. - * - * See also #PSA_PAKE_OUTPUT_MAX_SIZE - * - * \param alg A PAKE algorithm (PSA_ALG_XXX value such that - * #PSA_ALG_IS_PAKE(\p alg) is true). - * \param cipher_suite A cipher suite that is compatible with algorithm \p alg. - * \return A sufficient key share buffer size for the specified - * cipher suite and algorithm. If the cipher suite or PAKE - * algorithm is not recognized, or the parameters are - * incompatible, return 0. - */ -#define PSA_PAKE_KEY_SHARE_SIZE(alg, cipher_suite) \ - (PSA_PAKE_OUTPUT_SIZE(alg, cipher_suite, PSA_PAKE_DATA_KEY_SHARE) - /** A sufficient output buffer size for psa_pake_output(). * * If the size of the ciphertext buffer is at least this large, it is @@ -1172,8 +1152,8 @@ */ #define PSA_PAKE_OUTPUT_SIZE(alg, cipher_suite, output) -/** Output buffer size for psa_pake_output() and psa_pake_get_key_share(), - * for any of the supported cipher suites and PAKE algorithms. +/** Output buffer size for psa_pake_output() for any of the supported cipher + * suites and PAKE algorithms. * * This macro must expand to a compile-time constant integer. * diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h index 4a6b06c76..1e8c9fe38 100644 --- a/include/psa/crypto_values.h +++ b/include/psa/crypto_values.h @@ -1986,7 +1986,7 @@ * * The key exchange flow for JPAKE is as follows: * -# To get the first round data that needs to be sent to the peer, call - * psa_pake_get_key_share(operation, ...); + * psa_pake_output(operation, #PSA_PAKE_DATA_KEY_SHARE, ...); * psa_pake_output(operation, #PSA_PAKE_DATA_ZK_PUBLIC, ...); * psa_pake_output(operation, #PSA_PAKE_DATA_ZK_PROOF, ...); * psa_pake_output(operation, #PSA_PAKE_DATA_KEY_SHARE_2, ...); @@ -1994,7 +1994,7 @@ * psa_pake_output(operation, #PSA_PAKE_DATA_ZK_PROOF_2, ...); * -# To provide the first round data received from the peer to the operation, * call - * psa_pake_set_key_share(operation, ...); + * psa_pake_input(operation, #PSA_PAKE_DATA_KEY_SHARE, ...); * psa_pake_input(operation, #PSA_PAKE_DATA_ZK_PUBLIC, ...); * psa_pake_input(operation, #PSA_PAKE_DATA_ZK_PROOF, ...); * psa_pake_input(operation, #PSA_PAKE_DATA_KEY_SHARE_2, ...);