POSTTLS-FINGER(1) POSTTLS-FINGER(1)
NAME
posttls-finger - Probe the TLS properties of an ESMTP or
LMTP server.
SYNOPSIS
posttls-finger [options] [inet:]domain[:port] [match ...]
posttls-finger -S [options] unix:pathname [match ...]
DESCRIPTION
posttls-finger(1) connects to the specified destination
and reports TLS-related information about the server. With
SMTP, the destination is a domainname; with LMTP it is
either a domainname prefixed with inet: or a pathname pre-
fixed with unix:. If Postfix is built without TLS sup-
port, the resulting posttls-finger program has very lim-
ited functionality, and only the -a, -c, -h, -o, -S, -t,
-T and -v options are available.
Note: this is an unsupported test program. No attempt is
made to maintain compatibility between successive ver-
sions.
For SMTP servers that don't support ESMTP, only the greet-
ing banner and the negative EHLO response are reported.
Otherwise, the reported EHLO response details further
server capabilities.
If TLS support is enabled when posttls-finger(1) is com-
piled, and the server supports STARTTLS, a TLS handshake
is attempted.
If DNSSEC support is available, the connection TLS secu-
rity level (-l option) defaults to dane; see TLS_README
for details. Otherwise, it defaults to secure. This set-
ting determines the certificate matching policy.
If TLS negotiation succeeds, the TLS protocol and cipher
details are reported. The server certificate is then veri-
fied in accordance with the policy at the chosen (or
default) security level. With public CA-based trust, when
the -L option includes certmatch, (true by default) name
matching is performed even if the certificate chain is not
trusted. This logs the names found in the remote SMTP
server certificate and which if any would match, were the
certificate chain trusted.
Note: posttls-finger(1) does not perform any table
lookups, so the TLS policy table and obsolete per-site
tables are not consulted. It does not communicate with
the tlsmgr(8) daemon (or any other Postfix daemons); its
TLS session cache is held in private memory, and disap-
pears when the process exits.
With the -r delay option, if the server assigns a TLS ses-
sion id, the TLS session is cached. The connection is then
closed and re-opened after the specified delay, and post-
tls-finger(1) then reports whether the cached TLS session
was re-used.
When the destination is a load-balancer, it may be dis-
tributing load between multiple server caches. Typically,
each server returns its unique name in its EHLO response.
If, upon reconnecting with -r, a new server name is
detected, another session is cached for the new server,
and the reconnect is repeated up to a maximum number of
times (default 5) that can be specified via the -m option.
The choice of SMTP or LMTP (-S option) determines the syn-
tax of the destination argument. With SMTP, one can spec-
ify a service on a non-default port as host:service, and
disable MX (mail exchanger) DNS lookups with [host] or
[host]:port. The [] form is required when you specify an
IP address instead of a hostname. An IPv6 address takes
the form [ipv6:address]. The default port for SMTP is
taken from the smtp/tcp entry in /etc/services, defaulting
to 25 if the entry is not found.
With LMTP, specify unix:pathname to connect to a local
server listening on a unix-domain socket bound to the
specified pathname; otherwise, specify an optional inet:
prefix followed by a domain and an optional port, with the
same syntax as for SMTP. The default TCP port for LMTP is
24.
Arguments:
-a family (default: any)
Address family preference: ipv4, ipv6 or any. When
using any, posttls-finger will randomly select one
of the two as the more preferred, and exhaust all
MX preferences for the first address family before
trying any addresses for the other.
-A trust-anchor.pem (default: none)
A list of PEM trust-anchor files that overrides
CAfile and CApath trust chain verification. Spec-
ify the option multiple times to specify multiple
files. See the main.cf documentation for
smtp_tls_trust_anchor_file for details.
-c Disable SMTP chat logging; only TLS-related infor-
mation is logged.
-C Print the remote SMTP server certificate trust
chain in PEM format. The issuer DN, subject DN,
certificate and public key fingerprints (see -d
mdalg option below) are printed above each PEM cer-
tificate block. If you specify -F CAfile or -P
CApath, the OpenSSL library may augment the chain
with missing issuer certificates. To see the
actual chain sent by the remote SMTP server leave
CAfile and CApath unset.
-d mdalg (default: sha1)
The message digest algorithm to use for reporting
remote SMTP server fingerprints and matching
against user provided certificate fingerprints
(with DANE TLSA records the algorithm is specified
in the DNS).
-f Lookup the associated DANE TLSA RRset even when a
hostname is not an alias and its address records
lie in an unsigned zone. See smtp_tls_force_inse-
cure_host_tlsa_lookup for details.
-F CAfile.pem (default: none)
The PEM formatted CAfile for remote SMTP server
certificate verification. By default no CAfile is
used and no public CAs are trusted.
-g grade (default: medium)
The minimum TLS cipher grade used by posttls-fin-
ger. See smtp_tls_mandatory_ciphers for details.
-h host_lookup (default: dns)
The hostname lookup methods used for the connec-
tion. See the documentation of smtp_host_lookup
for syntax and semantics.
-l level (default: dane or secure)
The security level for the connection, default dane
or secure depending on whether DNSSEC is available.
For syntax and semantics, see the documentation of
smtp_tls_security_level. When dane or dane-only is
supported and selected, if no TLSA records are
found, or all the records found are unusable, the
secure level will be used instead. The fingerprint
security level allows you to test certificate or
public-key fingerprint matches before you deploy
them in the policy table.
Note, since posttls-finger does not actually
deliver any email, the none, may and encrypt secu-
rity levels are not very useful. Since may and
encrypt don't require peer certificates, they will
often negotiate anonymous TLS ciphersuites, so you
won't learn much about the remote SMTP server's
certificates at these levels if it also supports
anonymous TLS (though you may learn that the server
supports anonymous TLS).
-L logopts (default: routine,certmatch)
Fine-grained TLS logging options. To tune the TLS
features logged during the TLS handshake, specify
one or more of:
0, none
These yield no TLS logging; you'll generally
want more, but this is handy if you just
want the trust chain:
$ posttls-finger -cC -L none destination
1, routine, summary
These synonymous values yield a normal one-
line summary of the TLS connection.
2, debug
These synonymous values combine routine,
ssl-debug, cache and verbose.
3, ssl-expert
These synonymous values combine debug with
ssl-handshake-packet-dump. For experts
only.
4, ssl-developer
These synonymous values combine ssl-expert
with ssl-session-packet-dump. For experts
only, and in most cases, use wireshark
instead.
ssl-debug
Turn on OpenSSL logging of the progress of
the SSL handshake.
ssl-handshake-packet-dump
Log hexadecimal packet dumps of the SSL
handshake; for experts only.
ssl-session-packet-dump
Log hexadecimal packet dumps of the entire
SSL session; only useful to those who can
debug SSL protocol problems from hex dumps.
untrusted
Logs trust chain verification problems.
This is turned on automatically at security
levels that use peer names signed by cer-
tificate authorities to validate certifi-
cates. So while this setting is recognized,
you should never need to set it explicitly.
peercert
This logs a one line summary of the remote
SMTP server certificate subject, issuer, and
fingerprints.
certmatch
This logs remote SMTP server certificate
matching, showing the CN and each subjec-
tAltName and which name matched. With DANE,
logs matching of TLSA record trust-anchor
and end-entity certificates.
cache This logs session cache operations, showing
whether session caching is effective with
the remote SMTP server. Automatically used
when reconnecting with the -r option; rarely
needs to be set explicitly.
verbose
Enables verbose logging in the Postfix TLS
driver; includes all of peercert..cache and
more.
The default is routine,certmatch. After a recon-
nect, peercert, certmatch and verbose are automati-
cally disabled while cache and summary are enabled.
-m count (default: 5)
When the -r delay option is specified, the -m
option determines the maximum number of reconnect
attempts to use with a server behind a load-bal-
acer, to see whether connection caching is likely
to be effective for this destination. Some MTAs
don't expose the underlying server identity in
their EHLO response; with these servers there will
never be more than 1 reconnection attempt.
-o name=value
Specify zero or more times to override the value of
the main.cf parameter name with value. Possible
use-cases include overriding the values of TLS
library parameters, or "myhostname" to configure
the SMTP EHLO name sent to the remote server.
-p protocols (default: !SSLv2)
List of TLS protocols that posttls-finger will
exclude or include. See smtp_tls_mandatory_proto-
cols for details.
-P CApath/ (default: none)
The OpenSSL CApath/ directory (indexed via
c_rehash(1)) for remote SMTP server certificate
verification. By default no CApath is used and no
public CAs are trusted.
-r delay
With a cachable TLS session, disconnect and recon-
nect after delay seconds. Report whether the ses-
sion is re-used. Retry if a new server is encoun-
tered, up to 5 times or as specified with the -m
option. By default reconnection is disabled, spec-
ify a positive delay to enable this behavior.
-S Disable SMTP; that is, connect to an LMTP server.
The default port for LMTP over TCP is 24. Alterna-
tive ports can specified by appending ":service-
name" or ":portnumber" to the destination argument.
-t timeout (default: 30)
The TCP connection timeout to use. This is also
the timeout for reading the remote server's 220
banner.
-T timeout (default: 30)
The SMTP/LMTP command timeout for EHLO/LHLO, START-
TLS and QUIT.
-v Enable verose Postfix logging. Specify more than
once to increase the level of verbose logging.
[inet:]domain[:port]
Connect via TCP to domain domain, port port. The
default port is smtp (or 24 with LMTP). With SMTP
an MX lookup is performed to resolve the domain to
a host, unless the domain is enclosed in []. If
you want to connect to a specific MX host, for
instance mx1.example.com, specify [mx1.example.com]
as the destination and example.com as a match argu-
ment. When using DNS, the destination domain is
assumed fully qualified and no default domain or
search suffixes are applied; you must use fully-
qualified names or also enable native host lookups
(these don't support dane or dane-only as no DNSSEC
validation information is available via native
lookups).
unix:pathname
Connect to the UNIX-domain socket at pathname. LMTP
only.
match ...
With no match arguments specified, certificate
peername matching uses the compiled-in default
strategies for each security level. If you specify
one or more arguments, these will be used as the
list of certificate or public-key digests to match
for the fingerprint level, or as the list of DNS
names to match in the certificate at the verify and
secure levels. If the security level is dane, or
dane-only the match names are ignored, and host-
name, nexthop strategies are used.
ENVIRONMENT
MAIL_CONFIG
Read configuration parameters from a non-default
location.
MAIL_VERBOSE
Same as -v option.
SEE ALSO
smtp-source(1), SMTP/LMTP message source
smtp-sink(1), SMTP/LMTP message dump
README FILES
TLS_README, Postfix STARTTLS howto
LICENSE
The Secure Mailer license must be distributed with this
software.
AUTHOR(S)
Wietse Venema
IBM T.J. Watson Research
P.O. Box 704
Yorktown Heights, NY 10598, USA
Viktor Dukhovni
POSTTLS-FINGER(1)