Mbed-TLS / mbedtls

README for Mbed TLS =================== Mbed TLS is a C library that implements X.509 certificate manipulation and the TLS and DTLS protocols. Its small code footprint makes it suitable for embedded systems. Mbed TLS includes the TF-PSA-Crypto repository that provides an implementation of the PSA Cryptography API. Configuration ------------- Configuration options related to X.509 and TLS are available in , while cryptography and platform options are located in the TF-PSA-Crypto configuration file . With the default platform options, Mbed TLS should build out of the box on most systems. These configuration files can be edited manually, or programmatically using the Python script (run with --help for usage instructions). We provide some non-standard configurations focused on specific use cases in the directory. You can read more about those in . Documentation ------------- The main Mbed TLS documentation is available via ReadTheDocs. To generate a local copy of the library documentation in HTML format, tailored to your compile-time configuration: • Make sure that Doxygen is installed. • Run • Run • Open one of the main generated HTML files: • * or For other sources of documentation, see the SUPPORT document. Compiling --------- We use CMake to configure and drive our build process. Three libraries are built: , , and . Note that depends on and , and depends on . As a result, some linkers will expect flags to be in a specific order, for example the GNU linker wants . The cryptographic library is also provided under its legacy name, . Tool versions You need the following tools to build the library from the main branch with the provided CMake files. Mbed TLS minimum tool version requirements are set based on the versions shipped in the latest or penultimate (depending on the release cadence) long-term support releases of major Linux distributions, namely at time of writing: Ubuntu 22.04, RHEL 9, and SLES 15 SP4. • CMake 3.20.2 or later. • A build system like Make or Ninja for which CMake can generate build files. • A C99 toolchain (compiler, linker, archiver). We actively test with GCC 5.4, Clang 3.8, Arm Compiler 6, and Visual Studio 2017 Compiler. More recent versions should work. Slightly older versions may work. • Python 3.8 or later to generate the test code. Python is also needed to build the development branch (see next section). • Perl to run the tests, and to generate some source files in the development branch. • Doxygen 1.8.14 or later (if building the documentation; slightly older versions should work). Git usage The supported branches (see ) use Git submodules. They contain two submodules: the framework submodule and the tf-psa-crypto submodule, except for the 3.6 LTS branch, which contains only the framework submodule. Release tags also use Git submodules. After cloning or checking out a branch or tag, run: to initialize and update the submodules before building. However, the official source release tarballs (e.g. mbedtls-4.0.0.tar.bz2) include the contents of the submodules. Generated source files in the development branch The 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. The following tools are required: • Perl, for some library source files. • Python 3 and some Python packages, for some library source files, sample programs and test data. To install the necessary packages, run: Depending on your Python installation, you may need to invoke instead of . To install the packages system-wide or in a virtual environment, omit the option. • A C compiler for the host platform, for some test data. The scripts that generate the configuration-independent files will look for a host C compiler in the following places (in order of preference): • The environment variable. This can be used if is pointing to a cross-compiler. • The environment variable. • An executable called in the current path. Note: If you have multiple toolchains installed, it is recommended to set or to the intended host compiler before generating the files. Any of the following methods are available to generate the configuration-independent files: • On non-Windows systems, when not cross-compiling, CMake generates the required files automatically. • Run to generate all the configuration-independent files. CMake In order to build the libraries using CMake in a separate directory (recommended), just enter at the command line: mkdir /path/to/build_dir && cd /path/to/build_dir cmake /path/to/mbedtls_source cmake --build . In order to run the tests, enter: ctest The test suites need Python to be built. If you don't have Python installed, you'll want to disable the test suites with: cmake -DENABLE_TESTING=Off /path/to/mbedtls_source To configure CMake for building shared libraries, use: cmake -DUSE_SHARED_MBEDTLS_LIBRARY=On /path/to/mbedtls_source There are many different build types available with CMake. Most of them are available for gcc and clang, though some are compiler-specific: • . This generates the default code without any unnecessary information in the binary files. • . This generates debug information and disables optimization of the code. • . This generates code coverage information in addition to debug information. • . 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.) • . Same as ASan but slower, with debug information and better stack traces. • . This instruments the code with MemorySanitizer to check…