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 ec‐
74              cert- 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 to‐
86              gether 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  al‐
122              gorithm names (see "postconf -T public-key-algorithms"). In that
123              case, the corresponding setting from main.cf is used  to  locate
124              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 pa‐
140              rameter value is empty or equal to none, then no TLSA record  is
141              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
183       smtp_tls_session_cache_database (empty)
184              Name of the file containing the optional Postfix SMTP client TLS
185              session cache.
186
187       smtpd_tls_cert_file (empty)
188              File with the Postfix SMTP server RSA certificate in PEM format.
189
190       smtpd_tls_eccert_file (empty)
191              File  with the Postfix SMTP server ECDSA certificate in PEM for‐
192              mat.
193
194       smtpd_tls_eckey_file ($smtpd_tls_eccert_file)
195              File with the Postfix SMTP server ECDSA private key in PEM  for‐
196              mat.
197
198       smtpd_tls_key_file ($smtpd_tls_cert_file)
199              File with the Postfix SMTP server RSA private key in PEM format.
200
201       smtpd_tls_loglevel (0)
202              Enable additional Postfix SMTP server logging of TLS activity.
203
204       smtpd_tls_received_header (no)
205              Request that the Postfix SMTP server produces Received:  message
206              headers that include information about the protocol  and  cipher
207              used,  as  well  as the remote SMTP client CommonName and client
208              certificate issuer CommonName.
209
210       smtpd_tls_security_level (empty)
211              The SMTP TLS security level for the Postfix SMTP server; when  a
212              non-empty value is specified, this overrides the obsolete param‐
213              eters smtpd_use_tls and smtpd_enforce_tls.
214
215       tls_random_source (see 'postconf -d' output)
216              The external entropy source for the in-memory  tlsmgr(8)  pseudo
217              random number generator (PRNG) pool.
218

SEE ALSO

220       master(8) Postfix master program
221       postfix(1) Postfix administrative interface
222

README FILES

224       Use  "postconf readme_directory" or "postconf html_directory" to locate
225       this information.
226       TLS_README, Postfix TLS configuration and operation
227

LICENSE

229       The Secure Mailer license must be distributed with this software.
230

HISTORY

232       The "postfix tls" command was introduced with Postfix version 3.1.
233

AUTHOR(S)

235       Viktor Dukhovni
236
237
238
239                                                                POSTFIX-TLS(1)
Impressum