Remove USE_PSA from remaining documentation
MBED_TLS_USE_PSA_CRYPTO is now always enabled we need to remove
documentation discussing cases when it is disabled.
Signed-off-by: Janos Follath <janos.follath@arm.com>
diff --git a/README.md b/README.md
index 317874f..7d3a435 100644
--- a/README.md
+++ b/README.md
@@ -295,7 +295,7 @@
Mbed TLS includes a reference implementation of the PSA Cryptography API.
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 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.
+The X.509 and TLS code can use PSA cryptography for most operations. See `docs/use-psa-crypto.md` for details.
### PSA drivers
diff --git a/docs/architecture/psa-migration/psa-legacy-bridges.md b/docs/architecture/psa-migration/psa-legacy-bridges.md
index 912344e..75678c4 100644
--- a/docs/architecture/psa-migration/psa-legacy-bridges.md
+++ b/docs/architecture/psa-migration/psa-legacy-bridges.md
@@ -40,13 +40,13 @@
* Only PSA supports isolating cryptographic material in a secure service.
* The legacy API has features that are not present (yet) in PSA, notably parsing and formatting asymmetric keys.
-The legacy API can partially leverage PSA features via `MBEDTLS_USE_PSA_CRYPTO`, but this has limited scope.
+The legacy API can partially leverage PSA features, but this has limited scope.
In addition, many applications cannot be migrated in a single go. For large projects, it is impractical to rewrite a significant part of the code all at once. (For example, Mbed TLS itself will have taken more than 6 years to transition.) Projects that use one or more library in addition to Mbed TLS must follow the evolution of these libraries, each of which might have its own pace.
### Where mixing happens
-Mbed TLS can be, and normally is, built with support for both APIs. Therefore no special effort is necessary to allow an application to use both APIs.
+Mbed TLS is, built with support for both APIs. Therefore no special effort is necessary to allow an application to use both APIs.
Special effort is necessary to use both APIs as part of the implementation of the same feature. From an informal analysis of typical application requirements, we identify four parts of the use of cryptography which can be provided by different APIs:
@@ -155,7 +155,6 @@
Reasons for needing a PSA key object:
* Using the key with third-party interface that takes a PSA key identifier as input. (Mbed TLS itself has a few TLS functions that take PSA key identifiers, but as of Mbed TLS 3.5, it is always possible to use a legacy key instead.)
-* Benefiting from a PSA accelerator, or from PSA's world separation, even without `MBEDTLS_USE_PSA_CRYPTO`. (Not a priority scenario: we generally expect people to activate `MBEDTLS_USE_PSA_CRYPTO` at an early stage of their migration to PSA.)
Gap: a way to create a PSA key object from an `mbedtls_pk_context`. This partially exists in the form of `mbedtls_pk_wrap_as_opaque`, but it is not fully satisfactory, for reasons that are detailed in “[API to create a PSA key from a PK context](#api-to-create-a-psa-key-from-a-pk-context)” below.
@@ -167,7 +166,6 @@
* It creates a PK key of type `MBEDTLS_PK_OPAQUE` that wraps the PSA key. This is good enough in some scenarios, but not others. For example, it's ok for pkwrite, because we've upgraded the pkwrite code to handle `MBEDTLS_PK_OPAQUE`. That doesn't help users of third-party libraries that haven't yet been upgraded.
* It ties the lifetime of the PK object to the PSA key, which is error-prone: if the PSA key is destroyed but the PK object isn't, there is no way to reliably detect any subsequent misuse of the PK object.
-* It is only available under `MBEDTLS_USE_PSA_CRYPTO`. This is not a priority concern, since we generally expect people to activate `MBEDTLS_USE_PSA_CRYPTO` at an early stage of their migration to PSA. However, this function is useful to use specific PSA keys in X.509/TLS regardless of whether X.509/TLS use the PSA API for all cryptographic operations, so this is a wart in the current API.
It therefore appears that we need two ways to “convert” a PSA key to PK:
@@ -176,7 +174,7 @@
Gap: a way to copy a PSA key into a PK context. This can only be expected to work if the PSA key is exportable.
-After some discussion, have not identified anything we want to change in the behavior of `mbedtls_pk_setup_opaque`. We only want to generalize it to non-`MBEDTLS_USE_PSA_CRYPTO` and to document it better.
+After some discussion, have not identified anything we want to change in the behavior of `mbedtls_pk_setup_opaque`.
#### Signature formats
@@ -319,7 +317,7 @@
[ACTION] [#8712](https://github.com/Mbed-TLS/mbedtls/issues/8712) Clarify the documentation of `mbedtls_pk_setup_opaque` regarding which algorithms the resulting key will perform with `mbedtls_pk_sign`, `mbedtls_pk_verify`, `mbedtls_pk_encrypt`, `mbedtls_pk_decrypt`.
-[ACTION] [#8710](https://github.com/Mbed-TLS/mbedtls/issues/8710) Provide `mbedtls_pk_setup_opaque` whenever `MBEDTLS_PSA_CRYPTO_CLIENT` is enabled, not just when `MBEDTLS_USE_PSA_CRYPTO` is enabled. This is nice-to-have, not critical. Update `use-psa-crypto.md` accordingly.
+[ACTION] [#8710](https://github.com/Mbed-TLS/mbedtls/issues/8710) Provide `mbedtls_pk_setup_opaque` whenever `MBEDTLS_PSA_CRYPTO_CLIENT` is enabled. This is nice-to-have, not critical. Update `use-psa-crypto.md` accordingly.
[OPEN] What about `mbedtls_pk_sign_ext` and `mbedtls_pk_verify_ext`?
diff --git a/docs/architecture/psa-migration/psa-limitations.md b/docs/architecture/psa-migration/psa-limitations.md
index 29d7c53..75814f7 100644
--- a/docs/architecture/psa-migration/psa-limitations.md
+++ b/docs/architecture/psa-migration/psa-limitations.md
@@ -21,11 +21,11 @@
- <https://github.com/Mbed-TLS/mbedtls/issues/7293>;
- <https://github.com/Mbed-TLS/mbedtls/issues/7294>.
-Currently, when `MBEDTLS_USE_PSA_CRYPTO` and `MBEDTLS_ECP_RESTARTABLE` are
-both enabled, some operations that should be restartable are not (ECDH in TLS
-1.2 clients using ECDHE-ECDSA), as they are using PSA instead, and some
-operations that should use PSA do not (signature generation & verification) as
-they use the legacy API instead, in order to get restartable behaviour.
+Currently, when `MBEDTLS_ECP_RESTARTABLE` is enabled, some operations that
+should be restartable are not (ECDH in TLS 1.2 clients using ECDHE-ECDSA), as
+they are using PSA instead, and some operations that should use PSA do not
+(signature generation & verification) as they use the legacy API instead, in
+order to get restartable behaviour.
Things that are in the API but not implemented yet
--------------------------------------------------
diff --git a/docs/architecture/psa-migration/syms.sh b/docs/architecture/psa-migration/syms.sh
index 6c9686e..0fc55dd 100755
--- a/docs/architecture/psa-migration/syms.sh
+++ b/docs/architecture/psa-migration/syms.sh
@@ -11,7 +11,7 @@
#
# Usage:
# - build the library with debug symbols and the config you're interested in
-# (default, full minus MBEDTLS_USE_PSA_CRYPTO, full, etc.)
+# (default, full, etc.)
# - launch this script with 1 or more arguments depending on the analysis' goal:
# - if only 1 argument is used (which is the name of the used config,
# ex: full), then the analysis is done on libmbedx509 and libmbedtls
diff --git a/docs/architecture/tls13-support.md b/docs/architecture/tls13-support.md
index 6904c50..52669fd 100644
--- a/docs/architecture/tls13-support.md
+++ b/docs/architecture/tls13-support.md
@@ -126,7 +126,6 @@
| MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED | n/a |
| | |
| MBEDTLS_PSA_CRYPTO_C | no (1) |
- | MBEDTLS_USE_PSA_CRYPTO | yes |
(1) These options must remain in their default state of enabled.
(2) See the TLS 1.3 specific build options section below.
diff --git a/docs/proposed/config-split.md b/docs/proposed/config-split.md
index 6fd8c49..409141a 100644
--- a/docs/proposed/config-split.md
+++ b/docs/proposed/config-split.md
@@ -290,7 +290,6 @@
//#define MBEDTLS_SHA512_SMALLER
//#define MBEDTLS_SHA512_USE_A64_CRYPTO_IF_PRESENT
//#define MBEDTLS_SHA512_USE_A64_CRYPTO_ONLY
-//#define MBEDTLS_USE_PSA_CRYPTO
//#define MBEDTLS_ECP_FIXED_POINT_OPTIM 1
//#define MBEDTLS_ECP_WINDOW_SIZE 4
diff --git a/docs/psa-transition.md b/docs/psa-transition.md
index 2d7ad15..51ac028 100644
--- a/docs/psa-transition.md
+++ b/docs/psa-transition.md
@@ -50,8 +50,6 @@
To make the PSA API available, make sure that the configuration option [`MBEDTLS_PSA_CRYPTO_C`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/mbedtls__config_8h/#c.MBEDTLS_PSA_CRYPTO_C) is enabled. (It is enabled in the default configuration.)
-You should probably enable [`MBEDTLS_USE_PSA_CRYPTO`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/mbedtls__config_8h/#mbedtls__config_8h_1a70fd7b97d5f11170546583f2095942a6) as well (it is disabled by default). This option causes the PK, X.509 and TLS modules to use PSA crypto under the hood.
-
By default, the PSA crypto API offers a similar set of cryptographic mechanisms as those offered by the legacy API (configured by `MBEDTLS_XXX` macros). The PSA crypto API also has its own configuration mechanism; see “[Cryptographic mechanism availability](#cryptographic-mechanism-availability)”.
### Header files
@@ -908,7 +906,7 @@
* [`mbedtls_pk_copy_from_psa`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/pk_8h/#pk_8h_1ab8e88836fd9ee344ffe630c40447bd08) copies a PSA key into a PK object. The PSA key must be exportable. The PK object remains valid even if the PSA key is destroyed.
* [`mbedtls_pk_copy_public_from_psa`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/pk_8h/#pk_8h_1a2a50247a528889c12ea0ddddb8b15a4e) copies the public part of a PSA key into a PK object. The PK object remains valid even if the PSA key is destroyed.
-* [`mbedtls_pk_setup_opaque`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/pk_8h/#pk_8h_1a4c04ac22ab9c1ae09cc29438c308bf05) sets up a PK object that wraps the PSA key. This functionality is only available when `MBEDTLS_USE_PSA_CRYPTO` is enabled. The PK object has the type `MBEDTLS_PK_OPAQUE` regardless of whether the key is an RSA or ECC key. The PK object can only be used as permitted by the PSA key's policy. The PK object contains a reference to the PSA key identifier, therefore PSA key must not be destroyed as long as the PK object remains alive.
+* [`mbedtls_pk_setup_opaque`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/pk_8h/#pk_8h_1a4c04ac22ab9c1ae09cc29438c308bf05) sets up a PK object that wraps the PSA key. The PK object has the type `MBEDTLS_PK_OPAQUE` regardless of whether the key is an RSA or ECC key. The PK object can only be used as permitted by the PSA key's policy. The PK object contains a reference to the PSA key identifier, therefore PSA key must not be destroyed as long as the PK object remains alive.
Here is some sample code illustrating how to use the PK module to format a PSA public key or the public key of a PSA key pair.
```