portable_rustls/manual/
features.rs

1/*!
2
3<!-- TODO: MAKE THIS STATEMENT MORE SPECIFIC FOR THIS FORK -->
4The below list reflects the support provided with _existing_ crate features.
5Items marked with an asterisk `*` can be extended or altered via public
6APIs ([`CryptoProvider`] for example).
7
8[`CryptoProvider`]: crate::crypto::CryptoProvider
9
10## Current features
11
12* TLS1.2 and TLS1.3
13* ECDSA, Ed25519 or RSA server authentication by clients `*`
14* ECDSA, Ed25519[^1] or RSA server authentication by servers `*`
15* Forward secrecy using ECDHE; with curve25519, nistp256 or nistp384 curves `*`
16* Post-quantum hybrid key exchange with [X25519MLKEM768](https://datatracker.ietf.org/doc/draft-kwiatkowski-tls-ecdhe-mlkem/) [^2] `*`
17* AES128-GCM and AES256-GCM bulk encryption, with safe nonces `*`
18* ChaCha20-Poly1305 bulk encryption ([RFC7905](https://tools.ietf.org/html/rfc7905)) `*`
19* ALPN support
20* SNI support
21* Tunable fragment size to make TLS messages match size of underlying transport
22* Optional use of vectored IO to minimise system calls
23* TLS1.2 session resumption
24* TLS1.2 resumption via tickets ([RFC5077](https://tools.ietf.org/html/rfc5077))
25* TLS1.3 resumption via tickets or session storage
26* TLS1.3 0-RTT data
27* Server and optional client authentication
28* Extended master secret support ([RFC7627](https://tools.ietf.org/html/rfc7627))
29* Exporters ([RFC5705](https://tools.ietf.org/html/rfc5705))
30* OCSP stapling by servers
31* [RFC7250](https://tools.ietf.org/html/rfc7250) raw public keys for TLS1.3
32* [RFC8879](https://tools.ietf.org/html/rfc8879) certificate compression by clients
33  and servers `*`
34* Client-side Encrypted client hello (ECH)
35   ([draft-ietf-tls-esni](https://datatracker.ietf.org/doc/draft-ietf-tls-esni/)).
36
37[^1]: Note that, at the time of writing, Ed25519 does not have wide support
38      in browsers.  It is also not supported by the WebPKI, because the
39      CA/Browser Forum Baseline Requirements do not support it for publicly
40      trusted certificates.
41[^2]: See [the documentation][crate::manual::_05_defaults#about-the-post-quantum-secure-key-exchange-x25519mlkem768]
42
43## Non-features
44
45<!-- UPDATED FOR THIS FORK:
46For reasons explained in the other sections of this manual, rustls does not
47and will not support:
48- -->
49__Coming from upstream `rustls`, none of the following are supported by this fork:__
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/brody4hire/portable-rustls/blob/portable-rustls-0.0.1/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
94<!-- HIDING THIS STATEMENT IN THIS THIS FORK
95For experimentation and pre-standardization testing, we suggest
96forking rustls.
97- END HIDING THIS STATEMENT IN THIS THIS FORK -->
98
99<!-- HIDING GOLANG POSITION IN THIS FORK
100See also: [Go's position on such an API][golang].
101- END HIDING GOLANG POSITION IN THIS FORK -->
102
103[alps]: https://datatracker.ietf.org/doc/html/draft-vvv-tls-alps
104<!-- HIDING GOLANG POSITION IN THIS FORK
105[golang]: https://github.com/golang/go/issues/51497
106- END HIDING GOLANG POSITION IN THIS FORK -->
107[tlswg]: https://datatracker.ietf.org/wg/tls/charter/
108[^3]: rustls does not currently implement ALPS, but it is something we
109  would consider once standardised and deployed.
110*/
portable_rustls/manual/features.rs

portable_rustls/manual/
features.rs
