mbed-tls / mbedtls

An open source, portable, easy to use, readable and flexible TLS library, and reference implementation of the PSA Cryptography API. Releases are on a varying cadence, typically around 3 - 6 months between releases.

README for Mbed TLS

Mbed 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.

Mbed TLS includes a reference implementation of the PSA Cryptography API. This is currently a preview for evaluation purposes only.

Configuration

Mbed 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).

Compiler options can be set using conventional environment variables such as CC and CFLAGS when using the Make and CMake build system (see below).

We provide some non-standard configurations focused on specific use cases in the configs/ directory. You can read more about those in configs/README.txt

Documentation

The main Mbed TLS documentation is available via ReadTheDocs.

Documentation for the PSA Cryptography API is available on GitHub.

To generate a local copy of the library documentation in HTML format, tailored to your compile-time configuration:

1. Make sure that Doxygen is installed.
2. Run make apidoc.
3. Browse apidoc/index.html or apidoc/modules.html.

For other sources of documentation, see the SUPPORT document.

Compiling

There are currently three active build systems used within Mbed TLS releases:

• GNU Make
• CMake
• Microsoft Visual Studio

The 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.

The Make and CMake build systems create three libraries: libmbedcrypto, libmbedx509, and libmbedtls. Note that libmbedtls depends on libmbedx509 and libmbedcrypto, and libmbedx509 depends on libmbedcrypto. As a result, some linkers will expect flags to be in a specific order, for example the GNU linker wants -lmbedtls -lmbedx509 -lmbedcrypto.

Tool versions

You need the following tools to build the library with the provided makefiles:

• GNU Make 3.82 or a build tool that CMake supports.
• 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.
• 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).
• Perl to run the tests, and to generate some source files in the development branch.
• CMake 3.10.2 or later (if using CMake).
• Microsoft Visual Studio 2017 or later (if using Visual Studio).
• Doxygen 1.8.11 or later (if building the documentation; slightly older versions should work).

Git usage

The development branch and the mbedtls-3.6 long-term support branch of Mbed TLS use a Git submodule (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).

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 and for Visual Studio build files.
• Python 3.8 and some Python packages, for some library source files, sample programs and test data. To install the necessary packages, run:

  python3 -m pip install --user -r scripts/basic.requirements.txt
  

  Depending on your Python installation, you may need to invoke python instead of python3. To install the packages system-wide, omit the --user option.
• A C compiler for the host platform, for some test data.

If you are cross-compiling, you must set the CC environment variable to a C compiler for the host platform when generating the configuration-independent files.

Any of the following methods are available to generate the configuration-independent files:

• If not cross-compiling, running make with any target, or just make, will automatically generate required files.
• On non-Windows systems, when not cross-compiling, CMake will generate the required files automatically.
• Run make generated_files to generate all the configuration-independent files.
• On Unix/POSIX systems, run tests/scripts/check-generated-files.sh -u to generate all the configuration-independent files.
• On Windows, run scripts\make_generated_files.bat to generate all the configuration-independent files.

Make

We 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.

We 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.

In order to build from the source code using GNU Make, just enter at the command line:

make

In order to run the tests, enter:

make check

The 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:

make no_test

You'll still be able to run a much smaller set of tests with:

programs/test/selftest

In 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).

Setting 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.

Please 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.

Depending 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 for articles on your platform or issue.

In 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.

CMake

In order to build the source 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 and Perl to be executed. If you don't have one of these installed, you'll want to disable the test suites with:

cmake -DENABLE_TESTING=Off /path/to/mbedtls_source

If you disabled the test suites, but kept the programs enabled, you can still run a much smaller set of tests with:

programs/test/selftest

To configure CMake for building shared libraries, use:

cmake -DUSE_SHARED_MBEDTLS_LIBRARY=On /path/to/mbedtls_source

There are many different build modes available within the CMake buildsystem. Most of them are available for gcc and clang, though some are compiler-specific:

• Release. This generates the default code without any unnecessary information in the binary files.
• Debug. This generates debug information and disables optimization of the code.
• Coverage. This generates code coverage information in addition to debug information.
• 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.)
• ASanDbg. Same as ASan but slower, with debug information and better stack traces.
• MemSan. This instruments the code with MemorySanitizer to check for uninitialised memory reads. Experimental, needs recent clang on Linux/x86_64.
• MemSanDbg. Same as MemSan but slower, with debug information, better stack traces and origin tracking.
• Check. This activates the compiler warnings that depend on optimization and treats all warnings as errors.

Switching build modes in CMake is simple. For debug mode, enter at the command line:

cmake -D CMAKE_BUILD_TYPE=Debug /path/to/mbedtls_source

To list other available CMake options, use:

cmake -LH

Note that, with CMake, you can't adjust the compiler or its flags after the initial invocation of cmake. This means that CC=your_cc make and make CC=your_cc will not work (similarly with CFLAGS and other variables). These variables need to be adjusted when invoking cmake for the first time, for example:

CC=your_cc cmake /path/to/mbedtls_source

If you already invoked cmake and want to change those settings, you need to remove the build directory and create it again.

Note that it is possible to build in-place; this will however overwrite the provided Makefiles (see scripts/tmp_ignore_makefiles.sh if you want to prevent git status from showing them as modified). In order to do so, from the Mbed TLS source directory, use:

cmake .
make

If you want to change CC or CFLAGS afterwards, you will need to remove the CMake cache. This can be done with the following command using GNU find:

find . -iname '*cmake*' -not -name CMakeLists.txt -exec rm -rf {} +

You can now make the desired change:

CC=your_cc cmake .
make

