mirror/mbedtls
1
0
Fork 0
mirror of https://github.com/Mbed-TLS/mbedtls.git synced 2025-01-31 18:32:57 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Documentation fixes and code adaptation

Browse Source 
Signed-off-by: Przemek Stekiel <przemyslaw.stekiel@mobica.com>
This commit is contained in:
Przemek Stekiel 2023-02-19 22:55:33 +01:00
parent 251e86ae3f
commit 6b64862ef7
9 changed files with 48 additions and 77 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
docs/proposed/psa-driver-interface.md
View File

@ -463,12 +463,14 @@ For `PSA_ALG_JPAKE` the following steps are available for input operation:
``` ```
psa_status_t acme_pake_get_implicit_key( psa_status_t acme_pake_get_implicit_key(
                            acme_pake_operation_t *operation,                             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 * `operation` The driver PAKE operation object to use.
* `output` output buffer for implicit key * `output` Buffer where the implicit key is to be written.
* `output_size` size of the returned implicit key * `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 ### Driver entry points for key management

11
include/psa/crypto_extra.h
View File

@ -1318,8 +1318,8 @@ psa_status_t psa_crypto_driver_pake_get_password_len(
* *
* \param[in] inputs Operation inputs. * \param[in] inputs Operation inputs.
* \param[out] buffer Return buffer for password. * \param[out] buffer Return buffer for password.
* \param[in] buffer_size Size of the return buffer in bytes. * \param buffer_size Size of the return buffer in bytes.
* \param[in] buffer_length Actual size of the password in bytes. * \param[out] buffer_length Actual size of the password in bytes.
* *
* \retval #PSA_SUCCESS * \retval #PSA_SUCCESS
* Success. * Success.
@ -2034,11 +2034,10 @@ struct psa_pake_operation_s {
* ID value zero means the context is not valid or not assigned to * ID value zero means the context is not valid or not assigned to
* any driver (i.e. none of the driver contexts are active). */ * any driver (i.e. none of the driver contexts are active). */
unsigned int MBEDTLS_PRIVATE(id); unsigned int MBEDTLS_PRIVATE(id);
/* Algorithm used for PAKE operation */ /* Algorithm of the PAKE operation */
psa_algorithm_t MBEDTLS_PRIVATE(alg); psa_algorithm_t MBEDTLS_PRIVATE(alg);
/* Based on stage (collecting inputs/computation) we select active structure of data union. /* Stage of the PAKE operation: waiting for the setup, collecting inputs
* While switching stage (when driver setup is called) collected inputs * or computing. */
are copied to the corresponding operation context. */
uint8_t MBEDTLS_PRIVATE(stage); uint8_t MBEDTLS_PRIVATE(stage);
/* Holds computation stage of the PAKE algorithms. */ /* Holds computation stage of the PAKE algorithms. */
union { union {

1
library/psa_crypto.c
View File

@ -7863,6 +7863,7 @@ psa_status_t psa_pake_get_implicit_key(
status = psa_driver_wrapper_pake_get_implicit_key(operation, status = psa_driver_wrapper_pake_get_implicit_key(operation,
shared_key, shared_key,
sizeof(shared_key),
&shared_key_len); &shared_key_len);
if (status != PSA_SUCCESS) { if (status != PSA_SUCCESS) {

3
library/psa_crypto_driver_wrappers.h
View File

@ -434,7 +434,8 @@ psa_status_t psa_driver_wrapper_pake_input(
psa_status_t psa_driver_wrapper_pake_get_implicit_key( psa_status_t psa_driver_wrapper_pake_get_implicit_key(
psa_pake_operation_t *operation, 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_status_t psa_driver_wrapper_pake_abort(
psa_pake_operation_t *operation); psa_pake_operation_t *operation);

7
library/psa_crypto_pake.c
View File

@ -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( psa_status_t mbedtls_psa_pake_get_implicit_key(
mbedtls_psa_pake_operation_t *operation, 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; 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) { if (operation->alg == PSA_ALG_JPAKE) {
ret = mbedtls_ecjpake_write_shared_key(&operation->ctx.pake, ret = mbedtls_ecjpake_write_shared_key(&operation->ctx.pake,
operation->buffer, operation->buffer,
MBEDTLS_PSA_JPAKE_BUFFER_SIZE, output_size,
&operation->buffer_length, &operation->buffer_length,
mbedtls_psa_get_random, mbedtls_psa_get_random,
MBEDTLS_PSA_RANDOM_STATE); MBEDTLS_PSA_RANDOM_STATE);
@ -502,7 +503,7 @@ psa_status_t mbedtls_psa_pake_get_implicit_key(
} }
memcpy(output, operation->buffer, operation->buffer_length); memcpy(output, operation->buffer, operation->buffer_length);
*output_size = operation->buffer_length; *output_length = operation->buffer_length;
return PSA_SUCCESS; return PSA_SUCCESS;
} else } else

70
library/psa_crypto_pake.h
View File

@ -43,6 +43,8 @@
* compatible with the PAKE algorithm, or the hash algorithm in * compatible with the PAKE algorithm, or the hash algorithm in
* \p cipher_suite is not supported or not compatible with the PAKE * \p cipher_suite is not supported or not compatible with the PAKE
* algorithm and primitive. * 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, psa_status_t mbedtls_psa_pake_setup(mbedtls_psa_pake_operation_t *operation,
const psa_crypto_driver_pake_inputs_t *inputs); 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 * \param step The step of the algorithm for which the output is
* requested. * requested.
* \param[out] output Buffer where the output is to be written in the * \param[out] output Buffer where the output is to be written in the
* format appropriate for this \p step. Refer to * format appropriate for this driver \p step. Refer to
* the documentation of the individual * the documentation of psa_crypto_driver_pake_step_t for
* \c PSA_PAKE_STEP_XXX constants for more * more information.
* information.
* \param output_size Size of the \p output buffer in bytes. This must * \param output_size Size of the \p output buffer in bytes. This must
* be at least #PSA_PAKE_OUTPUT_SIZE(\p alg, \p * be at least #PSA_PAKE_OUTPUT_SIZE(\p alg, \p
* primitive, \p step) where \p alg and * 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. * Success.
* \retval #PSA_ERROR_BUFFER_TOO_SMALL * \retval #PSA_ERROR_BUFFER_TOO_SMALL
* The size of the \p output buffer is 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_ENTROPY
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_CORRUPTION_DETECTED * \retval #PSA_ERROR_CORRUPTION_DETECTED
* \retval #PSA_ERROR_STORAGE_FAILURE
* \retval #PSA_ERROR_DATA_CORRUPT * \retval #PSA_ERROR_DATA_CORRUPT
* \retval #PSA_ERROR_DATA_INVALID * \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_status_t mbedtls_psa_pake_output(mbedtls_psa_pake_operation_t *operation,
psa_crypto_driver_pake_step_t step, 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. /** Provide input for a step of a password-authenticated key exchange.
* *
* \note The signature of this function is that of a PSA driver * \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 * entry point as defined in the PSA driver interface specification for
* transparent drivers. * transparent drivers.
* *
* \param[in,out] operation Active PAKE operation. * \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 * \param[in] input Buffer containing the input in the format
* appropriate for this \p step. Refer to the * appropriate for this \p step. Refer to the
* documentation of the individual * documentation of psa_crypto_driver_pake_step_t
* \c PSA_PAKE_STEP_XXX constants for more * for more information.
* information.
* \param input_length Size of the \p input buffer in bytes. * \param input_length Size of the \p input buffer in bytes.
* *
* \retval #PSA_SUCCESS * \retval #PSA_SUCCESS
* Success. * Success.
* \retval #PSA_ERROR_INVALID_SIGNATURE * \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 * \retval #PSA_ERROR_INVALID_ARGUMENT
* \p step is not compatible with the \p operation’s algorithm, or the * the \p input is not valid for the \p operation's algorithm, cipher suite
* \p input is not valid for the \p operation's algorithm, cipher suite
* or \p step. * or \p step.
* \retval #PSA_ERROR_NOT_SUPPORTED * \retval #PSA_ERROR_NOT_SUPPORTED
* \p step p is not supported with the \p operation's algorithm, or the * the \p input is not supported for the \p operation's algorithm, cipher
* \p input is not supported for the \p operation's algorithm, cipher
* suite or \p step. * suite or \p step.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_CORRUPTION_DETECTED * \retval #PSA_ERROR_CORRUPTION_DETECTED
* \retval #PSA_ERROR_STORAGE_FAILURE
* \retval #PSA_ERROR_DATA_CORRUPT * \retval #PSA_ERROR_DATA_CORRUPT
* \retval #PSA_ERROR_DATA_INVALID * \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_status_t mbedtls_psa_pake_input(mbedtls_psa_pake_operation_t *operation,
psa_crypto_driver_pake_step_t step, 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. * interface specification for transparent drivers.
* *
* \param[in,out] operation Active PAKE operation. * \param[in,out] operation Active PAKE operation.
* \param[out] output Output buffer for implicit key * \param[out] output Output buffer for implicit key.
* \param[out] output_size Size of the returned 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 * \retval #PSA_SUCCESS
* 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 * Input from a PAKE is not supported by the algorithm in the \p output
* key derivation operation. * key derivation operation.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_CORRUPTION_DETECTED * \retval #PSA_ERROR_CORRUPTION_DETECTED
* \retval #PSA_ERROR_STORAGE_FAILURE
* \retval #PSA_ERROR_DATA_CORRUPT * \retval #PSA_ERROR_DATA_CORRUPT
* \retval #PSA_ERROR_DATA_INVALID * \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( psa_status_t mbedtls_psa_pake_get_implicit_key(
mbedtls_psa_pake_operation_t *operation, 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. /** Abort a PAKE operation.
* *
@ -194,11 +162,7 @@ psa_status_t mbedtls_psa_pake_get_implicit_key(
* *
* \retval #PSA_SUCCESS * \retval #PSA_SUCCESS
* Success. * Success.
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_CORRUPTION_DETECTED * \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); psa_status_t mbedtls_psa_pake_abort(mbedtls_psa_pake_operation_t *operation);

10
scripts/data_files/driver_templates/psa_crypto_driver_wrappers.c.jinja
View File

@ -2938,13 +2938,15 @@ psa_status_t psa_driver_wrapper_pake_input(
psa_status_t psa_driver_wrapper_pake_get_implicit_key( psa_status_t psa_driver_wrapper_pake_get_implicit_key(
psa_pake_operation_t *operation, 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 ) switch( operation->id )
{ {
#if defined(MBEDTLS_PSA_BUILTIN_PAKE) #if defined(MBEDTLS_PSA_BUILTIN_PAKE)
case PSA_CRYPTO_MBED_TLS_DRIVER_ID: 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 */ #endif /* MBEDTLS_PSA_BUILTIN_PAKE */
#if defined(PSA_CRYPTO_ACCELERATOR_DRIVER_PRESENT) #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: case MBEDTLS_TEST_TRANSPARENT_DRIVER_ID:
return( mbedtls_test_transparent_pake_get_implicit_key( return( mbedtls_test_transparent_pake_get_implicit_key(
&operation->data.ctx.transparent_test_driver_ctx, &operation->data.ctx.transparent_test_driver_ctx,
output, output_size ) ); output, output_size, output_length ) );
case MBEDTLS_TEST_OPAQUE_DRIVER_ID: case MBEDTLS_TEST_OPAQUE_DRIVER_ID:
return( mbedtls_test_opaque_pake_get_implicit_key( return( mbedtls_test_opaque_pake_get_implicit_key(
&operation->data.ctx.opaque_test_driver_ctx, &operation->data.ctx.opaque_test_driver_ctx,
output, output_size ) ); output, output_size, output_length ) );
#endif /* PSA_CRYPTO_DRIVER_TEST */ #endif /* PSA_CRYPTO_DRIVER_TEST */
#endif /* PSA_CRYPTO_ACCELERATOR_DRIVER_PRESENT */ #endif /* PSA_CRYPTO_ACCELERATOR_DRIVER_PRESENT */
default: default:

4
tests/include/test/drivers/pake.h
View File

@ -70,7 +70,7 @@ psa_status_t mbedtls_test_transparent_pake_input(
psa_status_t mbedtls_test_transparent_pake_get_implicit_key( psa_status_t mbedtls_test_transparent_pake_get_implicit_key(
mbedtls_transparent_test_driver_pake_operation_t *operation, 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( psa_status_t mbedtls_test_transparent_pake_abort(
mbedtls_transparent_test_driver_pake_operation_t *operation); 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( psa_status_t mbedtls_test_opaque_pake_get_implicit_key(
mbedtls_opaque_test_driver_pake_operation_t *operation, 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( psa_status_t mbedtls_test_opaque_pake_abort(
mbedtls_opaque_test_driver_pake_operation_t *operation); mbedtls_opaque_test_driver_pake_operation_t *operation);

9
tests/src/drivers/test_driver_pake.c
View File

@ -145,7 +145,7 @@ psa_status_t mbedtls_test_transparent_pake_input(
psa_status_t mbedtls_test_transparent_pake_get_implicit_key( psa_status_t mbedtls_test_transparent_pake_get_implicit_key(
mbedtls_transparent_test_driver_pake_operation_t *operation, 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++; 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) defined(LIBTESTDRIVER1_MBEDTLS_PSA_BUILTIN_PAKE)
mbedtls_test_driver_pake_hooks.driver_status = mbedtls_test_driver_pake_hooks.driver_status =
libtestdriver1_mbedtls_psa_pake_get_implicit_key( libtestdriver1_mbedtls_psa_pake_get_implicit_key(
operation, output, output_size); operation, output, output_size, output_length);
#elif defined(MBEDTLS_PSA_BUILTIN_PAKE) #elif defined(MBEDTLS_PSA_BUILTIN_PAKE)
mbedtls_test_driver_pake_hooks.driver_status = mbedtls_test_driver_pake_hooks.driver_status =
mbedtls_psa_pake_get_implicit_key( mbedtls_psa_pake_get_implicit_key(
operation, output, output_size); operation, output, output_size, output_length);
#else #else
(void) operation; (void) operation;
(void) output; (void) output;
@ -289,11 +289,12 @@ psa_status_t mbedtls_test_opaque_pake_input(
psa_status_t mbedtls_test_opaque_pake_get_implicit_key( psa_status_t mbedtls_test_opaque_pake_get_implicit_key(
mbedtls_opaque_test_driver_pake_operation_t *operation, 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) operation;
(void) output; (void) output;
(void) output_size; (void) output_size;
(void) output_length;
return PSA_ERROR_NOT_SUPPORTED; return PSA_ERROR_NOT_SUPPORTED;
} }