mbed-tls / tf-psa-crypto Goto Github PK

As part of our implementation of the PSA cryptography API, we need to define macros(like configuration options), types (like operation object types) and functions that are specific to our implementation. In Mbed TLS repository where the PSA cryptography API implementation is located for the time being those symbols are prefixed with MBEDTLS_PSA_ or mbedtls_psa_ as we think about our implementation as the Mbed TLS implementation of the PSA cryptography API. With the move of the PSA cryptography implementation to its own repository named PSA-Crypto, one may wonder if this should change or not.

As we aim for a group of three repositories (mbedtls, psa-crypto, mbedtls-tf(?)) I think it makes sense to keep the PSA cryptography implementation under the Mbed TLS umbrella. We would then keep the MBEDTLS_PSA_ and mbedtls_psa_ prefixes for the symbols specific to the implementation of the PSA cryptography API. We would also keep MBEDTLS_ and mbedtls_ prefixes for macros, types and functions exposed by PSA-Crypto beyond the PSA cryptography API, thinking about LMS, asn1 (useful to implement protocols like but not restricted to TLS using PSA Crypto API), platform(?) APIs here.

Add generated file checks

• Adapt tests/scripts/check-generated-files.sh to work for both mbedtls and psa-crypto. Note: psa-crypto has less generated files: no error.c, version_features.c, ssl_debug_helpers_generated.c, visualc/VS2013 ...
• Add component_check_generated_files all.sh component. Note: no make build system, CMake should be used instead

DOD: Same support for generated file checking in psa-crypto as in mbedtls

The development branch of the PSA cryptography repository is aimed to contain only code specific to the repo, not the files copied from the Mbed TLS repository. That's the purpose of the main branch to contain the content of the development branch and the files copied from a given commit of the Mbed TLS repository.

The purpose of this task is to create the main branch, document it together with the development branch in a BRANCHES.md file and describe the process to update it from a new commit of the Mbed TLS repository.

Add same support for Microsoft Visual Studio as in Mbed TLS in the PSA cryptography repository.

• CMake file
• vs2013.*template.*, NOT NECESSARY
• generate_visualc_files.pl NOT NECESSARY
• README.md
• common.h
• platform.{h,c}
• x86 specific configuration options like MBEDTLS_AESNI_C
• test we can compile the library with MSVC as CMake project and run Ctest successfully on windows

Fixed by #28.

Similar to the MBEDTLS_DEPRECATED_REMOVED/WARNING mbedtls config options, add PSA_CRYPTO_DEPRECATED_REMOVED/WARNING config options.

• Add PSA_CRYPTO_DEPRECATED_REMOVED/WARNING and their documentation in the "General configuration options" section of crypto_config.h. Disabled by default.
• Add their translation to MBEDTLS_DEPRECATED_REMOVED/WARNING in config_adjust_mbedtls_from_psa_crypto.h
• Add a test_default_no_deprecated all.sh component as the one in mbedtls.

Note: no all.sh component with PSA_CRYPTO_DEPRECATED_WARNING for the time being. We need to define first what is the psa-crypto full configuration is to add all.sh components involving PSA_CRYPTO_DEPRECATED_WARNING similar to the one involving
MBEDTLS_DEPRECATED_WARNING in mbedtls.

• Add PSA_CRYPTO_TEST_CONSTANT_FLOW_MEMSAN/VALGRIND config options and their documentations in the section "General configuration options" of crypto_config.h. Disabled by default.
• Add test_memsan, test_memsan_constant_flow_psa, test_valgrind_psa, test_valgrind_constant_flow_psa test components
• Check that the test components do what they intend to do and give evidence of this in this issue or the associated PR for the benefit of reviewers

Depends on:

• #58 to set up the full config

Investigate which Mbed TLS all.sh test and build components should have an equivalent in psa-crypto and in what form.
List of Mbed TLS test components in the below tables as of 87fe996.

Below table of the Mbed TLS all.sh test components for which it is planned to have an equivalent in psa-crypto:

