blob: 7981a0236d518d8a592c377c1182e7121d5ddaef [file] [log] [blame] [view]
Ron Eldorc7acb912017-10-30 17:03:57 +02001README for Mbed TLS
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +02002===================
3
Dan Handley20579b72020-02-19 09:34:20 +00004Mbed TLS is a C library that implements cryptographic primitives, X.509 certificate manipulation and the SSL/TLS and DTLS protocols. Its small code footprint makes it suitable for embedded systems.
5
Gilles Peskine8b13d262020-03-09 19:18:15 +01006Mbed TLS includes a reference implementation of the [PSA Cryptography API](#psa-cryptography-api). This is currently a preview for evaluation purposes only.
Gilles Peskineda5abbf2020-03-09 18:51:37 +01007
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +02008Configuration
9-------------
10
Bence Szépkútibb0cfeb2021-05-28 09:42:25 +020011Mbed TLS should build out of the box on most systems. Some platform specific options are available in the fully documented configuration file `include/mbedtls/mbedtls_config.h`, which is also the place where features can be selected. This file can be edited manually, or in a more programmatic way using the Python 3 script `scripts/config.py` (use `--help` for usage instructions).
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +020012
Simon Butcher741f2302016-09-04 16:01:32 +010013Compiler options can be set using conventional environment variables such as `CC` and `CFLAGS` when using the Make and CMake build system (see below).
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +020014
Gilles Peskineb05d89d2020-03-09 19:23:51 +010015We provide some non-standard configurations focused on specific use cases in the `configs/` directory. You can read more about those in `configs/README.txt`
16
Gilles Peskinea10cbda2020-03-09 19:21:51 +010017Documentation
18-------------
19
Dave Rodgman7c195162022-10-12 16:27:14 +010020The main Mbed TLS documentation is available via [ReadTheDocs](https://mbed-tls.readthedocs.io/).
21
Dave Rodgman12cee782022-10-31 15:34:11 +000022Documentation for the PSA Cryptography API is available [on GitHub](https://arm-software.github.io/psa-api/crypto/).
Gilles Peskinea10cbda2020-03-09 19:21:51 +010023
24To generate a local copy of the library documentation in HTML format, tailored to your compile-time configuration:
25
Dave Rodgman2f458d32021-06-03 17:58:13 +0100261. Make sure that [Doxygen](http://www.doxygen.nl/) is installed.
Gilles Peskinea10cbda2020-03-09 19:21:51 +0100271. Run `make apidoc`.
281. Browse `apidoc/index.html` or `apidoc/modules.html`.
29
Manuel Pégourié-Gonnard80c02af2021-02-25 12:34:58 +010030For other sources of documentation, see the [SUPPORT](SUPPORT.md) document.
31
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +020032Compiling
33---------
34
Simon Butcher3ad2efd2018-05-02 14:49:38 +010035There are currently three active build systems used within Mbed TLS releases:
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +020036
Gilles Peskine82759aa2017-06-16 14:52:39 +020037- GNU Make
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +020038- CMake
Dave Rodgman2f458d32021-06-03 17:58:13 +010039- Microsoft Visual Studio
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +020040
Gilles Peskine82759aa2017-06-16 14:52:39 +020041The main systems used for development are CMake and GNU Make. Those systems are always complete and up-to-date. The others should reflect all changes present in the CMake and Make build system, although features may not be ported there automatically.
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +020042
Ronald Cron8126a682024-10-25 17:34:23 +020043The Make and CMake build systems create three libraries: libmbedcrypto/libtfpsacrypto, libmbedx509, and libmbedtls. Note that libmbedtls depends on libmbedx509 and libmbedcrypto/libtfpsacrypto, and libmbedx509 depends on libmbedcrypto/libtfpsacrypto. As a result, some linkers will expect flags to be in a specific order, for example the GNU linker wants `-lmbedtls -lmbedx509 -lmbedcrypto`.
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +020044
Gilles Peskine67698702020-03-09 19:30:08 +010045### Tool versions
46
47You need the following tools to build the library with the provided makefiles:
48
Dave Rodgman2f458d32021-06-03 17:58:13 +010049* GNU Make 3.82 or a build tool that CMake supports.
Bence Szépkútiae0d97a2024-03-12 17:23:01 +010050* A C99 toolchain (compiler, linker, archiver). We actively test with GCC 5.4, Clang 3.8, Arm Compiler 6, IAR 8 and Visual Studio 2017. More recent versions should work. Slightly older versions may work.
Gilles Peskine95834692023-07-03 17:59:37 +020051* Python 3.8 to generate the test code. Python is also needed to integrate PSA drivers and to build the development branch (see next section).
Gilles Peskined05a5882021-05-17 23:57:42 +020052* Perl to run the tests, and to generate some source files in the development branch.
Dave Rodgman2f458d32021-06-03 17:58:13 +010053* CMake 3.10.2 or later (if using CMake).
Bence Szépkútiae0d97a2024-03-12 17:23:01 +010054* Microsoft Visual Studio 2017 or later (if using Visual Studio).
Dave Rodgman2f458d32021-06-03 17:58:13 +010055* Doxygen 1.8.11 or later (if building the documentation; slightly older versions should work).
Gilles Peskined05a5882021-05-17 23:57:42 +020056
Gilles Peskine0c3f0e92024-03-04 15:54:54 +010057### Git usage
58
Gilles Peskine93b28222024-03-13 13:08:57 +010059The `development` branch and the `mbedtls-3.6` long-term support branch of Mbed TLS use a [Git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules#_cloning_submodules) ([framework](https://github.com/Mbed-TLS/mbedtls-framework)). This is not needed to merely compile the library at a release tag. This is not needed to consume a release archive (zip or tar).
Gilles Peskine0c3f0e92024-03-04 15:54:54 +010060
Gilles Peskined05a5882021-05-17 23:57:42 +020061### Generated source files in the development branch
62
63The source code of Mbed TLS includes some files that are automatically generated by scripts and whose content depends only on the Mbed TLS source, not on the platform or on the library configuration. These files are not included in the development branch of Mbed TLS, but the generated files are included in official releases. This section explains how to generate the missing files in the development branch.
64
65The following tools are required:
66
67* Perl, for some library source files and for Visual Studio build files.
Gilles Peskine95834692023-07-03 17:59:37 +020068* Python 3.8 and some Python packages, for some library source files, sample programs and test data. To install the necessary packages, run:
Gilles Peskine87485a32021-11-17 19:17:03 +010069 ```
Gilles Peskine429e9012023-03-07 20:40:04 +010070 python3 -m pip install --user -r scripts/basic.requirements.txt
Gilles Peskine87485a32021-11-17 19:17:03 +010071 ```
Gilles Peskine429e9012023-03-07 20:40:04 +010072 Depending on your Python installation, you may need to invoke `python` instead of `python3`. To install the packages system-wide, omit the `--user` option.
Gilles Peskined05a5882021-05-17 23:57:42 +020073* A C compiler for the host platform, for some test data.
74
David Horstmann24e33882025-08-19 16:56:25 +010075The scripts that generate the configuration-independent files will look for a host C compiler in the following places (in order of preference):
76
771. The `HOSTCC` environment variable. This can be used if `CC` is pointing to a cross-compiler.
782. The `CC` environment variable.
793. An executable called `cc` in the current path.
80
81Note: If you have multiple toolchains installed, it is recommended to set `CC` or `HOSTCC` to the intended host compiler before generating the files.
Gilles Peskined05a5882021-05-17 23:57:42 +020082
83Any of the following methods are available to generate the configuration-independent files:
84
85* If not cross-compiling, running `make` with any target, or just `make`, will automatically generate required files.
David Horstmann48a05532021-10-22 15:10:46 +010086* On non-Windows systems, when not cross-compiling, CMake will generate the required files automatically.
Gilles Peskined05a5882021-05-17 23:57:42 +020087* Run `make generated_files` to generate all the configuration-independent files.
Ronald Cron444db892025-03-27 11:36:08 +010088* On Unix/POSIX systems, run `framework/scripts/make_generated_files.py` to generate all the configuration-independent files.
Gilles Peskined05a5882021-05-17 23:57:42 +020089* On Windows, run `scripts\make_generated_files.bat` to generate all the configuration-independent files.
Gilles Peskine67698702020-03-09 19:30:08 +010090
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +020091### Make
92
Gilles Peskine82759aa2017-06-16 14:52:39 +020093We require GNU Make. To build the library and the sample programs, GNU Make and a C compiler are sufficient. Some of the more advanced build targets require some Unix/Linux tools.
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +020094
Gilles Peskineec82da42017-10-02 10:52:50 +020095We intentionally only use a minimum of functionality in the makefiles in order to keep them as simple and independent of different toolchains as possible, to allow users to more easily move between different platforms. Users who need more features are recommended to use CMake.
96
Gilles Peskine82759aa2017-06-16 14:52:39 +020097In order to build from the source code using GNU Make, just enter at the command line:
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +020098
99 make
100
101In order to run the tests, enter:
102
103 make check
104
Ron Eldor276bd002019-01-17 17:51:55 -0600105The tests need Python to be built and Perl to be run. If you don't have one of them installed, you can skip building the tests with:
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +0200106
107 make no_test
108
109You'll still be able to run a much smaller set of tests with:
110
111 programs/test/selftest
112
113In order to build for a Windows platform, you should use `WINDOWS_BUILD=1` if the target is Windows but the build environment is Unix-like (for instance when cross-compiling, or compiling from an MSYS shell), and `WINDOWS=1` if the build environment is a Windows shell (for instance using mingw32-make) (in that case some targets will not be available).
114
Manuel Pégourié-Gonnard05c92712017-12-28 09:14:47 +0100115Setting the variable `SHARED` in your environment will build shared libraries in addition to the static libraries. Setting `DEBUG` gives you a debug build. You can override `CFLAGS` and `LDFLAGS` by setting them in your environment or on the make command line; compiler warning options may be overridden separately using `WARNING_CFLAGS`. Some directory-specific options (for example, `-I` directives) are still preserved.
116
Gilles Peskine85aba472019-07-02 20:03:01 +0200117Please note that setting `CFLAGS` overrides its default value of `-O2` and setting `WARNING_CFLAGS` overrides its default value (starting with `-Wall -Wextra`), so if you just want to add some warning options to the default ones, you can do so by setting `CFLAGS=-O2 -Werror` for example. Setting `WARNING_CFLAGS` is useful when you want to get rid of its default content (for example because your compiler doesn't accept `-Wall` as an option). Directory-specific options cannot be overridden from the command line.
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +0200118
Dave Rodgman7c195162022-10-12 16:27:14 +0100119Depending on your platform, you might run into some issues. Please check the Makefiles in `library/`, `programs/` and `tests/` for options to manually add or remove for specific platforms. You can also check [the Mbed TLS Knowledge Base](https://mbed-tls.readthedocs.io/en/latest/kb/) for articles on your platform or issue.
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +0200120
Dave Rodgman7c195162022-10-12 16:27:14 +0100121In case you find that you need to do something else as well, please let us know what, so we can add it to the [Mbed TLS Knowledge Base](https://mbed-tls.readthedocs.io/en/latest/kb/).
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +0200122
123### CMake
124
Manuel Pégourié-Gonnardb89c4722017-12-26 12:52:53 +0100125In order to build the source using CMake in a separate directory (recommended), just enter at the command line:
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +0200126
Manuel Pégourié-Gonnardb89c4722017-12-26 12:52:53 +0100127 mkdir /path/to/build_dir && cd /path/to/build_dir
128 cmake /path/to/mbedtls_source
Carlos Gomes Martinho227a9db2020-04-03 09:42:57 +0200129 cmake --build .
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +0200130
131In order to run the tests, enter:
132
Carlos Gomes Martinho227a9db2020-04-03 09:42:57 +0200133 ctest
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +0200134
Ron Eldor276bd002019-01-17 17:51:55 -0600135The test suites need Python to be built and Perl to be executed. If you don't have one of these installed, you'll want to disable the test suites with:
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +0200136
Manuel Pégourié-Gonnardb89c4722017-12-26 12:52:53 +0100137 cmake -DENABLE_TESTING=Off /path/to/mbedtls_source
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +0200138
139If you disabled the test suites, but kept the programs enabled, you can still run a much smaller set of tests with:
140
141 programs/test/selftest
142
143To configure CMake for building shared libraries, use:
144
Manuel Pégourié-Gonnardb89c4722017-12-26 12:52:53 +0100145 cmake -DUSE_SHARED_MBEDTLS_LIBRARY=On /path/to/mbedtls_source
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +0200146
147There are many different build modes available within the CMake buildsystem. Most of them are available for gcc and clang, though some are compiler-specific:
148
Gilles Peskineb21a0852018-03-09 14:24:36 +0100149- `Release`. This generates the default code without any unnecessary information in the binary files.
150- `Debug`. This generates debug information and disables optimization of the code.
151- `Coverage`. This generates code coverage information in addition to debug information.
152- `ASan`. This instruments the code with AddressSanitizer to check for memory errors. (This includes LeakSanitizer, with recent version of gcc and clang.) (With recent version of clang, this mode also instruments the code with UndefinedSanitizer to check for undefined behaviour.)
153- `ASanDbg`. Same as ASan but slower, with debug information and better stack traces.
154- `MemSan`. This instruments the code with MemorySanitizer to check for uninitialised memory reads. Experimental, needs recent clang on Linux/x86\_64.
155- `MemSanDbg`. Same as MemSan but slower, with debug information, better stack traces and origin tracking.
156- `Check`. This activates the compiler warnings that depend on optimization and treats all warnings as errors.
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +0200157
158Switching build modes in CMake is simple. For debug mode, enter at the command line:
159
Manuel Pégourié-Gonnardb89c4722017-12-26 12:52:53 +0100160 cmake -D CMAKE_BUILD_TYPE=Debug /path/to/mbedtls_source
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +0200161
162To list other available CMake options, use:
163
164 cmake -LH
165
Manuel Pégourié-Gonnard976dd162018-01-02 10:49:46 +0100166Note that, with CMake, you can't adjust the compiler or its flags after the
Manuel Pégourié-Gonnardb89c4722017-12-26 12:52:53 +0100167initial invocation of cmake. This means that `CC=your_cc make` and `make
168CC=your_cc` will *not* work (similarly with `CFLAGS` and other variables).
169These variables need to be adjusted when invoking cmake for the first time,
170for example:
171
172 CC=your_cc cmake /path/to/mbedtls_source
173
174If you already invoked cmake and want to change those settings, you need to
175remove the build directory and create it again.
176
177Note that it is possible to build in-place; this will however overwrite the
178provided Makefiles (see `scripts/tmp_ignore_makefiles.sh` if you want to
179prevent `git status` from showing them as modified). In order to do so, from
180the Mbed TLS source directory, use:
181
182 cmake .
183 make
184
185If you want to change `CC` or `CFLAGS` afterwards, you will need to remove the
186CMake cache. This can be done with the following command using GNU find:
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +0200187
188 find . -iname '*cmake*' -not -name CMakeLists.txt -exec rm -rf {} +
Manuel Pégourié-Gonnardb89c4722017-12-26 12:52:53 +0100189
Manuel Pégourié-Gonnard976dd162018-01-02 10:49:46 +0100190You can now make the desired change:
Manuel Pégourié-Gonnardb89c4722017-12-26 12:52:53 +0100191
192 CC=your_cc cmake .
193 make
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +0200194
Manuel Pégourié-Gonnard05c92712017-12-28 09:14:47 +0100195Regarding variables, also note that if you set CFLAGS when invoking cmake,
196your value of CFLAGS doesn't override the content provided by cmake (depending
197on the build mode as seen above), it's merely prepended to it.
198
Chris Kayd259e342021-03-25 16:03:25 +0000199#### Consuming Mbed TLS
200
201Mbed TLS provides a package config file for consumption as a dependency in other
202CMake projects. You can include Mbed TLS's CMake targets yourself with:
203
204 find_package(MbedTLS)
205
206If prompted, set `MbedTLS_DIR` to `${YOUR_MBEDTLS_INSTALL_DIR}/cmake`. This
207creates the following targets:
208
Ronald Cron8126a682024-10-25 17:34:23 +0200209- `MbedTLS::tfpsacrypto` (Crypto library)
Chris Kayd259e342021-03-25 16:03:25 +0000210- `MbedTLS::mbedtls` (TLS library)
211- `MbedTLS::mbedx509` (X509 library)
212
213You can then use these directly through `target_link_libraries()`:
214
215 add_executable(xyz)
216
217 target_link_libraries(xyz
218 PUBLIC MbedTLS::mbedtls
Ronald Cron8126a682024-10-25 17:34:23 +0200219 MbedTLS::tfpsacrypto
Chris Kayd259e342021-03-25 16:03:25 +0000220 MbedTLS::mbedx509)
221
222This will link the Mbed TLS libraries to your library or application, and add
223its include directories to your target (transitively, in the case of `PUBLIC` or
224`INTERFACE` link libraries).
225
Jaeden Amero41421c42019-06-20 17:26:29 +0100226#### Mbed TLS as a subproject
227
Manuel Pégourié-Gonnarda4b99a22020-03-19 12:36:02 +0100228Mbed TLS supports being built as a CMake subproject. One can
Jaeden Amero41421c42019-06-20 17:26:29 +0100229use `add_subdirectory()` from a parent CMake project to include Mbed TLS as a
230subproject.
231
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +0200232### Microsoft Visual Studio
233
Bence Szépkútiae0d97a2024-03-12 17:23:01 +0100234The build files for Microsoft Visual Studio are generated for Visual Studio 2017.
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +0200235
Ron Eldor276bd002019-01-17 17:51:55 -0600236The solution file `mbedTLS.sln` contains all the basic projects needed to build the library and all the programs. The files in tests are not generated and compiled, as these need Python and perl environments as well. However, the selftest program in `programs/test/` is still available.
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +0200237
Gilles Peskined05a5882021-05-17 23:57:42 +0200238In the development branch of Mbed TLS, the Visual Studio solution files need to be generated first as described in [“Generated source files in the development branch”](#generated-source-files-in-the-development-branch).
239
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +0200240Example programs
241----------------
242
Gilles Peskinecf63f592020-03-09 19:24:18 +0100243We've included example programs for a lot of different features and uses in [`programs/`](programs/README.md).
244Please note that the goal of these sample programs is to demonstrate specific features of the library, and the code may need to be adapted to build a real-world application.
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +0200245
246Tests
247-----
248
Ronald Croncf1af5a2024-07-12 19:32:58 +0200249Mbed TLS includes an elaborate test suite in `tests/` that initially requires Python to generate the tests files (e.g. `test\_suite\_ssl.c`). These files are generated from a `function file` (e.g. `suites/test\_suite\_ssl.function`) and a `data file` (e.g. `suites/test\_suite\_ssl.data`). The `function file` contains the test functions. The `data file` contains the test cases, specified as parameters that will be passed to the test function.
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +0200250
251For machines with a Unix shell and OpenSSL (and optionally GnuTLS) installed, additional test scripts are available:
252
253- `tests/ssl-opt.sh` runs integration tests for various TLS options (renegotiation, resumption, etc.) and tests interoperability of these options with other implementations.
254- `tests/compat.sh` tests interoperability of every ciphersuite with other implementations.
255- `tests/scripts/test-ref-configs.pl` test builds in various reduced configurations.
Andrzej Kurek29c002e2022-10-24 10:59:55 -0400256- `tests/scripts/depends.py` test builds in configurations with a single curve, key exchange, hash, cipher, or pkalg on.
Bence Szépkútibb0cfeb2021-05-28 09:42:25 +0200257- `tests/scripts/all.sh` runs a combination of the above tests, plus some more, with various build options (such as ASan, full `mbedtls_config.h`, etc).
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +0200258
Dave Rodgman0da8c512024-03-18 15:25:53 +0000259Instead of manually installing the required versions of all tools required for testing, it is possible to use the Docker images from our CI systems, as explained in [our testing infrastructure repository](https://github.com/Mbed-TLS/mbedtls-test/blob/main/README.md#quick-start).
Manuel Pégourié-Gonnard59626b62022-12-15 10:08:26 +0100260
Ron Eldorc7acb912017-10-30 17:03:57 +0200261Porting Mbed TLS
Andres AG1a6e9c32016-12-28 15:38:05 +0000262----------------
263
Simon Butcher6965f772018-07-23 23:57:07 +0100264Mbed TLS can be ported to many different architectures, OS's and platforms. Before starting a port, you may find the following Knowledge Base articles useful:
Andres AG1a6e9c32016-12-28 15:38:05 +0000265
Dave Rodgman7c195162022-10-12 16:27:14 +0100266- [Porting Mbed TLS to a new environment or OS](https://mbed-tls.readthedocs.io/en/latest/kb/how-to/how-do-i-port-mbed-tls-to-a-new-environment-OS/)
267- [What external dependencies does Mbed TLS rely on?](https://mbed-tls.readthedocs.io/en/latest/kb/development/what-external-dependencies-does-mbedtls-rely-on/)
268- [How do I configure Mbed TLS](https://mbed-tls.readthedocs.io/en/latest/kb/compiling-and-building/how-do-i-configure-mbedtls/)
Andres AG1a6e9c32016-12-28 15:38:05 +0000269
Minos Galanakisc42cadb2021-12-09 13:16:54 +0000270Mbed TLS is mostly written in portable C99; however, it has a few platform requirements that go beyond the standard, but are met by most modern architectures:
271
Minos Galanakisd7547fc2021-12-09 15:06:16 +0000272- Bytes must be 8 bits.
minosgalanakis0f2a46c2021-12-09 15:38:39 +0000273- All-bits-zero must be a valid representation of a null pointer.
Minos Galanakisd7547fc2021-12-09 15:06:16 +0000274- Signed integers must be represented using two's complement.
275- `int` and `size_t` must be at least 32 bits wide.
276- The types `uint8_t`, `uint16_t`, `uint32_t` and their signed equivalents must be available.
Dave Rodgman28f424f2022-12-01 09:49:44 +0000277- Mixed-endian platforms are not supported.
Dave Rodgman37296a42023-02-10 15:39:22 +0000278- SIZE_MAX must be at least as big as INT_MAX and UINT_MAX.
Minos Galanakisc42cadb2021-12-09 13:16:54 +0000279
Gilles Peskineda5abbf2020-03-09 18:51:37 +0100280PSA cryptography API
281--------------------
282
Dave Rodgman12cee782022-10-31 15:34:11 +0000283### PSA API
Gilles Peskineda5abbf2020-03-09 18:51:37 +0100284
285Arm's [Platform Security Architecture (PSA)](https://developer.arm.com/architectures/security-architectures/platform-security-architecture) is a holistic set of threat models, security analyses, hardware and firmware architecture specifications, and an open source firmware reference implementation. PSA provides a recipe, based on industry best practice, that allows security to be consistently designed in, at both a hardware and firmware level.
286
Dave Rodgman12cee782022-10-31 15:34:11 +0000287The [PSA cryptography API](https://arm-software.github.io/psa-api/crypto/) provides access to a set of cryptographic primitives. It has a dual purpose. First, it can be used in a PSA-compliant platform to build services, such as secure boot, secure storage and secure communication. Second, it can also be used independently of other PSA components on any platform.
Gilles Peskineda5abbf2020-03-09 18:51:37 +0100288
289The design goals of the PSA cryptography API include:
290
291* The API distinguishes caller memory from internal memory, which allows the library to be implemented in an isolated space for additional security. Library calls can be implemented as direct function calls if isolation is not desired, and as remote procedure calls if isolation is desired.
292* The structure of internal data is hidden to the application, which allows substituting alternative implementations at build time or run time, for example, in order to take advantage of hardware accelerators.
Ronald Croncf56a0a2020-08-04 09:51:30 +0200293* All access to the keys happens through key identifiers, which allows support for external cryptoprocessors that is transparent to applications.
Gilles Peskineda5abbf2020-03-09 18:51:37 +0100294* The interface to algorithms is generic, favoring algorithm agility.
295* The interface is designed to be easy to use and hard to accidentally misuse.
296
297Arm welcomes feedback on the design of the API. If you think something could be improved, please open an issue on our Github repository. Alternatively, if you prefer to provide your feedback privately, please email us at [`mbed-crypto@arm.com`](mailto:mbed-crypto@arm.com). All feedback received by email is treated confidentially.
298
299### PSA implementation in Mbed TLS
300
301Mbed TLS includes a reference implementation of the PSA Cryptography API.
Manuel Pégourié-Gonnard2dc436d2022-06-08 10:09:51 +0200302However, it does not aim to implement the whole specification; in particular it does not implement all the algorithms.
Gilles Peskine8b13d262020-03-09 19:18:15 +0100303
Gilles Peskine17467c52023-04-25 21:14:31 +0200304### PSA drivers
Gilles Peskineda5abbf2020-03-09 18:51:37 +0100305
Gilles Peskine17467c52023-04-25 21:14:31 +0200306Mbed TLS supports drivers for cryptographic accelerators, secure elements and random generators. This is work in progress. Please note that the driver interfaces are not fully stable yet and may change without notice. We intend to preserve backward compatibility for application code (using the PSA Crypto API), but the code of the drivers may have to change in future minor releases of Mbed TLS.
Gilles Peskineda5abbf2020-03-09 18:51:37 +0100307
David Horstmanne3567292025-03-13 16:53:27 +0000308Please see the [PSA driver example and guide](https://github.com/Mbed-TLS/TF-PSA-Crypto/blob/development/docs/psa-driver-example-and-guide.md) for information on writing a driver.
Gilles Peskine17467c52023-04-25 21:14:31 +0200309
Dan Handleyc76a5452020-02-18 17:58:20 +0000310License
311-------
312
Dave Rodgman8ce51702023-11-02 17:36:49 +0000313Unless specifically indicated otherwise in a file, Mbed TLS files are provided under a dual [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html) OR [GPL-2.0-or-later](https://spdx.org/licenses/GPL-2.0-or-later.html) license. See the [LICENSE](LICENSE) file for the full text of these licenses, and [the 'License and Copyright' section in the contributing guidelines](CONTRIBUTING.md#License-and-Copyright) for more information.
Dan Handleyc76a5452020-02-18 17:58:20 +0000314
Aditya Deshpandef100f002023-03-21 14:49:31 +0000315### Third-party code included in Mbed TLS
Tom Cosgrovef884e602023-07-26 11:44:45 +0100316
Ronald Cronbdd8df82024-07-02 07:49:55 +0200317This project contains code from other projects. This code is located within the `tf-psa-crypto/drivers/` directory. The original license text is included within project subdirectories, where it differs from the normal Mbed TLS license, and/or in source files. The projects are listed below:
Aditya Deshpande8d99f252023-02-20 17:30:52 +0000318
Ronald Cronbdd8df82024-07-02 07:49:55 +0200319* `drivers/everest/`: Files stem from [Project Everest](https://project-everest.github.io/) and are distributed under the Apache 2.0 license.
320* `drivers/p256-m/p256-m/`: Files have been taken from the [p256-m](https://github.com/mpg/p256-m) repository. The code in the original repository is distributed under the Apache 2.0 license. It is distributed in Mbed TLS under a dual Apache-2.0 OR GPL-2.0-or-later license with permission from the author.
Aditya Deshpande8d99f252023-02-20 17:30:52 +0000321
Manuel Pégourié-Gonnardf851f142015-09-03 13:29:45 +0200322Contributing
323------------
324
Dan Handleyc76a5452020-02-18 17:58:20 +0000325We gratefully accept bug reports and contributions from the community. Please see the [contributing guidelines](CONTRIBUTING.md) for details on how to do this.
Gilles Peskineb6b15b22021-09-30 14:10:06 +0200326
327Contact
328-------
329
330* To report a security vulnerability in Mbed TLS, please email <mbed-tls-security@lists.trustedfirmware.org>. For more information, see [`SECURITY.md`](SECURITY.md).
Dave Rodgman017a1992022-03-31 14:07:01 +0100331* To report a bug or request a feature in Mbed TLS, please [file an issue on GitHub](https://github.com/Mbed-TLS/mbedtls/issues/new/choose).
Gilles Peskineb6b15b22021-09-30 14:10:06 +0200332* Please see [`SUPPORT.md`](SUPPORT.md) for other channels for discussion and support about Mbed TLS.