Skip to content

Commit cd65058

Browse files
authored
faq: add answer for errors when using RusTLS
1 parent dbdedcd commit cd65058

File tree

1 file changed

+27
-0
lines changed

1 file changed

+27
-0
lines changed

FAQ.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,33 @@ and we don't factor MSRV bumps into our semantic versioning.
2525

2626
[`rust-version`]: https://doc.rust-lang.org/stable/cargo/reference/manifest.html#the-rust-version-field
2727

28+
----------------------------------------------------------------
29+
### I'm getting `HandshakeFailure` or `CorruptMessage` when trying to connect to a server over TLS using RusTLS. What gives?
30+
31+
To encourage good security practices and limit cruft, RusTLS does not support older versions of TLS or cryptographic algorithms
32+
that are considered insecure. `HandshakeFailure` is a normal error returned when RusTLS and the server cannot agree on parameters for
33+
a secure connection.
34+
35+
Check the supported TLS versions for the database server version you're running. If it does not support TLS 1.2 or greater, then
36+
you likely will not be able to connect to it with RusTLS.
37+
38+
The obvious solution, of course, is to upgrade your database server to a version that supports at least TLS 1.2.
39+
40+
* MySQL: [has supported TLS 1.2 since 5.6.46](https://dev.mysql.com/doc/refman/5.6/en/encrypted-connection-protocols-ciphers.html#encrypted-connection-supported-protocols).
41+
* PostgreSQL: depends on the system OpenSSL version.
42+
* MSSQL: TLS is not supported yet.
43+
44+
If you're running a third-party database that talks one of these protocols, consult its documentation for supported TLS versions.
45+
46+
If you're stuck on an outdated version, which is unfortunate but tends to happen for one reason or another, try switching to the corresponding
47+
`runtime-<tokio, async-std, actix>-native-tls` feature for SQLx. That will use the system APIs for TLS which tend to have much wider support.
48+
See [the `native-tls` crate docs](https://docs.rs/native-tls/latest/native_tls/) for details.
49+
50+
The `CorruptMessage` error occurs in similar situations and many users have had success with switching to `-native-tls` to get around it.
51+
However, if you do encounter this error, please try to capture a Wireshark or `tcpdump` trace of the TLS handshake as the RusTLS folks are interested
52+
in covering cases that trigger this (as it might indicate a protocol handling bug or the server is doing something non-standard):
53+
https://github.com/rustls/rustls/issues/893
54+
2855
----------------------------------------------------------------
2956
### How can I do a `SELECT ... WHERE foo IN (...)` query?
3057

0 commit comments

Comments
 (0)