xenial (1) posttls-finger.1.gz

Provided by: postfix_3.1.0-3ubuntu0.4_amd64 bug

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 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 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: 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.

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

              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_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     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.

       [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.

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)