diff --git a/CHANGELOG.md b/CHANGELOG.md index 163d5e3afa4..99d14b23f99 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index 37c6903b0da..6c35e028b90 100644 --- a/README.md +++ b/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/) diff --git a/VERSION b/VERSION index dc0208aba8e..91e4a9f2622 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -6.3.1 +6.3.2 diff --git a/doc/History.md b/doc/History.md index 08346ad93db..a4f34329c9d 100644 --- a/doc/History.md +++ b/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. diff --git a/doc/index.md b/doc/index.md index 06214e27a7b..3ea9f542195 100644 --- a/doc/index.md +++ b/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/) diff --git a/doc/migrations/6.3.1_6.3.2.md b/doc/migrations/6.3.1_6.3.2.md new file mode 100644 index 00000000000..6366f4e5f89 --- /dev/null +++ b/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/). diff --git a/doc/migrations/6.3.1_6.x.y.md b/doc/migrations/6.3.1_6.x.y.md deleted file mode 100644 index 26a2e59c89e..00000000000 --- a/doc/migrations/6.3.1_6.x.y.md +++ /dev/null @@ -1,83 +0,0 @@ -## 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) - -## `exml` upgraded to 4.0 - -### Change of internal format of XML messages affects the ways to upgrade MongooseIM cluster - -`exml` library used for parsing and emitting of XML messages was upgraded to version 4.0. -In this new version internal representation of XML elements changed - element attributes -are stored in a map (previously in a key value list). - -This is a disruptive change, and rollback to previous version is not possible. - -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 handle XML elements. This makes a rolling upgrade -(an upgrade of a cluster node by node) not viable for this release. - -One solution is to stop the whole MongooseIM cluster, upgrade and start again. - -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. - -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 -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 access the same database. - -One warning regarding this solution: There is a corner case regarding access to archived messages only while both clusters -are operating simultaneously. It may happen that users still connected to the old cluster try to retrieve newly archived messages. -This will result in errors and possibly crashes as the old code doesn't recognise new internal representation. -We just want to warn the operator about such possibility, the chance of it happening is slight, as we recommend the upgrade -to be undertaken during the time of minimal traffic. - -### Archived XML - mod_mam - -Change of XML element representation also affects stored or archived messages, if they are stored in the internal Erlang term format. - -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. -The default for RDBMS databases is `mam_message_compressed_eterm` (which is Erlang term format) while for Cassandra it is `mam_message_xml`. - -Messages stored in XML textual format (`mam_message_xml`) are not affected by `exml` version change. - -For messages stored as Erlang term (`mam_message_compressed_eterm` or `mam_message_eterm`), we provide transparent retrieval of the old format, while new messages will be written in the archive in -the new format. This means that the change of the format is transparent in operations of MongooseIM. -However if you have external tools accessing message archive, you may need to verify that they work correctly with the new internal XML element representation. - diff --git a/mkdocs.yml b/mkdocs.yml index c125abf834b..91797bf3d77 100644 --- a/mkdocs.yml +++ b/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' diff --git a/priv/migrations/cockroachdb_6.3.1_6.3.2.sql b/priv/migrations/cockroachdb_6.3.1_6.3.2.sql new file mode 100644 index 00000000000..8b7f0a03ea0 --- /dev/null +++ b/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) +); diff --git a/priv/migrations/mssql_6.3.1_6.3.2.sql b/priv/migrations/mssql_6.3.1_6.3.2.sql new file mode 100644 index 00000000000..2cb354ec740 --- /dev/null +++ b/priv/migrations/mssql_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 TINYINT, + new_token VARCHAR(250), + new_expire BIGINT, -- seconds unix timestamp + new_count INT, + new_mech_id TINYINT, + PRIMARY KEY(server, username, user_agent_id) +); diff --git a/priv/migrations/mysql_6.3.1_6.3.2.sql b/priv/migrations/mysql_6.3.1_6.3.2.sql new file mode 100644 index 00000000000..4cb46d24e2c --- /dev/null +++ b/priv/migrations/mysql_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 TINYINT UNSIGNED, + new_token VARCHAR(250), + new_expire BIGINT, -- seconds unix timestamp + new_count INT, + new_mech_id TINYINT UNSIGNED, + PRIMARY KEY(server, username, user_agent_id) +); diff --git a/priv/migrations/pgsql_6.3.1_6.3.2.sql b/priv/migrations/pgsql_6.3.1_6.3.2.sql new file mode 100644 index 00000000000..8b7f0a03ea0 --- /dev/null +++ b/priv/migrations/pgsql_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) +);