Merge pull request #8203 from gilles-peskine-arm/p256-m-production
Declare p256-m as ready for production
This commit is contained in:
commit
452beb9076
3 changed files with 39 additions and 13 deletions
5
ChangeLog.d/p256-m.txt
Normal file
5
ChangeLog.d/p256-m.txt
Normal file
|
@ -0,0 +1,5 @@
|
|||
Features
|
||||
* Applications using ECC over secp256r1 through the PSA API can use a
|
||||
new implementation with a much smaller footprint, but some minor
|
||||
usage restrictions. See the documentation of the new configuration
|
||||
option MBEDTLS_P256M_EXAMPLE_DRIVER_ENABLED for details.
|
|
@ -138,15 +138,20 @@ This guide assumes you are building Mbed TLS from source alongside your project.
|
|||
|
||||
### Example: Manually integrating a software accelerator alongside Mbed TLS
|
||||
|
||||
[p256-m](https://github.com/mpg/p256-m) is a minimalistic implementation of ECDH and ECDSA on the NIST P-256 curve, specifically optimized for use in constrained 32-bit environments. As such, it serves as a software accelerator. This section demonstrates the integration of `p256-m` as a transparent driver alongside Mbed TLS, serving as a guide for implementation.
|
||||
The code for p256-m can be found in `3rdparty/p256-m/p256m`. In this demonstration, p256-m is built from source alongside Mbed TLS.
|
||||
[p256-m](https://github.com/mpg/p256-m) is a minimalistic implementation of ECDH and ECDSA on the NIST P-256 curve, specifically optimized for use in constrained 32-bit environments. It started out as an independent project and has been integrated in Mbed TLS as a PSA transparent driver. The source code of p256-m and the driver entry points is located in the Mbed TLS source tree under `3rdparty/p256-m`. In this section, we will look at how this integration was done.
|
||||
|
||||
The driver prefix for p256-m is `P256`/`p256`. The driver macro is `MBEDTLS_P256M_EXAMPLE_DRIVER_ENABLED`. To build with and use p256-m, set the macro using `config.py`, then build as usual using make/cmake. From the root of the `mbedtls/` directory, run:
|
||||
The Mbed TLS build system includes the instructions needed to build p256-m. To build with and use p256-m, set the macro `MBEDTLS_P256M_EXAMPLE_DRIVER_ENABLED` using `config.py`, then build as usual using make/cmake. From the root of the `mbedtls/` directory, run:
|
||||
|
||||
python3 scripts/config.py set MBEDTLS_PSA_CRYPTO_CONFIG
|
||||
python3 scripts/config.py set MBEDTLS_P256M_EXAMPLE_DRIVER_ENABLED
|
||||
make
|
||||
|
||||
p256-m implements four entry points: `generate_key`, `key_agreement`, `sign_hash`, `verify_hash`. The `sign/verify_hash` entry points are used instead of `sign/verify_message` as messages must be hashed prior to any operation, and p256-m does not implement this. The driver entry point functions can be found in `p256m_driver_entrypoints.[hc]`. These functions act as an interface between Mbed TLS and p256-m; converting between PSA and p256-m argument formats and performing sanity checks. If the driver's status codes differ from PSA's, it is recommended to implement a status code translation function. The function `p256_to_psa_error()` converts error codes returned by p256-m into PSA error codes.
|
||||
(You need extra steps if you want to disable the built-in implementation of ECC algorithms, which includes more features than p256-m. Refer to the documentation of `MBEDTLS_P256M_EXAMPLE_DRIVER_ENABLED` for more information.)
|
||||
|
||||
The driver prefix for p256-m is `P256`/`p256`.
|
||||
The p256-m driver implements four entry points: `generate_key`, `key_agreement`, `sign_hash`, `verify_hash`.
|
||||
There are no entry points for `sign_message` and `verify_message`, which are not necessary for a sign-and-hash algorithm. The core still implements these functions by doing the hashes and then calling the sign/verify-hash entry points.
|
||||
The driver entry point functions can be found in `p256m_driver_entrypoints.[hc]`. These functions act as an interface between Mbed TLS and p256-m; converting between PSA and p256-m argument formats and performing sanity checks. If the driver's status codes differ from PSA's, it is recommended to implement a status code translation function. The function `p256_to_psa_error()` converts error codes returned by p256-m into PSA error codes.
|
||||
|
||||
The driver wrapper functions in `psa_crypto_driver_wrappers.c.jinja` for all four entry points have also been modified. The code block below shows the additions made to `psa_driver_wrapper_sign_hash()`. In adherence to the defined process, all code related to the driver call is placed within a check for `MBEDTLS_P256M_EXAMPLE_DRIVER_ENABLED`. p256-m only supports non-deterministic ECDSA using keys based on NIST P256; these constraints are enforced through checks (see the `if` statement). Checks that involve accessing key attributes, (e.g. checking key type or bits) **must** be performed in the driver wrapper. This is because this information is marked private and may not be accessed outside the library. Other checks can be performed here or in the entry point function. The status returned by the driver is propagated up the call hierarchy **unless** the driver does not support the operation (i.e. return `PSA_ERROR_NOT_SUPPORTED`). In that case the next available driver/built-in implementation is called.
|
||||
|
||||
|
|
|
@ -856,16 +856,32 @@
|
|||
//#define MBEDTLS_ECP_WITH_MPI_UINT
|
||||
|
||||
/**
|
||||
* Uncomment to enable p256-m, which implements ECC key generation, ECDH,
|
||||
* and ECDSA for SECP256R1 curves. This driver is used as an example to
|
||||
* document how a third-party driver or software accelerator can be integrated
|
||||
* to work alongside Mbed TLS.
|
||||
* Uncomment to enable p256-m. This is an alternative implementation of
|
||||
* key generation, ECDH and (randomized) ECDSA on the curve SECP256R1.
|
||||
* Compared to the default implementation:
|
||||
*
|
||||
* \warning p256-m has only been included to serve as a sample implementation
|
||||
* of how a driver/accelerator can be integrated alongside Mbed TLS. It is not
|
||||
* intended for use in production. p256-m files in Mbed TLS are not updated
|
||||
* regularly, so they may not contain upstream fixes/improvements.
|
||||
* DO NOT ENABLE/USE THIS MACRO IN PRODUCTION BUILDS!
|
||||
* - p256-m has a much smaller code size and RAM footprint.
|
||||
* - p256-m is only available via the PSA API. This includes the pk module
|
||||
* when #MBEDTLS_USE_PSA_CRYPTO is enabled.
|
||||
* - p256-m does not support deterministic ECDSA, EC-JPAKE, custom protocols
|
||||
* over the core arithmetic, or deterministic derivation of keys.
|
||||
*
|
||||
* We recommend enabling this option if your application uses the PSA API
|
||||
* and the only elliptic curve support it needs is ECDH and ECDSA over
|
||||
* SECP256R1.
|
||||
*
|
||||
* If you enable this option, you do not need to enable any ECC-related
|
||||
* MBEDTLS_xxx option. You do need to separately request support for the
|
||||
* cryptographic mechanisms through the PSA API:
|
||||
* - #MBEDTLS_PSA_CRYPTO_C and #MBEDTLS_PSA_CRYPTO_CONFIG for PSA-based
|
||||
* configuration;
|
||||
* - #MBEDTLS_USE_PSA_CRYPTO if you want to use p256-m from PK, X.509 or TLS;
|
||||
* - #PSA_WANT_ECC_SECP_R1_256;
|
||||
* - #PSA_WANT_ALG_ECDH and/or #PSA_WANT_ALG_ECDSA as needed;
|
||||
* - #PSA_WANT_KEY_TYPE_ECC_PUBLIC_KEY, #PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_BASIC,
|
||||
* #PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_IMPORT,
|
||||
* #PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_EXPORT and/or
|
||||
* #PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_GENERATE as needed.
|
||||
*/
|
||||
//#define MBEDTLS_P256M_EXAMPLE_DRIVER_ENABLED
|
||||
|
||||
|
|
Loading…
Reference in a new issue