Regarding variables, also note that if you set CFLAGS when invoking cmake, your value of CFLAGS doesn't override the content provided by cmake (depending on the build mode as seen above), it's merely prepended to it.

Consuming Mbed TLS

Mbed TLS provides a package config file for consumption as a dependency in other CMake projects. You can include Mbed TLS's CMake targets yourself with:

find_package(MbedTLS)

If prompted, set MbedTLS_DIR to ${YOUR_MBEDTLS_INSTALL_DIR}/cmake. This creates the following targets:

• MbedTLS::mbedcrypto (Crypto library)
• MbedTLS::mbedtls (TLS library)
• MbedTLS::mbedx509 (X509 library)

You can then use these directly through target_link_libraries():

add_executable(xyz)

target_link_libraries(xyz
    PUBLIC MbedTLS::mbedtls
           MbedTLS::mbedcrypto
           MbedTLS::mbedx509)

This will link the Mbed TLS libraries to your library or application, and add its include directories to your target (transitively, in the case of PUBLIC or INTERFACE link libraries).

Mbed TLS as a subproject

Mbed TLS supports being built as a CMake subproject. One can use add_subdirectory() from a parent CMake project to include Mbed TLS as a subproject.

Microsoft Visual Studio

The build files for Microsoft Visual Studio are generated for Visual Studio 2017.

The 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.

In 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”.

Example programs

We've included example programs for a lot of different features and uses in programs/. Please 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.

Tests

Mbed TLS includes an elaborate test suite in tests/ that initially requires Python to generate the tests files (e.g. test\_suite\_mpi.c). These files are generated from a function file (e.g. suites/test\_suite\_mpi.function) and a data file (e.g. suites/test\_suite\_mpi.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.

For machines with a Unix shell and OpenSSL (and optionally GnuTLS) installed, additional test scripts are available:

• tests/ssl-opt.sh runs integration tests for various TLS options (renegotiation, resumption, etc.) and tests interoperability of these options with other implementations.
• tests/compat.sh tests interoperability of every ciphersuite with other implementations.
• tests/scripts/test-ref-configs.pl test builds in various reduced configurations.
• tests/scripts/depends.py test builds in configurations with a single curve, key exchange, hash, cipher, or pkalg on.
• 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).

Instead 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.

Porting Mbed TLS

Mbed 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:

• Porting Mbed TLS to a new environment or OS
• What external dependencies does Mbed TLS rely on?
• How do I configure Mbed TLS

Mbed 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:

• Bytes must be 8 bits.
• All-bits-zero must be a valid representation of a null pointer.
• Signed integers must be represented using two's complement.
• int and size_t must be at least 32 bits wide.
• The types uint8_t, uint16_t, uint32_t and their signed equivalents must be available.
• Mixed-endian platforms are not supported.
• SIZE_MAX must be at least as big as INT_MAX and UINT_MAX.

PSA cryptography API

PSA API

Arm's Platform Security Architecture (PSA) 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.

The PSA cryptography API 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.

The design goals of the PSA cryptography API include:

• 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.
• 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.
• All access to the keys happens through key identifiers, which allows support for external cryptoprocessors that is transparent to applications.
• The interface to algorithms is generic, favoring algorithm agility.
• The interface is designed to be easy to use and hard to accidentally misuse.

Arm 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 [email protected]. All feedback received by email is treated confidentially.

PSA implementation in Mbed TLS

Mbed TLS includes a reference implementation of the PSA Cryptography API. However, it does not aim to implement the whole specification; in particular it does not implement all the algorithms.

The X.509 and TLS code can use PSA cryptography for most operations. To enable this support, activate the compilation option MBEDTLS_USE_PSA_CRYPTO in mbedtls_config.h. Note that TLS 1.3 uses PSA cryptography for most operations regardless of this option. See docs/use-psa-crypto.md for details.

PSA drivers

Mbed 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.

Please see the PSA driver example and guide for information on writing a driver.

When using drivers, you will generally want to enable two compilation options (see the reference manual for more information):

• MBEDTLS_USE_PSA_CRYPTO is necessary so that the X.509 and TLS code calls the PSA drivers rather than the built-in software implementation.
• MBEDTLS_PSA_CRYPTO_CONFIG allows you to enable PSA cryptographic mechanisms without including the code of the corresponding software implementation. This is not yet supported for all mechanisms.

License

Unless specifically indicated otherwise in a file, Mbed TLS files are provided under a dual Apache-2.0 OR GPL-2.0-or-later license. See the LICENSE file for the full text of these licenses, and the 'License and Copyright' section in the contributing guidelines for more information.

Third-party code included in Mbed TLS

This project contains code from other projects. This code is located within the 3rdparty/ 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:

• 3rdparty/everest/: Files stem from Project Everest and are distributed under the Apache 2.0 license.
• 3rdparty/p256-m/p256-m/: Files have been taken from the 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.

Contributing

We gratefully accept bug reports and contributions from the community. Please see the contributing guidelines for details on how to do this.

Contact

• To report a security vulnerability in Mbed TLS, please email [email protected]. For more information, see SECURITY.md.
• To report a bug or request a feature in Mbed TLS, please file an issue on GitHub.
• Please see SUPPORT.md for other channels for discussion and support about Mbed TLS.

mbedtls's Issues

CTR_DRBG is limited to AES

The module CTR_DRBG could be reworked to be able to use other block cyptos than only AES (like the HASH_DRBG module). This would make the module more future proof.

OpenVPN cert chain with sha512 sigs and 4096-bit keys not correctly validated

Have an OpenVPN configuration that works with
a WinXP client and Linux x86_64 server.

