1This document lists current limitations of the PSA Crypto API (as of version 21.1) that may impact our ability to (1) use it for all crypto operations in 3TLS and X.509 and (2) support isolation of all long-term secrets in TLS (that 4is, goals G1 and G2 in [strategy.md](strategy.md) in the same directory). 5 6This is supposed to be a complete list, based on a exhaustive review of crypto 7operations done in TLS and X.509 code, but of course it's still possible that 8subtle-but-important issues have been missed. The only way to be really sure 9is, of course, to actually do the migration work. 10 11Limitations relevant for G1 (performing crypto operations) 12========================================================== 13 14Restartable (aka interruptible) ECC operations 15---------------------------------------------- 16 17Support for interruptible ECDSA sign/verify was added to PSA in Mbed TLS 3.4. 18However, support for interruptible ECDH is not present yet. Also, PK, X.509 and 19TLS have not yet been adapted to take advantage of the new PSA APIs. See: 20- <https://github.com/Mbed-TLS/mbedtls/issues/7292>; 21- <https://github.com/Mbed-TLS/mbedtls/issues/7293>; 22- <https://github.com/Mbed-TLS/mbedtls/issues/7294>. 23 24Currently, when `MBEDTLS_USE_PSA_CRYPTO` and `MBEDTLS_ECP_RESTARTABLE` are 25both enabled, some operations that should be restartable are not (ECDH in TLS 261.2 clients using ECDHE-ECDSA), as they are using PSA instead, and some 27operations that should use PSA do not (signature generation & verification) as 28they use the legacy API instead, in order to get restartable behaviour. 29 30Things that are in the API but not implemented yet 31-------------------------------------------------- 32 33PSA Crypto has an API for FFDH, but it's not implemented in Mbed TLS yet. 34(Regarding FFDH, see the next section as well.) See issue [3261][ffdh] on 35github. 36 37[ffdh]: https://github.com/Mbed-TLS/mbedtls/issues/3261 38 39Arbitrary parameters for FFDH 40----------------------------- 41 42(See also the first paragraph in the previous section.) 43 44Currently, the PSA Crypto API can only perform FFDH with a limited set of 45well-known parameters (some of them defined in the spec, but implementations 46are free to extend that set). 47 48TLS 1.2 (and earlier) on the other hand have the server send explicit 49parameters (P and G) in its ServerKeyExchange message. This has been found to 50be suboptimal for security, as it is prohibitively hard for the client to 51verify the strength of these parameters. This led to the development of RFC 527919 which allows use of named groups in TLS 1.2 - however as this is only an 53extension, servers can still send custom parameters if they don't support the 54extension. 55 56In TLS 1.3 the situation will be simpler: named groups are the only 57option, so the current PSA Crypto API is a good match for that. (Not 58coincidentally, all the groups used by RFC 7919 and TLS 1.3 are included 59in the PSA specification.) 60 61There are several options here: 62 631. Implement support for custom FFDH parameters in PSA Crypto: this would pose 64 non-trivial API design problem, but most importantly seems backwards, as 65the crypto community is moving away from custom FFDH parameters. (Could be 66done any time.) 672. Drop the DHE-RSA and DHE-PSK key exchanges in TLS 1.2 when moving to PSA. 68 (For people who want some algorithmic variety in case ECC collapses, FFDH 69would still be available in TLS 1.3, just not in 1.2.) (Can only be done in 704.0 or another major version.) 713. Variant of the precedent: only drop client-side support. Server-side is 72 easy to support in terms of API/protocol, as the server picks the 73parameters: we just need remove the existing `mbedtls_ssl_conf_dh_param_xxx()` 74APIs and tell people to use `mbedtls_ssl_conf_groups()` instead. (Can only be 75done in 4.0 or another major version.) 764. Implement RFC 7919, support DHE-RSA and DHE-PSK only in conjunction with it 77 when moving to PSA. Server-side would work as above; unfortunately 78client-side the only option is to offer named groups and break the handshake 79if the server didn't take on our offer. This is not fully satisfying, but is 80perhaps the least unsatisfying option in terms of result; it's also probably 81the one that requires the most work, but it would deliver value beyond PSA 82migration by implementing RFC 7919. (Implementing RFC 7919 could be done any 83time; making it mandatory can only be done in 4.0 or another major version.) 84 85As of early 2023, the plan is to go with option 2 in Mbed TLS 4.0, which has 86been announced on the mailing-list and got no push-back, see 87<https://github.com/Mbed-TLS/mbedtls/issues/5278>. 88 89RSA-PSS parameters 90------------------ 91 92RSA-PSS signatures are defined by PKCS#1 v2, re-published as RFC 8017 93(previously RFC 3447). 94 95As standardized, the signature scheme takes several parameters, in addition to 96the hash algorithm potentially used to hash the message being signed: 97- a hash algorithm used for the encoding function 98- a mask generation function 99 - most commonly MGF1, which in turn is parametrized by a hash algorithm 100- a salt length 101- a trailer field - the value is fixed to 0xBC by PKCS#1 v2.1, but was left 102 configurable in the original scheme; 0xBC is used everywhere in practice. 103 104Both the existing `mbedtls_` API and the PSA API support only MGF1 as the 105generation function (and only 0xBC as the trailer field), but there are 106discrepancies in handling the salt length and which of the various hash 107algorithms can differ from each other. 108 109### API comparison 110 111- RSA: 112 - signature: `mbedtls_rsa_rsassa_pss_sign()` 113 - message hashed externally 114 - encoding hash = MGF1 hash (from context, or argument = message hash) 115 - salt length: always using the maximum legal value 116 - signature: `mbedtls_rsa_rsassa_pss_sign_ext()` 117 - message hashed externally 118 - encoding hash = MGF1 hash (from context, or argument = message hash) 119 - salt length: specified explicitly 120 - verification: `mbedtls_rsassa_pss_verify()` 121 - message hashed externally 122 - encoding hash = MGF1 hash (from context, or argument = message hash) 123 - salt length: any valid length accepted 124 - verification: `mbedtls_rsassa_pss_verify_ext()` 125 - message hashed externally 126 - encoding hash = MGF1 hash from dedicated argument 127 - expected salt length: specified explicitly, can specify "ANY" 128- PK: 129 - signature: not supported 130 - verification: `mbedtls_pk_verify_ext()` 131 - message hashed externally 132 - encoding hash = MGF1 hash, specified explicitly 133 - expected salt length: specified explicitly, can specify "ANY" 134- PSA: 135 - algorithm specification: 136 - hash alg used for message hashing, encoding and MGF1 137 - salt length can be either "standard" (<= hashlen, see note) or "any" 138 - signature generation: 139 - salt length: always <= hashlen (see note) and random salt 140 - verification: 141 - salt length: either <= hashlen (see note), or any depending on algorithm 142 143Note: above, "<= hashlen" means that hashlen is used if possible, but if it 144doesn't fit because the key is too short, then the maximum length that fits is 145used. 146 147The RSA/PK API is in principle more flexible than the PSA Crypto API. The 148following sub-sections study whether and how this matters in practice. 149 150### Use in X.509 151 152RFC 4055 Section 3.1 defines the encoding of RSA-PSS that's used in X.509. 153It allows independently specifying the message hash (also used for encoding 154hash), the MGF (and its hash if MGF1 is used), and the salt length (plus an 155extra parameter "trailer field" that doesn't vary in practice"). These can be 156encoded as part of the key, and of the signature. If both encoding are 157presents, all values must match except possibly for the salt length, where the 158value from the signature parameters is used. 159 160In Mbed TLS, RSA-PSS parameters can be parsed and displayed for various 161objects (certificates, CRLs, CSRs). During parsing, the following properties 162are enforced: 163- the extra "trailer field" parameter must have its default value 164- the mask generation function is MGF1 165- encoding hash = message hashing algorithm (may differ from MGF1 hash) 166 167When it comes to cryptographic operations, only two things are supported: 168- verifying the signature on a certificate from its parent; 169- verifying the signature on a CRL from the issuing CA. 170 171The verification is done using `mbedtls_pk_verify_ext()`. 172 173Note: since X.509 parsing ensures that message hash = encoding hash, and 174`mbedtls_pk_verify_ext()` uses encoding hash = mgf1 hash, it looks like all 175three hash algorithms must be equal, which would be good news as it would 176match a limitation of the PSA API. 177 178It is unclear what parameters people use in practice. It looks like by default 179OpenSSL picks saltlen = keylen - hashlen - 2 (tested with openssl 1.1.1f). 180The `certtool` command provided by GnuTLS seems to be picking saltlen = hashlen 181by default (tested with GnuTLS 3.6.13). FIPS 186-4 requires 0 <= saltlen <= 182hashlen. 183 184### Use in TLS 185 186In TLS 1.2 (or lower), RSA-PSS signatures are never used, except via X.509. 187 188In TLS 1.3, RSA-PSS signatures can be used directly in the protocol (in 189addition to indirect use via X.509). It has two sets of three signature 190algorithm identifiers (for SHA-256, SHA-384 and SHA-512), depending of what 191the OID of the public key is (rsaEncryption or RSASSA-PSS). 192 193In both cases, it specifies that: 194- the mask generation function is MGF1 195- all three hashes are equal 196- the length of the salt MUST be equal to the length of the digest algorithm 197 198When signing, the salt length picked by PSA is the one required by TLS 1.3 199(unless the key is unreasonably small). 200 201When verifying signatures, PSA will by default enforce the salt len is the one 202required by TLS 1.3. 203 204### Current testing - X509 205 206All test files use the default trailer field of 0xBC, as enforced by our 207parser. (There's a negative test for that using the 208`x509_parse_rsassa_pss_params` test function and hex data.) 209 210Files with "bad" in the name are expected to be invalid and rejected in tests. 211 212**Test certificates:** 213 214server9-bad-mgfhash.crt (announcing mgf1(sha224), signed with another mgf) 215 Hash Algorithm: sha256 216 Mask Algorithm: mgf1 with sha224 217 Salt Length: 0xDE 218server9-bad-saltlen.crt (announcing saltlen = 0xDE, signed with another len) 219 Hash Algorithm: sha256 220 Mask Algorithm: mgf1 with sha256 221 Salt Length: 0xDE 222server9-badsign.crt (one bit flipped in the signature) 223 Hash Algorithm: sha1 (default) 224 Mask Algorithm: mgf1 with sha1 (default) 225 Salt Length: 0xEA 226server9-defaults.crt 227 Hash Algorithm: sha1 (default) 228 Mask Algorithm: mgf1 with sha1 (default) 229 Salt Length: 0x14 (default) 230server9-sha224.crt 231 Hash Algorithm: sha224 232 Mask Algorithm: mgf1 with sha224 233 Salt Length: 0xE2 234server9-sha256.crt 235 Hash Algorithm: sha256 236 Mask Algorithm: mgf1 with sha256 237 Salt Length: 0xDE 238server9-sha384.crt 239 Hash Algorithm: sha384 240 Mask Algorithm: mgf1 with sha384 241 Salt Length: 0xCE 242server9-sha512.crt 243 Hash Algorithm: sha512 244 Mask Algorithm: mgf1 with sha512 245 Salt Length: 0xBE 246server9-with-ca.crt 247 Hash Algorithm: sha1 (default) 248 Mask Algorithm: mgf1 with sha1 (default) 249 Salt Length: 0xEA 250server9.crt 251 Hash Algorithm: sha1 (default) 252 Mask Algorithm: mgf1 with sha1 (default) 253 Salt Length: 0xEA 254 255These certificates are signed with a 2048-bit key. It appears that they are 256all using saltlen = keylen - hashlen - 2, except for server9-defaults which is 257using saltlen = hashlen. 258 259**Test CRLs:** 260 261crl-rsa-pss-sha1-badsign.pem 262 Hash Algorithm: sha1 (default) 263 Mask Algorithm: mgf1 with sha1 (default) 264 Salt Length: 0xEA 265crl-rsa-pss-sha1.pem 266 Hash Algorithm: sha1 (default) 267 Mask Algorithm: mgf1 with sha1 (default) 268 Salt Length: 0xEA 269crl-rsa-pss-sha224.pem 270 Hash Algorithm: sha224 271 Mask Algorithm: mgf1 with sha224 272 Salt Length: 0xE2 273crl-rsa-pss-sha256.pem 274 Hash Algorithm: sha256 275 Mask Algorithm: mgf1 with sha256 276 Salt Length: 0xDE 277crl-rsa-pss-sha384.pem 278 Hash Algorithm: sha384 279 Mask Algorithm: mgf1 with sha384 280 Salt Length: 0xCE 281crl-rsa-pss-sha512.pem 282 Hash Algorithm: sha512 283 Mask Algorithm: mgf1 with sha512 284 Salt Length: 0xBE 285 286These CRLs are signed with a 2048-bit key. It appears that they are 287all using saltlen = keylen - hashlen - 2. 288 289**Test CSRs:** 290 291server9.req.sha1 292 Hash Algorithm: sha1 (default) 293 Mask Algorithm: mgf1 with sha1 (default) 294 Salt Length: 0x6A 295server9.req.sha224 296 Hash Algorithm: sha224 297 Mask Algorithm: mgf1 with sha224 298 Salt Length: 0x62 299server9.req.sha256 300 Hash Algorithm: sha256 301 Mask Algorithm: mgf1 with sha256 302 Salt Length: 0x5E 303server9.req.sha384 304 Hash Algorithm: sha384 305 Mask Algorithm: mgf1 with sha384 306 Salt Length: 0x4E 307server9.req.sha512 308 Hash Algorithm: sha512 309 Mask Algorithm: mgf1 with sha512 310 Salt Length: 0x3E 311 312These CSRs are signed with a 2048-bit key. It appears that they are 313all using saltlen = keylen - hashlen - 2. 314 315### Possible courses of action 316 317There's no question about what to do with TLS (any version); the only question 318is about X.509 signature verification. Options include: 319 3201. Doing all verifications with `PSA_ALG_RSA_PSS_ANY_SALT` - while this 321 wouldn't cause a concrete security issue, this would be non-compliant. 3222. Doing verifications with `PSA_ALG_RSA_PSS` when we're lucky and the encoded 323 saltlen happens to match hashlen, and falling back to `ANY_SALT` otherwise. 324Same issue as with the previous point, except more contained. 3253. Reject all certificates with saltlen != hashlen. This includes all 326 certificates generated with OpenSSL using the default parameters, so it's 327probably not acceptable. 3284. Request an extension to the PSA Crypto API and use one of the above options 329 in the meantime. Such an extension seems inconvenient and not motivated by 330strong security arguments, so it's unclear whether it would be accepted. 331 332Since Mbed TLS 3.4, option 1 is implemented. 333 334Limitations relevant for G2 (isolation of long-term secrets) 335============================================================ 336 337Currently none. 338