STARTTLS(8)

💌 starttls(8) — the glow-up your mail server deserves 💌

okay so this page lives in the System Manager's Manual (yeah, section 8, the big-kid section) and it's all about starttls — ESMTP over TLS/SSL. bestie, if you've ever wondered how your email doesn't get read by randos on the wifi, this is the whole tea. ☕✨

---

✨ NAME ✨

starttls — ESMTP over TLS/SSL 🎀

---

🌸 DESCRIPTION 🌸

so STARTTLS is an ESMTP option, defined in RFC 3207, and it's the thing that lets you run ESMTP transactions over TLS circuits. translation: it makes mail server transactions way more secure. no cap. 🔥

STARTTLS lets you stack several security solutions together for MTA (mail transport agent) level services, all through the TLS suite. the security features include:

🔒 Confidentiality

encryption is used to protect data from passive monitoring. so like, nobody just lurking and reading your stuff. 🙈

🧬 Integrity

hash algorithms are used to ensure the integrity of the transmitted data. this protects data from modification in transit. nobody's editing your mail mid-flight, periodt. 💅

🪪 Authentication

the use of public key encryption allows for the strong authentication of either, or both, communicating parties. this can be used to allow for select features, such as relaying, to be controlled more securely. iykyk. 👑

a new ESMTP option, STARTTLS, has been added. this is presented by the server when an ESMTP session is initiated. the client then begins the TLS portion of the ESMTP session by issuing the command STARTTLS. the remaining portion of the ESMTP session occurs over a TLS channel. literally the main character moment of the whole handshake. 🌈

---

🎀 Creating a private key and certificate for an MTA 🎀

this example assumes you are creating your own self-signed certificates for use with smtpd(8) and STARTTLS. if you have an existing private key and you simply wish to generate a new certificate (for example, if your old certificate has expired), see the section entitled “Creating a certificate with an existing private key”. 🫶

for the purposes of this example the certificates will be stored in /etc/ssl, though it is possible to use a different directory if needed.

next, you must generate an RSA private key:

# openssl genrsa -out /etc/ssl/private/mail.example.com.key 4096

this would generate a 4096-bit RSA key stored in the file mail.example.com.key. she's big, she's secure, she's iconic. 💖

once you have generated the RSA key, you can generate a self-signed certificate from it using the command:

# openssl req -x509 -new -key /etc/ssl/private/mail.example.com.key \
  -out /etc/ssl/mail.example.com.crt -days 365

you may adjust the lifetime of the certificate via the -days parameter (one year in this example). ⏳

you can verify that the newly-generated certificate has correct information with the following command:

# openssl x509 -in /etc/ssl/mail.example.com.crt -text

it is better to configure and use acme-client(1) to obtain a signed certificate. slay, get the real one if you can. 🦋

because the private key files are unencrypted, MTAs can be picky about using tight permissions on those files. the certificate directory and the files therein should be readable and writable only by the owner (root). a simple way to ensure this is to run the following:

# chmod -R go-rwx /etc/ssl/private

🔐 do the chmod. do NOT skip the chmod. an unencrypted private key with loose perms is giving "i left my diary open on the kitchen table" energy. 😭

---

🧚 Creating a certificate with an existing private key 🧚

this example assumes you already have an existing private key, /etc/ssl/private/mail.example.com.key. you can generate a new certificate based on this key using the command:

# openssl req -x509 -new -key /etc/ssl/private/mail.example.com.key \
  -out /etc/ssl/mail.example.com.crt -days 365
# chmod 600 /etc/ssl/mail.example.com.crt

you may adjust the lifetime of the certificate via the -days parameter (one year in this example). ⏳

after having installed the certificates, the mail server needs to be configured to accept TLS sessions and use the key and certificate. for smtpd(8), it's as simple as adding pki configuration to smtpd.conf(5):

pki mail.example.com cert "/etc/ssl/mail.example.com.crt"
pki mail.example.com key "/etc/ssl/private/mail.example.com.key"

listen on [...] tls pki mail.example.com auth

after restarting the mail server, a new option should be presented for ESMTP transactions, STARTTLS. you can test this by connecting to the local host and issuing the “EHLO” command.

# telnet localhost 25
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
220 localhost ESMTP OpenSMTPD
EHLO localhost

after typing EHLO localhost, you should receive something like the following back. 🎁

250-localhost Hello localhost [127.0.0.1], pleased to meet you
250-8BITMIME
250-ENHANCEDSTATUSCODES
250-SIZE 36700160
250-DSN
250-STARTTLS
250 HELP

you should see “STARTTLS” listed along with the other options. if so, congratulations, the MTA will now use TLS to encrypt your mail traffic when the remote server supports it. if not, check /var/log/maillog to see whether the MTA has reported any security problems or other errors. go read the logs bestie, they're telling you something. 💀

---

👑 Uses for TLS equipped MTAs 👑

the most obvious use of a cryptographically enabled MTA is for confidentiality of the electronic mail transaction and the integrity checking provided by the cipher suite. all traffic between the two mail servers is encrypted, including the sender and recipient addresses. TLS also allows for authentication of either or both systems in the transaction. yes, even the addresses. everything. ✨

one use of public key cryptography is for strong authentication. we can use this authentication to selectively relay clients, including other mail servers and mobile clients like laptops. however, there have been some problems getting some mail clients to work using certificate-based authentication. clients will have to generate certificates and have them signed (for trust validation) by a trusted CA (certificate authority). like, it works, but it's giving "some assembly required". 🧩

---

🦋 SEE ALSO 🦋

• mail(1)
• openssl(1)
• smtpd(8)
• ssl(8)

---

📜 STANDARDS 📜

• P. Hoffman, SMTP Service Extension for Secure SMTP over Transport Layer Security, RFC 3207, February 2002.

---

⚠️ CAVEATS ⚠️

because TLS can only authenticate at the server level, true end-to-end authentication of the mail message cannot be performed with only the use of STARTTLS on the server. the use of S/MIME or PGP email and trustworthy key hierarchies can guarantee full confidentiality and integrity of the entire message path. 💜

---

and that's the whole page, bestie 🫶 this one is from Debian, dated May 5, 2025, shipped in the System Manager's Manual — go forth and encrypt everything, mwah 💋🌸