Use this template to host your MTA Strict Transport Security (MTA-STS) [RFC 8461] policy file on GitHub Pages.
How To Use • License • Author (https://github.com/jpawlowski)
MTA-STS is a security standard to secure e-mail delivery. E-mail servers that send inbound e-mail to your domain will be able to detect that your e-mail server supports SMTP-over-TLS via STARTTLS
(also known as Opportunistic TLS) before opening the actual connection.
In case the sending e-mail server is not able to initiate a secure connection, it will end the connection to enforce transport layer encryption. This mitigates Man-in-the-middle DNS and SMTP downgrade attacks that would allow an attacker to read or manipulate e-mail in transit.
-
Make sure you are signed in to GitHub. Then click on Use this template to create a copy to your own GitHub profile (see GitHub Docs). Don't clone the repository. You may name your repository whatever you like. For simplicity, you can name it
mta-sts.<your_domain.tld>
. -
Change the file
.well-known/mta-sts.txt
according to your needs. -
Create a
CNAME
record formta-sts.<your_domain.tld>
in your domain's DNS that points to<user>.github.io
or<organization>.github.io
and enable GitHub Pages. -
Open a browser to
https://mta-sts.<your_domain.tld>
and make sure it does not show any certificate warnings. -
Create a
TXT
record for_mta-sts.<your_domain.tld>
in your domain's DNS to enable the MTA-STS policy for your domain. You may copy & paste this to your DNS provider:#HOST #TTL #TYPE #VALUE _mta-sts 3600 TXT "v=STSv1; id=20220317000000Z"
Note that you will need to change the
id=
here whenever you make changes to yourmta-sts.txt
policy file. -
Validate your setup, for example by using the MTA-STS validator created by @aykevl.
Optional (but highly recommended):
-
Create another
TXT
record for_smtp._tls.<your_domain.tld>
in your domain's DNS to enable reporting (see RFC 8460). You may copy & paste this to your DNS provider:#HOST #TTL #TYPE #VALUE _smtp._tls 3600 TXT "v=TLSRPTv1; rua=mailto:tls-rua@mailcheck.<your_domain.tld>"
Note that the e-mail recipient mailbox shall be on a different domain without MTA-STS being configured. It is also quite painful to manually deal with the reports other e-mail providers will send to you. For that particular reason, you may want to consider sending these e-mails to a 3rd-party tool like Report URI, URIports, or from other commercial providers.
You probably want this to be the same tool you might use for DMARC reports, like DMARC Analyzer or Dmarcian.
-
Follow steps 1. to 3 above. My project naming convention was subtly different being
mta-sts.<your_fully_qualified_domain_name>
. Before proceeding to step 4 above, it is important to get the Custom domain configured: -
From
https://github.com/<user>/mta-sts.<your_fully_qualified_domain_name>
project navigate to Settings then Pages. Under Custom domain entermta-sts.<your_fully_qualified_domain_name>
as the custom domain name then press Save. Wait until the DNS check is successful. Investigate issues with your DNS service otherwise. -
Once the DNS test is successful Github will generate an SSL certificate for this URL. Once that is complete you may check the "Enforce HTTPS" box. Refresh the page and note that GitHub Pages now references the correct URL using HTTPS. Select "Visit site". This should show the mta-sts.txt file. Proceed to step 4 above once this is successful.
-
Within your project edit the file
.well-known/mta-sts.txt
, remove all comments etc. Initially set the mode totesting
. Do not reducemax_age
below 1 week. This is the recommended minimum time, once stable you could be pro active and increase this time. Switch mode toenforce
once you are confident MTA-STS is working. -
I use Mailahrdener for my free email system monitoring service: (https://www.mailhardener.com/kb/mta-sts) My only issues with email result from HotMail (Microsoft Outlooks) reputation algorithms where I get hit from being within a larger pool of IP addresses or low volume mail.
julian.pawlowski.me · GitHub @jpawlowski · Twitter @Loredo