An open source, portable, easy to use, readable and flexible SSL library
Go to file
Gilles Peskine 2ef377d56d all.sh: support variable seedfile size
The size of the seedfile used by the entropy module when
MBEDTLS_ENTROPY_NV_SEED is enabled is 32 byte when
MBEDTLS_ENTROPY_FORCE_SHA256 is enabled or MBEDTLS_SHA512_C is
disabled, and 64 bytes otherwise. A larger seedfile is ok on
entry (the code just grabs the first N bytes), but a smaller seedfile
is not ok. Therefore, if you run a component with a 32-byte seedfile
and then a component with a 64-byte seedfile, the second component
fails in the unit tests (up to test_suite_entropy which erases the
seedfile and creates a fresh one).

This is ok up to now because we only enable MBEDTLS_ENTROPY_NV_SEED
together with MBEDTLS_ENTROPY_FORCE_SHA256. But it prevents enabling
MBEDTLS_ENTROPY_NV_SEED without MBEDTLS_ENTROPY_FORCE_SHA256.

To fix this, unconditionally create a seedfile before each component.
2019-11-21 13:54:00 +01:00
.github Add github issue template 2018-11-29 15:53:00 +02:00
3rdparty Invoke config.py instead of config.pl 2019-11-13 14:33:33 +00:00
configs Add a reference configuration without any asymmetric cryptography 2019-10-11 18:21:08 +02:00
docs Merge remote-tracking branch 'myfork-public/development' into merge-crypto-development-20191115 2019-11-15 11:47:14 +01:00
doxygen Merge remote-tracking branch 'myfork-public/development' into merge-crypto-development-20191115 2019-11-15 11:47:14 +01:00
include Merge remote-tracking branch 'myfork-public/development' into merge-crypto-development-20191115 2019-11-15 11:47:14 +01:00
library MBEDTLS_CTR_DRBG_USE_128_BIT_KEY: add selftest data 2019-11-21 13:49:20 +01:00
programs Merge remote-tracking branch 'myfork-public/development' into merge-crypto-development-20191115 2019-11-15 11:47:14 +01:00
scripts config.pl full: exclude MBEDTLS_ENTROPY_FORCE_SHA256 2019-11-21 13:52:09 +01:00
tests all.sh: support variable seedfile size 2019-11-21 13:54:00 +01:00
visualc/VS2010 Merge pull request #185 from gilles-peskine-arm/harvard-md 2019-09-10 18:38:39 +01:00
.gitignore Merge branch 'development' into development 2019-05-29 14:44:16 +02:00
.globalrc Generate tags for Vi, for Emacs and with Global 2019-02-25 22:49:28 +01:00
.pylintrc Allow main() to lack a docstring. 2019-02-27 11:03:43 +01:00
.travis.yml Merge remote-tracking branch 'myfork-public/development' into merge-crypto-development-20191115 2019-11-15 11:47:14 +01:00
apache-2.0.txt Change main license to Apache 2.0 2015-09-04 14:21:07 +02:00
CMakeLists.txt cmake: fix Python requirement 2019-11-13 14:33:34 +00:00
CONTRIBUTING.md Fix #2370, minor typos and spelling mistakes 2019-01-24 10:37:40 +01:00
DartConfiguration.tcl Rename to mbed TLS in the documentation/comments 2015-01-22 16:11:05 +00:00
LICENSE Change main license to Apache 2.0 2015-09-04 14:21:07 +02:00
Makefile Invoke config.py instead of config.pl 2019-11-13 14:33:33 +00:00
README.md Merge remote-tracking branch 'origin/pr/2726' into development 2019-07-10 07:55:25 +01:00

Mbed Crypto library

The Mbed cryptography library is a reference implementation of the cryptography interface of the Arm Platform Security Architecture (PSA). This is a preview release of Mbed Crypto, provided for evaluation purposes only.

Mbed Crypto is distributed under the Apache License, version 2.0. See the LICENSE file for the full text of the license.

PSA cryptography 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 handles, 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.

Mbed Crypto implementation

Mbed Crypto is a reference implementation of the PSA cryptography API. It is written in portable C.

Documentation

The Mbed Crypto library is a reference implementation of the PSA cryptography API. Please refer to the PSA Cryptography API documents for an overview of the library's interfaces and a detailed description of the types, macros and functions that it provides.

There are currently a few deviations where the library does not yet implement the latest version of the specification. Please refer to the compliance issues on Github for an up-to-date list.

PSA Cryptography API

You can read the complete PSA cryptography API specification as a PDF document. The API reference is also available in HTML format.

Browsable library documentation

To generate a local copy of the library documentation in HTML format:

  1. Make sure that Doxygen is installed. We use version 1.8.11 but slightly older or more recent versions should work.
  2. Run make apidoc.
  3. Browse apidoc/index.html or apidoc/modules.html.

Compiling

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

  • GNU Make or a build tool that CMake supports.
  • A C99 toolchain (compiler, linker, archiver).
  • Python 2 or Python 3 (either will work) to generate the test code.
  • Perl to run the tests.

If you have a C compiler, such as GCC or Clang, just run make in the top-level directory to build the library, a set of unit tests and some sample programs.

To select a different compiler, set the CC variable to the name or path of the compiler and linker (default: cc), and set AR to a compatible archiver (default: ar). For example:

make CC=arm-linux-gnueabi-gcc AR=arm-linux-gnueabi-ar

The provided makefiles pass options to the compiler that assume a GCC-like command-line syntax. To use a different compiler, you may need to pass different values for CFLAGS, WARNINGS_CFLAGS and LDFLAGS.

To run the unit tests on the host machine, run make test from the top-level directory. If you are cross-compiling, copy the test executable from the tests directory to the target machine.

Compiling as a subproject

Mbed Crypto supports being built as a subproject of Mbed TLS. Mbed TLS can use Mbed Crypto for its cryptography implementation by using Mbed Crypto as a subproject.

From the Mbed TLS project repository, CMake can be invoked as follows to build Mbed TLS using Mbed Crypto's libmbedcrypto.

mkdir cmake
cd cmake
cmake .. -DUSE_CRYPTO_SUBMODULE=1
make -j
make test

When building Mbed Crypto as a subproject of Mbed TLS, the Mbed TLS configuration file (config.h) is used, and not the Mbed Crypto configuration file.

Example programs

The programs/ subdirectory contains sample programs that use the library. 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.

Upcoming features

Future releases of this library will include:

  • A driver programming interface, which makes it possible to use hardware accelerators instead of the default software implementation for chosen algorithms.
  • Support for external keys to be stored and manipulated exclusively in a separate cryptoprocessor.
  • A configuration mechanism to compile only the algorithms you need for your application.
  • A wider set of cryptographic algorithms.

Feedback welcome

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 mbed-crypto@arm.com. All feedback received by email is treated confidentially.