Set up TLS-RPT and MTA-STS

When TLS-RPT is enabled, email-sending services know where to send automated reports about TLS connections failures. The recipients of the reports can then assess and fix any potential issues. TLS-RPT will give you more assurances to progress to an MTA-STS policy of “enforce”.

Set up TLS-RPT and MTA-STS

1. Set up TLS-RPT and start monitoring (before you start your MTA-STS journey)

Create a DNS entry called the ‘TLS-RPT reporting policy’. This DNS record signals that your domain has a TLS-RPT reporting policy and where sender services should send the TLS-RPT reports. This is a ‘TXT’ record.

The NCSC Mail Check tool has built-in support for TLS-RPT to simplify the analysis of reports. Create a DNS entry like the following example (replacing example.gov.uk with your domain):

For a live example, take a look at the ncsc.gov.uk TLS-RPT reporting policy record.

The detailed specification for TLS-RPT is available in RFC8460.

2. Create and publish your initial MTA-STS policy file in testing mode

Create an MTA-STS policy file in testing mode. You will need to create an MTA-STS policy file (a .txt file) following the template in the example testing policy table below. You must substitute information from your own organisation.

You need to save the policy file as “mta-sts.txt”.

We recommend using a basic text editor such as Notepad on Windows to create this file because this will automatically insert the CRLF at the end of each line as specified in the RFC. It’s also important to check there are no extra spaces on lines or extra carriage returns at either the top or the bottom of the file. Both of these can cause the policy to fail.

Do not use wildcard MX records such as *.example.gov.uk. This negates what MTA-STS is designed to protect. Use the fully qualified domain names (FQDN) in your MX records of your DNS.

version: STSv1
mode: testing
mx: mx1.example.gov.uk
mx: mx2.example.gov.uk
max_age: 86401

Example testing policy table

Recommended settings	Definition
version: STSv1	This must be the first line and must contain the value STSv1 for this policy file to be valid.
mode: testing	mode: testing; monitoring mode MTA-STS is used, but the sending server can fall back to plain text in case of TLS failure. A report will be sent if TLS-RPT is enabled.
mx: mx1.example.gov.uk mx: mx2.example.gov.uk	List your mail hosts, one on each line of the file.
max_age: 86401	The max_age field in seconds is the maximum permissible time that a sending email service can cache the policy. In testing mode – we recommend setting this to 24 hours and one second (86401 seconds).

For a live example, see ncsc.gov.uk MTA-STS Policy file.

3. Choose a supplier to publish your MTA-STS policy file

You will need to decide on a suitable method to host a MTA-STS policy file online. The policy file must be publicly readable by HTTPS so it will need a certificate. Make sure the URL where you store your policy file is in the following format (replacing example.gov.uk with your domain)

https://mta-sts.example.gov.uk/.well-known/mta-sts.txt

You can host multiple copies of the policy file in different locations to increase resilience. In this case, you would need different hosting solutions that each provide access via an IP address for the file. These would likely be stored as multiple “A” or “AAAA” records in your DNS.

When deciding on your hosting approach be aware section 3.3 of the MTA-STS RFC8461 standard states that if your policy file is not available then it will not block you from receiving emails. The standard is designed to fail ‘open’ and follow the protections listed in the RFC.

Supplier Option 1 – Put it on your domain(s) website

Create a .well-known folder at the root of your website.
Put the MTA-STS.txt file into this folder.
Add an A record in your DNS pointing to your website called mta-sts.example.gov.uk (replacing example.gov.uk with your domain name).

If your website is controlled via ‘source control’ for example, on GitHub, you must add this folder and file to this ‘source control’ so it will not be accidentally removed when the website updates.

Supplier option 2 – Amazon Web Services (AWS) Single domain solution

Amazon allows “Hosting a static website using Amazon S3” and uses the following components:

• Amazon S3

• Amazon CloudFront

• Amazon Route 53 (if your domain is hosted with Amazon)

There is an official Amazon guide for setting up their single domain solution. You will need Amazon CloudFront because Amazon S3 website endpoints do not support HTTPS. There is more information about using Amazon CloudFront in the Amazon knowledge centre .