Document any differences in the release process that apply to PSA Crypto as opposed to Mbed TLS.

• Add PSA_CRYPTO_SHA256/512_USE_A64_CRYPTO_xyz config options as the MBEDTLS_SHA256/512_USE_A64_CRYPTO_xyz ones (four of them) and their documentation in the section "PSA driver interface implementation configuration options" of crypto_config.h
• The _IF_PRESENT ones are enabled by default. The _ONLY ones are disabled by default.
• Add their translation to MBEDTLS_SHA256/512_USE_A64_CRYPTO_xyz in config_adjust_mbedtls_from_psa_crypto.h

Note: no all.sh component for the _IF_PRESENT config options in Mbed TLS.

Update monthly the PSA crypto main branch against Mbed TLS development as described in the section "Updating the main branch" in psa-crypto-repository.md.

As part of the work to bring the testing in PSA-Crypto at the level it is in Mbed-TLS, add in tests/all_sh_components.txt a component equivalent to component_test_psa_crypto_config_accel_ecdsa to be the first libtestdriver1 component in PSA-Crypto.

. the cmake build system needs to be used instead of the make one.
. some adjustments to the all.sh framework (everything but the components in all.sh) is likely to be necessary.

• Add PSA_CRYPTO_ECP_WITH_MPI_UINT config option and its documentation in the section "PSA driver interface implementation configuration options" of crypto_config.h. Similar to MBEDTLS_ECP_WITH_MPI_UINT in Mbed TLS. Disabled by default.
• Add its translation to MBEDTLS_ECP_WITH_MPI_UINT in config_adjust_mbedtls_from_psa_crypto.h.
• Rename test_default_cmake_gcc_asan to test_default_gcc_asan
• Add test_default_gcc_asan_new_bignum all.sh component similar to the test_default_cmake_gcc_asan_new_bignum one in Mbed TLS. No self test, just run the unit test suites for the time being.
• Check that the test component do what it intends to do and give evidence of this in this issue or the associated PR for the benefit of reviewers.

• Add PSA_CRYPTO_AES_USE_HARDWARE_ONLY config option and its documentation in the section "PSA driver interface implementation configuration options" of crypto_config.h. Similar to MBEDTLS_AES_USE_HARDWARE_ONLY in mbedtls. Disabled by default.
• Add PSA_CRYPTO_AES_ONLY_128_BIT_KEY_LENGTH config option and its documentation in the section "PSA driver interface implementation configuration options" of crypto_config.h. Similar to MBEDTLS_AES_ONLY_128_BIT_KEY_LENGTH in mbedtls. Disabled by default.
• Add test_aesni, test_aes_only_128_bit_keys, test_aes_only_128_bit_keys_have_builtins, test_aes_fewer_tables, test_aes_rom_tables, test_fewer_tables_and_rom_tables test components
• Check that the test components do what they intend to do and give evidence of this in this issue or the associated PR for the benefit of reviewers

Notes:

