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

ENVIRONMENT

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

SEE ALSO

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

README FILES

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

LICENSE

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

AUTHOR(S)

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