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