diff options
Diffstat (limited to '')
| -rw-r--r-- | man/man1/postfix-tls.1 | 244 |
1 files changed, 244 insertions, 0 deletions
diff --git a/man/man1/postfix-tls.1 b/man/man1/postfix-tls.1 new file mode 100644 index 0000000..4e8cb92 --- /dev/null +++ b/man/man1/postfix-tls.1 @@ -0,0 +1,244 @@ +.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 |