• test_aesni_m32 is out of scope as MBEDTLS_PADLOCK_C is planned for removal in 4.0 (see #5903).
• self tests out of scope

Define the configuration corresponding to TF-M profile small. Define an all.sh component to test the configuration.
https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git/tree/lib/ext/mbedcrypto/mbedcrypto_config/crypto_config_profile_small.h

Add in psa-crypto the equivalent of the components:

• test_full_cmake_gcc_asan
• test_full_cmake_gcc_asan_new_bignum
• test_full_no_deprecated
• test_full_no_deprecated_deprecated_warning
• test_full_deprecated_warning
• test_full_cmake_clang

Not in scope of this issue:

• self-tests
• test_full_cmake_gcc_asan_new_bignum_test_hooks
• test_full_no_cipher
• test_full_no_bignum

Depends on:

• #58 to set up the full config
• #56 for the PSA_CRYPTO_ECP_WITH_MPI_UINT config option
• #54 for the PSA_CRYPTO_DEPRECATED_REMOVED/WARNING config options

Add file checks

• Adapt tests/scripts/check_files.py to work for both mbedtls and psa-crypto.
• Add component_check_files all.sh component.

DOD: Same support for file checking in psa-crypto as in mbedtls

The configuration of the PSA cryptography repository is based on the PSA cryptography configuration as described in psa-conditional-incluson-c.md. Some additional implementation (not specification) specific configuration is needed though. The goal of this task is to define and document this.

The Mbed TLS configuration file mbedtls_config.h is still used internally in builtin but not accessible to the user.
Configuration options in mbedtls_config.h relevant to the PSA implementation:

MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER
MBEDTLS_PSA_CRYPTO_BUILTIN_KEYS
MBEDTLS_PSA_CRYPTO_CLIENT Not sure about the use cases
MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG
MBEDTLS_PSA_CRYPTO_SPM
MBEDTLS_PSA_INJECT_ENTROPY keep ?
MBEDTLS_PSA_CRYPTO_STORAGE_C
MBEDTLS_PSA_ITS_FILE_C

MBEDTLS_PSA_HMAC_DRBG_MD_TYPE MBEDTLS_MD_SHA256 ?
MBEDTLS_PSA_CRYPTO_CONFIG_FILE "psa/crypto_config.h"
MBEDTLS_PSA_CRYPTO_USER_CONFIG_FILE "/dev/null"
MBEDTLS_PSA_KEY_SLOT_COUNT 32

MBEDTLS_TEST_HOOKS

We probably need a psa_crypto_config.h with an equivalent to the above plus somehow crypto_config.h.

No equivalent of mbedtls/check_config.h, rather resolve dependencies?

Add check_recursion and check_test_cases all.sh components.
Note: recursion.pl and check_test_cases.py does not need to be adapted to psa-crypto, they just work for psa-crypto as well.

We must use the same license as Mbed TLS, so that when Mbed TLS pulls in PSA-Crypto source code, it can redistribute it under the licensing scheme used by Mbed TLS.

If Mbed TLS reverts to Apache 2.0 or GPL 2, this means that PSA-Crypto must do the same. We will have a definite decision on this in mid-October time, so it makes sense to delay making PSA-Crypto public until we know which option we will go for.

In preparation of publication, improve the documentation of the repository: add BUGS.md, SECURITY.md, files in Mbed TLS docs relevant to PSA-Crypto. Add semantic versioning documentation.
Timebox task.

Add semantic versioning in PSA-Crypto as it is in Mbed-TLS.
Three macros defining the version: PSA_CRYPTO_VERSION_MAJOR/MINOR/PATCH. Version of the prototype for its publication: 0.1.0 or 0.3.x (aligned with MbedTLS but shifted) ? bump_version.sh needs to be adapted.

The PSA cryptography repository does not inherit the platform abstraction of the Mbed TLS repository.

Platform abstraction needs (no dynamic configuration, probably not exhaustive):
psa_crypto_calloc(), psa_crypto_free(), psa_crypto_snprintf(), psa_crypto_setbuf(), psa_crypto_zeroize(), C11 like mutex, C11 like condition ...

The PSA-Crypto cmake build system is independent of the Mbed TLS ones but originates from it. It is based on the Mbed TLS cmake build system from Mbed-TLS/mbedtls@32605b24be. Since then some fixes have been applied to the Mbed TLS cmake build system. The goal of this task is to apply the relevant fixes to the PSA-Crypto cmake build system.

Not in the scope of this issue: IAR support.

Add in psa-crypto component files the equivalent of:

• helper_libtestdriver1_adjust_config
• helper_libtestdriver1_make_drivers: need to add support for the build of the test library in tests/CMakeLists.txt
• helper_libtestdriver1_make_main

Demonstrate testing with libtestdriver1 by adding the equivalent of test_psa_crypto_config_accel_ecdsa.

Add in psa-crypto the equivalent of:

• test_clang_latest_opt
• test_clang_earliest_opt
• test_gcc_latest_opt
• test_gcc_earliest_opt

Depends on:

• #58 to set up the full config

Import the test suites of all crypto modules in PSA-Crypto as it aims to become the repository where the crypto development occurs. Check that all test suites are not at least once in all.sh.

Update monthly the PSA crypto main branch against Mbed TLS development as described in the section "Updating the main branch" in psa-crypto-repository.md. As long as the CI is not ready the testing of the update will be done by running locally all.sh.

Add code style check

• Adapt code_style.py to work both for mbedtls and psa-cryto repo
• Add check_code_style all.sh component

DOD: Same support for code style checking in psa-crypto as in mbedtls

N.B. Depends on issue #50

We need the equivalent of the Mbed TLS component component_test_psa_compliance as part of the validation of the PSA cryptography repository code.

Define the configurations corresponding to TF-M profile medium and large. Define all.sh components to test the configurations.

• Add PSA_CRYPTO_INJECT_ENTROPY config option and its documentation in the section "PSA cryptography core configuration options" of crypto_config.h. Similar to MBEDTLS_PSA_INJECT_ENTROPY in mbedtls. Disabled by default.
• Add its translation to MBEDTLS_PSA_INJECT_ENTROPY in config_adjust_mbedtls_from_psa_crypto.h. MBEDTLS_NO_DEFAULT_ENTROPY_SOURCES needs to be defined here as well.
• Add a test_psa_inject_entropy test component similar to the one in mbedtls.
• Check that the test component do what it intends to do and give evidence of this in this issue or the associated PR for the benefit of reviewers

Depends on:

• #58 to set up the full config

The main branch of the PSA crypto repo is going to be synchronized regularly with the head of the Mbed TLS development branch.
The synchronization is done by pushing a pull request targeting the main branch and based on the head of the PSA crypto repo and the Mbed TLS development branches. CI jobs (based on all.sh) are run against this pull request and if all tests are run successfully the PR can be merged into the main branch and the synchronization is completed.

To build the main branch of the PSA-Crypto repository from a commit of the Mbed TLS development branch a few commits are necessary on top of the development branch commit, see https://github.com/ronald-cron-arm/mbedtls/tree/base-for-psa-crypto-PR7644. This task is about creating PR(s) against Mbed TLS development to merge into Mbed TLS the changes done on scripts.

DoD: No change on scripts needed to build the main branch of the PSA-Crypto repository from a commit of the Mbed TLS development branch.

Split all.sh into two files: everything but the components (all.sh framework) and the test components. Mbed-TLS and PSA-Crypto share the all.sh framework and both have their own test components file.
With this we should be able to get rid of replace_all_sh_components in scripts/psa_crypto.py.

Add support for psa-crypto repo in config.py regarding the options baremetal,baremetal_size,full,full_no_deprecated,realfull,crypto,crypto_baremetal,crypto_full.

The configuration file in psa-crypto is include/psa/crypto_config.h. It contains PSA_CRYPTO_ and PSA_WANT_ configuration options and thus config.py should be able to handle those configuration options.

We have in build_tree.py looks_like_psa_crypto_root() to detect if we are in the mbedtls or psa-crypto repo.

In psa-crypto, baremetal and crypto_baremetal are equivalent, as well as full and crypto_full. crypto does not do anything, just the default psa-crypto configuration.

Collect pro-actively and address feedback about the PSA crypto repo prototype. This issue is to reserve time (~one week) to collect feedback and address some of it (no commitment to address it all).

As part of the work to bring the testing in PSA-Crypto at the level it is in Mbed-TLS, add in tests/all_sh_components.txt the components equivalent to the component_test_cmake_* Mbed-TLS ones.

DoD: the component_test_cmake_* run successfully with equivalent testing as the Mbed-TLS ones.

Add in psa-crypto the equivalent of:

• test_psa_ecc_key_pair_no_derive
• test_psa_ecc_key_pair_no_generate
• test_new_psa_want_key_pair_symbol
• test_aead_chachapoly_disabled
• test_aead_only_ccm
• test_psa_crypto_key_id_encodes_owner
• test_crypto_for_psa_service
• test_psa_crypto_rsa_no_genprime, rather test_no_rsa_key_pair_generation for the name probably, default config minus PSA_WANT_KEY_TYPE_RSA_KEY_PAIR_GENERATE).

