rustls/manual/
features.rs

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

rustls/manual/
features.rs
