1POSTFIX-TLS(1)              General Commands Manual             POSTFIX-TLS(1)
2
3
4

NAME

6       postfix-tls - Postfix TLS management
7

SYNOPSIS

9       postfix tls subcommand
10

DESCRIPTION

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
16       The following subcommands are available:
17
18       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
23              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
27              See also the all-default-client subcommand.
28
29       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
35              The randsource parameter is as with enable-client above, and the
36              remaining options are as with new-server-key below.
37
38              See also the all-default-server subcommand.
39
40       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
48              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
55              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
64              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
70              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
76              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
81              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
88       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
96              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
101              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
107       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
116       output-server-csr [-k keyfile] [hostname...]
117              Write to stdout a certificate  signing  request  (CSR)  for  the
118              specified keyfile.
119
120              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
126              Zero  or  more  hostname  values  can be specified.  The default
127              hostname is the value of myhostname main.cf parameter.
128
129       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
135              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
143              The  default  keyfile  list  consists of the two supported algo‐
144              rithms rsa and ecdsa.
145

AUXILIARY COMMANDS

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
152              postfix tls all-default-client &&
153                      postfix tls enable-client
154
155       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
160              postfix tls all-default-server &&
161                      postfix tls enable-server
162

CONFIGURATION PARAMETERS

164       The "postfix tls subcommand" feature reads  or  updates  the  following
165       configuration parameters.
166
167       command_directory (see 'postconf -d' output)
168              The location of all postfix administrative commands.
169
170       config_directory (see 'postconf -d' output)
171              The  default  location of the Postfix main.cf and master.cf con‐
172              figuration files.
173
174       openssl_path (openssl)
175              The location of the OpenSSL command line program openssl(1).
176
177       smtp_tls_loglevel (0)
178              Enable additional Postfix SMTP client logging of TLS activity.
179
180       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
186       smtp_tls_session_cache_database (empty)
187              Name of the file containing the optional Postfix SMTP client TLS
188              session cache.
189
190       smtpd_tls_cert_file (empty)
191              File with the Postfix SMTP server RSA certificate in PEM format.
192
193       smtpd_tls_eccert_file (empty)
194              File with the Postfix SMTP server ECDSA certificate in PEM  for‐
195              mat.
196
197       smtpd_tls_eckey_file ($smtpd_tls_eccert_file)
198              File  with the Postfix SMTP server ECDSA private key in PEM for‐
199              mat.
200
201       smtpd_tls_key_file ($smtpd_tls_cert_file)
202              File with the Postfix SMTP server RSA private key in PEM format.
203
204       smtpd_tls_loglevel (0)
205              Enable additional Postfix SMTP server logging of TLS activity.
206
207       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
213       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
218       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

SEE ALSO

223       master(8) Postfix master program
224       postfix(1) Postfix administrative interface
225

README FILES

227       Use "postconf readme_directory" or "postconf html_directory" to  locate
228       this information.
229       TLS_README, Postfix TLS configuration and operation
230

LICENSE

232       The Secure Mailer license must be distributed with this software.
233

HISTORY

235       The "postfix tls" command was introduced with Postfix version 3.1.
236

AUTHOR(S)

238       Viktor Dukhovni
239
240
241
242                                                                POSTFIX-TLS(1)
Impressum