diff options
Diffstat (limited to 'man/man1/posttls-finger.1')
| -rw-r--r-- | man/man1/posttls-finger.1 | 343 |
1 files changed, 343 insertions, 0 deletions
diff --git a/man/man1/posttls-finger.1 b/man/man1/posttls-finger.1 new file mode 100644 index 0000000..54b72ab --- /dev/null +++ b/man/man1/posttls-finger.1 @@ -0,0 +1,343 @@ +.TH POSTTLS-FINGER 1 +.ad +.fi +.SH NAME +posttls-finger +\- +Probe the TLS properties of an ESMTP or LMTP server. +.SH "SYNOPSIS" +.na +.nf +\fBposttls\-finger\fR [\fIoptions\fR] [\fBinet:\fR]\fIdomain\fR[:\fIport\fR] [\fImatch ...\fR] +.br +\fBposttls\-finger\fR \-S [\fIoptions\fR] \fBunix:\fIpathname\fR [\fImatch ...\fR] +.SH DESCRIPTION +.ad +.fi +\fBposttls\-finger\fR(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 \fBinet:\fR or a pathname prefixed with \fBunix:\fR. If +Postfix is built without TLS support, the resulting \fBposttls\-finger\fR(1) +program has very limited functionality, and only the \fB\-a\fR, \fB\-c\fR, +\fB\-h\fR, \fB\-o\fR, \fB\-S\fR, \fB\-t\fR, \fB\-T\fR and \fB\-v\fR 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 \fBposttls\-finger\fR(1) is compiled, and +the server supports \fBSTARTTLS\fR, a TLS handshake is attempted. + +If DNSSEC support is available, the connection TLS security level +(\fB\-l\fR option) defaults to \fBdane\fR; see TLS_README for +details. Otherwise, it defaults to \fBsecure\fR. 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 \fB\-L\fR option includes \fBcertmatch\fR, +(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: \fBposttls\-finger\fR(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 \fBtlsmgr\fR(8) daemon (or any other +Postfix daemons); its TLS session cache is held in private memory, and +disappears when the process exits. + +With the \fB\-r \fIdelay\fR 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 \fBposttls\-finger\fR(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 +\fB\-r\fR, 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 \fB\-m\fR +option. + +The choice of SMTP or LMTP (\fB\-S\fR option) determines the syntax of +the destination argument. With SMTP, one can specify a service on a +non\-default port as \fIhost\fR:\fIservice\fR, and disable MX (mail +exchanger) DNS lookups with [\fIhost\fR] or [\fIhost\fR]:\fIport\fR. +The [] form is required when you specify an IP address instead of a +hostname. An IPv6 address takes the form [\fBipv6:\fIaddress\fR]. +The default port for SMTP is taken from the \fBsmtp/tcp\fR entry in +/etc/services, defaulting to 25 if the entry is not found. + +With LMTP, specify \fBunix:\fIpathname\fR to connect to a local server +listening on a unix\-domain socket bound to the specified pathname; +otherwise, specify an optional \fBinet:\fR prefix followed by a +\fIdomain\fR and an optional port, with the same syntax as for +SMTP. The default TCP port for LMTP is 24. + +Arguments: +.IP "\fB\-a\fR \fIfamily\fR (default: \fBany\fR)" +Address family preference: \fBipv4\fR, \fBipv6\fR or \fBany\fR. When +using \fBany\fR, \fBposttls\-finger\fR(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. +.IP "\fB\-A\fR \fItrust\-anchor.pem\fR (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. +.IP "\fB\-c\fR" +Disable SMTP chat logging; only TLS\-related information is logged. +.IP "\fB\-C\fR" +Print the remote SMTP server certificate trust chain in PEM format. +The issuer DN, subject DN, certificate and public key fingerprints +(see \fB\-d \fImdalg\fR option below) are printed above each PEM +certificate block. If you specify \fB\-F \fICAfile\fR or +\fB\-P \fICApath\fR, the OpenSSL library may augment the chain with +missing issuer certificates. To see the actual chain sent by the +remote SMTP server leave \fICAfile\fR and \fICApath\fR unset. +.IP "\fB\-d \fImdalg\fR (default: \fB$smtp_tls_fingerprint_digest\fR)" +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). In Postfix versions prior to 3.6, the default value +was "md5". +.IP "\fB\-f\fR" +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. +.IP "\fB\-F \fICAfile.pem\fR (default: none)" +The PEM formatted CAfile for remote SMTP server certificate +verification. By default no CAfile is used and no public CAs +are trusted. +.IP "\fB\-g \fIgrade\fR (default: medium)" +The minimum TLS cipher grade used by \fBposttls\-finger\fR(1). +See smtp_tls_mandatory_ciphers for details. +.IP "\fB\-h \fIhost_lookup\fR (default: \fBdns\fR)" +The hostname lookup methods used for the connection. See the +documentation of smtp_host_lookup for syntax and semantics. +.IP "\fB\-H \fIchainfiles\fR (default: \fInone\fR)\fR" +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 +whitespace 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 \fB\-k\fR and \fB\-K\fR options. +.IP "\fB\-k \fIcertfile\fR (default: \fIkeyfile\fR)\fR" +File with PEM\-encoded TLS client certificate chain. This +defaults to \fIkeyfile\fR if one is specified. +.IP "\fB\-K \fIkeyfile\fR (default: \fIcertfile\fR)" +File with PEM\-encoded TLS client private key. +This defaults to \fIcertfile\fR if one is specified. +.IP "\fB\-l \fIlevel\fR (default: \fBdane\fR or \fBsecure\fR)" +The security level for the connection, default \fBdane\fR or +\fBsecure\fR depending on whether DNSSEC is available. For syntax +and semantics, see the documentation of smtp_tls_security_level. +When \fBdane\fR or \fBdane\-only\fR is supported and selected, if no +TLSA records are found, or all the records found are unusable, the +\fIsecure\fR level will be used instead. The \fBfingerprint\fR +security level allows you to test certificate or public\-key +fingerprint matches before you deploy them in the policy table. +.IP +Note, since \fBposttls\-finger\fR(1) does not actually deliver any email, +the \fBnone\fR, \fBmay\fR and \fBencrypt\fR security levels are not +very useful. Since \fBmay\fR and \fBencrypt\fR 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). +.IP "\fB\-L \fIlogopts\fR (default: \fBroutine,certmatch\fR)" +Fine\-grained TLS logging options. To tune the TLS features logged +during the TLS handshake, specify one or more of: +.RS +.IP "\fB0, none\fR" +These yield no TLS logging; you'll generally want more, but this +is handy if you just want the trust chain: +.RS +.ad +.nf +$ posttls\-finger \-cC \-L none destination +.fi +.RE +.IP "\fB1, routine, summary\fR" +These synonymous values yield a normal one\-line summary of the TLS +connection. +.IP "\fB2, debug\fR" +These synonymous values combine routine, ssl\-debug, cache and verbose. +.IP "\fB3, ssl\-expert\fR" +These synonymous values combine debug with ssl\-handshake\-packet\-dump. +For experts only. +.IP "\fB4, ssl\-developer\fR" +These synonymous values combine ssl\-expert with ssl\-session\-packet\-dump. +For experts only, and in most cases, use wireshark instead. +.IP "\fBssl\-debug\fR" +Turn on OpenSSL logging of the progress of the SSL handshake. +.IP "\fBssl\-handshake\-packet\-dump\fR" +Log hexadecimal packet dumps of the SSL handshake; for experts only. +.IP "\fBssl\-session\-packet\-dump\fR" +Log hexadecimal packet dumps of the entire SSL session; only useful +to those who can debug SSL protocol problems from hex dumps. +.IP "\fBuntrusted\fR" +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. +.IP "\fBpeercert\fR" +This logs a one line summary of the remote SMTP server certificate +subject, issuer, and fingerprints. +.IP "\fBcertmatch\fR" +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. +.IP "\fBcache\fR" +This logs session cache operations, showing whether session caching +is effective with the remote SMTP server. Automatically used when +reconnecting with the \fB\-r\fR option; rarely needs to be set +explicitly. +.IP "\fBverbose\fR" +Enables verbose logging in the Postfix TLS driver; includes all of +peercert..cache and more. +.RE +.IP +The default is \fBroutine,certmatch\fR. After a reconnect, +\fBpeercert\fR, \fBcertmatch\fR and \fBverbose\fR are automatically +disabled while \fBcache\fR and \fBsummary\fR are enabled. +.IP "\fB\-m \fIcount\fR (default: \fB5\fR)" +When the \fB\-r \fIdelay\fR option is specified, the \fB\-m\fR 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. +.IP "\fB\-M \fIinsecure_mx_policy\fR (default: \fBdane\fR)" +The TLS policy for MX hosts with "secure" TLSA records when the +nexthop destination security level is \fBdane\fR, but the MX +record was found via an "insecure" MX lookup. See the main.cf +documentation for smtp_tls_dane_insecure_mx_policy for details. +.IP "\fB\-o \fIname=value\fR" +Specify zero or more times to override the value of the main.cf +parameter \fIname\fR with \fIvalue\fR. Possible use\-cases include +overriding the values of TLS library parameters, or "myhostname" to +configure the SMTP EHLO name sent to the remote server. +.IP "\fB\-p \fIprotocols\fR (default: >=TLSv1)" +TLS protocols that \fBposttls\-finger\fR(1) will exclude or include. See +smtp_tls_mandatory_protocols for details. +.IP "\fB\-P \fICApath/\fR (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. +.IP "\fB\-r \fIdelay\fR" +With a cacheable TLS session, disconnect and reconnect after \fIdelay\fR +seconds. Report whether the session is re\-used. Retry if a new server +is encountered, up to 5 times or as specified with the \fB\-m\fR option. +By default reconnection is disabled, specify a positive delay to +enable this behavior. +.IP "\fB\-s \fIservername\fR" +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. +.IP "\fB\-S\fR" +Disable SMTP; that is, connect to an LMTP server. The default port for +LMTP over TCP is 24. Alternative ports can specified by appending +"\fI:servicename\fR" or ":\fIportnumber\fR" to the destination +argument. +.IP "\fB\-t \fItimeout\fR (default: \fB30\fR)" +The TCP connection timeout to use. This is also the timeout for +reading the remote server's 220 banner. +.IP "\fB\-T \fItimeout\fR (default: \fB30\fR)" +The SMTP/LMTP command timeout for EHLO/LHLO, STARTTLS and QUIT. +.IP "\fB\-v\fR" +Enable verbose Postfix logging. Specify more than once to increase +the level of verbose logging. +.IP "\fB\-w\fR" +Enable outgoing TLS wrapper mode, or SUBMISSIONS/SMTPS support. This +is typically provided on port 465 by servers that are compatible with +the SMTP\-in\-SSL protocol, rather than the STARTTLS protocol. +The destination \fIdomain\fR:\fIport\fR must of course provide such +a service. +.IP "\fB\-X\fR" +Enable \fBtlsproxy\fR(8) mode. This is an unsupported mode, +for program development only. +.IP "[\fBinet:\fR]\fIdomain\fR[:\fIport\fR]" +Connect via TCP to domain \fIdomain\fR, port \fIport\fR. The default +port is \fBsmtp\fR (or 24 with LMTP). With SMTP an MX lookup is +performed to resolve the domain to a host, unless the domain is +enclosed in \fB[]\fR. If you want to connect to a specific MX host, +for instance \fImx1.example.com\fR, specify [\fImx1.example.com\fR] +as the destination and \fIexample.com\fR as a \fBmatch\fR 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 \fBnative\fR host lookups +(these don't support \fBdane\fR or \fBdane\-only\fR as no DNSSEC +validation information is available via \fBnative\fR lookups). +.IP "\fBunix:\fIpathname\fR" +Connect to the UNIX\-domain socket at \fIpathname\fR. LMTP only. +.IP "\fBmatch ...\fR" +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 \fBfingerprint\fR +level, or as the list of DNS names to match in the certificate at the +\fBverify\fR and \fBsecure\fR levels. If the security level is +\fBdane\fR, or \fBdane\-only\fR the match names are ignored, and +\fBhostname, nexthop\fR strategies are used. +.ad +.fi +.SH "ENVIRONMENT" +.na +.nf +.ad +.fi +.IP \fBMAIL_CONFIG\fR +Read configuration parameters from a non\-default location. +.IP \fBMAIL_VERBOSE\fR +Same as \fB\-v\fR option. +.SH "SEE ALSO" +.na +.nf +smtp\-source(1), SMTP/LMTP message source +smtp\-sink(1), SMTP/LMTP message dump + +.SH "README FILES" +.na +.nf +.ad +.fi +Use "\fBpostconf readme_directory\fR" or "\fBpostconf +html_directory\fR" to locate this information. +.na +.nf +TLS_README, Postfix STARTTLS howto +.SH "LICENSE" +.na +.nf +.ad +.fi +The Secure Mailer license must be distributed with this software. +.SH "AUTHOR(S)" +.na +.nf +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 |