From 4d9b8f9a4be24851d0e8da180980d7d5b5acf0b9 Mon Sep 17 00:00:00 2001
From: Maxime Labelle <springcomp@users.noreply.github.com>
Date: Thu, 20 Jul 2023 18:26:06 +0200
Subject: [PATCH] Documented MTA-STS and TLSRPT (#1806)

---
 docs/ssl.md | 101 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 100 insertions(+), 1 deletion(-)

diff --git a/docs/ssl.md b/docs/ssl.md
index 1114c4df..b32bbf14 100644
--- a/docs/ssl.md
+++ b/docs/ssl.md
@@ -1,4 +1,4 @@
-# SSL, HTTPS, and HSTS
+# SSL, HTTPS, HSTS and additional security measures
 
 It's highly recommended to enable SSL/TLS on your server, both for the web app and email server.
 
@@ -58,3 +58,102 @@ Now, reload Nginx:
 ```bash
 sudo systemctl reload nginx
 ```
+
+## Additional security measures
+
+For additional security, we recommend you take some extra steps.
+
+### SMTP MTA Strict Transport Security (MTA-STS)
+
+[MTA-STS](https://datatracker.ietf.org/doc/html/rfc8461) is an extra step you can take to broadcast the ability of your instance to receive and, optionally enforce, TSL-secure SMTP connections to protect email traffic.
+
+Enabling MTA-STS requires you serve a specific file from subdomain `mta-sts.domain.com` on a well-known route.
+
+Create a text file `/var/www/.well-known/mta-sts.txt` with the content:
+
+```txt
+version: STSv1
+mode: testing
+mx: app.mydomain.com
+max_age: 86400
+```
+
+It is recommended to start with `mode: testing` for starters to get time to review failure reports. Add as many `mx:` domain entries as you have matching **MX records** in your DNS configuration.
+
+Create a **TXT record** for `_mta-sts.mydomain.com.` with the following value:
+
+```txt
+v=STSv1; id=UNIX_TIMESTAMP
+```
+
+With `UNIX_TIMESTAMP` being the current date/time.
+
+Use the following command to generate the record:
+
+```bash
+echo "v=STSv1; id=$(date +%s)"
+```
+
+To verify if the DNS works, the following command
+
+```bash
+dig @1.1.1.1 _mta-sts.mydomain.com txt
+```
+
+should return a result similar to this one:
+
+```
+_mta-sts.mydomain.com.	3600	IN	TXT	"v=STSv1; id=1689416399"
+```
+
+Create an additional Nginx configuration in `/etc/nginx/sites-enabled/mta-sts` with the following content:
+
+```
+server {
+	server_name mta-sts.mydomain.com;
+	root /var/www;
+	listen 80;
+
+	location ^~ /.well-known {}
+}
+```
+
+Restart Nginx with the following command:
+
+```sh
+sudo service nginx restart
+```
+
+A correct configuration of MTA-STS, however, requires that the certificate used to host the `mta-sts` subdomain matches that of the subdomain referred to by the **MX record** from the DNS. In other words, both `mta-sts.mydomain.com` and `app.mydomain.com` must share the same certificate.
+
+The easiest way to do this is to _expand_ the certificate associated with `app.mydomain.com` to also support the `mta-sts` subdomain using the following command:
+
+```sh
+certbot --expand --nginx -d app.mydomain.com,mta-sts.mydomain.com
+```
+
+## SMTP TLS Reporting
+
+[TLSRPT](https://datatracker.ietf.org/doc/html/rfc8460) is used by SMTP systems to report failures in establishing TLS-secure sessions as broadcast by the MTA-STS configuration.
+
+Configuring MTA-STS in `mode: testing` as shown in the previous section gives you time to review failures from some SMTP senders.
+
+Create a **TXT record** for `_smtp._tls.mydomain.com.` with the following value:
+
+```txt
+v=TSLRPTv1; rua=mailto:YOUR_EMAIL
+```
+
+The TLSRPT configuration at the DNS level allows SMTP senders that fail to initiate TLS-secure sessions to send reports to a particular email address.  We suggest creating a `tls-reports` alias in SimpleLogin for this purpose.
+
+To verify if the DNS works, the following command
+
+```bash
+dig @1.1.1.1 _smtp._tls.mydomain.com txt
+```
+
+should return a result similar to this one:
+
+```
+_smtp._tls.mydomain.com.	3600	IN	TXT	"v=TSLRPTv1; rua=mailto:tls-reports@mydomain.com"
+```