Merge pull request #5757 from mpg/update-doc-use-psa
Update "use PSA" documentation (inc. strategy)
diff --git a/ChangeLog.d/use-psa-improvements.txt b/ChangeLog.d/use-psa-improvements.txt
new file mode 100644
index 0000000..1bd97a4
--- /dev/null
+++ b/ChangeLog.d/use-psa-improvements.txt
@@ -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.
diff --git a/README.md b/README.md
index 275e2dd..8978faf 100644
--- a/README.md
+++ b/README.md
@@ -286,11 +286,9 @@
### 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
diff --git a/docs/architecture/psa-migration/psa-limitations.md b/docs/architecture/psa-migration/psa-limitations.md
index f5b5700..7b8ec99 100644
--- a/docs/architecture/psa-migration/psa-limitations.md
+++ b/docs/architecture/psa-migration/psa-limitations.md
@@ -14,8 +14,8 @@
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 @@
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 @@
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 @@
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.
diff --git a/docs/architecture/psa-migration/strategy.md b/docs/architecture/psa-migration/strategy.md
index 2bb0284..7bb8247 100644
--- a/docs/architecture/psa-migration/strategy.md
+++ b/docs/architecture/psa-migration/strategy.md
@@ -40,16 +40,14 @@
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 @@
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 @@
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 @@
- 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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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.
diff --git a/docs/architecture/psa-migration/tasks-g2.md b/docs/architecture/psa-migration/tasks-g2.md
deleted file mode 100644
index 72bd377..0000000
--- a/docs/architecture/psa-migration/tasks-g2.md
+++ /dev/null
@@ -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)
diff --git a/docs/architecture/psa-migration/testing.md b/docs/architecture/psa-migration/testing.md
index 70229ce..f205c16 100644
--- a/docs/architecture/psa-migration/testing.md
+++ b/docs/architecture/psa-migration/testing.md
@@ -21,11 +21,11 @@
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 @@
(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 @@
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:
diff --git a/docs/use-psa-crypto.md b/docs/use-psa-crypto.md
index 9c97b5d..c849221 100644
--- a/docs/use-psa-crypto.md
+++ b/docs/use-psa-crypto.md
@@ -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 @@
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
diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h
index 37200e7..8629721 100644
--- a/include/mbedtls/mbedtls_config.h
+++ b/include/mbedtls/mbedtls_config.h
@@ -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.
*/
