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(1) 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 de‐
33 faults 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 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 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 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 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 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 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 Arguments:
77 -a family (default: any)
79 Address family preference: ipv4, ipv6 or any. When using any,
80 posttls-finger(1) will randomly select one of the two as the
81 more preferred, and exhaust all MX preferences for the first ad‐
82 dress family before trying any addresses for the other.
83 -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 -c Disable SMTP chat logging; only TLS-related information is
91 logged.
92 -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 -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 "md5".
107 -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 -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 -g grade (default: medium)
118 The minimum TLS cipher grade used by posttls-finger(1). See
119 smtp_tls_mandatory_ciphers for details.
120 -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 -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 -k certfile (default: keyfile)
137 File with PEM-encoded TLS client certificate chain. This de‐
138 faults to keyfile if one is specified.
139 -K keyfile (default: certfile)
141 File with PEM-encoded TLS client private key. This defaults to
142 certfile if one is specified.
143 -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 Note, since posttls-finger(1) does not actually deliver any
155 email, the none, may and encrypt security levels are not very
156 useful. Since may and encrypt don't require peer certificates,
157 they will often negotiate anonymous TLS ciphersuites, so you
158 won't learn much about the remote SMTP server's certificates at
159 these levels if it also supports anonymous TLS (though you may
160 learn that the server supports anonymous TLS).
161 -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 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 1, routine, summary
172 These synonymous values yield a normal one-line summary
173 of the TLS connection.
174 2, debug
176 These synonymous values combine routine, ssl-debug, cache
177 and verbose.
178 3, ssl-expert
180 These synonymous values combine debug with ssl-hand‐
181 shake-packet-dump. For experts only.
182 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 ssl-debug
189 Turn on OpenSSL logging of the progress of the SSL hand‐
190 shake.
191 ssl-handshake-packet-dump
193 Log hexadecimal packet dumps of the SSL handshake; for
194 experts only.
195 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 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 peercert
209 This logs a one line summary of the remote SMTP server
210 certificate subject, issuer, and fingerprints.
211 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 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 verbose
224 Enables verbose logging in the Postfix TLS driver; in‐
225 cludes all of peercert..cache and more.
226 The default is routine,certmatch. After a reconnect, peercert,
228 certmatch and verbose are automatically disabled while cache and
229 summary are enabled.
230 -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 -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_dane_insecure_mx_policy for details.
245 -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 -p protocols (default: >=TLSv1)
253 TLS protocols that posttls-finger(1) will exclude or include.
254 See smtp_tls_mandatory_protocols for details.
255 -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 -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 -R Use SRV lookup instead of MX.
269 -s servername
271 The server name to send with the TLS Server Name Indication
272 (SNI) extension. When the server has DANE TLSA records, this
273 parameter is ignored and the TLSA base domain is used instead.
274 Otherwise, SNI is not used by default, but can be enabled by
275 specifying the desired value with this option.
276 -S Disable SMTP; that is, connect to an LMTP server. The default
278 port for LMTP over TCP is 24. Alternative ports can specified
279 by appending ":servicename" or ":portnumber" to the destination
280 argument.
281 -t timeout (default: 30)
283 The TCP connection timeout to use. This is also the timeout for
284 reading the remote server's 220 banner.
285 -T timeout (default: 30)
287 The SMTP/LMTP command timeout for EHLO/LHLO, STARTTLS and QUIT.
288 -v Enable verbose Postfix logging. Specify more than once to in‐
290 crease the level of verbose logging.
291 -w Enable outgoing TLS wrapper mode, or SUBMISSIONS/SMTPS support.
293 This is typically provided on port 465 by servers that are com‐
294 patible with the SMTP-in-SSL protocol, rather than the STARTTLS
295 protocol. The destination domain:port must of course provide
296 such a service.
297 -X Enable tlsproxy(8) mode. This is an unsupported mode, for pro‐
299 gram development only.
300 [inet:]domain[:port]
302 Connect via TCP to domain domain, port port. The default port is
303 smtp (or 24 with LMTP). With SMTP an MX lookup is performed to
304 resolve the domain to a host, unless the domain is enclosed in
305 []. If you want to connect to a specific MX host, for instance
306 mx1.example.com, specify [mx1.example.com] as the destination
307 and example.com as a match argument. When using DNS, the desti‐
308 nation domain is assumed fully qualified and no default domain
309 or search suffixes are applied; you must use fully-qualified
310 names or also enable native host lookups (these don't support
311 dane or dane-only as no DNSSEC validation information is avail‐
312 able via native lookups).
313 unix:pathname
315 Connect to the UNIX-domain socket at pathname. LMTP only.
316 match ...
318 With no match arguments specified, certificate peername matching
319 uses the compiled-in default strategies for each security level.
320 If you specify one or more arguments, these will be used as the
321 list of certificate or public-key digests to match for the fin‐
322 gerprint level, or as the list of DNS names to match in the cer‐
323 tificate at the verify and secure levels. If the security level
324 is dane, or dane-only the match names are ignored, and hostname,
325 nexthop strategies are used.
326
328 MAIL_CONFIG
329 Read configuration parameters from a non-default location.
330 MAIL_VERBOSE
332 Same as -v option.
333
335 smtp-source(1), SMTP/LMTP message source
336 smtp-sink(1), SMTP/LMTP message dump
337
340 Use "postconf readme_directory" or "postconf html_directory" to locate
341 this information.
342 TLS_README, Postfix STARTTLS howto
343
345 The Secure Mailer license must be distributed with this software.
346
348 Wietse Venema
349 IBM T.J. Watson Research
350 P.O. Box 704
351 Yorktown Heights, NY 10598, USA
352 Wietse Venema
354 Google, Inc.
355 111 8th Avenue
356 New York, NY 10011, USA
357 Viktor Dukhovni
359 POSTTLS-FINGER(1)