AuroraMiddleware/mbedtls
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge pull request #5757 from mpg/update-doc-use-psa

Browse Source 
Update "use PSA" documentation (inc. strategy)
This commit is contained in:
Manuel Pégourié-Gonnard 2022-07-04 17:59:00 +02:00 committed by GitHub
commit 0358597589
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 143 additions and 357 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
ChangeLog.d/use-psa-improvements.txt Normal file
View File

@ -0,0 +1,12 @@
Features
* The configuration option MBEDTLS_USE_PSA_CRYPTO, which previously
affected only a limited subset of crypto operations in TLS, X.509 and PK,
now causes most of them to be done using PSA Crypto; see
docs/use-psa-crypto.md for the list of exceptions.
* The function mbedtls_pk_setup_opaque() now supports RSA key pairs as well.
Opaque keys can now be used everywhere a private key is expected in the
TLS and X.509 modules.
* Opaque pre-shared keys for TLS, provisioned with
mbedtls_ssl_conf_psk_opaque() or mbedtls_ssl_set_hs_psk_opaque(), which
previously only worked for "pure" PSK key exchange, now can also be used
for the "mixed" PSK key exchanges as well: ECDHE-PSK, DHE-PSK, RSA-PSK.

6
README.md
View File

@ -286,11 +286,9 @@ A browsable copy of the PSA Cryptography API documents is available on the [PSA
### PSA implementation in Mbed TLS
Mbed TLS includes a reference implementation of the PSA Cryptography API.
This implementation is not yet as mature as the rest of the library. Some parts of the code have not been reviewed as thoroughly, and some parts of the PSA implementation are not yet well optimized for code size.
However, it does not aim to implement the whole specification; in particular it does not implement all the algorithms.
The X.509 and TLS code can use PSA cryptography for a limited subset of operations. To enable this support, activate the compilation option `MBEDTLS_USE_PSA_CRYPTO` in `mbedtls_config.h`.
There are currently a few deviations where the library does not yet implement the latest version of the specification. Please refer to the [compliance issues on Github](https://github.com/Mbed-TLS/mbedtls/labels/compliance) for an up-to-date list.
The X.509 and TLS code can use PSA cryptography for most operations. To enable this support, activate the compilation option `MBEDTLS_USE_PSA_CRYPTO` in `mbedtls_config.h`. Note that TLS 1.3 uses PSA cryptography for most operations regardless of this option. See `docs/use-psa-crypto.md` for details.
### Upcoming features

103
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`.
@ -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
------------------
@ -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 an Extract-then-Expand approach, 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.

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

@ -40,16 +40,14 @@ We currently have two compile-time options that are relevant to the migration:
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/Mbed-TLS/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
- 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 depend 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.
@ -65,8 +63,11 @@ 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`
@ -84,7 +85,13 @@ incompatible with `MBEDTLS_USE_PSA_CRYPTO`.
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).
`MBEDTLS_ECP_RESTARTABLE` in the build). This would require some work to
dispatch operations as intended, and test.
Currently (early 2022) the mild consensus seems to be that since we'll need to
implement restartable in PSA anyway, it's probably not worth spending time on
the compatibility issue while waiting for it to get a more satisfying
resolution when PSA starts supporting restartable.
### `MBEDTLS_PSA_CRYPTO_CONFIG`
@ -174,9 +181,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 +190,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 +205,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 +229,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,13 +249,11 @@ 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
Migrating away from the legacy API
@ -281,7 +279,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
@ -373,5 +371,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:

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 exceptions, 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.
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 exceptions, 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

15
include/mbedtls/mbedtls_config.h
View File

@ -1506,9 +1506,15 @@
* 1.3 support that this option enables.
*
* Requires: MBEDTLS_SSL_KEEP_PEER_CERTIFICATE
* Requires: MBEDTLS_PSA_CRYPTO_C
*
* Note: even though TLS 1.3 depends on PSA Crypto, if you want it to only use
* PSA for all crypto operations, you need to also enable
* MBEDTLS_USE_PSA_CRYPTO; otherwise X.509 operations, and functions that are
* common with TLS 1.2 (record protection, running handshake hash) will still
* use non-PSA crypto.
*
* Uncomment this macro to enable the support for TLS 1.3.
*
*/
//#define MBEDTLS_SSL_PROTO_TLS1_3
@ -1763,12 +1769,11 @@
* \note See docs/use-psa-crypto.md for a complete description of what this
* option currently does, and of parts that are not affected by it so far.
*
* \warning This option enables new Mbed TLS APIs which are currently
* considered experimental and may change in incompatible ways at any time.
* That is, the APIs enabled by this option are not covered by the usual
* promises of API stability.
* \warning If you enable this option, you need to call `psa_crypto_init()`
* before calling any function from the SSL/TLS, X.509 or PK modules.
*
* Requires: MBEDTLS_PSA_CRYPTO_C.
* Conflicts with: MBEDTLS_ECP_RESTARTABLE
*
* Uncomment this to enable internal use of PSA Crypto and new associated APIs.
*/