1<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" 2 "http://www.w3.org/TR/html4/loose.dtd"> 3<html> <head> 4<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> 5<title> Postfix manual - posttls-finger(1) </title> 6</head> <body> <pre> 7POSTTLS-FINGER(1) POSTTLS-FINGER(1) 8 9<b>NAME</b> 10 posttls-finger - Probe the TLS properties of an ESMTP or LMTP server. 11 12<b>SYNOPSIS</b> 13 <b>posttls-finger</b> [<i>options</i>] [<b>inet:</b>]<i>domain</i>[:<i>port</i>] [<i>match ...</i>] 14 <b>posttls-finger</b> -S [<i>options</i>] <b>unix:</b><i>pathname</i> [<i>match ...</i>] 15 16<b>DESCRIPTION</b> 17 <a href="posttls-finger.1.html"><b>posttls-finger</b>(1)</a> connects to the specified destination and reports 18 TLS-related information about the server. With SMTP, the destination is 19 a domainname; with LMTP it is either a domainname prefixed with <b>inet:</b> 20 or a pathname prefixed with <b>unix:</b>. If Postfix is built without TLS 21 support, the resulting posttls-finger program has very limited func- 22 tionality, and only the <b>-a</b>, <b>-c</b>, <b>-h</b>, <b>-o</b>, <b>-S</b>, <b>-t</b>, <b>-T</b> and <b>-v</b> options are 23 available. 24 25 Note: this is an unsupported test program. No attempt is made to main- 26 tain compatibility between successive versions. 27 28 For SMTP servers that don't support ESMTP, only the greeting banner and 29 the negative EHLO response are reported. Otherwise, the reported EHLO 30 response details further server capabilities. 31 32 If TLS support is enabled when <a href="posttls-finger.1.html"><b>posttls-finger</b>(1)</a> is compiled, and the 33 server supports <b>STARTTLS</b>, a TLS handshake is attempted. 34 35 If DNSSEC support is available, the connection TLS security level (<b>-l</b> 36 option) defaults to <b>dane</b>; see <a href="TLS_README.html">TLS_README</a> for details. Otherwise, it 37 defaults to <b>secure</b>. This setting determines the certificate matching 38 policy. 39 40 If TLS negotiation succeeds, the TLS protocol and cipher details are 41 reported. The server certificate is then verified in accordance with 42 the policy at the chosen (or default) security level. With public CA- 43 based trust, when the <b>-L</b> option includes <b>certmatch</b>, (true by default) 44 name matching is performed even if the certificate chain is not 45 trusted. This logs the names found in the remote SMTP server certifi- 46 cate and which if any would match, were the certificate chain trusted. 47 48 Note: <a href="posttls-finger.1.html"><b>posttls-finger</b>(1)</a> does not perform any table lookups, so the TLS 49 policy table and obsolete per-site tables are not consulted. It does 50 not communicate with the <a href="tlsmgr.8.html"><b>tlsmgr</b>(8)</a> daemon (or any other Postfix dae- 51 mons); its TLS session cache is held in private memory, and disappears 52 when the process exits. 53 54 With the <b>-r</b> <i>delay</i> option, if the server assigns a TLS session id, the 55 TLS session is cached. The connection is then closed and re-opened 56 after the specified delay, and <a href="posttls-finger.1.html"><b>posttls-finger</b>(1)</a> then reports whether 57 the cached TLS session was re-used. 58 59 When the destination is a load-balancer, it may be distributing load 60 between multiple server caches. Typically, each server returns its 61 unique name in its EHLO response. If, upon reconnecting with <b>-r</b>, a new 62 server name is detected, another session is cached for the new server, 63 and the reconnect is repeated up to a maximum number of times (default 64 5) that can be specified via the <b>-m</b> option. 65 66 The choice of SMTP or LMTP (<b>-S</b> option) determines the syntax of the 67 destination argument. With SMTP, one can specify a service on a non- 68 default port as <i>host</i>:<i>service</i>, and disable MX (mail exchanger) DNS 69 lookups with [<i>host</i>] or [<i>host</i>]:<i>port</i>. The [] form is required when you 70 specify an IP address instead of a hostname. An IPv6 address takes the 71 form [<b>ipv6:</b><i>address</i>]. The default port for SMTP is taken from the 72 <b>smtp/tcp</b> entry in /etc/services, defaulting to 25 if the entry is not 73 found. 74 75 With LMTP, specify <b>unix:</b><i>pathname</i> to connect to a local server listening 76 on a unix-domain socket bound to the specified pathname; otherwise, 77 specify an optional <b>inet:</b> prefix followed by a <i>domain</i> and an optional 78 port, with the same syntax as for SMTP. The default TCP port for LMTP 79 is 24. 80 81 Arguments: 82 83 <b>-a</b> <i>family</i> (default: <b>any</b>) 84 Address family preference: <b>ipv4</b>, <b>ipv6</b> or <b>any</b>. When using <b>any</b>, 85 posttls-finger will randomly select one of the two as the more 86 preferred, and exhaust all MX preferences for the first address 87 family before trying any addresses for the other. 88 89 <b>-A</b> <i>trust-anchor.pem</i> (default: none) 90 A list of PEM trust-anchor files that overrides CAfile and CAp- 91 ath trust chain verification. Specify the option multiple times 92 to specify multiple files. See the <a href="postconf.5.html">main.cf</a> documentation for 93 <a href="postconf.5.html#smtp_tls_trust_anchor_file">smtp_tls_trust_anchor_file</a> for details. 94 95 <b>-c</b> Disable SMTP chat logging; only TLS-related information is 96 logged. 97 98 <b>-C</b> Print the remote SMTP server certificate trust chain in PEM for- 99 mat. The issuer DN, subject DN, certificate and public key fin- 100 gerprints (see <b>-d</b> <i>mdalg</i> option below) are printed above each PEM 101 certificate block. If you specify <b>-F</b> <i>CAfile</i> or <b>-P</b> <i>CApath</i>, the 102 OpenSSL library may augment the chain with missing issuer cer- 103 tificates. To see the actual chain sent by the remote SMTP 104 server leave <i>CAfile</i> and <i>CApath</i> unset. 105 106 <b>-d</b> <i>mdalg</i> (default: <b>sha1</b>) 107 The message digest algorithm to use for reporting remote SMTP 108 server fingerprints and matching against user provided certifi- 109 cate fingerprints (with DANE TLSA records the algorithm is spec- 110 ified in the DNS). 111 112 <b>-f</b> Lookup the associated DANE TLSA RRset even when a hostname is 113 not an alias and its address records lie in an unsigned zone. 114 See <a href="postconf.5.html#smtp_tls_force_insecure_host_tlsa_lookup">smtp_tls_force_insecure_host_tlsa_lookup</a> for details. 115 116 <b>-F</b> <i>CAfile.pem</i> (default: none) 117 The PEM formatted CAfile for remote SMTP server certificate ver- 118 ification. By default no CAfile is used and no public CAs are 119 trusted. 120 121 <b>-g</b> <i>grade</i> (default: medium) 122 The minimum TLS cipher grade used by posttls-finger. See 123 <a href="postconf.5.html#smtp_tls_mandatory_ciphers">smtp_tls_mandatory_ciphers</a> for details. 124 125 <b>-h</b> <i>host</i><b>_</b><i>lookup</i> (default: <b>dns</b>) 126 The hostname lookup methods used for the connection. See the 127 documentation of <a href="postconf.5.html#smtp_host_lookup">smtp_host_lookup</a> for syntax and semantics. 128 129 <b>-l</b> <i>level</i> (default: <b>dane</b> or <b>secure</b>) 130 The security level for the connection, default <b>dane</b> or <b>secure</b> 131 depending on whether DNSSEC is available. For syntax and seman- 132 tics, see the documentation of <a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a>. When 133 <b>dane</b> or <b>dane-only</b> is supported and selected, if no TLSA records 134 are found, or all the records found are unusable, the <i>secure</i> 135 level will be used instead. The <b>fingerprint</b> security level 136 allows you to test certificate or public-key fingerprint matches 137 before you deploy them in the policy table. 138 139 Note, since <b>posttls-finger</b> does not actually deliver any email, 140 the <b>none</b>, <b>may</b> and <b>encrypt</b> security levels are not very useful. 141 Since <b>may</b> and <b>encrypt</b> don't require peer certificates, they will 142 often negotiate anonymous TLS ciphersuites, so you won't learn 143 much about the remote SMTP server's certificates at these levels 144 if it also supports anonymous TLS (though you may learn that the 145 server supports anonymous TLS). 146 147 <b>-L</b> <i>logopts</i> (default: <b>routine,certmatch</b>) 148 Fine-grained TLS logging options. To tune the TLS features 149 logged during the TLS handshake, specify one or more of: 150 151 <b>0, none</b> 152 These yield no TLS logging; you'll generally want more, 153 but this is handy if you just want the trust chain: 154 $ posttls-finger -cC -L none destination 155 156 <b>1, routine, summary</b> 157 These synonymous values yield a normal one-line summary 158 of the TLS connection. 159 160 <b>2, debug</b> 161 These synonymous values combine routine, ssl-debug, cache 162 and verbose. 163 164 <b>3, ssl-expert</b> 165 These synonymous values combine debug with ssl-handshake- 166 packet-dump. For experts only. 167 168 <b>4, ssl-developer</b> 169 These synonymous values combine ssl-expert with ssl-ses- 170 sion-packet-dump. For experts only, and in most cases, 171 use wireshark instead. 172 173 <b>ssl-debug</b> 174 Turn on OpenSSL logging of the progress of the SSL hand- 175 shake. 176 177 <b>ssl-handshake-packet-dump</b> 178 Log hexadecimal packet dumps of the SSL handshake; for 179 experts only. 180 181 <b>ssl-session-packet-dump</b> 182 Log hexadecimal packet dumps of the entire SSL session; 183 only useful to those who can debug SSL protocol problems 184 from hex dumps. 185 186 <b>untrusted</b> 187 Logs trust chain verification problems. This is turned 188 on automatically at security levels that use peer names 189 signed by certificate authorities to validate certifi- 190 cates. So while this setting is recognized, you should 191 never need to set it explicitly. 192 193 <b>peercert</b> 194 This logs a one line summary of the remote SMTP server 195 certificate subject, issuer, and fingerprints. 196 197 <b>certmatch</b> 198 This logs remote SMTP server certificate matching, show- 199 ing the CN and each subjectAltName and which name 200 matched. With DANE, logs matching of TLSA record trust- 201 anchor and end-entity certificates. 202 203 <b>cache</b> This logs session cache operations, showing whether ses- 204 sion caching is effective with the remote SMTP server. 205 Automatically used when reconnecting with the <b>-r</b> option; 206 rarely needs to be set explicitly. 207 208 <b>verbose</b> 209 Enables verbose logging in the Postfix TLS driver; 210 includes all of peercert..cache and more. 211 212 The default is <b>routine,certmatch</b>. After a reconnect, <b>peercert</b>, 213 <b>certmatch</b> and <b>verbose</b> are automatically disabled while <b>cache</b> and 214 <b>summary</b> are enabled. 215 216 <b>-m</b> <i>count</i> (default: <b>5</b>) 217 When the <b>-r</b> <i>delay</i> option is specified, the <b>-m</b> option determines 218 the maximum number of reconnect attempts to use with a server 219 behind a load-balacer, to see whether connection caching is 220 likely to be effective for this destination. Some MTAs don't 221 expose the underlying server identity in their EHLO response; 222 with these servers there will never be more than 1 reconnection 223 attempt. 224 225 <b>-o</b> <i>name=value</i> 226 Specify zero or more times to override the value of the <a href="postconf.5.html">main.cf</a> 227 parameter <i>name</i> with <i>value</i>. Possible use-cases include overrid- 228 ing the values of TLS library parameters, or "<a href="postconf.5.html#myhostname">myhostname</a>" to 229 configure the SMTP EHLO name sent to the remote server. 230 231 <b>-p</b> <i>protocols</i> (default: !SSLv2) 232 List of TLS protocols that posttls-finger will exclude or 233 include. See <a href="postconf.5.html#smtp_tls_mandatory_protocols">smtp_tls_mandatory_protocols</a> for details. 234 235 <b>-P</b> <i>CApath/</i> (default: none) 236 The OpenSSL CApath/ directory (indexed via c_rehash(1)) for 237 remote SMTP server certificate verification. By default no CAp- 238 ath is used and no public CAs are trusted. 239 240 <b>-r</b> <i>delay</i> 241 With a cachable TLS session, disconnect and reconnect after 242 <i>delay</i> seconds. Report whether the session is re-used. Retry if a 243 new server is encountered, up to 5 times or as specified with 244 the <b>-m</b> option. By default reconnection is disabled, specify a 245 positive delay to enable this behavior. 246 247 <b>-S</b> Disable SMTP; that is, connect to an LMTP server. The default 248 port for LMTP over TCP is 24. Alternative ports can specified 249 by appending "<i>:servicename</i>" or ":<i>portnumber</i>" to the destination 250 argument. 251 252 <b>-t</b> <i>timeout</i> (default: <b>30</b>) 253 The TCP connection timeout to use. This is also the timeout for 254 reading the remote server's 220 banner. 255 256 <b>-T</b> <i>timeout</i> (default: <b>30</b>) 257 The SMTP/LMTP command timeout for EHLO/LHLO, STARTTLS and QUIT. 258 259 <b>-v</b> Enable verose Postfix logging. Specify more than once to 260 increase the level of verbose logging. 261 262 [<b>inet:</b>]<i>domain</i>[:<i>port</i>] 263 Connect via TCP to domain <i>domain</i>, port <i>port</i>. The default port is 264 <b>smtp</b> (or 24 with LMTP). With SMTP an MX lookup is performed to 265 resolve the domain to a host, unless the domain is enclosed in 266 <b>[]</b>. If you want to connect to a specific MX host, for instance 267 <i>mx1.example.com</i>, specify [<i>mx1.example.com</i>] as the destination 268 and <i>example.com</i> as a <b>match</b> argument. When using DNS, the desti- 269 nation domain is assumed fully qualified and no default domain 270 or search suffixes are applied; you must use fully-qualified 271 names or also enable <b>native</b> host lookups (these don't support 272 <b>dane</b> or <b>dane-only</b> as no DNSSEC validation information is avail- 273 able via <b>native</b> lookups). 274 275 <b>unix:</b><i>pathname</i> 276 Connect to the UNIX-domain socket at <i>pathname</i>. LMTP only. 277 278 <b>match ...</b> 279 With no match arguments specified, certificate peername matching 280 uses the compiled-in default strategies for each security level. 281 If you specify one or more arguments, these will be used as the 282 list of certificate or public-key digests to match for the <b>fin-</b> 283 <b>gerprint</b> level, or as the list of DNS names to match in the cer- 284 tificate at the <b>verify</b> and <b>secure</b> levels. If the security level 285 is <b>dane</b>, or <b>dane-only</b> the match names are ignored, and <b>hostname,</b> 286 <b>nexthop</b> strategies are used. 287 288<b>ENVIRONMENT</b> 289 <b>MAIL_CONFIG</b> 290 Read configuration parameters from a non-default location. 291 292 <b>MAIL_VERBOSE</b> 293 Same as <b>-v</b> option. 294 295<b>SEE ALSO</b> 296 <a href="smtp-source.1.html">smtp-source(1)</a>, SMTP/LMTP message source 297 <a href="smtp-sink.1.html">smtp-sink(1)</a>, SMTP/LMTP message dump 298 299<b>README FILES</b> 300 <a href="TLS_README.html">TLS_README</a>, Postfix STARTTLS howto 301 302<b>LICENSE</b> 303 The Secure Mailer license must be distributed with this software. 304 305<b>AUTHOR(S)</b> 306 Wietse Venema 307 IBM T.J. Watson Research 308 P.O. Box 704 309 Yorktown Heights, NY 10598, USA 310 311 Viktor Dukhovni 312 313 POSTTLS-FINGER(1) 314</pre> </body> </html> 315