yuzu-emu/mbedtls
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Remove psa_pake_get/set_key_share() functions

Browse source 
The main purpose of psa_pake_get_key_share() is to provide a more
straightforward and convenient call flow for regular PAKEs. Most PAKEs
have a single key share and need a flow like this:

op=PSA_PAKE_OPERATION_INIT;
psa_pake_setup();
psa_pake_get_key_share();
psa_pake_set_key_share();
psa_pake_get_implicit_key();

Adding psa_pake_get/set_key_share() functions cuts out the
psa_pake_data_t constants from the users vision, hiding complexity that
exists only for unrelated PAKEs that aren't relevant for the user.

This comes with the cost of the two additional API functions that we need
to maintain.

Since the current stream of work focuses on enabling J-PAKE, there are
no benefits to these functions for now.

Once algorithms that can benefit from this simplification are added,
adding back these functions can be reconsidered.

Signed-off-by: Janos Follath <janos.follath@arm.com>
This commit is contained in:
Janos Follath 2021-04-19 13:57:13 +01:00
parent fb4203dcff
commit 7ebcbf34f9
3 changed files with 8 additions and 108 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

88
include/psa/crypto.h
View file

@ -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

24
include/psa/crypto_sizes.h
View file

@ -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.
*

4
include/psa/crypto_values.h
View file

@ -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, ...);