MIM-2360 Add migration note about fast_tls deprecation

Author: Andrzej Telezynski

doc/listeners/listen-c2s.md

@@ -164,6 +164,16 @@ Password to the X509 PEM file with the private key.
 * **Default:** `true`
 * **Example:** `tls.disconnect_on_failure = false`
 
+This option specifies what happens when client certificate is verified during TLS handshake.
+It therefore only applies when client certificate verification is enabled, that is `tls.verify_mode` is set to `"peer"` or `"selfsigned_peer"`.
+
+When set to `true`, client verification is performed during TLS handshake and in case of error the connection is aborted.
+Additionally empty client certificate is treated as an error.
+
+When set to `false`, TLS handshake will succeed even if there were errors in client certificate verification.
+This allows to use other methods of authentication (like SASL) later as part of XMPP stream.
+The above behaviour is the same as default `fast_tls` behaviour (not aborting TLS connection on verification errors).
+
 ### `listen.c2s.tls.versions` - only for `just_tls`
 * **Syntax:** array of strings
 * **Default:** not set, all supported versions are accepted

doc/migrations/6.3.1_6.x.y.md

@@ -0,0 +1,38 @@
+## Change of the default TLS library used for C2S connections
+
+As of this release, usage of `fast_tls` for Client to Server connections (C2S) has been deprecated.
+`fast_tls` will be removed in a future release.
+
+From now on the default TLS library for C2S is `just_tls`, which uses TLS implementation from Erlang OTP.
+In our load tests `just_tls` is as performant as `fast_tls` and also has better standards compliance.
+
+This deprecation affects only C2S, `fast_tls` remains as a TLS implementation for S2S.
+
+To continue using `fast_tls` for C2S in existing deployment after upgrade, make sure the
+option `tls.module` is set to `fast_tls` in `listen.c2s` section of your MongooseIM config.
+
+### Channel binding for TLS
+
+Note that `just_tls` currently does not implement `channel binding` for TLS, which is required for SCRAM_PLUS
+authentication methods. If you depend on using SCRAM_PLUS for authentication, you need to use `fast_tls`.
+We do plan to implement `channel binding` for `just_tls` (only for TLS 1.3) in the future.
+
+### TLS handshake
+
+There is a difference between `fast_tls` and `just_tls` in client authentication behaviour during TLS handshake.
+
+`fast_tls` doesn't verify client certificate during TLS handshake and relies on other mechanisms, like SASL,
+to authenticate client. It may involve client certificate, but is executed after TLS handshake succeeded,
+and in case of invalid certificate will result in an error reported in message stream.
+
+`just_tls` by default verifies client certificate during TLS handshake
+and aborts connection when client certificate is invalid. This is realised by the default settings in
+`just_tls` of `verify_mode` set to `peer` and `disconnect_on_failure` set to `true`.
+
+If you want to have the same behaviour for `just_tls` as it was in `fast_tls` regarding TLS handshake,
+set `tls.disconnect_on_failure` to `false`. This is required for example when using SASL for client authentication.
+
+It is also possible to completely disable client certificate verification during TLS
+handshake in `just_tls` by setting `tls.verify_mode` to `none`.
+
+For more information regarding configuration of TLS for C2S see [Listener modules](../listeners/listen-c2s/#tls-options-for-c2s)