TASK-144964: New page for TLS_EC_curve_names (SparkPost/Momentum#1247)

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 |

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 |

content/momentum/4/config/tls-ec-curve-names.md

@@ -0,0 +1,58 @@
+---
+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 of Momentum 5.3 and later, a colon-separated list in preference order (e.g. secp384r1:prime256v1)."
+---
+
+<a name="config.tls_ec_curve_names"></a>
+## 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 = "<curve>[:<another curve>]"`
+
+## 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.
+
+### 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.
+
+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.
+
+### 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.

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. |