Notes:

• test_psa_ecc_key_pair_no_derive and test_psa_ecc_key_pair_no_generate disable USE_PSA_CRYPTO. Not sure why and not possible in psa-crypto.
• not sure that in psa-crypto context, test_crypto_for_psa_service brings additional value compared to test_psa_crypto_key_id_encodes_owner.

Depends on:

• #58 to set up the full config

Add doxygen checks

• Adapt tests/scripts/check-doxy-blocks.pl to work for both mbedtls and psa-crypto repo
• Adapt tests/scripts/doxygen.sh to work for both mbedtls and psa-crypto repo
• Add component_check_doxy_blocks and component_check_doxygen_warnings all.sh components

DOD: Same support for doxygen checks in psa-crypto as in mbedtls

Depends on #58

Port code from Mbed-TLS/mbedtls#7980 to the PSA Crypto repo

Add to PSA-Crypto the remaining Mbed TLS crypto modules that were not included in the first place as they are not used by the PSA implementation yet. Those are mostly modules used to import and export keys in various formats. They will be hopefully soon used by the PSA API implementation with the development of extended import/export APIs.

List of the modules to add:
base64.c, nist_kw.c, pem.c, pkcs5.c, pkcs12.c (not pkcs7.c as it currently contains things that are rather on the side on using crypto than providing crypto like TLS or x509).

