| 1 |
Building Mbed TLS with PSA cryptoprocessor drivers |
| 2 |
================================================== |
| 3 |
|
| 4 |
**This is a specification of work in progress. The implementation is not yet merged into Mbed TLS.** |
| 5 |
For a description of the current state of drivers Mbed TLS, see our [PSA Cryptoprocessor driver development examples](../psa-driver-example-and-guide.html). |
| 6 |
|
| 7 |
This document describes how to build Mbed TLS with additional cryptoprocessor drivers that follow the PSA cryptoprocessor driver interface. |
| 8 |
|
| 9 |
The interface is not fully implemented in Mbed TLS yet. Please note that the interface may still change: until further notice, we do not guarantee backward compatibility with existing driver code. |
| 10 |
|
| 11 |
## Introduction |
| 12 |
|
| 13 |
The PSA cryptography driver interface provides a way to build Mbed TLS with additional code that implements certain cryptographic primitives. This is primarily intended to support platform-specific hardware. |
| 14 |
|
| 15 |
Note that such drivers are only available through the PSA cryptography API (crypto functions beginning with `psa_`, and X.509 and TLS interfaces that reference PSA types). |
| 16 |
|
| 17 |
Concretely speaking, a driver consists of one or more **driver description files** in JSON format and some code to include in the build. The driver code can either be provided in binary form as additional object file to link, or in source form. |
| 18 |
|
| 19 |
## How to build Mbed TLS with drivers |
| 20 |
|
| 21 |
To build Mbed TLS with drivers: |
| 22 |
|
| 23 |
1. Pass the driver description files through the Make variable `PSA_DRIVERS` when building the library. |
| 24 |
|
| 25 |
``` |
| 26 |
cd /path/to/mbedtls |
| 27 |
make PSA_DRIVERS="/path/to/acme/driver.json /path/to/nadir/driver.json" lib |
| 28 |
``` |
| 29 |
|
| 30 |
2. Link your application with the implementation of the driver functions. |
| 31 |
|
| 32 |
``` |
| 33 |
cd /path/to/application |
| 34 |
ld myapp.o -L/path/to/acme -lacmedriver -L/path/to/nadir -lnadirdriver -L/path/to/mbedtls -lmbedcrypto |
| 35 |
``` |
| 36 |
|
| 37 |
<!-- TODO: what if the driver is provided as C source code? --> |
| 38 |
|
| 39 |
<!-- TODO: what about additional include files? --> |