.\"	$NetBSD: postfix-tls.1,v 1.2.18.1 2023/12/25 12:54:39 martin Exp $
.\"
.TH POSTFIX-TLS 1 
.ad
.fi
.SH NAME
postfix-tls
\-
Postfix TLS management
.SH "SYNOPSIS"
.na
.nf
\fBpostfix tls\fR \fIsubcommand\fR
.SH DESCRIPTION
.ad
.fi
The "\fBpostfix tls \fIsubcommand\fR" 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:
.IP "\fBenable\-client\fR [\fB\-r \fIrandsource\fR]"
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.
.sp
Specify \fIrandsource\fR to update the value of the
\fBtls_random_source\fR configuration parameter (typically,
/dev/urandom).  Prepend \fBdev:\fR to device paths or
\fBegd:\fR to EGD socket paths.
.sp
See also the \fBall\-default\-client\fR subcommand.
.IP "\fBenable\-server\fR [\fB\-r \fIrandsource\fR] [\fB\-a \fIalgorithm\fR] [\fB\-b \fIbits\fR] [\fIhostname\fB...\fR]"
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.
.sp
The \fIrandsource\fR parameter is as with \fBenable\-client\fR
above, and the remaining options are as with \fBnew\-server\-key\fR
below.
.sp
See also the \fBall\-default\-server\fR subcommand.
.IP "\fBnew\-server\-key\fR [\fB\-a \fIalgorithm\fR] [\fB\-b \fIbits\fR] [\fIhostname\fB...\fR]"
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.
.sp
The \fIalgorithm\fR defaults to \fBrsa\fR, and \fIbits\fR
defaults to 2048.  If you choose the \fBecdsa\fR  \fIalgorithm\fR
then \fIbits\fR will be an EC curve name (by default
\fBsecp256r1\fR, also known as prime256v1).  Curves other
than \fBsecp256r1\fR, \fBsecp384r1\fR or \fBsecp521r1\fR
are unlikely to be widely interoperable.  When generating
EC keys, use one of these three.  DSA keys are obsolete and
are not supported.
.sp
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.
.sp
The first \fIhostname\fR argument will be the \fBCommonName\fR
of both the subject and issuer of the self\-signed certificate.
It, and any additional \fIhostname\fR arguments, will also
be listed as DNS alternative names in the certificate.  If
no \fIhostname\fR is provided the value of the \fBmyhostname\fR
main.cf parameter will be used.
.sp
For RSA, the generated private key and certificate files
are named \fBkey\-\fIyyyymmdd\-hhmmss\fB.pem\fR and
\fBcert\-\fIyyyymmdd\-hhmmss\fB.pem\fR, where \fIyyyymmdd\fR
is the calendar date and \fIhhmmss\fR is the time of day
in UTC.  For ECDSA, the file names start with \fBeckey\-\fR
and \fBeccert\-\fR instead of \fBkey\-\fR and \fBcert\-\fR
respectively.
.sp
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.
.sp
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.
.IP "\fBnew\-server\-cert\fR [\fB\-a \fIalgorithm\fR] [\fB\-b \fIbits\fR] [\fIhostname\fB...\fR]"
This is just like \fBnew\-server\-key\fR 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 \fIalgorithm\fR and
\fIbits\fR arguments are used only if no key of the same
algorithm is already configured.
.sp
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.
.sp
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).
.IP "\fBdeploy\-server\-cert \fIcertfile\fB \fIkeyfile\fR"
This subcommand deploys the certificates in \fIcertfile\fR
and private key in \fIkeyfile\fR (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 \fIkeyfile\fR and \fIcertfile\fR filenames
may be relative to the Postfix configuration directory.
.IP "\fBoutput\-server\-csr\fR [\fB\-k \fIkeyfile\fR] [\fIhostname\fB...\fR]"
Write to stdout a certificate signing request (CSR) for the
specified \fIkeyfile\fR.
.sp
Instead of an absolute pathname or a pathname relative to
$config_directory, \fIkeyfile\fR may specify one of the
supported key algorithm names (see "\fBpostconf \-T
public\-key\-algorithms\fR"). In that case, the corresponding
setting from main.cf is used to locate the \fIkeyfile\fR.
The default \fIkeyfile\fR value is \fBrsa\fR.
.sp
Zero or more \fIhostname\fR values can be specified.  The
default \fIhostname\fR is the value of \fBmyhostname\fR
main.cf parameter.
.IP "\fBoutput\-server\-tlsa\fR [\fB\-h \fIhostname\fR] [\fIkeyfile\fB...\fR]"
Write to stdout a DANE TLSA RRset suitable for a port 25
SMTP server on host \fIhostname\fR with keys from any of
the specified \fIkeyfile\fR values.  The default \fIhostname\fR
is the value of the \fBmyhostname\fR main.cf parameter.
.sp
Instead of absolute pathnames or pathnames relative to
$config_directory, the \fIkeyfile\fR list may specify
names of supported public key algorithms (see "\fBpostconf
\-T public\-key\-algorithms\fR").  In that case, the actual
\fIkeyfile\fR list uses the values of the corresponding
Postfix server TLS key file parameters.  If a parameter
value is empty or equal to \fBnone\fR, then no TLSA record
is output for that algorithm.
.sp
The default \fIkeyfile\fR list consists of the two supported
algorithms \fBrsa\fR and \fBecdsa\fR.
.SH "AUXILIARY COMMANDS"
.na
.nf
.IP "\fBall\-default\-client\fR"
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:
.sp
\fBpostfix tls all\-default\-client &&
        postfix tls enable\-client\fR
.IP "\fBall\-default\-server\fR"
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:
.sp
\fBpostfix tls all\-default\-server &&
        postfix tls enable\-server\fR
.SH "CONFIGURATION PARAMETERS"
.na
.nf
.ad
.fi
The "\fBpostfix tls \fIsubcommand\fR" feature reads
or updates the following configuration parameters.
.IP "\fBcommand_directory (see 'postconf -d' output)\fR"
The location of all postfix administrative commands.
.IP "\fBconfig_directory (see 'postconf -d' output)\fR"
The default location of the Postfix main.cf and master.cf
configuration files.
.IP "\fBopenssl_path (openssl)\fR"
The location of the OpenSSL command line program \fBopenssl\fR(1).
.IP "\fBsmtp_tls_loglevel (0)\fR"
Enable additional Postfix SMTP client logging of TLS activity.
.IP "\fBsmtp_tls_security_level (empty)\fR"
The default SMTP TLS security level for the Postfix SMTP client.
.IP "\fBsmtp_tls_session_cache_database (empty)\fR"
Name of the file containing the optional Postfix SMTP client
TLS session cache.
.IP "\fBsmtpd_tls_cert_file (empty)\fR"
File with the Postfix SMTP server RSA certificate in PEM format.
.IP "\fBsmtpd_tls_eccert_file (empty)\fR"
File with the Postfix SMTP server ECDSA certificate in PEM format.
.IP "\fBsmtpd_tls_eckey_file ($smtpd_tls_eccert_file)\fR"
File with the Postfix SMTP server ECDSA private key in PEM format.
.IP "\fBsmtpd_tls_key_file ($smtpd_tls_cert_file)\fR"
File with the Postfix SMTP server RSA private key in PEM format.
.IP "\fBsmtpd_tls_loglevel (0)\fR"
Enable additional Postfix SMTP server logging of TLS activity.
.IP "\fBsmtpd_tls_received_header (no)\fR"
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.
.IP "\fBsmtpd_tls_security_level (empty)\fR"
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.
.IP "\fBtls_random_source (see 'postconf -d' output)\fR"
The external entropy source for the in\-memory \fBtlsmgr\fR(8) pseudo
random number generator (PRNG) pool.
.SH "SEE ALSO"
.na
.nf
master(8) Postfix master program
postfix(1) Postfix administrative interface
.SH "README FILES"
.na
.nf
.ad
.fi
Use "\fBpostconf readme_directory\fR" or
"\fBpostconf html_directory\fR" to locate this information.
.na
.nf
TLS_README, Postfix TLS configuration and operation
.SH "LICENSE"
.na
.nf
.ad
.fi
The Secure Mailer license must be distributed with this software.
.SH HISTORY
.ad
.fi
The "\fBpostfix tls\fR" command was introduced with Postfix
version 3.1.
.SH "AUTHOR(S)"
.na
.nf
Viktor Dukhovni