mirror/mbedtls
1
0
Fork 0
mirror of https://github.com/Mbed-TLS/mbedtls.git synced 2025-01-31 09:32:55 +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(
                            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

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[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 {

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,
shared_key,
sizeof(shared_key),
&shared_key_len);
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_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);

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

70
library/psa_crypto_pake.h
View File

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

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_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:

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(
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);

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(
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;
}