summaryrefslogtreecommitdiffstats
path: root/html/postfix-tls.1.html
blob: 099284e58edf81c3fe1740a9cf10bba9bfb6af0c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
        "http://www.w3.org/TR/html4/loose.dtd">
<html> <head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<title> Postfix manual - postfix-tls(1) </title>
</head> <body> <pre>
POSTFIX-TLS(1)                                                  POSTFIX-TLS(1)

<b>NAME</b>
       postfix-tls - Postfix TLS management

<b>SYNOPSIS</b>
       <b><a href="postfix-tls.1.html">postfix tls</a></b> <i>subcommand</i>

<b>DESCRIPTION</b>
       The  "<b><a href="postfix-tls.1.html">postfix  tls</a></b> <i>subcommand</i>" feature enables opportunistic TLS in the
       Postfix SMTP client or server, and manages Postfix SMTP server  private
       keys and certificates.

       The following subcommands are available:

       <b>enable-client</b> [<b>-r</b> <i>randsource</i>]
              Enable opportunistic TLS in the Postfix SMTP client, if all SMTP
              client TLS settings are at  their  default  values.   Otherwise,
              suggest parameter settings without making any changes.

              Specify  <i>randsource</i> to update the value of the <b><a href="postconf.5.html#tls_random_source">tls_random_source</a></b>
              configuration parameter (typically, /dev/urandom).  Prepend <b>dev:</b>
              to device paths or <b>egd:</b> to EGD socket paths.

              See also the <b>all-default-client</b> subcommand.

       <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>]
              Create  a new private key and self-signed server certificate and
              enable opportunistic TLS in the Postfix SMTP server, if all SMTP
              server  TLS  settings  are  at their default values.  Otherwise,
              suggest parameter settings without making any changes.

              The <i>randsource</i> parameter is as with <b>enable-client</b> above, and the
              remaining options are as with <b>new-server-key</b> below.

              See also the <b>all-default-server</b> subcommand.

       <b>new-server-key</b> [<b>-a</b> <i>algorithm</i>] [<b>-b</b> <i>bits</i>] [<i>hostname</i><b>...</b>]
              Create a new private key and self-signed server certificate, but
              do not deploy them. Log and display commands to deploy  the  new
              key  and  corresponding  certificate.  Also log and display com-
              mands to output a corresponding CSR or TLSA records which may be
              needed  to  obtain  a CA certificate or to update DNS before the
              new key can be deployed.

              The <i>algorithm</i> defaults to <b>rsa</b>, and <i>bits</i> defaults  to  2048.   If
              you  choose  the  <b>ecdsa</b>  <i>algorithm</i> then <i>bits</i> will be an EC curve
              name (by default <b>secp256r1</b>, also known as  prime256v1).   Curves
              other  than <b>secp256r1</b>, <b>secp384r1</b> or <b>secp521r1</b> are unlikely to be
              widely interoperable.  When generating EC keys, use one of these
              three.  DSA keys are obsolete and are not supported.

              Note:  ECDSA support requires OpenSSL 1.0.0 or later and may not
              be available on your system.  Not all client systems  will  sup-
              port  ECDSA,  so  you'll  generally  want to deploy both RSA and
              ECDSA certificates to make use of ECDSA with compatible  clients
              and  RSA with the rest. If you want to deploy certificate chains
              with intermediate CAs for both RSA and  ECDSA,  you'll  want  at
              least OpenSSL 1.0.2, as earlier versions may not handle multiple
              chain files correctly.

              The first <i>hostname</i> argument will be the <b>CommonName</b> of  both  the
              subject  and issuer of the self-signed certificate.  It, and any
              additional <i>hostname</i> arguments, will also be listed as DNS alter-
              native names in the certificate.  If no <i>hostname</i> is provided the
              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.

              For RSA, the generated private key  and  certificate  files  are
              named   <b>key-</b><i>yyyymmdd-hhmmss</i><b>.pem</b>   and  <b>cert-</b><i>yyyymmdd-hhmmss</i><b>.pem</b>,
              where <i>yyyymmdd</i> is the calendar date and <i>hhmmss</i> is  the  time  of
              day  in  UTC.   For  ECDSA, the file names start with <b>eckey-</b> and
              <b>eccert-</b> instead of <b>key-</b> and <b>cert-</b> respectively.

              Before deploying the new key and certificate with  DANE,  update
              the  DNS  with  new  DANE  TLSA records, then wait for secondary
              nameservers to update and then for stale records in  remote  DNS
              caches to expire.

              Before  deploying  a new CA certificate make sure to include all
              the required intermediate issuing CA certificates  in  the  cer-
              tificate  chain  file.  The server certificate must be the first
              certificate in the chain file.  Overwrite and  deploy  the  file
              with  the  original  self-signed  certificate that was generated
              together with the key.

       <b>new-server-cert</b> [<b>-a</b> <i>algorithm</i>] [<b>-b</b> <i>bits</i>] [<i>hostname</i><b>...</b>]
              This is just like <b>new-server-key</b> except that, rather than gener-
              ating  a  new private key, any currently deployed private key is
              copied to the new key file.  Thus if you're publishing DANE TLSA
              "3  1  1"  or  "3  1  2" records, there is no need to update DNS
              records.  The <i>algorithm</i> and <i>bits</i> arguments are used only  if  no
              key of the same algorithm is already configured.

              This  command is rarely needed, because the self-signed certifi-
              cates generated have a 100-year nominal  expiration  time.   The
              underlying  public key algorithms may well be obsoleted by quan-
              tum computers long before then.

              The most plausible reason for using this  command  is  when  the
              system hostname changes, and you'd like the name in the certifi-
              cate to match the new hostname (not required for DANE "3  1  1",
              but some needlessly picky non-DANE opportunistic TLS clients may
              log warnings or even refuse to communicate).

       <b>deploy-server-cert</b> <i>certfile keyfile</i>
              This subcommand deploys the certificates in <i>certfile</i> and private
              key  in  <i>keyfile</i>  (which are typically generated by the commands
              above, which will also log and display the full  command  needed
              to  deploy  the  generated  key and certificate).  After the new
              certificate and key are deployed any obsolete keys and  certifi-
              cates  may  be removed by hand.   The <i>keyfile</i> and <i>certfile</i> file-
              names may be relative to the Postfix configuration directory.

       <b>output-server-csr</b> [<b>-k</b> <i>keyfile</i>] [<i>hostname</i><b>...</b>]
              Write to stdout a certificate  signing  request  (CSR)  for  the
              specified <i>keyfile</i>.

              Instead  of an absolute pathname or a pathname relative to $<a href="postconf.5.html#config_directory">con</a>-
              <a href="postconf.5.html#config_directory">fig_directory</a>, <i>keyfile</i> may specify  one  of  the  supported  key
              algorithm  names  (see  "<b>postconf -T public-key-algorithms</b>"). In
              that case, the corresponding setting from  <a href="postconf.5.html">main.cf</a>  is  used  to
              locate the <i>keyfile</i>.  The default <i>keyfile</i> value is <b>rsa</b>.

              Zero  or  more  <i>hostname</i>  values  can be specified.  The default
              <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.

       <b>output-server-tlsa</b> [<b>-h</b> <i>hostname</i>] [<i>keyfile</i><b>...</b>]
              Write to stdout a DANE TLSA RRset suitable for a  port  25  SMTP
              server on host <i>hostname</i> with keys from any of the specified <i>key-</i>
              <i>file</i> values.  The default <i>hostname</i> is the value of  the  <b>myhost-</b>
              <b>name</b> <a href="postconf.5.html">main.cf</a> parameter.

              Instead  of  absolute  pathnames  or pathnames relative to $<a href="postconf.5.html#config_directory">con</a>-
              <a href="postconf.5.html#config_directory">fig_directory</a>, the <i>keyfile</i> list may specify names  of  supported
              public key algorithms (see "<b>postconf -T public-key-algorithms</b>").
              In that case, the actual <i>keyfile</i> list uses  the  values  of  the
              corresponding  Postfix  server  TLS  key  file parameters.  If a
              parameter value is empty or equal to <b>none</b>, then no  TLSA  record
              is output for that algorithm.

              The  default  <i>keyfile</i>  list  consists of the two supported algo-
              rithms <b>rsa</b> and <b>ecdsa</b>.

