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(1) 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 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 -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 trusted.
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 found.
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.
Arguments:
  - -a family (default: any)
- Address family preference: ipv4, ipv6 or any. When
      using any, posttls-finger(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.
- -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 logged.
- -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: $smtp_tls_fingerprint_digest)
- 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".
- -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(1). 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(1) 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.
- ssl-debug
- Turn on OpenSSL logging of the progress of the SSL handshake.
- ssl-handshake-packet-dump
- Log hexadecimal packet dumps of the SSL handshake; for experts only.
- ssl-session-packet-dump
- Log hexadecimal packet dumps of the entire SSL session; only useful to
      those who can debug SSL protocol problems from hex dumps.
- untrusted
- 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.
- peercert
- This logs a one line summary of the remote SMTP server certificate
      subject, issuer, and fingerprints.
- certmatch
- 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.
- verbose
- 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 attempt.
- -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_dane_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: >=TLSv1)
- TLS protocols that posttls-finger(1) 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.
- -R
- Use SRV lookup instead of MX.
- -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 argument.
- -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 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
      domain:port must of course provide such a service.
- -X
- Enable tlsproxy(8) mode. This is an unsupported mode, for program
      development only.
- [inet:]domain[:port]
- 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).
- unix:pathname
- 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.
    
 
  - MAIL_CONFIG
- Read configuration parameters from a non-default location.
- MAIL_VERBOSE
- 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