EOP-218: Compilation of changes for Momentum 4.8 release (#771)

* EOP-164: add support pages for MTA-STS in Momentum (#760) * EOP-155 ec_mta_sts_purge utility (#764) * EOP-176 tlsa_expire_interval (#765) * EOP-134 Fix documentation for ec_ssl_SSL_CTX_fixup (#766) * EOP-208: Release 4.8 documentation (#769) * EOP-218: Updating the c-ares version Signed-off-by: Doug Koerich <[email protected]> --------- Signed-off-by: Doug Koerich <[email protected]> Co-authored-by: Julie Zhao <[email protected]> Co-authored-by: Kris Kelley <[email protected]>
SparkPost · Sep 4, 2024 · ed45684 · ed45684
1 parent 4a9f380
commit ed45684
Show file tree

Hide file tree

Showing 27 changed files with 623 additions and 36 deletions.
diff --git a/content/momentum/3/3-api/hooks-core-ec-ssl-ssl-ctx-fixup.md b/content/momentum/3/3-api/hooks-core-ec-ssl-ssl-ctx-fixup.md
@@ -1,38 +1,31 @@
 ---
-lastUpdated: "03/26/2020"
+lastUpdated: "06/30/2024"
 title: "ec_ssl_SSL_CTX_fixup"
-description: "ec ssl SSL CTX fixup This hook provides an opportunity for modules to alter the context and add passphrase callbacks via Open SSL functions void core ec ssl SSL CTX fixup closure sslctx type domain certfile keyfile clientca cipher list void closure struct ssl ctx st sslctx int type const..."
+description: "ec ssl SSL CTX fixup This hook provides an opportunity for modules to alter the context and add passphrase callbacks via Open SSL functions"
 ---
 
 <a name="hooks.core.ec_ssl_SSL_CTX_fixup"></a> 
 ## Name
 
-ec_ssl_SSL_CTX_fixup — This hook provides an opportunity for modules to alter the context and add passphrase callbacks via OpenSSL functions
+ec_ssl_SSL_CTX_fixup — This hook provides an opportunity for modules to alter the context and add passphrase callbacks via OpenSSL functions.
 
 ## Synopsis
 
 `#include "hooks/core/ec_ssl_SSL_CTX_fixup.h"`
 
-| `void **core_ec_ssl_SSL_CTX_fixup** (` | <var class="pdparam">closure</var>, |   |
-|   | <var class="pdparam">sslctx</var>, |   |
-|   | <var class="pdparam">type</var>, |   |
-|   | <var class="pdparam">domain</var>, |   |
-|   | <var class="pdparam">certfile</var>, |   |
-|   | <var class="pdparam">keyfile</var>, |   |
-|   | <var class="pdparam">clientca</var>, |   |
-|   | <var class="pdparam">cipher_list</var>`)`; |   |
-
-`void * <var class="pdparam">closure</var>`;
-`struct ssl_ctx_st * <var class="pdparam">sslctx</var>`;
-`int <var class="pdparam">type</var>`;
-`const char * <var class="pdparam">domain</var>`;
-`const char * <var class="pdparam">certfile</var>`;
-`const char * <var class="pdparam">keyfile</var>`;
-`const char * <var class="pdparam">clientca</var>`;
-`const char * <var class="pdparam">cipher_list</var>`;<a name="idp42798880"></a> 
+```
+void core_ec_ssl_SSL_CTX_fixup (void *closure,
+                                struct ssl_ctx_st *sslctx,
+                                int type,
+                                const char *domain,
+                                const char *certfile,
+                                const char *keyfile,
+                                const char *clientca,
+                                const char *cipher_list);
+```
 ## Description
 
-This hook is called after the SSL_CTX (struct ssl_ctx_st) context has been allocated, but before the private key has been loaded.
+This hook is called after the SSL_CTX (`struct ssl_ctx_st`) context has been allocated, but before the private key has been loaded.
 
 This hook provides an opportunity for modules to alter the context and add passphrase callbacks via these OpenSSL functions:
 
@@ -55,7 +48,7 @@ A pointer to the closure.
 
 <dd>
 
-An `ec_ssl_ctx` struct. For documentation of this data structure see [“ec_ssl_ctx”](/momentum/3/3-api/structs-ec-ssl-ctx).
+This struct would be passed as-is to OpenSSL functions as the SSL_CTX parameter.
 
 </dd>
 
@@ -115,4 +108,4 @@ This hook returns `void`.
 
 **<a name="idp42822832"></a> Threading**
 
-This hook will be called in the `Scheduler` thread.
+This hook will be called in the `Scheduler` thread.
diff --git a/content/momentum/4/4-console-commands.md b/content/momentum/4/4-console-commands.md
@@ -118,6 +118,9 @@ This table lists all console commands alphabetically giving a brief description.
 | [message retry](/momentum/4/console-commands/message-retry) – Perform an immediate delivery attempt on a message | 4.0 |   | message |
 | [module hooks](/momentum/4/console-commands/4-module) – Manage loaded module hooks | 4.0 |   | module |
 | [module list](/momentum/4/console-commands/4-module) – Show loaded modules | 4.0 |   | module |
+| [mta_sts list all](/momentum/4/console-commands/mta-sts) – list active domains which have MTA-STS policy | 4.8 |   | mta-sts |
+| [mta_sts show domain](/momentum/4/console-commands/mta-sts) – show MTA-STS policy details for a domain | 4.8 |   | mta-sts |
+| [mta_sts refresh policy](/momentum/4/console-commands/mta-sts) – refresh MTA-STS policy for a domain | 4.8 |   | mta-sts |
 | [outbound_audit:instance_name clear all](/momentum/4/modules/outbound-audit#modules.outbound_audit.console) – Zero-out all statistics | 4.0 | outbound_audit | module |
 | [outbound_audit:instance_name clear domain](/momentum/4/modules/outbound-audit#modules.outbound_audit.console) – Zero-out a domain's statistics | 4.0 | outbound_audit | module |
 | [outbound_audit:instance_name domain_list](/momentum/4/modules/outbound-audit#modules.outbound_audit.console) – Runtime addition/deletion of a domain in the monitoring list | 4.0 | outbound_audit | module |
@@ -160,4 +163,4 @@ This table lists all console commands alphabetically giving a brief description.
 | [trace smtp remove](/momentum/4/console-commands/trace-smtp) – Remove an SMTP trace | 4.0 |   | misc |
 | [unlink stats](/momentum/4/console-commands/unlink-stats) – Show statistics of removing messages from the disk | 4.0 |   | stats |
 | [version](/momentum/4/console-commands/version) – Show version information of Momentum | 4.0 |   | misc |
-| [write config](/momentum/4/console-commands/write-config) – Display current running configuration | 4.0 |   | config |
+| [write config](/momentum/4/console-commands/write-config) – Display current running configuration | 4.0 |   | config |
diff --git a/content/momentum/4/4-exe.md b/content/momentum/4/4-exe.md
@@ -22,7 +22,8 @@ This table lists all executable commands alphabetically giving a brief descripti
 | [ec_lic](/momentum/4/executable/ec-lic) – Fetch a new license file from Message Systems | misc |
 | [ec_log_trace](/momentum/4/executable/ec-log-trace) – Parse Momentum log files | logs |
 | [ec_md5passwd](/momentum/4/executable/ec-md-5-passwd) – Change the password for a system user's password | security |
-| [ec_rotate](/momentum/4/executable/ec-rotate) – Rotate Momentum logfiles | logs |
+| [ec_mta_sts_purge](/momentum/4/executable/ec-mta-sts-purge) - remove expired MTA-STS policy files | misc |
+| [ec_rotate](/momentum/4/executable/ec-rotate) – Rotate Momentum logfiles | misc |
 | [ec_sendmail](/momentum/4/executable/ec-sendmail) – A sendmail compatibility interface | misc |
 | [ec_show](/momentum/4/executable/ec-show) – Show spool or message information | messages |
 | [eccfg](/momentum/4/executable/eccfg) – Subversion repository management | config |

diff --git a/content/momentum/4/config-options-summary.md b/content/momentum/4/config-options-summary.md
@@ -149,6 +149,7 @@ The `Version` column indicated the version(s) of Momentum that support the optio
 | [enable_authorization](/momentum/4/control-authz) – Whether or not to enable authorization for console commands | receiving |   | 4.0 and later | control_listener, listen, peer |
 | [enable_duravip](/momentum/4/4-cluster-config-duravip) – Whether to enable Durable MultiVIP© bindings (cluster-specific) | both |   | 4.0 and later | binding, listen |
 | [enable_fbl_header_insertion](/momentum/4/config/ref-enable-fbl-header-insertion) – Enable or disable fbl header insertion | sending |   | 4.0 and later | binding, binding_group, domain, global |
+| [enable_mta_sts](/momentum/4/config/mta-sts/enable-mta-sts) – Enable or disable MTA-STS policy application | sending |   | 4.8 and later | binding, binding_group, domain, global |
 | **enabled** – Whether or not the module is enabled (cluster-specific) | na | true | 4.0 and later | cluster |
 | [error](/momentum/4/config/ref-debug-flags) – Set the debug level | na | ALL | 4.0 and later | debug_flags |
 | [esmtp_listener](/momentum/4/esmtp-listener) *(scope)* – Listener for incoming SMTP connections | receiving |   | 4.0 and later | global |
@@ -237,6 +238,8 @@ The `Version` column indicated the version(s) of Momentum that support the optio
 | [max_resident_active_queue](/momentum/4/config/ref-max-resident-active-queue) – Threshold above which messages are not held in memory | sending | 250 | 4.0 and later | binding, binding_group, domain, global |
 | [max_resident_messages](/momentum/4/config/ref-max-resident-messages) – Threshold above which messages are not held in memory | sending | 32768 | 4.0 and later | binding, binding_group, global |
 | [max_resident_transfails](/momentum/4/config/ref-max-resident-transfails) – If the transient failure queue grows beyond this size, messages are swapped out of memory | sending | 100 | 4.0 and later | global |
+| [mta_sts_dns_cname_max_depth](/momentum/4/config/mta-sts/mta-sts-dns-cname-max-depth) – Maximum number of continous CNAME lookups allowed while doing MTA-STS DNS lookup | sending | 5 | 4.8 and later | global |
+| [mta_sts_policy_store](/momentum/4/config/mta-sts/mta-sts-policy-store) – Directory to store MTA-STS policy files | sending | /var/spool/ecelerity/mtasts (*non-dynamic*) | 4.8 and later | global |
 | [swap_out_meta_after_each_tempfail](/momentum/4/config/ref-swap-out-meta-after-each-tempfail) – If this is set to false, Momentum will only update metadata on disk after each tempfail if the message context is dirty, and the num_retires, next_attempt and message context may not be accurate if Momentum crashes | sending | true | 4.3.1 and later | global |
 | [max_retries](/momentum/4/config/ref-max-retries) – Override the system configured max_retries | sending |   | 4.0 and later | binding, binding_group, domain, global |
 | [max_retry_interval](/momentum/4/config/ref-max-retry-interval) – Maximum retry interval | sending | 43200 | 4.0 and later | binding, binding_group, domain, global |
@@ -352,6 +355,7 @@ The `Version` column indicated the version(s) of Momentum that support the optio
 | [tls_verified_peer_is_authorized](/momentum/4/config/tls-verified-peer-is-authorized) – Mark requests that use a verified SSL Client certificate as being authorized | sending | false | 4.0 and later | http_listener, listen, pathway, peer |
 | [tls_verify](/momentum/4/config/tls-verify) – Specify how to handle the remote presented certificate | sending | no | 4.0 and later | binding, binding_group, domain, global |
 | [tls_verify_mode](/momentum/4/config/tls-verify-mode) – Determine whether a TLS certificates is required | receiving |   | 4.0 and later | ecstream_listener, esmtp_listener, http_listener, listen, pathway, pathway_group, peer, xmpp_listener |
+| [tlsa_expire_interval](/momentum/4/config/tlsa-expire-interval) – How often to check for domains with expired DANE TLSA information | sending | 3600 | 4.8 and later | global |
 | [topology](/momentum/4/4-cluster-config-duravip) *(scope)* – Define the cluster network topology (cluster-specific) | na |   | 4.0 and later | cluster |
 | [trace_smtp_mode](/momentum/4/config/ref-trace-smtp-mode) – Set the default permissions of trace files | sending | 0640 (*non-dynamic*) | 4.0 and later | global |
 | [tracking_domain](/momentum/4/config/tracking-domain) – Set the tracking domain to use for engagement tracking in SMTP injections | string | localhost:8080 | 4.1-HF4 (beta) | esmtp_listener, listen, pathway, pathway_group, peer |
@@ -365,6 +369,7 @@ The `Version` column indicated the version(s) of Momentum that support the optio
 | [use_iflist_cache](/momentum/4/config/ref-use-iflist-cache) – Whether or not to cache the list of interfaces configured by the system | sending | 0 (*non-dynamic*) | 4.0 and later | global |
 | [use_ipv6](/momentum/4/config/ref-use-ipv-6) – Affects the selection of IPv6 hosts in the SMTP client | sending | false | 4.0 and later | global |
 | [use_mmap](/momentum/4/config/ref-use-mmap) – Use mmap when spooling messages from disk | na | false | 4.0 and later | global |
+| [use_mta_sts](/momentum/4/config/mta-sts/use-mta-sts) – Enable MTA-STS policy fetching on a domain | sending | false | 4.8 and later | global, domain |
 | [use_sendfile](/momentum/4/config/ref-use-sendfile) – Use sendfile() when sending mail | sending | false | 4.0 and later | global |
 | **use_ssl** – Whether or not to use SSL verification | receiving | false | 4.0 and later | ecstream_listener, esmtp_listener, http_listener, listen, pathway, pathway_group, peer |
 | [user](/momentum/4/config/ref-user) – User identity to assume after startup | na | ecuser (*non-dynamic*) | 4.0 and later | security |

diff --git a/content/momentum/4/config/enable-dane.md b/content/momentum/4/config/enable-dane.md
@@ -0,0 +1,29 @@
+---
+lastUpdated: "06/01/2024"
+title: "enable_dane"
+description: "config option to enable application of DANE TLS verification for outbound mails"
+---
+
+<a name="config.enable-dane"></a>
+## Name
+
+enable_dane — specify whether Momentum should apply DANE TLS verification for outbound emails
+
+## Synopsis
+
+`enable_dane = "true|false"`
+
+## Description
+
+This option is only effective when [dane module](/momentum/4/modules/dane) is configured and
+ [use_dane](/momentum/4/config/use-dane) is `true` for a recipient domain.
+
+This option specifies whether Momentum should try to apply the DANE TLS verification rules defined
+ in TLSA record when sending emails to a remote site.
+
+The default value is `true` when `use_dane` is `true` for a domain.
+
+
+## Scope
+
+`enable_dane` is valid in the binding, binding_group, domain and global scopes.
diff --git a/content/momentum/4/config/index.md b/content/momentum/4/config/index.md
@@ -75,7 +75,9 @@ description: "This chapter provides the definitions of the configuration options
 | [ecstream_timeout](/momentum/4/config/ref-ecstream-timeout) | the amount of time to wait for an ecstream connection to be established |
 | [ehlo_hostname](/momentum/4/config/ref-ehlo-hostname) | set the hostname used for EHLO in outbound mail |
 | [ehlo_timeout](/momentum/4/config/ref-ehlo-timeout) | network timeout for EHLO |
+| [enable_dane](/momentum/4/config/enable-dane) | enable application of DANE TLS verification on email delivery to a remote domain |
 | [enable_fbl_header_insertion](/momentum/4/config/ref-enable-fbl-header-insertion) | enable or disable fbl header insertion |
+| [enable_mta_sts](/momentum/4/config/mta-sts/enable-mta-sts) | enable application of MTA-STS policy on email delivery to a remote domain |
 | [event_loop](/momentum/4/config/ref-event-loop) | associate a pool of event loops within a listener scope to use multiple threads |
 | [eventloop](/momentum/4/config/ref-eventloop) | define a pool of event loops to enable multiple event loop configuration |
 | [events_per_iter](/momentum/4/config/ref-events-per-iter) | employ when using a concurrency greater than 1. |
@@ -136,6 +138,8 @@ description: "This chapter provides the definitions of the configuration options
 | [migrate_connections_between_sibling_domains](/momentum/4/config/ref-migrate-connections-between-sibling-domains) | optimize connections for sibling domains |
 | [mime_parse_large_messages_during_reception](/momentum/4/config/ref-mime-parse-large-messages-during-reception) | configure whether large messages are parsed upon reception or just in time. |
 | [min_dns_ttl](/momentum/4/config/ref-min-dns-ttl) | override DNS TTLs smaller than this value |
+| [mta_sts_dns_cname_max_depth](/momentum/4/config/mta-sts/mta-sts-dns-cname-max-depth) | the maximum number of continuous CNAME lookups while doing MTA-STS DNS TXT lookup |
+| [mta_sts_policy_store](/momentum/4/config/mta-sts/mta-sts-policy-store) | the directory to store MTA-STS policy files |
 | [mx_failures_fallback_to_a](/momentum/4/config/ref-mx-failures-fallback-to-a) | configure the maximum number of times an MX lookup will be attempted |
 | [mx_failures_to_delay](/momentum/4/config/ref-mx-failures-to-delay) | number of consecutive failures before a domain is auto-delayed |
 | [never_attempt_expired_messages](/momentum/4/config/ref-never-attempt-expired-messages) | Never attempt delivery of expired messages |
@@ -217,16 +221,19 @@ description: "This chapter provides the definitions of the configuration options
 | [tls_verified_peer_is_authorized](/momentum/4/config/tls-verified-peer-is-authorized) | Marks requests that use a verified SSL Client certificate as being authorized |
 | [tls_verify](/momentum/4/config/tls-verify) | specify how to handle the remote presented certificate |
 | [tls_verify_mode](/momentum/4/config/tls-verify-mode) | determine whether a TLS certificate is required |
+| [tlsa_expire_interval](/momentum/4/config/tlsa-expire-interval) | how often to check for expired TLSA records |
 | [trace_smtp_mode](/momentum/4/config/ref-trace-smtp-mode) | set the default permissions of trace files |
 | [tracking_domain](/momentum/4/config/tracking-domain) | set the tracking domain to use for engagement tracking in SMTP injections |
 | [tracking_link_expiry](/momentum/4/config/tracking-link-expiry) | set the expiration time for engagement tracking for SMTP injections |
 | [transfail_drain_rate](/momentum/4/config/ref-transfail-drain-rate) | the maximum number of messages to pop off the transient failure queue in a single scheduler iteration |
 | [transform_8bitmime_content](/momentum/4/config/ref-transform-8-bitmime-content) | Enable 8BITMIME downconversion when sending mail |
 | [unlink_on_spool_in_failure](/momentum/4/config/ref-unlink-on-spool-in-failure) | Whether or not to remove malformed messages |
 | [_unsafe_spool](/momentum/4/config/ref-unsafe-spool) | allow dangerous spool semantics to be used |
+| [use_dane](/momentum/4/config/use-dane) | enable DNSSEC validation on MX/A records, if both secure, TLSA record is fetched and DNSSEC validation is done for a domain |
 | [use_iflist_cache](/momentum/4/config/ref-use-iflist-cache) | Whether or not to cache the list of network interfaces configured by the system |
 | [use_ipv6](/momentum/4/config/ref-use-ipv-6) | Affects the selection of IPv6 hosts in the SMTP client |
 | [use_mmap](/momentum/4/config/ref-use-mmap) | use mmap when spooling messages from disk |
+| [use_mta_sts](/momentum/4/config/mta-sts/use-mta-sts) | fetch MTA-STS policy for a domain |
 | [use_sendfile](/momentum/4/config/ref-use-sendfile) | use sendfile() when sending mail |
 | [user](/momentum/4/config/ref-user) | security: user identity to assume after startup |
 | [xclient](/momentum/4/config/ref-xclient) | use the xclient extension to SMTP for outbound mail |

diff --git a/content/momentum/4/config/mta-sts/enable-mta-sts.md b/content/momentum/4/config/mta-sts/enable-mta-sts.md
@@ -0,0 +1,42 @@
+---
+lastUpdated: "06/01/2024"
+title: "enable_mta_sts"
+description: "config option to enable MTA-STS policy application for outbound mails"
+---
+
+<a name="config.enable-mta-sts"></a>
+## Name
+
+enable_mta_sts — specify whether Momentum should apply MTA-STS policies for outbound emails.
+
+## Synopsis
+
+`enable_mta_sts = "true|false"`
+
+## Description
+
+This option is only effective when [use_mta_sts](/momentum/4/config/mta-sts/use-mta-sts) is `true`
+for a recipient domain.
+This option specifies whether Momentum should try to apply the retrieved MTA-STS policy when sending
+emails to a remote site. See [MTA-STS support in Momentum](/momentum/4/mta-sts) for more details.
+
+
+When this option is `true`, the MTA-STS policy mode will be considered along with the configuration
+ values for [TLS](/momentum/4/config/ref-tls) and [TLS_Verify](/momentum/4/config/tls-verify).
+ The more strict policy will apply:
+
+- When the MTA-STS policy mode is `enforce`, regardless of the
+ values for `TLS` and `TLS_Verify`, Momentum will enforce TLS (equivalent to `TLS = required`) and
+ will fail the delivery upon a failed certificate validation (equivalent to `TLS_Verify = host`).
+- When the MTA-STS policy mode is `testing`, Momentum will apply `TLS = ifavailable` (unless
+ `TLS = required` is specified) and `TLS_Verify = optional` (unless `TLS_Verify = host` is
+ specified).
+- When the MTA-STS policy mode is `none`, the policy will be ignored and the configuration values for
+ `TLS` and `TLS_Verify` will be respected.
+
+The default value is `true` when `use_mta_sts` is `true` for a domain.
+
+
+## Scope
+
+`enable_mta_sts` is valid in the domain, binding, binding_group, and global scopes.
diff --git a/content/momentum/4/config/mta-sts/index.md b/content/momentum/4/config/mta-sts/index.md
@@ -0,0 +1,14 @@
+---
+lastUpdated: "06/01/2024"
+title: "Category File"
+type: "custom"
+name: "MTA-STS Configuration Options Reference"
+description: "MTA-STS configuration Options index"
+---
+
+- [use_mta_sts](/momentum/4/config/mta-sts/use-mta-sts)
+- [enable_mta_sts](/momentum/4/config/mta-sts/enable-mta-sts)
+- [mta_sts_dns_cname_max_depth](/momentum/4/config/mta-sts/mta-sts-dns-cname-max-depth)
+- [mta_sts_policy_store](/momentum/4/config/mta-sts/mta-sts-policy-store)
+
+