POSTFIX-TLS(1)

📦
version 3.11.7 · 4 versions
, in alpine 3.24, arch rolling, nixos 26.05, nixpkgs unstable, ubuntu stonking

hii bestie 💖 sit down, hydrate, and let's talk TLS because this one is actually iconic. You're looking at postfix-tls, straight out of the General Commands Manual section, and it's the whole vibe of "my mail server speaks TLS and I didn't have to lose my mind doing it." 🦋

🎀 NAME 🎀

postfix-tls — Postfix TLS management ✨

💅 SYNOPSIS 💅

postfix tls subcommand

🌸 DESCRIPTION 🌸

okay so the "postfix tls subcommand" feature does two big things, no cap: it enables opportunistic TLS in the Postfix SMTP client or server, and it manages Postfix SMTP server private keys and certificates. Very demure, very mindful, very encrypted.

The following subcommands are available:

🌈 enable-client [-r randsource]

Turns on opportunistic TLS in the Postfix SMTP client — but only if all your SMTP client TLS settings are sitting at their default values. If they're not? It just suggests parameter settings and makes literally zero changes. It's being polite, not lazy.

  • -r randsource — updates the value of the tls_random_source configuration parameter (typically, /dev/urandom). Prepend dev: to device paths or egd: to EGD socket paths.

Also go peek at the all-default-client subcommand below, iykyk.

⭐ enable-server [-r randsource] [-a algorithm] [-b bits] [hostname...]

Makes a brand new private key and a self-signed server certificate, then enables opportunistic TLS in the Postfix SMTP server — as long as all SMTP server TLS settings are still at their defaults. If they aren't, it suggests parameter settings and changes nothing. Boundaries! We love them.

