lib/mbedtls
1
0
Fork 0
mirror of https://github.com/Mbed-TLS/mbedtls.git synced 2025-07-29 11:41:15 +03:00
Code Activity

Merge branch 'Mbed-TLS:development' into codegen_1.1

Browse Source
This commit is contained in:
asfand-silabs
2022-09-17 19:54:01 +02:00
committed by GitHub
parent 39452a8ca4 1716f06ee3
commit b549776a23
389 changed files with 50509 additions and 19601 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
docs/3.0-migration-guide.md
View File

@ -2,7 +2,7 @@
This guide details the steps required to migrate from Mbed TLS version 2.x to
Mbed TLS version 3.0 or greater. Unlike normal releases, Mbed TLS 3.0 breaks
compatibility with previous versions, so users (and alt implementors) might
compatibility with previous versions, so users (and alt implementers) might
need to change their own code in order to make it work with Mbed TLS 3.0.
Here's the list of breaking changes; each entry should help you answer these
@ -13,7 +13,28 @@ The changes are detailed below, and include:
- Removal of many insecure or obsolete features
- Tidying up of configuration options (including removing some less useful options).
- Changing function signatures, e.g. adding return codes, adding extra parameters, or making some arguments const.
- Removal of functions previously marked as deprecated.
- Removal of functions, macros, and types previously marked as deprecated.
Much of the information needed to determine a migration path can be found in the Mbed TLS 2.x documentation.
## Accessing the Mbed TLS 2.x documentation
For features previously marked as deprecated, Mbed TLS 2.x documentation may
explain how to upgrade, and should be referred to when migrating code. Where a
migration path is not provided in prior documentation, changes made and the
upgrade steps required will be explained later in this guide.
It's best to use the latest version of Mbed TLS 2.x for this purpose, which is the 2.28 LTS release.
So to generate the documentation, checkout the `mbedtls-2.28` branch and follow
the instructions in the [Documentation section of the README](https://github.com/Mbed-TLS/mbedtls/blob/mbedtls-2.28/README.md#documentation).
Then browse `apidoc/deprecated.html` for guidance on upgrading deprecated code.
For some deprecated functions, 2.x documentation will suggest using a variant
suffixed with `_ret`. In Mbed TLS 3.x, this change may not be required, as most
of these variants have been renamed without the suffix. The section
[Rename mbedtls_*_ret...](#rename-mbedtls__ret-cryptography-functions-whose-deprecated-variants-have-been-removed)
has further detail on which functions this applies to.
## General changes
@ -48,7 +69,7 @@ Attempting to access a private field directly will result in a compilation error
If you were accessing structure fields directly, and these fields are not documented as public, you need to change your code. If an accessor (getter/setter) function exists, use that. Direct accessor functions are usually called `mbedtls_<MODULE>_{get,set}_<FIELD>` or `mbedtls_<MODULE>_<STRUCTURE>_{get,set}_<FIELD>`. Accessor functions that change the format may use different verbs, for example `read`/`write` for functions that import/export data from/to a text or byte string.
If no accessor function exists, please open an [enhancement request against Mbed TLS](https://github.com/ARMmbed/mbedtls/issues/new?template=feature_request.md) and describe your use case. The Mbed TLS development team is aware that some useful accessor functions are missing in the 3.0 release, and we expect to add them to the first minor release(s) (3.1, etc.).
If no accessor function exists, please open an [enhancement request against Mbed TLS](https://github.com/Mbed-TLS/mbedtls/issues/new?template=feature_request.md) and describe your use case. The Mbed TLS development team is aware that some useful accessor functions are missing in the 3.0 release, and we expect to add them to the first minor release(s) (3.1, etc.).
As a last resort, you can access the field `foo` of a structure `bar` by writing `bar.MBEDTLS_PRIVATE(foo)`. Note that you do so at your own risk, since such code is likely to break in a future minor version of Mbed TLS.
@ -157,7 +178,7 @@ The macros `MBEDTLS_DHM_RFC5114_MODP_2048_P`, `MBEDTLS_DHM_RFC5114_MODP_2048_G`,
`MBEDTLS_DHM_RFC3526_MODP_4096_P `and `MBEDTLS_DHM_RFC3526_MODP_4096_G` were
removed. The primes from RFC 5114 are deprecated because their derivation is not
documented and therefore their usage constitutes a security risk; they are fully
removed from the library. Please use parameters from RFC3526 (still in the
removed from the library. Please use parameters from RFC 3526 (still in the
library, only in binary form) or RFC 7919 (also available in the library) or
other trusted sources instead.
@ -248,22 +269,29 @@ Alternative implementations of the SHA256 and SHA512 modules must adjust their f
### Deprecated error codes for hardware failures were removed
- The macros `MBEDTLS_ERR_xxx_FEATURE_UNSUPPORTED` from various crypto modules
- The macros `MBEDTLS_ERR_xxx_FEATURE_UNAVAILABLE` from various crypto modules
were removed; `MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED` is now used
instead.
- The macro `MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION` was removed;
`MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED` is now used instead.
- The macros `MBEDTLS_ERR_xxx_HW_ACCEL_FAILED` from various crypto modules
were removed; `MBEDTLS_ERR_PLATFORM_HW_ACCEL_FAILED` is now used instead.
### Deprecated error codes for invalid input data were removed
- The macros `MBEDTLS_ERR_xxx_INVALID_KEY_LENGTH` from ARIA and Camellia
modules were removed; `MBEDTLS_ERR_xxx_BAD_INPUT_DATA` is now used instead.
### Remove the mode parameter from RSA functions
This affects all users who use the RSA encryption, decryption, sign and
This affects all users who use the RSA encrypt, decrypt, sign and
verify APIs.
The RSA module no longer supports private-key operations with the public key or
vice versa. As a consequence, RSA operation functions no longer have a mode
parameter. If you were calling RSA operations with the normal mode (public key
for verification or encryption, private key for signature or decryption), remove
the `MBEDTLS_MODE_PUBLIC` or `MBEDTLS_MODE_PRIVATE` argument. If you were calling
the `MBEDTLS_RSA_PUBLIC` or `MBEDTLS_RSA_PRIVATE` argument. If you were calling
RSA operations with the wrong mode, which rarely makes sense from a security
perspective, this is no longer supported.
@ -334,7 +362,7 @@ the RSA verify functions.
### Remove the padding parameters from `mbedtls_rsa_init()`
This affects all users who use the RSA encryption, decryption, sign and
This affects all users who use the RSA encrypt, decrypt, sign and
verify APIs.
The function `mbedtls_rsa_init()` no longer supports selecting the PKCS#1 v2.1
@ -552,13 +580,13 @@ extension if it contains any unsupported certificate policies.
### Remove `MBEDTLS_X509_CHECK_*_KEY_USAGE` options from `mbedtls_config.h`
This change affects users who have chosen the configuration options to disable the
library's verification of the `keyUsage` and `extendedKeyUsage` fields of x509
library's verification of the `keyUsage` and `extendedKeyUsage` fields of X.509
certificates.
The `MBEDTLS_X509_CHECK_KEY_USAGE` and `MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE`
configuration options are removed and the X509 code now behaves as if they were
configuration options are removed and the X.509 code now behaves as if they were
always enabled. It is consequently not possible anymore to disable at compile
time the verification of the `keyUsage` and `extendedKeyUsage` fields of X509
time the verification of the `keyUsage` and `extendedKeyUsage` fields of X.509
certificates.
The verification of the `keyUsage` and `extendedKeyUsage` fields is important,
@ -772,7 +800,7 @@ than just the MFL configuration into account.
### Relaxed semantics for PSK configuration
This affects users which call the PSK configuration APIs
`mbedtlsl_ssl_conf_psk()` and `mbedtls_ssl_conf_psk_opaque()`
`mbedtls_ssl_conf_psk()` and `mbedtls_ssl_conf_psk_opaque()`
multiple times on the same SSL configuration.
In Mbed TLS 2.x, users would observe later calls overwriting

155
docs/architecture/mbed-crypto-storage-specification.md
View File

@ -112,7 +112,7 @@ Information about each key is stored in a dedicated file designated by the key i
The way in which the file name is constructed from the key identifier depends on the storage backend. The content of the file is described [below](#key-file-format-for-1.0.0).
* Library integration: the key file name is just the key identifier as defined in the PSA crypto specification. This is a 32-bit value.
* PSA service integration: the key file name is `(uint32_t)owner_uid << 32 | key_id` where `key_id` is the key identifier from the owner point of view and `owner_uid` (of type `int32_t`) is the calling partition identifier provided to the server by the partition manager. This is a 64-bit value.
* PSA service integration: the key file name is `(uint64_t)owner_uid << 32 | key_id` where `key_id` is the key identifier from the owner point of view and `owner_uid` (of type `int32_t`) is the calling partition identifier provided to the server by the partition manager. This is a 64-bit value.
### Key file format for 1.0.0
@ -120,7 +120,11 @@ The layout is identical to [0.1.0](#key-file-format-for-0.1.0) so far. However n
### Nonvolatile random seed file format for 1.0.0
[Identical to 0.1.0](#nonvolatile-random-seed-file-format-for-0.1.0).
The nonvolatile random seed file contains a seed for the random generator. If present, it is rewritten at each boot as part of the random generator initialization.
The file format is just the seed as a byte string with no metadata or encoding of any kind.
This is unchanged since [the feature was introduced in Mbed Crypto 0.1.0](#nonvolatile-random-seed-file-format-for-0.1.0).
### File namespace on a PSA platform for 1.0.0
@ -167,7 +171,21 @@ Tags: mbedcrypto-1.1.0
Released in early June 2019. <br>
Integrated in Mbed OS 5.13.
Identical to [1.0.0](#mbed-crypto-1.0.0) except for some changes in the key file format.
Changes since [1.0.0](#mbed-crypto-1.0.0):
* The stdio backend for storage has been replaced by an implementation of [PSA ITS over stdio](#file-namespace-on-stdio-for-1.1.0).
* [Some changes in the key file format](#key-file-format-for-1.1.0).
### File namespace on stdio for 1.1.0
Assumption: C stdio, allowing names containing lowercase letters, digits and underscores, of length up to 23.
An undocumented build-time configuration value `PSA_ITS_STORAGE_PREFIX` allows storing the key files in a directory other than the current directory. This value is simply prepended to the file name (so it must end with a directory separator to put the keys in a different directory).
* `PSA_ITS_STORAGE_PREFIX "tempfile.psa_its"`: used as a temporary file. Must be writable. May be overwritten or deleted if present.
* `sprintf(PSA_ITS_STORAGE_PREFIX "%016llx.psa_its", key_id)`: a key or non-key file. The `key_id` in the name is the 64-bit file identifier, which is the [key identifier](#key-names-for-mbed-tls-2.25.0) for a key file or some reserved identifier for a non-key file (currently: only the [nonvolatile random seed](#nonvolatile-random-seed-file-format-for-1.0.0)). The contents of the file are:
* Magic header (8 bytes): `"PSA\0ITS\0"`
* File contents.
### Key file format for 1.1.0
@ -314,3 +332,134 @@ The layout of a key file is:
* For an opaque key (unified driver interface): driver-specific opaque key blob.
* For an opaque key (key in a secure element): slot number (8 bytes), in platform endianness.
* Any trailing data is rejected on load.
Mbed TLS 2.25.0
---------------
Tags: `mbedtls-2.25.0`, `mbedtls-2.26.0`, `mbedtls-2.27.0`, `mbedtls-2.28.0`, `mbedtls-3.0.0`, `mbedtls-3.1.0`
First released in December 2020.
Note: this is the first version that is officially supported. The version number is still 0.
Backward compatibility commitments: we promise backward compatibility for stored keys when Mbed TLS is upgraded from x to y if x >= 2.25 and y < 4. See [`BRANCHES.md`](../../BRANCHES.md) for more details.
Supported integrations:
* [PSA platform](#file-namespace-on-a-psa-platform-on-mbed-tls-2.25.0)
* [library using PSA ITS](#file-namespace-on-its-as-a-library-on-mbed-tls-2.25.0)
* [library using C stdio](#file-namespace-on-stdio-for-mbed-tls-2.25.0)
Supported features:
* [Persistent keys](#key-file-format-for-mbed-tls-2.25.0) designated by a [key identifier and owner](#key-names-for-mbed-tls-2.25.0). Keys can be:
* Transparent, stored in the export format.
* Opaque, using the unified driver interface with statically registered drivers (`MBEDTLS_PSA_CRYPTO_DRIVERS`). The driver determines the content of the opaque key blob.
* Opaque, using the deprecated secure element interface with dynamically registered drivers (`MBEDTLS_PSA_CRYPTO_SE_C`). The driver picks a slot number which is stored in the place of the key material.
* [Nonvolatile random seed](#nonvolatile-random-seed-file-format-for-mbed-tls-2.25.0) on ITS only.
### Changes introduced in Mbed TLS 2.25.0
* The numerical encodings of `psa_key_type_t`, `psa_key_usage_t` and `psa_algorithm_t` have changed.
### File namespace on a PSA platform on Mbed TLS 2.25.0
Assumption: ITS provides a 64-bit file identifier namespace. The Crypto service can use arbitrary file identifiers and no other part of the system accesses the same file identifier namespace.
Assumption: the owner identifier is a nonzero value of type `int32_t`.
* Files 0 through 0xfffeffff: unused.
* Files 0xffff0000 through 0xffffffff: reserved for internal use of the crypto library or crypto service. See [non-key files](#non-key-files-on-mbed-tls-2.25.0).
* Files 0x100000000 through 0xffffffffffff: [content](#key-file-format-for-mbed-tls-2.25.0) of the [key whose identifier is the file identifier](#key-names-for-mbed-tls-2.25.0). The upper 32 bits determine the owner.
### File namespace on ITS as a library on Mbed TLS 2.25.0
Assumption: ITS provides a 64-bit file identifier namespace. The entity using the crypto library can use arbitrary file identifiers and no other part of the system accesses the same file identifier namespace.
This is a library integration, so there is no owner. The key file identifier is identical to the key identifier.
* File 0: unused.
* Files 1 through 0xfffeffff: [content](#key-file-format-for-mbed-tls-2.25.0) of the [key whose identifier is the file identifier](#key-names-for-mbed-tls-2.25.0).
* Files 0xffff0000 through 0xffffffff: reserved for internal use of the crypto library or crypto service. See [non-key files](#non-key-files-on-mbed-tls-2.25.0).
* Files 0x100000000 through 0xffffffffffffffff: unused.
### File namespace on stdio for Mbed TLS 2.25.0
Assumption: C stdio, allowing names containing lowercase letters, digits and underscores, of length up to 23.
An undocumented build-time configuration value `PSA_ITS_STORAGE_PREFIX` allows storing the key files in a directory other than the current directory. This value is simply prepended to the file name (so it must end with a directory separator to put the keys in a different directory).
* `PSA_ITS_STORAGE_PREFIX "tempfile.psa_its"`: used as a temporary file. Must be writable. May be overwritten or deleted if present.
* `sprintf(PSA_ITS_STORAGE_PREFIX "%016llx.psa_its", key_id)`: a key or non-key file. The `key_id` in the name is the 64-bit file identifier, which is the [key identifier](#key-names-for-mbed-tls-2.25.0) for a key file or some reserved identifier for a [non-key file](#non-key-files-on-mbed-tls-2.25.0). The contents of the file are:
* Magic header (8 bytes): `"PSA\0ITS\0"`
* File contents.
### Key names for Mbed TLS 2.25.0
Information about each key is stored in a dedicated file designated by the key identifier. In integrations where there is no concept of key owner (in particular, in library integrations), the key identifier is exactly the key identifier as defined in the PSA Cryptography API specification (`psa_key_id_t`). In integrations where there is a concept of key owner (integration into a service for example), the key identifier is made of an owner identifier (its semantics and type are integration specific) and of the key identifier (`psa_key_id_t`) from the key owner point of view.
The way in which the file name is constructed from the key identifier depends on the storage backend. The content of the file is described [below](#key-file-format-for-mbed-tls-2.25.0).
* Library integration: the key file name is just the key identifier as defined in the PSA crypto specification. This is a 32-bit value which must be in the range 0x00000001..0x3fffffff (`PSA_KEY_ID_USER_MIN`..`PSA_KEY_ID_USER_MAX`).
* PSA service integration: the key file name is `(uint64_t)owner_uid << 32 | key_id` where `key_id` is the key identifier from the owner point of view and `owner_uid` (of type `int32_t`) is the calling partition identifier provided to the server by the partition manager. This is a 64-bit value.
### Key file format for Mbed TLS 2.25.0
All integers are encoded in little-endian order in 8-bit bytes except where otherwise indicated.
The layout of a key file is:
* magic (8 bytes): `"PSA\0KEY\0"`.
* version (4 bytes): 0.
* lifetime (4 bytes): `psa_key_lifetime_t` value.
* type (2 bytes): `psa_key_type_t` value.
* bits (2 bytes): `psa_key_bits_t` value.
* policy usage flags (4 bytes): `psa_key_usage_t` value.
* policy usage algorithm (4 bytes): `psa_algorithm_t` value.
* policy enrollment algorithm (4 bytes): `psa_algorithm_t` value.
* key material length (4 bytes).
* key material:
* For a transparent key: output of `psa_export_key`.
* For an opaque key (unified driver interface): driver-specific opaque key blob.
* For an opaque key (key in a dynamic secure element): slot number (8 bytes), in platform endianness.
* Any trailing data is rejected on load.
### Non-key files on Mbed TLS 2.25.0
File identifiers that are outside the range of persistent key identifiers are reserved for internal use by the library. The only identifiers currently in use have the owner id (top 32 bits) set to 0.
* Files 0xfffffe02 through 0xfffffeff (`PSA_CRYPTO_SE_DRIVER_ITS_UID_BASE + lifetime`): dynamic secure element driver storage. The content of the file is the secure element driver's persistent data.
* File 0xffffff52 (`PSA_CRYPTO_ITS_RANDOM_SEED_UID`): [nonvolatile random seed](#nonvolatile-random-seed-file-format-for-mbed-tls-2.25.0).
* File 0xffffff54 (`PSA_CRYPTO_ITS_TRANSACTION_UID`): [transaction file](#transaction-file-format-for-mbed-tls-2.25.0).
* Other files are unused and reserved for future use.
### Nonvolatile random seed file format for Mbed TLS 2.25.0
[Identical to Mbed Crypto 0.1.0](#nonvolatile-random-seed-file-format-for-0.1.0).
### Transaction file format for Mbed TLS 2.25.0
The transaction file contains data about an ongoing action that cannot be completed atomically. It exists only if there is an ongoing transaction.
All integers are encoded in platform endianness.
All currently existing transactions concern a key in a dynamic secure element.
The layout of a transaction file is:
* type (2 bytes): the [transaction type](#transaction-types-on-mbed-tls-2.25.0).
* unused (2 bytes)
* lifetime (4 bytes): `psa_key_lifetime_t` value that corresponds to a key in a secure element.
* slot number (8 bytes): `psa_key_slot_number_t` value. This is the unique designation of the key for the secure element driver.
* key identifier (4 bytes in a library integration, 8 bytes on a PSA platform): the internal representation of the key identifier. On a PSA platform, this encodes the key owner in the same way as [in file identifiers for key files](#file-namespace-on-a-psa-platform-on-mbed-tls-2.25.0)).
#### Transaction types on Mbed TLS 2.25.0
* 0x0001: key creation. The following locations may or may not contain data about the key that is being created:
* The slot in the secure element designated by the slot number.
* The file containing the key metadata designated by the key identifier.
* The driver persistent data.
* 0x0002: key destruction. The following locations may or may not still contain data about the key that is being destroyed:
* The slot in the secure element designated by the slot number.
* The file containing the key metadata designated by the key identifier.
* The driver persistent data.

2
docs/architecture/psa-crypto-implementation-structure.md
View File

@ -1,4 +1,4 @@
PSA Cryptograpy API implementation and PSA driver interface
PSA Cryptography API implementation and PSA driver interface
===========================================================
## Introduction

116
docs/architecture/psa-migration/outcome-analysis.sh Executable file
View File

@ -0,0 +1,116 @@
#!/bin/sh
# This script runs tests in various revisions and configurations and analyses
# the results in order to highlight any difference in the set of tests skipped
# in the test suites of interest.
#
# It can be used to ensure the testing criteria mentioned in strategy.md,
# end of section "Supporting builds with drivers without the software
# implementation" are met, namely:
#
# - the sets of tests skipped in the default config and the full config must be
# the same before and after the PR that implements step 3;
# - the set of tests skipped in the driver-only build is the same as in an
# equivalent software-based configuration, or the difference is small enough,
# justified, and a github issue is created to track it.
#
# WARNING: this script checks out a commit other than the head of the current
# branch; it checks out the current branch again when running successfully,
# but while the script is running, or if it terminates early in error, you
# should be aware that you might be at a different commit than expected.
#
# NOTE: This is only an example/template script, you should make a copy and
# edit it to suit your needs. The part that needs editing is at the top.
#
# Also, you can comment out parts that don't need to be re-done when
# re-running this script (for example "get numbers before this PR").
# ----- BEGIN edit this -----
# The component in all.sh that builds and tests with drivers.
DRIVER_COMPONENT=test_psa_crypto_config_accel_hash_use_psa
# A similar configuration to that of the component, except without drivers,
# for comparison.
reference_config () {
scripts/config.py set MBEDTLS_USE_PSA_CRYPTO
scripts/config.py unset MBEDTLS_PKCS1_V21
scripts/config.py unset MBEDTLS_X509_RSASSA_PSS_SUPPORT
scripts/config.py unset MBEDTLS_ECDSA_DETERMINISTIC
}
# Space-separated list of test suites of interest.
SUITES="rsa pkcs1_v15 pk pkparse pkwrite"
# ----- END edit this -----
set -eu
cleanup() {
make clean
git checkout -- include/mbedtls/mbedtls_config.h include/psa/crypto_config.h
}
record() {
export MBEDTLS_TEST_OUTCOME_FILE="$PWD/outcome-$1.csv"
rm -f $MBEDTLS_TEST_OUTCOME_FILE
make check
}
# save current HEAD
HEAD=$(git branch --show-current)
# get the numbers before this PR for default and full
cleanup
git checkout $(git merge-base HEAD development)
record "before-default"
cleanup
scripts/config.py full
record "before-full"
# get the numbers now for default and full
cleanup
git checkout $HEAD
record "after-default"
cleanup
scripts/config.py full
record "after-full"
# get the numbers now for driver-only and reference
cleanup
reference_config
record "reference"
cleanup
export MBEDTLS_TEST_OUTCOME_FILE="$PWD/outcome-drivers.csv"
tests/scripts/all.sh -k test_psa_crypto_config_accel_hash_use_psa
# analysis
compare_suite () {
ref="outcome-$1.csv"
new="outcome-$2.csv"
suite="$3"
pattern_suite=";test_suite_$suite;"
total=$(grep -c "$pattern_suite" "$ref")
sed_cmd="s/^.*$pattern_suite\(.*\);SKIP.*/\1/p"
sed -n "$sed_cmd" "$ref" > skipped-ref
sed -n "$sed_cmd" "$new" > skipped-new
nb_ref=$(wc -l <skipped-ref)
nb_new=$(wc -l <skipped-new)
printf "%12s: total %3d; skipped %3d -> %3d\n" \
$suite $total $nb_ref $nb_new
diff skipped-ref skipped-new | grep '^> ' || true
rm skipped-ref skipped-new
}
compare_builds () {
printf "\n*** Comparing $1 -> $2 ***\n"
for suite in $SUITES; do
compare_suite "$1" "$2" "$suite"
done
}
compare_builds before-default after-default
compare_builds before-full after-full
compare_builds reference drivers

111
docs/architecture/psa-migration/psa-limitations.md
View File

@ -14,8 +14,8 @@ Limitations relevant for G1 (performing crypto operations)
Restartable ECC operations
--------------------------
There is currently no support for that in PSA at all. API design, as well as
implementation, would be non-trivial.
There is currently no support for that in PSA at all, but it will be added at
some point, see <https://github.com/orgs/Mbed-TLS/projects/1#column-18816849>.
Currently, `MBEDTLS_USE_PSA_CRYPTO` is simply incompatible with
`MBEDTLS_ECP_RESTARTABLE`.
@ -27,12 +27,12 @@ PSA Crypto has an API for FFDH, but it's not implemented in Mbed TLS yet.
(Regarding FFDH, see the next section as well.) See issue [3261][ffdh] on
github.
[ffdh]: https://github.com/ARMmbed/mbedtls/issues/3261
[ffdh]: https://github.com/Mbed-TLS/mbedtls/issues/3261
PSA Crypto has an experimental API for EC J-PAKE, but it's not implemented in
Mbed TLS yet. See the [EC J-PAKE follow-up EPIC][ecjp] on github.
[ecjp]: https://github.com/orgs/ARMmbed/projects/18#column-15836385
[ecjp]: https://github.com/orgs/Mbed-TLS/projects/1#column-17950140
Arbitrary parameters for FFDH
-----------------------------
@ -60,16 +60,25 @@ There are several options here:
1. Implement support for custom FFDH parameters in PSA Crypto: this would pose
non-trivial API design problem, but most importantly seems backwards, as
the crypto community is moving away from custom FFDH parameters.
the crypto community is moving away from custom FFDH parameters. (Could be
done any time.)
2. Drop the DHE-RSA and DHE-PSK key exchanges in TLS 1.2 when moving to PSA.
3. Implement RFC 7919, support DHE-RSA and DHE-PSK only in conjunction with it
when moving to PSA. We can modify our server so that it only selects a DHE
ciphersuite if the client offered name FFDH groups; unfortunately
(For people who want some algorithmic variety in case ECC collapses, FFDH
would still be available in TLS 1.3, just not in 1.2.) (Can only be done in
4.0 or another major version.)
3. Variant of the precedent: only drop client-side support. Server-side is
easy to support in terms of API/protocol, as the server picks the
parameters: we just need remove the existing `mbedtls_ssl_conf_dh_param_xxx()`
APIs and tell people to use `mbedtls_ssl_conf_groups()` instead. (Can only be
done in 4.0 or another major version.)
4. Implement RFC 7919, support DHE-RSA and DHE-PSK only in conjunction with it
when moving to PSA. Server-side would work as above; unfortunately
client-side the only option is to offer named groups and break the handshake
if the server didn't take on our offer. This is not fully satisfying, but is
perhaps the least unsatisfying option in terms of result; it's also probably
the one that requires the most work, but it would deliver value beyond PSA
migration by implementing RFC 7919.
migration by implementing RFC 7919. (Implementing RFC 7919 could be done any
time; making it mandatory can only be done in 4.0 or another major version.)
RSA-PSS parameters
------------------
@ -84,7 +93,7 @@ the hash algorithm potentially used to hash the message being signed:
- most commonly MGF1, which in turn is parametrized by a hash algorithm
- a salt length
- a trailer field - the value is fixed to 0xBC by PKCS#1 v2.1, but was left
configurable in the original scheme; 0xBC is used everywhere in pratice.
configurable in the original scheme; 0xBC is used everywhere in practice.
Both the existing `mbedtls_` API and the PSA API support only MGF1 as the
generation function (and only 0xBC as the trailer field), but there are
@ -162,7 +171,7 @@ match a limitation of the PSA API.
It is unclear what parameters people use in practice. It looks like by default
OpenSSL picks saltlen = keylen - hashlen - 2 (tested with openssl 1.1.1f).
The `certool` command provided by GnuTLS seems to be picking saltlen = hashlen
The `certtool` command provided by GnuTLS seems to be picking saltlen = hashlen
by default (tested with GnuTLS 3.6.13). FIPS 186-4 requires 0 <= saltlen <=
hashlen.
@ -294,7 +303,7 @@ server9.req.sha512
Mask Algorithm: mgf1 with sha512
Salt Length: 0x3E
These CSRss are signed with a 2048-bit key. It appears that they are
These CSRs are signed with a 2048-bit key. It appears that they are
all using saltlen = keylen - hashlen - 2.
### Possible courses of action
@ -308,87 +317,13 @@ is about X.509 signature verification. Options include:
saltlen happens to match hashlen, and falling back to `ANY_SALT` otherwise.
Same issue as with the previous point, except more contained.
3. Reject all certificates with saltlen != hashlen. This includes all
certificates generate with OpenSSL using the default parameters, so it's
certificates generated with OpenSSL using the default parameters, so it's
probably not acceptable.
4. Request an extension to the PSA Crypto API and use one of the above options
in the meantime. Such an extension seems inconvenient and not motivated by
strong security arguments, so it's unclear whether it would be accepted.
HKDF: Expand not exposed on its own (TLS 1.3)
---------------------------------------------
The HKDF function uses and Extract-then-Expand approch, that is:
HKDF(x, ...) = HKDF-Expand(HKDF-Extract(x, ...), ...)
Only the full HKDF function is safe in general, however there are cases when
one case safely use the individual Extract and Expand; the TLS 1.3 key
schedule does so. Specifically, looking at the [hierarchy of secrets][13hs]
is seems that Expand and Extract are always chained, so that this hierarchy
can be implemented using only the full HKDF. However, looking at the
derivation of traffic keys (7.3) and the update mechanism (7.2) it appears
that calls to HKDF-Expand are iterated without any intermediated call to
HKDF-Extract : that is, the traffic keys are computed as
HKDF-Expand(HKDF-Expand(HKDF-Extract(...)))
(with possibly more than two Expands in a row with update).
[13hs]: https://datatracker.ietf.org/doc/html/rfc8446#page-93
In the short term (early 2022), we'll work around that by re-implementing HKDF
in `ssl_tls13_keys.c` based on the `psa_mac_` APIs (for HMAC).
In the long term, it is desirable to extend the PSA API. See
https://github.com/ARM-software/psa-crypto-api/issues/539
Limitations relevant for G2 (isolation of long-term secrets)
============================================================
Custom key derivations for mixed-PSK handshake
----------------------------------------------
Currently, `MBEDTLS_USE_PSA_CRYPTO` enables the new configuration function
`mbedtls_ssl_conf_psk_opaque()` which allows a PSA-held key to be used for the
(pure) `PSK` key exchange in TLS 1.2. This requires that the derivation of the
Master Secret (MS) be done on the PSA side. To support this, an algorithm
family `PSA_ALG_TLS12_PSK_TO_MS(hash_alg)` was added to PSA Crypto.
If we want to support key isolation for the "mixed PSK" key exchanges:
DHE-PSK, RSA-PSK, ECDHE-PSK, where the PSK is concatenated with the result of
a DH key agreement (resp. RSA decryption) to form the pre-master secret (PMS)
from which the MS is derived. If the value of the PSK is to remain hidden, we
need the derivation PSK + secondary secret -> MS to be implemented as an
ad-hoc PSA key derivation algorithm.
Adding this new, TLS-specific, key derivation algorithm to PSA Crypto should
be no harder than it was to add `PSA_ALG_TLS12_PSK_TO_MS()` but still requires
an extension to PSA Crypto.
Note: looking at RFCs 4279 and 5489, it appears that the structure of the PMS
is always the same: 2-byte length of the secondary secret, secondary secret,
2-byte length of the PSK, PSK. So, a single key derivation algorithm should be
able to cover the 3 key exchanges DHE-PSK, RSA-PSK and ECDHE-PSK. (That's a
minor gain: adding 3 algorithms would not be a blocker anyway.)
Note: if later we want to also isolate short-term secret (G3), the "secondary
secret" (output of DHE/ECDHE key agreement or RSA decryption) could be a
candidate. This wouldn't be a problem as the PSA key derivation API always
allows inputs from key slots. (Tangent: the hard part in isolating the result
of RSA decryption would be still checking that is has the correct format:
48 bytes, the first two matching the TLS version - note that this is timing
sensitive.)
HKDF: Expand not exposed on its own (TLS 1.3)
---------------------------------------------
See the section with the same name in the G1 part above for background.
The work-around mentioned there works well enough just for acceleration, but
is not sufficient for key isolation or generally proper key management (it
requires marking keys are usable for HMAC while they should only be used for
key derivation).
The obvious long-term solution is to make HKDF-Expand available as a new KDF
(in addition to the full HKDF) in PSA (with appropriate warnings in the
documentation).
Currently none.

311
docs/architecture/psa-migration/strategy.md
View File

@ -12,19 +12,14 @@ G3. Allow isolation of short-term secrets (for example, TLS session keys).
G4. Have a clean, unified API for Crypto (retire the legacy API).
G5. Code size: compile out our implementation when a driver is available.
Currently, some parts of (G1) and (G2) are implemented when
As of Mbed TLS 3.2, most of (G1) and all of (G2) is implemented when
`MBEDTLS_USE_PSA_CRYPTO` is enabled. For (G2) to take effect, the application
needs to be changed to use new APIs.
needs to be changed to use new APIs. For a more detailed account of what's
implemented, see `docs/use-psa-crypto.md`, where new APIs are about (G2), and
internal changes implement (G1).
Generally speaking, the numbering above doesn't mean that each goal requires
the preceding ones to be completed, for example G2-G5 could be done in any
order; however they all either depend on G1 or are just much more convenient
if G1 is done before (note that this is not a dependency on G1 being complete,
it's more like each bit of G2-G5 is helped by some specific bit in G1).
So, a solid intermediate goal would be to complete (G1) when
`MBEDTLS_USA_PSA_CRYPTO` is enabled - that is, all crypto operations in X.509
and TLS would be done via the PSA Crypto API.
the preceding ones to be completed.
Compile-time options
====================
@ -36,37 +31,37 @@ We currently have two compile-time options that are relevant to the migration:
- `MBEDTLS_USE_PSA_CRYPTO` - disabled by default (enabled in "full" config),
controls usage of PSA Crypto APIs to perform operations in X.509 and TLS
(G1 above), as well as the availability of some new APIs (G2 above).
- `PSA_CRYPTO_CONFIG` - disabled by default, supports builds with drivers and
without the corresponding software implementation (G5 above).
The reasons why `MBEDTLS_USE_PSA_CRYPTO` is optional and disabled by default
are:
- it's incompatible with `MBEDTLS_ECP_RESTARTABLE`;
- historical: used to be incompatible
`MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER` (fixed early 2022, see
<https://github.com/ARMmbed/mbedtls/issues/5259>);
- it does not work well with `MBEDTLS_PSA_CRYPTO_CONFIG` (could compile with
both of them, but then `MBEDTLS_PSA_CRYPTO_CONFIG` won't have the desired
effect)
- to avoid a hard/default dependency of TLS, X.509 and PK on
`MBEDTLS_PSA_CRYPTO_C`, for backward compatibility reasons:
- when `MBEDTLS_PSA_CRYPTO_C` is enabled and used, applications need to call
`psa_crypto_init()` before TLS/X.509 uses PSA functions
- `MBEDTLS_PSA_CRYPTO_C` has a hard depend on `MBEDTLS_ENTROPY_C ||
- When `MBEDTLS_PSA_CRYPTO_C` is enabled and used, applications need to call
`psa_crypto_init()` before TLS/X.509 uses PSA functions. (This prevents us
from even enabling the option by default.)
- `MBEDTLS_PSA_CRYPTO_C` has a hard dependency on `MBEDTLS_ENTROPY_C ||
MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG` but it's
currently possible to compilte TLS and X.509 without any of the options.
currently possible to compile TLS and X.509 without any of the options.
Also, we can't just auto-enable `MBEDTLS_ENTROPY_C` as it doesn't build
out of the box on all platforms, and even less
`MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG` as it requires a user-provided RNG
function.
The downside of this approach is that until we feel ready to make
The downside of this approach is that until we are able to make
`MBDEDTLS_USE_PSA_CRYPTO` non-optional (always enabled), we have to maintain
two versions of some parts of the code: one using PSA, the other using the
legacy APIs. However, see next section for strategies that can lower that
cost. The rest of this section explains the reasons for the
incompatibilities mentioned above.
In the medium term (writing this in early 2020), we're going to look for ways
to make `MBEDTLS_USE_PSA_CRYPTO` non-optional (always enabled).
At the time of writing (early 2022) it is unclear what could be done about the
backward compatibility issues, and in particular if the cost of implementing
solutions to these problems would be higher or lower than the cost of
maintaining dual code paths until the next major version. (Note: these
solutions would probably also solve other problems at the same time.)
### `MBEDTLS_ECP_RESTARTABLE`
@ -76,51 +71,19 @@ Crypto does not support restartable operations, there's a clear conflict: the
TLS and X.509 layers can't both use only PSA APIs and get restartable
behaviour.
Supporting this in PSA is on our roadmap (it's been requested). But it's way
below generalizing support for `MBEDTLS_USE_PSA_CRYPTO` for “mainstream” use
cases on our priority list. So in the medium term `MBEDTLS_ECP_RESTARTABLE` is
incompatible with `MBEDTLS_USE_PSA_CRYPTO`.
Supporting this in PSA is on our roadmap and currently planned for end of
2022, see <https://github.com/orgs/Mbed-TLS/projects/1#column-18883250>.
Note: it is possible to make the options compatible at build time simply by
deciding that when `USE_PSA_CRYPTO` is enabled, PSA APIs are used except if
restartable behaviour was requested at run-time (in addition to enabling
`MBEDTLS_ECP_RESTARTABLE` in the build).
It will then require follow-up work to make use of the new PSA API in
PK/X.509/TLS in all places where we currently allow restartable operations.
### `MBEDTLS_PSA_CRYPTO_CONFIG`
(This section taken from a comment by Gilles.)
X509 and TLS code use `MBEDTLS_xxx` macros to decide whether an algorithm is
supported. This doesn't make `MBEDTLS_USE_PSA_CRYPTO` incompatible with
`MBEDTLS_PSA_CRYPTO_CONFIG` per se, but it makes it incompatible with most
useful uses of `MBEDTLS_PSA_CRYPTO_CONFIG`. The point of
`MBEDTLS_PSA_CRYPTO_CONFIG` is to be able to build a library with support for
an algorithm through a PSA driver only, without building the software
implementation of that algorithm. But then the TLS code would consider the
algorithm unavailable.
This is tracked in https://github.com/ARMmbed/mbedtls/issues/3674 and
https://github.com/ARMmbed/mbedtls/issues/3677. But now that I look at it with
fresh eyes, I don't think the approach we were planning to use would actually
works. This needs more design effort.
This is something we need to support eventually, and several partners want it.
I don't know what the priority is for `MBEDTLS_USE_PSA_CRYPTO` between
improving driver support and covering more of the protocol. It seems to me
that it'll be less work overall to first implement a good architecture for
`MBEDTLS_USE_PSA_CRYPTO + MBEDTLS_PSA_CRYPTO_CONFIG` and then extend to more
protocol features, because implementing that architecture will require changes
to the existing code and the less code there is at this point the better,
whereas extending to more protocol features will require the same amount of
work either way.
### Backward compatibility issues with making it always on
### Backward compatibility issues with making `MBEDTLS_USE_PSA_CRYPTO` always on
1. Existing applications may not be calling `psa_crypto_init()` before using
TLS, X.509 or PK. We can try to work around that by calling (the relevant
part of) it ourselves under the hood as needed, but that would likely require
splitting init between the parts that can fail and the parts that can't (see
https://github.com/ARM-software/psa-crypto-api/pull/536 for that).
<https://github.com/ARM-software/psa-crypto-api/pull/536> for that).
2. It's currently not possible to enable `MBEDTLS_PSA_CRYPTO_C` in
configurations that don't have `MBEDTLS_ENTROPY_C`, and we can't just
auto-enable the latter, as it won't build or work out of the box on all
@ -138,7 +101,7 @@ available in entropy-less builds. (Then code using those functions still needs
to have one version using it, for entropy-less builds, and one version using
the standard function, for driver support in build with entropy.)
See https://github.com/ARMmbed/mbedtls/issues/5156
See <https://github.com/Mbed-TLS/mbedtls/issues/5156>.
Taking advantage of the existing abstractions layers - or not
=============================================================
@ -174,9 +137,8 @@ crypto API.
- Downside: tricky to implement if the PSA implementation is currently done on
top of that layer (dependency loop).
This strategy is currently (late 2021) used for ECDSA signature
verification in the PK layer, and could be extended to all operations in the
PK layer.
This strategy is currently (early 2022) used for all operations in the PK
layer.
This strategy is not very well suited to the Cipher layer, as the PSA
implementation is currently done on top of that layer.
@ -184,9 +146,9 @@ implementation is currently done on top of that layer.
This strategy will probably be used for some time for the PK layer, while we
figure out what the future of that layer is: parts of it (parse/write, ECDSA
signatures in the format that X.509 & TLS want) are not covered by PSA, so
they will need to keep existing in some way. Also the PK layer is also a good
they will need to keep existing in some way. (Also, the PK layer is a good
place for dispatching to either PSA or `mbedtls_xxx_restartable` while that
part is not covered by PSA yet.
part is not covered by PSA yet, if we decide to do that.)
Replace calls for each operation
--------------------------------
@ -199,10 +161,8 @@ Replace calls for each operation
code size.
- Downside: TLS/X.509 code has to be done for each operation.
This strategy is currently (late 2021) used for the MD layer. (Currently only
a subset of calling places, but will be extended to all of them.)
In the future (early 2022) we're going to use it for the Cipher layer as well.
This strategy is currently (early 2022) used for the MD layer and the Cipher
layer.
Opt-in use of PSA from the abstraction layer
--------------------------------------------
@ -225,20 +185,16 @@ function also allows for key isolation (the key is only held by PSA,
supporting both G1 and G2 in that area), and one without isolation (the key is
still stored outside of PSA most of the time, supporting only G1).
This strategy, with support for key isolation, is currently (end of 2021) used for ECDSA
signature generation in the PK layer - see `mbedtls_pk_setup_opaque()`. This
This strategy, with support for key isolation, is currently (early 2022) used for
private-key operations in the PK layer - see `mbedtls_pk_setup_opaque()`. This
allows use of PSA-held private ECDSA keys in TLS and X.509 with no change to
the TLS/X.509 code, but a contained change in the application. If could be
extended to other private key operations in the PK layer, which is the plan as
of early 2022.
the TLS/X.509 code, but a contained change in the application.
This strategy, without key isolation, is also currently used in the Cipher
layer - see `mbedtls_cipher_setup_psa()`. This allows use of PSA for cipher
operations in TLS with no change to the application code, and a
contained change in TLS code. (It currently only supports a subset of
ciphers.) However, we'll move to the "Replace calls for each operation"
strategy (early 2022), in the hope of being able to build without this layer
in order to save some code size in the future.
This strategy, without key isolation, was also previously used (until 3.1
included) in the Cipher layer - see `mbedtls_cipher_setup_psa()`. This allowed
use of PSA for cipher operations in TLS with no change to the application
code, and a contained change in TLS code. (It only supported a subset of
ciphers.)
Note: for private key operations in the PK layer, both the "silent" and the
"opt-in" strategy can apply, and can complement each other, as one provides
@ -249,15 +205,188 @@ support for drivers, but fails to provide isolation support.
Summary
-------
Strategies currently used with each abstraction layer:
Strategies currently (early 2022) used with each abstraction layer:
- PK (for G1): silently call PSA
- PK (for G2): opt-in use of PSA (new key type)
- Cipher (G1):
- late 2021: opt-in use of PSA (new setup function)
- early 2022: moving to "replace calls at each call site"
- Cipher (G1): replace calls at each call site
- MD (G1): replace calls at each call site
Supporting builds with drivers without the software implementation
==================================================================
This section presents a plan towards G5: save code size by compiling out our
software implementation when a driver is available.
Additionally, we want to save code size by compiling out the
abstractions layers that we are not using when `MBEDTLS_USE_PSA_CRYPTO` is
enabled (see previous section): MD and Cipher.
Let's expand a bit on the definition of the goal: in such a configuration
(driver used, software implementation and abstraction layer compiled out),
we want:
a. the library to build in a reasonably-complete configuration,
b. with all tests passing,
c. and no more tests skipped than the same configuration with software
implementation.
Criterion (c) ensures not only test coverage, but that driver-based builds are
at feature parity with software-based builds.
We can roughly divide the work needed to get there in the following steps:
0. Have a working driver interface for the algorithms we want to replace.
1. Have users of these algorithms call to PSA, not the legacy API, for all
operations. (This is G1, and for PK, X.509 and TLS this is controlled by
`MBEDTLS_USE_PSA_CRYPTO`.) This needs to be done in the library and tests.
2. Have users of these algorithms not depend on the legacy API for information
management (getting a size for a given algorithm, etc.)
3. Adapt compile-time guards used to query availability of a given algorithm;
this needs to be done in the library (for crypto operations and data) and
tests.
Note: the first two steps enable use of drivers, but not by themselves removal
of the software implementation.
Note: the fact that step 1 is not achieved for all of libmbedcrypto (see
below) is the reason why criterion (a) has "a reasonably-complete
configuration", to allow working around internal crypto dependencies when
working on other parts such as X.509 and TLS - for example, a configuration
without RSA PKCS#1 v2.1 still allows reasonable use of X.509 and TLS.
Note: this is a conceptual division that will sometimes translate to how the
work is divided into PRs, sometimes not. For example, in situations where it's
not possible to achieve good test coverage at the end of step 1 or step 2, it
is preferable to group with the next step(s) in the same PR until good test
coverage can be reached.
**Status as of Mbed TLS 3.2:**
- Step 0 is achieved for most algorithms, with only a few gaps remaining.
- Step 1 is achieved for most of PK, X.509, and TLS when
`MBEDTLS_USE_PSA_CRYPTO` is enabled with only a few gaps remaining (see
docs/use-psa-crypto.md).
- Step 1 is not achieved for a lot of the crypto library including the PSA
core. For example, `entropy.c` calls the legacy API
`mbedtls_sha256` (or `mbedtls_sha512` optionally); `hmac_drbg.c` calls the
legacy API `mbedtls_md` and `ctr_drbg.c` calls the legacy API `mbedtls_aes`;
the PSA core depends on the entropy module and at least one of the DRBG
modules (unless `MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG` is used). Further, several
crypto modules have similar issues, for example RSA PKCS#1 v2.1 calls
`mbedtls_md` directly.
- Step 2 is achieved for most of X.509 and TLS (same gaps as step 1) when
`MBEDTLS_USE_PSA_CRYPTO` is enabled - this was tasks like #5795, #5796,
#5797. It is being done in PK and RSA PKCS#1 v1.5 by PR #6065.
- Step 3 was mostly not started at all before 3.2; it is being done for PK by
PR #6065.
**Strategy for step 1:**
Regarding PK, X.509, and TLS, this is mostly achieved with only a few gaps.
(The strategy was outlined in the previous section.)
Regarding libmbedcrypto, outside of the RNG subsystem, for modules that
currently depend on other legacy crypto modules, this can be achieved without
backwards compatibility issues, by using the software implementation if
available, and "falling back" to PSA only if it's not. The compile-time
dependency changes from the current one (say, `MD_C` or `AES_C`) to "the
previous dependency OR PSA Crypto with needed algorithms". When building
without software implementation, users need to call `psa_crypto_init()` before
calling any function from these modules. This condition does not constitute a
break of backwards compatibility, as it was previously impossible to build in
those configurations, and in configurations were the build was possible,
application code keeps working unchanged. An work-in-progress example of
applying this strategy, for RSA PKCS#1 v2.1, is here:
<https://github.com/Mbed-TLS/mbedtls/pull/6141>
There is a problem with the modules used for the PSA RNG, as currently the RNG
is initialized before drivers and the key store. This part will need further
study, but in the meantime we can proceed with everything that's not the
entropy module of one of the DRBG modules, and that does not depend on one of
those modules.
**Strategy for step 2:**
The most satisfying situation here is when we can just use the PSA Crypto API
for information management as well. However sometimes it may not be
convenient, for example in parts of the code that accept old-style identifiers
(such as `mbedtls_md_type_t`) in their API and can't assume PSA to be
compiled in (such as `rsa.c`).
It is suggested that, as a temporary solution until we clean this up
later when removing the legacy API including its identifiers (G4), we may
occasionally use ad-hoc internal functions, such as the ones introduced by PR
6065 in `library/hash_info.[ch]`.
An alternative would be to have two different code paths depending on whether
`MBEDTLS_PSA_CRYPTO_C` is defined or not. However this is not great for
readability or testability.
**Strategy for step 3:**
There are currently two (complementary) ways for crypto-using code to check if a
particular algorithm is supported: using `MBEDTLS_xxx` macros, and using
`PSA_WANT_xxx` macros. For example, PSA-based code that want to use SHA-256
will check for `PSA_WANT_ALG_SHA_256`, while legacy-based code that wants to
use SHA-256 will check for `MBEDTLS_SHA256_C` if using the `mbedtls_sha256`
API, or for `MBEDTLS_MD_C && MBEDTLS_SHA256_C` if using the `mbedtls_md` API.
Code that obeys `MBEDTLS_USE_PSA_CRYPTO` will want to use one of the two
dependencies above depending on whether `MBEDTLS_USE_PSA_CRYPTO` is defined:
if it is, the code want the algorithm available in PSA, otherwise, it wants it
available via the legacy API(s) is it using (MD and/or low-level).
The strategy for steps 1 and 2 above will introduce new situations: code that
currently compute hashes using MD (resp. a low-level hash module) will gain
the ability to "fall back" to using PSA if the legacy dependency isn't
available. Data related to a certain hash (OID, sizes, translations) should
only be included in the build if it is possible to use that hash in some way.
In order to cater to these new needs, new families of macros are introduced in
`library/legacy_or_psa.h`, see its documentation for details.
It should be noted that there are currently:
- too many different ways of computing a hash (low-level, MD, PSA);
- too many different ways to configure the library that influence which of
these ways is available and will be used (`MBEDTLS_USE_PSA_CRYPTO`,
`MBEDTLS_PSA_CRYPTO_CONFIG`, `mbedtls_config.h` + `psa/crypto_config.h`).
As a result, we need more families of dependency macros than we'd like to.
This is a temporary situation until we move to a place where everything is
based on PSA Crypto. In the meantime, long and explicit names where chosen for
the new macros in the hope of avoiding confusion.
Executing step 3 will mostly consist of using the right dependency macros in
the right places (once the previous steps are done).
**Note on testing**
Since supporting driver-only builds is not about adding features, but about
supporting existing features in new types of builds, testing will not involve
adding cases to the test suites, but instead adding new components in `all.sh`
that build and run tests in newly-supported configurations. For example, if
we're making some part of the library work with hashes provided only by
drivers when `MBEDTLS_USE_PSA_CRYPTO` is defined, there should be a place in
`all.sh` that builds and run tests in such a configuration.
There is however a risk, especially in step 3 where we change how dependencies
are expressed (sometimes in bulk), to get things wrong in a way that would
result in more tests being skipped, which is easy to miss. Care must be
taken to ensure this does not happen. The following criteria can be used:
- the sets of tests skipped in the default config and the full config must be
the same before and after the PR that implements step 3;
- the set of tests skipped in the driver-only build is the same as in an
equivalent software-based configuration, or the difference is small enough,
justified, and a github issue is created to track it.
Note that the favourable case is when the number of tests skipped is 0 in the
driver-only build. In other cases, analysis of the outcome files is needed,
see the example script `outcome-analysis.sh` in the same directory.
Migrating away from the legacy API
==================================
@ -267,7 +396,7 @@ mainly as they relate to choices in previous stages.
The role of the PK/Cipher/MD APIs in user migration
---------------------------------------------------
We're currently taking advantage of the existing PK and Cipher layers in order
We're currently taking advantage of the existing PK layer in order
to reduce the number of places where library code needs to be changed. It's
only natural to consider using the same strategy (with the PK, MD and Cipher
layers) for facilitating migration of application code.
@ -281,7 +410,7 @@ The most favourable case is if we can have a zero-cost abstraction (no
runtime, RAM usage or code size penalty), for example just a bunch of
`#define`s, essentially mapping `mbedtls_` APIs to their `psa_` equivalent.
Unfortunately that's unlikely fully work. For example, the MD layer uses the
Unfortunately that's unlikely to fully work. For example, the MD layer uses the
same context type for hashes and HMACs, while the PSA API (rightfully) has
distinct operation types. Similarly, the Cipher layer uses the same context
type for unauthenticated and AEAD ciphers, which again the PSA API
@ -360,7 +489,7 @@ would need a way to easily extract the PSA key ID from the PK context.
2. APIs the accept list of identifiers: for example
`mbedtls_ssl_conf_curves()` taking a list of `mbedtls_ecp_group_id`s. This
could be changed to accept a list of pairs (`psa_ecc_familiy_t`, size) but we
could be changed to accept a list of pairs (`psa_ecc_family_t`, size) but we
should probably take this opportunity to move to a identifier independent from
the underlying crypto implementation and use TLS-specific identifiers instead
(based on IANA values or custom enums), as is currently done in the new
@ -373,5 +502,5 @@ An question that needs careful consideration when we come around to removing
the low-level crypto APIs and making PK, MD and Cipher optional compatibility
layers is to be sure to preserve testing quality. A lot of the existing test
cases use the low level crypto APIs; we would need to either keep using that
API for tests, or manually migrated test to the PSA Crypto API. Perhaps a
API for tests, or manually migrate tests to the PSA Crypto API. Perhaps a
combination of both, perhaps evolving gradually over time.

80
docs/architecture/psa-migration/tasks-g2.md
View File

@ -1,80 +0,0 @@
This document is temporary; it lists tasks to achieve G2 as described in
`strategy.md` while the strategy is being reviewed - once that's done,
corresponding github issues will be created and this document removed.
For all of the tasks here, specific testing (integration and unit test depending
on the task) is required, see `testing.md`.
RSA Signature operations
========================
In PK
-----
### Modify existing `PK_OPAQUE` type to allow for RSA keys
- the following must work and be tested: `mbedtls_pk_get_type()`,
`mbedtls_pk_get_name()`, `mbedtls_pk_get_bitlen()`, `mbedtls_pk_get_len()`,
`mbedtls_pk_can_do()`.
- most likely adapt `pk_psa_genkey()` in `test_suite_pk.function`.
- all other function (sign, verify, encrypt, decrypt, check pair, debug) will
return `MBEDTLS_ERR_PK_TYPE_MISMATCH` and this will be tested too.
### Modify `mbedtls_pk_wrap_as_opaque()` to work with RSA.
- OK to have policy hardcoded on signing with PKCS1v1.5, or allow more if
available at this time
### Modify `mbedtls_pk_write_pubkey_der()` to work with RSA-opaque.
- OK to just test that a generated key (with `pk_psa_genkey()`) can be
written, without checking for correctness of the result - this will be
tested as part of another task
### Make `mbedtls_pk_sign()` work with RSA-opaque.
- testing may extend `pk_psa_sign()` in `test_suite_pk_function` by adding
selector for ECDSA/RSA.
In X.509
--------
### Test using RSA-opaque for CSR generation
- similar to what's already done with ECDSA-opaque
### Test using opaque keys for Certificate generation
- similar to what's done with testing CSR generation
- should test both RSA and ECDSA as ECDSA is not tested yet
- might require slight code adaptations, even if unlikely
In TLS
------
### Test using RSA-opaque for TLS client auth
- similar to what's already done with ECDSA-opaque
### Test using RSA-opaque for TLS server auth
- similar to what's already done with ECDSA-opaque
- key exchanges: ECDHE-RSA and DHE-RSA
RSA decrypt
===========
### Extend `PK_OPAQUE` to allow RSA decryption (PKCS1 v1.5)
### Test using that in TLS for RSA and RSA-PSK key exchange.
Support opaque PSKs for "mixed-PSK" key exchanges
=================================================
See `PSA-limitations.md`.
Possible split:
- one task to extend PSA (see `PSA-limitations.md`)
- then one task per handshake: DHE-PSK, ECDHE-PSK, RSA-PSK (with tests for
each)

16
docs/architecture/psa-migration/testing.md
View File

@ -21,11 +21,11 @@ they should be when `MBEDTLS_USE_PSA_CRYPTO` is enabled.
However, when it comes to TLS, we also have the option of using debug messages
to confirm which code path is taken. This is generally unnecessary, except when
a decision is made at run-time about whether to use the PSA or legacy code
path. For example, for record protection, currently some ciphers are supported
via PSA while some others aren't, with a run-time fallback. In this case, it's
path. (For example, for record protection, previously (until 3.1), some ciphers were supported
via PSA while some others weren't, with a run-time fallback. In this case, it's
good to have a debug message checked by the test case to confirm that the
right decision was made at run-time, i. e. that we didn't use the fallback for
ciphers that are supposed to be supported.
ciphers that are supposed to be supported.)
New APIs meant for application use
@ -54,9 +54,8 @@ In that case, we want:
(We should have the same server-side.)
- in `test_suite_x509write` we have a new test function
`x509_csr_check_opaque()` checking integration of the new API with the
existing `mbedtls_x509write_csr_set_key()`.
(We should have something similar for
`mbedtls_x509write_crt_set_issuer_key()`.)
existing `mbedtls_x509write_csr_set_key()`. (And also
`mbedtls_x509write_crt_set_issuer_key()` since #5710.)
For some APIs, for example with `mbedtls_ssl_conf_psk_opaque()`, testing in
`test_suite_ssl` was historically not possible, so we only have testing in
@ -65,8 +64,9 @@ For some APIs, for example with `mbedtls_ssl_conf_psk_opaque()`, testing in
New APIs meant for internal use
-------------------------------
For example, `mbedtls_cipher_setup_psa()` is meant to be used by the TLS
layer, but probably not directly by applications.
For example, `mbedtls_cipher_setup_psa()` (no longer used, soon to be
deprecated - #5261) was meant to be used by the TLS layer, but probably not
directly by applications.
In that case, we want:

2
docs/architecture/testing/driver-interface-test-strategy.md
View File

@ -87,7 +87,7 @@ Creating or removing a key in a secure element involves multiple storage modific
* This must be done for each possible flow, including error cases (e.g. a key creation that fails midway due to `OUT_OF_MEMORY`).
* The recovery during `psa_crypto_init` can itself be interrupted. Test those interruptions too.
* Two things need to be tested: the key that is being created or destroyed, and the driver's persistent storage.
* Check both that the storage has the expected content (this can be done by e.g. using a key that is supposed to be present) and does not have any unexpected content (for keys, this can be done by checking that `psa_open_key` fails with `PSA_ERRROR_DOES_NOT_EXIST`).
* Check both that the storage has the expected content (this can be done by e.g. using a key that is supposed to be present) and does not have any unexpected content (for keys, this can be done by checking that `psa_open_key` fails with `PSA_ERROR_DOES_NOT_EXIST`).
This requires instrumenting the storage implementation, either to force it to fail at each point or to record successive storage states and replay each of them. Each `psa_its_xxx` function call is assumed to be atomic.

2
docs/architecture/testing/psa-storage-format-testing.md
View File

@ -40,7 +40,7 @@ If the way certain keys are stored changes, and we don't deliberately decide to
## Storage architecture overview
The PSA subsystem provides storage on top of the PSA trusted storage interface. The state of the storage is a mapping from file identifer (a 64-bit number) to file content (a byte array). These files include:
The PSA subsystem provides storage on top of the PSA trusted storage interface. The state of the storage is a mapping from file identifier (a 64-bit number) to file content (a byte array). These files include:
* [Key files](#key-storage) (files containing one key's metadata and, except for some secure element keys, key material).
* The [random generator injected seed or state file](#random-generator-state) (`PSA_CRYPTO_ITS_RANDOM_SEED_UID`).

290
docs/architecture/tls13-support.md
View File

@ -4,8 +4,8 @@ TLS 1.3 support
Overview
--------
Mbed TLS provides a minimum viable implementation of the TLS 1.3 protocol
defined in the "MVP definition" section below. The TLS 1.3 support enablement
Mbed TLS provides a partial implementation of the TLS 1.3 protocol defined in
the "Support description" section below. The TLS 1.3 support enablement
is controlled by the MBEDTLS_SSL_PROTO_TLS1_3 configuration option.
The development of the TLS 1.3 protocol is based on the TLS 1.3 prototype
@ -16,38 +16,22 @@ development branch into the prototype. The section "Prototype upstreaming
status" below describes what remains to be upstreamed.
MVP definition
--------------
Support description
-------------------
- Overview
- The TLS 1.3 MVP implements only the client side of the protocol.
- Mbed TLS implements both the client and the server side of the TLS 1.3
protocol.
- The TLS 1.3 MVP supports ECDHE key establishment.
- Mbed TLS supports ECDHE key establishment.
- The TLS 1.3 MVP does not support DHE key establishment.
- Mbed TLS does not support DHE key establishment.
- The TLS 1.3 MVP does not support pre-shared keys, including any form of
- Mbed TLS does not support pre-shared keys, including any form of
session resumption. This implies that it does not support sending early
data (0-RTT data).
- The TLS 1.3 MVP supports the authentication of the server by the client
but does not support authentication of the client by the server. In terms
of TLS 1.3 authentication messages, this means that the TLS 1.3 MVP
supports the processing of the Certificate and CertificateVerify messages
but not of the CertificateRequest message.
- The TLS 1.3 MVP does not support the handling of server HelloRetryRequest
message. In practice, this means that the handshake will fail if the MVP
does not provide in its ClientHello the shared secret associated to the
group selected by the server for key establishement. For more information,
see the comment associated to the `key_share` extension below.
- If the TLS 1.3 MVP receives a HelloRetryRequest or a CertificateRequest
message, it aborts the handshake with an handshake_failure closure alert
and the `mbedtls_ssl_handshake()` returns in error with the
`MBEDTLS_ERR_SSL_HANDSHAKE_FAILURE` error code.
- Supported cipher suites: depends on the library configuration. Potentially
all of them:
TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256,
@ -55,94 +39,72 @@ MVP definition
- Supported ClientHello extensions:
| Extension | MVP | Prototype (1) |
| ---------------------------- | ------- | ------------- |
| server_name | YES | YES |
| max_fragment_length | no | YES |
| status_request | no | no |
| supported_groups | YES | YES |
| signature_algorithms | YES | YES |
| use_srtp | no | no |
| heartbeat | no | no |
| apln | no | YES |
| signed_certificate_timestamp | no | no |
| client_certificate_type | no | no |
| server_certificate_type | no | no |
| padding | no | no |
| key_share | YES (2) | YES |
| pre_shared_key | no | YES |
| psk_key_exchange_modes | no | YES |
| early_data | no | YES |
| cookie | no | YES |
| supported_versions | YES (3) | YES |
| certificate_authorities | no | no |
| post_handshake_auth | no | no |
| signature_algorithms_cert | no | no |
| Extension | Support |
| ---------------------------- | ------- |
| server_name | YES |
| max_fragment_length | no |
| status_request | no |
| supported_groups | YES |
| signature_algorithms | YES |
| use_srtp | no |
| heartbeat | no |
| apln | YES |
| signed_certificate_timestamp | no |
| client_certificate_type | no |
| server_certificate_type | no |
| padding | no |
| key_share | YES |
| pre_shared_key | no |
| psk_key_exchange_modes | no |
| early_data | no |
| cookie | no |
| supported_versions | YES |
| certificate_authorities | no |
| post_handshake_auth | no |
| signature_algorithms_cert | no |
(1) This is just for comparison.
(2) The MVP sends only one shared secret corresponding to the configured
preferred group. This could end up with connection failure if the
server does not support our preferred curve, as the MVP does not implement
HelloRetryRequest. The preferred group is the group of the first curve in
the list of allowed curves as defined by the configuration. The allowed
curves are by default ordered as follows: `x25519`, `secp256r1`,
`secp384r1` and finally `secp521r1`. Note that, in the absence of an
application profile standard specifying otherwise, section 9.1 of the
specification rather promotes curve `secp256r1` to be supported over
curve `x25519`. The MVP would, however, rather keep the preference order
currently promoted by Mbed TLS as this applies to TLS 1.2 as well, and
changing the order only for TLS1.3 would be potentially difficult.
In the unlikely event a server does not support curve `x25519` but does
support curve `secp256r1`, curve `secp256r1` can be set as the preferred
curve through the `mbedtls_ssl_conf_curves()` API.
(3) The MVP proposes only TLS 1.3 and does not support version negotiation.
Out-of-protocol fallback is supported though if the Mbed TLS library
has been built to support both TLS 1.3 and TLS 1.2: just set the
maximum of the minor version of the SSL configuration to
MBEDTLS_SSL_MINOR_VERSION_3 (`mbedtls_ssl_conf_min_version()` API) and
re-initiate a server handshake.
- Supported groups: depends on the library configuration.
Potentially all ECDHE groups but x448:
secp256r1, x25519, secp384r1 and secp521r1.
Potentially all ECDHE groups:
secp256r1, x25519, secp384r1, x448 and secp521r1.
Finite field groups (DHE) are not supported.
- Supported signature algorithms (both for certificates and CertificateVerify):
depends on the library configuration.
Potentially:
rsa_pkcs1_sha256, rsa_pss_rsae_sha256, ecdsa_secp256r1_sha256,
ecdsa_secp384r1_sha384 and ecdsa_secp521r1_sha512.
ecdsa_secp256r1_sha256, ecdsa_secp384r1_sha384, ecdsa_secp521r1_sha512,
rsa_pkcs1_sha256, rsa_pkcs1_sha384, rsa_pkcs1_sha512, rsa_pss_rsae_sha256,
rsa_pss_rsae_sha384 and rsa_pss_rsae_sha512.
Note that in absence of an application profile standard specifying otherwise
the three first ones in the list above are mandatory (see section 9.1 of the
specification).
rsa_pkcs1_sha256, rsa_pss_rsae_sha256 and ecdsa_secp256r1_sha256 are
mandatory (see section 9.1 of the specification).
- Supported versions:
- TLS 1.2 and TLS 1.3 but version negotiation is not supported.
- TLS 1.2 and TLS 1.3 with version negotiation on the client side, not server
side.
- TLS 1.3 cannot be enabled in the build (MBEDTLS_SSL_PROTO_TLS1_3
configuration option) without TLS 1.2 (MBEDTLS_SSL_PROTO_TLS1_2 configuration
option).
- TLS 1.2 can be enabled in the build independently of TLS 1.3.
- TLS 1.2 and TLS 1.3 can be enabled in the build independently of each
other.
- If both TLS 1.3 and TLS 1.2 are enabled at build time, only one of them can
be configured at runtime via `mbedtls_ssl_conf_{min,max}_version`. Otherwise,
`mbedtls_ssl_setup` will raise `MBEDTLS_ERR_SSL_BAD_CONFIG` error.
be configured at runtime via `mbedtls_ssl_conf_{min,max}_tls_version` for a
server endpoint. Otherwise, `mbedtls_ssl_setup` will raise
`MBEDTLS_ERR_SSL_BAD_CONFIG` error.
- Compatibility with existing SSL/TLS build options:
The TLS 1.3 MVP is compatible with all TLS 1.2 configuration options in the
sense that when enabling the TLS 1.3 MVP in the library there is no need to
modify the configuration for TLS 1.2. The MBEDTLS_USE_PSA_CRYPTO configuration
option is an exception though, the TLS 1.3 MVP is not compatible with it.
The TLS 1.3 implementation is compatible with nearly all TLS 1.2
configuration options in the sense that when enabling TLS 1.3 in the library
there is rarely any need to modify the configuration from that used for
TLS 1.2. There are two exceptions though: the TLS 1.3 implementation requires
MBEDTLS_PSA_CRYPTO_C and MBEDTLS_SSL_KEEP_PEER_CERTIFICATE, so these options
must be enabled.
Mbed TLS SSL/TLS related features are not supported or not applicable to the
TLS 1.3 MVP:
Most of the Mbed TLS SSL/TLS related options are not supported or not
applicable to the TLS 1.3 implementation:
| Mbed TLS configuration option | Support |
| ---------------------------------------- | ------- |
@ -152,13 +114,12 @@ MVP definition
| MBEDTLS_SSL_DEBUG_ALL | no |
| MBEDTLS_SSL_ENCRYPT_THEN_MAC | n/a |
| MBEDTLS_SSL_EXTENDED_MASTER_SECRET | n/a |
| MBEDTLS_SSL_KEEP_PEER_CERTIFICATE | no |
| MBEDTLS_SSL_KEEP_PEER_CERTIFICATE | no (1) |
| MBEDTLS_SSL_RENEGOTIATION | n/a |
| MBEDTLS_SSL_MAX_FRAGMENT_LENGTH | no |
| | |
| MBEDTLS_SSL_SESSION_TICKETS | no |
| MBEDTLS_SSL_EXPORT_KEYS | no (1) |
| MBEDTLS_SSL_SERVER_NAME_INDICATION | no |
| MBEDTLS_SSL_SERVER_NAME_INDICATION | yes |
| MBEDTLS_SSL_VARIABLE_BUFFER_LENGTH | no |
| | |
| MBEDTLS_ECP_RESTARTABLE | no |
@ -176,35 +137,20 @@ MVP definition
| MBEDTLS_KEY_EXCHANGE_ECDH_RSA_ENABLED | n/a |
| MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED | n/a |
| | |
| MBEDTLS_USE_PSA_CRYPTO | no |
| MBEDTLS_PSA_CRYPTO_C | no (1) |
| MBEDTLS_USE_PSA_CRYPTO | yes |
(1) Some support has already been upstreamed but it is incomplete.
(1) These options must remain in their default state of enabled.
(2) Key exchange configuration options for TLS 1.3 will likely to be
organized around the notion of key exchange mode along the line
of the MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_NONE/PSK/PSK_EPHEMERAL/EPHEMERAL
runtime configuration macros.
- Quality considerations
- Standard Mbed TLS review bar
- Interoperability testing with OpenSSL and GnuTLS. Test with all the
cipher suites and signature algorithms supported by OpenSSL/GnuTLS server.
- Negative testing against OpenSSL/GnuTLS servers with which the
handshake fails due to incompatibility with the capabilities of the
MVP: TLS 1.2 or 1.1 server, server sending an HelloRetryRequest message in
response to the MVP ClientHello, server sending a CertificateRequest
message ...
Prototype upstreaming status
----------------------------
The following summarizes which parts of the TLS 1.3 prototype remain to be
upstreamed:
- Ephemeral only handshake on client side: client authentication,
HelloRetryRequest support, version negotiation.
- Ephemeral only handshake server side.
The following parts of the TLS 1.3 prototype remain to be upstreamed:
- Pre-shared keys, session resumption and 0-RTT data (both client and server
side).
@ -324,7 +270,7 @@ TLS 1.3 specific coding rules:
```
- To mitigate what happened here
(https://github.com/ARMmbed/mbedtls/pull/4882#discussion_r701704527) from
(https://github.com/Mbed-TLS/mbedtls/pull/4882#discussion_r701704527) from
happening again, use always a local variable named `p` for the reading
pointer in functions parsing TLS 1.3 data, and for the writing pointer in
functions writing data into an output buffer and only that variable. The
@ -388,10 +334,10 @@ General coding rules:
Example:
```
int mbedtls_ssl_tls13_start_handshake_msg( mbedtls_ssl_context *ssl,
unsigned hs_type,
unsigned char **buf,
size_t *buf_len );
int mbedtls_ssl_start_handshake_msg( mbedtls_ssl_context *ssl,
unsigned hs_type,
unsigned char **buf,
size_t *buf_len );
```
- When a function's parameters span several lines, group related parameters
@ -400,12 +346,110 @@ General coding rules:
For example, prefer:
```
mbedtls_ssl_tls13_start_handshake_msg( ssl, hs_type,
buf, buf_len );
mbedtls_ssl_start_handshake_msg( ssl, hs_type,
buf, buf_len );
```
over
```
mbedtls_ssl_tls13_start_handshake_msg( ssl, hs_type, buf,
buf_len );
mbedtls_ssl_start_handshake_msg( ssl, hs_type, buf,
buf_len );
```
even if it fits.
Overview of handshake code organization
---------------------------------------
The TLS 1.3 handshake protocol is implemented as a state machine. The
functions `mbedtls_ssl_tls13_handshake_{client,server}_step` are the top level
functions of that implementation. They are implemented as a switch over all the
possible states of the state machine.
Most of the states are either dedicated to the processing or writing of an
handshake message.
The implementation does not go systematically through all states as this would
result in too many checks of whether something needs to be done or not in a
given state to be duplicated across several state handlers. For example, on
client side, the states related to certificate parsing and validation are
bypassed if the handshake is based on a pre-shared key and thus does not
involve certificates.
On the contrary, the implementation goes systematically though some states
even if they could be bypassed if it helps in minimizing when and where inbound
and outbound keys are updated. The `MBEDTLS_SSL_CLIENT_CERTIFICATE` state on
client side is a example of that.
The names of the handlers processing/writing an handshake message are
prefixed with `(mbedtls_)ssl_tls13_{process,write}`. To ease the maintenance and
reduce the risk of bugs, the code of the message processing and writing
handlers is split into a sequence of stages.
The sending of data to the peer only occurs in `mbedtls_ssl_handshake_step`
between the calls to the handlers and as a consequence handlers do not have to
care about the MBEDTLS_ERR_SSL_WANT_WRITE error code. Furthermore, all pending
data are flushed before to call the next handler. That way, handlers do not
have to worry about pending data when changing outbound keys.
### Message processing handlers
For message processing handlers, the stages are:
* coordination stage: check if the state should be bypassed. This stage is
optional. The check is either purely based on the reading of the value of some
fields of the SSL context or based on the reading of the type of the next
message. The latter occurs when it is not known what the next handshake message
will be, an example of that on client side being if we are going to receive a
CertificateRequest message or not. The intent is, apart from the next record
reading to not modify the SSL context as this stage may be repeated if the
next handshake message has not been received yet.
* fetching stage: at this stage we are sure of the type of the handshake
message we must receive next and we try to fetch it. If we did not go through
a coordination stage involving the next record type reading, the next
handshake message may not have been received yet, the handler returns with
`MBEDTLS_ERR_SSL_WANT_READ` without changing the current state and it will be
called again later.
* pre-processing stage: prepare the SSL context for the message parsing. This
stage is optional. Any processing that must be done before the parsing of the
message or that can be done to simplify the parsing code. Some simple and
partial parsing of the handshake message may append at that stage like in the
ServerHello message pre-processing.
* parsing stage: parse the message and restrict as much as possible any
update of the SSL context. The idea of the pre-processing/parsing/post-processing
organization is to concentrate solely on the parsing in the parsing function to
reduce the size of its code and to simplify it.
* post-processing stage: following the parsing, further update of the SSL
context to prepare for the next incoming and outgoing messages. This stage is
optional. For example, secret and key computations occur at this stage, as well
as handshake messages checksum update.
* state change: the state change is done in the main state handler to ease the
navigation of the state machine transitions.
### Message writing handlers
For message writing handlers, the stages are:
* coordination stage: check if the state should be bypassed. This stage is
optional. The check is based on the value of some fields of the SSL context.
* preparation stage: prepare for the message writing. This stage is optional.
Any processing that must be done before the writing of the message or that can
be done to simplify the writing code.
* writing stage: write the message and restrict as much as possible any update
of the SSL context. The idea of the preparation/writing/finalization
organization is to concentrate solely on the writing in the writing function to
reduce the size of its code and simplify it.
* finalization stage: following the writing, further update of the SSL
context to prepare for the next incoming and outgoing messages. This stage is
optional. For example, handshake secret and key computation occur at that
stage (ServerHello writing finalization), switching to handshake keys for
outbound message on server side as well.
* state change: the state change is done in the main state handler to ease
the navigation of the state machine transitions.

2
docs/proposed/psa-driver-interface.md
View File

@ -241,7 +241,7 @@ The entry points that implement each step of a multi-part operation are grouped
1. The core calls the `xxx_setup` entry point for this operation family. If this fails, the core destroys the operation context object without calling any other driver entry point on it.
1. The core calls other entry points that manipulate the operation context object, respecting the constraints.
1. If any entry point fails, the core calls the driver's `xxx_abort` entry point for this operation family, then destroys the operation context object without calling any other driver entry point on it.
1. If a “finish” entry point fails, the core destroys the operation context object without calling any other driver entry point on it. The finish entry points are: *prefix*`_mac_sign_finish`, *prefix*`_mac_verify_finish`, *prefix*`_cipher_fnish`, *prefix*`_aead_finish`, *prefix*`_aead_verify`.
1. If a “finish” entry point fails, the core destroys the operation context object without calling any other driver entry point on it. The finish entry points are: *prefix*`_mac_sign_finish`, *prefix*`_mac_verify_finish`, *prefix*`_cipher_finish`, *prefix*`_aead_finish`, *prefix*`_aead_verify`.
If a driver implements a multi-part operation but not the corresponding single-part operation, the core calls the driver's multipart operation entry points to perform the single-part operation.

8
docs/proposed/psa-driver-wrappers-codegen-migration-guide.md
View File

@ -1,5 +1,5 @@
Migrating to an auto genrated psa_crypto_driver_wrappers.c file
===============================================================
Migrating to an auto generated psa_crypto_driver_wrappers.c file
================================================================
**This is a specification of work in progress. The implementation is not yet merged into Mbed TLS.**
@ -8,7 +8,7 @@ It is meant to give the library user migration guidelines while the Mbed TLS pro
## Introduction
The design of the Driver Wrappers code generation is based on the design proposal https://github.com/ARMmbed/mbedtls/pull/5067
The design of the Driver Wrappers code generation is based on the design proposal https://github.com/Mbed-TLS/mbedtls/pull/5067
During the process of implementation there might be minor variations wrt versioning and broader implementation specific ideas, but the design remains the same.
## Prerequisites
@ -21,7 +21,7 @@ Python3, Jinja2 rev 2.10.1 and jsonschema rev 3.2.0
### What's critical for a migrating user
The Driver Wrapper auto generation project is designed to use a python templating library ( Jinja2 ) to render templates based on drivers that are defined using a Driver descrioption JSON file(s).
The Driver Wrapper auto generation project is designed to use a python templating library ( Jinja2 ) to render templates based on drivers that are defined using a Driver description JSON file(s).
While that is the larger goal, for version 1.1 here's what's changed

200
docs/use-psa-crypto.md
View File

@ -1,107 +1,80 @@
This document describes the compile-time configuration option
`MBEDTLS_USE_PSA_CRYPTO` from a user's perspective, more specifically its
current effects as well as the parts that aren't covered yet.
`MBEDTLS_USE_PSA_CRYPTO` from a user's perspective.
Current effects
===============
This option makes the X.509 and TLS library use PSA for cryptographic
operations, and enables new APIs for using keys handled by PSA Crypto.
General limitations
-------------------
General considerations
----------------------
Compile-time: enabling `MBEDTLS_USE_PSA_CRYPTO` requires
`MBEDTLS_ECP_RESTARTABLE` and
`MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER` to be disabled.
**Compile-time:** enabling `MBEDTLS_USE_PSA_CRYPTO` requires
`MBEDTLS_ECP_RESTARTABLE` to be disabled.
Effect: `MBEDTLS_USE_PSA_CRYPTO` has no effect on TLS 1.3 for which PSA
cryptography is mandatory.
**Application code:** when this option is enabled, you need to call
`psa_crypto_init()` before calling any function from the SSL/TLS, X.509 or PK
module.
Stability: any API that's only available when `MBEDTLS_USE_PSA_CRYPTO` is
defined is considered experimental and may change in incompatible ways at any
time. Said otherwise, these APIs are explicitly excluded from the usual API
stability promises.
**Scope:** `MBEDTLS_USE_PSA_CRYPTO` has no effect on the parts of the code that
are specific to TLS 1.3; those parts always use PSA Crypto. The parts of the
TLS 1.3 code that are common with TLS 1.2, however, follow this option;
currently this is the record protection code, computation of the running
handshake hash, and X.509. You need to enable `MBEDTLS_USE_PSA_CRYPTO` if you
want TLS 1.3 to use PSA everywhere.
New APIs / API extensions
-------------------------
Some of these APIs are meant for the application to use in place of
pre-existing APIs, in order to get access to the benefits; in the sub-sections
below these are indicated by "Use in (X.509 and) TLS: opt-in", meaning that
this requires changes to the application code for the (X.509 and) TLS layers
to pick up the improvements.
Some of these APIs are mostly meant for internal use by the TLS (and X.509)
layers; they are indicated below by "Use in (X.509 and) TLS: automatic",
meaning that no changes to the application code are required for the TLS (and
X.509) layers to pick up the improvements.
### PSA-held (opaque) keys in the PK layer
There is a new API function `mbedtls_pk_setup_opaque()` that can be used to
wrap a PSA keypair into a PK context. The key can be used for private-key
**New API function:** `mbedtls_pk_setup_opaque()` - can be used to
wrap a PSA key pair into a PK context. The key can be used for private-key
operations and its public part can be exported.
Benefits: isolation of long-term secrets, use of PSA Crypto drivers.
**Benefits:** isolation of long-term secrets, use of PSA Crypto drivers.
Limitations: only for private keys, only ECC. (That is, only ECDSA signature
generation. Note: currently this will use randomized ECDSA while Mbed TLS uses
deterministic ECDSA by default.) The following operations are not supported
**Limitations:** can only wrap a key pair, can only use it for private key
operations. (That is, signature generation, and for RSA decryption too.)
Note: for ECDSA, currently this uses randomized ECDSA while Mbed TLS uses
deterministic ECDSA by default. The following operations are not supported
with a context set this way, while they would be available with a normal
`ECKEY` context: `mbedtls_pk_verify()`, `mbedtls_pk_check_pair()`,
`mbedtls_pk_debug()`.
context: `mbedtls_pk_check_pair()`, `mbedtls_pk_debug()`, all public key
operations.
Use in X.509 and TLS: opt-in. The application needs to construct the PK context
**Use in X.509 and TLS:** opt-in. The application needs to construct the PK context
using the new API in order to get the benefits; it can then pass the
resulting context to the following existing APIs:
- `mbedtls_ssl_conf_own_cert()` or `mbedtls_ssl_set_hs_own_cert()` to use the
key together with a certificate for ECDSA-based key exchanges (note: while
this is supported on both sides, it's currently only tested client-side);
key together with a certificate for certificate-based key exchanges;
- `mbedtls_x509write_csr_set_key()` to generate a CSR (certificate signature
request).
In the TLS and X.509 API, there's one other function which accepts a keypair
as a PK context: `mbedtls_x509write_crt_set_issuer_key()`. Use of opaque
contexts here probably works but is so far untested.
request);
- `mbedtls_x509write_crt_set_issuer_key()` to generate a certificate.
### PSA-held (opaque) keys for TLS pre-shared keys (PSK)
There are two new API functions `mbedtls_ssl_conf_psk_opaque()` and
**New API functions:** `mbedtls_ssl_conf_psk_opaque()` and
`mbedtls_ssl_set_hs_psk_opaque()`. Call one of these from an application to
register a PSA key for use with a PSK key exchange.
Benefits: isolation of long-term secrets.
**Benefits:** isolation of long-term secrets.
Limitations: the key can only be used with "pure"
PSK key exchanges (ciphersuites starting with `TLS_PSK_WITH_`), to the
exclusion of RSA-PSK, DHE-PSK and ECDHE-PSK key exchanges. It is the responsibility of
the user to make sure that when provisioning an opaque pre-shared key, the
only PSK ciphersuites that can be negotiated are "pure" PSK; other XXX-PSK key
exchanges will result in a handshake failure with the handshake function
returning `MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE`.
**Limitations:** none.
Use in TLS: opt-in. The application needs to register the key using the new
APIs to get the benefits.
**Use in TLS:** opt-in. The application needs to register the key using one of
the new APIs to get the benefits.
### PSA-based operations in the Cipher layer
There is a new API function `mbedtls_cipher_setup_psa()` to set up a context
that will call PSA to store the key and perform the operations.
Benefits: use of PSA Crypto drivers; partial isolation of short-term secrets
(still generated outside of PSA, but then held by PSA).
This function only worked for a small number of ciphers. It is now deprecated
and it is recommended to use `psa_cipher_xxx()` or `psa_aead_xxx()` functions
directly instead.
Limitations: the key is still passed in the clear by the application. The
multi-part APIs are not supported, only the one-shot APIs. The only modes
supported are ECB, CBC without padding, GCM and CCM (this excludes stream
ciphers and ChachaPoly); the only cipher supported is AES (this excludes Aria,
Camellia, and ChachaPoly). (Note: ECB is currently not tested.) (Note: it is
possible to perform multiple one-shot operations with the same context;
however this is not unit-tested, only tested via usage in TLS.)
Use in TLS: automatic. Used when the cipher and mode is supported (with
gracious fallback to the legacy API otherwise) in all places where a cipher is
used. There are two such places: in `ssl_tls.c` for record protection, and in
`ssl_ticket.c` for protecting tickets we issue.
**Warning:** This function will be removed in a future version of Mbed TLS. If
you are using it and would like us to keep it, please let us know about your
use case.
Internal changes
----------------
@ -109,89 +82,34 @@ Internal changes
All of these internal changes are active as soon as `MBEDTLS_USE_PSA_CRYPTO`
is enabled, no change required on the application side.
### TLS: cipher operations based on PSA
### TLS: most crypto operations based on PSA
See "PSA-based operations in the Cipher layer" above.
Current exceptions:
### PK layer: ECDSA verification based on PSA
- EC J-PAKE (when `MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED` is defined)
- finite-field (non-EC) Diffie-Hellman (used in key exchanges: DHE-RSA,
DHE-PSK)
Scope: `mbedtls_pk_verify()` will call to PSA for ECDSA signature
verification.
Other than the above exceptions, all crypto operations are based on PSA when
`MBEDTLS_USE_PSA_CRYPTO` is enabled.
Benefits: use of PSA Crypto drivers.
### X.509: most crypto operations based on PSA
Use in TLS and X.509: in all places where an ECDSA signature is verified.
Current exception:
### TLS: ECDHE computation based on PSA
- verification of RSA-PSS signatures with a salt length that is different from
the hash length.
Scope: Client-side, for ECDHE-RSA and ECDHE-ECDSA key exchanges, the
computation of the ECDHE key exchange is done by PSA.
Other than the above exception, all crypto operations are based on PSA when
`MBEDTLS_USE_PSA_CRYPTO` is enabled.
Limitations: client-side only, ECDHE-PSK not covered
### PK layer: most crypto operations based on PSA
Benefits: use of PSA Crypto drivers.
Current exception:
### TLS: handshake hashes and PRF computed with PSA
- verification of RSA-PSS signatures with a salt length that is different from
the hash length, or with an MGF hash that's different from the message hash.
Scope: with TLS 1.2, the following are computed with PSA:
- the running handshake hashes;
- the hash of the ServerKeyExchange part that is signed;
- the `verify_data` part of the Finished message;
- the TLS PRF.
Other than the above exception, all crypto operations are based on PSA when
`MBEDTLS_USE_PSA_CRYPTO` is enabled.
Benefits: use of PSA Crypto drivers.
### X.509: some hashes computed with PSA
Scope: the following hashes are computed with PSA:
- when verifying a certificate chain, hash of the child for verifying the
parent's signature;
- when writing a CSR, hash of the request for self-signing the request.
Benefits: use of PSA Crypto drivers.
Parts that are not covered yet
==============================
This is only a high-level overview, grouped by theme
TLS: key exchanges / asymmetric crypto
--------------------------------------
The following key exchanges are not covered at all:
- RSA
- DHE-RSA
- DHE-PSK
- RSA-PSK
- ECDHE-PSK
- ECDH-RSA
- ECDH-ECDSA
- ECJPAKE
The following key exchanges are only partially covered:
- ECDHE-RSA: RSA operations are not covered and, server-side, the ECDHE
operation isn't either
- ECDHE-ECDSA: server-side, the ECDHE operation isn't covered. (ECDSA
signature generation is only covered if using `mbedtls_pk_setup_opaque()`.)
PSK if covered when the application uses `mbedtls_ssl_conf_psk_opaque()` or
`mbedtls_ssl_set_hs_psk_opaque()`.
TLS: symmetric crypto
---------------------
- some ciphers not supported via PSA yet: ARIA, Camellia, ChachaPoly (silent
fallback to the legacy APIs)
- the HMAC part of the CBC and NULL ciphersuites
- the HMAC computation in `ssl_cookie.c`
X.509
-----
- most hash operations are still done via the legacy API, except the few that
are documented above as using PSA
- RSA PKCS#1 v1.5 signature generation (from PSA-held keys)
- RSA PKCS#1 v1.5 signature verification
- RSA-PSS signature verification