Lines Matching +full:all +full:- +full:apis

1 This document describes the compile-time configuration option
9 -------------------
11 Compile-time: enabling `MBEDTLS_USE_PSA_CRYPTO` requires
20 time. Said otherwise, these APIs are explicitly excluded from the usual API
23 New APIs / API extensions
24 -------------------------
26 Some of these APIs are meant for the application to use in place of
27 pre-existing APIs, in order to get access to the benefits; in the sub-sections
28 below these are indicated by "Use in (X.509 and) TLS: opt-in", meaning that
32 Some of these APIs are mostly meant for internal use by the TLS (and X.509)
37 ### PSA-held (opaque) keys in the PK layer
40 wrap a PSA keypair into a PK context. The key can be used for private-key
43 Benefits: isolation of long-term secrets, use of PSA Crypto drivers.
52 Use in X.509 and TLS: opt-in. The application needs to construct the PK context
54 resulting context to the following existing APIs:
56 - `mbedtls_ssl_conf_own_cert()` or `mbedtls_ssl_set_hs_own_cert()` to use the
57   key together with a certificate for ECDSA-based key exchanges (note: while
58 this is supported on both sides, it's currently only tested client-side);
59 - `mbedtls_x509write_csr_set_key()` to generate a CSR (certificate signature
67 ### PSA-held (opaque) keys for TLS pre-shared keys (PSK)
73 Benefits: isolation of long-term secrets.
77 exclusion of RSA-PSK, DHE-PSK and ECDHE-PSK key exchanges. It is the responsibility of
78 the user to make sure that when provisioning an opaque pre-shared key, the
79 only PSK ciphersuites that can be negotiated are "pure" PSK; other XXX-PSK key
83 Use in TLS: opt-in. The application needs to register the key using the new
84 APIs to get the benefits.
86 ### PSA-based operations in the Cipher layer
91 Benefits: use of PSA Crypto drivers; partial isolation of short-term secrets
95 multi-part APIs are not supported, only the one-shot APIs. The only modes
99 possible to perform multiple one-shot operations with the same context;
100 however this is not unit-tested, only tested via usage in TLS.)
103 gracious fallback to the legacy API otherwise) in all places where a cipher is
108 ----------------
110 All of these internal changes are active as soon as `MBEDTLS_USE_PSA_CRYPTO`
115 See "PSA-based operations in the Cipher layer" above.
124 Use in TLS and X.509: in all places where an ECDSA signature is verified.
128 Scope: Client-side, for ECDHE-RSA and ECDHE-ECDSA key exchanges, the
131 Limitations: client-side only, ECDHE-PSK not covered
138 - the running handshake hashes;
139 - the hash of the ServerKeyExchange part that is signed;
140 - the `verify_data` part of the Finished message;
141 - the TLS PRF.
148 - when verifying a certificate chain, hash of the child for verifying the
150 - when writing a CSR, hash of the request for self-signing the request.
157 This is only a high-level overview, grouped by theme
160 --------------------------------------
162 The following key exchanges are not covered at all:
164 - RSA
165 - DHE-RSA
166 - DHE-PSK
167 - RSA-PSK
168 - ECDHE-PSK
169 - ECDH-RSA
170 - ECDH-ECDSA
171 - ECJPAKE
175 - ECDHE-RSA: RSA operations are not covered and, server-side, the ECDHE
177 - ECDHE-ECDSA: server-side, the ECDHE operation isn't covered. (ECDSA
184 ---------------------
186 - some ciphers not supported via PSA yet: ARIA, Camellia, ChachaPoly (silent
187   fallback to the legacy APIs)
188 - the HMAC part of the CBC and NULL ciphersuites
189 - the HMAC computation in `ssl_cookie.c`
192 -----
194 - most hash operations are still done via the legacy API, except the few that
196 - RSA PKCS#1 v1.5 signature generation (from PSA-held keys)
197 - RSA PKCS#1 v1.5 signature verification
198 - RSA-PSS signature verification