    POSTTLS-FINGER(1)                                            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 cer-
           tificate 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.

           -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  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 -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 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-hand-
                         shake-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 Certification 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 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 documen-
                  tation 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  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  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
                  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 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 pro-
                  gram 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 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
           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

           Wietse Venema
           Google, Inc.
           111 8th Avenue
           New York, NY 10011, USA

           Viktor Dukhovni

                                                                 POSTTLS-FINGER(1)