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