@@ -25,6 +25,33 @@ and we don't factor MSRV bumps into our semantic versioning.
25
25
26
26
[ `rust-version` ] : https://doc.rust-lang.org/stable/cargo/reference/manifest.html#the-rust-version-field
27
27
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
+
28
55
----------------------------------------------------------------
29
56
### How can I do a ` SELECT ... WHERE foo IN (...) ` query?
30
57
0 commit comments