rustls/manual/
features.rs

1/*!
2
3The below list reflects the support provided with the default crate features.
4Items marked with an asterisk `*` can be extended or altered via public
5APIs ([`CryptoProvider`] for example).
6
7[`CryptoProvider`]: crate::crypto::CryptoProvider
8
9## Current features
10
11* TLS1.2 and TLS1.3
12* ECDSA, Ed25519 or RSA server authentication by clients `*`
13* ECDSA, Ed25519[^1] or RSA server authentication by servers `*`
14* Forward secrecy using ECDHE; with curve25519, nistp256 or nistp384 curves `*`
15* Post-quantum hybrid key exchange with [X25519MLKEM768](https://datatracker.ietf.org/doc/draft-ietf-tls-ecdhe-mlkem/) [^2] `*`
16* AES128-GCM and AES256-GCM bulk encryption, with safe nonces `*`
17* ChaCha20-Poly1305 bulk encryption ([RFC7905](https://tools.ietf.org/html/rfc7905)) `*`
18* ALPN support
19* SNI support
20* Tunable fragment size to make TLS messages match size of underlying transport
21* Optional use of vectored IO to minimise system calls
22* TLS1.2 session resumption
23* TLS1.2 resumption via tickets ([RFC5077](https://tools.ietf.org/html/rfc5077))
24* TLS1.3 resumption via tickets or session storage
25* TLS1.3 0-RTT data
26* Server and optional client authentication
27* Extended master secret support ([RFC7627](https://tools.ietf.org/html/rfc7627))
28* Exporters ([RFC5705](https://tools.ietf.org/html/rfc5705))
29* OCSP stapling by servers
30* [RFC7250](https://tools.ietf.org/html/rfc7250) raw public keys for TLS1.3
31* [RFC8879](https://tools.ietf.org/html/rfc8879) certificate compression by clients
32  and servers `*`
33* Client-side Encrypted client hello (ECH)
34   ([draft-ietf-tls-esni](https://datatracker.ietf.org/doc/draft-ietf-tls-esni/)).
35
36[^1]: Note that, at the time of writing, Ed25519 does not have wide support
37      in browsers.  It is also not supported by the WebPKI, because the
38      CA/Browser Forum Baseline Requirements do not support it for publicly
39      trusted certificates.
40[^2]: See [the documentation][crate::manual::_05_defaults#about-the-post-quantum-secure-key-exchange-x25519mlkem768]
41
42## Non-features
43
44For reasons explained in the other sections of this manual, rustls does not
45and will not support:
46
47* SSL1, SSL2, SSL3, TLS1 or TLS1.1
48* RC4
49* DES or triple DES
50* EXPORT ciphersuites
51* MAC-then-encrypt ciphersuites
52* Ciphersuites without forward secrecy
53* Renegotiation
54* Kerberos
55* TLS 1.2 protocol compression
56* Discrete-log Diffie-Hellman `*`
57* Automatic protocol version downgrade
58* Using CA certificates directly to authenticate a server/client (often called "self-signed
59  certificates"). _Rustls' default certificate verifier does not support using a trust anchor as
60  both a CA certificate and an end-entity certificate in order to limit complexity and risk in
61  path building. While dangerous, all authentication can be turned off if required --
62  see the [example code](https://github.com/rustls/rustls/blob/v/0.23.23/examples/src/bin/tlsclient-mio.rs#L338)_ `*`
63
64### About "custom extensions"
65
66OpenSSL allows an application to add arbitrary TLS extensions (via
67the `SSL_CTX_add_custom_ext` function and associated APIs).  We don't
68support this, with the following rationale:
69
70Such an API is limited to extensions that are quite narrow in scope:
71they cannot change the meaning of standard messages, or introduce new
72messages, or make any changes to the connection's cryptography.
73
74However, there is no reasonable way to technically limit that API to
75that set of extensions.  That makes the API pretty unsafe (in the
76TLS and cryptography sense, not memory safety sense).  This could
77cause security or interop failures.
78
79Instead, we suggest that potential users of that API consider:
80
81- whether their use can fit in standard extensions such as ALPN,
82  or [ALPS][alps][^3].
83- if not, whether they can fit in a more general extension, and define
84  and standardize that in the [IETF TLSWG][tlswg].
85
86Note the above is not a guarantee or offer that rustls will implement
87any specific extensions that are standardized by the IETF TLSWG.
88It is a non-goal of this project to implement absolutely everything.
89
90For experimentation and pre-standardization testing, we suggest
91forking rustls.
92
93See also: [Go's position on such an API][golang].
94
95[alps]: https://datatracker.ietf.org/doc/html/draft-vvv-tls-alps
96[golang]: https://github.com/golang/go/issues/51497
97[tlswg]: https://datatracker.ietf.org/wg/tls/charter/
98[^3]: rustls does not currently implement ALPS, but it is something we
99  would consider once standardised and deployed.
100*/
rustls/manual/features.rs

rustls/manual/
features.rs