This will provide you with a fully qualified domain name (FQDN) that you assign to your DNS as a “CNAME” record called mta-sts.example.gov.uk (replacing example.gov.uk with your domain name).

Supplier option 3 – Cloudflare single domain solution

If you’re already using Cloudflare, the easiest way to host your MTA-STS policy file is by using the Workers facility.

Cloudflare offers a free platform you can use for testing even if you’re not a customer. It allows you to register a free *.workers.dev domain that your workers can use as an FQDN. There are limits to what the free account can do and you should make sure you understand the terms of use.

Cloudflare will not allow you create a CNAME to the *.workers.dev FQDN unless you manage your domain in Cloudflare, or have a Business or Enterprise account.
Below is an example Cloudflare worker script in JavaScript containing dummy values for an MTA-STS policy file:

addEventListener("fetch", event => { 
  event.respondWith(handleRequest(event.request)) 
}) 

async function handleRequest(request) { 
  return new Response( 
    "version: STSv1rn" + 
    "mode: testingrn" + 
    "mx: your.mail.server.comrn" + 
    "max_age: 86401", 
  { 
    headers: { "content-type": "text/plain" } 
  })
}

The Response string is split up into multiple lines using a ‘+’ to join them. This should make it easier to match to your MTA-STS policy file. The r and n at the end of each line is the JavaScript required to put in a carriage return (CR) and line feed (LF), so you need to leave those in.

If you have more than one MX record then you need to add multiple lines, like in the mta-sts.txt file. We recommend you do this editing in a basic text editor to ensure there are no extra whitespaces or carriage returns.

The Cloudflare documentation instructs you to install Wrangler CLI to access Workers and write code, but for this you can use the simple editor built into the web page. This process is not well documented so we have added steps here to help you.

Go to the Workers & Pages section of your Cloudflare account.
Select “Create application”.
Select “Create Worker”, which will create a default “Hello World” Worker.
Name the new service and it will show how that name adds to your *.workers.dev FQDN.
Select “Deploy”.
Once the Worker has been deployed, select “Edit code” to open the editor built into the web page. This will contain the example code on the left but this can be deleted. This will leave you with just a line number 1.
Paste in the JavaScript code they have supplied here, amended with the details from your MTA-STS policy file.
Select “Save and deploy”.
You should now be able to test your new Cloudflare Worker by putting the *.workers.dev FQDN that you assigned to your Worker into a web browser. Check that the responding web page looks exactly the same as the mta-sts.txt file that you created.
On the main screen for the new Worker, select the “Triggers” tab.
Select “Add Custom Domain”.
Enter the full domain as mta-sts.example.gov.uk (replacing example.gov.uk with your domain name).
Select “Add Custom Domain”.
This will provision the DNS record and issue a HTTPS certificate.

You should now be able to test your new Cloudflare Worker by putting the *.workers.dev FQDN that you assigned to your Worker into a web browser. Check that the responding web page looks exactly the same as the mta-sts.txt file that you created.

It’s imperative that there are no extra spaces or extra carriage returns at either the top or the bottom of the file. Both of these can cause the policy to fail.

This will provide you with an FQDN that you assign to your DNS hosted in Cloudflare as a “CNAME” record called mta-sts.example.gov.uk (replacing example.gov.uk with your domain name).

The final step is to create a route in Cloudflare from your “CNAME” to your Worker. There is more information about Cloudflare guidance on routes.

Cloudflare has an option to provide a static IP address that you can use with this solution as well, but this is only available to their Enterprise account customers.

Supplier option 4 – Google Cloud Platform (GCP) Single domain solution

The Google solution is described as Hosting a Static Website and uses their billable components:

Cloud Storage
Cloud Load Balancing
Cloud CDN

The load balancer is required because Google Storage does not support custom domains with HTTPS on its own.

This will provide you with a static IP address you assign to your DNS as an “A” record called mta-sts.example.gov.uk (replacing example.gov.uk with your domain name).

Supplier option 5 – Microsoft Azure single domain solution

The Microsoft solution is described as Static Website hosting in Azure Storage. You can enable the static website hosting free of charge, but are billed for the blob storage and operations costs. The solution uses the following Azure components:

