libmbedtls/mbedtls/README.md

24 To generate a local copy of the library documentation in HTML format, tailored to your compile-time…
41 …velopment are CMake and GNU Make. Those systems are always complete and up-to-date. The others sho…
43 …x509 depends on libmbedcrypto. As a result, some linkers will expect flags to be in a specific ord…
47 You need the following tools to build the library with the provided makefiles:
51 * Python 3.8 to generate the test code. Python is also needed to integrate PSA drivers and to build…
52 * Perl to run the tests, and to generate some source files in the development branch.
59 …S/mbedtls-framework)). This is not needed to merely compile the library at a release tag. This is …
63 …nerated files are included in official releases. This section explains how to generate the missing…
72 …Depending on your Python installation, you may need to invoke `python` instead of `python3`. To in…
75 If you are cross-compiling, you must set the `CC` environment variable to a C compiler for the host…
77 Any of the following methods are available to generate the configuration-independent files:
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 …
89 …to keep them as simple and independent of different toolchains as possible, to allow users to more…
91 In order to build from the source code using GNU Make, just enter at the command line:
95 In order to run the tests, enter:
99 The tests need Python to be built and Perl to be run. If you don't have one of them installed, you …
103 You'll still be able to run a much smaller set of tests with:
107 In order to build for a Windows platform, you should use `WINDOWS_BUILD=1` if the target is Windows…
109 Setting the variable `SHARED` in your environment will build shared libraries in addition to the st…
111 …to add some warning options to the default ones, you can do so by setting `CFLAGS=-O2 -Werror` for…
113 …se check the Makefiles in `library/`, `programs/` and `tests/` for options to manually add or remo…
115 In case you find that you need to do something else as well, please let us know what, so we can add…
119 In order to build the source using CMake in a separate directory (recommended), just enter at the c…
121     mkdir /path/to/build_dir && cd /path/to/build_dir
122     cmake /path/to/mbedtls_source
125 In order to run the tests, enter:
129 The test suites need Python to be built and Perl to be executed. If you don't have one of these ins…
131     cmake -DENABLE_TESTING=Off /path/to/mbedtls_source
139     cmake -DUSE_SHARED_MBEDTLS_LIBRARY=On /path/to/mbedtls_source
145 -   `Coverage`. This generates code coverage information in addition to debug information.
146 …to check for memory errors. (This includes LeakSanitizer, with recent version of gcc and clang.) (…
148 -   `MemSan`. This instruments the code with MemorySanitizer to check for uninitialised memory read…
154     cmake -D CMAKE_BUILD_TYPE=Debug /path/to/mbedtls_source
163 These variables need to be adjusted when invoking cmake for the first time,
166     CC=your_cc cmake /path/to/mbedtls_source
168 If you already invoked cmake and want to change those settings, you need to
171 Note that it is possible to build in-place; this will however overwrite the
172 provided Makefiles (see `scripts/tmp_ignore_makefiles.sh` if you want to
173 prevent `git status` from showing them as modified). In order to do so, from
179 If you want to change `CC` or `CFLAGS` afterwards, you will need to remove the
191 on the build mode as seen above), it's merely prepended to it.
200 If prompted, set `MbedTLS_DIR` to `${YOUR_MBEDTLS_INSTALL_DIR}/cmake`. This
216 This will link the Mbed TLS libraries to your library or application, and add
217 its include directories to your target (transitively, in the case of `PUBLIC` or
223 use `add_subdirectory()` from a parent CMake project to include Mbed TLS as a
230 The solution file `mbedTLS.sln` contains all the basic projects needed to build the library and all…
232 In the development branch of Mbed TLS, the Visual Studio solution files need to be generated first …
238 …goal of these sample programs is to demonstrate specific features of the library, and the code may…
243 …to generate the tests files (e.g. `test\_suite\_mpi.c`). These files are generated from a `functio…
253 …ng the required versions of all tools required for testing, it is possible to use the Docker image…
258 Mbed TLS can be ported to many different architectures, OS's and platforms. Before starting a port,…
260 -   [Porting Mbed TLS to a new environment or OS](https://mbed-tls.readthedocs.io/en/latest/kb/how-…
279 …A provides a recipe, based on industry best practice, that allows security to be consistently desi…
281 …o/) provides access to a set of cryptographic primitives. It has a dual purpose. First, it can be …
285 * The API distinguishes caller memory from internal memory, which allows the library to be implemen…
286 …ata is hidden to the application, which allows substituting alternative implementations at build t…
287 * All access to the keys happens through key identifiers, which allows support for external cryptop…
288 * The interface to algorithms is generic, favoring algorithm agility.
289 * The interface is designed to be easy to use and hard to accidentally misuse.
291 …lease open an issue on our Github repository. Alternatively, if you prefer to provide your feedbac…
296 However, it does not aim to implement the whole specification; in particular it does not implement …
302 …ice. We intend to preserve backward compatibility for application code (using the PSA Crypto API),…
306 When using drivers, you will generally want to enable two compilation options (see the reference ma…
309 * `MBEDTLS_PSA_CRYPTO_CONFIG` allows you to enable PSA cryptographic mechanisms without including t…
326 …community. Please see the [contributing guidelines](CONTRIBUTING.md) for details on how to do this.