7
Probe the TLS properties of an ESMTP or LMTP server.
11
\fBposttls-finger\fR [\fIoptions\fR] [\fBinet:\fR]\fIdomain\fR[:\fIport\fR] [\fImatch ...\fR]
13
\fBposttls-finger\fR -S [\fIoptions\fR] \fBunix:\fIpathname\fR [\fImatch ...\fR]
17
\fBposttls-finger\fR(1) connects to the specified destination
18
and reports TLS-related information about the server. With SMTP, the
19
destination is a domainname; with LMTP it is either a domainname
20
prefixed with \fBinet:\fR or a pathname prefixed with \fBunix:\fR. If
21
Postfix is built without TLS support, the resulting posttls-finger
22
program has very limited functionality, and only the \fB-a\fR, \fB-c\fR,
23
\fB-h\fR, \fB-o\fR, \fB-S\fR, \fB-t\fR, \fB-T\fR and \fB-v\fR options
26
Note: this is an unsupported test program. No attempt is made
27
to maintain compatibility between successive versions.
29
For SMTP servers that don't support ESMTP, only the greeting banner
30
and the negative EHLO response are reported. Otherwise, the reported
31
EHLO response details further server capabilities.
33
If TLS support is enabled when \fBposttls-finger\fR(1) is compiled, and
34
the server supports \fBSTARTTLS\fR, a TLS handshake is attempted.
36
If DNSSEC support is available, the connection TLS security level
37
(\fB-l\fR option) defaults to \fBdane\fR; see TLS_README for
38
details. Otherwise, it defaults to \fBsecure\fR. This setting
39
determines the certificate matching policy.
41
If TLS negotiation succeeds, the TLS protocol and cipher details are
42
reported. The server certificate is then verified in accordance with
43
the policy at the chosen (or default) security level. With public
44
CA-based trust, when the \fB-L\fR option includes \fBcertmatch\fR,
45
(true by default) name matching is performed even if the certificate
46
chain is not trusted. This logs the names found in the remote SMTP
47
server certificate and which if any would match, were the certificate
50
Note: \fBposttls-finger\fR(1) does not perform any table lookups, so
51
the TLS policy table and obsolete per-site tables are not consulted.
52
It does not communicate with the \fBtlsmgr\fR(8) daemon (or any other
53
Postfix daemons); its TLS session cache is held in private memory, and
54
disappears when the process exits.
56
With the \fB-r \fIdelay\fR option, if the server assigns a TLS
57
session id, the TLS session is cached. The connection is then closed
58
and re-opened after the specified delay, and \fBposttls-finger\fR(1)
59
then reports whether the cached TLS session was re-used.
61
When the destination is a load-balancer, it may be distributing
62
load between multiple server caches. Typically, each server returns
63
its unique name in its EHLO response. If, upon reconnecting with
64
\fB-r\fR, a new server name is detected, another session is cached
65
for the new server, and the reconnect is repeated up to a maximum
66
number of times (default 5) that can be specified via the \fB-m\fR
69
The choice of SMTP or LMTP (\fB-S\fR option) determines the syntax of
70
the destination argument. With SMTP, one can specify a service on a
71
non-default port as \fIhost\fR:\fIservice\fR, and disable MX (mail
72
exchanger) DNS lookups with [\fIhost\fR] or [\fIhost\fR]:\fIport\fR.
73
The [] form is required when you specify an IP address instead of a
74
hostname. An IPv6 address takes the form [\fBipv6:\fIaddress\fR].
75
The default port for SMTP is taken from the \fBsmtp/tcp\fR entry in
76
/etc/services, defaulting to 25 if the entry is not found.
78
With LMTP, specify \fBunix:\fIpathname\fR to connect to a local server
79
listening on a unix-domain socket bound to the specified pathname;
80
otherwise, specify an optional \fBinet:\fR prefix followed by a
81
\fIdomain\fR and an optional port, with the same syntax as for
82
SMTP. The default TCP port for LMTP is 24.
85
.IP "\fB-a\fR \fIfamily\fR (default: \fBany\fR)"
86
Address family preference: \fBipv4\fR, \fBipv6\fR or \fBany\fR. When
87
using \fBany\fR, posttls-finger will randomly select one of the two as
88
the more preferred, and exhaust all MX preferences for the first
89
address family before trying any addresses for the other.
90
.IP "\fB-A\fR \fItrust-anchor.pem\fR (default: none)"
91
A list of PEM trust-anchor files that overrides CAfile and CApath
92
trust chain verification. Specify the option multiple times to
93
specify multiple files. See the main.cf documentation for
94
smtp_tls_trust_anchor_file for details.
96
Disable SMTP chat logging; only TLS-related information is logged.
98
Print the remote SMTP server certificate trust chain in PEM format.
99
The issuer DN, subject DN, certificate and public key fingerprints
100
(see \fB-d \fImdalg\fR option below) are printed above each PEM
101
certificate block. If you specify \fB-F \fICAfile\fR or
102
\fB-P \fICApath\fR, the OpenSSL library may augment the chain with
103
missing issuer certificates. To see the actual chain sent by the
104
remote SMTP server leave \fICAfile\fR and \fICApath\fR unset.
105
.IP "\fB-d \fImdalg\fR (default: \fBsha1\fR)"
106
The message digest algorithm to use for reporting remote SMTP server
107
fingerprints and matching against user provided certificate
108
fingerprints (with DANE TLSA records the algorithm is specified
111
Lookup the associated DANE TLSA RRset even when a hostname is not an
112
alias and its address records lie in an unsigned zone. See
113
smtp_tls_force_insecure_host_tlsa_lookup for details.
114
.IP "\fB-F \fICAfile.pem\fR (default: none)"
115
The PEM formatted CAfile for remote SMTP server certificate
116
verification. By default no CAfile is used and no public CAs
118
.IP "\fB-g \fIgrade\fR (default: medium)"
119
The minimum TLS cipher grade used by posttls-finger. See
120
smtp_tls_mandatory_ciphers for details.
121
.IP "\fB-h \fIhost_lookup\fR (default: \fBdns\fR)"
122
The hostname lookup methods used for the connection. See the
123
documentation of smtp_host_lookup for syntax and semantics.
124
.IP "\fB-l \fIlevel\fR (default: \fBdane\fR or \fBsecure\fR)"
125
The security level for the connection, default \fBdane\fR or
126
\fBsecure\fR depending on whether DNSSEC is available. For syntax
127
and semantics, see the documentation of smtp_tls_security_level.
128
When \fBdane\fR or \fBdane-only\fR is supported and selected, if no
129
TLSA records are found, or all the records found are unusable, the
130
\fIsecure\fR level will be used instead. The \fBfingerprint\fR
131
security level allows you to test certificate or public-key
132
fingerprint matches before you deploy them in the policy table.
134
Note, since \fBposttls-finger\fR does not actually deliver any email,
135
the \fBnone\fR, \fBmay\fR and \fBencrypt\fR security levels are not
136
very useful. Since \fBmay\fR and \fBencrypt\fR don't require peer
137
certificates, they will often negotiate anonymous TLS ciphersuites,
138
so you won't learn much about the remote SMTP server's certificates
139
at these levels if it also supports anonymous TLS (though you may
140
learn that the server supports anonymous TLS).
141
.IP "\fB-L \fIlogopts\fR (default: \fBroutine,certmatch\fR)"
142
Fine-grained TLS logging options. To tune the TLS features logged
143
during the TLS handshake, specify one or more of:
146
These yield no TLS logging; you'll generally want more, but this
147
is handy if you just want the trust chain:
151
$ posttls-finger -cC -L none destination
154
.IP "\fB1, routine, summary\fR"
155
These synonymous values yield a normal one-line summary of the TLS
158
These synonymous values combine routine, ssl-debug, cache and verbose.
159
.IP "\fB3, ssl-expert\fR"
160
These synonymous values combine debug with ssl-handshake-packet-dump.
162
.IP "\fB4, ssl-developer\fR"
163
These synonymous values combine ssl-expert with ssl-session-packet-dump.
164
For experts only, and in most cases, use wireshark instead.
165
.IP "\fBssl-debug\fR"
166
Turn on OpenSSL logging of the progress of the SSL handshake.
167
.IP "\fBssl-handshake-packet-dump\fR"
168
Log hexadecimal packet dumps of the SSL handshake; for experts only.
169
.IP "\fBssl-session-packet-dump\fR"
170
Log hexadecimal packet dumps of the entire SSL session; only useful
171
to those who can debug SSL protocol problems from hex dumps.
172
.IP "\fBuntrusted\fR"
173
Logs trust chain verification problems. This is turned on
174
automatically at security levels that use peer names signed
175
by certificate authorities to validate certificates. So while
176
this setting is recognized, you should never need to set it
179
This logs a one line summary of the remote SMTP server certificate
180
subject, issuer, and fingerprints.
181
.IP "\fBcertmatch\fR"
182
This logs remote SMTP server certificate matching, showing the CN
183
and each subjectAltName and which name matched. With DANE, logs
184
matching of TLSA record trust-anchor and end-entity certificates.
186
This logs session cache operations, showing whether session caching
187
is effective with the remote SMTP server. Automatically used when
188
reconnecting with the \fB-r\fR option; rarely needs to be set
191
Enables verbose logging in the Postfix TLS driver; includes all of
192
peercert..cache and more.
195
The default is \fBroutine,certmatch\fR. After a reconnect,
196
\fBpeercert\fR, \fBcertmatch\fR and \fBverbose\fR are automatically
197
disabled while \fBcache\fR and \fBsummary\fR are enabled.
198
.IP "\fB-m \fIcount\fR (default: \fB5\fR)"
199
When the \fB-r \fIdelay\fR option is specified, the \fB-m\fR option
200
determines the maximum number of reconnect attempts to use with
201
a server behind a load-balacer, to see whether connection caching
202
is likely to be effective for this destination. Some MTAs
203
don't expose the underlying server identity in their EHLO
204
response; with these servers there will never be more than
205
1 reconnection attempt.
206
.IP "\fB-o \fIname=value\fR"
207
Specify zero or more times to override the value of the main.cf
208
parameter \fIname\fR with \fIvalue\fR. Possible use-cases include
209
overriding the values of TLS library parameters, or "myhostname" to
210
configure the SMTP EHLO name sent to the remote server.
211
.IP "\fB-p \fIprotocols\fR (default: !SSLv2)"
212
List of TLS protocols that posttls-finger will exclude or include. See
213
smtp_tls_mandatory_protocols for details.
214
.IP "\fB-P \fICApath/\fR (default: none)"
215
The OpenSSL CApath/ directory (indexed via c_rehash(1)) for remote
216
SMTP server certificate verification. By default no CApath is used
217
and no public CAs are trusted.
218
.IP "\fB-r \fIdelay\fR"
219
With a cachable TLS session, disconnect and reconnect after \fIdelay\fR
220
seconds. Report whether the session is re-used. Retry if a new server
221
is encountered, up to 5 times or as specified with the \fB-m\fR option.
222
By default reconnection is disabled, specify a positive delay to
223
enable this behavior.
225
Disable SMTP; that is, connect to an LMTP server. The default port for
226
LMTP over TCP is 24. Alternative ports can specified by appending
227
"\fI:servicename\fR" or ":\fIportnumber\fR" to the destination
229
.IP "\fB-t \fItimeout\fR (default: \fB30\fR)"
230
The TCP connection timeout to use. This is also the timeout for
231
reading the remote server's 220 banner.
232
.IP "\fB-T \fItimeout\fR (default: \fB30\fR)"
233
The SMTP/LMTP command timeout for EHLO/LHLO, STARTTLS and QUIT.
235
Enable verose Postfix logging. Specify more than once to increase
236
the level of verbose logging.
237
.IP "[\fBinet:\fR]\fIdomain\fR[:\fIport\fR]"
238
Connect via TCP to domain \fIdomain\fR, port \fIport\fR. The default
239
port is \fBsmtp\fR (or 24 with LMTP). With SMTP an MX lookup is
240
performed to resolve the domain to a host, unless the domain is
241
enclosed in \fB[]\fR. If you want to connect to a specific MX host,
242
for instance \fImx1.example.com\fR, specify [\fImx1.example.com\fR]
243
as the destination and \fIexample.com\fR as a \fBmatch\fR argument.
244
When using DNS, the destination domain is assumed fully qualified
245
and no default domain or search suffixes are applied; you must use
246
fully-qualified names or also enable \fBnative\fR host lookups
247
(these don't support \fBdane\fR or \fBdane-only\fR as no DNSSEC
248
validation information is available via \fBnative\fR lookups).
249
.IP "\fBunix:\fIpathname\fR"
250
Connect to the UNIX-domain socket at \fIpathname\fR. LMTP only.
251
.IP "\fBmatch ...\fR"
252
With no match arguments specified, certificate peername matching uses
253
the compiled-in default strategies for each security level. If you
254
specify one or more arguments, these will be used as the list of
255
certificate or public-key digests to match for the \fBfingerprint\fR
256
level, or as the list of DNS names to match in the certificate at the
257
\fBverify\fR and \fBsecure\fR levels. If the security level is
258
\fBdane\fR, or \fBdane-only\fR the match names are ignored, and
259
\fBhostname, nexthop\fR strategies are used.
267
.IP \fBMAIL_CONFIG\fR
268
Read configuration parameters from a non-default location.
269
.IP \fBMAIL_VERBOSE\fR
270
Same as \fB-v\fR option.
274
smtp-source(1), SMTP/LMTP message source
275
smtp-sink(1), SMTP/LMTP message dump
282
Use "\fBpostconf readme_directory\fR" or "\fBpostconf
283
html_directory\fR" to locate this information.
286
TLS_README, Postfix STARTTLS howto
292
The Secure Mailer license must be distributed with this software.
297
IBM T.J. Watson Research
299
Yorktown Heights, NY 10598, USA
added
removed
man/man1/posttls-finger.1