Azure Storage
Azure CDN

Official Microsoft guides include:

This will provide you with an FQDN that you assign to your DNS as a “CNAME” record called mta-sts.example.gov.uk (replacing example.gov.uk with your domain name).

4. Test that your policy file is visible

This step is crucial to make sure your policy will work properly.

Many mail vendors will only look for the MTA-STS policy file once or twice as soon as the discovery record is visible. If they do not find the policy file, they will back off and sometimes not look again for periods up to 4 weeks. This will delay your MTA-STS implementation as errors will show in the TLS-RPT data.

Check you can view your policy file. This can be done by several methods, including a web browser or a curl command from a Linux command line. This should be tested via multiple ISP connections to ensure your DNS record propagates fully around the internet.

Once you have tested this and the policy file is visible, you should leave 48 hours before adding the policy discovery record to your DNS.

5. Create your MTA-STS policy discovery record

You will need to create a DNS entry called the ‘MTA-STS policy discovery record’. This DNS record signals that your domain has an MTA-STS policy. It is a ‘TXT’ record.

Use this example to create a DNS entry, replacing example.gov.uk with your domain:

Record type	`TXT`
Name	`_mta-sts.example.gov.uk`
Value	`v=STSv1; id=20221012`

When using this example, you will need to choose the ID in the value column. This must change every time you update the policy. Use something simple for the ID, such as a date. The ID can be any alphanumeric value up to 32 characters long, and must uniquely identify that version of the policy.

Whenever the MTA-STS policy is changed, you must change the ID value in the ‘TXT’ record to a new and unique value, which signals that a new policy has been set.

For a live example, take a look at the ncsc.gov.uk MTA Policy Discovery Record.

6. Upgrade MTA-STS policy to “enforce”

Once you have correctly set up MTA-STS in ‘testing’ mode, we recommend monitoring your email traffic for at least 2 weeks to check that there are no failures in your TLS-RPT reports. Make sure to check your TLS-RPT section for your domain in Mail Check.

After 2 weeks, if no failures are showing, you should set up an MTA-STS ‘enforce’ policy. This policy means inbound emails will not be delivered if the connection does not support TLS 1.2 or higher, or TLS certificates are invalid.

As before, we recommend using a basic text editor such as Notepad on Windows to create this file because this will automatically insert the CRLF at the end of each line as specified in the RFC. It’s also important to check there are no extra spaces on lines or extra carriage returns at either the top or the bottom of the file. Both of these can cause the policy to fail.

version: STSv1
mode: enforce
mx: mx1.example.gov.uk
mx: mx2.example.gov.uk
max_age: 1209600

Example enforcement policy table

Recommended settings	Definition
version: STSv1	version: must be the first line and must contain value STSv1 for this policy file to be valid.
mode: enforce	mode: enforce; MTA-STS is used, and the sending server should not deliver if there is a TLS failure. A report will be sent if TLS-RPT is enabled.
mx: mx1.example.gov.uk mx: mx2.example.gov.uk	mx: list your mail hosts, one on each line of the file
max_age: 1209600	max_age: the max_age field in seconds is the maximum permissible time that a sending email service can cache the policy. We recommend this be set to 2 weeks (1209600 seconds) when in enforce mode. This will protect against attacks on DNS or the policy hosting.

Implementing your new enforce policy file

Updating Single domain solution

If you set up your MTA-STS policy using a single domain solution you need to replace the old mta-sts.txt file containing your ‘testing’ policy with the newly created mta-sts.txt file containing your ‘enforce’ policy.

Changes must be made in the correct order to avoid the risk of message delays.

Many cloud storage products have caches which will keep the old version of the file live for a certain amount of time. Always check with your cloud storage provider on what these times are and if they can be reduced while you make the change to speed up the move to the new policy setting.

