241 lines
14 KiB
HTML
241 lines
14 KiB
HTML
<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
|
|
"https://www.w3.org/TR/html4/loose.dtd">
|
|
<html> <head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<link rel='stylesheet' type='text/css' href='postfix-doc.css'>
|
|
<title> Postfix manual - postfix-tls(1) </title>
|
|
</head> <body> <pre>
|
|
POSTFIX-TLS(1) POSTFIX-TLS(1)
|
|
|
|
<b><a name="name">NAME</a></b>
|
|
postfix-tls - Postfix TLS management
|
|
|
|
<b><a name="synopsis">SYNOPSIS</a></b>
|
|
<b><a href="postfix-tls.1.html">postfix tls</a></b> <i>subcommand</i>
|
|
|
|
<b><a name="description">DESCRIPTION</a></b>
|
|
The "<b><a href="postfix-tls.1.html">postfix tls</a></b> <i>subcommand</i>" 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:
|
|
|
|
<b>enable-client</b> [<b>-r</b> <i>randsource</i>]
|
|
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 <i>randsource</i> to update the value of the <b><a href="postconf.5.html#tls_random_source">tls_random_source</a></b>
|
|
configuration parameter (typically, /dev/urandom). Prepend <b>dev:</b>
|
|
to device paths or <b>egd:</b> to EGD socket paths.
|
|
|
|
See also the <b>all-default-client</b> subcommand.
|
|
|
|
<b>enable-server</b> [<b>-r</b> <i>randsource</i>] [<b>-a</b> <i>algorithm</i>] [<b>-b</b> <i>bits</i>] [<i>hostname</i><b>...</b>]
|
|
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 <i>randsource</i> parameter is as with <b>enable-client</b> above, and the
|
|
remaining options are as with <b>new-server-key</b> below.
|
|
|
|
See also the <b>all-default-server</b> subcommand.
|
|
|
|
<b>new-server-key</b> [<b>-a</b> <i>algorithm</i>] [<b>-b</b> <i>bits</i>] [<i>hostname</i><b>...</b>]
|
|
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 com-
|
|
mands 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 <i>algorithm</i> defaults to <b>rsa</b>, and <i>bits</i> defaults to 2048. If
|
|
you choose the <b>ecdsa</b> <i>algorithm</i> then <i>bits</i> will be an EC curve
|
|
name (by default <b>secp256r1</b>, also known as prime256v1). Curves
|
|
other than <b>secp256r1</b>, <b>secp384r1</b> or <b>secp521r1</b> 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 sup-
|
|
port 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 <i>hostname</i> argument will be the <b>CommonName</b> of both the
|
|
subject and issuer of the self-signed certificate. It, and any
|
|
additional <i>hostname</i> arguments, will also be listed as DNS alter-
|
|
native names in the certificate. If no <i>hostname</i> is provided the
|
|
value of the <b><a href="postconf.5.html#myhostname">myhostname</a></b> <a href="postconf.5.html">main.cf</a> parameter will be used.
|
|
|
|
For RSA, the generated private key and certificate files are
|
|
named <b>key-</b><i>yyyymmdd-hhmmss</i><b>.pem</b> and <b>cert-</b><i>yyyymmdd-hhmmss</i><b>.pem</b>,
|
|
where <i>yyyymmdd</i> is the calendar date and <i>hhmmss</i> is the time of
|
|
day in UTC. For ECDSA, the file names start with <b>eckey-</b> and
|
|
<b>eccert-</b> instead of <b>key-</b> and <b>cert-</b> 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 cer-
|
|
tificate 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.
|
|
|
|
<b>new-server-cert</b> [<b>-a</b> <i>algorithm</i>] [<b>-b</b> <i>bits</i>] [<i>hostname</i><b>...</b>]
|
|
This is just like <b>new-server-key</b> except that, rather than gener-
|
|
ating 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 <i>algorithm</i> and <i>bits</i> arguments are used only if no
|
|
key of the same algorithm is already configured.
|
|
|
|
This command is rarely needed, because the self-signed certifi-
|
|
cates generated have a 100-year nominal expiration time. The
|
|
underlying public key algorithms may well be obsoleted by quan-
|
|
tum 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 certifi-
|
|
cate 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).
|
|
|
|
<b>deploy-server-cert</b> <i>certfile keyfile</i>
|
|
This subcommand deploys the certificates in <i>certfile</i> and private
|
|
key in <i>keyfile</i> (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 certifi-
|
|
cates may be removed by hand. The <i>keyfile</i> and <i>certfile</i> file-
|
|
names may be relative to the Postfix configuration directory.
|
|
|
|
<b>output-server-csr</b> [<b>-k</b> <i>keyfile</i>] [<i>hostname</i><b>...</b>]
|
|
Write to stdout a certificate signing request (CSR) for the
|
|
specified <i>keyfile</i>.
|
|
|
|
Instead of an absolute pathname or a pathname relative to $<a href="postconf.5.html#config_directory">con</a>-
|
|
<a href="postconf.5.html#config_directory">fig_directory</a>, <i>keyfile</i> may specify one of the supported key
|
|
algorithm names (see "<b>postconf -T public-key-algorithms</b>"). In
|
|
that case, the corresponding setting from <a href="postconf.5.html">main.cf</a> is used to
|
|
locate the <i>keyfile</i>. The default <i>keyfile</i> value is <b>rsa</b>.
|
|
|
|
Zero or more <i>hostname</i> values can be specified. The default
|
|
<i>hostname</i> is the value of <b><a href="postconf.5.html#myhostname">myhostname</a></b> <a href="postconf.5.html">main.cf</a> parameter.
|
|
|
|
<b>output-server-tlsa</b> [<b>-h</b> <i>hostname</i>] [<i>keyfile</i><b>...</b>]
|
|
Write to stdout a DANE TLSA RRset suitable for a port 25 SMTP
|
|
server on host <i>hostname</i> with keys from any of the specified <i>key-</i>
|
|
<i>file</i> values. The default <i>hostname</i> is the value of the <b>myhost-</b>
|
|
<b>name</b> <a href="postconf.5.html">main.cf</a> parameter.
|
|
|
|
Instead of absolute pathnames or pathnames relative to $<a href="postconf.5.html#config_directory">con</a>-
|
|
<a href="postconf.5.html#config_directory">fig_directory</a>, the <i>keyfile</i> list may specify names of supported
|
|
public key algorithms (see "<b>postconf -T public-key-algorithms</b>").
|
|
In that case, the actual <i>keyfile</i> list uses the values of the
|
|
corresponding Postfix server TLS key file parameters. If a
|
|
parameter value is empty or equal to <b>none</b>, then no TLSA record
|
|
is output for that algorithm.
|
|
|
|
The default <i>keyfile</i> list consists of the two supported algo-
|
|
rithms <b>rsa</b> and <b>ecdsa</b>.
|
|
|
|
<b><a name="auxiliary_commands">AUXILIARY COMMANDS</a></b>
|
|
<b>all-default-client</b>
|
|
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:
|
|
|
|
<b><a href="postfix-tls.1.html">postfix tls</a> all-default-client</b> &&
|
|
<b><a href="postfix-tls.1.html">postfix tls</a> enable-client</b>
|
|
|
|
<b>all-default-server</b>
|
|
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:
|
|
|
|
<b><a href="postfix-tls.1.html">postfix tls</a> all-default-server</b> &&
|
|
<b><a href="postfix-tls.1.html">postfix tls</a> enable-server</b>
|
|
|
|
<b><a name="configuration_parameters">CONFIGURATION PARAMETERS</a></b>
|
|
The "<b><a href="postfix-tls.1.html">postfix tls</a></b> <i>subcommand</i>" feature reads or updates the following
|
|
configuration parameters.
|
|
|
|
<b><a href="postconf.5.html#command_directory">command_directory</a> (see 'postconf -d' output)</b>
|
|
The location of all postfix administrative commands.
|
|
|
|
<b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b>
|
|
The default location of the Postfix <a href="postconf.5.html">main.cf</a> and <a href="master.5.html">master.cf</a> con-
|
|
figuration files.
|
|
|
|
<b><a href="postconf.5.html#openssl_path">openssl_path</a> (openssl)</b>
|
|
The location of the OpenSSL command line program <b>openssl</b>(1).
|
|
|
|
<b><a href="postconf.5.html#smtp_tls_loglevel">smtp_tls_loglevel</a> (0)</b>
|
|
Enable additional Postfix SMTP client logging of TLS activity.
|
|
|
|
<b><a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> (empty)</b>
|
|
The default SMTP TLS security level for the Postfix SMTP client.
|
|
|
|
<b><a href="postconf.5.html#smtp_tls_session_cache_database">smtp_tls_session_cache_database</a> (empty)</b>
|
|
Name of the file containing the optional Postfix SMTP client TLS
|
|
session cache.
|
|
|
|
<b><a href="postconf.5.html#smtpd_tls_cert_file">smtpd_tls_cert_file</a> (empty)</b>
|
|
File with the Postfix SMTP server RSA certificate in PEM format.
|
|
|
|
<b><a href="postconf.5.html#smtpd_tls_eccert_file">smtpd_tls_eccert_file</a> (empty)</b>
|
|
File with the Postfix SMTP server ECDSA certificate in PEM for-
|
|
mat.
|
|
|
|
<b><a href="postconf.5.html#smtpd_tls_eckey_file">smtpd_tls_eckey_file</a> ($<a href="postconf.5.html#smtpd_tls_eccert_file">smtpd_tls_eccert_file</a>)</b>
|
|
File with the Postfix SMTP server ECDSA private key in PEM for-
|
|
mat.
|
|
|
|
<b><a href="postconf.5.html#smtpd_tls_key_file">smtpd_tls_key_file</a> ($<a href="postconf.5.html#smtpd_tls_cert_file">smtpd_tls_cert_file</a>)</b>
|
|
File with the Postfix SMTP server RSA private key in PEM format.
|
|
|
|
<b><a href="postconf.5.html#smtpd_tls_loglevel">smtpd_tls_loglevel</a> (0)</b>
|
|
Enable additional Postfix SMTP server logging of TLS activity.
|
|
|
|
<b><a href="postconf.5.html#smtpd_tls_received_header">smtpd_tls_received_header</a> (no)</b>
|
|
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.
|
|
|
|
<b><a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> (empty)</b>
|
|
The SMTP TLS security level for the Postfix SMTP server; when a
|
|
non-empty value is specified, this overrides the obsolete param-
|
|
eters <a href="postconf.5.html#smtpd_use_tls">smtpd_use_tls</a> and <a href="postconf.5.html#smtpd_enforce_tls">smtpd_enforce_tls</a>.
|
|
|
|
<b><a href="postconf.5.html#tls_random_source">tls_random_source</a> (see 'postconf -d' output)</b>
|
|
The external entropy source for the in-memory <a href="tlsmgr.8.html"><b>tlsmgr</b>(8)</a> pseudo
|
|
random number generator (PRNG) pool.
|
|
|
|
<b><a name="see_also">SEE ALSO</a></b>
|
|
<a href="master.8.html">master(8)</a> Postfix master program
|
|
<a href="postfix.1.html">postfix(1)</a> Postfix administrative interface
|
|
|
|
<b><a name="readme_files">README FILES</a></b>
|
|
<a href="TLS_README.html">TLS_README</a>, Postfix TLS configuration and operation
|
|
|
|
<b><a name="license">LICENSE</a></b>
|
|
The Secure Mailer license must be distributed with this software.
|
|
|
|
<b><a name="history">HISTORY</a></b>
|
|
The "<b><a href="postfix-tls.1.html">postfix tls</a></b>" command was introduced with Postfix version 3.1.
|
|
|
|
<b>AUTHOR(S)</b>
|
|
Viktor Dukhovni
|
|
|
|
POSTFIX-TLS(1)
|
|
</pre> </body> </html>
|