<b>AUXILIARY COMMANDS</b>
       <b>all-default-client</b>
              Exit with status 0 (success) if all SMTP client TLS settings are
              at their default values.  Otherwise, exit with a non-zero status.
              This is typically used as follows:

              <b><a href="postfix-tls.1.html">postfix tls</a> all-default-client</b> &amp;&amp;
                      <b><a href="postfix-tls.1.html">postfix tls</a> enable-client</b>

       <b>all-default-server</b>
              Exit with status 0 (success) if all SMTP server TLS settings are
              at their default values.  Otherwise, exit with a non-zero status.
              This is typically used as follows:

              <b><a href="postfix-tls.1.html">postfix tls</a> all-default-server</b> &amp;&amp;
                      <b><a href="postfix-tls.1.html">postfix tls</a> enable-server</b>

<b>CONFIGURATION PARAMETERS</b>
       The "<b><a href="postfix-tls.1.html">postfix tls</a></b> <i>subcommand</i>" feature reads  or  updates  the  following
       configuration parameters.

       <b><a href="postconf.5.html#command_directory">command_directory</a> (see 'postconf -d' output)</b>
              The location of all postfix administrative commands.

       <b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b>
              The  default  location of the Postfix <a href="postconf.5.html">main.cf</a> and <a href="master.5.html">master.cf</a> con-
              figuration files.

       <b><a href="postconf.5.html#openssl_path">openssl_path</a> (openssl)</b>
              The location of the OpenSSL command line program <b>openssl</b>(1).

       <b><a href="postconf.5.html#smtp_tls_loglevel">smtp_tls_loglevel</a> (0)</b>
              Enable additional Postfix SMTP client logging of TLS activity.

       <b><a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> (empty)</b>
              The default SMTP TLS security level for the Postfix SMTP client;
              when a non-empty value is specified, this overrides the obsolete
              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
              <a href="postconf.5.html#smtp_tls_enforce_peername">smtp_tls_enforce_peername</a>.

       <b><a href="postconf.5.html#smtp_tls_session_cache_database">smtp_tls_session_cache_database</a> (empty)</b>
              Name of the file containing the optional Postfix SMTP client TLS
              session cache.

       <b><a href="postconf.5.html#smtpd_tls_cert_file">smtpd_tls_cert_file</a> (empty)</b>
              File with the Postfix SMTP server RSA certificate in PEM format.

       <b><a href="postconf.5.html#smtpd_tls_eccert_file">smtpd_tls_eccert_file</a> (empty)</b>
              File  with the Postfix SMTP server ECDSA certificate in PEM for-
              mat.

       <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>
              File with the Postfix SMTP server ECDSA private key in PEM  for-
              mat.

       <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>
              File with the Postfix SMTP server RSA private key in PEM format.

       <b><a href="postconf.5.html#smtpd_tls_loglevel">smtpd_tls_loglevel</a> (0)</b>
              Enable additional Postfix SMTP server logging of TLS activity.

       <b><a href="postconf.5.html#smtpd_tls_received_header">smtpd_tls_received_header</a> (no)</b>
              Request that the Postfix SMTP server produces Received:  message
              headers  that  include information about the protocol and cipher
              used, as well as the remote SMTP client  CommonName  and  client
              certificate issuer CommonName.

       <b><a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> (empty)</b>
              The  SMTP TLS security level for the Postfix SMTP server; when a
              non-empty value is specified, this overrides the obsolete param-
              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>.

       <b><a href="postconf.5.html#tls_random_source">tls_random_source</a> (see 'postconf -d' output)</b>
              The  external  entropy source for the in-memory <a href="tlsmgr.8.html"><b>tlsmgr</b>(8)</a> pseudo
              random number generator (PRNG) pool.

<b>SEE ALSO</b>
       <a href="master.8.html">master(8)</a> Postfix master program
       <a href="postfix.1.html">postfix(1)</a> Postfix administrative interface

<b>README FILES</b>
       <a href="TLS_README.html">TLS_README</a>, Postfix TLS configuration and operation

<b>LICENSE</b>
       The Secure Mailer license must be distributed with this software.

<b>HISTORY</b>
       The "<b><a href="postfix-tls.1.html">postfix tls</a></b>" command was introduced with Postfix version 3.1.

<b>AUTHOR(S)</b>
       Viktor Dukhovni

                                                                POSTFIX-TLS(1)
</pre> </body> </html>