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