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



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

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

DESCRIPTION
       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 func-
       tionality, 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 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 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 certifi-
       cate 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  dae-
       mons);  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 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  CAp-
              ath 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 for-
              mat.  The issuer DN, subject DN, certificate and public key fin-
              gerprints (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  cer-
              tificates.   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 certifi-
              cate fingerprints (with DANE TLSA records the algorithm is spec-
              ified 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 ver-
              ification.  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.

       -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 seman-
              tics,  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-ses-
                     sion-packet-dump.  For experts only, and in  most  cases,
                     use wireshark instead.

              ssl-debug
                     Turn  on OpenSSL logging of the progress of the SSL hand-
                     shake.

              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  certificate  authorities to validate certifi-
                     cates.  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,  show-
                     ing  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 ses-
                     sion 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-balacer,  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.

       -o name=value
              Specify  zero or more times to override the value of the main.cf
              parameter name with value.  Possible use-cases include  overrid-
              ing  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 CAp-
              ath is used and no public CAs are trusted.

       -r delay
              With  a  cachable  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     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  verose  Postfix  logging.   Specify  more  than  once to
              increase the level of verbose logging.

       [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 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 native host lookups  (these  don't  support
              dane  or dane-only as no DNSSEC validation information is avail-
              able 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 fin-
              gerprint level, or as the list of DNS names to match in the cer-
              tificate 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.

ENVIRONMENT
       MAIL_CONFIG
              Read configuration parameters from a non-default location.

       MAIL_VERBOSE
              Same as -v option.

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


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

LICENSE
       The Secure Mailer license must be distributed with this software.

AUTHOR(S)
       Wietse Venema
       IBM T.J. Watson Research
       P.O. Box 704
       Yorktown Heights, NY 10598, USA

       Viktor Dukhovni



                                                             POSTTLS-FINGER(1)
