From a848231ae0f346dc7cc000973fbeb65b0894ee92 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Wed, 10 Apr 2024 21:59:03 +0200 Subject: Adding upstream version 3.8.5. Signed-off-by: Daniel Baumann --- html/posttls-finger.1.html | 365 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 365 insertions(+) create mode 100644 html/posttls-finger.1.html (limited to 'html/posttls-finger.1.html') diff --git a/html/posttls-finger.1.html b/html/posttls-finger.1.html new file mode 100644 index 0000000..2ed629a --- /dev/null +++ b/html/posttls-finger.1.html @@ -0,0 +1,365 @@ + + + + + Postfix manual - posttls-finger(1) + 
+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(1) 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(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 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: $smtp_tls_fingerprint_digest)
+              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).   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 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(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 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(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-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_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 overrid-
+              ing 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 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.
+
+       -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 com-
+              patible 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  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)
+
-- cgit v1.2.3