Skip to content

Mbed Crypto 2.0.0
Compare
Choose a tag to compare
@Patater Patater released this 18 Sep 13:00
· 1036 commits to development since this release
mbedcrypto-2.0.0
92348d1

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 [email protected] 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()

Old New
psa_open_key() Only use for opening previously created persistent keys
psa_create_key() psa_set_key_id() Keys with IDs are made persistent implicitly upon creation

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.

Old New
psa_allocate_key() Not necessary. Delete calls to psa_allocate_key().

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

Old New
psa_key_policy_init() psa_key_attributes_init()
psa_key_policy_set_usage() psa_set_key_usage_flags(), psa_set_key_algorithm()
Pass key type to psa_import_key() psa_set_key_type()
psa_set_key_policy() Pass the attributes to psa_import_key()
psa_import_key() 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().

Old New
psa_key_policy_init() psa_key_attributes_init()
psa_key_policy_set_usage() psa_set_key_usage_flags(), psa_set_key_algorithm()
Pass key type to psa_import_key() psa_set_key_type()
psa_set_key_policy() Pass the attributes to psa_import_key()
psa_generate_key() 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.

Old New
psa_get_key_policy(), psa_get_key_information() psa_get_key_attributes()

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.

Old New
psa_crypto_generator_t psa_key_derivation_operation_t
psa_generator_abort() psa_key_derivation_abort()
psa_get_generator_capacity() psa_key_derivation_get_capacity()
Function parameter psa_key_derivation_set_capacity()
psa_generator_read() psa_key_derivation_output_bytes()
Use of generator with PSA_ALG_SELECT_RAW psa_raw_key_agreement()
psa_key_derivation() Deriving keys now uses key derivation objects and consists of multiple parts. See the getting started guide for details.

Key agreement

Old New
psa_key_agreement() psa_key_derivation_setup(), psa_key_derivation_key_agreement(), psa_key_derivation_output_key()

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.

Old New
Many hash function calls psa_hash_compute()
Many hash function calls psa_hash_compare()

Computing or verifying a MAC

Note: Not yet implemented in Mbed Crypto 2.0.0

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

Old New
Many MAC function calls psa_mac_compute()
Many MAC function calls psa_mac_verify()

Symmetric cryptography

Note: Not yet implemented in Mbed Crypto 2.0.0

The PSA Crypto API 1.0b3 adds a few new functions to help with working with symmetric ciphers. Specifically, functions to perform one-shot encryption or decryption. The types used by psa_cipher_generate_iv(), psa_cipher_set_iv(), and psa_cipher_update() have changed from unsigned char to uint8_t.

Old New
Many cipher function calls psa_cipher_encrypt()
Many cipher function calls psa_cipher_decrypt()

Authenticated encryption

Note: Not yet implemented in Mbed Crypto 2.0.0

The PSA Crypto API 1.0b3 introduces multi-part authenticated encryption functions. The original one-shot AEAD functions still remain and aren't being replaced.

New functions for multipart AEAD
  • psa_aead_operation_init()
  • psa_aead_encrypt_setup()
  • psa_aead_decrypt_setup()
  • psa_aead_generate_nonce()
  • psa_aead_set_nonce()
  • psa_aead_set_lengths()
  • psa_aead_update_ad()
  • psa_aead_update()
  • psa_aead_finish()
  • psa_aead_verify()
  • psa_aead_abort()

Mbed Crypto entropy injection

Use of uint8_t replaces unsigned char in mbedtls_psa_inject_entropy(). The macro MBEDTLS_PSA_INJECT_ENTROPY replaces MBEDTLS_PSA_ENTROPY_INJECTION.

Assets 2
Loading