Replace your “testing” mta-sts.txt file with your new “enforce” mta-sts.txt file in your chosen storage solution.
Wait until your new mta-sts.txt file with the ‘enforce’ policy is visible, by testing the URL in a web browser. You should test this from multiple devices, browsers, and ISP connections to ensure that the change has fully propagated. You may still see the old file and the new file as you refresh. This is normal and means the change is still propagating to all nodes of your cloud storage provider. Wait until this stops and all you see is the new file before moving to step 3.
Once the new mta-sts.txt file appears consistently you can then update the _mta-sts.example.gov.uk (replacing example.gov.uk with your domain) ‘TXT’ DNS record that you created in section 4.

Record type	`TXT`
Name	`_mta-sts.example.gov.uk`
Value	`v=STSv1; id=20221012`

You must change the id in the value column. For this example the original ID was set on 12 October 2022 and in the format YYYYMMDD.

For this update example we want to set the date of the change to be 26 October 2022. This would make the DNS record look like the following with the new ID of 20221026. You can use any value you like for the ID, but using a date helps you keep track of when the change was made.

Record type	`TXT`
Name	`_mta-sts.example.gov.uk`
Value	`v=STSv1; id=20221026`

4. Test your domain using a tool like Hardenize or MailHardener. This should now show your new DNS record with the new ID and your new policy file set to ‘enforce’.

For cloud storage, it may take some time for your DNS change to propagate round to all DNS servers worldwide.

Updating your MTA-STS policy file if you use a multiple domain solution

For any of the multiple domain solutions you will have already set up and hosted both your ‘testing’ and ‘enforce’ policy files because all your domains use the same MX records. Depending on which one you chose you will now have either:

Two IP addresses. One pointing to your ‘testing’ policy file, and one pointing to your ‘enforce’ policy file. Your DNS ‘A’ record mta-sts.example.gov.uk (replacing example.gov.uk with your domain) will be using the IP address pointing to your ‘testing’ policy file.

Two FQDNs. One pointing to your ‘testing’ policy file, and one pointing to your ‘enforce’ policy file. Your DNS ‘CNAME’ record mta-sts.example.gov.uk (replacing example.gov.uk with your domain) will be using the FQDN pointing to your ‘testing’ policy file.

You will now need to change either your DNS ‘A’ record or your DNS ‘CNAME record for mta sts.example.gov.uk (replacing example.gov.uk with your domain) to point to your “enforce” policy file.

As with the single domain solution this sounds simple, but must be done in the correct order to avoid the risk of message delays.

Change your DNS ‘A’ record to point to your IP address for your ‘enforce’ policy file, or your DNS ‘CNAME’ record to point to your FQDN for your ‘enforce’ policy file.
Wait until your new mta-sts.txt file with the “enforce” policy is visible by testing the url via a web browser. You should test this from multiple devices, browsers, and ISP connections to ensure that the change has fully propagated. You may still see the old file and the new file as you refresh. This is normal and means the change is still propagating to all DNS servers worldwide. Wait until this stops and all you see is the new file before moving to step 3.
Only once the new mta-sts.txt file appears consistently can you update the _mta-sts.example.gov.uk (replacing example.gov.uk with your domain) ‘TXT’ DNS record that you created in section 4.

Record type	`TXT`
Name	`_mta-sts.example.gov.uk`
Value	`v=STSv1; id=20221012`

You must change the ID in the value column. For this example the original ID was set on 12 October 2022 and in the format YYYYMMDD.

For this update example, set the date of the change to 26 October 2022. This would make the DNS record look like the following with the new ID of 20221026. You can use any value you like for the ID, but using a date helps you keep track of when the change was made.

Record type	`TXT`
Name	`_mta-sts.example.gov.uk`
Value	`v=STSv1; id=20221026`

Test your domain using a tool like Hardenize or MailHardener. This should now show your new DNS record with the new id and your new policy file set to ‘enforce’. As with step 2 of this list it may take some time for your DNS change to propagate round to all DNS servers worldwide.

Contact us

The Government Security Centre for Cyber (Cyber GSeC) is actively supporting all Central Government organisations to safely deploy MTA-STS and TLS-RPT. In 2022, 93% of all MTA-STS Central Government deployments have been guided by us. Cyber GSeC time to you is free, please get in touch: cybergsec@hmrc.gov.uk

Set up TLS-RPT and MTA-STS