summaryrefslogtreecommitdiffstats
path: root/html/posttls-finger.1.html
blob: 2ed629a8672ab11c879b0a9a65b7069d0b300fb7 (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
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
<!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=utf-8">
<link rel='stylesheet' type='text/css' href='postfix-doc.css'>
<title> Postfix manual - posttls-finger(1) </title>
</head> <body> <pre>
POSTTLS-FINGER(1)                                            POSTTLS-FINGER(1)

<b>NAME</b>
       posttls-finger - Probe the TLS properties of an ESMTP or LMTP server.

<b>SYNOPSIS</b>
       <b>posttls-finger</b> [<i>options</i>] [<b>inet:</b>]<i>domain</i>[:<i>port</i>] [<i>match ...</i>]
       <b>posttls-finger</b> -S [<i>options</i>] <b>unix:</b><i>pathname</i> [<i>match ...</i>]

<b>DESCRIPTION</b>
       <a href="posttls-finger.1.html"><b>posttls-finger</b>(1)</a>  connects  to  the  specified destination and reports
       TLS-related information about the server. With SMTP, the destination is
       a  domainname;  with LMTP it is either a domainname prefixed with <b>inet:</b>
       or a pathname prefixed with <b>unix:</b>.  If Postfix  is  built  without  TLS
       support, the resulting <a href="posttls-finger.1.html"><b>posttls-finger</b>(1)</a> program has very limited func-
       tionality, and only the <b>-a</b>, <b>-c</b>, <b>-h</b>, <b>-o</b>, <b>-S</b>, <b>-t</b>, <b>-T</b> and <b>-v</b>  options  are
       available.

       Note:  this is an unsupported test program. No attempt is made to main-
       tain compatibility between successive versions.

       For SMTP servers that don't support ESMTP, only the greeting banner and
       the  negative  EHLO response are reported. Otherwise, the reported EHLO
       response details further server capabilities.

       If TLS support is enabled when <a href="posttls-finger.1.html"><b>posttls-finger</b>(1)</a> is compiled,  and  the
       server supports <b>STARTTLS</b>, a TLS handshake is attempted.

       If  DNSSEC  support is available, the connection TLS security level (<b>-l</b>
       option) defaults to <b>dane</b>; see <a href="TLS_README.html">TLS_README</a>  for  details.  Otherwise,  it
       defaults  to  <b>secure</b>.  This setting determines the certificate matching
       policy.

       If TLS negotiation succeeds, the TLS protocol and  cipher  details  are
       reported.  The  server  certificate is then verified in accordance with
       the policy at the chosen (or  default)  security  level.   With  public
       CA-based  trust,  when  the  <b>-L</b>  option  includes  <b>certmatch</b>,  (true by
       default) name matching is performed even if the  certificate  chain  is
       not  trusted.  This logs the names found in the remote SMTP server cer-
       tificate and which if any  would  match,  were  the  certificate  chain
       trusted.

       Note:  <a href="posttls-finger.1.html"><b>posttls-finger</b>(1)</a> does not perform any table lookups, so the TLS
       policy table and obsolete per-site tables are not consulted.   It  does
       not  communicate  with  the <a href="tlsmgr.8.html"><b>tlsmgr</b>(8)</a> daemon (or any other Postfix dae-
       mons); its TLS session cache is held in private memory, and  disappears
       when the process exits.

       With  the  <b>-r</b> <i>delay</i> option, if the server assigns a TLS session id, the
       TLS session is cached. The connection  is  then  closed  and  re-opened
       after  the  specified delay, and <a href="posttls-finger.1.html"><b>posttls-finger</b>(1)</a> then reports whether
       the cached TLS session was re-used.

       When the destination is a load balancer, it may  be  distributing  load
       between  multiple  server  caches.  Typically,  each server returns its
       unique name in its EHLO response. If, upon reconnecting with <b>-r</b>, a  new
       server  name is detected, another session is cached for the new server,
       and the reconnect is repeated up to a maximum number of times  (default
       5) that can be specified via the <b>-m</b> option.

       The  choice  of  SMTP  or LMTP (<b>-S</b> option) determines the syntax of the
       destination argument. With  SMTP,  one  can  specify  a  service  on  a
       non-default  port  as <i>host</i>:<i>service</i>, and disable MX (mail exchanger) DNS
       lookups with [<i>host</i>] or [<i>host</i>]:<i>port</i>.  The [] form is required  when  you
       specify an IP address instead of a hostname.  An IPv6 address takes the
       form [<b>ipv6:</b><i>address</i>].  The default port  for  SMTP  is  taken  from  the
       <b>smtp/tcp</b>  entry  in /etc/services, defaulting to 25 if the entry is not
       found.

       With LMTP, specify <b>unix:</b><i>pathname</i> to connect to a local server listening
       on  a  unix-domain  socket  bound to the specified pathname; otherwise,
       specify an optional <b>inet:</b> prefix followed by a <i>domain</i> and  an  optional
       port,  with  the same syntax as for SMTP. The default TCP port for LMTP
       is 24.

       Arguments:

       <b>-a</b> <i>family</i> (default: <b>any</b>)
              Address family preference: <b>ipv4</b>, <b>ipv6</b> or <b>any</b>.  When  using  <b>any</b>,
              <a href="posttls-finger.1.html"><b>posttls-finger</b>(1)</a>  will  randomly  select  one of the two as the
              more preferred, and exhaust all MX  preferences  for  the  first
              address family before trying any addresses for the other.

       <b>-A</b> <i>trust-anchor.pem</i> (default: none)
              A  list of PEM trust-anchor files that overrides CAfile and CAp-
              ath trust chain verification.  Specify the option multiple times
              to  specify  multiple  files.  See the <a href="postconf.5.html">main.cf</a> documentation for
              <a href="postconf.5.html#smtp_tls_trust_anchor_file">smtp_tls_trust_anchor_file</a> for details.

       <b>-c</b>     Disable SMTP  chat  logging;  only  TLS-related  information  is
              logged.

       <b>-C</b>     Print the remote SMTP server certificate trust chain in PEM for-
              mat.  The issuer DN, subject DN, certificate and public key fin-
              gerprints (see <b>-d</b> <i>mdalg</i> option below) are printed above each PEM
              certificate block.  If you specify <b>-F</b> <i>CAfile</i> or <b>-P</b>  <i>CApath</i>,  the
              OpenSSL  library  may augment the chain with missing issuer cer-
              tificates.  To see the actual chain  sent  by  the  remote  SMTP
              server leave <i>CAfile</i> and <i>CApath</i> unset.

       <b>-d</b> <i>mdalg</i> (default: <b>$<a href="postconf.5.html#smtp_tls_fingerprint_digest">smtp_tls_fingerprint_digest</a></b>)
              The  message  digest  algorithm to use for reporting remote SMTP
              server fingerprints and matching against user provided  certifi-
              cate fingerprints (with DANE TLSA records the algorithm is spec-
              ified in the DNS).   In  Postfix  versions  prior  to  3.6,  the
              default value was "md5".

       <b>-f</b>     Lookup  the  associated  DANE TLSA RRset even when a hostname is
              not an alias and its address records lie in  an  unsigned  zone.
              See <a href="postconf.5.html#smtp_tls_force_insecure_host_tlsa_lookup">smtp_tls_force_insecure_host_tlsa_lookup</a> for details.

       <b>-F</b> <i>CAfile.pem</i> (default: none)
              The PEM formatted CAfile for remote SMTP server certificate ver-
              ification.  By default no CAfile is used and no public  CAs  are
              trusted.

       <b>-g</b> <i>grade</i> (default: medium)
              The  minimum  TLS  cipher  grade used by <a href="posttls-finger.1.html"><b>posttls-finger</b>(1)</a>.  See
              <a href="postconf.5.html#smtp_tls_mandatory_ciphers">smtp_tls_mandatory_ciphers</a> for details.

       <b>-h</b> <i>host</i><b>_</b><i>lookup</i> (default: <b>dns</b>)
              The hostname lookup methods used for the  connection.   See  the
              documentation of <a href="postconf.5.html#smtp_host_lookup">smtp_host_lookup</a> for syntax and semantics.

       <b>-H</b> <i>chainfiles</i> (default: <i>none</i>)
              List of files with a sequence PEM-encoded TLS client certificate
              chains.  The list can be built-up incrementally,  by  specifying
              the  option multiple times, or all at once via a comma or white-
              space separated list of filenames.  Each  chain  starts  with  a
              private  key, which is followed immediately by the corresponding
              certificate, and optionally by additional  issuer  certificates.
              Each new key begins a new chain for the corresponding algorithm.
              This option is mutually exclusive  with  the  below  <b>-k</b>  and  <b>-K</b>
              options.

       <b>-k</b> <i>certfile</i> (default: <i>keyfile</i>)
              File   with  PEM-encoded  TLS  client  certificate  chain.  This
              defaults to <i>keyfile</i> if one is specified.

       <b>-K</b> <i>keyfile</i> (default: <i>certfile</i>)
              File with PEM-encoded TLS client private key.  This defaults  to
              <i>certfile</i> if one is specified.

       <b>-l</b> <i>level</i> (default: <b>dane</b> or <b>secure</b>)
              The  security  level  for the connection, default <b>dane</b> or <b>secure</b>
              depending on whether DNSSEC is available.  For syntax and seman-
              tics,  see  the  documentation of <a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a>.  When
              <b>dane</b> or <b>dane-only</b> is supported and selected, if no TLSA  records
              are  found,  or  all  the records found are unusable, the <i>secure</i>
              level will be used  instead.   The  <b>fingerprint</b>  security  level
              allows you to test certificate or public-key fingerprint matches
              before you deploy them in the policy table.

              Note, since <a href="posttls-finger.1.html"><b>posttls-finger</b>(1)</a>  does  not  actually  deliver  any
              email,  the  <b>none</b>,  <b>may</b> and <b>encrypt</b> security levels are not very
              useful.  Since <b>may</b> and <b>encrypt</b> don't require peer  certificates,
              they  will  often  negotiate  anonymous TLS ciphersuites, so you
              won't learn much about the remote SMTP server's certificates  at
              these  levels  if it also supports anonymous TLS (though you may
              learn that the server supports anonymous TLS).

       <b>-L</b> <i>logopts</i> (default: <b>routine,certmatch</b>)
              Fine-grained TLS logging  options.  To  tune  the  TLS  features
              logged during the TLS handshake, specify one or more of:

              <b>0, none</b>
                     These  yield  no TLS logging; you'll generally want more,
                     but this is handy if you just want the trust chain:
                     $ posttls-finger -cC -L none destination

              <b>1, routine, summary</b>
                     These synonymous values yield a normal  one-line  summary
                     of the TLS connection.

              <b>2, debug</b>
                     These synonymous values combine routine, ssl-debug, cache
                     and verbose.

              <b>3, ssl-expert</b>
                     These synonymous  values  combine  debug  with  ssl-hand-
                     shake-packet-dump.  For experts only.

              <b>4, ssl-developer</b>
                     These  synonymous values combine ssl-expert with ssl-ses-
                     sion-packet-dump.  For experts only, and in  most  cases,
                     use wireshark instead.

              <b>ssl-debug</b>
                     Turn  on OpenSSL logging of the progress of the SSL hand-
                     shake.

              <b>ssl-handshake-packet-dump</b>
                     Log hexadecimal packet dumps of the  SSL  handshake;  for
                     experts only.

              <b>ssl-session-packet-dump</b>
                     Log  hexadecimal  packet dumps of the entire SSL session;
                     only useful to those who can debug SSL protocol  problems
                     from hex dumps.

              <b>untrusted</b>
                     Logs  trust  chain verification problems.  This is turned
                     on automatically at security levels that use  peer  names
                     signed  by Certification Authorities to validate certifi-
                     cates.  So while this setting is recognized,  you  should
                     never need to set it explicitly.

              <b>peercert</b>
                     This  logs  a  one line summary of the remote SMTP server
                     certificate subject, issuer, and fingerprints.

              <b>certmatch</b>
                     This logs remote SMTP server certificate matching,  show-
                     ing  the  CN  and  each  subjectAltName  and  which  name
                     matched.   With  DANE,  logs  matching  of  TLSA   record
                     trust-anchor and end-entity certificates.

              <b>cache</b>  This  logs session cache operations, showing whether ses-
                     sion caching is effective with the  remote  SMTP  server.
                     Automatically  used when reconnecting with the <b>-r</b> option;
                     rarely needs to be set explicitly.

              <b>verbose</b>
                     Enables  verbose  logging  in  the  Postfix  TLS  driver;
                     includes all of peercert..cache and more.

              The  default  is <b>routine,certmatch</b>. After a reconnect, <b>peercert</b>,
              <b>certmatch</b> and <b>verbose</b> are automatically disabled while <b>cache</b> and
              <b>summary</b> are enabled.

       <b>-m</b> <i>count</i> (default: <b>5</b>)
              When  the <b>-r</b> <i>delay</i> option is specified, the <b>-m</b> option determines
              the maximum number of reconnect attempts to use  with  a  server
              behind  a  load  balancer,  to see whether connection caching is
              likely to be effective for this destination.   Some  MTAs  don't
              expose  the  underlying  server identity in their EHLO response;
              with these servers there will never be more than 1  reconnection
              attempt.

       <b>-M</b> <i>insecure</i><b>_</b><i>mx</i><b>_</b><i>policy</i> (default: <b>dane</b>)
              The  TLS policy for MX hosts with "secure" TLSA records when the
              nexthop destination security level is <b>dane</b>, but  the  MX  record
              was found via an "insecure" MX lookup.  See the <a href="postconf.5.html">main.cf</a> documen-
              tation for <a href="postconf.5.html#smtp_tls_dane_insecure_mx_policy">smtp_tls_dane_insecure_mx_policy</a> for details.

       <b>-o</b> <i>name=value</i>
              Specify zero or more times to override the value of the  <a href="postconf.5.html">main.cf</a>
              parameter  <i>name</i> with <i>value</i>.  Possible use-cases include overrid-
              ing the values of TLS library  parameters,  or  "<a href="postconf.5.html#myhostname">myhostname</a>"  to
              configure the SMTP EHLO name sent to the remote server.

       <b>-p</b> <i>protocols</i> (default: &gt;=TLSv1)
              TLS  protocols  that  <a href="posttls-finger.1.html"><b>posttls-finger</b>(1)</a> will exclude or include.
              See <a href="postconf.5.html#smtp_tls_mandatory_protocols">smtp_tls_mandatory_protocols</a> for details.

       <b>-P</b> <i>CApath/</i> (default: none)
              The OpenSSL CApath/  directory  (indexed  via  c_rehash(1))  for
              remote SMTP server certificate verification.  By default no CAp-
              ath is used and no public CAs are trusted.

       <b>-r</b> <i>delay</i>
              With a cacheable TLS session,  disconnect  and  reconnect  after
              <i>delay</i> seconds. Report whether the session is re-used. Retry if a
              new server is encountered, up to 5 times or  as  specified  with
              the  <b>-m</b>  option.  By default reconnection is disabled, specify a
              positive delay to enable this behavior.

       <b>-R</b>     Use SRV lookup instead of MX.

       <b>-s</b> <i>servername</i>
              The server name to send with  the  TLS  Server  Name  Indication
              (SNI)  extension.   When  the server has DANE TLSA records, this
              parameter is ignored and the TLSA base domain is  used  instead.
              Otherwise,  SNI  is  not  used by default, but can be enabled by
              specifying the desired value with this option.

       <b>-S</b>     Disable SMTP; that is, connect to an LMTP  server.  The  default
              port  for  LMTP over TCP is 24.  Alternative ports can specified
              by appending "<i>:servicename</i>" or ":<i>portnumber</i>" to the  destination
              argument.

       <b>-t</b> <i>timeout</i> (default: <b>30</b>)
              The TCP connection timeout to use.  This is also the timeout for
              reading the remote server's 220 banner.

       <b>-T</b> <i>timeout</i> (default: <b>30</b>)
              The SMTP/LMTP command timeout for EHLO/LHLO, STARTTLS and  QUIT.

       <b>-v</b>     Enable  verbose  Postfix  logging.   Specify  more  than once to
              increase the level of verbose logging.

       <b>-w</b>     Enable outgoing TLS wrapper mode, or SUBMISSIONS/SMTPS  support.
              This  is typically provided on port 465 by servers that are com-
              patible with the SMTP-in-SSL protocol, rather than the  STARTTLS
              protocol.   The  destination  <i>domain</i>:<i>port</i> must of course provide
              such a service.

       <b>-X</b>     Enable <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> mode. This is an unsupported mode,  for  pro-
              gram development only.

       [<b>inet:</b>]<i>domain</i>[:<i>port</i>]
              Connect via TCP to domain <i>domain</i>, port <i>port</i>. The default port is
              <b>smtp</b> (or 24 with LMTP).  With SMTP an MX lookup is performed  to
              resolve  the  domain to a host, unless the domain is enclosed in
              <b>[]</b>.  If you want to connect to a specific MX host, for  instance
              <i>mx1.example.com</i>,  specify  [<i>mx1.example.com</i>]  as the destination
              and <i>example.com</i> as a <b>match</b> argument.  When using DNS, the desti-
              nation  domain  is assumed fully qualified and no <a href="ADDRESS_CLASS_README.html#default_domain_class">default domain</a>
              or search suffixes are applied;  you  must  use  fully-qualified
              names  or  also  enable <b>native</b> host lookups (these don't support
              <b>dane</b> or <b>dane-only</b> as no DNSSEC validation information is  avail-
              able via <b>native</b> lookups).

       <b>unix:</b><i>pathname</i>
              Connect to the UNIX-domain socket at <i>pathname</i>. LMTP only.

       <b>match ...</b>
              With no match arguments specified, certificate peername matching
              uses the compiled-in default strategies for each security level.
              If  you specify one or more arguments, these will be used as the
              list of certificate or public-key digests to match for the  <b>fin-</b>
              <b>gerprint</b> level, or as the list of DNS names to match in the cer-
              tificate at the <b>verify</b> and <b>secure</b> levels.  If the security level
              is <b>dane</b>, or <b>dane-only</b> the match names are ignored, and <b>hostname,</b>
              <b>nexthop</b> strategies are used.

<b>ENVIRONMENT</b>
       <b>MAIL_CONFIG</b>
              Read configuration parameters from a non-default location.

       <b>MAIL_VERBOSE</b>
              Same as <b>-v</b> option.

<b>SEE ALSO</b>
       <a href="smtp-source.1.html">smtp-source(1)</a>, SMTP/LMTP message source
       <a href="smtp-sink.1.html">smtp-sink(1)</a>, SMTP/LMTP message dump

<b>README FILES</b>
       <a href="TLS_README.html">TLS_README</a>, Postfix STARTTLS howto

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

<b>AUTHOR(S)</b>
       Wietse Venema
       IBM T.J. Watson Research
       P.O. Box 704
       Yorktown Heights, NY 10598, USA

       Wietse Venema
       Google, Inc.
       111 8th Avenue
       New York, NY 10011, USA

       Viktor Dukhovni

                                                             POSTTLS-FINGER(1)
</pre> </body> </html>