diff --git a/content/momentum/4/config/mta-sts/enable-mta-sts.md b/content/momentum/4/config/mta-sts/enable-mta-sts.md new file mode 100644 index 00000000..701539ba --- /dev/null +++ b/content/momentum/4/config/mta-sts/enable-mta-sts.md @@ -0,0 +1,31 @@ +--- +lastUpdated: "06/01/2024" +title: "enable_mta_sts" +description: "config option to enable MTA-STS policy application for outbound mails" +--- + + +## 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 specified whether Momentum try to apply the retrieved MTA-STS policies when sending +emails to a remote site. See [mta-sts](/momentum/4/mta-sts) for more details. +When this option is `true`, the MTA-STS policy mode will take the preference over the config options + of [TLS](/momentum/4.config/tls) and [TLS_Verify](/momentum/4/config/tls-verify), unless the + MTA-STS policy mode is `none`. + +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. diff --git a/content/momentum/4/config/mta-sts/mta-sts-dns-cname-max-depth.md b/content/momentum/4/config/mta-sts/mta-sts-dns-cname-max-depth.md new file mode 100644 index 00000000..563b8ac0 --- /dev/null +++ b/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" +--- + + +## 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. diff --git a/content/momentum/4/config/mta-sts/mta-sts-policy-store.md b/content/momentum/4/config/mta-sts/mta-sts-policy-store.md new file mode 100644 index 00000000..662d6d26 --- /dev/null +++ b/content/momentum/4/config/mta-sts/mta-sts-policy-store.md @@ -0,0 +1,29 @@ +--- +lastUpdated: "06/01/2024" +title: "mta_sts_policy_store" +description: "the location to store the MTA-STS policy" +--- + + +## Name + +mta_sts_policy_store — 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_policy_store = "/var/spool/ecelerity/mtasts"` + +## Description + +Momentum stores MTA-STS policy for a domain in 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. diff --git a/content/momentum/4/config/mta-sts/use-mta-sts.md b/content/momentum/4/config/mta-sts/use-mta-sts.md new file mode 100644 index 00000000..7640fd60 --- /dev/null +++ b/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" +--- + + +## 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 specified whether Momentum shall 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) + +The default value is `false`. + + +## Scope + +`use_mta_sts` is valid in the domain and global scopes. diff --git a/content/momentum/4/mta-sts.md b/content/momentum/4/mta-sts.md new file mode 100644 index 00000000..498a225c --- /dev/null +++ b/content/momentum/4/mta-sts.md @@ -0,0 +1,91 @@ +--- +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 server name in the certificate + +For verifying certificates, Momentum use 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/coonfig/mta-sts/enable-mta-sts)