From f0b722674324953b671434d2fe42d4c70b3bb20b Mon Sep 17 00:00:00 2001 From: Doug Koerich Date: Thu, 21 May 2026 16:00:35 -0300 Subject: [PATCH 1/3] TASK-144946: New page for TLS_EC_curve_names (SparkPost/Momentum#1247) Signed-off-by: Doug Koerich --- content/momentum/4/config-options-summary.md | 1 + content/momentum/4/config/index.md | 1 + .../momentum/4/config/tls-ec-curve-names.md | 42 +++++++++++++++++++ content/momentum/changelog/5/5-3-0.md | 1 + 4 files changed, 45 insertions(+) create mode 100644 content/momentum/4/config/tls-ec-curve-names.md diff --git a/content/momentum/4/config-options-summary.md b/content/momentum/4/config-options-summary.md index 42d6f293..7a784f35 100644 --- a/content/momentum/4/config-options-summary.md +++ b/content/momentum/4/config-options-summary.md @@ -356,6 +356,7 @@ The `Version` column indicated the version(s) of Momentum that support the optio | [tlsv13_ciphersuites](/momentum/4/config/tlsv13-ciphersuites) – Specify allowable TLSv1.3 ciphersuites for TLS inbound and outbound sessions | receiving and sending |   | 4.6 and later | binding, binding_group, domain, esmtp_listener, global, http_listener, listen, pathway, pathway_group, peer | | [tls_client_ca](/momentum/4/config/tls-client-ca) – Specify certificate authority for inbound mail | receiving |   | 4.0 and later | ecstream_listener, esmtp_listener, global, http_listener, listen, pathway, pathway_group, peer, xmpp_listener | | [tls_dhparams_file](/momentum/4/config/ref-tls-dhparams-file) – Specifies DHE parameters that add per-session randomness to the encryption | both |   | 4.0 and later | global | +| [tls_ec_curve_names](/momentum/4/config/tls-ec-curve-names) – Select the elliptic curves or TLS groups used for ECDHE key exchange in inbound and outbound TLS sessions | both | | 4.2 and later | global | | [tls_enable_dhe_ciphers](/momentum/4/config/ref-tls-enable-dhe-ciphers) – Controls whether or not DHE ciphers are available | both | true | 4.0 and later | global | | [tls_engine](/momentum/4/config/tls-engine) – Specify the TLS library to use (OpenSSL or GNUTLS) | sending | openssl | 4.0 and later | global | | [tls_ifavailable_fallback](/momentum/4/config/tls-ifavailable-fallback) – Determine the behavior if TLS negotiation fails | sending | true | 4.1 and later | binding, binding_group, domain, global | diff --git a/content/momentum/4/config/index.md b/content/momentum/4/config/index.md index d83a40b6..cfc1dca8 100644 --- a/content/momentum/4/config/index.md +++ b/content/momentum/4/config/index.md @@ -220,6 +220,7 @@ description: "This chapter provides the definitions of the configuration options | [tlsv13_ciphersuites](/momentum/4/config/tlsv13-ciphersuites) | specify allowable TLSv1.3 ciphersuites for TLS inbound and outbound sessions | | [tls_client_ca](/momentum/4/config/tls-client-ca) | certificate authority for inbound mail | | [tls_dhparams_file](/momentum/4/config/ref-tls-dhparams-file) | specifies the file of Diffie Hellman (DHE) parameters that add per-session randomness to the encryption. Default parameters are built in the product if none are specified. | +| [tls_ec_curve_names](/momentum/4/config/tls-ec-curve-names) | select the elliptic curves or TLS groups used for ECDHE key exchange in inbound and outbound TLS sessions | | [tls_enable_dhe_ciphers](/momentum/4/config/ref-tls-enable-dhe-ciphers) | controls whether or not Diffie Hellman (DHE) ciphers are available | | [tls_engine](/momentum/4/config/tls-engine) | specify the TLS library to use | | [tls_ifavailable_fallback](/momentum/4/config/tls-ifavailable-fallback) | determine the behavior if TLS negotiation fails | diff --git a/content/momentum/4/config/tls-ec-curve-names.md b/content/momentum/4/config/tls-ec-curve-names.md new file mode 100644 index 00000000..85907edf --- /dev/null +++ b/content/momentum/4/config/tls-ec-curve-names.md @@ -0,0 +1,42 @@ +--- +lastUpdated: "05/21/2026" +title: "tls_ec_curve_names" +description: "tls_ec_curve_names selects the OpenSSL elliptic curves or TLS groups used for ECDHE key exchange in inbound and outbound TLS sessions. Specify a single curve short name (e.g. secp384r1) or, in newer versions, a colon-separated list in preference order (e.g. secp384r1:prime256v1)." +--- + + +## Name + +tls_ec_curve_names — select the elliptic curves or TLS groups used for ECDHE key exchange in inbound and outbound TLS sessions + +## Synopsis + +`TLS_EC_Curve_Names = "[:]"` + +## Description + +This option selects the elliptic curves (or TLS groups, in TLS 1.3 terminology) advertised and used during ECDHE key exchange for TLS sessions established by Momentum. The value is a curve short name as accepted by OpenSSL, for example `secp384r1` or `prime256v1`. A full list of curve short names available on the host can be obtained by running `openssl ecparam -list_curves` on the host machine. + +This option has no default value; when unset, Momentum lets OpenSSL pick the curve from its built-in defaults. + +**Configuration Change.** As of version 5.3, the value may also be a colon-separated list of curve or TLS group short names, in preference order. For example: + +`TLS_EC_Curve_Names = "secp384r1:prime256v1"` + +In earlier versions, only a single curve short name is accepted; setting a colon-separated list is rejected. + +The list must be normalized: no leading or trailing whitespace, no spaces around the `:` delimiters, and no empty segments (e.g. `"a::b"` or `":a"` are rejected). Each token must be a curve or group name accepted by OpenSSL; if any token is unknown, the whole value is rejected at `config set` time with an `invalid curve or group list` error. + +This option has no meaning for GNUTLS. + +### Note + +When Momentum is built or deployed against a *FIPS-validated cryptographic library* (for example OpenSSL with the FIPS provider, or a drop-in FIPS-validated replacement like SafeLogic), the set of curves the library will actually use is restricted to those approved by the active FIPS module — typically a subset of the NIST P-curves, with `prime256v1`, `secp384r1`, and `secp521r1` being the safe baseline across modules. Curves outside that subset are likely to be rejected by OpenSSL at config-set time with the `invalid curve or group list` error, even if `openssl ecparam -list_curves` shows them as known to the binary. + +The exact accepted set varies by OpenSSL version, FIPS module version, and (on Linux distributions that ship one, like Red Hat Enterprise Linux) the system-wide crypto policy, which layers on top of the FIPS module's own restrictions. FIPS 140 itself — currently FIPS 140-3, with FIPS 140-2 modules still common in production through the transition — governs the *module*: its cryptographic boundary, self-tests, and key handling. *Which* curves that module is permitted to expose is defined separately, by NIST Special Publications: SP 800-186 (finalized February 2023) for ECDH curves, and FIPS 186-5 (also 2023) for ECDSA. A module certified against earlier revisions of those publications will reject curves added later — for example, `x25519` is recognized by OpenSSL 3 and listed by `openssl ecparam -list_curves`, but FIPS modules certified before SP 800-186 (including most FIPS 140-2 modules) refuse it, so setting `tls_ec_curve_names = "x25519"` against such a module fails validation. Non-certified FIPS-style libraries add yet another axis of variation: they may approximate the restrictions of a certified module but do not necessarily track the latest Special Publication updates. + +**Operators targeting a FIPS-enabled environment should validate their `tls_ec_curve_names` value** against the curves enabled on the host before relying on it. As a practical safeguard, prefer building the list around the universally-FIPS-approved baseline (`prime256v1`, `secp384r1`, `secp521r1`); when targeting a host whose FIPS module's accepted set is unknown or heterogeneous across a fleet, a baseline-only value such as `TLS_EC_Curve_Names = "secp384r1:prime256v1"` is accepted across all FIPS modules and avoids the risk that the whole list is rejected because of a single curve the active provider does not register. + +## Scope + +`tls_ec_curve_names` 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 fff0a78b..43cb3c04 100644 --- a/content/momentum/changelog/5/5-3-0.md +++ b/content/momentum/changelog/5/5-3-0.md @@ -14,5 +14,6 @@ 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. | +| 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 77790b79fdf4b58a89eb57d780bf97f498b7da72 Mon Sep 17 00:00:00 2001 From: Doug Koerich Date: Thu, 21 May 2026 16:34:46 -0300 Subject: [PATCH 2/3] TASK-144964: Added PQ note (SparkPost/Momentum#1247) Signed-off-by: Doug Koerich --- .../momentum/4/config/tls-ec-curve-names.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/content/momentum/4/config/tls-ec-curve-names.md b/content/momentum/4/config/tls-ec-curve-names.md index 85907edf..465c7dd0 100644 --- a/content/momentum/4/config/tls-ec-curve-names.md +++ b/content/momentum/4/config/tls-ec-curve-names.md @@ -29,7 +29,7 @@ The list must be normalized: no leading or trailing whitespace, no spaces around This option has no meaning for GNUTLS. -### Note +### FIPS considerations When Momentum is built or deployed against a *FIPS-validated cryptographic library* (for example OpenSSL with the FIPS provider, or a drop-in FIPS-validated replacement like SafeLogic), the set of curves the library will actually use is restricted to those approved by the active FIPS module — typically a subset of the NIST P-curves, with `prime256v1`, `secp384r1`, and `secp521r1` being the safe baseline across modules. Curves outside that subset are likely to be rejected by OpenSSL at config-set time with the `invalid curve or group list` error, even if `openssl ecparam -list_curves` shows them as known to the binary. @@ -37,6 +37,22 @@ The exact accepted set varies by OpenSSL version, FIPS module version, and (on L **Operators targeting a FIPS-enabled environment should validate their `tls_ec_curve_names` value** against the curves enabled on the host before relying on it. As a practical safeguard, prefer building the list around the universally-FIPS-approved baseline (`prime256v1`, `secp384r1`, `secp521r1`); when targeting a host whose FIPS module's accepted set is unknown or heterogeneous across a fleet, a baseline-only value such as `TLS_EC_Curve_Names = "secp384r1:prime256v1"` is accepted across all FIPS modules and avoids the risk that the whole list is rejected because of a single curve the active provider does not register. +### Post-quantum key exchange + +OpenSSL 3.5 (April 2025) accepts the TLS 1.3 *group* identifiers registered for post-quantum key encapsulation, so they are valid tokens in `tls_ec_curve_names`. The names recognized by OpenSSL 3.5+ are: + +- **Standalone ML-KEM**: `MLKEM512`, `MLKEM768`, `MLKEM1024`. +- **Hybrid ECDHE + ML-KEM**: `X25519MLKEM768`, `X448MLKEM1024`, `SecP256r1MLKEM768`, `SecP384r1MLKEM1024`. + +#### FIPS status + +ML-KEM became FIPS-approved when FIPS 203 was published in August 2024. The practical consequences for `tls_ec_curve_names`: + +- FIPS 140-2 modules — and, more generally, any module certified before late 2024 — do not include ML-KEM and will reject every name listed above. Deployments that need post-quantum key exchange under FIPS must use a FIPS 140-3 module whose scope explicitly includes ML-KEM. +- For hybrids, both halves must be in the module's certified scope. `SecP256r1MLKEM768` and `SecP384r1MLKEM1024` are the safest choices for FIPS portability, because their classical halves draw on the universally-FIPS-approved NIST P-curve baseline. Hybrids that include `x25519` or `x448` carry the same module-vintage caveat as standalone `x25519` / `x448` — they were added to the approved curve list only with NIST SP 800-186 in February 2023, and older FIPS 140-3 modules may not register them. + +A reasonable PQC-preferred configuration that still negotiates cleanly with peers that have not yet adopted ML-KEM is `TLS_EC_Curve_Names = "SecP384r1MLKEM1024:SecP256r1MLKEM768:secp384r1:prime256v1"`. As with any multi-token value, every name in the list must be registered by the active provider on the host or the whole value is rejected at `config set` time, so validate against the target OpenSSL build and FIPS module before deploying. + ## Scope `tls_ec_curve_names` is valid in the global scope. From bd7d70c2cf73c00ed8336c16be42cb96a476f7a1 Mon Sep 17 00:00:00 2001 From: Doug Koerich Date: Fri, 22 May 2026 09:48:03 -0300 Subject: [PATCH 3/3] TASK-144964: Minor change in page header (Momentum#1247) Signed-off-by: Doug Koerich --- content/momentum/4/config/tls-ec-curve-names.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/momentum/4/config/tls-ec-curve-names.md b/content/momentum/4/config/tls-ec-curve-names.md index 465c7dd0..074f463e 100644 --- a/content/momentum/4/config/tls-ec-curve-names.md +++ b/content/momentum/4/config/tls-ec-curve-names.md @@ -1,7 +1,7 @@ --- lastUpdated: "05/21/2026" title: "tls_ec_curve_names" -description: "tls_ec_curve_names selects the OpenSSL elliptic curves or TLS groups used for ECDHE key exchange in inbound and outbound TLS sessions. Specify a single curve short name (e.g. secp384r1) or, in newer versions, a colon-separated list in preference order (e.g. secp384r1:prime256v1)." +description: "tls_ec_curve_names selects the OpenSSL elliptic curves or TLS groups used for ECDHE key exchange in inbound and outbound TLS sessions. Specify a single curve short name (e.g. secp384r1) or, in newer versions of Momentum 5.3 and later, a colon-separated list in preference order (e.g. secp384r1:prime256v1)." ---