docs/use-psa-crypto.md

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.

Current effects
===============

General limitations
-------------------

Compile-time: enabling `MBEDTLS_USE_PSA_CRYPTO` requires
`MBEDTLS_ECP_RESTARTABLE` and
`MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER` to be disabled.

Effect: `MBEDTLS_USE_PSA_CRYPTO` currently has no effect on TLS 1.3 (which is
itself experimental and only partially supported so far): TLS 1.3 always uses
the legacy APIs even when this option is set.

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.

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
operations and its public part can be exported.

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
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()`.

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;
- `mbedtls_x509write_csr_set_key()` to generate a CSR (certificate signature
  request).

In the TLS and X.509 API, there are two other functions which accept a key or
keypair as a PK context: `mbedtls_x509write_crt_set_subject_key()` and
`mbedtls_x509write_crt_set_issuer_key()`. Use of opaque contexts here probably
works but is so far untested.

### PSA-held (opaque) keys for TLS 1.2 pre-shared keys (PSK)

There are two 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.

Limitations: the key can only be used with with TLS 1.2, and only 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`.

Use in TLS: opt-in. The application needs to register the key using 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).

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).

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.

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

See "PSA-based operations in the Cipher layer" above.

### PK layer: ECDSA verification based on PSA

Scope: `mbedtls_pk_verify()` will call to PSA for ECDSA signature
verification.

Benefits: use of PSA Crypto drivers.

Use in TLS and X.509: in all places where an ECDSA signature is verified.

### TLS: ECDHE computation based on PSA

Scope: Client-side, for ECDHE-RSA and ECDHE-ECDSA key exchanges, the
computation of the ECDHE key exchange is done by PSA.

Limitations: client-side only, ECDHE-PSK not covered

Benefits: use of PSA Crypto drivers.

### TLS: handshake hashes and PRF computed with PSA

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.

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