diff --git a/docs/proposed/psa-driver-interface.md b/docs/proposed/psa-driver-interface.md index 07f198908d..ac6b8ded79 100644 --- a/docs/proposed/psa-driver-interface.md +++ b/docs/proposed/psa-driver-interface.md @@ -463,12 +463,14 @@ For `PSA_ALG_JPAKE` the following steps are available for input operation: ``` psa_status_t acme_pake_get_implicit_key(                             acme_pake_operation_t *operation, -                            uint8_t *output, size_t *output_size ); +                            uint8_t *output, size_t output_size, + size_t *output_length ); ``` -* `operation` is an operation object -* `output` output buffer for implicit key -* `output_size` size of the returned implicit key +* `operation` The driver PAKE operation object to use. +* `output` Buffer where the implicit key is to be written. +* `output_size` Size of the output buffer in bytes. +* `output_length` On success, the number of bytes of the implicit key. ### Driver entry points for key management diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h index 39ef52cbec..5f86c3f4fd 100644 --- a/include/psa/crypto_extra.h +++ b/include/psa/crypto_extra.h @@ -1318,8 +1318,8 @@ psa_status_t psa_crypto_driver_pake_get_password_len( * * \param[in] inputs Operation inputs. * \param[out] buffer Return buffer for password. - * \param[in] buffer_size Size of the return buffer in bytes. - * \param[in] buffer_length Actual size of the password in bytes. + * \param buffer_size Size of the return buffer in bytes. + * \param[out] buffer_length Actual size of the password in bytes. * * \retval #PSA_SUCCESS * Success. @@ -2034,11 +2034,10 @@ struct psa_pake_operation_s { * ID value zero means the context is not valid or not assigned to * any driver (i.e. none of the driver contexts are active). */ unsigned int MBEDTLS_PRIVATE(id); - /* Algorithm used for PAKE operation */ + /* Algorithm of the PAKE operation */ psa_algorithm_t MBEDTLS_PRIVATE(alg); - /* Based on stage (collecting inputs/computation) we select active structure of data union. - * While switching stage (when driver setup is called) collected inputs - are copied to the corresponding operation context. */ + /* Stage of the PAKE operation: waiting for the setup, collecting inputs + * or computing. */ uint8_t MBEDTLS_PRIVATE(stage); /* Holds computation stage of the PAKE algorithms. */ union { diff --git a/library/psa_crypto.c b/library/psa_crypto.c index 2c1a910fbd..1c066ce13b 100644 --- a/library/psa_crypto.c +++ b/library/psa_crypto.c @@ -7863,6 +7863,7 @@ psa_status_t psa_pake_get_implicit_key( status = psa_driver_wrapper_pake_get_implicit_key(operation, shared_key, + sizeof(shared_key), &shared_key_len); if (status != PSA_SUCCESS) { diff --git a/library/psa_crypto_driver_wrappers.h b/library/psa_crypto_driver_wrappers.h index 65d0d3f078..dd1b763b18 100644 --- a/library/psa_crypto_driver_wrappers.h +++ b/library/psa_crypto_driver_wrappers.h @@ -434,7 +434,8 @@ psa_status_t psa_driver_wrapper_pake_input( psa_status_t psa_driver_wrapper_pake_get_implicit_key( psa_pake_operation_t *operation, - uint8_t *output, size_t *output_size); + uint8_t *output, size_t output_size, + size_t *output_length); psa_status_t psa_driver_wrapper_pake_abort( psa_pake_operation_t *operation); diff --git a/library/psa_crypto_pake.c b/library/psa_crypto_pake.c index 73032c6a8a..150270c6c3 100644 --- a/library/psa_crypto_pake.c +++ b/library/psa_crypto_pake.c @@ -485,7 +485,8 @@ psa_status_t mbedtls_psa_pake_input(mbedtls_psa_pake_operation_t *operation, psa_status_t mbedtls_psa_pake_get_implicit_key( mbedtls_psa_pake_operation_t *operation, - uint8_t *output, size_t *output_size) + uint8_t *output, size_t output_size, + size_t *output_length) { int ret = MBEDTLS_ERR_ERROR_CORRUPTION_DETECTED; @@ -493,7 +494,7 @@ psa_status_t mbedtls_psa_pake_get_implicit_key( if (operation->alg == PSA_ALG_JPAKE) { ret = mbedtls_ecjpake_write_shared_key(&operation->ctx.pake, operation->buffer, - MBEDTLS_PSA_JPAKE_BUFFER_SIZE, + output_size, &operation->buffer_length, mbedtls_psa_get_random, MBEDTLS_PSA_RANDOM_STATE); @@ -502,7 +503,7 @@ psa_status_t mbedtls_psa_pake_get_implicit_key( } memcpy(output, operation->buffer, operation->buffer_length); - *output_size = operation->buffer_length; + *output_length = operation->buffer_length; return PSA_SUCCESS; } else diff --git a/library/psa_crypto_pake.h b/library/psa_crypto_pake.h index 365855601b..9bdcc33872 100644 --- a/library/psa_crypto_pake.h +++ b/library/psa_crypto_pake.h @@ -43,6 +43,8 @@ * compatible with the PAKE algorithm, or the hash algorithm in * \p cipher_suite is not supported or not compatible with the PAKE * algorithm and primitive. + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_CORRUPTION_DETECTED */ psa_status_t mbedtls_psa_pake_setup(mbedtls_psa_pake_operation_t *operation, const psa_crypto_driver_pake_inputs_t *inputs); @@ -59,10 +61,9 @@ psa_status_t mbedtls_psa_pake_setup(mbedtls_psa_pake_operation_t *operation, * \param step The step of the algorithm for which the output is * requested. * \param[out] output Buffer where the output is to be written in the - * format appropriate for this \p step. Refer to - * the documentation of the individual - * \c PSA_PAKE_STEP_XXX constants for more - * information. + * format appropriate for this driver \p step. Refer to + * the documentation of psa_crypto_driver_pake_step_t for + * more information. * \param output_size Size of the \p output buffer in bytes. This must * be at least #PSA_PAKE_OUTPUT_SIZE(\p alg, \p * primitive, \p step) where \p alg and @@ -77,23 +78,10 @@ psa_status_t mbedtls_psa_pake_setup(mbedtls_psa_pake_operation_t *operation, * Success. * \retval #PSA_ERROR_BUFFER_TOO_SMALL * The size of the \p output buffer is too small. - * \retval #PSA_ERROR_INVALID_ARGUMENT - * \p step is not compatible with the operation's algorithm. - * \retval #PSA_ERROR_NOT_SUPPORTED - * \p step is not supported with the operation's algorithm. * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE * \retval #PSA_ERROR_DATA_CORRUPT * \retval #PSA_ERROR_DATA_INVALID - * \retval #PSA_ERROR_BAD_STATE - * The operation state is not valid (it must be active, and fully set - * up, and this call must conform to the algorithm's requirements - * for ordering of input and output steps). - * It is implementation-dependent whether a failure to initialize - * results in this error code. */ psa_status_t mbedtls_psa_pake_output(mbedtls_psa_pake_operation_t *operation, psa_crypto_driver_pake_step_t step, @@ -104,43 +92,32 @@ psa_status_t mbedtls_psa_pake_output(mbedtls_psa_pake_operation_t *operation, /** Provide input for a step of a password-authenticated key exchange. * * \note The signature of this function is that of a PSA driver - * key_agreement entry point. This function behaves as a key_agreement + * pake_input entry point. This function behaves as a pake_input * entry point as defined in the PSA driver interface specification for * transparent drivers. * * \param[in,out] operation Active PAKE operation. - * \param step The step for which the input is provided. + * \param step The driver step for which the input is provided. * \param[in] input Buffer containing the input in the format * appropriate for this \p step. Refer to the - * documentation of the individual - * \c PSA_PAKE_STEP_XXX constants for more - * information. + * documentation of psa_crypto_driver_pake_step_t + * for more information. * \param input_length Size of the \p input buffer in bytes. * * \retval #PSA_SUCCESS * Success. * \retval #PSA_ERROR_INVALID_SIGNATURE - * The verification fails for a #PSA_PAKE_STEP_ZK_PROOF input step. + * The verification fails for a zero-knowledge input step. * \retval #PSA_ERROR_INVALID_ARGUMENT - * \p step is not compatible with the \p operation’s algorithm, or the - * \p input is not valid for the \p operation's algorithm, cipher suite + * the \p input is not valid for the \p operation's algorithm, cipher suite * or \p step. * \retval #PSA_ERROR_NOT_SUPPORTED - * \p step p is not supported with the \p operation's algorithm, or the - * \p input is not supported for the \p operation's algorithm, cipher + * the \p input is not supported for the \p operation's algorithm, cipher * suite or \p step. * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE * \retval #PSA_ERROR_DATA_CORRUPT * \retval #PSA_ERROR_DATA_INVALID - * \retval #PSA_ERROR_BAD_STATE - * The operation state is not valid (it must be active, and fully set - * up, and this call must conform to the algorithm's requirements - * for ordering of input and output steps). - * It is implementation-dependent whether a failure to initialize - * results in this error code. */ psa_status_t mbedtls_psa_pake_input(mbedtls_psa_pake_operation_t *operation, psa_crypto_driver_pake_step_t step, @@ -155,8 +132,9 @@ psa_status_t mbedtls_psa_pake_input(mbedtls_psa_pake_operation_t *operation, * interface specification for transparent drivers. * * \param[in,out] operation Active PAKE operation. - * \param[out] output Output buffer for implicit key - * \param[out] output_size Size of the returned implicit key + * \param[out] output Output buffer for implicit key. + * \param output_size Size of the output buffer in bytes. + * \param[out] output_length On success, the number of bytes of the implicit key. * * \retval #PSA_SUCCESS * Success. @@ -164,24 +142,14 @@ psa_status_t mbedtls_psa_pake_input(mbedtls_psa_pake_operation_t *operation, * Input from a PAKE is not supported by the algorithm in the \p output * key derivation operation. * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE * \retval #PSA_ERROR_DATA_CORRUPT * \retval #PSA_ERROR_DATA_INVALID - * \retval #PSA_ERROR_BAD_STATE - * The PAKE operation state is not valid (it must be active, but beyond - * that validity is specific to the algorithm), - * or the state of \p output is not valid for - * the #PSA_KEY_DERIVATION_INPUT_SECRET step. This can happen if the - * step is out of order or the application has done this step already - * and it may not be repeated. - * It is implementation-dependent whether a failure to initialize - * results in this error code. */ psa_status_t mbedtls_psa_pake_get_implicit_key( mbedtls_psa_pake_operation_t *operation, - uint8_t *output, size_t *output_size); + uint8_t *output, size_t output_size, + size_t *output_length); /** Abort a PAKE operation. * @@ -194,11 +162,7 @@ psa_status_t mbedtls_psa_pake_get_implicit_key( * * \retval #PSA_SUCCESS * Success. - * \retval #PSA_ERROR_COMMUNICATION_FAILURE * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_BAD_STATE - * It is implementation-dependent whether a failure to initialize - * results in this error code. */ psa_status_t mbedtls_psa_pake_abort(mbedtls_psa_pake_operation_t *operation); diff --git a/scripts/data_files/driver_templates/psa_crypto_driver_wrappers.c.jinja b/scripts/data_files/driver_templates/psa_crypto_driver_wrappers.c.jinja index b287b37a1d..a34d9b0947 100644 --- a/scripts/data_files/driver_templates/psa_crypto_driver_wrappers.c.jinja +++ b/scripts/data_files/driver_templates/psa_crypto_driver_wrappers.c.jinja @@ -2938,13 +2938,15 @@ psa_status_t psa_driver_wrapper_pake_input( psa_status_t psa_driver_wrapper_pake_get_implicit_key( psa_pake_operation_t *operation, - uint8_t *output, size_t *output_size ) + uint8_t *output, size_t output_size, + size_t *output_length ) { switch( operation->id ) { #if defined(MBEDTLS_PSA_BUILTIN_PAKE) case PSA_CRYPTO_MBED_TLS_DRIVER_ID: - return( mbedtls_psa_pake_get_implicit_key( &operation->data.ctx.mbedtls_ctx, output, output_size ) ); + return( mbedtls_psa_pake_get_implicit_key( &operation->data.ctx.mbedtls_ctx, + output, output_size, output_length ) ); #endif /* MBEDTLS_PSA_BUILTIN_PAKE */ #if defined(PSA_CRYPTO_ACCELERATOR_DRIVER_PRESENT) @@ -2952,11 +2954,11 @@ psa_status_t psa_driver_wrapper_pake_get_implicit_key( case MBEDTLS_TEST_TRANSPARENT_DRIVER_ID: return( mbedtls_test_transparent_pake_get_implicit_key( &operation->data.ctx.transparent_test_driver_ctx, - output, output_size ) ); + output, output_size, output_length ) ); case MBEDTLS_TEST_OPAQUE_DRIVER_ID: return( mbedtls_test_opaque_pake_get_implicit_key( &operation->data.ctx.opaque_test_driver_ctx, - output, output_size ) ); + output, output_size, output_length ) ); #endif /* PSA_CRYPTO_DRIVER_TEST */ #endif /* PSA_CRYPTO_ACCELERATOR_DRIVER_PRESENT */ default: diff --git a/tests/include/test/drivers/pake.h b/tests/include/test/drivers/pake.h index d082d6e5ed..4a2b7c4614 100644 --- a/tests/include/test/drivers/pake.h +++ b/tests/include/test/drivers/pake.h @@ -70,7 +70,7 @@ psa_status_t mbedtls_test_transparent_pake_input( psa_status_t mbedtls_test_transparent_pake_get_implicit_key( mbedtls_transparent_test_driver_pake_operation_t *operation, - uint8_t *output, size_t *output_size); + uint8_t *output, size_t output_size, size_t *output_length); psa_status_t mbedtls_test_transparent_pake_abort( mbedtls_transparent_test_driver_pake_operation_t *operation); @@ -114,7 +114,7 @@ psa_status_t mbedtls_test_opaque_pake_input( psa_status_t mbedtls_test_opaque_pake_get_implicit_key( mbedtls_opaque_test_driver_pake_operation_t *operation, - uint8_t *output, size_t *output_size); + uint8_t *output, size_t output_size, size_t *output_length); psa_status_t mbedtls_test_opaque_pake_abort( mbedtls_opaque_test_driver_pake_operation_t *operation); diff --git a/tests/src/drivers/test_driver_pake.c b/tests/src/drivers/test_driver_pake.c index 615f7ef8a1..3eaf38a654 100644 --- a/tests/src/drivers/test_driver_pake.c +++ b/tests/src/drivers/test_driver_pake.c @@ -145,7 +145,7 @@ psa_status_t mbedtls_test_transparent_pake_input( psa_status_t mbedtls_test_transparent_pake_get_implicit_key( mbedtls_transparent_test_driver_pake_operation_t *operation, - uint8_t *output, size_t *output_size) + uint8_t *output, size_t output_size, size_t *output_length) { mbedtls_test_driver_pake_hooks.hits++; @@ -157,11 +157,11 @@ psa_status_t mbedtls_test_transparent_pake_get_implicit_key( defined(LIBTESTDRIVER1_MBEDTLS_PSA_BUILTIN_PAKE) mbedtls_test_driver_pake_hooks.driver_status = libtestdriver1_mbedtls_psa_pake_get_implicit_key( - operation, output, output_size); + operation, output, output_size, output_length); #elif defined(MBEDTLS_PSA_BUILTIN_PAKE) mbedtls_test_driver_pake_hooks.driver_status = mbedtls_psa_pake_get_implicit_key( - operation, output, output_size); + operation, output, output_size, output_length); #else (void) operation; (void) output; @@ -289,11 +289,12 @@ psa_status_t mbedtls_test_opaque_pake_input( psa_status_t mbedtls_test_opaque_pake_get_implicit_key( mbedtls_opaque_test_driver_pake_operation_t *operation, - uint8_t *output, size_t *output_size) + uint8_t *output, size_t output_size, size_t *output_length) { (void) operation; (void) output; (void) output_size; + (void) output_length; return PSA_ERROR_NOT_SUPPORTED; }