posttls-finger.1.html [plain text]
<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html> <head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<title> Postfix manual - posttls-finger(1) </title>
</head> <body> <pre>
POSTTLS-FINGER(1) POSTTLS-FINGER(1)
<b>NAME</b>
posttls-finger - Probe the TLS properties of an ESMTP or LMTP server.
<b>SYNOPSIS</b>
<b>posttls-finger</b> [<i>options</i>] [<b>inet:</b>]<i>domain</i>[:<i>port</i>] [<i>match ...</i>]
<b>posttls-finger</b> -S [<i>options</i>] <b>unix:</b><i>pathname</i> [<i>match ...</i>]
<b>DESCRIPTION</b>
<a href="posttls-finger.1.html"><b>posttls-finger</b>(1)</a> 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 <b>inet:</b>
or a pathname prefixed with <b>unix:</b>. If Postfix is built without TLS
support, the resulting posttls-finger program has very limited func-
tionality, and only the <b>-a</b>, <b>-c</b>, <b>-h</b>, <b>-o</b>, <b>-S</b>, <b>-t</b>, <b>-T</b> and <b>-v</b> options are
available.
Note: this is an unsupported test program. No attempt is made to main-
tain 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 <a href="posttls-finger.1.html"><b>posttls-finger</b>(1)</a> is compiled, and the
server supports <b>STARTTLS</b>, a TLS handshake is attempted.
If DNSSEC support is available, the connection TLS security level (<b>-l</b>
option) defaults to <b>dane</b>; see <a href="TLS_README.html">TLS_README</a> for details. Otherwise, it
defaults to <b>secure</b>. 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 <b>-L</b> option includes <b>certmatch</b>, (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 cer-
tificate and which if any would match, were the certificate chain
trusted.
Note: <a href="posttls-finger.1.html"><b>posttls-finger</b>(1)</a> 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 <a href="tlsmgr.8.html"><b>tlsmgr</b>(8)</a> daemon (or any other Postfix dae-
mons); its TLS session cache is held in private memory, and disappears
when the process exits.
With the <b>-r</b> <i>delay</i> 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 <a href="posttls-finger.1.html"><b>posttls-finger</b>(1)</a> 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 <b>-r</b>, 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 <b>-m</b> option.
The choice of SMTP or LMTP (<b>-S</b> option) determines the syntax of the
destination argument. With SMTP, one can specify a service on a
non-default port as <i>host</i>:<i>service</i>, and disable MX (mail exchanger) DNS
lookups with [<i>host</i>] or [<i>host</i>]:<i>port</i>. The [] form is required when you
specify an IP address instead of a hostname. An IPv6 address takes the
form [<b>ipv6:</b><i>address</i>]. The default port for SMTP is taken from the
<b>smtp/tcp</b> entry in /etc/services, defaulting to 25 if the entry is not
found.
With LMTP, specify <b>unix:</b><i>pathname</i> to connect to a local server listening
on a unix-domain socket bound to the specified pathname; otherwise,
specify an optional <b>inet:</b> prefix followed by a <i>domain</i> and an optional
port, with the same syntax as for SMTP. The default TCP port for LMTP
is 24.
Arguments:
<b>-a</b> <i>family</i> (default: <b>any</b>)
Address family preference: <b>ipv4</b>, <b>ipv6</b> or <b>any</b>. When using <b>any</b>,
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.
<b>-A</b> <i>trust-anchor.pem</i> (default: none)
A list of PEM trust-anchor files that overrides CAfile and CAp-
ath trust chain verification. Specify the option multiple times
to specify multiple files. See the <a href="postconf.5.html">main.cf</a> documentation for
<a href="postconf.5.html#smtp_tls_trust_anchor_file">smtp_tls_trust_anchor_file</a> for details.
<b>-c</b> Disable SMTP chat logging; only TLS-related information is
logged.
<b>-C</b> Print the remote SMTP server certificate trust chain in PEM for-
mat. The issuer DN, subject DN, certificate and public key fin-
gerprints (see <b>-d</b> <i>mdalg</i> option below) are printed above each PEM
certificate block. If you specify <b>-F</b> <i>CAfile</i> or <b>-P</b> <i>CApath</i>, the
OpenSSL library may augment the chain with missing issuer cer-
tificates. To see the actual chain sent by the remote SMTP
server leave <i>CAfile</i> and <i>CApath</i> unset.
<b>-d</b> <i>mdalg</i> (default: <b>sha1</b>)
The message digest algorithm to use for reporting remote SMTP
server fingerprints and matching against user provided certifi-
cate fingerprints (with DANE TLSA records the algorithm is spec-
ified in the DNS).
<b>-f</b> Lookup the associated DANE TLSA RRset even when a hostname is
not an alias and its address records lie in an unsigned zone.
See <a href="postconf.5.html#smtp_tls_force_insecure_host_tlsa_lookup">smtp_tls_force_insecure_host_tlsa_lookup</a> for details.
<b>-F</b> <i>CAfile.pem</i> (default: none)
The PEM formatted CAfile for remote SMTP server certificate ver-
ification. By default no CAfile is used and no public CAs are
trusted.
<b>-g</b> <i>grade</i> (default: medium)
The minimum TLS cipher grade used by posttls-finger. See
<a href="postconf.5.html#smtp_tls_mandatory_ciphers">smtp_tls_mandatory_ciphers</a> for details.
<b>-h</b> <i>host</i><b>_</b><i>lookup</i> (default: <b>dns</b>)
The hostname lookup methods used for the connection. See the
documentation of <a href="postconf.5.html#smtp_host_lookup">smtp_host_lookup</a> for syntax and semantics.
<b>-k</b> <i>certfile</i> (default: <i>keyfile</i>)
File with PEM-encoded TLS client certificate chain. This
defaults to <i>keyfile</i> if one is specified.
<b>-K</b> <i>keyfile</i> (default: <i>certfile</i>)
File with PEM-encoded TLS client private key. This defaults to
<i>certfile</i> if one is specified.
<b>-l</b> <i>level</i> (default: <b>dane</b> or <b>secure</b>)
The security level for the connection, default <b>dane</b> or <b>secure</b>
depending on whether DNSSEC is available. For syntax and seman-
tics, see the documentation of <a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a>. When
<b>dane</b> or <b>dane-only</b> is supported and selected, if no TLSA records
are found, or all the records found are unusable, the <i>secure</i>
level will be used instead. The <b>fingerprint</b> security level
allows you to test certificate or public-key fingerprint matches
before you deploy them in the policy table.
Note, since <b>posttls-finger</b> does not actually deliver any email,
the <b>none</b>, <b>may</b> and <b>encrypt</b> security levels are not very useful.
Since <b>may</b> and <b>encrypt</b> 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).
<b>-L</b> <i>logopts</i> (default: <b>routine,certmatch</b>)
Fine-grained TLS logging options. To tune the TLS features
logged during the TLS handshake, specify one or more of:
<b>0, none</b>
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
<b>1, routine, summary</b>
These synonymous values yield a normal one-line summary
of the TLS connection.
<b>2, debug</b>
These synonymous values combine routine, ssl-debug, cache
and verbose.
<b>3, ssl-expert</b>
These synonymous values combine debug with ssl-hand-
shake-packet-dump. For experts only.
<b>4, ssl-developer</b>
These synonymous values combine ssl-expert with ssl-ses-
sion-packet-dump. For experts only, and in most cases,
use wireshark instead.
<b>ssl-debug</b>
Turn on OpenSSL logging of the progress of the SSL hand-
shake.
<b>ssl-handshake-packet-dump</b>
Log hexadecimal packet dumps of the SSL handshake; for
experts only.
<b>ssl-session-packet-dump</b>
Log hexadecimal packet dumps of the entire SSL session;
only useful to those who can debug SSL protocol problems
from hex dumps.
<b>untrusted</b>
Logs trust chain verification problems. This is turned
on automatically at security levels that use peer names
signed by Certification Authorities to validate certifi-
cates. So while this setting is recognized, you should
never need to set it explicitly.
<b>peercert</b>
This logs a one line summary of the remote SMTP server
certificate subject, issuer, and fingerprints.
<b>certmatch</b>
This logs remote SMTP server certificate matching, show-
ing the CN and each subjectAltName and which name
matched. With DANE, logs matching of TLSA record
trust-anchor and end-entity certificates.
<b>cache</b> This logs session cache operations, showing whether ses-
sion caching is effective with the remote SMTP server.
Automatically used when reconnecting with the <b>-r</b> option;
rarely needs to be set explicitly.
<b>verbose</b>
Enables verbose logging in the Postfix TLS driver;
includes all of peercert..cache and more.
The default is <b>routine,certmatch</b>. After a reconnect, <b>peercert</b>,
<b>certmatch</b> and <b>verbose</b> are automatically disabled while <b>cache</b> and
<b>summary</b> are enabled.
<b>-m</b> <i>count</i> (default: <b>5</b>)
When the <b>-r</b> <i>delay</i> option is specified, the <b>-m</b> 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.
<b>-M</b> <i>insecure</i><b>_</b><i>mx</i><b>_</b><i>policy</i> (default: <b>dane</b>)
The TLS policy for MX hosts with "secure" TLSA records when the
nexthop destination security level is <b>dane</b>, but the MX record
was found via an "insecure" MX lookup. See the <a href="postconf.5.html">main.cf</a> documen-
tation for smtp_tls_insecure_mx_policy for details.
<b>-o</b> <i>name=value</i>
Specify zero or more times to override the value of the <a href="postconf.5.html">main.cf</a>
parameter <i>name</i> with <i>value</i>. Possible use-cases include overrid-
ing the values of TLS library parameters, or "<a href="postconf.5.html#myhostname">myhostname</a>" to
configure the SMTP EHLO name sent to the remote server.
<b>-p</b> <i>protocols</i> (default: !SSLv2)
List of TLS protocols that posttls-finger will exclude or
include. See <a href="postconf.5.html#smtp_tls_mandatory_protocols">smtp_tls_mandatory_protocols</a> for details.
<b>-P</b> <i>CApath/</i> (default: none)
The OpenSSL CApath/ directory (indexed via c_rehash(1)) for
remote SMTP server certificate verification. By default no CAp-
ath is used and no public CAs are trusted.
<b>-r</b> <i>delay</i>
With a cacheable TLS session, disconnect and reconnect after
<i>delay</i> seconds. Report whether the session is re-used. Retry if a
new server is encountered, up to 5 times or as specified with
the <b>-m</b> option. By default reconnection is disabled, specify a
positive delay to enable this behavior.
<b>-S</b> Disable SMTP; that is, connect to an LMTP server. The default
port for LMTP over TCP is 24. Alternative ports can specified
by appending "<i>:servicename</i>" or ":<i>portnumber</i>" to the destination
argument.
<b>-t</b> <i>timeout</i> (default: <b>30</b>)
The TCP connection timeout to use. This is also the timeout for
reading the remote server's 220 banner.
<b>-T</b> <i>timeout</i> (default: <b>30</b>)
The SMTP/LMTP command timeout for EHLO/LHLO, STARTTLS and QUIT.
<b>-v</b> Enable verbose Postfix logging. Specify more than once to
increase the level of verbose logging.
<b>-w</b> 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 <i>domain</i>:<i>port</i> should of course
provide such a service.
[<b>inet:</b>]<i>domain</i>[:<i>port</i>]
Connect via TCP to domain <i>domain</i>, port <i>port</i>. The default port is
<b>smtp</b> (or 24 with LMTP). With SMTP an MX lookup is performed to
resolve the domain to a host, unless the domain is enclosed in
<b>[]</b>. If you want to connect to a specific MX host, for instance
<i>mx1.example.com</i>, specify [<i>mx1.example.com</i>] as the destination
and <i>example.com</i> as a <b>match</b> argument. When using DNS, the desti-
nation domain is assumed fully qualified and no <a href="ADDRESS_CLASS_README.html#default_domain_class">default domain</a>
or search suffixes are applied; you must use fully-qualified
names or also enable <b>native</b> host lookups (these don't support
<b>dane</b> or <b>dane-only</b> as no DNSSEC validation information is avail-
able via <b>native</b> lookups).
<b>unix:</b><i>pathname</i>
Connect to the UNIX-domain socket at <i>pathname</i>. LMTP only.
<b>match ...</b>
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 <b>fin-</b>
<b>gerprint</b> level, or as the list of DNS names to match in the cer-
tificate at the <b>verify</b> and <b>secure</b> levels. If the security level
is <b>dane</b>, or <b>dane-only</b> the match names are ignored, and <b>hostname,</b>
<b>nexthop</b> strategies are used.
<b>ENVIRONMENT</b>
<b>MAIL_CONFIG</b>
Read configuration parameters from a non-default location.
<b>MAIL_VERBOSE</b>
Same as <b>-v</b> option.
<b>SEE ALSO</b>
<a href="smtp-source.1.html">smtp-source(1)</a>, SMTP/LMTP message source
<a href="smtp-sink.1.html">smtp-sink(1)</a>, SMTP/LMTP message dump
<b>README FILES</b>
<a href="TLS_README.html">TLS_README</a>, Postfix STARTTLS howto
<b>LICENSE</b>
The Secure Mailer license must be distributed with this software.
<b>AUTHOR(S)</b>
Wietse Venema
IBM T.J. Watson Research
P.O. Box 704
Yorktown Heights, NY 10598, USA
Viktor Dukhovni
POSTTLS-FINGER(1)
</pre> </body> </html>