MTA-STS
Hedwig implements MTA-STS (RFC 8461) on the sending side. When delivering outbound email, Hedwig automatically looks up recipient domain TLS policies and enforces them — preventing STARTTLS downgrade attacks and MX impersonation.
MTA-STS is always active. No configuration is needed. A valid, unexpired
enforce policy requires authenticated TLS. Otherwise, outbound delivery uses
opportunistic TLS as described in RFC 3207:
Hedwig uses STARTTLS when offered, accepting self-signed, expired, or
hostname-mismatched certificates. If STARTTLS is not offered, delivery proceeds
in plaintext. An actual TLS handshake failure still defers delivery; Hedwig
does not reconnect in plaintext after a failed handshake.
The server must still present a parseable X.509 v3 certificate and support a
compatible TLS 1.2 or later connection; relaxing certificate verification does
not enable older TLS versions or malformed certificates.
Opportunistic TLS encrypts traffic against passive eavesdropping, but does not authenticate the receiving server or prevent an active attacker from stripping STARTTLS. Hedwig does not currently implement DANE; MTA-STS is its mechanism for requiring authenticated outbound TLS.
How it works
When Hedwig delivers mail to a recipient domain (e.g. gmail.com):
- DNS lookup — checks for a
_mta-sts.gmail.comTXT record - Policy fetch — downloads the policy from
https://mta-sts.gmail.com/.well-known/mta-sts.txt - MX validation — verifies that each MX server matches the policy’s allowed patterns
- TLS selection — requires valid, PKIX-authenticated TLS for
enforcepolicies; otherwise uses opportunistic TLS
Policy modes
Recipient domains publish their policy in one of three modes:
| Mode | Behavior |
|---|---|
| enforce | MX servers that don’t match the policy are skipped. STARTTLS and a trusted, unexpired certificate matching the MX hostname are required. Failures defer delivery and remain subject to the queue’s retry limit. |
| testing | MX mismatches are logged as warnings. Delivery uses opportunistic TLS. Certificate validation is not enforced or reported via TLSRPT. |
| none | No enforcement — delivery uses opportunistic TLS. |
Connection pools are separated by MX hostname and TLS mode. Domains sharing an
MX cannot cause an enforced delivery to reuse an unauthenticated connection,
and newly enforced policies use a separate pool. outbound_local = true skips
TLS for development only when no enforce policy applies.
Caching
Policies are cached only in memory to avoid repeated DNS and HTTPS lookups:
- Cache respects each policy’s
max_age(TTL set by the recipient domain) - The cache holds up to 10,000 policy domains; capacity pressure can evict policies before
max_age, and a process restart loses all cached policies - While an unexpired
enforcepolicy remains in the cache, it stays mandatory even if DNS or policy refresh fails - A background task checks cached
enforceandtestingpolicy TXT identifiers every hour and fetches updated policies when identifiers change nonepolicies are not refreshed proactively; a switch toenforceis discovered only after cache expiry, eviction, or restart- If a fresh policy can’t be fetched, an existing, unexpired cached version is used
- Failed fetches trigger a 5-minute cooldown before retrying
On a cache miss, including after restart or capacity eviction, Hedwig attempts policy discovery again. If discovery or fetching fails and no valid cached policy remains, delivery uses opportunistic TLS. An active attacker who blocks discovery in this state can prevent enforcement; policies are not persisted across restarts.
Major providers with MTA-STS
Most major email providers publish MTA-STS policies:
| Provider | Mode | max_age |
|---|---|---|
| Gmail | enforce | 1 day |
| Outlook / Hotmail | enforce | 7 days |
| Microsoft | enforce | 7 days |
| ProtonMail | enforce | 7 days |
| Yahoo | testing | 1 day |
| Fastmail | testing | 1 day |
Metrics
When metrics are enabled, Hedwig exports MTA-STS counters:
hedwig_mta_sts_policy_fetch_total{result}— policy fetch attempts (success,failure,cached)hedwig_mta_sts_enforcement_total{mode,result}— enforcement decisions (pass,fail) by modehedwig_mta_sts_cache_size— number of cached policies
Verify it’s working
Check the logs for MTA-STS activity:
# Policy fetched and cached
INFO cached MTA-STS policy domain=gmail.com mode=enforce max_age=86400
# Enforce mode: MX validated
DEBUG MTA-STS policy found domain=gmail.com mode=enforce
# Testing mode: would-be failure logged
WARN MTA-STS testing: MX host does not match policy domain=example.com mx=bad.example.com
Or query the Prometheus metrics:
curl -s http://localhost:9090/metrics | grep mta_sts