375 lines
22 KiB
HTML
375 lines
22 KiB
HTML
<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
|
|
"https://www.w3.org/TR/html4/loose.dtd">
|
|
<html> <head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<link rel='stylesheet' type='text/css' href='postfix-doc.css'>
|
|
<title> Postfix manual - posttls-finger(1) </title>
|
|
</head> <body> <pre>
|
|
POSTTLS-FINGER(1) POSTTLS-FINGER(1)
|
|
|
|
<b><a name="name">NAME</a></b>
|
|
posttls-finger - Probe the TLS properties of an ESMTP or LMTP server.
|
|
|
|
<b><a name="synopsis">SYNOPSIS</a></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><a name="description">DESCRIPTION</a></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 <a href="posttls-finger.1.html"><b>posttls-finger</b>(1)</a> 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>,
|
|
<a href="posttls-finger.1.html"><b>posttls-finger</b>(1)</a> 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>$<a href="postconf.5.html#smtp_tls_fingerprint_digest">smtp_tls_fingerprint_digest</a></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). In Postfix versions prior to 3.6, the
|
|
default value was "md5".
|
|
|
|
<b>-f</b> Look up 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 <a href="posttls-finger.1.html"><b>posttls-finger</b>(1)</a>. 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>-H</b> <i>chainfiles</i> (default: <i>none</i>)
|
|
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 white-
|
|
space 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 <b>-k</b> and <b>-K</b>
|
|
options.
|
|
|
|
<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 <a href="posttls-finger.1.html"><b>posttls-finger</b>(1)</a> 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 <a href="postconf.5.html#smtp_tls_dane_insecure_mx_policy">smtp_tls_dane_insecure_mx_policy</a> 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: >=TLSv1)
|
|
TLS protocols that <a href="posttls-finger.1.html"><b>posttls-finger</b>(1)</a> 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>-R</b> Use SRV lookup instead of MX.
|
|
|
|
<b>-s</b> <i>servername</i>
|
|
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.
|
|
|
|
<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 SUBMISSIONS/SMTPS support.
|
|
This is typically provided on port 465 by servers that are com-
|
|
patible with the SMTP-in-SSL protocol, rather than the STARTTLS
|
|
protocol. The destination <i>domain</i>:<i>port</i> must of course provide
|
|
such a service.
|
|
|
|
<b>-x</b> Prefer <a href="https://tools.ietf.org/html/rfc7250">RFC7250</a> non-X.509 raw public key (RPK) server creden-
|
|
tials. By default only X.509 certificates are accepted. This
|
|
is analogous to setting <b><a href="postconf.5.html#smtp_tls_enable_rpk">smtp_tls_enable_rpk</a> = yes</b> in the <a href="smtp.8.html">smtp(8)</a>
|
|
client. At the fingerprint security level, when raw public keys
|
|
are enabled, only public key (and not certificate) fingerprints
|
|
will be compared against the specified list of <i>match</i> arguments.
|
|
Certificate fingerprints are fragile when raw public keys are
|
|
solicited, the server may at some point in time start returning
|
|
only the public key.
|
|
|
|
<b>-X</b> Enable <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> mode. This is an unsupported mode, for pro-
|
|
gram development only.
|
|
|
|
[<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><a name="environment">ENVIRONMENT</a></b>
|
|
<b>MAIL_CONFIG</b>
|
|
Read configuration parameters from a non-default location.
|
|
|
|
<b>MAIL_VERBOSE</b>
|
|
Same as <b>-v</b> option.
|
|
|
|
<b><a name="see_also">SEE ALSO</a></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><a name="readme_files">README FILES</a></b>
|
|
<a href="TLS_README.html">TLS_README</a>, Postfix STARTTLS howto
|
|
|
|
<b><a name="license">LICENSE</a></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
|
|
|
|
Wietse Venema
|
|
Google, Inc.
|
|
111 8th Avenue
|
|
New York, NY 10011, USA
|
|
|
|
Viktor Dukhovni
|
|
|
|
POSTTLS-FINGER(1)
|
|
</pre> </body> </html>
|