Provided by: postfix_3.8.1-2ubuntu0.2_amd64 
NAME
postfix-tls - Postfix TLS management
SYNOPSIS
postfix tls subcommand
DESCRIPTION
The "postfix tls subcommand" feature enables opportunistic TLS in the Postfix SMTP client
or server, and manages Postfix SMTP server private keys and certificates.
The following subcommands are available:
enable-client [-r randsource]
Enable opportunistic TLS in the Postfix SMTP client, if all SMTP client TLS
settings are at their default values. Otherwise, suggest parameter settings
without making any changes.
Specify randsource to update the value of the tls_random_source configuration
parameter (typically, /dev/urandom). Prepend dev: to device paths or egd: to EGD
socket paths.
See also the all-default-client subcommand.
enable-server [-r randsource] [-a algorithm] [-b bits] [hostname...]
Create a new private key and self-signed server certificate and enable
opportunistic TLS in the Postfix SMTP server, if all SMTP server TLS settings are
at their default values. Otherwise, suggest parameter settings without making any
changes.
The randsource parameter is as with enable-client above, and the remaining options
are as with new-server-key below.
See also the all-default-server subcommand.
new-server-key [-a algorithm] [-b bits] [hostname...]
Create a new private key and self-signed server certificate, but do not deploy
them. Log and display commands to deploy the new key and corresponding certificate.
Also log and display commands to output a corresponding CSR or TLSA records which
may be needed to obtain a CA certificate or to update DNS before the new key can be
deployed.
The algorithm defaults to rsa, and bits defaults to 2048. If you choose the ecdsa
algorithm then bits will be 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. DSA
keys are obsolete and are not supported.
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 to make use of ECDSA with compatible
clients and RSA with the rest. If you want to deploy certificate chains with
intermediate CAs for both RSA and ECDSA, you'll want at least OpenSSL 1.0.2, as
earlier versions may not handle multiple chain files correctly.
The first hostname argument will be the CommonName of both the subject and issuer
of the self-signed certificate. It, and 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 will be 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 for stale
records in remote DNS caches to expire.
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. 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, rather than generating a new private
key, any currently deployed private key is copied to the new key file. Thus 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 used only 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. 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).
deploy-server-cert certfile keyfile
This subcommand deploys the certificates in certfile and private key in keyfile
(which are typically generated by the commands above, which will 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...]
Write 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 myhostname main.cf parameter.
output-server-tlsa [-h hostname] [keyfile...]
Write 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
Exit with status 0 (success) if all SMTP client TLS settings are
at their default values. Otherwise, exit with a non-zero status.
This is typically used as follows:
postfix tls all-default-client &&
postfix tls enable-client
all-default-server
Exit with status 0 (success) if all SMTP server TLS settings are
at their default values. Otherwise, exit 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.
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 (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
master(8) Postfix master program
postfix(1) Postfix administrative interface
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
POSTFIX-TLS(1)