From d43673eb62582f690c11615cb1984d603c57b801 Mon Sep 17 00:00:00 2001 From: Doug Koerich Date: Wed, 3 Jun 2026 19:36:09 -0300 Subject: [PATCH 1/3] Doc: OpenSSL API modernization (SparkPost/Momentum#1276) Signed-off-by: Doug Koerich --- content/momentum/4/4-console-commands.md | 2 +- content/momentum/4/config-options-summary.md | 4 ++-- content/momentum/4/config/crypto-lock-method.md | 4 +++- content/momentum/4/config/ssl-lock-method.md | 4 +++- content/momentum/4/config/tls-protocols.md | 4 ++-- content/momentum/4/config/tlsv13-ciphersuites.md | 10 +++++----- content/momentum/4/console-commands/tls.md | 4 +++- content/momentum/changelog/5/5-3-0.md | 1 + 8 files changed, 20 insertions(+), 13 deletions(-) diff --git a/content/momentum/4/4-console-commands.md b/content/momentum/4/4-console-commands.md index ee93ab660..97cb5e501 100644 --- a/content/momentum/4/4-console-commands.md +++ b/content/momentum/4/4-console-commands.md @@ -158,7 +158,7 @@ This table lists all console commands alphabetically giving a brief description. | [threads io queue](/momentum/4/console-commands/threads) – Display summary statistics for the IO thread pools | 4.0 |   | stats | | [threads stats](/momentum/4/console-commands/threads) – Display summary statistics for thread pools | 4.0 |   | stats | | [tls flush cache](/momentum/4/console-commands/tls) – Flush the TLS cache | 4.0 |   | tls | -| [tls rekey](/momentum/4/console-commands/tls) – Remove the temporary RSA key | 4.0 |   | tls | +| [tls rekey](/momentum/4/console-commands/tls) – Remove the temporary RSA key | 4.0 through 5.2 |   | tls | | [tls show cache](/momentum/4/console-commands/tls) – Show the TLS cache | 4.0 |   | tls | | [trace smtp add](/momentum/4/console-commands/trace-smtp) – Add an SMTP trace | 4.0 |   | misc | | [trace smtp list](/momentum/4/console-commands/trace-smtp) – List smtp traces | 4.0 |   | misc | diff --git a/content/momentum/4/config-options-summary.md b/content/momentum/4/config-options-summary.md index 7a784f357..3b13bf7bc 100644 --- a/content/momentum/4/config-options-summary.md +++ b/content/momentum/4/config-options-summary.md @@ -107,7 +107,7 @@ The `Version` column indicated the version(s) of Momentum that support the optio | [control_listener](/momentum/4/control-listener#control_listener.config) *(scope)* – Listener for incoming control connections | na |   | 4.0 and later | global | | [critical](/momentum/4/config/ref-debug-flags) – Set the debug level | na | ALL | 4.0 and later | debug_flags | | [crypto_engine](/momentum/4/config/ref-crypto-engine) – Enable hardware cryptography acceleration | both |   | 4.0 and later | global | -| [crypto_lock_method](/momentum/4/config/crypto-lock-method) – Set the locking method used by the TLS layer | receiving and sending | EC_SSL_DEFAULTLOCK (*non-dynamic*) | 4.0 and later | global | +| [crypto_lock_method](/momentum/4/config/crypto-lock-method) – Set the locking method used by the TLS layer | receiving and sending | EC_SSL_DEFAULTLOCK (*non-dynamic*) | 4.0 through 5.2 | global | | [debug](/momentum/4/config/ref-debug-flags) – Set the debug level | na |   | 4.0 and later | debug_flags | | [debug_flags](/momentum/4/config/ref-debug-flags) *(scope)* – Configure debug verbosity | na |   | 4.0 and later | global | | [debug_level](/momentum/4/4-module-config) – Set the module debug level (applicable to all modules) (cluster-specific) | na | error | 4.0 and later | cluster | @@ -331,7 +331,7 @@ The `Version` column indicated the version(s) of Momentum that support the optio | [soft_bounce_drain_rate](/momentum/4/config/ref-soft-bounce-drain-rate) – How many soft bounces to place into the mail queues in a single scheduler iteration | sending | 100 | 4.0 and later | global | | [spool_mode](/momentum/4/config/ref-spool-mode) – Set the file mode for newly created spool files | na | 0640 (*non-dynamic*) | 4.0 and later | global | | [spoolbase](/momentum/4/config/ref-spoolbase) – Set the base directory for the spool | na | /var/spool/ecelerity (*non-dynamic*) | 4.0 and later | global | -| [ssl_lock_method](/momentum/4/config/ssl-lock-method) – Specify the SSL lock method | na | mutex (*non-dynamic*) | 4.0 and later | global | +| [ssl_lock_method](/momentum/4/config/ssl-lock-method) – Specify the SSL lock method | na | mutex (*non-dynamic*) | 4.0 through 5.2 | global | | [stack_size](/momentum/4/config/ref-threadpool) – Stack space for a threadpool | na | 0 (*non-dynamic*) | 4.0 and later | threadpool | | [starttls_injection_policy](/momentum/4/config/starttls-injection-policy) – Protect against SMTP injections prior to TLS | receiving | reject | 4.0 and later | esmtp_listener, listen, pathway, pathway_group, peer | | [state](/momentum/4/config/ref-snmp) – Whether to enable the SNMP agent | na | 1 (*non-dynamic*) | 4.0 and later | snmp | diff --git a/content/momentum/4/config/crypto-lock-method.md b/content/momentum/4/config/crypto-lock-method.md index 6caf7196c..8cf555069 100644 --- a/content/momentum/4/config/crypto-lock-method.md +++ b/content/momentum/4/config/crypto-lock-method.md @@ -1,5 +1,5 @@ --- -lastUpdated: "03/26/2020" +lastUpdated: "06/03/2026" title: "crypto_lock_method" description: "crypto lock method set the locking method used by the TLS layer Crypto Lock Method EC SSL SPINLOCK Crypto Lock Method EC SSL MUTEX Crypto Lock Method EC SSL DEFAULTLOCK This option affects how thread safe locking is performed You should not need to change the default value of this..." --- @@ -9,6 +9,8 @@ description: "crypto lock method set the locking method used by the TLS layer Cr crypto_lock_method — set the locking method used by the TLS layer +> **NOTE: This option was REMOVED in Momentum 5.3.0 and is no longer supported.** OpenSSL 1.1.1 and later (the supported range, from 1.1.1 on RHEL 8 through the 3.5.x series) is internally thread-safe; the `CRYPTO_set_locking_callback()`-based locking that this option configured was retired from OpenSSL itself. The option is silently ignored; remove it from `ecelerity.conf`. This page is retained for reference on releases prior to 5.3.0. See also [ssl_lock_method](/momentum/4/config/ssl-lock-method). + ## Synopsis `Crypto_Lock_Method = "EC_SSL_SPINLOCK"` diff --git a/content/momentum/4/config/ssl-lock-method.md b/content/momentum/4/config/ssl-lock-method.md index 3874e2845..485c091fe 100644 --- a/content/momentum/4/config/ssl-lock-method.md +++ b/content/momentum/4/config/ssl-lock-method.md @@ -1,5 +1,5 @@ --- -lastUpdated: "03/26/2020" +lastUpdated: "06/03/2026" title: "ssl_lock_method" description: "ssl lock method the SSL lock method SSL Lock Method mutex spinlock This option specifies the SSL lock method This option should be changed in consultation with Message Systems support only if SSL performance issues are encountered with the default method This option can be set to the following mutex..." --- @@ -9,6 +9,8 @@ description: "ssl lock method the SSL lock method SSL Lock Method mutex spinlock ssl_lock_method — the SSL lock method +> **NOTE: This option was REMOVED in Momentum 5.3.0 and is no longer supported.** OpenSSL 1.1.1 and later (the supported range, from 1.1.1 on RHEL 8 through the 3.5.x series) is internally thread-safe and no longer uses the application-supplied crypto locking callbacks that this option controlled. The option is silently ignored; remove it from `ecelerity.conf`. This page is retained for reference on releases prior to 5.3.0. See also [crypto_lock_method](/momentum/4/config/crypto-lock-method). + ## Synopsis `SSL_Lock_Method = "mutex|spinlock"` diff --git a/content/momentum/4/config/tls-protocols.md b/content/momentum/4/config/tls-protocols.md index a79aec189..7a34779cb 100644 --- a/content/momentum/4/config/tls-protocols.md +++ b/content/momentum/4/config/tls-protocols.md @@ -1,5 +1,5 @@ --- -lastUpdated: "09/20/2023" +lastUpdated: "06/03/2026" title: "tls_protocols" description: "tls protocols allowable ciphers for TLS inbound and outbound sessions tls protocols baseprotocol additional protocols Configuration Change This option is available as of version 4 1 0 2 tls protocols specifies the allowable protocols for an Open SSL TLS session The available protocols are ALL SS Lv 2 SS Lv..." --- @@ -30,7 +30,7 @@ The default value is “+ALL”. ### Note -In Centos/RHEL 5, which are typically shipped with OpenSSL 0.98, TLSv1.1, TLSv1.2 and TLSv1.3 are not available. +The supported OpenSSL range is 1.1.1 or later — from 1.1.1 (as shipped with RHEL 8) through the 3.5.x series — so `TLSv1.1`, `TLSv1.2` and `TLSv1.3` are always available and can be enabled or disabled freely. ## Scope diff --git a/content/momentum/4/config/tlsv13-ciphersuites.md b/content/momentum/4/config/tlsv13-ciphersuites.md index 918d2e834..8b4d21a85 100644 --- a/content/momentum/4/config/tlsv13-ciphersuites.md +++ b/content/momentum/4/config/tlsv13-ciphersuites.md @@ -1,5 +1,5 @@ --- -lastUpdated: "09/20/2023" +lastUpdated: "06/03/2026" title: "tlsv13_ciphersuites" description: "specify allowable ciphersuites for TLS inbound and outbound sessions when TLSv1.3 protocol is negotiated and used" --- @@ -24,7 +24,7 @@ allowable ciphersuites must be a subset of the available TLSv1.3 ciphersuites on When TLS_Engine is set to `openssl`, `TLSv13_Ciphersuites` specifies a "ciphersuite list", which is a colon (":") separated list of the supported TLSv1.3 ciphersuite names in order of preference. -There are 5 valid TLSv1.3 ciphersuites that are supported by OpenSSL 1.1.1: +There are 5 valid TLSv1.3 ciphersuites, supported across the full OpenSSL range used by Momentum (1.1.1 — as on RHEL 8 — through the 3.5.x series): ``` TLS_AES_256_GCM_SHA384 TLS_CHACHA20_POLY1305_SHA256 @@ -33,14 +33,14 @@ There are 5 valid TLSv1.3 ciphersuites that are supported by OpenSSL 1.1.1: TLS_AES_128_CCM_SHA256 ``` By default (if not explicitly specified through this configuration option), only the first three are enabled. -On the host machine, `openssl11 ciphers -s -tls1_3` can show the default TLSv1.3 ciphersuites; -`openssl11 ciphers -tls1_3 -v -s -ciphersuites TLS_AES_128_CCM_8_SHA256:TLS_AES_128_CCM_SHA256` can +On the host machine, `openssl ciphers -s -tls1_3` can show the default TLSv1.3 ciphersuites; +`openssl ciphers -tls1_3 -v -s -ciphersuites TLS_AES_128_CCM_8_SHA256:TLS_AES_128_CCM_SHA256` can check whether the last two ciphersuites are supported if enabled. For more information about the TLSv1.3 ciphersuites, see [https://wiki.openssl.org/index.php/TLS1.3#Ciphersuites](https://wiki.openssl.org/index.php/TLS1.3#Ciphersuites). -* To set the option to all the 5 TLSv1.3 ciphersuites supported by OpenSSL 1.1.1: +* To set the option to all 5 supported TLSv1.3 ciphersuites: ``` TLSv13_Ciphersuites = "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256:TLS_AES_128_CCM_8_SHA256:TLS_AES_128_CCM_SHA256" diff --git a/content/momentum/4/console-commands/tls.md b/content/momentum/4/console-commands/tls.md index 4f2fa067d..b44ea1cbd 100644 --- a/content/momentum/4/console-commands/tls.md +++ b/content/momentum/4/console-commands/tls.md @@ -1,5 +1,5 @@ --- -lastUpdated: "03/26/2020" +lastUpdated: "06/03/2026" title: "tls" description: "tls show cache tls flush cache tls rekey manage TLS cache used by Momentum tls flush cache tls rekey tls show cache tls show cache shows information of the TLS cache used by the server tls flush cache flushes TLS cache tls rekey removes the temporary RSA key Next use..." --- @@ -9,6 +9,8 @@ description: "tls show cache tls flush cache tls rekey manage TLS cache used by tls show cache, tls flush cache, tls rekey — manage TLS cache used by Momentum +> **NOTE: The `tls rekey` subcommand was REMOVED in Momentum 5.3.0 and is no longer a valid command.** It managed a temporary RSA key used for export-grade cipher suites; that mechanism was retired from OpenSSL (the `SSL_CTX_set_tmp_rsa_callback()` API) and from Momentum as part of the OpenSSL 1.1.1+/3.5.x modernization. On 5.3.0 and later, `tls show cache` no longer prints a "Temp RSA key" line. The `tls rekey` description below is retained for reference on releases prior to 5.3.0. + ## Synopsis `tls flush cache` diff --git a/content/momentum/changelog/5/5-3-0.md b/content/momentum/changelog/5/5-3-0.md index d39afc7ae..0eb9dae2a 100644 --- a/content/momentum/changelog/5/5-3-0.md +++ b/content/momentum/changelog/5/5-3-0.md @@ -18,6 +18,7 @@ This section will list all of the major changes that happened with the release o | Feature | I-1214 | Removed `msys-nodejs` RPM from the Momentum bundle, to be replaced with the 3rd-party `nodejs` package. Node.js LTS 24+ must be installed separately from the system or a vendor repository. | | Feature | I-1216 | Added the [log_hires_timestamp](/momentum/4/config/ref-log-hires-timestamp) option to emit microsecond-resolution timestamps in the `mainlog`, `bouncelog`, `rejectlog`, `paniclog`, custom logs, chunk logs, and message generation logs, preserving event ordering when reading multiple log files together. | | Feature | I-1225 | Added optional `--meta` / `--header` filtering to the [`reroute queue`](/momentum/4/console-commands/reroute-queue#reroute_queue_selective) console command, to selectively move queued messages by metadata or RFC822 header match. | +| Enhancement | I-1276 | The supported range of OpenSSL covers 1.1.1 (RHEL 8) through the 3.5.x series — all pre-1.1.1 compatibility code has been retired. No configuration changes are required — the removed options are silently ignored if still present. | | Feature | TASK-144964 | The [tls_ec_curve_names](/momentum/4/config/tls-ec-curve-names) option now accepts a colon-separated list of curve or TLS group short names in preference order, instead of a single curve. | | Feature | TASK-198522 | New DNS configuration options to [rate-limit MX lookups](/momentum/4/config/ref-dns-rate-limit), preventing query bursts from overwhelming the DNS infrastructure. | | Fix | TASK-227757 | [`ha_proxy_client`](/momentum/4/modules/ha-proxy-client) now re-resolves a hostname-based `ha_proxy_server` during each health check, so backend IP changes are picked up automatically without restart. | From be3ef720b3a10878c96f8aea6771a439f2a39967 Mon Sep 17 00:00:00 2001 From: Doug Koerich Date: Wed, 3 Jun 2026 19:52:13 -0300 Subject: [PATCH 2/3] Doc: adding note about protocols actually supported (SparkPost/Momentum#1276) Signed-off-by: Doug Koerich --- content/momentum/4/config/tls-protocols.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/content/momentum/4/config/tls-protocols.md b/content/momentum/4/config/tls-protocols.md index 7a34779cb..40b670bd0 100644 --- a/content/momentum/4/config/tls-protocols.md +++ b/content/momentum/4/config/tls-protocols.md @@ -18,11 +18,11 @@ tls_protocols — allowable ciphers for TLS inbound and outbound sessions **Configuration Change. ** This option is available as of version 4.1.0.2\. -`tls_protocols` specifies the allowable protocols for an OpenSSL TLS session. The available -protocols are `ALL`, `SSLv2`, `SSLv3`, `TLSv1.0`, `TLSv1.1`, `TLSv1.2` and `TLSv1.3` (since Momentum -4.6). Each set can be enabled or disabled by prefixing its name with a “+” or “-“ respectively. The following example shows the SSLv2 and SSLv3 protocols being disabled: +`tls_protocols` specifies the allowable protocols for an OpenSSL TLS session. Momentum parses the +tokens `ALL`, `SSLv2`, `SSLv3`, `TLSv1.0`, `TLSv1.1`, `TLSv1.2` and `TLSv1.3` (the last since Momentum +4.6). Each is enabled or disabled by prefixing its name with a “+” or “-“ respectively. The following example disables the older protocols, leaving TLS 1.2 and TLS 1.3: -`TLS_Protocols = "+ALL:-SSLv2:-SSLv3"` +`TLS_Protocols = "+ALL:-SSLv3:-TLSv1.0:-TLSv1.1"` This option has no meaning for GNUTLS. @@ -30,7 +30,17 @@ The default value is “+ALL”. ### Note -The supported OpenSSL range is 1.1.1 or later — from 1.1.1 (as shipped with RHEL 8) through the 3.5.x series — so `TLSv1.1`, `TLSv1.2` and `TLSv1.3` are always available and can be enabled or disabled freely. +The tokens above are still accepted for backward compatibility, but which protocols can **actually** be negotiated is determined by the OpenSSL build (1.1.1, as on RHEL 8, through the 3.5.x series) and — on distributions that ship one — the system-wide crypto policy: + +* **SSLv2** — removed from OpenSSL as of 1.1.0 and never negotiated. Momentum builds its contexts with `TLS_method()`, so the `SSLv2` token has no effect. + +* **SSLv3** — insecure and disabled by default; platform OpenSSL packages (including RHEL 8) typically compile it out or block it via the crypto policy. Treat it as unavailable. + +* **TLSv1.0 / TLSv1.1** — deprecated; still implemented by OpenSSL but commonly disabled by the OS crypto policy. For example, the RHEL 8 DEFAULT policy permits only TLS 1.2 and TLS 1.3, so enabling these tokens has no effect there. + +* **TLSv1.2 / TLSv1.3** — the protocols in normal use. + +As a result, `+ALL` no longer implies SSLv2 or SSLv3, and on a typical RHEL 8 deployment it resolves to TLS 1.2 and TLS 1.3 only. ## Scope From a228fe475b1fc00f3ec2f8862a605446d8229187 Mon Sep 17 00:00:00 2001 From: Doug Koerich Date: Mon, 8 Jun 2026 10:33:22 -0300 Subject: [PATCH 3/3] Adding the list of configuration changes to the changelog (SparkPost/Momentum#1276) Signed-off-by: Doug Koerich --- .../momentum/4/config/ref-crypto-engine.md | 4 +++- content/momentum/changelog/5/5-3-0.md | 21 ++++++++++++++++++- 2 files changed, 23 insertions(+), 2 deletions(-) diff --git a/content/momentum/4/config/ref-crypto-engine.md b/content/momentum/4/config/ref-crypto-engine.md index 624321b3f..78d7aabee 100644 --- a/content/momentum/4/config/ref-crypto-engine.md +++ b/content/momentum/4/config/ref-crypto-engine.md @@ -9,6 +9,8 @@ description: "crypto engine enable hardware cryptography acceleration crypto eng crypto_engine — enable hardware cryptography acceleration +> **NOTE: This option depends on the OpenSSL ENGINE API, which was removed in OpenSSL 3.0 in favor of the provider model.** On builds running OpenSSL 3.x (including the 3.5.x series), `crypto_engine` has no effect and is silently ignored; it remains functional only on OpenSSL 1.1.1 builds (for example, RHEL 8). + ## Synopsis crypto_engine = "*`engine_name`*" @@ -27,4 +29,4 @@ The example below shows how to configure Momentum to use the pkcs12 engine. ## Scope -crypto_engine is valid in the global scope. \ No newline at end of file +crypto_engine is valid in the global scope. diff --git a/content/momentum/changelog/5/5-3-0.md b/content/momentum/changelog/5/5-3-0.md index 0eb9dae2a..4f11af30f 100644 --- a/content/momentum/changelog/5/5-3-0.md +++ b/content/momentum/changelog/5/5-3-0.md @@ -18,7 +18,26 @@ This section will list all of the major changes that happened with the release o | Feature | I-1214 | Removed `msys-nodejs` RPM from the Momentum bundle, to be replaced with the 3rd-party `nodejs` package. Node.js LTS 24+ must be installed separately from the system or a vendor repository. | | Feature | I-1216 | Added the [log_hires_timestamp](/momentum/4/config/ref-log-hires-timestamp) option to emit microsecond-resolution timestamps in the `mainlog`, `bouncelog`, `rejectlog`, `paniclog`, custom logs, chunk logs, and message generation logs, preserving event ordering when reading multiple log files together. | | Feature | I-1225 | Added optional `--meta` / `--header` filtering to the [`reroute queue`](/momentum/4/console-commands/reroute-queue#reroute_queue_selective) console command, to selectively move queued messages by metadata or RFC822 header match. | -| Enhancement | I-1276 | The supported range of OpenSSL covers 1.1.1 (RHEL 8) through the 3.5.x series — all pre-1.1.1 compatibility code has been retired. No configuration changes are required — the removed options are silently ignored if still present. | +| Enhancement | I-1276 | The supported range of OpenSSL covers 1.1.1 (RHEL 8) through the 3.5.x series — all pre-1.1.1 compatibility code has been retired. A few obsolete TLS settings were removed as part of this change; see the [note](#changelog.5.3.0.openssl-removals) below. | | Feature | TASK-144964 | The [tls_ec_curve_names](/momentum/4/config/tls-ec-curve-names) option now accepts a colon-separated list of curve or TLS group short names in preference order, instead of a single curve. | | Feature | TASK-198522 | New DNS configuration options to [rate-limit MX lookups](/momentum/4/config/ref-dns-rate-limit), preventing query bursts from overwhelming the DNS infrastructure. | | Fix | TASK-227757 | [`ha_proxy_client`](/momentum/4/modules/ha-proxy-client) now re-resolves a hostname-based `ha_proxy_server` during each health check, so backend IP changes are picked up automatically without restart. | + + + +**NOTE: OpenSSL cleanup (I-1276) — configuration impact.** No action is required in any of the cases below, but you may tidy up your configuration if you wish. + +The following settings are obsolete as of 5.3.0 and are silently ignored if still present; they can be deleted from `ecelerity.conf` and from any console scripts: + +* [`ssl_lock_method`](/momentum/4/config/ssl-lock-method) — configuration option +* [`crypto_lock_method`](/momentum/4/config/crypto-lock-method) — configuration option +* [`tls rekey`](/momentum/4/console-commands/tls) — console command (the `tls show cache` output no longer includes a "Temp RSA key" line) + +In addition, the following [`tls_protocols`](/momentum/4/config/tls-protocols) (and equivalent [`tls_ciphers`](/momentum/4/config/tls-ciphers)) protocol tokens are still accepted for backward compatibility but no longer take effect, because the protocols are not negotiated on OpenSSL 1.1.1 and later: + +* `SSLv2`, `SSLv3` — removed or disabled within OpenSSL itself and never negotiated +* `TLSv1.0`, `TLSv1.1` — deprecated and, on platforms such as RHEL 8 (DEFAULT crypto policy), restricted to TLS 1.2 and TLS 1.3 + +As a result, `tls_protocols = "+ALL"` resolves to TLS 1.2 and TLS 1.3 on a typical deployment. + +Finally, [`crypto_engine`](/momentum/4/config/ref-crypto-engine) is version-dependent rather than removed: it has no effect on OpenSSL 3.x builds (including the 3.5.x series), because the ENGINE API it relies on was removed in OpenSSL 3.0 in favor of the provider model. It continues to work on OpenSSL 1.1.1 builds such as RHEL 8. On OpenSSL 3.x, configure the appropriate OpenSSL provider at the library level instead.