Introduction

Mbed Crypto 3.1.0 has now been released. This release brings fixes for a security issue, as described in more detail in our security advisory.

The Mbed cryptography library is a reference implementation of the cryptography interface of the Arm Platform Security (PSA) architecture. Note that while this library is versioned as 3.1.0, the PSA APIs are under development and subject to change based on feedback. The next release of Mbed Crypto may not provide backwards compatibility with this release.

Security

• Fix potential memory overread when performing an ECDSA signature operation. The overread only happens with cryptographically low probability (of the order of 2^-n where n is the bitsize of the curve) unless the RNG is broken, and could result in information disclosure or denial of service (application crash or extra resource consumption). Found by Auke Zeilstra and Peter Schwabe, using static analysis.
• To avoid a side channel vulnerability when parsing an RSA private key, read all the CRT parameters from the DER structure rather than reconstructing them. Found by Alejandro Cabrera Aldaya and Billy Bob Brumley. Reported and fix contributed by Jack Lloyd.

Features

• The new build option MBEDTLS_SHA512_NO_SHA384 allows building SHA-512 support without SHA-384.

API Changes

• Change the encoding of key types and curves in the PSA API. The new values are aligned with the upcoming release of the PSA Crypto API specification version 1.0.0. The main change which may break some existing code is that elliptic curve key types no longer encode the exact curve: a psa_ecc_curve_t or psa_key_type_t value only encodes a curve family and the key size determines the exact curve (for example, PSA_ECC_CURVE_SECP_R1 with 256 bits is P256R1).

Bugfix

• Fix a possible error code mangling in psa_mac_verify_finish() when a cryptographic accelerator fails.
• Fix a bug in mbedtls_pk_parse_key() that would cause it to accept some RSA keys that would later be rejected by functions expecting private keys. Found by Catena cyber using oss-fuzz (issue 20467).
• Fix a bug in mbedtls_pk_parse_key() that would cause it to accept some RSA keys with invalid values by silently fixing those values.

Who should update

We recommend all affected users should update to take advantage of the bug fixes contained in this release at an appropriate point in their development lifecycle.

Introduction

Mbed Crypto 3.0.1 has now been released. This release brings fixes for a security issue, as described in more detail in our security advisory.

The Mbed cryptography library is a reference implementation of the cryptography interface of the Arm Platform Security (PSA) architecture. Note that while this library is versioned as 3.0.1, the PSA APIs are under development and subject to change based on feedback. The next release of Mbed Crypto may not provide backwards compatibility with this release.

Default behavior changes

• The initial seeding of a CTR_DRBG instance makes a second call to the entropy function to obtain entropy for a nonce if the entropy size is less than 3/2 times the key size. In case you want to disable the extra call to grab entropy, you can call mbedtls_ctr_drbg_set_nonce_len() to force the nonce length to 0.

Security

• Enforce that mbedtls_entropy_func() gathers a total of MBEDTLS_ENTROPY_BLOCK_SIZE bytes or more from strong sources. In the default configuration, on a platform with a single entropy source, the entropy module formerly only grabbed 32 bytes, which is good enough for security if the source is genuinely strong, but less than the expected 64 bytes (size of the entropy accumulator).
• Zeroize local variables in mbedtls_internal_aes_encrypt() and mbedtls_internal_aes_decrypt() before exiting the function. The value of these variables can be used to recover the last round key. To follow best practice and to limit the impact of buffer overread vulnerabilities (like Heartbleed) we need to zeroize them before exiting the function. Issue reported by Tuba Yavuz, Farhaan Fowze, Ken (Yihang) Bai, Grant Hernandez, and Kevin Butler (University of Florida) and Dave Tian (Purdue University).
• Fix side channel vulnerability in ECDSA. Our bignum implementation is not constant time/constant trace, so side channel attacks can retrieve the blinded value, factor it (as it is smaller than RSA keys and not guaranteed to have only large prime factors), and then, by brute force, recover the key. Reported by Alejandro Cabrera Aldaya and Billy Brumley.
• Fix side channel vulnerability in ECDSA key generation. Obtaining precise timings on the comparison in the key generation enabled the attacker to learn leading bits of the ephemeral key used during ECDSA signatures and to recover the private key. Reported by Jeremy Dubeuf.
• Catch failure of AES functions in mbedtls_ctr_drbg_random(). Uncaught failures could happen with alternative implementations of AES. Bug reported and fix proposed by Johan Uppman Bruce and Christoffer Lauri, Sectra.

