Misc clean-ups in docs/use-psa-crypto.md

Note: limitations of opaque PSKs changed from "TLS 1.2 only" to "none"
since TLS 1.3 does not support PSK at all so far, and it is expected to
support opaque PSKs as soon as it gains PSK support, it will be just a
matter of selecting between psa_key_derivation_input_bytes() and
psa_key_derivation_input_key() - and testing obviously.

Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>

docs/use-psa-crypto.md

@@ -4,17 +4,17 @@ This document describes the compile-time configuration option
 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
+**Compile-time:** enabling `MBEDTLS_USE_PSA_CRYPTO` requires
 `MBEDTLS_ECP_RESTARTABLE` to be disabled.
 
-Application code: when this option is enabled, you need to call
+**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.
 
-Scope: `MBEDTLS_USE_PSA_CRYPTO` has no effect on the parts of the code that
+**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
@@ -26,42 +26,42 @@ New APIs / API extensions
 
 ### 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: can only wrap a keypair, can only use it for private key
+**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
-`mbedtls_pk_check_pair()`, `mbedtls_pk_debug()`, all public key operations.
+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).
+  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: only TLS 1.2 for now.
+**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
 
@@ -72,8 +72,9 @@ 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.
 
-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.
+**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
 ----------------
@@ -85,8 +86,8 @@ is enabled, no change required on the application side.
 
 Current exceptions:
 
-- EC J-PAKE (when `MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED`)
-- finite-field (non-EC) Diffie-Hellman (use in key exchanges: DHE-RSA,
+- 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)
 
 Other than the above exceptions, all crypto operations are based on PSA when