EOP-164: add support pages for MTA-STS in Momentum (#760)

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 |

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 |
@@ -365,6 +368,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 |

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.

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 |

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.

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)
+
+

content/momentum/4/config/mta-sts/mta-sts-dns-cname-max-depth.md

@@ -0,0 +1,31 @@
+---
+lastUpdated: "06/01/2024"
+title: "mta_sts_dns_cname_max_depth"
+description: "config option on how many continuous CNAME lookups are allowed when doing MTA-STS TXT
+record lookup for a domain"
+---
+
+<a name="config.mta-sts-dns-cname-max-depth"></a>
+## Name
+
+mta_sts_dns_cname_max_depth — specifies how many continuous `CNAME` lookups are allowed when doing DNS
+ lookups for MTA-STS TXT record for a domain. Exceeding the configured value will be treated as a DNS
+ lookup failure, which will be further treated as no MTA-STS policy available.
+
+## Synopsis
+
+`mta_sts_dns_cname_max_depth = 5`
+
+## Description
+
+Momentum supports MTA-STS policy delegation, which points the `_mta-sts` TXT record for the policy
+ domain via `CNAME` (to the `_mta-sts` record maintained by the provider). Momentum's DNS lookup
+ will follow the `CNAME`s. To avoid a DNS lookup loop, Momentum uses this config option to limit how
+ many continuous `CNAME` lookups can happen before claiming a lookup failure.
+
+The default value is `5`.
+
+
+## Scope
+
+`mta_sts_dns_cname_max_depth` is valid in the domain and global scopes.

content/momentum/4/config/mta-sts/mta-sts-policy-store.md

@@ -0,0 +1,27 @@
+---
+lastUpdated: "06/01/2024"
+title: "mta_sts_policy_store"
+description: "the location to store the MTA-STS policy"
+---
+
+<a name="config.mta-sts-policy-store"></a>
+## Name
+
+mta_sts_policy_store — specifies the location to keep the MTA-STS policy details for the domains.
+
+## Synopsis
+
+`mta_sts_policy_store = "/var/spool/ecelerity/mtasts"`
+
+## Description
+
+Momentum stores MTA-STS policy for a domain in a file on disk, and accesses the HTTPS endpoint to refresh the
+ policy once every 24 hours. This config option specifies the directory where the policies are stored
+ on the disk.
+
+The default value is `/var/spool/ecelerity/mtasts`.
+
+
+## Scope
+
+`mta_sts_policy_store` is valid in the global scope.

content/momentum/4/config/mta-sts/use-mta-sts.md

@@ -0,0 +1,27 @@
+---
+lastUpdated: "06/01/2024"
+title: "use_mta_sts"
+description: "config option to enable MTA-STS policy fetching for a domain"
+---
+
+<a name="config.use-mta-sts"></a>
+## Name
+
+use_mta_sts — specify whether Momentum should do MTA-STS policy fetching for a domain.
+
+## Synopsis
+
+`use_mta_sts = "true|false"`
+
+## Description
+
+This option specifies whether Momentum shall attempt to discover the recipient domain's MTA-STS
+ policy (via a DNS TXT lookup to retrieve the MTA-STS policy ID and a HTTPS lookup to retrieve the
+ MTA-STS policy).
+
+The default value is `false`.
+
+
+## Scope
+
+`use_mta_sts` is valid in the domain and global scopes.

content/momentum/4/config/ref-debug-flags.md

@@ -28,11 +28,21 @@ Debug_Flags {
         CRITICAL = (TIME FD SMTP LOG1 DNS DNSDS NET SIG MEM DB LIC SSL MOD START ALL)
 }
 ```
-
 ### Note
-
 Use ‘`ALL`’ instead of listing each service debug flag.
 
+
+The example below enables more (at `WARNING` level) MTA-STS and SSL related logging, along with default
+`ERROR` and `CRITICAL` loggings:
+```
+Debug_Flags {
+    WARNING = (MTA_STS SSL)
+    ERROR = (ALL)
+    CRITICAL = (ALL)
+}
+```
+
+
 <a name="conf.ref.debug.levels"></a> 
 
 
@@ -55,8 +65,10 @@ Use ‘`ALL`’ instead of listing each service debug flag.
 | File Descriptors | FD |
 | SMTP | SMTP |
 | LOG1 | LOG1 |
+| DANE | DANE |
 | DNS | DNS |
 | DNS data structures | DNSDS |
+| MTA-STS | MTA_STS |
 | Network | NET |
 | Signals | SIG |
 | Memory Management | MEM |
@@ -69,4 +81,4 @@ Use ‘`ALL`’ instead of listing each service debug flag.
 <a name="idp24068272"></a> 
 ## Scope
 
-debug_flags is valid in the global scope.
+debug_flags is valid in the global scope.

content/momentum/4/config/tlsa-expire-interval.md

@@ -0,0 +1,26 @@
+---
+lastUpdated: "06/01/2024"
+title: "tlsa_expire_interval"
+description: "tlsa expire interval how often to check for expired TLSA DNS records"
+---
+
+## Name
+
+tlsa_expire_interval — how often to check for expired TLSA records
+
+## Synopsis
+
+`tlsa_expire_interval = 3600`
+
+## Description
+
+How often the garbage collector should check for expired TLSA records. During email delivery,
+ a related TLSA record will be checked for expiration and removed from memory if expired.
+ The purpose of garbage collection controlled by this configuration option is to retire
+ the stale TLSA records which are not actively in use.
+
+The default is `3600` seconds.
+
+## Scope
+
+`tlsa_expire_interval` is valid in the global scope.

content/momentum/4/config/use-dane.md

@@ -0,0 +1,30 @@
+---
+lastUpdated: "06/01/2024"
+title: "use_dane"
+description: "config option to enable DANE TLSA DNS lookup for a domain"
+---
+
+<a name="config.use-dane"></a>
+## Name
+
+use_dane — specify whether Momentum should check DNS record DNSSEC status and look up TLSA
+ records if applicable.
+
+## Synopsis
+
+`use_dane = "true|false"`
+
+## Description
+
+This option is only effective when [dane module](/momentum/4/modules/dane) is configured.
+
+This option specifies whether Momentum shall check the DNSSEC status of a domain's MX and A record,
+ and if both pass DNSSEC validation, corresponding TLSA record will be fetched and DNSSEC status
+ checked.
+
+The default value is `false`.
+
+
+## Scope
+
+`use_dane` is valid in the domain and global scopes.