PolarSSL reject same exact certs that work with
aforementioned configuration.

Much detail at

https://community.openvpn.net/openvpn/ticket/332

Visual Studio Debug build fails

The "Include Directories" property under Project Settings>"Configuration Properties">"VC++ Directories" is changed from the default for the Debug configurations only. This breaks the Debug builds on my system (Windows 7 with VS Express 2013). Changing the property to "inherit from project defaults" fixes this.

Possible memory leak if someone runs the benchmarks in a loop.

The GCM context does not get freed in programs/test/benchmark.c. There is a missing gcm_free() after line 300.

MSVC 2010 misses new .c and .h files in 1.2.8

Add new modules from 1.2 branch and 1.3 branch for new releases..

POLARSSL_ECP_DP_SECPxxxK1_ENABLED in config.h and ecp.c

The following:

!defined(POLARSSL_ECP_DP_SECP192K1_ENABLED) &&                  \
!defined(POLARSSL_ECP_DP_SECP224K1_ENABLED) &&                  \
!defined(POLARSSL_ECP_DP_SECP256K1_ENABLED) &&                  \

should probably be added to the following block in config.h:

#if defined(POLARSSL_ECP_C) && ( !defined(POLARSSL_BIGNUM_C) || (   \
    !defined(POLARSSL_ECP_DP_SECP192R1_ENABLED) &&                  \
    !defined(POLARSSL_ECP_DP_SECP224R1_ENABLED) &&                  \
    !defined(POLARSSL_ECP_DP_SECP256R1_ENABLED) &&                  \
    !defined(POLARSSL_ECP_DP_SECP384R1_ENABLED) &&                  \
    !defined(POLARSSL_ECP_DP_SECP521R1_ENABLED) &&                  \
    !defined(POLARSSL_ECP_DP_BP256R1_ENABLED)   &&                  \
    !defined(POLARSSL_ECP_DP_BP384R1_ENABLED)   &&                  \
    !defined(POLARSSL_ECP_DP_BP512R1_ENABLED) ) )
#error "POLARSSL_ECP_C defined, but not all prerequisites"
#endif

and similar in ecp.c

defined(POLARSSL_ECP_DP_SECP192K1_ENABLED) ||   \
defined(POLARSSL_ECP_DP_SECP224K1_ENABLED) ||   \
defined(POLARSSL_ECP_DP_SECP256K1_ENABLED) ||   \

ECDH and ECDSA test suite fails on big-endian MIPS

It passes on my x86-64 dev box and on mipsel, so I'm guessing this is an endianness issue, but I haven't tested further. I have bisected it back to d589a0d.

Here's the test suite output:
$ make check
Running checks (Success if all tests PASSED)

• test_suite_aes.ecb
  PASSED (77 / 77 tests (0 skipped))
• test_suite_aes.cbc
  PASSED (72 / 72 tests (0 skipped))
• test_suite_aes.cfb
  PASSED (72 / 72 tests (0 skipped))
• test_suite_aes.rest
  PASSED (5 / 5 tests (0 skipped))
• test_suite_arc4
  PASSED (9 / 9 tests (0 skipped))
• test_suite_base64
  PASSED (20 / 20 tests (0 skipped))
• test_suite_blowfish
  PASSED (103 / 103 tests (0 skipped))
• test_suite_camellia
  PASSED (59 / 59 tests (0 skipped))
• test_suite_cipher.aes
  PASSED (275 / 275 tests (0 skipped))
• test_suite_cipher.arc4
  PASSED (26 / 26 tests (0 skipped))
• test_suite_cipher.gcm
  PASSED (32 / 32 tests (0 skipped))
• test_suite_cipher.blowfish
  PASSED (138 / 138 tests (0 skipped))
• test_suite_cipher.camellia
  PASSED (190 / 190 tests (0 skipped))
• test_suite_cipher.des
  PASSED (138 / 138 tests (0 skipped))
• test_suite_cipher.null
  PASSED (24 / 24 tests (24 skipped))
• test_suite_cipher.padding
  PASSED (43 / 43 tests (1 skipped))
• test_suite_ctr_drbg
  PASSED (240 / 240 tests (0 skipped))
• test_suite_debug
  PASSED (8 / 8 tests (2 skipped))
• test_suite_des
  PASSED (80 / 80 tests (0 skipped))
• test_suite_dhm
  PASSED (4 / 4 tests (0 skipped))
• test_suite_ecdh
  ECDH primitive rfc 5903 p256 ...................................... FAILED
  mpi_cmp_mpi( &qA.X, &check ) == 0
  ECDH primitive rfc 5903 p384 ...................................... FAILED
  mpi_cmp_mpi( &qA.X, &check ) == 0
  ECDH primitive rfc 5903 p521 ...................................... FAILED
  mpi_cmp_mpi( &qA.X, &check ) == 0
  FAILED (7 / 10 tests (0 skipped))
  **** Failed ***************
• test_suite_ecdsa
  ECDSA primitive rfc 4754 p256 ..................................... FAILED
  mpi_cmp_mpi( &r, &r_check ) == 0
  ECDSA primitive rfc 4754 p384 ..................................... FAILED
  mpi_cmp_mpi( &r, &r_check ) == 0
  ECDSA primitive rfc 4754 p521 ..................................... FAILED
  mpi_cmp_mpi( &r, &r_check ) == 0
  FAILED (10 / 13 tests (0 skipped))
  **** Failed ***************
• test_suite_ecp
  PASSED (87 / 87 tests (0 skipped))
• test_suite_error
  PASSED (6 / 6 tests (0 skipped))
• test_suite_gcm.decrypt_128
  PASSED (169 / 169 tests (0 skipped))
