Release MongooseIM 6.3.2

CHANGELOG.md

@@ -1,3 +1,49 @@
+# [MongooseIM 6.3.2](https://github.com/esl/MongooseIM/releases/tag/6.3.2) - 2025-02-14
+
+## Highlights
+- Added support for XEP-0484: **Fast Authentication Streamlining Tokens**
+- Upgraded to **exml 4.1.1**
+- Deprecated `fast_tls`
+- Improved `just_tls` with distinct client and server options
+- Various enhancements and bug fixes
+
+## Added
+- Distinction between client and server options for `just_tls` (#4456)
+- XEP-0484: "Fast Authentication Streamlining Tokens" implementation (#4379)
+
+## Changed
+- Updated exml to 4.1.1 (#4465, #4471, #4473)
+- Update dependencies: `erl_cloud` and `base16` (#4469)
+- Deprecated `fast_tls` for C2S (#4468)
+- Behavior of PEP discovery to closely match the XEP specification (#4475)
+- Migrated GraphiQL to V3 (#4474)
+- Translations are now a service (#4481)
+- Cleaned up empty GraphQL queries (#4482)
+- Updated `elvis.config` to exclude modules that do not match linter standards (#4483)
+
+## Fixed
+- Description of log handler migration (#4454)
+- Compilation warnings (#4462)
+- Certificates generations for CockroarchDB (#4466)
+- `probe_failed` error (#4440)
+- Wrong namespace when removing IQ handlers in `mod_sic` (#4484)
+
+## Other
+- Documentation improvements (#4476)
+- CI improvements (#4459)
+
+## Commits, merged PRs and closed issues
+- [List of merged PRs](https://github.com/esl/MongooseIM/pulls?q=is%3Apr+is%3Amerged+milestone%3A6.3.2)
+
+- [List of closed issues](https://github.com/esl/MongooseIM/issues?q=is%3Aissue+is%3Aclosed+closed%3A2024-12-30..2025-02-14)
+
+- [Repository history for this release](https://github.com/esl/MongooseIM/graphs/contributors?from=2024-12-30&to=2025-02-14&type=c)
+
+- [List of merged PRs based on merge date](https://github.com/esl/MongooseIM/pulls?q=is%3Apr+is%3Amerged+milestone%3A6.3.2+sort%3Aupdated-desc)
+
+## Special thanks to our contributors
+- [@xvnds](https://github.com/xvnds) Migrated graphiql to v3 (#4474)
+
 # [MongooseIM 6.3.1](https://github.com/esl/MongooseIM/releases/tag/6.3.1) - 2024-12-30
 
 ## Highlights

README.md

@@ -1,10 +1,10 @@
 # MongooseIM platform
 
 [![GitHub release](https://img.shields.io/github/release/esl/MongooseIM.svg)](https://github.com/esl/MongooseIM/releases)
-[![CircleCI](https://dl.circleci.com/status-badge/img/gh/esl/MongooseIM/tree/rel-6.2.svg?style=shield)](https://app.circleci.com/pipelines/github/esl/MongooseIM?branch=rel-6.2)
-[![Codecov](https://codecov.io/gh/esl/MongooseIM/branch/rel-6.2/graph/badge.svg)](https://app.codecov.io/gh/esl/MongooseIM/tree/rel-6.2)
-[![GitHub Actions](https://github.com/esl/MongooseIM/actions/workflows/ci.yml/badge.svg?branch=rel-6.2)](https://github.com/esl/MongooseIM/actions/workflows/ci.yml?query=branch%3Arel-6.2)
-[![Coveralls](https://coveralls.io/repos/github/esl/MongooseIM/badge.svg?branch=rel-6.2)](https://coveralls.io/github/esl/MongooseIM?branch=rel-6.2)
+[![CircleCI](https://dl.circleci.com/status-badge/img/gh/esl/MongooseIM/tree/rel-6.3.svg?style=shield)](https://app.circleci.com/pipelines/github/esl/MongooseIM?branch=rel-6.3)
+[![Codecov](https://codecov.io/gh/esl/MongooseIM/branch/rel-6.3/graph/badge.svg)](https://app.codecov.io/gh/esl/MongooseIM/tree/rel-6.3)
+[![GitHub Actions](https://github.com/esl/MongooseIM/actions/workflows/ci.yml/badge.svg?branch=rel-6.3)](https://github.com/esl/MongooseIM/actions/workflows/ci.yml?query=branch%3Arel-6.3)
+[![Coveralls](https://coveralls.io/repos/github/esl/MongooseIM/badge.svg?branch=rel-6.3)](https://coveralls.io/github/esl/MongooseIM?branch=rel-6.3)
 
 * [Getting started](https://esl.github.io/MongooseDocs/latest/getting-started/Installation/)
 * [Developer's guide](https://esl.github.io/MongooseDocs/latest/developers-guide/Testing-MongooseIM/)
@@ -63,6 +63,7 @@ Check out our test results:
 See the documentation for the latest releases:
 
 * [Master](https://esl.github.io/MongooseDocs/latest/)
+* [6.3.2](https://esl.github.io/MongooseDocs/6.3.2/)
 * [6.3.1](https://esl.github.io/MongooseDocs/6.3.1/)
 * [6.3.0](https://esl.github.io/MongooseDocs/6.3.0/)
 * [6.2.1](https://esl.github.io/MongooseDocs/6.2.1/)

VERSION

@@ -1 +1 @@
-6.3.1
+6.3.2

doc/History.md

@@ -1,5 +1,14 @@
 # MongooseIM history
 
+## 2025: Fast Authentication, TLS Improvements
+
+Added support for XEP-0484 (Fast Authentication Streamlining Tokens).
+Deprecated `fast_tls` and improved `just_tls`.
+
+Releases:
+
+* [MongooseIM 6.3.2](https://github.com/esl/MongooseIM/releases/tag/6.3.2) in February 2025.
+
 ## 2023-2024: C2S, CETS and Instrumentation
 
 Created an alternative to Mnesia RAM-only tables - CETS.

doc/index.md

@@ -1,10 +1,10 @@
 # MongooseIM Documentation
 
 [![GitHub release](https://img.shields.io/github/release/esl/MongooseIM.svg)](https://github.com/esl/MongooseIM/releases)
-[![CircleCI](https://dl.circleci.com/status-badge/img/gh/esl/MongooseIM/tree/rel-6.2.svg?style=shield)](https://app.circleci.com/pipelines/github/esl/MongooseIM?branch=rel-6.2)
-[![Codecov](https://codecov.io/gh/esl/MongooseIM/branch/rel-6.2/graph/badge.svg)](https://app.codecov.io/gh/esl/MongooseIM/tree/rel-6.2)
-[![GitHub Actions](https://github.com/esl/MongooseIM/actions/workflows/ci.yml/badge.svg?branch=rel-6.2)](https://github.com/esl/MongooseIM/actions/workflows/ci.yml?query=branch%3Arel-6.2)
-[![Coveralls](https://coveralls.io/repos/github/esl/MongooseIM/badge.svg?branch=rel-6.2)](https://coveralls.io/github/esl/MongooseIM?branch=rel-6.2)
+[![CircleCI](https://dl.circleci.com/status-badge/img/gh/esl/MongooseIM/tree/rel-6.3.svg?style=shield)](https://app.circleci.com/pipelines/github/esl/MongooseIM?branch=rel-6.3)
+[![Codecov](https://codecov.io/gh/esl/MongooseIM/branch/rel-6.3/graph/badge.svg)](https://app.codecov.io/gh/esl/MongooseIM/tree/rel-6.3)
+[![GitHub Actions](https://github.com/esl/MongooseIM/actions/workflows/ci.yml/badge.svg?branch=rel-6.3)](https://github.com/esl/MongooseIM/actions/workflows/ci.yml?query=branch%3Arel-6.3)
+[![Coveralls](https://coveralls.io/repos/github/esl/MongooseIM/badge.svg?branch=rel-6.3)](https://coveralls.io/github/esl/MongooseIM?branch=rel-6.3)
 
 * Home: [https://github.com/esl/MongooseIM](https://github.com/esl/MongooseIM)
 * Product page: [https://www.erlang-solutions.com/products/mongooseim.html](https://www.erlang-solutions.com/products/mongooseim.html)
@@ -80,6 +80,7 @@ Check out our test results:
 See the documentation for the latest releases:
 
 * [Master](https://esl.github.io/MongooseDocs/latest/)
+* [6.3.2](https://esl.github.io/MongooseDocs/6.3.2/)
 * [6.3.1](https://esl.github.io/MongooseDocs/6.3.1/)
 * [6.3.0](https://esl.github.io/MongooseDocs/6.3.0/)
 * [6.2.1](https://esl.github.io/MongooseDocs/6.2.1/)

doc/migrations/6.3.1_6.3.2.md

@@ -0,0 +1,89 @@
+## 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`](../listeners/listen-c2s.md#listenc2stlsmodule) 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`](../listeners/listen-c2s.md#listenc2stlsprotocol_options-only-for-fast_tls) option, which you might have used, will be no longer valid.
+With `just_tls`, you need to use different options, e.g. [`tls.versions`](../listeners/listen-c2s.md#listenc2stlsversions-only-for-just_tls).
+
+### 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`](../listeners/listen-c2s.md#listenc2stlsdisconnect_on_failure-only-for-just_tls) to `false`. This is required for example when using [SASL EXTERNAL](../tutorials/client-certificate.md#enable-sasl-external-mechanism).
+It is also possible to completely disable client certificate verification during TLS
+handshake in `just_tls` by setting [`tls.verify_mode`](../listeners/listen-c2s.md#listenc2stlsverify_mode) to `none`.
+
+For more information regarding configuration of TLS for C2S, see [C2S listener options](../listeners/listen-c2s.md#tls-options-for-c2s).
+
+## `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](../operation-and-maintenance/Rolling-upgrade.md) 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`](../configuration/internal-databases.md#internal_databasescetscluster_name).
+
+### Archived XML - `mod_mam`
+
+The change of XML element representation could affect messages archived by `mod_mam`.
+
+!!! question "Is my server affected?"
+
+    There is a config setting [`modules.mod_mam.db_message_format`](../modules/mod_mam.md#modulesmod_mamdb_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.
+
+!!! info "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`](https://github.com/esl/MongooseIM/tree/master/priv/migrations) directory. These migrations introduce the **`fast_auth_token`** table, which is required for [**XEP-0484: Fast Authentication Streamlining Tokens**](../modules/mod_fast_auth_token.md) to function properly.
+
+## Translations moved to a service
+
+System message translations are now handled by [`service_translations`](../configuration/Services.md#service_translations). Translations files can be found in [`priv/translations/`](https://github.com/esl/MongooseIM/tree/master/priv/translations/).

mkdocs.yml

@@ -216,6 +216,7 @@ nav:
       - '6.2.0 to 6.2.1': 'migrations/6.2.0_6.2.1.md'
       - '6.2.1 to 6.3.0': 'migrations/6.2.1_6.3.0.md'
       - '6.3.0 to 6.3.1': 'migrations/6.3.0_6.3.1.md'
+      - '6.3.1 to 6.3.2': 'migrations/6.3.1_6.3.2.md'
       - 'MAM MUC migration helper': 'migrations/jid-from-mam-muc-script.md'
   - 'Contributions to the Ecosystem': 'Contributions.md'
   - 'MongooseIM History': 'History.md'

priv/migrations/cockroachdb_6.3.1_6.3.2.sql

@@ -0,0 +1,19 @@
+-- XEP-0484: Fast Authentication Streamlining Tokens
+-- Module: mod_fast_auth_token
+CREATE TABLE fast_auth_token(
+     server VARCHAR(250) NOT NULL,
+     username VARCHAR(250) NOT NULL,
+     -- Device installation ID (User-Agent ID)
+     -- Unique for each device
+     -- https://xmpp.org/extensions/xep-0388.html#initiation
+     user_agent_id VARCHAR(250) NOT NULL,
+     current_token VARCHAR(250),
+     current_expire BIGINT, -- seconds unix timestamp
+     current_count INT, -- replay counter
+     current_mech_id smallint,
+     new_token VARCHAR(250),
+     new_expire BIGINT, -- seconds unix timestamp
+     new_count INT,
+     new_mech_id smallint,
+     PRIMARY KEY(server, username, user_agent_id)
+);