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