354 lines
16 KiB
Groff
354 lines
16 KiB
Groff
.TH POSTTLS-FINGER 1
|
|
.ad
|
|
.fi
|
|
.SH NAME
|
|
posttls-finger
|
|
\-
|
|
Probe the TLS properties of an ESMTP or LMTP server.
|
|
.SH "SYNOPSIS"
|
|
.na
|
|
.nf
|
|
\fBposttls\-finger\fR [\fIoptions\fR] [\fBinet:\fR]\fIdomain\fR[:\fIport\fR] [\fImatch ...\fR]
|
|
.br
|
|
\fBposttls\-finger\fR \-S [\fIoptions\fR] \fBunix:\fIpathname\fR [\fImatch ...\fR]
|
|
.SH DESCRIPTION
|
|
.ad
|
|
.fi
|
|
\fBposttls\-finger\fR(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 \fBinet:\fR or a pathname prefixed with \fBunix:\fR. If
|
|
Postfix is built without TLS support, the resulting \fBposttls\-finger\fR(1)
|
|
program has very limited functionality, and only the \fB\-a\fR, \fB\-c\fR,
|
|
\fB\-h\fR, \fB\-o\fR, \fB\-S\fR, \fB\-t\fR, \fB\-T\fR and \fB\-v\fR 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 \fBposttls\-finger\fR(1) is compiled, and
|
|
the server supports \fBSTARTTLS\fR, a TLS handshake is attempted.
|
|
|
|
If DNSSEC support is available, the connection TLS security level
|
|
(\fB\-l\fR option) defaults to \fBdane\fR; see TLS_README for
|
|
details. Otherwise, it defaults to \fBsecure\fR. 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 \fB\-L\fR option includes \fBcertmatch\fR,
|
|
(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: \fBposttls\-finger\fR(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 \fBtlsmgr\fR(8) daemon (or any other
|
|
Postfix daemons); its TLS session cache is held in private memory, and
|
|
disappears when the process exits.
|
|
|
|
With the \fB\-r \fIdelay\fR 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 \fBposttls\-finger\fR(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
|
|
\fB\-r\fR, 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 \fB\-m\fR
|
|
option.
|
|
|
|
The choice of SMTP or LMTP (\fB\-S\fR option) determines the syntax of
|
|
the destination argument. With SMTP, one can specify a service on a
|
|
non\-default port as \fIhost\fR:\fIservice\fR, and disable MX (mail
|
|
exchanger) DNS lookups with [\fIhost\fR] or [\fIhost\fR]:\fIport\fR.
|
|
The [] form is required when you specify an IP address instead of a
|
|
hostname. An IPv6 address takes the form [\fBipv6:\fIaddress\fR].
|
|
The default port for SMTP is taken from the \fBsmtp/tcp\fR entry in
|
|
/etc/services, defaulting to 25 if the entry is not found.
|
|
|
|
With LMTP, specify \fBunix:\fIpathname\fR to connect to a local server
|
|
listening on a unix\-domain socket bound to the specified pathname;
|
|
otherwise, specify an optional \fBinet:\fR prefix followed by a
|
|
\fIdomain\fR and an optional port, with the same syntax as for
|
|
SMTP. The default TCP port for LMTP is 24.
|
|
|
|
Arguments:
|
|
.IP "\fB\-a\fR \fIfamily\fR (default: \fBany\fR)"
|
|
Address family preference: \fBipv4\fR, \fBipv6\fR or \fBany\fR. When
|
|
using \fBany\fR, \fBposttls\-finger\fR(1) 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.
|
|
.IP "\fB\-A\fR \fItrust\-anchor.pem\fR (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.
|
|
.IP "\fB\-c\fR"
|
|
Disable SMTP chat logging; only TLS\-related information is logged.
|
|
.IP "\fB\-C\fR"
|
|
Print the remote SMTP server certificate trust chain in PEM format.
|
|
The issuer DN, subject DN, certificate and public key fingerprints
|
|
(see \fB\-d \fImdalg\fR option below) are printed above each PEM
|
|
certificate block. If you specify \fB\-F \fICAfile\fR or
|
|
\fB\-P \fICApath\fR, the OpenSSL library may augment the chain with
|
|
missing issuer certificates. To see the actual chain sent by the
|
|
remote SMTP server leave \fICAfile\fR and \fICApath\fR unset.
|
|
.IP "\fB\-d \fImdalg\fR (default: \fB$smtp_tls_fingerprint_digest\fR)"
|
|
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 "md5".
|
|
.IP "\fB\-f\fR"
|
|
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
|
|
smtp_tls_force_insecure_host_tlsa_lookup for details.
|
|
.IP "\fB\-F \fICAfile.pem\fR (default: none)"
|
|
The PEM formatted CAfile for remote SMTP server certificate
|
|
verification. By default no CAfile is used and no public CAs
|
|
are trusted.
|
|
.IP "\fB\-g \fIgrade\fR (default: medium)"
|
|
The minimum TLS cipher grade used by \fBposttls\-finger\fR(1).
|
|
See smtp_tls_mandatory_ciphers for details.
|
|
.IP "\fB\-h \fIhost_lookup\fR (default: \fBdns\fR)"
|
|
The hostname lookup methods used for the connection. See the
|
|
documentation of smtp_host_lookup for syntax and semantics.
|
|
.IP "\fB\-H \fIchainfiles\fR (default: \fInone\fR)\fR"
|
|
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 \fB\-k\fR and \fB\-K\fR options.
|
|
.IP "\fB\-k \fIcertfile\fR (default: \fIkeyfile\fR)\fR"
|
|
File with PEM\-encoded TLS client certificate chain. This
|
|
defaults to \fIkeyfile\fR if one is specified.
|
|
.IP "\fB\-K \fIkeyfile\fR (default: \fIcertfile\fR)"
|
|
File with PEM\-encoded TLS client private key.
|
|
This defaults to \fIcertfile\fR if one is specified.
|
|
.IP "\fB\-l \fIlevel\fR (default: \fBdane\fR or \fBsecure\fR)"
|
|
The security level for the connection, default \fBdane\fR or
|
|
\fBsecure\fR depending on whether DNSSEC is available. For syntax
|
|
and semantics, see the documentation of smtp_tls_security_level.
|
|
When \fBdane\fR or \fBdane\-only\fR is supported and selected, if no
|
|
TLSA records are found, or all the records found are unusable, the
|
|
\fIsecure\fR level will be used instead. The \fBfingerprint\fR
|
|
security level allows you to test certificate or public\-key
|
|
fingerprint matches before you deploy them in the policy table.
|
|
.IP
|
|
Note, since \fBposttls\-finger\fR(1) does not actually deliver any email,
|
|
the \fBnone\fR, \fBmay\fR and \fBencrypt\fR security levels are not
|
|
very useful. Since \fBmay\fR and \fBencrypt\fR 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).
|
|
.IP "\fB\-L \fIlogopts\fR (default: \fBroutine,certmatch\fR)"
|
|
Fine\-grained TLS logging options. To tune the TLS features logged
|
|
during the TLS handshake, specify one or more of:
|
|
.RS
|
|
.IP "\fB0, none\fR"
|
|
These yield no TLS logging; you'll generally want more, but this
|
|
is handy if you just want the trust chain:
|
|
.RS
|
|
.ad
|
|
.nf
|
|
$ posttls\-finger \-cC \-L none destination
|
|
.fi
|
|
.RE
|
|
.IP "\fB1, routine, summary\fR"
|
|
These synonymous values yield a normal one\-line summary of the TLS
|
|
connection.
|
|
.IP "\fB2, debug\fR"
|
|
These synonymous values combine routine, ssl\-debug, cache and verbose.
|
|
.IP "\fB3, ssl\-expert\fR"
|
|
These synonymous values combine debug with ssl\-handshake\-packet\-dump.
|
|
For experts only.
|
|
.IP "\fB4, ssl\-developer\fR"
|
|
These synonymous values combine ssl\-expert with ssl\-session\-packet\-dump.
|
|
For experts only, and in most cases, use wireshark instead.
|
|
.IP "\fBssl\-debug\fR"
|
|
Turn on OpenSSL logging of the progress of the SSL handshake.
|
|
.IP "\fBssl\-handshake\-packet\-dump\fR"
|
|
Log hexadecimal packet dumps of the SSL handshake; for experts only.
|
|
.IP "\fBssl\-session\-packet\-dump\fR"
|
|
Log hexadecimal packet dumps of the entire SSL session; only useful
|
|
to those who can debug SSL protocol problems from hex dumps.
|
|
.IP "\fBuntrusted\fR"
|
|
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.
|
|
.IP "\fBpeercert\fR"
|
|
This logs a one line summary of the remote SMTP server certificate
|
|
subject, issuer, and fingerprints.
|
|
.IP "\fBcertmatch\fR"
|
|
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.
|
|
.IP "\fBcache\fR"
|
|
This logs session cache operations, showing whether session caching
|
|
is effective with the remote SMTP server. Automatically used when
|
|
reconnecting with the \fB\-r\fR option; rarely needs to be set
|
|
explicitly.
|
|
.IP "\fBverbose\fR"
|
|
Enables verbose logging in the Postfix TLS driver; includes all of
|
|
peercert..cache and more.
|
|
.RE
|
|
.IP
|
|
The default is \fBroutine,certmatch\fR. After a reconnect,
|
|
\fBpeercert\fR, \fBcertmatch\fR and \fBverbose\fR are automatically
|
|
disabled while \fBcache\fR and \fBsummary\fR are enabled.
|
|
.IP "\fB\-m \fIcount\fR (default: \fB5\fR)"
|
|
When the \fB\-r \fIdelay\fR option is specified, the \fB\-m\fR 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.
|
|
.IP "\fB\-M \fIinsecure_mx_policy\fR (default: \fBdane\fR)"
|
|
The TLS policy for MX hosts with "secure" TLSA records when the
|
|
nexthop destination security level is \fBdane\fR, but the MX
|
|
record was found via an "insecure" MX lookup. See the main.cf
|
|
documentation for smtp_tls_dane_insecure_mx_policy for details.
|
|
.IP "\fB\-o \fIname=value\fR"
|
|
Specify zero or more times to override the value of the main.cf
|
|
parameter \fIname\fR with \fIvalue\fR. Possible use\-cases include
|
|
overriding the values of TLS library parameters, or "myhostname" to
|
|
configure the SMTP EHLO name sent to the remote server.
|
|
.IP "\fB\-p \fIprotocols\fR (default: >=TLSv1)"
|
|
TLS protocols that \fBposttls\-finger\fR(1) will exclude or include. See
|
|
smtp_tls_mandatory_protocols for details.
|
|
.IP "\fB\-P \fICApath/\fR (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.
|
|
.IP "\fB\-r \fIdelay\fR"
|
|
With a cacheable TLS session, disconnect and reconnect after \fIdelay\fR
|
|
seconds. Report whether the session is re\-used. Retry if a new server
|
|
is encountered, up to 5 times or as specified with the \fB\-m\fR option.
|
|
By default reconnection is disabled, specify a positive delay to
|
|
enable this behavior.
|
|
.IP "\fB\-R\fR"
|
|
Use SRV lookup instead of MX.
|
|
.IP "\fB\-s \fIservername\fR"
|
|
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.
|
|
.IP "\fB\-S\fR"
|
|
Disable SMTP; that is, connect to an LMTP server. The default port for
|
|
LMTP over TCP is 24. Alternative ports can specified by appending
|
|
"\fI:servicename\fR" or ":\fIportnumber\fR" to the destination
|
|
argument.
|
|
.IP "\fB\-t \fItimeout\fR (default: \fB30\fR)"
|
|
The TCP connection timeout to use. This is also the timeout for
|
|
reading the remote server's 220 banner.
|
|
.IP "\fB\-T \fItimeout\fR (default: \fB30\fR)"
|
|
The SMTP/LMTP command timeout for EHLO/LHLO, STARTTLS and QUIT.
|
|
.IP "\fB\-v\fR"
|
|
Enable verbose Postfix logging. Specify more than once to increase
|
|
the level of verbose logging.
|
|
.IP "\fB\-w\fR"
|
|
Enable outgoing TLS wrapper mode, or SUBMISSIONS/SMTPS support. This
|
|
is typically provided on port 465 by servers that are compatible with
|
|
the SMTP\-in\-SSL protocol, rather than the STARTTLS protocol.
|
|
The destination \fIdomain\fR:\fIport\fR must of course provide such
|
|
a service.
|
|
.IP "\fB\-x\fR"
|
|
Prefer RFC7250 non\-X.509 raw public key (RPK) server credentials. By
|
|
default only X.509 certificates are accepted. This is analogous to
|
|
setting \fBsmtp_tls_enable_rpk = yes\fR in the smtp(8) 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 \fImatch\fR 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.
|
|
.IP "\fB\-X\fR"
|
|
Enable \fBtlsproxy\fR(8) mode. This is an unsupported mode,
|
|
for program development only.
|
|
.IP "[\fBinet:\fR]\fIdomain\fR[:\fIport\fR]"
|
|
Connect via TCP to domain \fIdomain\fR, port \fIport\fR. The default
|
|
port is \fBsmtp\fR (or 24 with LMTP). With SMTP an MX lookup is
|
|
performed to resolve the domain to a host, unless the domain is
|
|
enclosed in \fB[]\fR. If you want to connect to a specific MX host,
|
|
for instance \fImx1.example.com\fR, specify [\fImx1.example.com\fR]
|
|
as the destination and \fIexample.com\fR as a \fBmatch\fR 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 \fBnative\fR host lookups
|
|
(these don't support \fBdane\fR or \fBdane\-only\fR as no DNSSEC
|
|
validation information is available via \fBnative\fR lookups).
|
|
.IP "\fBunix:\fIpathname\fR"
|
|
Connect to the UNIX\-domain socket at \fIpathname\fR. LMTP only.
|
|
.IP "\fBmatch ...\fR"
|
|
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 \fBfingerprint\fR
|
|
level, or as the list of DNS names to match in the certificate at the
|
|
\fBverify\fR and \fBsecure\fR levels. If the security level is
|
|
\fBdane\fR, or \fBdane\-only\fR the match names are ignored, and
|
|
\fBhostname, nexthop\fR strategies are used.
|
|
.ad
|
|
.fi
|
|
.SH "ENVIRONMENT"
|
|
.na
|
|
.nf
|
|
.ad
|
|
.fi
|
|
.IP \fBMAIL_CONFIG\fR
|
|
Read configuration parameters from a non\-default location.
|
|
.IP \fBMAIL_VERBOSE\fR
|
|
Same as \fB\-v\fR option.
|
|
.SH "SEE ALSO"
|
|
.na
|
|
.nf
|
|
smtp\-source(1), SMTP/LMTP message source
|
|
smtp\-sink(1), SMTP/LMTP message dump
|
|
|
|
.SH "README FILES"
|
|
.na
|
|
.nf
|
|
.ad
|
|
.fi
|
|
Use "\fBpostconf readme_directory\fR" or "\fBpostconf
|
|
html_directory\fR" to locate this information.
|
|
.na
|
|
.nf
|
|
TLS_README, Postfix STARTTLS howto
|
|
.SH "LICENSE"
|
|
.na
|
|
.nf
|
|
.ad
|
|
.fi
|
|
The Secure Mailer license must be distributed with this software.
|
|
.SH "AUTHOR(S)"
|
|
.na
|
|
.nf
|
|
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
|