Skip to content

6.3.1 to 6.3.2

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, and fast_tls remains as the 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 for each of your C2S listeners.

If you leave tls.module unset, the TLS module will change from fast_tls to just_tls after the upgrade. One consequence is that the tls.protocol_options option, which you might have used, will be no longer valid. With just_tls, you need to use different options, e.g. tls.versions.

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 the client certificate during TLS handshake and relies on other mechanisms, like SASL, to authenticate the client.
  • just_tls by default verifies the client certificate during TLS handshake and aborts connection when the certificate is invalid. This is realised by the default settings in just_tls: 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 EXTERNAL. 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 C2S listener options.

exml upgraded to 4.1.1

exml library used for parsing and encoding of XML messages was upgraded to version 4.1.1. In this new version, internal representation of XML elements has changed - element attributes are stored in a map (previously in a key-value list).

Impact on the upgrade procedure

Parsed XML messages are being sent within MongooseIM cluster between Erlang nodes in internal representation, so to understand received messages (Erlang terms), all nodes must have the same code that handles XML elements. This makes a rolling upgrade not viable for this release, as it would lead to multiple errors in the logs and clients being disconnected abruptly. There are following alternatives:

  1. One solution is to stop the whole MongooseIM cluster, upgrade and start again.

  2. The second solution is to configure a new cluster running new version alongside the old cluster, and migrate traffic from the old one to the new one.

  3. There is a third solution, which allows to maintain service availability but not requiring building a full new cluster. In this solution, you upgrade nodes one by one (like in the rolling upgrade), but change configuration to not allow the upgraded node to rejoin the old cluster, but instead run as a new cluster. That way all nodes are migrated one by one to the newly formed cluster. Both clusters have to access the same database. If you are using CETS, you can form a new cluster by changing internal_databases.cluster_name.

Archived XML - mod_mam

The change of XML element representation could affect messages archived by mod_mam.

Is my server affected?

There is a config setting modules.mod_mam.db_message_format, which controls the message format for archived messages, and its default is different depending on the database backend used.

  • Messages stored in the XML textual format (mam_message_xml) are not affected.
  • Messages stored in the Erlang term format (mam_message_compressed_eterm or mam_message_eterm) are affected.

For messages stored as Erlang terms, we provide transparent retrieval of the old format, while new messages will be written in the archive in the new format. However, a nonupgraded node would fail to read messages stored in the new format. This is not an issue unless you upgrade using method 2 or 3 from the list above (keeping two clusters running simultaneously), or you perform a rollback. To limit such issues, we recommend the upgrade to be undertaken during the time of minimal traffic.

What errors to expect?

When a client connected to a nonupgraded node requests a message stored in the new format, you can expect:

  • A warning log with what=process_iq_error on the MongooseIM node.
  • An internal-server-error IQ stanza returned to the client.

Such issues would be transient during the upgrade, but if you attempt a rollback, they would persist until you upgrade again.

Database migration

Migration scripts for CockroachDB, PostgreSQL, MySQL, and MS SQL are available in the priv/migrations directory. These migrations introduce the fast_auth_token table, which is required for XEP-0484: Fast Authentication Streamlining Tokens to function properly.

Translations moved to a service

System message translations are now handled by service_translations. Translations files can be found in priv/translations/.

SCRAM hashing fix

In versions 6.3.1 and earlier, a bug caused incorrect hash calculations for SCRAM authentication when using algorithms stronger than SHA-1 with OpenSSL >=3.4.1. This release includes a fix for this issue. If you were affected, all users must reset their passwords after upgrading to ensure correct authentication. For more details, see SCRAM hashing issue.