1POSTTLS-FINGER(1) General Commands Manual POSTTLS-FINGER(1)
2
6 posttls-finger - Probe the TLS properties of an ESMTP or LMTP server.
7
9 posttls-finger [options] [inet:]domain[:port] [match ...]
10 posttls-finger -S [options] unix:pathname [match ...]
11
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 Note: this is an unsupported test program. No attempt is made to main‐
22 tain compatibility between successive versions.
23 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 If TLS support is enabled when posttls-finger(1) is compiled, and the
29 server supports STARTTLS, a TLS handshake is attempted.
30 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 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 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 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 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 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 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 Arguments:
79 -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 -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 -c Disable SMTP chat logging; only TLS-related information is
93 logged.
94 -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 -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 -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 -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 -g grade (default: medium)
119 The minimum TLS cipher grade used by posttls-finger. See
120 smtp_tls_mandatory_ciphers for details.
121 -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 -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 -k certfile (default: keyfile)
138 File with PEM-encoded TLS client certificate chain. This
139 defaults to keyfile if one is specified.
140 -K keyfile (default: certfile)
142 File with PEM-encoded TLS client private key. This defaults to
143 certfile if one is specified.
144 -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 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 -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 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 1, routine, summary
173 These synonymous values yield a normal one-line summary
174 of the TLS connection.
175 2, debug
177 These synonymous values combine routine, ssl-debug, cache
178 and verbose.
179 3, ssl-expert
181 These synonymous values combine debug with ssl-hand‐
182 shake-packet-dump. For experts only.
183 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 ssl-debug
190 Turn on OpenSSL logging of the progress of the SSL hand‐
191 shake.
192 ssl-handshake-packet-dump
194 Log hexadecimal packet dumps of the SSL handshake; for
195 experts only.
196 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 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 peercert
210 This logs a one line summary of the remote SMTP server
211 certificate subject, issuer, and fingerprints.
212 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 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 verbose
225 Enables verbose logging in the Postfix TLS driver;
226 includes all of peercert..cache and more.
227 The default is routine,certmatch. After a reconnect, peercert,
229 certmatch and verbose are automatically disabled while cache and
230 summary are enabled.
231 -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 -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 -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 -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 -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 -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 -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 -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 -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 -T timeout (default: 30)
286 The SMTP/LMTP command timeout for EHLO/LHLO, STARTTLS and QUIT.
287 -v Enable verbose Postfix logging. Specify more than once to
289 increase the level of verbose logging.
290 -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 -X Enable tlsproxy(8) mode. This is an unsupported mode, for pro‐
298 gram development only.
299 [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 unix:pathname
314 Connect to the UNIX-domain socket at pathname. LMTP only.
315 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
327 MAIL_CONFIG
328 Read configuration parameters from a non-default location.
329 MAIL_VERBOSE
331 Same as -v option.
332
334 smtp-source(1), SMTP/LMTP message source
335 smtp-sink(1), SMTP/LMTP message dump
336
339 Use "postconf readme_directory" or "postconf html_directory" to locate
340 this information.
341 TLS_README, Postfix STARTTLS howto
342
344 The Secure Mailer license must be distributed with this software.
345
347 Wietse Venema
348 IBM T.J. Watson Research
349 P.O. Box 704
350 Yorktown Heights, NY 10598, USA
351 Wietse Venema
353 Google, Inc.
354 111 8th Avenue
355 New York, NY 10011, USA
356 Viktor Dukhovni
358 POSTTLS-FINGER(1)