Features

• Key derivation inputs in the PSA API can now either come from a key object or from a buffer regardless of the step type.
• The CTR_DRBG module can grab a nonce from the entropy source during the initial seeding. The default nonce length is chosen based on the key size to achieve the security strength defined by NIST SP 800-90A. You can change it with mbedtls_ctr_drbg_set_nonce_len().
• Add ENUMERATED tag support to the ASN.1 module. Contributed by msopiha-linaro.

API changes

• In the PSA API, forbid zero-length keys. To pass a zero-length input to a key derivation function, use a buffer instead (this is now always possible).
• Rename psa_asymmetric_sign() to psa_sign_hash() and psa_asymmetric_verify() to psa_verify_hash().

Bugfix

• Fix a buffer overflow in the PSA HMAC code when using a long key with an unsupported algorithm.
• Fix mbedtls_asn1_get_int to support any number of leading zeros. Credit to OSS-Fuzz for finding a bug in an intermediate version of the fix.
• Fix mbedtls_asn1_get_bitstring_null to correctly parse bitstrings of at most 2 bytes.
• mbedtls_ctr_drbg_set_entropy_len() and mbedtls_hmac_drbg_set_entropy_len() now work if you call them before mbedtls_ctr_drbg_seed() or mbedtls_hmac_drbg_seed().

Changes

• Remove the technical possibility to define custom mbedtls_md_info structures, which was exposed only in an internal header.
• psa_close_key(0) and psa_destroy_key(0) now succeed (doing nothing, as before).
• Variables containing error codes are now initialized to an error code rather than success, so that coding mistakes or memory corruption tends to cause functions to return this error code rather than a success. There are no known instances where this changes the behavior of the library: this is merely a robustness improvement.
• Remove a useless call to mbedtls_ecp_group_free(). Contributed by Alexander Krizhanovsky
• Speed up PBKDF2 by caching the digest calculation. Contributed by Jack Lloyd and Fortanix Inc
• Small performance improvement of mbedtls_mpi_div_mpi(). Contributed by Alexander Krizhanovsky

Who should update

We recommend all affected users should update to take advantage of the bug fixes contained in this release at an appropriate point in their development lifecycle.

Introduction

Mbed Crypto 2.0.0 has now been released.

The Mbed cryptography library is a reference implementation of the cryptography interface of the Arm Platform Security (PSA) architecture. Note that while this library is versioned as 2.0.0, the PSA APIs are under development and subject to change based on feedback. The next release of Mbed Crypto may not provide backwards compatibility with this release.

Security

• Fix a missing error detection in ECJPAKE. This could have caused a predictable shared secret if a hardware accelerator failed and the other side of the key exchange had a similar bug.
• When writing a private EC key, use a constant size for the private value, as specified in RFC 5915. Previously, the value was written as an ASN.1 INTEGER, which caused the size of the key to leak about 1 bit of information on average and could cause the value to be 1 byte too large for the output buffer.
• The deterministic ECDSA calculation reused the scheme's HMAC-DRBG to implement blinding. Because of this for the same key and message the same blinding value was generated. This reduced the effectiveness of the countermeasure and leaked information about the private key through side channels. Reported by Jack Lloyd.

Features

