1POSTTLS-FINGER(1)           General Commands Manual          POSTTLS-FINGER(1)
2
3
4

NAME

6       posttls-finger - Probe the TLS properties of an ESMTP or LMTP server.
7

SYNOPSIS

9       posttls-finger [options] [inet:]domain[:port] [match ...]
10       posttls-finger -S [options] unix:pathname [match ...]
11

DESCRIPTION

13       posttls-finger(1)  connects  to  the  specified destination and reports
14       TLS-related information about the server. With SMTP, the destination is
15       a  domainname;  with LMTP it is either a domainname prefixed with inet:
16       or a pathname prefixed with unix:.  If Postfix  is  built  without  TLS
17       support,  the  resulting  posttls-finger program has very limited func‐
18       tionality, and only the -a, -c, -h, -o, -S, -t, -T and -v  options  are
19       available.
20
21       Note:  this is an unsupported test program. No attempt is made to main‐
22       tain compatibility between successive versions.
23
24       For SMTP servers that don't support ESMTP, only the greeting banner and
25       the  negative  EHLO response are reported. Otherwise, the reported EHLO
26       response details further server capabilities.
27
28       If TLS support is enabled when posttls-finger(1) is compiled,  and  the
29       server supports STARTTLS, a TLS handshake is attempted.
30
31       If  DNSSEC  support is available, the connection TLS security level (-l
32       option) defaults to dane; see TLS_README  for  details.  Otherwise,  it
33       defaults  to  secure.  This setting determines the certificate matching
34       policy.
35
36       If TLS negotiation succeeds, the TLS protocol and  cipher  details  are
37       reported.  The  server  certificate is then verified in accordance with
38       the policy at the chosen (or  default)  security  level.   With  public
39       CA-based  trust,  when  the  -L  option  includes  certmatch,  (true by
40       default) name matching is performed even if the  certificate  chain  is
41       not  trusted.  This logs the names found in the remote SMTP server cer‐
42       tificate and which if any  would  match,  were  the  certificate  chain
43       trusted.
44
45       Note:  posttls-finger(1) does not perform any table lookups, so the TLS
46       policy table and obsolete per-site tables are not consulted.   It  does
47       not  communicate  with  the tlsmgr(8) daemon (or any other Postfix dae‐
48       mons); its TLS session cache is held in private memory, and  disappears
49       when the process exits.
50
51       With  the  -r delay option, if the server assigns a TLS session id, the
52       TLS session is cached. The connection  is  then  closed  and  re-opened
53       after  the  specified delay, and posttls-finger(1) then reports whether
54       the cached TLS session was re-used.
55
56       When the destination is a load balancer, it may  be  distributing  load
57       between  multiple  server  caches.  Typically,  each server returns its
58       unique name in its EHLO response. If, upon reconnecting with -r, a  new
59       server  name is detected, another session is cached for the new server,
60       and the reconnect is repeated up to a maximum number of times  (default
61       5) that can be specified via the -m option.
62
63       The  choice  of  SMTP  or LMTP (-S option) determines the syntax of the
64       destination argument. With  SMTP,  one  can  specify  a  service  on  a
65       non-default  port  as host:service, and disable MX (mail exchanger) DNS
66       lookups with [host] or [host]:port.  The [] form is required  when  you
67       specify an IP address instead of a hostname.  An IPv6 address takes the
68       form [ipv6:address].  The default port  for  SMTP  is  taken  from  the
69       smtp/tcp  entry  in /etc/services, defaulting to 25 if the entry is not
70       found.
71
72       With LMTP, specify unix:pathname to connect to a local server listening
73       on  a  unix-domain  socket  bound to the specified pathname; otherwise,
74       specify an optional inet: prefix followed by a domain and  an  optional
75       port,  with  the same syntax as for SMTP. The default TCP port for LMTP
76       is 24.
77
78       Arguments:
79
80       -a family (default: any)
81              Address family preference: ipv4, ipv6 or any.  When  using  any,
82              posttls-finger  will  randomly select one of the two as the more
83              preferred, and exhaust all MX preferences for the first  address
84              family before trying any addresses for the other.
85
86       -A trust-anchor.pem (default: none)
87              A  list of PEM trust-anchor files that overrides CAfile and CAp‐
88              ath trust chain verification.  Specify the option multiple times
89              to  specify  multiple  files.  See the main.cf documentation for
90              smtp_tls_trust_anchor_file for details.
91
92       -c     Disable SMTP  chat  logging;  only  TLS-related  information  is
93              logged.
94
95       -C     Print the remote SMTP server certificate trust chain in PEM for‐
96              mat.  The issuer DN, subject DN, certificate and public key fin‐
97              gerprints (see -d mdalg option below) are printed above each PEM
98              certificate block.  If you specify -F CAfile or -P  CApath,  the
99              OpenSSL  library  may augment the chain with missing issuer cer‐
100              tificates.  To see the actual chain  sent  by  the  remote  SMTP
101              server leave CAfile and CApath unset.
102
103       -d mdalg (default: sha1)
104              The  message  digest  algorithm to use for reporting remote SMTP
105              server fingerprints and matching against user provided  certifi‐
106              cate fingerprints (with DANE TLSA records the algorithm is spec‐
107              ified in the DNS).
108
109       -f     Lookup the associated DANE TLSA RRset even when  a  hostname  is
110              not  an  alias  and its address records lie in an unsigned zone.
111              See smtp_tls_force_insecure_host_tlsa_lookup for details.
112
113       -F CAfile.pem (default: none)
114              The PEM formatted CAfile for remote SMTP server certificate ver‐
115              ification.   By  default no CAfile is used and no public CAs are
116              trusted.
117
118       -g grade (default: medium)
119              The minimum  TLS  cipher  grade  used  by  posttls-finger.   See
120              smtp_tls_mandatory_ciphers for details.
121
122       -h host_lookup (default: dns)
123              The  hostname  lookup  methods used for the connection.  See the
124              documentation of smtp_host_lookup for syntax and semantics.
125
126       -H chainfiles (default: none)
127              List of files with a sequence PEM-encoded TLS client certificate
128              chains.   The  list can be built-up incrementally, by specifying
129              the option multiple times, or all at once via a comma or  white‐
130              space  separated  list  of  filenames.  Each chain starts with a
131              private key, which is followed immediately by the  corresponding
132              certificate,  and  optionally by additional issuer certificates.
133              Each new key begins a new chain for the corresponding algorithm.
134              This  option  is  mutually  exclusive  with  the below -k and -K
135              options.
136
137       -k certfile (default: keyfile)
138              File  with  PEM-encoded  TLS  client  certificate  chain.   This
139              defaults to keyfile if one is specified.
140
141       -K keyfile (default: certfile)
142              File  with PEM-encoded TLS client private key.  This defaults to
143              certfile if one is specified.
144
145       -l level (default: dane or secure)
146              The security level for the connection, default  dane  or  secure
147              depending on whether DNSSEC is available.  For syntax and seman‐
148              tics, see the documentation  of  smtp_tls_security_level.   When
149              dane  or dane-only is supported and selected, if no TLSA records
150              are found, or all the records found  are  unusable,  the  secure
151              level  will  be  used  instead.   The fingerprint security level
152              allows you to test certificate or public-key fingerprint matches
153              before you deploy them in the policy table.
154
155              Note,  since posttls-finger does not actually deliver any email,
156              the none, may and encrypt security levels are not  very  useful.
157              Since may and encrypt don't require peer certificates, they will
158              often negotiate anonymous TLS ciphersuites, so you  won't  learn
159              much about the remote SMTP server's certificates at these levels
160              if it also supports anonymous TLS (though you may learn that the
161              server supports anonymous TLS).
162
163       -L logopts (default: routine,certmatch)
164              Fine-grained  TLS  logging  options.  To  tune  the TLS features
165              logged during the TLS handshake, specify one or more of:
166
167              0, none
168                     These yield no TLS logging; you'll generally  want  more,
169                     but this is handy if you just want the trust chain:
170                     $ posttls-finger -cC -L none destination
171
172              1, routine, summary
173                     These  synonymous  values yield a normal one-line summary
174                     of the TLS connection.
175
176              2, debug
177                     These synonymous values combine routine, ssl-debug, cache
178                     and verbose.
179
180              3, ssl-expert
181                     These  synonymous  values  combine  debug  with ssl-hand‐
182                     shake-packet-dump.  For experts only.
183
184              4, ssl-developer
185                     These synonymous values combine ssl-expert with  ssl-ses‐
186                     sion-packet-dump.   For  experts only, and in most cases,
187                     use wireshark instead.
188
189              ssl-debug
190                     Turn on OpenSSL logging of the progress of the SSL  hand‐
191                     shake.
192
193              ssl-handshake-packet-dump
194                     Log  hexadecimal  packet  dumps of the SSL handshake; for
195                     experts only.
196
197              ssl-session-packet-dump
198                     Log hexadecimal packet dumps of the entire  SSL  session;
199                     only  useful to those who can debug SSL protocol problems
200                     from hex dumps.
201
202              untrusted
203                     Logs trust chain verification problems.  This  is  turned
204                     on  automatically  at security levels that use peer names
205                     signed by Certification Authorities to validate  certifi‐
206                     cates.   So  while this setting is recognized, you should
207                     never need to set it explicitly.
208
209              peercert
210                     This logs a one line summary of the  remote  SMTP  server
211                     certificate subject, issuer, and fingerprints.
212
213              certmatch
214                     This  logs remote SMTP server certificate matching, show‐
215                     ing  the  CN  and  each  subjectAltName  and  which  name
216                     matched.    With  DANE,  logs  matching  of  TLSA  record
217                     trust-anchor and end-entity certificates.
218
219              cache  This logs session cache operations, showing whether  ses‐
220                     sion  caching  is  effective with the remote SMTP server.
221                     Automatically used when reconnecting with the -r  option;
222                     rarely needs to be set explicitly.
223
224              verbose
225                     Enables  verbose  logging  in  the  Postfix  TLS  driver;
226                     includes all of peercert..cache and more.
227
228              The default is routine,certmatch. After a  reconnect,  peercert,
229              certmatch and verbose are automatically disabled while cache and
230              summary are enabled.
231
232       -m count (default: 5)
233              When the -r delay option is specified, the -m option  determines
234              the  maximum  number  of reconnect attempts to use with a server
235              behind a load balancer, to see  whether  connection  caching  is
236              likely  to  be  effective for this destination.  Some MTAs don't
237              expose the underlying server identity in  their  EHLO  response;
238              with  these servers there will never be more than 1 reconnection
239              attempt.
240
241       -M insecure_mx_policy (default: dane)
242              The TLS policy for MX hosts with "secure" TLSA records when  the
243              nexthop  destination  security  level is dane, but the MX record
244              was found via an "insecure" MX lookup.  See the main.cf documen‐
245              tation for smtp_tls_insecure_mx_policy for details.
246
247       -o name=value
248              Specify  zero or more times to override the value of the main.cf
249              parameter name with value.  Possible use-cases include  overrid‐
250              ing  the  values  of  TLS library parameters, or "myhostname" to
251              configure the SMTP EHLO name sent to the remote server.
252
253       -p protocols (default: !SSLv2)
254              List of  TLS  protocols  that  posttls-finger  will  exclude  or
255              include.  See smtp_tls_mandatory_protocols for details.
256
257       -P CApath/ (default: none)
258              The  OpenSSL  CApath/  directory  (indexed  via c_rehash(1)) for
259              remote SMTP server certificate verification.  By default no CAp‐
260              ath is used and no public CAs are trusted.
261
262       -r delay
263              With  a  cacheable  TLS  session, disconnect and reconnect after
264              delay seconds. Report whether the session is re-used. Retry if a
265              new  server  is  encountered, up to 5 times or as specified with
266              the -m option.  By default reconnection is disabled,  specify  a
267              positive delay to enable this behavior.
268
269       -s servername
270              The  server  name  to  send  with the TLS Server Name Indication
271              (SNI) extension.  When the server has DANE  TLSA  records,  this
272              parameter  is  ignored and the TLSA base domain is used instead.
273              Otherwise, SNI is not used by default, but  can  be  enabled  by
274              specifying the desired value with this option.
275
276       -S     Disable  SMTP;  that  is, connect to an LMTP server. The default
277              port for LMTP over TCP is 24.  Alternative ports  can  specified
278              by  appending ":servicename" or ":portnumber" to the destination
279              argument.
280
281       -t timeout (default: 30)
282              The TCP connection timeout to use.  This is also the timeout for
283              reading the remote server's 220 banner.
284
285       -T timeout (default: 30)
286              The SMTP/LMTP command timeout for EHLO/LHLO, STARTTLS and QUIT.
287
288       -v     Enable  verbose  Postfix  logging.   Specify  more  than once to
289              increase the level of verbose logging.
290
291       -w     Enable outgoing TLS wrapper mode, or  SMTPS  support.   This  is
292              typically  provided  on  port 465 by servers that are compatible
293              with the ad-hoc SMTP in SSL protocol, rather than  the  standard
294              STARTTLS protocol.  The destination domain:port should of course
295              provide such a service.
296
297       -X     Enable tlsproxy(8) mode. This is an unsupported mode,  for  pro‐
298              gram development only.
299
300       [inet:]domain[:port]
301              Connect via TCP to domain domain, port port. The default port is
302              smtp (or 24 with LMTP).  With SMTP an MX lookup is performed  to
303              resolve  the  domain to a host, unless the domain is enclosed in
304              [].  If you want to connect to a specific MX host, for  instance
305              mx1.example.com,  specify  [mx1.example.com]  as the destination
306              and example.com as a match argument.  When using DNS, the desti‐
307              nation  domain  is assumed fully qualified and no default domain
308              or search suffixes are applied;  you  must  use  fully-qualified
309              names  or  also  enable native host lookups (these don't support
310              dane or dane-only as no DNSSEC validation information is  avail‐
311              able via native lookups).
312
313       unix:pathname
314              Connect to the UNIX-domain socket at pathname. LMTP only.
315
316       match ...
317              With no match arguments specified, certificate peername matching
318              uses the compiled-in default strategies for each security level.
319              If  you specify one or more arguments, these will be used as the
320              list of certificate or public-key digests to match for the  fin‐
321              gerprint level, or as the list of DNS names to match in the cer‐
322              tificate at the verify and secure levels.  If the security level
323              is dane, or dane-only the match names are ignored, and hostname,
324              nexthop strategies are used.
325

ENVIRONMENT

327       MAIL_CONFIG
328              Read configuration parameters from a non-default location.
329
330       MAIL_VERBOSE
331              Same as -v option.
332

SEE ALSO

334       smtp-source(1), SMTP/LMTP message source
335       smtp-sink(1), SMTP/LMTP message dump
336
337

README FILES

339       Use "postconf readme_directory" or "postconf html_directory" to  locate
340       this information.
341       TLS_README, Postfix STARTTLS howto
342

LICENSE

344       The Secure Mailer license must be distributed with this software.
345

AUTHOR(S)

347       Wietse Venema
348       IBM T.J. Watson Research
349       P.O. Box 704
350       Yorktown Heights, NY 10598, USA
351
352       Wietse Venema
353       Google, Inc.
354       111 8th Avenue
355       New York, NY 10011, USA
356
357       Viktor Dukhovni
358
359
360
361                                                             POSTTLS-FINGER(1)
Impressum