Skip to content

Commit e6ae3d5

Browse files
authored
Merge pull request #4485 from esl/rel-6.3
Release MongooseIM 6.3.2
2 parents 73c6e8e + 83fe738 commit e6ae3d5

15 files changed

+258
-92
lines changed

CHANGELOG.md

+51
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,54 @@
1+
# [MongooseIM 6.3.2](https://github.com/esl/MongooseIM/releases/tag/6.3.2) - 2025-02-24
2+
3+
## Highlights
4+
- Added support for XEP-0484: **Fast Authentication Streamlining Tokens**
5+
- Upgraded to **exml 4.1.1**
6+
- Deprecated `fast_tls`
7+
- Improved `just_tls` with distinct client and server options
8+
- Various enhancements and bug fixes
9+
10+
## Added
11+
- Distinction between client and server options for `just_tls` (#4456)
12+
- XEP-0484: "Fast Authentication Streamlining Tokens" implementation (#4379)
13+
14+
## Changed
15+
- Updated exml to 4.1.1 (#4465, #4471, #4473)
16+
- Update dependencies: `erl_cloud` and `base16` (#4469)
17+
- Deprecated `fast_tls` for C2S (#4468)
18+
- Behavior of PEP discovery to closely match the XEP specification (#4475)
19+
- Migrated GraphiQL to V3 (#4474)
20+
- Translations are now a service (#4481)
21+
- Cleaned up empty GraphQL queries (#4482)
22+
- Updated `elvis.config` to exclude modules that do not match linter standards (#4483)
23+
24+
## Fixed
25+
- Description of log handler migration (#4454)
26+
- Compilation warnings (#4462)
27+
- Certificates generations for CockroarchDB (#4466)
28+
- `probe_failed` error (#4440)
29+
- Wrong namespace when removing IQ handlers in `mod_sic` (#4484)
30+
- SCRAM hashing issue by upgrading `fast_scram` library (#4491)
31+
32+
## Other
33+
- Documentation improvements (#4476, #4487, #4488)
34+
- CI improvements (#4459)
35+
36+
## Known issues
37+
- If you are using MongooseIM 4.1.0 to 6.3.1 with SCRAM authentication and OpenSSL >=3.4.1, hashes for algorithms stronger than SHA-1 are calculated incorrectly.
38+
This issue is fixed in this release. See [SCRAM hashing issue](/doc/developers-guide/SCRAM-serialization.md#scram-hash-calculation-issue-in-mongooseim-410631) for details and required actions.
39+
40+
## Commits, merged PRs and closed issues
41+
- [List of merged PRs](https://github.com/esl/MongooseIM/pulls?q=is%3Apr+is%3Amerged+milestone%3A6.3.2)
42+
43+
- [List of closed issues](https://github.com/esl/MongooseIM/issues?q=is%3Aissue+is%3Aclosed+closed%3A2024-12-30..2025-02-24)
44+
45+
- [Repository history for this release](https://github.com/esl/MongooseIM/graphs/contributors?from=2024-12-30&to=2025-02-24&type=c)
46+
47+
- [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)
48+
49+
## Special thanks to our contributors
50+
- [@xvnds](https://github.com/xvnds) Migrated graphiql to v3 (#4474)
51+
152
# [MongooseIM 6.3.1](https://github.com/esl/MongooseIM/releases/tag/6.3.1) - 2024-12-30
253

354
## Highlights

README.md

+5-4
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
# MongooseIM platform
22

33
[![GitHub release](https://img.shields.io/github/release/esl/MongooseIM.svg)](https://github.com/esl/MongooseIM/releases)
4-
[![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)
5-
[![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)
6-
[![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)
7-
[![Coveralls](https://coveralls.io/repos/github/esl/MongooseIM/badge.svg?branch=rel-6.2)](https://coveralls.io/github/esl/MongooseIM?branch=rel-6.2)
4+
[![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)
5+
[![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)
6+
[![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)
7+
[![Coveralls](https://coveralls.io/repos/github/esl/MongooseIM/badge.svg?branch=rel-6.3)](https://coveralls.io/github/esl/MongooseIM?branch=rel-6.3)
88

99
* [Getting started](https://esl.github.io/MongooseDocs/latest/getting-started/Installation/)
1010
* [Developer's guide](https://esl.github.io/MongooseDocs/latest/developers-guide/Testing-MongooseIM/)
@@ -63,6 +63,7 @@ Check out our test results:
6363
See the documentation for the latest releases:
6464

6565
* [Master](https://esl.github.io/MongooseDocs/latest/)
66+
* [6.3.2](https://esl.github.io/MongooseDocs/6.3.2/)
6667
* [6.3.1](https://esl.github.io/MongooseDocs/6.3.1/)
6768
* [6.3.0](https://esl.github.io/MongooseDocs/6.3.0/)
6869
* [6.2.1](https://esl.github.io/MongooseDocs/6.2.1/)

VERSION

+1-1
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
6.3.1
1+
6.3.2

doc/History.md

+9
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,14 @@
11
# MongooseIM history
22

3+
## 2025: Fast Authentication, TLS Improvements
4+
5+
Added support for XEP-0484 (Fast Authentication Streamlining Tokens).
6+
Deprecated `fast_tls` and improved `just_tls`.
7+
8+
Releases:
9+
10+
* [MongooseIM 6.3.2](https://github.com/esl/MongooseIM/releases/tag/6.3.2) in February 2025.
11+
312
## 2023-2024: C2S, CETS and Instrumentation
413

514
Created an alternative to Mnesia RAM-only tables - CETS.

doc/authentication-methods/http.md

+4
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,10 @@ It is transparent when MongooseIM is responsible for all DB operations such as p
4444
The service CAN perform the (de)serialization of SCRAM-encoded passwords.
4545
You can find more details on the [SCRAM serialization](../developers-guide/SCRAM-serialization.md) page.
4646

47+
!!! Warning
48+
If you are using MongooseIM 4.1.0 to 6.3.1 with SCRAM authentication and OpenSSL >=3.4.1, a known issue affects hash calculation for algorithms stronger than SHA-1.
49+
See [SCRAM hashing issue](../developers-guide/SCRAM-serialization.md#scram-hash-calculation-issue-in-mongooseim-410631) for details on how to resolve this.
50+
4751
## Authentication service API
4852

4953
### URL format

doc/configuration/auth.md

+4
Original file line numberDiff line numberDiff line change
@@ -111,6 +111,10 @@ The older XMPP clients can still use the `PLAIN` mechanism even if the format is
111111

112112
For these options to take effect, `password.format` should be set to `scram`.
113113

114+
!!! Warning
115+
If you are using MongooseIM 4.1.0 to 6.3.1 with SCRAM authentication and OpenSSL >=3.4.1, a known issue affects hash calculation for algorithms stronger than SHA-1.
116+
See [SCRAM hashing issue](../developers-guide/SCRAM-serialization.md#scram-hash-calculation-issue-in-mongooseim-410631) for details on how to resolve this.
117+
114118
### `auth.password.hash`
115119
* **Syntax:** list of strings, allowed values: `"sha"`, `"sha224"`, `"sha256"`, `"sha384"`, `"sha512"`
116120
* **Default:** not set - all hash functions supported

doc/developers-guide/SCRAM-serialization.md

+7
Original file line numberDiff line numberDiff line change
@@ -84,3 +84,10 @@ In order to learn more about the meaning of the Stored Key, Server Key, Salt and
8484
* *Serialized password:* `==SCRAM==,tmi5IE+9pceRV/jkPLFHEaVY33c=,MiWNa8T3dniVDwmh77ufJ41fpAQ=,inKXODlSY5y5SCsLxibi0w==,4096`
8585

8686
[the SCRAM specification]: https://tools.ietf.org/html/rfc5802
87+
88+
## Known issues
89+
### SCRAM hash calculation issue in MongooseIM 4.1.0–6.3.1
90+
91+
If you are using MongooseIM 4.1.0 to 6.3.1 with SCRAM authentication and have OpenSSL >=3.4.1 installed, hashes for algorithms stronger than SHA-1 are calculated incorrectly.
92+
To fix this issue, you must upgrade to MongooseIM 6.3.2, which includes `fast_pbkdf2` version 2.0 with the bug fixed or downgrade OpenSSL to a version lower than 3.4.1.
93+
After applying one of these fixes, all affected users must reset their passwords, as the previously stored hashes are incorrect.

doc/index.md

+5-4
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
# MongooseIM Documentation
22

33
[![GitHub release](https://img.shields.io/github/release/esl/MongooseIM.svg)](https://github.com/esl/MongooseIM/releases)
4-
[![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)
5-
[![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)
6-
[![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)
7-
[![Coveralls](https://coveralls.io/repos/github/esl/MongooseIM/badge.svg?branch=rel-6.2)](https://coveralls.io/github/esl/MongooseIM?branch=rel-6.2)
4+
[![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)
5+
[![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)
6+
[![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)
7+
[![Coveralls](https://coveralls.io/repos/github/esl/MongooseIM/badge.svg?branch=rel-6.3)](https://coveralls.io/github/esl/MongooseIM?branch=rel-6.3)
88

99
* Home: [https://github.com/esl/MongooseIM](https://github.com/esl/MongooseIM)
1010
* 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:
8080
See the documentation for the latest releases:
8181

8282
* [Master](https://esl.github.io/MongooseDocs/latest/)
83+
* [6.3.2](https://esl.github.io/MongooseDocs/6.3.2/)
8384
* [6.3.1](https://esl.github.io/MongooseDocs/6.3.1/)
8485
* [6.3.0](https://esl.github.io/MongooseDocs/6.3.0/)
8586
* [6.2.1](https://esl.github.io/MongooseDocs/6.2.1/)

doc/migrations/6.3.1_6.3.2.md

+95
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
## Change of the default TLS library used for C2S connections
2+
3+
As of this release, usage of `fast_tls` for Client to Server connections (C2S) has been deprecated.
4+
`fast_tls` will be removed in a future release.
5+
6+
From now on the default TLS library for C2S is `just_tls`, which uses TLS implementation from Erlang OTP.
7+
In our load tests, `just_tls` is as performant as `fast_tls` and also has better standards compliance.
8+
This deprecation affects only C2S, and `fast_tls` remains as the TLS implementation for S2S.
9+
10+
To continue using `fast_tls` for C2S in existing deployment after upgrade, make sure the
11+
option [`tls.module`](../listeners/listen-c2s.md#listenc2stlsmodule) is set to `fast_tls` for each of your C2S listeners.
12+
13+
If you leave `tls.module` unset, the TLS module will change from `fast_tls` to `just_tls` after the upgrade.
14+
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.
15+
With `just_tls`, you need to use different options, e.g. [`tls.versions`](../listeners/listen-c2s.md#listenc2stlsversions-only-for-just_tls).
16+
17+
### Channel binding for TLS
18+
19+
Note that `just_tls` currently does not implement `channel binding` for TLS, which is required for SCRAM_PLUS
20+
authentication methods. If you depend on using SCRAM_PLUS for authentication, you need to use `fast_tls`.
21+
We do plan to implement `channel binding` for `just_tls` (only for TLS 1.3) in the future.
22+
23+
### TLS handshake
24+
25+
There is a difference between `fast_tls` and `just_tls` in client authentication behaviour during TLS handshake:
26+
27+
* `fast_tls` doesn't verify the client certificate during TLS handshake and relies on other mechanisms, like SASL, to authenticate the client.
28+
* `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
29+
`just_tls`: `verify_mode` set to `peer` and `disconnect_on_failure` set to `true`.
30+
31+
If you want to have the same behaviour for `just_tls` as it was in `fast_tls` regarding TLS handshake,
32+
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).
33+
It is also possible to completely disable client certificate verification during TLS
34+
handshake in `just_tls` by setting [`tls.verify_mode`](../listeners/listen-c2s.md#listenc2stlsverify_mode) to `none`.
35+
36+
For more information regarding configuration of TLS for C2S, see [C2S listener options](../listeners/listen-c2s.md#tls-options-for-c2s).
37+
38+
## `exml` upgraded to 4.1.1
39+
40+
`exml` library used for parsing and encoding of XML messages was upgraded to version 4.1.1.
41+
In this new version, internal representation of XML elements has changed - element attributes are stored in a map (previously in a key-value list).
42+
43+
### Impact on the upgrade procedure
44+
45+
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.
46+
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.
47+
There are following alternatives:
48+
49+
1. One solution is to stop the whole MongooseIM cluster, upgrade and start again.
50+
51+
2. The second solution is to configure a new cluster running new version
52+
alongside the old cluster, and migrate traffic from the old one to the new one.
53+
54+
3. There is a third solution, which allows to maintain service availability but not requiring building a full new cluster.
55+
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.
56+
That way all nodes are migrated one by one to the newly formed cluster. Both clusters have to access the same database.
57+
If you are using CETS, you can form a new cluster by changing [`internal_databases.cluster_name`](../configuration/internal-databases.md#internal_databasescetscluster_name).
58+
59+
### Archived XML - `mod_mam`
60+
61+
The change of XML element representation could affect messages archived by `mod_mam`.
62+
63+
!!! question "Is my server affected?"
64+
65+
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.
66+
67+
* Messages stored in the XML textual format (`mam_message_xml`) are **not** affected.
68+
* Messages stored in the Erlang term format (`mam_message_compressed_eterm` or `mam_message_eterm`) are affected.
69+
70+
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.
71+
However, a nonupgraded node would fail to read messages stored in the new format.
72+
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.
73+
To limit such issues, we recommend the upgrade to be undertaken during the time of minimal traffic.
74+
75+
!!! info "What errors to expect?"
76+
When a client connected to a nonupgraded node requests a message stored in the new format, you can expect:
77+
78+
* A warning log with `what=process_iq_error` on the MongooseIM node.
79+
* An `internal-server-error` IQ stanza returned to the client.
80+
81+
Such issues would be transient during the upgrade, but if you attempt a rollback, they would persist until you upgrade again.
82+
83+
## Database migration
84+
85+
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.
86+
87+
## Translations moved to a service
88+
89+
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/).
90+
91+
### SCRAM hashing fix
92+
93+
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.
94+
This release includes a fix for this issue. If you were affected, all users must reset their passwords after upgrading to ensure correct authentication.
95+
For more details, see [SCRAM hashing issue](../developers-guide/SCRAM-serialization.md#scram-hash-calculation-issue-in-mongooseim-410631).

0 commit comments

Comments
 (0)