| 1 | /*! |
| 2 | |
|---|
| 3 | The below list reflects the support provided with the default crate features. |
|---|
| 4 | Items marked with an asterisk `*` can be extended or altered via public |
|---|
| 5 | APIs ([`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 | |
|---|
| 44 | For reasons explained in the other sections of this manual, rustls does not |
|---|
| 45 | and 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 | |
|---|
| 66 | OpenSSL allows an application to add arbitrary TLS extensions (via |
|---|
| 67 | the `SSL_CTX_add_custom_ext` function and associated APIs). We don't |
|---|
| 68 | support this, with the following rationale: |
|---|
| 69 | |
|---|
| 70 | Such an API is limited to extensions that are quite narrow in scope: |
|---|
| 71 | they cannot change the meaning of standard messages, or introduce new |
|---|
| 72 | messages, or make any changes to the connection's cryptography. |
|---|
| 73 | |
|---|
| 74 | However, there is no reasonable way to technically limit that API to |
|---|
| 75 | that set of extensions. That makes the API pretty unsafe (in the |
|---|
| 76 | TLS and cryptography sense, not memory safety sense). This could |
|---|
| 77 | cause security or interop failures. |
|---|
| 78 | |
|---|
| 79 | Instead, 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 | |
|---|
| 86 | Note the above is not a guarantee or offer that rustls will implement |
|---|
| 87 | any specific extensions that are standardized by the IETF TLSWG. |
|---|
| 88 | It is a non-goal of this project to implement absolutely everything. |
|---|
| 89 | |
|---|
| 90 | For experimentation and pre-standardization testing, we suggest |
|---|
| 91 | forking rustls. |
|---|
| 92 | |
|---|
| 93 | See 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 | */ |
|---|
| 101 | |
|---|
