libmbedtls/mbedtls/README.md

6 Mbed TLS includes a reference implementation of the [PSA Cryptography API](#psa-cryptography-api). …
9 -------------
11 …on most systems. Some platform specific options are available in the fully documented configuratio…
15 We provide some non-standard configurations focused on specific use cases in the `configs/` directo…
18 -------------
20 The main Mbed TLS documentation is available via [ReadTheDocs](https://mbed-tls.readthedocs.io/).
22 …mentation for the PSA Cryptography API is available [on GitHub](https://arm-software.github.io/psa…
24 To generate a local copy of the library documentation in HTML format, tailored to your compile-time…
33 ---------
37 -   GNU Make
38 -   CMake
39 -   Microsoft Visual Studio
41 …velopment are CMake and GNU Make. Those systems are always complete and up-to-date. The others sho…
43 …on libmbedx509 and libmbedcrypto, and libmbedx509 depends on libmbedcrypto. As a result, some link…
59 …-3.6` long-term support branch of Mbed TLS use a [Git submodule](https://git-scm.com/book/en/v2/Gi…
63 …generated by scripts and whose content depends only on the Mbed TLS source, not on the platform or…
70     python3 -m pip install --user -r scripts/basic.requirements.txt
72 …Depending on your Python installation, you may need to invoke `python` instead of `python3`. To in…
75 …you are cross-compiling, you must set the `CC` environment variable to a C compiler for the host p…
77 Any of the following methods are available to generate the configuration-independent files:
79 * If not cross-compiling, running `make` with any target, or just `make`, will automatically genera…
80 * On non-Windows systems, when not cross-compiling, CMake will generate the required files automati…
81 * Run `make generated_files` to generate all the configuration-independent files.
82 * On Unix/POSIX systems, run `tests/scripts/check-generated-files.sh -u` to generate all the config…
83 * On Windows, run `scripts\make_generated_files.bat` to generate all the configuration-independent …
107 …-like (for instance when cross-compiling, or compiling from an MSYS shell), and `WINDOWS=1` if the…
109 …on the make command line; compiler warning options may be overridden separately using `WARNING_CFL…
111 …-O2` and setting `WARNING_CFLAGS` overrides its default value (starting with `-Wall -Wextra`), so …
113 …on your platform, you might run into some issues. Please check the Makefiles in `library/`, `progr…
115 …us know what, so we can add it to the [Mbed TLS Knowledge Base](https://mbed-tls.readthedocs.io/en…
123     cmake --build .
131     cmake -DENABLE_TESTING=Off /path/to/mbedtls_source
139     cmake -DUSE_SHARED_MBEDTLS_LIBRARY=On /path/to/mbedtls_source
141 …CMake buildsystem. Most of them are available for gcc and clang, though some are compiler-specific:
143 -   `Release`. This generates the default code without any unnecessary information in the binary fi…
144 -   `Debug`. This generates debug information and disables optimization of the code.
145 -   `Coverage`. This generates code coverage information in addition to debug information.
146 -   `ASan`. This instruments the code with AddressSanitizer to check for memory errors. (This inclu…
147 -   `ASanDbg`. Same as ASan but slower, with debug information and better stack traces.
148 -   `MemSan`. This instruments the code with MemorySanitizer to check for uninitialised memory read…
149 -   `MemSanDbg`. Same as MemSan but slower, with debug information, better stack traces and origin …
150 -   `Check`. This activates the compiler warnings that depend on optimization and treats all warnin…
154     cmake -D CMAKE_BUILD_TYPE=Debug /path/to/mbedtls_source
158     cmake -LH
171 Note that it is possible to build in-place; this will however overwrite the
182     find . -iname '*cmake*' -not -name CMakeLists.txt -exec rm -rf {} +
191 on the build mode as seen above), it's merely prepended to it.
203 - `MbedTLS::mbedcrypto` (Crypto library)
204 - `MbedTLS::mbedtls` (TLS library)
205 - `MbedTLS::mbedx509` (X509 library)
232 …enerated source files in the development branch”](#generated-source-files-in-the-development-branc…
235 ----------------
238 …fic features of the library, and the code may need to be adapted to build a real-world application.
241 -----
247 -   `tests/ssl-opt.sh` runs integration tests for various TLS options (renegotiation, resumption, e…
248 -   `tests/compat.sh` tests interoperability of every ciphersuite with other implementations.
249 -   `tests/scripts/test-ref-configs.pl` test builds in various reduced configurations.
250 -   `tests/scripts/depends.py` test builds in configurations with a single curve, key exchange, has…
251 -   `tests/scripts/all.sh` runs a combination of the above tests, plus some more, with various buil…
253 …ing infrastructure repository](https://github.com/Mbed-TLS/mbedtls-test/blob/main/README.md#quick-…
256 ----------------
260 -   [Porting Mbed TLS to a new environment or OS](https://mbed-tls.readthedocs.io/en/latest/kb/how-…
261 -   [What external dependencies does Mbed TLS rely on?](https://mbed-tls.readthedocs.io/en/latest/k…
262 -   [How do I configure Mbed TLS](https://mbed-tls.readthedocs.io/en/latest/kb/compiling-and-buildi…
266 - Bytes must be 8 bits.
267 - All-bits-zero must be a valid representation of a null pointer.
268 - Signed integers must be represented using two's complement.
269 - `int` and `size_t` must be at least 32 bits wide.
270 - The types `uint8_t`, `uint16_t`, `uint32_t` and their signed equivalents must be available.
271 - Mixed-endian platforms are not supported.
272 - SIZE_MAX must be at least as big as INT_MAX and UINT_MAX.
275 --------------------
279 …-architectures/platform-security-architecture) is a holistic set of threat models, security analys…
281 …-software.github.io/psa-api/crypto/) provides access to a set of cryptographic primitives. It has …
291 …on the design of the API. If you think something could be improved, please open an issue on our Gi…
298 … cryptography for most operations regardless of this option. See `docs/use-psa-crypto.md` for deta…
304 …ease see the [PSA driver example and guide](docs/psa-driver-example-and-guide.md) for information …
308 …y so that the X.509 and TLS code calls the PSA drivers rather than the built-in software implement…
312 -------
314 …-2.0](https://spdx.org/licenses/Apache-2.0.html) OR [GPL-2.0-or-later](https://spdx.org/licenses/G…
316 ### Third-party code included in Mbed TLS
320 * `3rdparty/everest/`: Files stem from [Project Everest](https://project-everest.github.io/) and ar…
321 …-m/p256-m/`: Files have been taken from the [p256-m](https://github.com/mpg/p256-m) repository. Th…
324 ------------
326 …community. Please see the [contributing guidelines](CONTRIBUTING.md) for details on how to do this.
329 -------
331 * To report a security vulnerability in Mbed TLS, please email <mbed-tls-security@lists.trustedfirm…
332 …ug or request a feature in Mbed TLS, please [file an issue on GitHub](https://github.com/Mbed-TLS/…