summaryrefslogtreecommitdiffstats
path: root/html/postfix-tls.1.html
diff options
context:
space:
mode:
Diffstat (limited to 'html/postfix-tls.1.html')
-rw-r--r--html/postfix-tls.1.html243
1 files changed, 243 insertions, 0 deletions
diff --git a/html/postfix-tls.1.html b/html/postfix-tls.1.html
new file mode 100644
index 0000000..099284e
--- /dev/null
+++ b/html/postfix-tls.1.html
@@ -0,0 +1,243 @@
+<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
+ "http://www.w3.org/TR/html4/loose.dtd">
+<html> <head>
+<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
+<title> Postfix manual - postfix-tls(1) </title>
+</head> <body> <pre>
+POSTFIX-TLS(1) POSTFIX-TLS(1)
+
+<b>NAME</b>
+ postfix-tls - Postfix TLS management
+
+<b>SYNOPSIS</b>
+ <b><a href="postfix-tls.1.html">postfix tls</a></b> <i>subcommand</i>
+
+<b>DESCRIPTION</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>AUXILIARY COMMANDS</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> &amp;&amp;
+ <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> &amp;&amp;
+ <b><a href="postfix-tls.1.html">postfix tls</a> enable-server</b>
+
+<b>CONFIGURATION PARAMETERS</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;
+ when a non-empty value is specified, this overrides the obsolete
+ parameters <a href="postconf.5.html#smtp_use_tls">smtp_use_tls</a>, <a href="postconf.5.html#smtp_enforce_tls">smtp_enforce_tls</a>, and
+ <a href="postconf.5.html#smtp_tls_enforce_peername">smtp_tls_enforce_peername</a>.
+
+ <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>SEE ALSO</b>
+ <a href="master.8.html">master(8)</a> Postfix master program
+ <a href="postfix.1.html">postfix(1)</a> Postfix administrative interface
+
+<b>README FILES</b>
+ <a href="TLS_README.html">TLS_README</a>, Postfix TLS configuration and operation
+
+<b>LICENSE</b>
+ The Secure Mailer license must be distributed with this software.
+
+<b>HISTORY</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>