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

rustls/manual/
features.rs
