Skip to content

Commit

Permalink
add support pages for MTA-STS in Momentum
Browse files Browse the repository at this point in the history
  • Loading branch information
juliebin committed May 7, 2024
1 parent 462ae0e commit 158b14d
Show file tree
Hide file tree
Showing 5 changed files with 209 additions and 0 deletions.
31 changes: 31 additions & 0 deletions content/momentum/4/config/mta-sts/enable-mta-sts.md
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 content/momentum/4/config/mta-sts/mta-sts-dns-cname-max-depth.md
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.
29 changes: 29 additions & 0 deletions content/momentum/4/config/mta-sts/mta-sts-policy-store.md
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.
27 changes: 27 additions & 0 deletions content/momentum/4/config/mta-sts/use-mta-sts.md
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.
91 changes: 91 additions & 0 deletions content/momentum/4/mta-sts.md
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)

0 comments on commit 158b14d

Please sign in to comment.