rustls/manual/
defaults.rs

1/*!
2
3## Rationale for defaults
4
5### Why is AES-256 preferred over AES-128?
6
7This is a trade-off between:
8
91. classical security level: searching a 2^128 key space is as implausible as 2^256.
102. post-quantum security level: the difference is more meaningful, and AES-256 seems like the conservative choice.
113. performance: AES-256 is around 40% slower than AES-128, though hardware acceleration typically narrows this gap.
12
13The choice is frankly quite marginal.
14
15### Why is AES-GCM preferred over chacha20-poly1305?
16
17Hardware support for accelerating AES-GCM is widespread, and hardware-accelerated AES-GCM
18is quicker than un-accelerated chacha20-poly1305.
19
20However, if you know your application will run on a platform without that, you should
21_definitely_ change the default order to prefer chacha20-poly1305: both the performance and
22the implementation security will be improved.  We think this is an uncommon case.
23
24### Why is x25519 preferred for key exchange over nistp256?
25
26Both provide roughly the same classical security level, but x25519 has better performance and
27it's _much_ more likely that both peers will have good quality implementations.
28
29### About the post-quantum-secure key exchange `X25519MLKEM768`
30
31[`X25519MLKEM768`] -- a hybrid[^1], post-quantum-secure[^2] key exchange
32algorithm -- is available when using the aws-lc-rs provider, set as the highest-priority key
33exchange algorithm by default.
34
35[X25519MLKEM768] is pre-standardization, but is now widely deployed,
36for example, by [Chrome] and [Cloudflare].
37
38You may see unexpected connection failures (such as [tldr.fail])
39-- [please report these to us][interop-bug].
40
41The two components of this key exchange are well regarded:
42X25519 alone is already used by default by rustls, and tends to have
43higher quality implementations than other elliptic curves.
44ML-KEM-768 was standardized by NIST in [FIPS203].
45
46[`MLKEM768`] is available separately, but is not currently enabled
47by default out of conservatism.
48
49[^1]: meaning: a construction that runs a classical and post-quantum
50      key exchange, and uses the output of both together.  This is a hedge
51      against the post-quantum half being broken.
52
53[^2]: a "post-quantum-secure" algorithm is one posited to be invulnerable
54      to attack using a cryptographically-relevant quantum computer.  In contrast,
55      classical algorithms would be broken by such a computer.  Note that such computers
56      do not currently exist, and may never exist, but current traffic could be captured
57      now and attacked later.
58
59[X25519MLKEM768]: <https://datatracker.ietf.org/doc/draft-ietf-tls-ecdhe-mlkem/>
60[`X25519MLKEM768`]: crate::crypto::aws_lc_rs::kx_group::X25519MLKEM768
61[`MLKEM768`]: crate::crypto::aws_lc_rs::kx_group::MLKEM768
62[FIPS203]: <https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.203.pdf>
63[Chrome]: <https://security.googleblog.com/2024/09/a-new-path-for-kyber-on-web.html>
64[Cloudflare]: <https://blog.cloudflare.com/pq-2024/#ml-kem-768-and-x25519>
65[interop-bug]: <https://github.com/rustls/rustls/issues/new?assignees=&labels=&projects=&template=bug_report.md&title=>
66[tldr.fail]: <https://web.archive.org/web/tldr.fail/>
67
68*/
rustls/manual/defaults.rs

rustls/manual/
defaults.rs
