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.
33
34The `prefer-post-quantum` crate feature makes `X25519MLKEM768` the
35highest-priority key exchange algorithm. Otherwise, it is available but
36not highest-priority.
37
38[X25519MLKEM768] is pre-standardization, but is now widely deployed,
39for example, by [Chrome] and [Cloudflare].
40
41You may see unexpected connection failures (such as [tldr.fail])
42-- [please report these to us][interop-bug].
43
44The two components of this key exchange are well regarded:
45X25519 alone is already used by default by rustls, and tends to have
46higher quality implementations than other elliptic curves.
47ML-KEM-768 was standardized by NIST in [FIPS203].
48
49[`MLKEM768`] is available separately, but is not currently enabled
50by default out of conservatism.
51
52[^1]: meaning: a construction that runs a classical and post-quantum
53 key exchange, and uses the output of both together. This is a hedge
54 against the post-quantum half being broken.
55
56[^2]: a "post-quantum-secure" algorithm is one posited to be invulnerable
57 to attack using a cryptographically-relevant quantum computer. In contrast,
58 classical algorithms would be broken by such a computer. Note that such computers
59 do not currently exist, and may never exist, but current traffic could be captured
60 now and attacked later.
61
62[X25519MLKEM768]: <https://datatracker.ietf.org/doc/draft-ietf-tls-ecdhe-mlkem/>
63[`X25519MLKEM768`]: crate::crypto::aws_lc_rs::kx_group::X25519MLKEM768
64[`MLKEM768`]: crate::crypto::aws_lc_rs::kx_group::MLKEM768
65[FIPS203]: <https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.203.pdf>
66[Chrome]: <https://security.googleblog.com/2024/09/a-new-path-for-kyber-on-web.html>
67[Cloudflare]: <https://blog.cloudflare.com/pq-2024/#ml-kem-768-and-x25519>
68[interop-bug]: <https://github.com/rustls/rustls/issues/new?assignees=&labels=&projects=&template=bug_report.md&title=>
69[tldr.fail]: <https://tldr.fail/>
70
71*/
72