Updated: 2021/Apr/14

POSTTLS-FINGER(1)           General Commands Manual          POSTTLS-FINGER(1)

       posttls-finger - Probe the TLS properties of an ESMTP or LMTP server.

       posttls-finger [options] [inet:]domain[:port] [match ...]
       posttls-finger -S [options] unix:pathname [match ...]

       posttls-finger(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 inet:
       or a pathname prefixed with unix:.  If Postfix is built without TLS
       support, the resulting posttls-finger program has very limited
       functionality, and only the -a, -c, -h, -o, -S, -t, -T and -v 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 posttls-finger(1) is compiled, and the
       server supports STARTTLS, a TLS handshake is attempted.

       If DNSSEC support is available, the connection TLS security level (-l
       option) defaults to dane; see TLS_README for details. Otherwise, it
       defaults to secure.  This setting determines the certificate matching

       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 -L option includes certmatch, (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

       Note: posttls-finger(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 tlsmgr(8) daemon (or any other Postfix
       daemons); its TLS session cache is held in private memory, and
       disappears when the process exits.

       With the -r delay 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 posttls-finger(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 -r, 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 -m option.

       The choice of SMTP or LMTP (-S option) determines the syntax of the
       destination argument. With SMTP, one can specify a service on a
       non-default port as host:service, and disable MX (mail exchanger) DNS
       lookups with [host] or [host]:port.  The [] form is required when you
       specify an IP address instead of a hostname.  An IPv6 address takes the
       form [ipv6:address].  The default port for SMTP is taken from the
       smtp/tcp entry in /etc/services, defaulting to 25 if the entry is not

       With LMTP, specify unix:pathname to connect to a local server listening
       on a unix-domain socket bound to the specified pathname; otherwise,
       specify an optional inet: prefix followed by a domain and an optional
       port, with the same syntax as for SMTP. The default TCP port for LMTP
       is 24.


       -a family (default: any)
              Address family preference: ipv4, ipv6 or any.  When using any,
              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.

       -A trust-anchor.pem (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.

       -c     Disable SMTP chat logging; only TLS-related information is

       -C     Print the remote SMTP server certificate trust chain in PEM
              format.  The issuer DN, subject DN, certificate and public key
              fingerprints (see -d mdalg option below) are printed above each
              PEM certificate block.  If you specify -F CAfile or -P CApath,
              the OpenSSL library may augment the chain with missing issuer
              certificates.  To see the actual chain sent by the remote SMTP
              server leave CAfile and CApath unset.

       -d mdalg (default: sha1)
              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).

       -f     Lookup 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.

       -F CAfile.pem (default: none)
              The PEM formatted CAfile for remote SMTP server certificate
              verification.  By default no CAfile is used and no public CAs
              are trusted.

       -g grade (default: medium)
              The minimum TLS cipher grade used by posttls-finger.  See
              smtp_tls_mandatory_ciphers for details.

       -h host_lookup (default: dns)
              The hostname lookup methods used for the connection.  See the
              documentation of smtp_host_lookup for syntax and semantics.

       -H chainfiles (default: none)
              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 -k and -K options.

       -k certfile (default: keyfile)
              File with PEM-encoded TLS client certificate chain. This
              defaults to keyfile if one is specified.

       -K keyfile (default: certfile)
              File with PEM-encoded TLS client private key.  This defaults to
              certfile if one is specified.

       -l level (default: dane or secure)
              The security level for the connection, default dane or secure
              depending on whether DNSSEC is available.  For syntax and
              semantics, see the documentation of smtp_tls_security_level.
              When dane or dane-only is supported and selected, if no TLSA
              records are found, or all the records found are unusable, the
              secure level will be used instead.  The fingerprint security
              level allows you to test certificate or public-key fingerprint
              matches before you deploy them in the policy table.

              Note, since posttls-finger does not actually deliver any email,
              the none, may and encrypt security levels are not very useful.
              Since may and encrypt 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).

       -L logopts (default: routine,certmatch)
              Fine-grained TLS logging options. To tune the TLS features
              logged during the TLS handshake, specify one or more of:

              0, none
                     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

              1, routine, summary
                     These synonymous values yield a normal one-line summary
                     of the TLS connection.

              2, debug
                     These synonymous values combine routine, ssl-debug, cache
                     and verbose.

              3, ssl-expert
                     These synonymous values combine debug with
                     ssl-handshake-packet-dump.  For experts only.

              4, ssl-developer
                     These synonymous values combine ssl-expert with
                     ssl-session-packet-dump.  For experts only, and in most
                     cases, use wireshark instead.

                     Turn on OpenSSL logging of the progress of the SSL

                     Log hexadecimal packet dumps of the SSL handshake; for
                     experts only.

                     Log hexadecimal packet dumps of the entire SSL session;
                     only useful to those who can debug SSL protocol problems
                     from hex dumps.

                     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.

                     This logs a one line summary of the remote SMTP server
                     certificate subject, issuer, and fingerprints.

                     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.

              cache  This logs session cache operations, showing whether
                     session caching is effective with the remote SMTP server.
                     Automatically used when reconnecting with the -r option;
                     rarely needs to be set explicitly.

                     Enables verbose logging in the Postfix TLS driver;
                     includes all of peercert..cache and more.

              The default is routine,certmatch. After a reconnect, peercert,
              certmatch and verbose are automatically disabled while cache and
              summary are enabled.

       -m count (default: 5)
              When the -r delay option is specified, the -m 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

       -M insecure_mx_policy (default: dane)
              The TLS policy for MX hosts with "secure" TLSA records when the
              nexthop destination security level is dane, but the MX record
              was found via an "insecure" MX lookup.  See the main.cf
              documentation for smtp_tls_insecure_mx_policy for details.

       -o name=value
              Specify zero or more times to override the value of the main.cf
              parameter name with value.  Possible use-cases include
              overriding the values of TLS library parameters, or "myhostname"
              to configure the SMTP EHLO name sent to the remote server.

       -p protocols (default: !SSLv2)
              List of TLS protocols that posttls-finger will exclude or
              include.  See smtp_tls_mandatory_protocols for details.

       -P CApath/ (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.

       -r delay
              With a cacheable TLS session, disconnect and reconnect after
              delay seconds. Report whether the session is re-used. Retry if a
              new server is encountered, up to 5 times or as specified with
              the -m option.  By default reconnection is disabled, specify a
              positive delay to enable this behavior.

       -s servername
              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.

       -S     Disable SMTP; that is, connect to an LMTP server. The default
              port for LMTP over TCP is 24.  Alternative ports can specified
              by appending ":servicename" or ":portnumber" to the destination

       -t timeout (default: 30)
              The TCP connection timeout to use.  This is also the timeout for
              reading the remote server's 220 banner.

       -T timeout (default: 30)
              The SMTP/LMTP command timeout for EHLO/LHLO, STARTTLS and QUIT.

       -v     Enable verbose Postfix logging.  Specify more than once to
              increase the level of verbose logging.

       -w     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 domain:port should of course
              provide such a service.

       -X     Enable tlsproxy(8) mode. This is an unsupported mode, for
              program development only.

              Connect via TCP to domain domain, port port. The default port is
              smtp (or 24 with LMTP).  With SMTP an MX lookup is performed to
              resolve the domain to a host, unless the domain is enclosed in
              [].  If you want to connect to a specific MX host, for instance
              mx1.example.com, specify [mx1.example.com] as the destination
              and example.com as a match 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 native host lookups (these
              don't support dane or dane-only as no DNSSEC validation
              information is available via native lookups).

              Connect to the UNIX-domain socket at pathname. LMTP only.

       match ...
              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
              fingerprint level, or as the list of DNS names to match in the
              certificate at the verify and secure levels.  If the security
              level is dane, or dane-only the match names are ignored, and
              hostname, nexthop strategies are used.


              Read configuration parameters from a non-default location.

              Same as -v option.

       smtp-source(1), SMTP/LMTP message source
       smtp-sink(1), SMTP/LMTP message dump

       Use "postconf readme_directory" or "postconf html_directory" to locate
       this information.
       TLS_README, Postfix STARTTLS howto

       The Secure Mailer license must be distributed with this software.

       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