• test_suite_gcm.decrypt_192
  PASSED (169 / 169 tests (0 skipped))
• test_suite_gcm.decrypt_256
  PASSED (169 / 169 tests (0 skipped))
• test_suite_gcm.encrypt_128
  PASSED (169 / 169 tests (0 skipped))
• test_suite_gcm.encrypt_192
  PASSED (169 / 169 tests (0 skipped))
• test_suite_gcm.encrypt_256
  PASSED (169 / 169 tests (0 skipped))
• test_suite_hmac_shax
  PASSED (36 / 36 tests (0 skipped))
• test_suite_md
  PASSED (258 / 258 tests (48 skipped))
• test_suite_mdx
  PASSED (55 / 55 tests (32 skipped))
• test_suite_mpi
  PASSED (197 / 197 tests (0 skipped))
• test_suite_pbkdf2
  PASSED (5 / 5 tests (0 skipped))
• test_suite_pkcs1_v21
  PASSED (247 / 247 tests (0 skipped))
• test_suite_pkcs5
  PASSED (5 / 5 tests (0 skipped))
• test_suite_pkparse
  PASSED (57 / 57 tests (0 skipped))
• test_suite_pkwrite
  PASSED (4 / 4 tests (0 skipped))
• test_suite_rsa
  PASSED (95 / 95 tests (4 skipped))
• test_suite_shax
  PASSED (63 / 63 tests (0 skipped))
• test_suite_x509parse
  PASSED (197 / 197 tests (2 skipped))
• test_suite_x509write
  PASSED (8 / 8 tests (1 skipped))
• test_suite_xtea
  PASSED (13 / 13 tests (0 skipped))
• test_suite_version
  PASSED (2 / 2 tests (0 skipped))

make[1]: *** [check] Error 1
make: *** [check] Error 2

X.509 certificate validity period beginning will not be checked in verification

When verifying a X.509 certificate, the process will succeed even if the system time is before the certificate validity period.

This is due to the fact that the member valid_from from the appropriated structure x509_cert will never be checked.

Solaris 10 socket library build problem

Compiling current head of polarssl-1.2 on Solaris 10 appears to be missing linker flags (-lsocket, -lnsl)? Compilation fails.

$ make
...
  CC    pkey/dh_client.c
Undefined                       first referenced
 symbol                             in file
bind                                ../library/libpolarssl.a(net.o)
accept                              ../library/libpolarssl.a(net.o)
listen                              ../library/libpolarssl.a(net.o)
gethostbyname                       ../library/libpolarssl.a(net.o)
socket                              ../library/libpolarssl.a(net.o)
setsockopt                          ../library/libpolarssl.a(net.o)
connect                             ../library/libpolarssl.a(net.o)
shutdown                            ../library/libpolarssl.a(net.o)
ld: fatal: symbol referencing errors. No output written to pkey/dh_client
collect2: ld returned 1 exit status
make[1]: *** [pkey/dh_client] Error 1
make: *** [all] Error 2

PKCS#12 file support

Compression and empty blocks

It seems socat likes to send empty blocks which causes zlib to punt.

To reproduce, run this on a test-server:

socat OPENSSL-LISTEN:5555,verify=0,key=test.key,cert=test.crt STDOUT

Connect to this with a polarssl client. Sending from polar to socat works fine. Just hitting enter on the socat end will make the connection fail on the PolarSSL side with a compression error.

I tracked that down to ssl_decompress_buf() being called with an empty block.
The zlib will return an error in that case.

Putting

if( !len_pre ) return ( 0 );

near the top of ssl_compress_buf() and ssl_decompress_buf() fixes that.

Versions:

• client: PolarSSL 1.2.7 with zlib 1.2.8
• server: socat 1.7.1.3 with openssl 1.0.0e-2ubuntu4.7

Error when building shared library

I encountered an issue when attempting to compile a shared library with make. This problem does not occur when using cmake with

option(USE_SHARED_POLARSSL_LIBRARY "Build PolarSSL as a shared library." ON)

Any tips on resolving this without using cmake?

