Merge pull request #4495 from esl/update-openssl-related-docs

chrzaszcz · web-flow · commit ca654aef5a25 · 2025-02-28T15:21:17.000+01:00
Update OpenSSL related docs
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -33,9 +33,10 @@
 - Documentation improvements (#4476, #4487, #4488)
 - CI improvements (#4459)
 
-## Known issues
+## Known issues and upgrade recommendations
 - 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.
 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.
+- OpenSSL versions below 3.0 are no longer supported. If you are using OpenSSL 1.x or older, you must upgrade to OpenSSL 3.x before updating MongooseIM, as older versions will not work.
 
 ## 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)
diff --git a/doc/configuration/outgoing-connections.md b/doc/configuration/outgoing-connections.md
@@ -414,7 +414,7 @@ Password to the X509 PEM file with the private key.
 * **Default:** not set, all supported cipher suites are accepted
 * **Example:** `tls.ciphers = "ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384"`
 
-Cipher suites to use. Please refer to the [OpenSSL documentation](http://www.openssl.org/docs/man1.0.2/apps/ciphers.html) for the cipher string format. For allowed values, see the [Erlang/OTP SSL documentation](https://erlang.org/doc/man/ssl.html#type-ciphers).
+Cipher suites to use. Please refer to the [OpenSSL documentation](https://docs.openssl.org/master/man1/openssl-ciphers/) for the cipher string format. For allowed values, see the [Erlang/OTP SSL documentation](https://erlang.org/doc/man/ssl.html#type-ciphers).
 
 ### `outgoing_pools.*.*.connection.tls.versions`
 * **Syntax:** list of strings
diff --git a/doc/configuration/s2s.md b/doc/configuration/s2s.md
@@ -84,7 +84,7 @@ This option defines IP addresses and port numbers for specific non-local XMPP do
 * **Example:** `ciphers = "TLSv1.2"`
 
 Defines a list of accepted SSL ciphers for outgoing S2S connections.
-Please refer to the [OpenSSL documentation](http://www.openssl.org/docs/apps/ciphers.html) for the cipher string format.
+Please refer to the [OpenSSL documentation](https://docs.openssl.org/master/man1/openssl-ciphers/) for the cipher string format.
 
 ### `s2s.max_retry_delay`
 * **Syntax:** positive integer
diff --git a/doc/listeners/listen-c2s.md b/doc/listeners/listen-c2s.md
@@ -136,7 +136,7 @@ Path to the Diffie-Hellman parameter file.
 * **Default:** for `fast_tls` the default is`"TLSv1.2:TLSv1.3"`. For `just_tls` this option is not set by default - all supported suites are accepted.
 * **Example:** `tls.ciphers = "ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384"`
 
-Cipher suites to use with StartTLS or TLS. Please refer to the [OpenSSL documentation](http://www.openssl.org/docs/man1.0.2/apps/ciphers.html) for the cipher string format. For `fast_tls`, this string can be used to specify versions as well. For `just_tls`, see the [Erlang/OTP SSL documentation](https://erlang.org/doc/man/ssl.html#type-ciphers) for allowed values.
+Cipher suites to use with StartTLS or TLS. Please refer to the [OpenSSL documentation](https://docs.openssl.org/master/man1/openssl-ciphers/) for the cipher string format. For `fast_tls`, this string can be used to specify versions as well. For `just_tls`, see the [Erlang/OTP SSL documentation](https://erlang.org/doc/man/ssl.html#type-ciphers) for allowed values.
 
 ### `listen.c2s.tls.protocol_options` - only for `fast_tls`
 * **Syntax:** array of strings
diff --git a/doc/migrations/6.3.1_6.3.2.md b/doc/migrations/6.3.1_6.3.2.md
@@ -88,8 +88,11 @@ Migration scripts for CockroachDB, PostgreSQL, MySQL, and MS SQL are available i
 
 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/).
 
-### SCRAM hashing fix
+## 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](../developers-guide/SCRAM-serialization.md#scram-hash-calculation-issue-in-mongooseim-410631).
+
+## OpenSSL <3.0 no longer supported
+All OpenSSL versions below 3.0 are no longer supported. If your deployment relies on OpenSSL 1.x or older, you must upgrade to OpenSSL 3.x before updating MongooseIM, as older versions will not work.
diff --git a/doc/modules/mod_global_distrib.md b/doc/modules/mod_global_distrib.md
@@ -235,7 +235,7 @@ These options will be passed to the `fast_tls` driver.
 * **Default:** `"TLSv1.2:TLSv1.3"`
 * **Example:** `ciphers = "ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384"`
 
-Cipher suites to use with StartTLS or TLS. Please refer to the [OpenSSL documentation](https://www.openssl.org/docs/man1.0.2/man1/ciphers.html) for the cipher string format.
+Cipher suites to use with StartTLS or TLS. Please refer to the [OpenSSL documentation](https://docs.openssl.org/master/man1/openssl-ciphers/) for the cipher string format.
 
 #### `modules.mod_global_distrib.connections.tls.dhfile`
 * **Syntax:** string, path in the file system
diff --git a/doc/tutorials/How-to-build.md b/doc/tutorials/How-to-build.md
@@ -20,7 +20,7 @@ To compile MongooseIM you need:
       *   Erlang/OTP 26.0 or higher:
         * `erlang` EPEL package, or,
         * install using [kerl](https://github.com/kerl/kerl),
-      *   OpenSSL 0.9.8 or higher, for STARTTLS, SASL and SSL encryption: `openssl` and `openssl-devel`,
+      *   OpenSSL 3.0.2 or higher, for STARTTLS, SASL and SSL encryption: `openssl` and `openssl-devel`,
       *   ODBC library: `unixODBC-devel`,
       *   Zlib 1.2.3 or higher: `zlib-devel`.
 
@@ -31,7 +31,7 @@ To compile MongooseIM you need:
       *   Erlang/OTP 24.0 or higher:
         * `erlang` package, or,
         * install using [kerl](https://github.com/kerl/kerl),
-      *   OpenSSL 0.9.8 or higher, for STARTTLS, SASL and SSL encryption: `olibssl-dev`,
+      *   OpenSSL 3.0.2 or higher, for STARTTLS, SASL and SSL encryption: `olibssl-dev`,
       *   ODBC library: `unixodbc-dev`,
       *   Zlib 1.2.3 or higher: `zlib1g-dev`.
 
@@ -41,9 +41,14 @@ To compile MongooseIM you need:
       *   Erlang/OTP 24.0 or higher:
         * [`erlang`](https://formulae.brew.sh/formula/erlang) from Homebrew,
         * install using [kerl](https://github.com/kerl/kerl),
-      *   OpenSSL 0.9.8 or higher, for STARTTLS, SASL and SSL encryption: [`openssl`](https://formulae.brew.sh/formula/openssl@1.1) from Homebrew
+      *   OpenSSL 3.0.2 or higher, for STARTTLS, SASL and SSL encryption: [`openssl`](https://formulae.brew.sh/formula/openssl@3.0) from Homebrew
       *   ODBC library: [`unixodbc`](https://formulae.brew.sh/formula/unixodbc) from Homebrew.
 
+### OpenSSL Version Compatibility
+
+- MongooseIM 6.3.2+ requires OpenSSL 3.0 or newer to compile.
+- MongooseIM 6.3.1 and earlier support OpenSSL <3.0 but may have issues with SCRAM authentication when using OpenSSL 3.4.1+. See the [SCRAM hashing issue](../developers-guide/SCRAM-serialization.md#scram-hash-calculation-issue-in-mongooseim-410631) for details.
+
 ## Preparing the environment
 
 === "Rocky/Alma"
