Ubuntu Manpage: posttls-finger - Probe the TLS properties of an ESMTP or LMTP server.

Provided by: postfix_3.6.4-1ubuntu2_amd64

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 prefixed with unix:. If Postfix is
built without TLS support, the resulting posttls-finger program has very limited
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 versions.

For SMTP servers that don't support ESMTP, only the greeting 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 compiled, and the server supports
STARTTLS, a TLS handshake is attempted.

If DNSSEC support is available, the connection TLS security level (-l option) defaults to
dane; see TLS_README for details. Otherwise, it defaults to secure. This setting
determines the certificate matching policy.

If TLS negotiation succeeds, the TLS protocol and cipher details are reported. The server
certificate is then verified 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 disappears when the process exits.

With the -r delay option, if the server assigns a TLS session id, the TLS session is
cached. The connection is then closed and re-opened after the specified delay, and
posttls-finger(1) then reports whether the cached TLS session was re-used.

When the destination is a load balancer, it may be distributing 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 syntax of the destination argument.
With SMTP, one can specify 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. Specify 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 information 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 certificate 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: $smtp_tls_fingerprint_digest)
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). In Postfix versions prior to 3.6, the
default value was "sha1".

-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_insecure_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-finger. See
smtp_tls_mandatory_ciphers for details.

-h host_lookup (default: dns)
The hostname lookup methods used for the connection. See the documentation of
smtp_host_lookup for syntax and semantics.

-H chainfiles (default: none)
List of files with a sequence PEM-encoded TLS client certificate chains. The list
can be built-up incrementally, by specifying the option multiple times, or all at
once via a comma or whitespace separated list of filenames. Each chain starts with
a private key, which is followed immediately by the corresponding certificate, and
optionally by additional issuer certificates. Each new key begins a new chain for
the corresponding algorithm. This option is mutually exclusive with the below -k
and -K options.

-k certfile (default: keyfile)
File with PEM-encoded TLS client certificate chain. This defaults to keyfile if one
is specified.

-K keyfile (default: certfile)
File with PEM-encoded TLS client private key. This defaults to certfile if one is
specified.

-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 security 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 Certification Authorities to
validate certificates. 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
subjectAltName 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 reconnect, peercert, certmatch and
verbose are automatically 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 balancer, 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.

-M insecure_mx_policy (default: dane)
The TLS policy for MX hosts with "secure" TLSA records when the nexthop destination
security level is dane, but the MX record was found via an "insecure" MX lookup.
See the main.cf documentation for smtp_tls_insecure_mx_policy for details.

-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: >=TLSv1)
TLS protocols that posttls-finger will exclude or include. See
smtp_tls_mandatory_protocols 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 cacheable TLS session, disconnect and reconnect after delay seconds. Report
whether the session is re-used. Retry if a new server is encountered, up to 5 times
or as specified with the -m option. By default reconnection is disabled, specify a
positive delay to enable this behavior.

-s servername
The server name to send with the TLS Server Name Indication (SNI) extension. When
the server has DANE TLSA records, this parameter is ignored and the TLSA base
domain is used instead. Otherwise, SNI is not used by default, but can be enabled
by specifying the desired value with this option.

-S Disable SMTP; that is, connect to an LMTP server. The default port for LMTP over
TCP is 24. Alternative ports can specified by appending ":servicename" 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, STARTTLS and QUIT.

-v Enable verbose Postfix logging. Specify more than once to increase the level of
verbose logging.

-w Enable outgoing TLS wrapper mode, or SMTPS support. This is typically provided on
port 465 by servers that are compatible with the ad-hoc SMTP in SSL protocol,
rather than the standard STARTTLS protocol. The destination domain:port should of
course provide such a service.

-X Enable tlsproxy(8) mode. This is an unsupported mode, for program development only.

[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 argument. 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 hostname, nexthop strategies are used.

ENVIRONMENT

       MAIL_CONFIG
              Read configuration parameters from a non-default location.

       MAIL_VERBOSE
              Same as -v option.

README FILES

       Use "postconf readme_directory" or "postconf html_directory" to locate this information.
       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

       Wietse Venema
       Google, Inc.
       111 8th Avenue
       New York, NY 10011, USA

       Viktor Dukhovni

                                                                                POSTTLS-FINGER(1)