lib/mbedtls
1
0
Fork 0
mirror of https://github.com/Mbed-TLS/mbedtls.git synced 2025-11-03 20:33:16 +03:00
Code Activity

Update the documentation (v.3)

Browse Source 
Signed-off-by: Przemek Stekiel <przemyslaw.stekiel@mobica.com>
This commit is contained in:
Przemek Stekiel
2023-01-25 23:16:18 +01:00
parent 38b4e1761d
commit 27cd488088
1 changed files with 17 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -323,17 +323,17 @@ TODO
### Driver entry points for PAKE ### Driver entry points for PAKE
PAKE operation is divided into two stages: collecting inputs and computation. Core side is responsible for keeping inputs and core set-data functions do not have driver entry points. Collected inputs are available for drivers via get-data functions for `password`, `role` and `cipher_suite`. A PAKE operation is divided into two stages: collecting inputs and computation. Core side is responsible for keeping inputs and core set-data functions do not have driver entry points. Collected inputs are available for drivers via get-data functions for `password`, `role` and `cipher_suite`.
### PAKE driver dispatch logic ### PAKE driver dispatch logic
The core decides whether to dispatch a PAKE operation to a driver based on the location of the provided password. The core decides whether to dispatch a PAKE operation to a driver based on the location of the provided password.
When all inputs are collected and `"psa_pake_output"` or `"psa_pake_input"` is called for the first time `"pake_setup"` driver entry point is invoked. When all inputs are collected and `"psa_pake_output"` or `"psa_pake_input"` is called for the first time `"pake_setup"` driver entry point is invoked.
1. Lifetime of the `password` is local storage 1. If the location of the `password` is the local storage
- if there is a transparent driver available for the given configuration, the core calls that driver's `"pake_setup"` and subsequent entry points. - if there is a transparent driver for the specified ciphersuite, the core calls that driver's `"pake_setup"` and subsequent entry points.
- if a transparent driver is not available or can not handle a given configuration, the core uses its built-in implementation. - otherwise, or on fallback, the core uses its built-in implementation.
2. Lifetime of the `password` is test driver 2. If the location of the `password` is the location of a secure element
- the core calls opaque driver's `"pake_setup"` and subsequent entry points. - the core calls the `"pake_setup"` entry point of the secure element driver and subsequent entry points.
### Summary of entry points for PAKE ### Summary of entry points for PAKE
@@ -365,10 +365,15 @@ psa_status_t psa_crypto_driver_pake_get_password_len(
    const psa_crypto_driver_pake_inputs_t *inputs,     const psa_crypto_driver_pake_inputs_t *inputs,
    size_t *password_len);     size_t *password_len);
psa_status_t psa_crypto_driver_pake_get_password( psa_status_t psa_crypto_driver_pake_get_password_bytes(
    const psa_crypto_driver_pake_inputs_t *inputs,     const psa_crypto_driver_pake_inputs_t *inputs,
    uint8_t *buffer, size_t buffer_size, size_t *buffer_length);     uint8_t *buffer, size_t buffer_size, size_t *buffer_length);
psa_status_t psa_crypto_driver_pake_get_password_key(
    const psa_crypto_driver_pake_inputs_t *inputs,
    uint8_t** p_key_buffer, size_t *key_buffer_size,
const psa_key_attributes_t *attributes);
psa_status_t psa_crypto_driver_pake_get_role( psa_status_t psa_crypto_driver_pake_get_role(
    const psa_crypto_driver_pake_inputs_t *inputs,     const psa_crypto_driver_pake_inputs_t *inputs,
    psa_pake_role_t *role);     psa_pake_role_t *role);
@@ -385,13 +390,13 @@ Next parameters are return buffers (must not be null pointers).
These functions can return the following statuses: These functions can return the following statuses:
* `PSA_SUCCESS`: value has been successfully obtained * `PSA_SUCCESS`: value has been successfully obtained
* `PSA_ERROR_BAD_STATE`: the inputs are not ready * `PSA_ERROR_BAD_STATE`: the inputs are not ready
* `PSA_ERROR_BUFFER_TOO_SMALL` (`psa_crypto_driver_pake_get_password` only): the output buffer is too small. This is not a fatal error and the driver can, for example, subsequently call the same function again with a larger buffer. Call `psa_crypto_driver_pake_get_password_len` to obtain the required size. * `PSA_ERROR_BUFFER_TOO_SMALL` (`psa_crypto_driver_pake_get_password_bytes` and `psa_crypto_driver_pake_get_password_key` only): the output buffer is too small. This is not a fatal error and the driver can, for example, subsequently call the same function again with a larger buffer. Call `psa_crypto_driver_pake_get_password_len` to obtain the required size.
#### PAKE driver setup #### PAKE driver setup
``` ```
psa_status_t acme_psa_pake_setup( acme_pake_operation_t *operation, psa_status_t acme_pake_setup( acme_pake_operation_t *operation,
                                  const psa_crypto_driver_pake_inputs_t *inputs );                               const psa_crypto_driver_pake_inputs_t *inputs );
``` ```
* `operation` is a zero-initialized operation object. * `operation` is a zero-initialized operation object.
@@ -399,6 +404,8 @@ psa_status_t acme_psa_pake_setup( acme_pake_operation_t *operation,
The setup driver function should preserve the inputs using get-data functions. The setup driver function should preserve the inputs using get-data functions.
The pointer output by `psa_crypto_driver_pake_get_password_key` is only valid until the "pake_setup" entry point returns. Opaque drivers must copy all relevant data from the key buffer during the "pake_setup" entry point and must not store the pointer itself.
#### PAKE driver output #### PAKE driver output
``` ```