diff options
Diffstat (limited to 'html/postfix-tls.1.html')
| -rw-r--r-- | html/postfix-tls.1.html | 243 |
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> && + <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>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> |