Add the associated test suites and a specific all.sh component that enable them beyond the PSA-Crypto configuration and test them.

Requirement checklist

• Timescale
  • publish PSA crypto repo at the end of Q3
• Description:
  • Prepare PSA crypto repo for publication
• Deliverables:
  • PSA crypto repo publication, ready for production (usable by other projects)
• Exclusions / out-of-scope:
  • Not committing to enable development, still a mirror of Mbed TLS
• Dependencies
  • N/A
• Relevant contacts
  • Shebu. James King may also have input.

Epic checklist

• Is epic fully broken down?
  • yes
• Epic estimate
  • yes
• DoD
  • Publication of the PSA Crypto repo
• Experts list
  • @ronald-cron-arm, @adeaarm, @Summer-ARM, @imre-kis-arm
• Design documentation
  • Present, in the initial PR.
• Dependencies
  • CI depends on support from @bensze01
• Resources needed
  • n/a
• Infra/Test automation/CI needs
  • Nothing at the moment - maybe something minor will come out of the CI work?
• Requirement link
  • https://jira.arm.com/browse/SECLIB-622
• Risks
• Testing notes
  • Issues related to testing

To build the main branch of the PSA-Crypto repository from a commit of the Mbed TLS development branch a few commits are necessary on top of the development branch commit, see https://github.com/ronald-cron-arm/mbedtls/tree/base-for-psa-crypto-PR7644. This task is about creating PR(s) against Mbed TLS development to merge into Mbed TLS the changes done on the library.

DoD: No change on the library code needed to build the main branch of the PSA-Crypto repository from a commit of the Mbed TLS development branch.

• Add PSA_CRYPTO_MPI_WINDOW_SIZE/MAX_SIZE config options and their documentations at the end of the section "PSA driver interface implementation configuration options" of crypto_config.h. Similar to MBEDTLS_MPI_WINDOW_SIZE/MAX_SIZE in mbedtls. Not defined by default, default values, 2 and 1024.
• Add test_no_udbl_division, test_no_64bit_multiplication, test_m32_o0, test_m32_o2, test_mx32, test_min_mpi_window_size, test_have_int32, test_have_int64 test components similar to the mbedtls ones.
• Check that the test components do what they intend to do and give evidence of this in this issue or the associated PR for the benefit of reviewers

