Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
POSTTLS-FINGER(1)	    General Commands Manual	     POSTTLS-FINGER(1)

       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	program	has very limited func-
       tionality, and only the -a, -c, -h, -o, -S, -t, -T and -v  options  are

       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 de-
       faults  to  secure.   This  setting determines the certificate matching

       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 de-
       fault) 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 af-
       ter 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-de-
       fault 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.


       -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 documentation for
	      smtp_tls_trust_anchor_file for details.

       -c     Disable SMTP  chat  logging;  only  TLS-related  information  is

       -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

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

       -k certfile (default: keyfile)
	      File with	PEM-encoded TLS	client	certificate  chain.  This  de-
	      faults 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 al-
	      lows 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.

		     Turn on OpenSSL logging of	the progress of	the SSL	 hand-

		     Log  hexadecimal  packet  dumps of	the SSL	handshake; for
		     experts only.

		     Log hexadecimal packet dumps of the entire	 SSL  session;
		     only  useful to those who can debug SSL protocol problems
		     from hex dumps.

		     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.

		     This logs a one line summary of the  remote  SMTP	server
		     certificate subject, issuer, and fingerprints.

		     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.

		     Enables  verbose  logging	in the Postfix TLS driver; in-
		     cludes 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

       -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 documen-
	      tation for smtp_tls_insecure_mx_policy for details.

       -o name=value
	      Specify  zero or more times to override the value	of the
	      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  in-
	      clude.  See smtp_tls_mandatory_protocols for details.

       -P CApath/ (default: none)
	      The  OpenSSL CApath/ directory (indexed via c_rehash(1)) for re-
	      mote 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 de-
	      lay 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

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

	      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,	specify	 []  as the destination
	      and 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).

	      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.

	      Read configuration parameters from a non-default location.

	      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



Want to link to this manual page? Use this URL:

home | help