diff options
Diffstat (limited to 'html/posttls-finger.1.html')
| -rw-r--r-- | html/posttls-finger.1.html | 361 |
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> |