summaryrefslogtreecommitdiffstats
path: root/html/posttls-finger.1.html
diff options
context:
space:
mode:
Diffstat (limited to 'html/posttls-finger.1.html')
-rw-r--r--html/posttls-finger.1.html361
1 files changed, 361 insertions, 0 deletions
diff --git a/html/posttls-finger.1.html b/html/posttls-finger.1.html
new file mode 100644
index 0000000..4a47a48
--- /dev/null
+++ b/html/posttls-finger.1.html
@@ -0,0 +1,361 @@
+<!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>-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 <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> <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 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>-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 default domain
+ 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
+
+ Wietse Venema
+ Google, Inc.
+ 111 8th Avenue
+ New York, NY 10011, USA
+
+ Viktor Dukhovni
+
+ POSTTLS-FINGER(1)
+</pre> </body> </html>