Update docs/use-psa-crypto.md
The scope of the option has been expanded, now it makes more sense to describe it as "everything except ...". Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>
This commit is contained in:
Manuel Pégourié-Gonnard
Manuel Pégourié-Gonnard
parent
ff43ff6e78
commit
b2bd34ecdc
1 changed files with 32 additions and 120 deletions
|
|
@ -1,9 +1,5 @@
|
|||
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
|
||||
===============
|
||||
`MBEDTLS_USE_PSA_CRYPTO` from a user's perspective.
|
||||
|
||||
General limitations
|
||||
-------------------
|
||||
|
|
@ -20,17 +16,6 @@ is currently just the record protection code).
|
|||
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
|
||||
|
|
@ -39,12 +24,12 @@ 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
|
||||
Limitations: can only wrap a keypair, 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()`.
|
||||
`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
|
||||
using the new API in order to get the benefits; it can then pass the
|
||||
|
|
@ -55,10 +40,7 @@ resulting context to the following existing APIs:
|
|||
this is supported on both sides, it's currently only tested client-side);
|
||||
- `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.
|
||||
- `mbedtls_x509write_crt_set_issuer_key()` to generate a certificate.
|
||||
|
||||
### PSA-held (opaque) keys for TLS pre-shared keys (PSK)
|
||||
|
||||
|
|
@ -68,13 +50,7 @@ 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 "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: only TLS 1.2 for now.
|
||||
|
||||
Use in TLS: opt-in. The application needs to register the key using the new
|
||||
APIs to get the benefits.
|
||||
|
|
@ -84,21 +60,12 @@ APIs to get the benefits.
|
|||
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.
|
||||
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
|
||||
----------------
|
||||
|
|
@ -106,89 +73,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`)
|
||||
- finite-field (non-EC) Diffie-Hellman (use 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
|
||||
|
|
|
|||
Loading…
Reference in a new issue