1<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" 2 "http://www.w3.org/TR/html4/loose.dtd"> 3<html> <head> 4<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> 5<title> Postfix manual - postfix-tls(1) </title> 6</head> <body> <pre> 7POSTFIX-TLS(1) POSTFIX-TLS(1) 8 9<b>NAME</b> 10 postfix-tls - Postfix TLS management 11 12<b>SYNOPSIS</b> 13 <b><a href="postfix-tls.1.html">postfix tls</a></b> <i>subcommand</i> 14 15<b>DESCRIPTION</b> 16 The "<b><a href="postfix-tls.1.html">postfix tls</a></b> <i>subcommand</i>" feature enables opportunistic TLS in the 17 Postfix SMTP client or server, and manages Postfix SMTP server private 18 keys and certificates. 19 20 The following subcommands are available: 21 22 <b>enable-client</b> [<b>-r</b> <i>randsource</i>] 23 Enable opportunistic TLS in the Postfix SMTP client, if all SMTP 24 client TLS settings are at their default values. Otherwise, 25 suggest parameter settings without making any changes. 26 27 Specify <i>randsource</i> to update the value of the <b><a href="postconf.5.html#tls_random_source">tls_random_source</a></b> 28 configuration parameter (typically, /dev/urandom). Prepend <b>dev:</b> 29 to device paths or <b>egd:</b> to EGD socket paths. 30 31 See also the <b>all-default-client</b> subcommand. 32 33 <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>] 34 Create a new private key and self-signed server certificate and 35 enable opportunistic TLS in the Postfix SMTP server, if all SMTP 36 server TLS settings are at their default values. Otherwise, 37 suggest parameter settings without making any changes. 38 39 The <i>randsource</i> parameter is as with <b>enable-client</b> above, and the 40 remaining options are as with <b>new-server-key</b> below. 41 42 See also the <b>all-default-server</b> subcommand. 43 44 <b>new-server-key</b> [<b>-a</b> <i>algorithm</i>] [<b>-b</b> <i>bits</i>] [<i>hostname</i><b>...</b>] 45 Create a new private key and self-signed server certificate, but 46 do not deploy them. Log and display commands to deploy the new 47 key and corresponding certificate. Also log and display com- 48 mands to output a corresponding CSR or TLSA records which may be 49 needed to obtain a CA certificate or to update DNS before the 50 new key can be deployed. 51 52 The <i>algorithm</i> defaults to <b>rsa</b>, and <i>bits</i> defaults to 2048. If 53 you choose the <b>ecdsa</b> <i>algorithm</i> then <i>bits</i> will be an EC curve 54 name (by default <b>secp256r1</b>, also known as prime256v1). Curves 55 other than <b>secp256r1</b>, <b>secp384r1</b> or <b>secp521r1</b> are unlikely to be 56 widely interoperable. When generating EC keys, use one of these 57 three. DSA keys are obsolete and are not supported. 58 59 Note: ECDSA support requires OpenSSL 1.0.0 or later and may not 60 be available on your system. Not all client systems will sup- 61 port ECDSA, so you'll generally want to deploy both RSA and 62 ECDSA certificates to make use of ECDSA with compatible clients 63 and RSA with the rest. If you want to deploy certificate chains 64 with intermediate CAs for both RSA and ECDSA, you'll want at 65 least OpenSSL 1.0.2, as earlier versions may not handle multiple 66 chain files correctly. 67 68 The first <i>hostname</i> argument will be the <b>CommonName</b> of both the 69 subject and issuer of the self-signed certificate. It, and any 70 additional <i>hostname</i> arguments, will also be listed as DNS alter- 71 native names in the certificate. If no <i>hostname</i> is provided the 72 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. 73 74 For RSA, the generated private key and certificate files are 75 named <b>key-</b><i>yyyymmdd-hhmmss</i><b>.pem</b> and <b>cert-</b><i>yyyymmdd-hhmmss</i><b>.pem</b>, 76 where <i>yyyymmdd</i> is the calendar date and <i>hhmmss</i> is the time of 77 day in UTC. For ECDSA, the file names start with <b>eckey-</b> and 78 <b>eccert-</b> instead of <b>key-</b> and <b>cert-</b> respectively. 79 80 Before deploying the new key and certificate with DANE, update 81 the DNS with new DANE TLSA records, then wait for secondary 82 nameservers to update and then for stale records in remote DNS 83 caches to expire. 84 85 Before deploying a new CA certificate make sure to include all 86 the required intermediate issuing CA certificates in the cer- 87 tificate chain file. The server certificate must be the first 88 certificate in the chain file. Overwrite and deploy the file 89 with the original self-signed certificate that was generated 90 together with the key. 91 92 <b>new-server-cert</b> [<b>-a</b> <i>algorithm</i>] [<b>-b</b> <i>bits</i>] [<i>hostname</i><b>...</b>] 93 This is just like <b>new-server-key</b> except that, rather than gener- 94 ating a new private key, any currently deployed private key is 95 copied to the new key file. Thus if you're publishing DANE TLSA 96 "3 1 1" or "3 1 2" records, there is no need to update DNS 97 records. The <i>algorithm</i> and <i>bits</i> arguments are used only if no 98 key of the same algorithm is already configured. 99 100 This command is rarely needed, because the self-signed certifi- 101 cates generated have a 100-year nominal expiration time. The 102 underlying public key algorithms may well be obsoleted by quan- 103 tum computers long before then. 104 105 The most plausible reason for using this command is when the 106 system hostname changes, and you'd like the name in the certifi- 107 cate to match the new hostname (not required for DANE "3 1 1", 108 but some needlessly picky non-DANE opportunistic TLS clients may 109 log warnings or even refuse to communicate). 110 111 <b>deploy-server-cert</b> <i>certfile keyfile</i> 112 This subcommand deploys the certificates in <i>certfile</i> and private 113 key in <i>keyfile</i> (which are typically generated by the commands 114 above, which will also log and display the full command needed 115 to deploy the generated key and certificate). After the new 116 certificate and key are deployed any obsolete keys and certifi- 117 cates may be removed by hand. The <i>keyfile</i> and <i>certfile</i> file- 118 names may be relative to the Postfix configuration directory. 119 120 <b>output-server-csr</b> [<b>-k</b> <i>keyfile</i>] [<i>hostname</i><b>...</b>] 121 Write to stdout a certificate signing request (CSR) for the 122 specified <i>keyfile</i>. 123 124 Instead of an absolute pathname or a pathname relative to $<a href="postconf.5.html#config_directory">con</a>- 125 <a href="postconf.5.html#config_directory">fig_directory</a>, <i>keyfile</i> may specify one of the supported key 126 algorithm names (see "<b>postconf -T public-key-algorithms</b>"). In 127 that case, the corresponding setting from <a href="postconf.5.html">main.cf</a> is used to 128 locate the <i>keyfile</i>. The default <i>keyfile</i> value is <b>rsa</b>. 129 130 Zero or more <i>hostname</i> values can be specified. The default 131 <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. 132 133 <b>output-server-tlsa</b> [<b>-h</b> <i>hostname</i>] [<i>keyfile</i><b>...</b>] 134 Write to stdout a DANE TLSA RRset suitable for a port 25 SMTP 135 server on host <i>hostname</i> with keys from any of the specified <i>key-</i> 136 <i>file</i> values. The default <i>hostname</i> is the value of the <b>myhost-</b> 137 <b>name</b> <a href="postconf.5.html">main.cf</a> parameter. 138 139 Instead of absolute pathnames or pathnames relative to $<a href="postconf.5.html#config_directory">con</a>- 140 <a href="postconf.5.html#config_directory">fig_directory</a>, the <i>keyfile</i> list may specify names of supported 141 public key algorithms (see "<b>postconf -T public-key-algorithms</b>"). 142 In that case, the actual <i>keyfile</i> list uses the values of the 143 corresponding Postfix server TLS key file parameters. If a 144 parameter value is empty or equal to <b>none</b>, then no TLSA record 145 is output for that algorithm. 146 147 The default <i>keyfile</i> list consists of the two supported algo- 148 rithms <b>rsa</b> and <b>ecdsa</b>. 149 150<b>AUXILIARY COMMANDS</b> 151 <b>all-default-client</b> 152 Exit with status 0 (success) if all SMTP client TLS settings are 153 at their default values. Otherwise, exit with a non-zero status. 154 This is typically used as follows: 155 156 <b><a href="postfix-tls.1.html">postfix tls</a> all-default-client</b> && 157 <b><a href="postfix-tls.1.html">postfix tls</a> enable-client</b> 158 159 <b>all-default-server</b> 160 Exit with status 0 (success) if all SMTP server TLS settings are 161 at their default values. Otherwise, exit with a non-zero status. 162 This is typically used as follows: 163 164 <b><a href="postfix-tls.1.html">postfix tls</a> all-default-server</b> && 165 <b><a href="postfix-tls.1.html">postfix tls</a> enable-server</b> 166 167<b>CONFIGURATION PARAMETERS</b> 168 The "<b><a href="postfix-tls.1.html">postfix tls</a></b> <i>subcommand</i>" feature reads or updates the following 169 configuration parameters. 170 171 <b><a href="postconf.5.html#command_directory">command_directory</a> (see 'postconf -d' output)</b> 172 The location of all postfix administrative commands. 173 174 <b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b> 175 The default location of the Postfix <a href="postconf.5.html">main.cf</a> and <a href="master.5.html">master.cf</a> con- 176 figuration files. 177 178 <b><a href="postconf.5.html#openssl_path">openssl_path</a> (openssl)</b> 179 The location of the OpenSSL command line program <b>openssl</b>(1). 180 181 <b><a href="postconf.5.html#smtp_tls_loglevel">smtp_tls_loglevel</a> (0)</b> 182 Enable additional Postfix SMTP client logging of TLS activity. 183 184 <b><a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> (empty)</b> 185 The default SMTP TLS security level for the Postfix SMTP client; 186 when a non-empty value is specified, this overrides the obsolete 187 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 188 <a href="postconf.5.html#smtp_tls_enforce_peername">smtp_tls_enforce_peername</a>. 189 190 <b><a href="postconf.5.html#smtp_tls_session_cache_database">smtp_tls_session_cache_database</a> (empty)</b> 191 Name of the file containing the optional Postfix SMTP client TLS 192 session cache. 193 194 <b><a href="postconf.5.html#smtpd_tls_cert_file">smtpd_tls_cert_file</a> (empty)</b> 195 File with the Postfix SMTP server RSA certificate in PEM format. 196 197 <b><a href="postconf.5.html#smtpd_tls_eccert_file">smtpd_tls_eccert_file</a> (empty)</b> 198 File with the Postfix SMTP server ECDSA certificate in PEM for- 199 mat. 200 201 <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> 202 File with the Postfix SMTP server ECDSA private key in PEM for- 203 mat. 204 205 <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> 206 File with the Postfix SMTP server RSA private key in PEM format. 207 208 <b><a href="postconf.5.html#smtpd_tls_loglevel">smtpd_tls_loglevel</a> (0)</b> 209 Enable additional Postfix SMTP server logging of TLS activity. 210 211 <b><a href="postconf.5.html#smtpd_tls_received_header">smtpd_tls_received_header</a> (no)</b> 212 Request that the Postfix SMTP server produces Received: message 213 headers that include information about the protocol and cipher 214 used, as well as the remote SMTP client CommonName and client 215 certificate issuer CommonName. 216 217 <b><a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> (empty)</b> 218 The SMTP TLS security level for the Postfix SMTP server; when a 219 non-empty value is specified, this overrides the obsolete param- 220 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>. 221 222 <b><a href="postconf.5.html#tls_random_source">tls_random_source</a> (see 'postconf -d' output)</b> 223 The external entropy source for the in-memory <a href="tlsmgr.8.html"><b>tlsmgr</b>(8)</a> pseudo 224 random number generator (PRNG) pool. 225 226<b>SEE ALSO</b> 227 <a href="master.8.html">master(8)</a> Postfix master program 228 <a href="postfix.1.html">postfix(1)</a> Postfix administrative interface 229 230<b>README FILES</b> 231 <a href="TLS_README.html">TLS_README</a>, Postfix TLS configuration and operation 232 233<b>LICENSE</b> 234 The Secure Mailer license must be distributed with this software. 235 236<b>HISTORY</b> 237 The "<b><a href="postfix-tls.1.html">postfix tls</a></b>" command was introduced with Postfix version 3.1. 238 239<b>AUTHOR(S)</b> 240 Viktor Dukhovni 241 242 POSTFIX-TLS(1) 243</pre> </body> </html> 244