-
Notifications
You must be signed in to change notification settings - Fork 36
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
add support pages for MTA-STS in Momentum
- Loading branch information
Showing
5 changed files
with
209 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,31 @@ | ||
--- | ||
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 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. |
31 changes: 31 additions & 0 deletions
31
content/momentum/4/config/mta-sts/mta-sts-dns-cname-max-depth.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,29 @@ | ||
--- | ||
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 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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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) |