EOP-164: add support pages for MTA-STS in Momentum

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 on outbound email sending
+
+## 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. E.g. When the MTA-STS policy mode is `enforce`, regardless 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 the domain level `use_mta_sts` is `true`.
+
+
+## Scope
+
+`enable_mta_sts` is valid in the binding, binding_group, domain and global scopes.

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 continous 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 continous 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_dns_cname_max_depth` 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 or not
+
+## 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

@@ -57,6 +57,7 @@ Use ‘`ALL`’ instead of listing each service debug flag.
 | LOG1 | LOG1 |
 | DNS | DNS |
 | DNS data structures | DNSDS |
+| MTA-STS | MTA_STS |
 | Network | NET |
 | Signals | SIG |
 | Memory Management | MEM |
@@ -69,4 +70,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/console-commands/mta-sts.md

@@ -0,0 +1,53 @@
+---
+lastUpdated: "06/01/2024"
+title: "mta_sts"
+description: "mta_sts ec_console commands" 
+---
+
+<a name="console_commands.mta-sts"></a>
+## Name
+
+mta_sts - commands for MTA-STS related data
+
+## Synopsis
+
+`mta_sts list all`
+
+`mta-sts show domain {domain name}`
+
+`mta-sts refresh policy {domain name}`
+
+## Description
+
+**mta_sts list all**     - lists all the active domains which have MTA-STS policies
+
+```
+15:42:38 /tmp/2025> mta_sts list all
+gmail.com
+Total domains: 1
+```
+
+**mta-sts show domain { domain name }**     - shows MTA-STS TXT record and policy details of a given domain.
+ The same content will show in [domain](/momentum/4/console-commands/domain) command output also if
+ available.
+
+
+```
+18:13:43 /tmp/2025> mta_sts show domain gmail.com
+Domain 'gmail.com' has MTA-STS TXT and a TTL of 185 seconds
+        id: 20190429T010101
+        max_age: 86400 seconds; refresh in 86375 seconds
+        mode: enforce
+        mxlist:
+               gmail-smtp-in.l.google.com
+               gmail-smtp-in.l.google.com
+```
+
+**mta-sts refresh policy {domain name}**     - forces MTA-STS policy refresh by fetching the policy
+ from the HTTPS endpoint for a given domain
+
+
+```
+18:14:41 /tmp/2025> mta_sts refresh policy gmail.com
+MTA-STS policy for gmail.com refreshed.
+```

content/momentum/4/mta-sts.md

@@ -0,0 +1,99 @@
+---
+lastUpdated: "06/01/2024"
+title: "MTA-STS support in Momentum"
+description: "MTA-STS support in Momentum"
+---
+
+MTA-STS (MTA Strict Transport Security) improves email security by requiring authentication
+checks and encryption for delivering email.  RFC 8461 describes the use of MTA-STS for improving
+SMTP security between MTAs.
+
+If the per-domain config option [use_mta_sts](/momentum/4/config/mta-sts/use-mta-sts) is set to `true`,
+ Momentum will attempt to discover the recipient domain's MTA-STS policy
+ (via a DNS lookup to retrieve the MTA-STS policy ID and a HTTPS lookup to retrieve the
+  MTA-STS policy) and use it for validating the connection to the remote site.
+ If the recipient domain enforces MTA-STS, Momentum delivers email to the remote
+domain's MX if and only if the following conditions are satisfied:
+ - remote site matches at least one of the MX patterns defined in the recipient domain's MTA-STS
+   policy
+ - connection to remote site can be encrypted (via the use of STARTTLS)
+ - Momentum can authenticate both - the certificate chain presented by the server on the connection
+   and the server name in the certificate
+
+For verifying certificates, Momentum uses the configured CA for outbound email defined by
+ [TLS_CA](/momentum/4/config/tls-ca).
+ Momentum does not currently check for certificate revocation via the Online Certificate Status
+Protocol (RFC 6960).
+
+Momentum caches the MTA-STS policy for up to `max-age` specified in the policy, and attempts to
+refresh the cached policy once every 24 hours.
+
+Momentum does not currently implement SMTP TLS Reporting (RFC 8460).
+
+The examples below illustrate a few cases describing how Momentum implements MTA-STS.
+For all examples the recipient domain would be `domain.com`.
+
+### Example 1: Recipient domain enforces MTA-STS and MX is allowed as per the MTA-STS policy
+
+> **MTA-STS policy retrieved from https://mta-sts.domain.com/.well-known/mta-sts.txt**
+```
+version: STSv1
+mode: enforce
+mx: *.domain.com
+max_age: 86400
+```
+> **DNS results for domain's MX lookup**
+```
+mx1.domain.com
+```
+> **Explanation**
+> Momentum attempts to deliver email to `mx1.domain.com` as it matches at least one of the
+MX patterns defined in the MTA-STS policy.
+
+### Example 2: Recipient domain enforces MTA-STS and MX is not allowed as per the MTA-STS policy
+
+> **MTA-STS policy retrieved from https://mta-sts.domain.com/.well-known/mta-sts.txt**
+```
+version: STSv1
+mode: enforce
+mx: *.domain.com
+max_age: 86400
+```
+> **DNS results for domain's MX lookup**
+```
+mx1.other.com
+```
+> **Explanation**
+> Momentum does not attempt to deliver email to `mx1.other.com` as it does not match any of the
+MX patterns defined in the MTA-STS policy.
+
+### Example 3: Recipient domain does not enforce MTA-STS and MX is not allowed as per the MTA-STS
+policy
+
+> **MTA-STS policy retrieved from https://mta-sts.domain.com/.well-known/mta-sts.txt**
+```
+version: STSv1
+mode: testing
+mx: *.domain.com
+max_age: 86400
+```
+> **DNS results for domain's MX lookup**
+```
+mx1.other.com
+```
+> **Explanation**
+> Momentum attempts to deliver email to `mx1.other.com` even though it does not match any of the
+MX patterns defined in the MTA-STS policy since the policy mode is not `enforce`.
+
+
+## Related Configuration Options
+- [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)
+
+## Related [Debug_Flags](/momentum/4/config/ref-debug-flags)
+- MTA_STS
+
+## ec_console commands
+- [mta_sts](/momentum/4/console-commands/mta-sts)

content/momentum/navigation.yml

@@ -511,6 +511,8 @@
           title: Sending Emails as CC and BCC
         - link: /momentum/4/complex-template
           title: Using Complex Templates
+    - link: /momentum/4/mta-sts
+      title: MTA-STS support
     - link: /momentum/4/http-api-stats
       title: Stats HTTP API
       items:
@@ -2007,4 +2009,4 @@
         - link: /momentum/changelog/legacy/message-central
           title: Message Central Legacy Changelog
         - link: /momentum/changelog/legacy/message-scope
-          title: Message Scope Legacy Changelog
+          title: Message Scope Legacy Changelog