Notes:

• MBEDTLS_HAVE_INT32/64 are not configuration options, just compilation flags in mbedtls, let's keep them as they are in psa-crypto at least for the time being.

Depends on:

• #58 to set up the full config

The PSA cryptography repository prototype will support less functionalities than the Mbed TLS libmbedcrypto library. The purpose of this task is to document what is supported in libmbedcrypto and will not be supported in the PSA cryptography repository prototype.

CTR_DRBG and HMAC_DRBG configuration
LMS
PK
no heap implementation

Generating coverage data in the Mbed TLS repo is done by the script lcov.sh. In the PSA Crypto repo it is currently done inline in the lcov target in CMake.

It would be best to unify these two approaches by using the lcov.sh script in PSA Crypto. However, this script cannot be used directly in PSA Crypto as it refers to the library directory, which is unique to Mbed TLS.

This task consists of 2 parts:

1. Modify lcov.sh so that it works in either the Mbed TLS or PSA Crypto repo.
2. Add lcov.sh to the PSA Crypto repo and use it in the CMake lcov target.

• Add PSA_CRYPTO_ENTROPY_FORCE_SHA256 config option and its documentation in the section "PSA cryptography core configuration options" of crypto_config.h. Similar to MBEDTLS_ENTROPY_FORCE_SHA256 in mbedtls. Disabled by default.
• Add PSA_CRYPTO_CTR_DRBG_USE_128_BIT_KEY config option and its documentation in the section "PSA cryptography core configuration options" of crypto_config.h. Similar to MBEDTLS_CTR_DRBG_USE_128_BIT_KEY in mbedtls. Disabled by default.
• Take into account PSA_CRYPTO_ENTROPY_FORCE_SHA256 and PSA_CRYPTO_CTR_DRBG_USE_128_BIT_KEY in RNG/DRBG pre-processor logic (see #if defined(PSA_CRYPTO_EXTERNAL_RNG) in config_adjust_mbedtls_from_psa_crypto.h.
• Add test_hmac_drbg test component similar to test_no_ctr_drbg_use_psa in mbedtls.
• Add test_hmac_drbg_aes_only_128_bit_keys test component similar to test_no_ctr_drbg_aes_only_128_bit_keys in mbedtls.
• Add test_ctr_drbg_aes_256_sha_256, test_ctr_drbg_aes_128_sha_512 and test_ctr_drbg_aes_128_sha_256 similar to the mbedtls ones
• Add test_psa_external_rng test component equivalent to test_rng_no_drbg_use_psa and test_psa_external_rng_use_psa_crypt
• Check that the test components do what they intend to do and give evidence of this in this issue or the associated PR for the benefit of reviewers

Notes:

• In psa-crypto the selection between CTR_DRBG and HMAC_DRBG is done through PSA_CRYPTO_HMAC_DRBG_HASH (see crypto_config.h)
• No need for test_no_ctr_drbg_use_psa and test_no_hmac_drbg_use_psa equivalents as in psa-crypto there is no configuration option to enable or disable the CTR_DRBG and HMAC_DRBG modules.

Depends on:

• #58 to set up the full config
• #65 for PSA_CRYPTO_AES_ONLY_128_BIT_KEY_LENGTH

Add name checks

• Adapt tests/scripts/check_names.py to work for both mbedtls and psa-crypto.
• Add component_check_names all.sh component.

DOD: Same support for name checking in psa-crypto as in mbedtls

Add change log support

• Add an initial empty ChangeLog or almost empty file
• Create the ChangeLog.d with its 00README.md
• Adapt assemble_changelog.py to work for both mbedtls and psa-cryto repo
• Add check_changelog all.sh component

DOD: Same support for change logs in psa-crypto as in mbedtls

Add in psa-crypto the equivalent of the test_psa_crypto_config_accel.* and test_psa_crypto_config_reference.* components.

test_psa_crypto_config_accel_ecdsa not in scope of this issue (part of #61).

Depends on #61.