[ayrx@c00kies library]$ make shared
CC aes.c
CC aesni.c
CC arc4.c
CC asn1parse.c
CC asn1write.c
CC base64.c
CC bignum.c
CC blowfish.c
CC camellia.c
CC certs.c
CC cipher.c
CC cipher_wrap.c
CC ctr_drbg.c
CC debug.c
CC des.c
CC dhm.c
CC ecdh.c
CC ecdsa.c
CC ecp.c
CC ecp_curves.c
CC entropy.c
CC entropy_poll.c
CC error.c
CC gcm.c
CC havege.c
CC md.c
CC md_wrap.c
CC md2.c
CC md4.c
CC md5.c
CC memory.c
CC memory_buffer_alloc.c
CC net.c
CC oid.c
CC padlock.c
CC pbkdf2.c
CC pem.c
CC pkcs5.c
CC pkcs11.c
CC pkcs12.c
CC pk.c
CC pk_wrap.c
CC pkparse.c
CC pkwrite.c
CC rsa.c
CC sha1.c
CC sha256.c
CC sha512.c
CC ssl_cache.c
CC ssl_cli.c
CC ssl_srv.c
CC ssl_ciphersuites.c
CC ssl_tls.c
CC threading.c
CC timing.c
CC version.c
CC x509.c
CC x509_create.c
CC x509_crl.c
CC x509_crt.c
CC x509_csr.c
CC x509write_crt.c
CC x509write_csr.c
CC xtea.c
AR libpolarssl.a
ar: creating libpolarssl.a
RL libpolarssl.a
LD libpolarssl.so.5
/usr/bin/ld: aes.o: relocation R_X86_64_32 against `.bss' can not be used when making a shared object; recompile with -fPIC
aes.o: could not read symbols: Bad value
collect2: error: ld returned 1 exit status
make: *** [libpolarssl.so.5] Error 1

Solaris 10 ar error

(On current polarssl-1.2 head).

Workaround:

Install package SUNWbinutils and then before building do:

export AR=gar

Otherwise:

$ make
....
  AR    libpolarssl.a
ar: creating libpolarssl.a
  RL    libpolarssl.a
ar: one of [drqtpmx] must be specified
make[1]: *** [libpolarssl.a] Error 1
make: *** [all] Error 2

Possible memory leak in ssl_tls.c

It looks like there is one parameter in the SSL context that is never freed. Using valgrind on Linux, ssl_client1 exits with 100 bytes first allocated to session_negotiate.

This is with the latest version from git. I compiled the library with DEBUG=1 and used standard valgrind as provided by Ubuntu 10.04.

$ valgrind --leak-check=full ./ssl_client1
==21144== Memcheck, a memory error detector
==21144== Copyright (C) 2002-2009, and GNU GPL'd, by Julian Seward et al.
==21144== Using Valgrind-3.6.0.SVN-Debian and LibVEX; rerun with -h for copyright info
==21144== Command: ./ssl_client1
==21144== 

  . Seeding the random number generator... ok
  . Loading the CA root certificate ... ok (0 skipped)
  . Connecting to tcp/localhost/4433... ok
  . Setting up the SSL/TLS structure... ok
  . Performing the SSL/TLS handshake... ok
  . Verifying peer X.509 certificate... ok
  > Write to server: 18 bytes written

GET / HTTP/1.0

  < Read from server: 148 bytes read

HTTP/1.0 200 OK
Content-Type: text/html

<h2>PolarSSL Test Server</h2>
<p>Successful connection using: TLS-DHE-RSA-WITH-AES-256-CBC-SHA256</p>


EOF

==21144== 
==21144== HEAP SUMMARY:
==21144==     in use at exit: 4,538 bytes in 19 blocks
==21144==   total heap usage: 546 allocs, 527 frees, 81,271 bytes allocated
==21144== 
==21144== 4,538 (100 direct, 4,438 indirect) bytes in 1 blocks are definitely lost in loss record 12 of 12
==21144==    at 0x4024F20: malloc (vg_replace_malloc.c:236)
==21144==    by 0x8050B33: ssl_handshake_init (ssl_tls.c:2873)
==21144==    by 0x8049295: main (ssl_client1.c:150)
==21144== 
==21144== LEAK SUMMARY:
==21144==    definitely lost: 100 bytes in 1 blocks
==21144==    indirectly lost: 4,438 bytes in 18 blocks
==21144==      possibly lost: 0 bytes in 0 blocks
==21144==    still reachable: 0 bytes in 0 blocks
==21144==         suppressed: 0 bytes in 0 blocks
==21144== 
==21144== For counts of detected and suppressed errors, rerun with: -v
==21144== ERROR SUMMARY: 1 errors from 1 contexts (suppressed: 14 from 9)
$ 

Certificate cache

ECDSA signature verification is missing a modular operation

Hi,

I think that a mpi_mod_mpi is missing from ecdsa_signature as shown below.
Without that line addition, ECDSA verification in DTCP-IP doesn't work.
I'm no ECP expert, so let me know if you disagree with this change.
For reference, I compared the values of each MPI at every line of code with my own reference ECDSA implementation, and that is the only place that differs in PolarSSL.

Thanks.

if( ecp_is_zero( &R ) )
{
    ret = POLARSSL_ERR_ECP_VERIFY_FAILED;
    goto cleanup;
}

// Make sure R.X is mod n.
MPI_CHK( mpi_mod_mpi( &R.X, &R.X, &grp->N ) );

/*
 * Step 6: check that xR == r
 */
if( mpi_cmp_mpi( &R.X, r ) != 0 )

EC benchmarks randomly fail.

When I run the benchmarks with 1.3.4, some of the EC benchmarks randomly fail. I tested it under WIN64 and LINUX64.

On Linux64 I rarely get any errors (but occasionally I get them) but on Win64 I always get at least one FAIL.

On WIN64 I use:
gcc (x86_64-win32-seh, Built by MinGW-W64 project) 4.8.2

On Linux64:
gcc (Ubuntu/Linaro 4.6.3-1ubuntu5) 4.6.3

Some results:

Run 1 (WIN64):

  ECDSA-brainpoolP384 :  FAILED
  ECDSA-secp224k1    :  FAILED

Run 2 (WIN64):

  ECDSA-secp224k1    :  FAILED

Run 3 (WIN64):

  ECDSA-secp224k1    :  FAILED
  ECDHE-secp224k1    :  FAILED
  ECDH-secp224k1     :  FAILED

Run 1 (Linux64):

  ECDHE-secp224k1    :  FAILED

Run 2 (Linux 64):

  ECDHE-secp224k1    :  FAILED
  ECDH-secp224k1     :  FAILED

Run 3 (Linux 64):

  ECDSA-brainpoolP38 :  FAILED

renegotiation extension is always sent in server hello

ssl_write_server_hello() always sends secure renegotiation extension, even when the client does not support it.

This makes my (old) openssl client upset, as it's compiled without extensions support. Perhaps the extension should only be sent when client hello contains SCSV or the extension? Or possibly close the connection for such insecure clients.

RFC 5746:
Note that sending a "renegotiation_info" extension in response to a
ClientHello containing only the SCSV is an explicit exception to the
prohibition in RFC 5246, Section 7.4.1.4, on the server sending
unsolicited extensions and is only allowed because the client is
signaling its willingness to receive the extension via the
TLS_EMPTY_RENEGOTIATION_INFO_SCSV SCSV. TLS implementations MUST
continue to comply with Section 7.4.1.4 for all other extensions.

Openssl build subtley

This is a big edgy, but sometimes its useful to build openssl stripped down:

diff --git a/programs/test/o_p_test.c b/programs/test/o_p_test.c
index 0665098..3a6c693 100644
--- a/programs/test/o_p_test.c
+++ b/programs/test/o_p_test.c
@@ -32,7 +32,9 @@
#include <sys/stat.h>

#include <openssl/rsa.h>
+#ifndef OPENSSL_NO_ENGINE
#include <openssl/engine.h>
+#endif
#include <openssl/pem.h>
#include <openssl/bio.h>

bad cert_type offset in certificate request

Not that I know if the server does things properly, but the following patch seems to make more sense and get things to work. BTW, couldn't this be handled by the asn.1 decoder?

diff --git a/library/ssl_cli.c b/library/ssl_cli.c
index 545906a..6228f63 100644
--- a/library/ssl_cli.c
+++ b/library/ssl_cli.c
@@ -951,7 +951,7 @@ static int ssl_parse_certificate_request( ssl_context *ssl )
         return( POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE_REQUEST );
     }

-    p = buf + 4;
+    p = buf + 5;
     while( cert_type_len > 0 )
     {
         if( *p == SSL_CERT_TYPE_RSA_SIGN )

[ARM] bignum multiplication improvement

MULADDC_CORE can be improved for ARM.

I am using PolarSSL's rsa.c for 2048-bit key with STM32F103 processor.
It takes 1.78 second to sign in current implementation.
With this change, it takes 1.72 second.

Please see attached patch.
https://gist.github.com/4079268

Tomstdenis:
ARMv4 TDMI and ARMv5 up support much more efficient multiplication. You may want to look into that. From a practical standpoint new devices are V5 or higher anyways so supporting V4 and below is kinda archaic.

We could help you speed up your math lib. We have an ARM A9 to profile on as well.

NTRU support

https://www.securityinnovation.com/products/encryption-libraries/ntru-cryptography.html

Reference Code (GPL2):
https://github.com/NTRUOpenSourceProject/ntru-crypto

but:

Is NTRU Patented?

Yes. The patents will still be enforced but may be used under the GPL, i.e. under the condition that any work that uses them is also made available under the GPL. The patents and the code implementations are also available under standard commercial terms.

Why has NTRU been open source licensed?

By offering NTRU source code and patents under the Gnu Public License (GPL) v2, we are intending to remove barriers to widespread deployment. We want to enable the developers of the open-source software that powers the internet to test, use, deploy, and start transitioning to fast, future-proof cryptography. Recent revelations and speculation about NSA influence on both crypto algorithms and crypto implementations have made it clear that the security community desperately needs alternatives to existing crypto solutions.

Making NTRU open-source also removes barriers to testing of both the algorithm and the implementation. Open scrutiny and testing is the only way to instill confidence in any encryption solution.

Furthermore, the open source licensing allows users to implement the NTRU algorithm in other languages and for other operating systems beyond those we currently support.

Are there any commercial licenses available?

For commercial (not open source) applications, Security Innovation offers a commercial license (see repository) that is not limited to use in open source applications only.

Entropy module not fully thread safe.

In the entropy module only the function entropy_func() is thread safe. The other public functions entropy_update_manual() and entropy_gather() are not thread safe. Maybe it was intended to be so, but I think either the whole module should be thread safe or the documentation should explicitly warn that those public functions are not thread safe.

#define typo in rsa.c.

There are two erratic #defines in rsa.c. Look for "POLARSSL_PCKS1_V15" instead of "POLARSSL_PKCS1_V15".

This causes the RSA self test not to run even if defined.

Memory leak if ecdsa_sign/ecdsa_verify fail with an error

The sign&verify functions will not free up some mpi's if they fail.
I used the alpha 1.3.1 that was released a couple of months ago.

__udivti3 undefined when compiling with Apple LLVM v 5.0

Recently upgraded to OsX mavericks, which comes with a new compiler, that identifies itself as:

Configured with: --prefix=/Applications/Xcode.app/Contents/Developer/usr --with-gxx-include-dir=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.9.sdk/usr/include/c++/4.2.1
Apple LLVM version 5.0 (clang-500.2.79) (based on LLVM 3.3svn)
Target: x86_64-apple-darwin13.1.0

Building PolarSSL v.2.3.3:

Undefined symbols for architecture x86_64:
"___udivti3", referenced from:
_mpi_div_mpi in libpolarssl.a(bignum.o)

The error is in bignum.c at line 1239:

        t_udbl r;

        r  = (t_udbl) X.p[i] << biL;
        r |= (t_udbl) X.p[i - 1];
        r /= Y.p[t];                                                    <---- this line
        if( r > ((t_udbl) 1 << biL) - 1)
            r = ((t_udbl) 1 << biL) - 1;

        Z.p[i - t - 1] = (t_uint) r;

Looks like clang can't find its own definition of a built-in 128 bit division. I have a workaround for now: undefine POLARSSL_HAVE_UDBL in bignum.h

Incompatibile with Chrome on Linux

Chrome version 29.0.1547.65.

Easy to test, just run programs/ssl/ssl_server and open https://localhost:4433/

$ ./ssl_server

  . Loading the server cert. and key... ok
  . Bind on https://localhost:4433/ ... ok
  . Seeding the random number generator... ok
  . Setting up the SSL data.... ok
  . Waiting for a remote connection ... ok
  . Performing the SSL/TLS handshake... failed
  ! ssl_handshake returned -80

Last error was: -80 - NET - Connection was reset by peer

Chrome is linked against GnuTLS. I presume it uses that library for SSL connections then, although using gnutls-cli works fine. You can try:

gnutls-cli -d 255 localhost --port 4433 --insecure

So either it configures GnuTLS in a different way than gnutls-cli, or it doesn't actually use GnuTLS to do the SSL connection.

This bug only affects the Linux version of Chrome. The Windows and Mac versions (same version 29) seem to work fine.

I hope you have an idea of what is going on here. I've been tcpdumping and low-level tracing polarssl all day and I am baffled.

Thanks.

Certificate export support

x509_write_cert_req() fails

x509_write_cert_req() calls rsa_pkcs1_sign() without a random number generator. Then rsa_pkcs1_sign() calls rsa_rsassa_pss_sign() which rejects a call without a RNG with an error. Finally, the error is not checked in x509_write_cert_req(), leaving old buffer contents in the signature buffer.

Small Cmake bug

to pick up the appropriate openssl include path, should do the following:

diff --git a/programs/test/CMakeLists.txt b/programs/test/CMakeLists.txt
index c05b903..8437b18 100644
--- a/programs/test/CMakeLists.txt
+++ b/programs/test/CMakeLists.txt
@@ -30,6 +30,7 @@ install(TARGETS selftest benchmark ssl_test ssl_cert_test

if(OPENSSL_FOUND)
add_executable(o_p_test o_p_test.c)

• include_directories (${OPENSSL_INCLUDE_DIR})
  target_link_libraries(o_p_test ${libs} ${OPENSSL_LIBRARIES})

install(TARGETS o_p_test

Direct support for AES-CFB8

We are hoping to use PolarSSL for our C++ MineCraft server (@mc-server), but MineCraft uses AES-CFB8 encryption for its client connections. It is possible to implement this indirectly already, but it'd be much better to have direct internal support for this combination in the library. Are there any plans to add this mode?

Extensive malloc/free

Possible performance issue only.

Both ssl_compress_buf() and ssl_decompress_buf() call malloc/free on each run.

We might want to keep a central buffer in ssl_context and allocate that once at init.

Increased the size of ssl_context by a major factor.

Dynamic salt length for PKCS#1 v2.1 signing and verification

Thank you for adding PKCS #1 v2.1 to the library. I see that the salt length is effectively tied to the hash length with slen=hlen. Can you make the salt length a parameter when calling the sign and verify functions?

Verify automatically uses the salt that is in the signature itself.

For sign, a change is needed. I don't like adding a salt-len variable that is only used if the RSASSA-PSS is enable in the code.. I'm still looking for a nice and not so ugly solution to propagate the salt-len into that part of the code.

Suggestions are welcome.

Postponed to a next release.

Automatically build up certificate chains

SSL servers should provide as much information their certificate's chain as possible. PolarSSL could help applications by appending certificate authority certificates to a certificate automatically.

Along similar lines, if a server requests a client certificate, it can pass a list of known CAs to the client. PolarSSL should ensure that the returned client certificate has one of the given CAs as its parent.

DTLS

Request for DTLS support as this would increase usability for my projects.

CMake test data files are not being properly built...

if we check out the current 1.2 branch code (1.2.7 as of today) from scratch and attempt to build, all the .data files that are automatically being generated to prepare for the test cases do not ever get created. i had another previously checked out branch that had the files generated already, and all the tests passed fine with those, but once i cleaned them up, they were never re-generated.

i have examined the methodology and don't see anything obvious, but am guessing the person who made the changes for test cases will know exactly what the issue is.

Support in mbed

I've purchased an mbed prototype board (​http://www.mbed.org) and would love to have PolarSSL as a component as I use it in my other projects as well.

Do you plan to make a component there?

polarssl-1.3 externs

ecp.h openssl.h x509.h missing some open/close extern "C"

polarssl-1.3.2/library/x509_crt.c:1276: 2 * possible bad if test ?

I just compiled polarssl-1.3.2 with Linux gcc compiler flag -Wlogical-op.
It said

polarssl-1.3.2/library/x509_crt.c:1276:9: warning: logical 'or' of collectively exhaustive tests is always true [-Wlogical-op]
polarssl-1.3.2/library/x509_crt.c:1279:9: warning: logical 'or' of collectively exhaustive tests is always true [-Wlogical-op]

Source code is

    if( ( n1[i] >= 'a' || n1[i] <= 'z' ) && ( diff == 0 || diff == 32 ) )
        continue;

    if( ( n1[i] >= 'A' || n1[i] <= 'Z' ) && ( diff == 0 || diff == 32 ) )
        continue;

Suggest swap || for && in the a..z checks.

Extend support for VIA Padlock engine

PolarSSL already has code to use the Padlock engine for AES on VIA CPUs, but those CPUs also feature HW accelerated SHA1, SHA256, 2 HW RNGs and an HW accelerated Montgomery multiplier which can be used to accelerate RSA and DSA.

The OpenSSL folks have quite optimized code for all of this (except the RNG):
http://git.openssl.org/gitweb/?p=openssl.git;a=blob;f=engines/asm/e_padlock-x86.pl
http://git.openssl.org/gitweb/?p=openssl.git;a=blob;f=engines/asm/e_padlock-x86_64.pl
http://git.openssl.org/gitweb/?p=openssl.git;a=blob;f=crypto/bn/asm/via-mont.pl

Thanks

This is not an issue, but I just wanted to say thanks for moving to GitHub! I have used this library for some time while developing RtmpDump, and its a big help to have both "under the same roof".

Keep up the good work!

Solaris 10 build failure: dirent.d_type

(Reposting from the forum since I'm not sure where the definitive place to post issues is and this seems a better place for tracking: https://polarssl.org/discussions/bug-report-issues/solaris-10-build-failure).

Build of polarssl 1.2.6 (and current HEAD at github) fails on Solaris 10 (u9, x86 and SPARC) because struct dirent does not include a d_type member as required by library/x509parse.c line 1952.

This struct has not been updated for Solaris 11 or 11.1 so presumably will not build there either.

Opengroup ref: http://pubs.opengroup.org/onlinepubs/009695399/basedefs/dirent.h.html

$ uname -a 
SunOS sol10u9 5.10 Generic_142910-17 i86pc i386 i86pc
$ gcc --version
gcc (GCC) 4.4.2
Copyright (C) 2009 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

$ make
...
  CC    x509parse.c
x509parse.c: In function 'x509parse_crtpath':
x509parse.c:1952: error: 'struct dirent' has no member named 'd_type'
x509parse.c:1952: error: 'DT_REG' undeclared (first use in this function)
x509parse.c:1952: error: (Each undeclared identifier is reported only once
x509parse.c:1952: error: for each function it appears in.)
make[1]: *** [x509parse.o] Error 1
make: *** [all] Error 2

/usr/include/sys/dirent.h:

/*
 * File-system independent directory entry.
 */
typedef struct dirent {
    ino_t       d_ino;      /* "inode number" of entry */
    off_t       d_off;      /* offset of disk directory entry */
    unsigned short  d_reclen;   /* length of this record */
    char        d_name[1];  /* name of file */
} dirent_t;

x509_crt.c does not respect alternate threading implementations

The mutex calls in x509_crt.c are #ifdef-ed against POLARSSL_THREADING_PTHREAD so they won't respect any alternate threading implementation. I think they should be depending on POLARSSL_THREADING_C.

buffered fread() in platform_entropy_poll()

This is just a minor inefficiency: ENTROPY_MAX_GATHER is set to 128, but fread() will read more than that (the exact value depends on the underlying C library) because buffering is not disabled via setbuf().

Object identifier database

X509 certificates use object IDs for many different purposes (including in their DN and issuer strings). Such Object IDs have a short form string (e.g. "SN"), and sometimes a longer descriptive string.

Currently the string representation of such object IDs are generated using a switch-case construct within the x509 code. As more and more certificate extensions and OID types are added, this becomes less and less maintainable. A separate module containing an object "database" would allow more flexibility, and cleaner code.

PolarSSL will not compile on Mac when using CMake

I get the following errors after running cmake . && make:

/var/folders/m2/h8x9nnlj6ld196rpd26qrt9m0000gn/T//ccjiXQHX.s:114:no such instruction: `pclmulqdq $0x00, %xmm0,%xmm1'
/var/folders/m2/h8x9nnlj6ld196rpd26qrt9m0000gn/T//ccjiXQHX.s:115:no such instruction: `pclmulqdq $0x11, %xmm0,%xmm2'
/var/folders/m2/h8x9nnlj6ld196rpd26qrt9m0000gn/T//ccjiXQHX.s:116:no such instruction: `pclmulqdq $0x10, %xmm0,%xmm3'
/var/folders/m2/h8x9nnlj6ld196rpd26qrt9m0000gn/T//ccjiXQHX.s:117:no such instruction: `pclmulqdq $0x01, %xmm0,%xmm4'
make[2]: *** [library/CMakeFiles/polarssl.dir/aesni.c.o] Error 1
make[1]: *** [library/CMakeFiles/polarssl.dir/all] Error 2
make: *** [all] Error 2