• New implementation of X25519 (ECDH using Curve25519) from Project Everest (https://project-everest.github.io/). It can be enabled at compile time with MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED. This implementation is formally verified and significantly faster, but is only supported on x86 platforms (32-bit and 64-bit) using GCC, Clang or Visual Studio. Contributed by Christoph Wintersteiger from Microsoft Research.

API Changes

• The new function mbedtls_ecdsa_sign_det_ext() is similar to mbedtls_ecdsa_sign_det() but allows passing an external RNG for the purpose of blinding.
• The new function mbedtls_ecp_gen_privkey() allows to generate a private key without generating the public part of the pair.

PSA Crypto API 1.0b3 API breaking changes

Mbed Crypto tracks the upstream PSA Crypto API, so a number of breaking changes come in this release. Details on migration available in the section "Migrating from Mbed Crypto 1.x" below.

• Use key attributes structures for key creation
• Make generating or importing a key also allocate the key
• Update key derivation functions to accept chunked inputs
• Update key agreement API
• Align PSA Crypto error codes with other PSA error codes
• Rename functions for consistency with each other and the rest of PSA
• Be consistent in use of stdint types

Bugfix

• Fix to allow building test suites with any warning that detects unused functions. Fixes #1628.
• Remove redundant include file in timing.c. Fixes ARMmbed/mbed-tls#2640 reported by irwir.
• Fix Visual Studio Release x64 build configuration by inheriting PlatformToolset from the project configuration. Fixes ARMmbed/mbed-tls#1430 reported by irwir.
• Enable Suite B with subset of ECP curves. Make sure the code compiles even if some curves are not defined. Fixes ARMmbed/mbed-tls#1591 reported by dbedev.
• Fix misuse of signed arithmetic in the HAVEGE module. ARMmbed/mbed-tls#2598
• Update test certificates that were about to expire. Reported by Bernhard M. Wiedemann in ARMmbed/mbed-tls#2357.
• Fix the build on ARMv5TE in ARM mode to not use assembly instructions that are only available in Thumb mode. Fix contributed by Aurelien Jarno in ARMmbed/mbed-tls#2169.
• Fix propagation of restart contexts in restartable EC operations. This could previously lead to segmentation faults in builds using an address-sanitizer and enabling but not using MBEDTLS_ECP_RESTARTABLE.
• Fix memory leak in in mpi_miller_rabin(). Contributed by Jens Wiklander jens.wiklander@linaro.org in ARMmbed/mbed-tls#2363
• Fix bug in endianness conversion in bignum module. This lead to functionally incorrect code on bigendian systems which don't have BYTE_ORDER defined. Reported by Brendan Shanks. Fixes ARMmbed/mbed-tls#2622.
• Fix undefined memset(NULL) call in test_suite_nist_kw.
• Make NV seed test support MBEDTLS_ENTROPY_FORCE_SHA256.
• Zero length buffer check for undefined behavior in mbedtls_platform_zeroize(). Fixes #49.

Changes

• Make it easier to define MBEDTLS_PARAM_FAILED as assert (which config.h suggests). ARMmbed/mbed-tls#2671
• Make make clean clean all programs always. Fixes ARMmbed/mbed-tls#1862.

Who should update

We recommend all affected users should update to take advantage of the bug fixes contained in this release at an appropriate point in their development lifecycle.

Migrating from Mbed Crypto 1.x

Renaming of key pair names

Replace KEY_PAIR in names that would have used KEYPAIR in the previous API version. For example, PSA_KEY_TYPE_ECC_KEY_PAIR replaces PSA_KEY_TYPE_ECC_KEYPAIR.

Using persistent keys

Use psa_open_key() to open a persistent key. Previously, volatile keys could also be opened. With PSA Crypto API 1.0b3, keys are implicitly opened for you upon import, generation, or derivation.

psa_status_t psa_open_key(psa_key_id_t id,
                          psa_key_handle_t *handle);

Only persistent keys can be opened, so there is no need to pass the lifetime anymore.

It is no longer necessary to call psa_create_key() to make a key persistent. A key is persistent if it is created with a lifetime other than PSA_KEY_LIFETIME_VOLATILE. As part of key creation, use psa_set_key_id() to set both the key's persistent identifier and to set the lifetime to persistent and then call the key creation routine: like psa_generate_key() or psa_import_key()

Allocating keys

Key creation will implicitly allocate resources as necessary, so psa_allocate_key() has been removed from the API and is no longer needed.

Importing keys

Previously, you had create a policy structure and pass many function arguments to communicate the properties you wanted the imported key to have. Now, you describe them entirely within the attributes structure, passing only the attributes and data to psa_import_key().

Generating keys

Previously, you had create a policy structure and pass many function arguments to communicate the properties you wanted the imported key to have. Now, you describe them entirely within the attributes structure, passing only the attributes and data to psa_generate_key().

Reading key policy or information

What used to be two functions with many parameters each is now one function that returns the attributes in one structure, in the same format you'd use to create new keys.

Deriving keys

The previous "generator" class of functions has been renamed to "key_derivation". The psa_crypto_generator_t structure was previously used to derive keys. Use of the psa_key_derivation_operation_t structure replaces psa_crypto_generator_t for deriving keys.

Key agreement

Hashing

Note: Not yet implemented in Mbed Crypto 2.0.0

The PSA Crypto API 1.0b3 adds a few new functions to help with hashing. Specifically, functions to perform one-shot computation or comparison of hashes.

Introduction

Mbed Crypto 1.1.0 has now been released.

The Mbed cryptography library is a reference implementation of the cryptography interface of the Arm Platform Security (PSA) architecture. Note that while this library is versioned as 1.1.0, the PSA APIs are under development and subject to change based on feedback. Mbed Crypto 1.1.0 implements PSA Crypto API 1.0b1. The next release of Mbed Crypto may not provide backwards compatibility with this release.

Features

• Keys may allow a second algorithm. Added to support RFC 4492 section 3.2 ECDSA_fixed_ECDH.
• Add a macro to get the bit size of an elliptic curve, PSA_ECC_CURVE_BITS().
• Add the Any Policy certificate policy oid, as defined in RFC 5280 section 4.2.1.4.
• It is now possible to use NIST key wrap mode via the mbedtls_cipher API. Contributed by Jack Lloyd and Fortanix Inc.
• Add the Wi-SUN Field Area Network (FAN) device extended key usage.
• It is now possible to perform RSA PKCS v1.5 signatures with RIPEMD-160 digest. Contributed by Jack Lloyd and Fortanix Inc.

Bugfix

• Fix private key DER output in the key_app_writer example. File contents were shifted by one byte, creating an invalid ASN.1 tag. Fixed by Christian Walther in #2239.
• Reduce stack usage of HKDF tests. Fixes #2195.
• Fix 1-byte buffer overflow in mbedtls_mpi_write_string() when used with negative inputs. Found by Guido Vranken in #2404. Credit to OSS-Fuzz.
• Fix bugs in the AEAD test suite which would be exposed by ciphers which either used both encrypt and decrypt key schedules, or which perform padding. GCM and CCM were not affected. Fixed by Jack Lloyd.

Security

• Make mbedtls_ecdh_get_params return an error if the second key belongs to a different group from the first. Before, if an application passed keys that belonged to different group, the first key's data was interpreted according to the second group, which could lead to either an error or a meaningless output from mbedtls_ecdh_get_params. In the latter case, this could expose at most 5 bits of the private key.

Changes

• Removal of the X.509 and TLS modules from Mbed Crypto, which continue to be maintained within Mbed TLS.
• Removed the Diffie-Hellman examples which implemented a toy protocol inspired by TLS DH key exchange. For an example of how to use the DHM module, see the code that calls mbedtls_dhm_xxx in ssl_tls.c and ssl_cli.c in Mbed TLS.
• Remove dead code from bignum.c in the default configuration. Found by Coverity, reported and fixed by Peter Kolbus (Garmin). Fixes #2309.
• Add test for minimal value of MBEDTLS_MPI_WINDOW_SIZE to all.sh. Contributed by Peter Kolbus (Garmin).
• Ensure that unused bits are zero when writing ASN.1 bitstrings when using
  mbedtls_asn1_write_bitstring().
• Fix issue when writing the named bitstrings in KeyUsage and NsCertType
  extensions in CSRs and CRTs that caused these bitstrings to not be encoded
  correctly as trailing zeroes were not accounted for as unused bits in the
  leading content octet. Fixes #1610.
• Add a new function mbedtls_asn1_write_named_bitstring() to write ASN.1
  named bitstring in DER as required by RFC 5280 Appendix B.
• Fix false failure in all.sh when backup files exist in include/mbedtls
  (e.g. config.h.bak). Fixed by Peter Kolbus (Garmin) #2407.

Driver model

This release includes a specification of the interface that drivers for cryptography accelerators, entropy sources and secure elements must implement. This specification is a work in progress, provided for review purposes only. The implementation does not support drivers yet. The specification is provided in the distribution as docs/PSACryptoDriverModelSpec.pdf.

Intended future changes

The PSA Crypto API is still under development and subject to change based on feedback. The following is a list of major changes that we intend to make in the near future. This list may be revised without notice at any time.

Expected breaking changes from tracking the PSA Crypto API, to be addressed in Mbed Crypto 2.0.0

• Update key derivation functions to accept chunked inputs #37
• Update key agreement API #37
• Simplify key allocation and configuration
• Rename functions for consistency with each other and the rest of PSA

Introduction

Mbed Crypto 1.0.0 has now been released.

The Mbed cryptography library is a reference implementation of the cryptography interface of the Arm Platform Security (PSA) architecture. Note that while this library is versioned as 1.0.0, the PSA APIs are under development and subject to change based on feedback. The next release of Mbed Crypto may not provide backwards compatibility with this release.

New features

This release of Mbed Crypto adds support for the following features:

• Manage keys through handles instead of requiring external key slot management.
• Implement the new function psa_copy_key(), allowing copying keys between key slots without an export.
• Implement the function psa_hash_clone(), enabling TLS stacks built on PSA to use the intermediate result of hash calculations as part of the TLS handshake.
• Simplify the format of RSA and EC keys, removing the SubjectPublicKeyInfo encoding layer.
• Support wildcard hash in signature policies. This supports concrete use cases which require a different trade-off between safety and flexibility. In particular, X.509 makes it impractical to commit a signature key to a specific hash mechanism as was previously required.
• Other changes for compliance with the PSA Crypto API 1.0.0b1.
• Support 64-bit key IDs when integrated with a PSA Secure Partition Manager (SPM).

API Changes

What is being broken?

By continuing to track the PSA Crypto API, this release of Mbed Crypto includes API breaking changes.

PSA Crypto API 1.0b1 API breaking changes, addressed in Mbed Crypto 1.0.0

• Simplify the EC and RSA public key formats
• Replace manual key slot allocation with dynamic key slot allocation and key handles (affects most PSA Crypto API functions)
• Add and require initializers for PSA Crypto contexts
• Align PSA Crypto error codes with other PSA error codes

Why is it being broken?

Mbed Crypto needs to track the PSA Crypto API in order remain PSA compliant. The PSA Crypto API was not yet finalized in Mbed Crypto 0.1.0 and continues to evolve. We shipped an implementation of early PSA Crypto APIs in Mbed Crypto 0.1.0 to enable building services atop APIs that should be similar to, but may not be compatible with, future versions of the PSA Crypto API.

Impact

Compilation or linker failures when using code written against Mbed Crypto 0.1.0 with Mbed Crypto 1.0.0.

Mitigation and migration path

Please update to the new version of the API.

• Key handles replace key slots. Adapting to this change requires accessing key slots via handles instead of using key slots directly. To obtain a handle to a volatile key slot, allocate a slot with psa_allocate_key(). To obtain a handle to a persistent key slot, open the key from storage with psa_open_key().
• Use the new RSA and EC key formats, as documented in crypto.h.
• Initialize PSA crypto contexts before use using appropriate initializers, as documented for each context type in crypto.h.
• Update to using new PSA error codes. Previous error codes have been deprecated.

Driver model

This release includes a specification of the interface that drivers for cryptography accelerators, entropy sources and secure elements must implement. This specification is a work in progress, provided for review purposes only. The implementation does not support drivers yet. The specification is provided in the distribution as docs/PSACryptoDriverModelSpec.pdf.

Intended future changes

The PSA Crypto API is still under development and subject to change based on feedback. The following is a list of major changes that we intend to make in the near future. This list may be revised without notice at any time.

Expected breaking changes from tracking the PSA Crypto API, to be addressed in Mbed Crypto 2.0.0

• Update key derivation functions to accept chunked inputs #37
• Update key agreement API #37
• Simplify key allocation and configuration
• Rename functions for consistency with each other and the rest of PSA

Introduction

Mbed Crypto 0.1.0b2 has now been released.

The Mbed cryptography library is a reference implementation of the cryptography interface of the Arm Platform Security (PSA) architecture. This is a preview release of Mbed Crypto, provided for evaluation purposes only. As this is an beta and evaluation release, APIs are under development and subject to change based on feedback.

New features

This release of Mbed Crypto adds support for the following features:

• The interface now includes key agreement. The implementation supports ECDH.
• The key derivation interface supports two new function families: the TLS 1.2 PRF (pseudorandom function) and the transformation from TLS 1.2 PSK (pre-shared key) to master secret.
• Truncated MAC algorithms and AEAD with shorter tags are defined in the interface, and they are implemented for all algorithms for which the base algorithm is implemented.
• The implementation now supports persistent keys. Keys can be saved either to stdio files or to PSA ITS (Internal Trusted Storage) objects, based on a compilation option. To declare a key as persistent, call psa_set_key_lifetime() before creating or using the key. Note that this implementation is considered experimental and future releases are unlikely to maintain backward compatibility with the current storage format or to provide an upgrade path.
• We provide a mechanism for injecting initial entropy into a device that has trusted storage but may lack a hardware random number generator. Note that this implementation is considered experimental and future releases are unlikely to maintain backward compatibility with the current storage format or to provide a generic upgrade path. We will provide an upgrade path for the integration of this feature in Mbed OS 5.11.

Driver model

This release includes a specification of the interface that drivers for cryptography accelerators, entropy sources and secure elements must implement. This specification is a work in progress, provided for review purposes only. The implementation does not support drivers yet. The specification is provided in the distribution as docs/PSACryptoDriverModelSpec.pdf.

Other changes

The following changes may affect existing application code:

• Many macros to compose and decompose key types and algorithms have been added or modified to offer a more consistent interface.
• The import/export format of elliptic curve key pairs has changed from the RFC 5915 private key to the raw secret value.

In addition, the interface and the implementation include many tweaks and bug fixes that should not require changes in application source code.

Intended future changes

APIs are under development and subject to change based on feedback. The following is a list of major changes that we intend to make in the near future. This list may be revised without notice at any time.

• Instead of using key slots transparently, applications will access slots via handles. To obtain a handle to a volatile key slot, the application will allocate a slot. To obtain a handle to a persistent key slot, the application will open the key from storage.
• Simplify the format of public keys to remove the SubjectPublicKeyInfo encoding layer.
• Enrich the policy language to support concrete use cases which require a different trade-off between safety and flexibility. In particular, X.509 makes it impractical to commit a signature key to a specific hash mechanism.

Overview

The Mbed cryptography library is a reference implementation of the cryptography interface of the Arm Platform Security (PSA) architecture. This is a preview release of Mbed Crypto, provided for evaluation purposes only. As this is an alpha and evaluation release, APIs are under development and subject to change based on feedback.

Features

Mbed Crypto 0.1.0a provides the following features:

• Opaque key handles through key slots
• Key slot configuration and management
• Hashes - psa_hash_xxx() functions
• MAC - psa_mac_xxx() functions
• Symmetric ciphers - psa_cipher_xxx() functions
• Authenticated encryption (AEAD) - psa_aead_xxx() functions
• Asymmetric cryptography - psa_asymmetric_xxx() functions
• Random number generation - psa_generate_random() function
• Key derivation - psa_key_derivation() function