The randsource parameter works exactly like it does in enable-client above, and the rest of the options work like new-server-key below (scroll down bestie, it's all there).

Also see the all-default-server subcommand. 👑

🧚 new-server-key [-a algorithm] [-b bits] [hostname...]

Generates a new private key and self-signed server certificate — but does not deploy them. Instead it logs and displays the commands you'd need to deploy the new key and its matching certificate. It also logs and displays commands to output a corresponding CSR or TLSA records, which you might need to grab a CA certificate or update DNS before the new key can actually be deployed.

  • algorithm defaults to rsa, and bits defaults to 2048.
  • If you pick the ecdsa algorithm, then bits becomes an EC curve name (by default secp256r1, also known as prime256v1).
  • Curves other than secp256r1, secp384r1 or secp521r1 are unlikely to be widely interoperable. When generating EC keys, use one of these three. Periodt.
  • DSA keys are obsolete and are not supported. Not me even bringing it up — it's in the manual, bestie, we don't do DSA here.
Note: ECDSA support requires OpenSSL 1.0.0 or later and may not be available on your system. Not all client systems will support ECDSA, so you'll generally want to deploy both RSA and ECDSA certificates — that way you get ECDSA with the compatible clients and RSA with the rest. And if you want to deploy certificate chains with intermediate CAs for both RSA and ECDSA, you'll want at least OpenSSL 1.0.2, because earlier versions may not handle multiple chain files correctly. 🙈

The first hostname argument becomes the CommonName of both the subject and the issuer of the self-signed certificate. It, plus any additional hostname arguments, will also be listed as DNS alternative names in the certificate. If no hostname is provided, the value of the myhostname main.cf parameter gets used. 🫶

For RSA, the generated private key and certificate files are named key-yyyymmdd-hhmmss.pem and cert-yyyymmdd-hhmmss.pem, where yyyymmdd is the calendar date and hhmmss is the time of day in UTC. For ECDSA, the file names start with eckey- and eccert- instead of key- and cert- respectively. 💫

Before deploying the new key and certificate with DANE, update the DNS with new DANE TLSA records, then wait for secondary nameservers to update, and then wait for stale records in remote DNS caches to expire. The waiting is the hard part, I know. 😭
Before deploying a new CA certificate, make sure to include all the required intermediate issuing CA certificates in the certificate chain file. The server certificate must be the first certificate in the chain file. Then overwrite and deploy the file with the original self-signed certificate that was generated together with the key.

💜 new-server-cert [-a algorithm] [-b bits] [hostname...]

This is just like new-server-key — except that instead of generating a new private key, any currently deployed private key is simply copied to the new key file. So if you're publishing DANE TLSA "3 1 1" or "3 1 2" records, there is no need to update DNS records. The algorithm and bits arguments are only used if no key of the same algorithm is already configured.

This command is rarely needed, because the self-signed certificates generated have a 100-year nominal expiration time. And honestly? The underlying public key algorithms may well be obsoleted by quantum computers long before then. 💀

The most plausible reason for using this command is when the system hostname changes, and you'd like the name in the certificate to match the new hostname (not required for DANE "3 1 1", but some needlessly picky non-DANE opportunistic TLS clients may log warnings or even refuse to communicate). Like, chill, but okay. 🙄

🍓 deploy-server-cert certfile keyfile

Deploys the certificates in certfile and the private key in keyfile (which are typically generated by the commands above — those also log and display the full command needed to deploy the generated key and certificate). After the new certificate and key are deployed, any obsolete keys and certificates may be removed by hand. The keyfile and certfile filenames may be relative to the Postfix configuration directory.

🌟 output-server-csr [-k keyfile] [hostname...]

Writes to stdout a certificate signing request (CSR) for the specified keyfile.

Instead of an absolute pathname or a pathname relative to $config_directory, keyfile may specify one of the supported key algorithm names (see postconf -T public-key-algorithms). In that case, the corresponding setting from main.cf is used to locate the keyfile. The default keyfile value is rsa.

Zero or more hostname values can be specified. The default hostname is the value of the myhostname main.cf parameter.

🌈 output-server-tlsa [-h hostname] [keyfile...]

Writes to stdout a DANE TLSA RRset suitable for a port 25 SMTP server on host hostname, with keys from any of the specified keyfile values. The default hostname is the value of the myhostname main.cf parameter.

Instead of absolute pathnames or pathnames relative to $config_directory, the keyfile list may specify names of supported public key algorithms (see postconf -T public-key-algorithms). In that case, the actual keyfile list uses the values of the corresponding Postfix server TLS key file parameters. If a parameter value is empty or equal to none, then no TLSA record is output for that algorithm.

The default keyfile list consists of the two supported algorithms rsa and ecdsa. 👑

✨ AUXILIARY COMMANDS ✨

all-default-client

Exits with status 0 (success) if all SMTP client TLS settings are at their default values. Otherwise, it exits with a non-zero status. This is typically used as follows:

postfix tls all-default-client &&
        postfix tls enable-client

all-default-server

Exits with status 0 (success) if all SMTP server TLS settings are at their default values. Otherwise, it exits with a non-zero status. This is typically used as follows:

postfix tls all-default-server &&
        postfix tls enable-server

🎀 CONFIGURATION PARAMETERS 🎀

The "postfix tls subcommand" feature reads or updates the following configuration parameters. Look at all these little guys.

  • command_directory (see postconf -d output) — The location of all postfix administrative commands.
  • config_directory (see postconf -d output) — The default location of the Postfix main.cf and master.cf configuration files.
  • openssl_path (openssl) — The location of the OpenSSL command line program openssl(1).
  • smtp_tls_loglevel (0) — Enable additional Postfix SMTP client logging of TLS activity.
  • smtp_tls_security_level (Postfix >= 3.11: may; Postfix < 3.11: empty) — The default SMTP TLS security level for the Postfix SMTP client.
  • smtp_tls_session_cache_database (empty) — Name of the file containing the optional Postfix SMTP client TLS session cache.
  • smtpd_tls_cert_file (empty) — File with the Postfix SMTP server RSA certificate in PEM format.
  • smtpd_tls_eccert_file (empty) — File with the Postfix SMTP server ECDSA certificate in PEM format.
  • smtpd_tls_eckey_file ($smtpd_tls_eccert_file) — File with the Postfix SMTP server ECDSA private key in PEM format.
  • smtpd_tls_key_file ($smtpd_tls_cert_file) — File with the Postfix SMTP server RSA private key in PEM format.
  • smtpd_tls_loglevel (0) — Enable additional Postfix SMTP server logging of TLS activity.
  • smtpd_tls_received_header (no) — Request that the Postfix SMTP server produces Received: message headers that include information about the protocol and cipher used, as well as the remote SMTP client CommonName and client certificate issuer CommonName.
  • smtpd_tls_security_level (empty) — The SMTP TLS security level for the Postfix SMTP server; when a non-empty value is specified, this overrides the obsolete parameters smtpd_use_tls and smtpd_enforce_tls.
  • tls_random_source (see postconf -d output) — The external entropy source for the in-memory tlsmgr(8) pseudo random number generator (PRNG) pool.

🌈 SEE ALSO 🌈

🦋 README FILES 🦋

Use postconf readme_directory or postconf html_directory to locate this information.

  • TLS_README, Postfix TLS configuration and operation

💖 LICENSE 💖

The Secure Mailer license must be distributed with this software.

⭐ HISTORY ⭐

The "postfix tls" command was introduced with Postfix version 3.1.

👑 AUTHOR(S) 👑

Viktor Dukhovni

and that's the whole page bestie, we ate and left no crumbs 🍓✨ shoutout to the POSTFIX-TLS(1) manual page for the source, mwah 💋

📦 where this page comes from