I am running Mac OS 10.7.5. I get the same errors when using clang or the GNU toolchain.

If I use a clean copy where I haven't run cmake and just use the provided makefile, then it works fine. However, for the project that I am a part of I need cmake to work properly.

Segfault when RNG is not set

If you never call ssl_set_rng() and then do something that needs the RNG, the program segfaults. For example, comment the line with ssl_set_rng in ssl/ssl_client1.c and run ssl_server and then ssl_client1. ssl_client1 will segfault during the handshake. There should be either a safe default or a graceful failure instead.

Save and load entropy seed.

In systems that are very poor on entropy feed, the accumulated entropy is very valuable.(Even more valuable than the DRBG seed.) The entropy module could provide similar functions that the DRBG module(s) already provide: to save and load the entropy seed.

Support for RIPEMD-160

Support for RIPEMD-160 would be a nice enhancement.

It would be very useful for people working on Bitcoin related projects e.g. jgarzik/picocoin#7

The same goes for ECDSA secp256k1, which is also used by Bitcoin.

Polarssl 1.3.4 breaks 8 out of 47 tests when compiled on Mac OS X 10.8.5

$ gcc --version
Configured with: --prefix=/Applications/Xcode.app/Contents/Developer/usr --with-gxx-include-dir=/usr/include/c++/4.2.1
Apple LLVM version 5.0 (clang-500.2.79) (based on LLVM 3.3svn)
Target: x86_64-apple-darwin12.5.0
Thread model: posix

The following tests FAILED:
33 - md-suite (Failed)
34 - mdx-suite (Failed)
35 - mpi-suite (SEGFAULT)
40 - pkparse-suite (Failed)
41 - pkwrite-suite (Failed)
42 - shax-suite (Failed)
46 - x509parse-suite (Failed)
47 - x509write-suite (Failed)