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 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>-H</b> <i>chainfiles</i> (default: <i>none</i>) 131 List of files with a sequence PEM-encoded TLS client certificate 132 chains. The list can be built-up incrementally, by specifying 133 the option multiple times, or all at once via a comma or white- 134 space separated list of filenames. Each chain starts with a 135 private key, which is followed immediately by the corresponding 136 certificate, and optionally by additional issuer certificates. 137 Each new key begins a new chain for the corresponding algorithm. 138 This option is mutually exclusive with the below <b>-k</b> and <b>-K</b> 139 options. 140 141 <b>-k</b> <i>certfile</i> (default: <i>keyfile</i>) 142 File with PEM-encoded TLS client certificate chain. This 143 defaults to <i>keyfile</i> if one is specified. 144 145 <b>-K</b> <i>keyfile</i> (default: <i>certfile</i>) 146 File with PEM-encoded TLS client private key. This defaults to 147 <i>certfile</i> if one is specified. 148 149 <b>-l</b> <i>level</i> (default: <b>dane</b> or <b>secure</b>) 150 The security level for the connection, default <b>dane</b> or <b>secure</b> 151 depending on whether DNSSEC is available. For syntax and seman- 152 tics, see the documentation of <a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a>. When 153 <b>dane</b> or <b>dane-only</b> is supported and selected, if no TLSA records 154 are found, or all the records found are unusable, the <i>secure</i> 155 level will be used instead. The <b>fingerprint</b> security level 156 allows you to test certificate or public-key fingerprint matches 157 before you deploy them in the policy table. 158 159 Note, since <b>posttls-finger</b> does not actually deliver any email, 160 the <b>none</b>, <b>may</b> and <b>encrypt</b> security levels are not very useful. 161 Since <b>may</b> and <b>encrypt</b> don't require peer certificates, they will 162 often negotiate anonymous TLS ciphersuites, so you won't learn 163 much about the remote SMTP server's certificates at these levels 164 if it also supports anonymous TLS (though you may learn that the 165 server supports anonymous TLS). 166 167 <b>-L</b> <i>logopts</i> (default: <b>routine,certmatch</b>) 168 Fine-grained TLS logging options. To tune the TLS features 169 logged during the TLS handshake, specify one or more of: 170 171 <b>0, none</b> 172 These yield no TLS logging; you'll generally want more, 173 but this is handy if you just want the trust chain: 174 $ posttls-finger -cC -L none destination 175 176 <b>1, routine, summary</b> 177 These synonymous values yield a normal one-line summary 178 of the TLS connection. 179 180 <b>2, debug</b> 181 These synonymous values combine routine, ssl-debug, cache 182 and verbose. 183 184 <b>3, ssl-expert</b> 185 These synonymous values combine debug with ssl-hand- 186 shake-packet-dump. For experts only. 187 188 <b>4, ssl-developer</b> 189 These synonymous values combine ssl-expert with ssl-ses- 190 sion-packet-dump. For experts only, and in most cases, 191 use wireshark instead. 192 193 <b>ssl-debug</b> 194 Turn on OpenSSL logging of the progress of the SSL hand- 195 shake. 196 197 <b>ssl-handshake-packet-dump</b> 198 Log hexadecimal packet dumps of the SSL handshake; for 199 experts only. 200 201 <b>ssl-session-packet-dump</b> 202 Log hexadecimal packet dumps of the entire SSL session; 203 only useful to those who can debug SSL protocol problems 204 from hex dumps. 205 206 <b>untrusted</b> 207 Logs trust chain verification problems. This is turned 208 on automatically at security levels that use peer names 209 signed by Certification Authorities to validate certifi- 210 cates. So while this setting is recognized, you should 211 never need to set it explicitly. 212 213 <b>peercert</b> 214 This logs a one line summary of the remote SMTP server 215 certificate subject, issuer, and fingerprints. 216 217 <b>certmatch</b> 218 This logs remote SMTP server certificate matching, show- 219 ing the CN and each subjectAltName and which name 220 matched. With DANE, logs matching of TLSA record 221 trust-anchor and end-entity certificates. 222 223 <b>cache</b> This logs session cache operations, showing whether ses- 224 sion caching is effective with the remote SMTP server. 225 Automatically used when reconnecting with the <b>-r</b> option; 226 rarely needs to be set explicitly. 227 228 <b>verbose</b> 229 Enables verbose logging in the Postfix TLS driver; 230 includes all of peercert..cache and more. 231 232 The default is <b>routine,certmatch</b>. After a reconnect, <b>peercert</b>, 233 <b>certmatch</b> and <b>verbose</b> are automatically disabled while <b>cache</b> and 234 <b>summary</b> are enabled. 235 236 <b>-m</b> <i>count</i> (default: <b>5</b>) 237 When the <b>-r</b> <i>delay</i> option is specified, the <b>-m</b> option determines 238 the maximum number of reconnect attempts to use with a server 239 behind a load balancer, to see whether connection caching is 240 likely to be effective for this destination. Some MTAs don't 241 expose the underlying server identity in their EHLO response; 242 with these servers there will never be more than 1 reconnection 243 attempt. 244 245 <b>-M</b> <i>insecure</i><b>_</b><i>mx</i><b>_</b><i>policy</i> (default: <b>dane</b>) 246 The TLS policy for MX hosts with "secure" TLSA records when the 247 nexthop destination security level is <b>dane</b>, but the MX record 248 was found via an "insecure" MX lookup. See the <a href="postconf.5.html">main.cf</a> documen- 249 tation for smtp_tls_insecure_mx_policy for details. 250 251 <b>-o</b> <i>name=value</i> 252 Specify zero or more times to override the value of the <a href="postconf.5.html">main.cf</a> 253 parameter <i>name</i> with <i>value</i>. Possible use-cases include overrid- 254 ing the values of TLS library parameters, or "<a href="postconf.5.html#myhostname">myhostname</a>" to 255 configure the SMTP EHLO name sent to the remote server. 256 257 <b>-p</b> <i>protocols</i> (default: !SSLv2) 258 List of TLS protocols that posttls-finger will exclude or 259 include. See <a href="postconf.5.html#smtp_tls_mandatory_protocols">smtp_tls_mandatory_protocols</a> for details. 260 261 <b>-P</b> <i>CApath/</i> (default: none) 262 The OpenSSL CApath/ directory (indexed via c_rehash(1)) for 263 remote SMTP server certificate verification. By default no CAp- 264 ath is used and no public CAs are trusted. 265 266 <b>-r</b> <i>delay</i> 267 With a cacheable TLS session, disconnect and reconnect after 268 <i>delay</i> seconds. Report whether the session is re-used. Retry if a 269 new server is encountered, up to 5 times or as specified with 270 the <b>-m</b> option. By default reconnection is disabled, specify a 271 positive delay to enable this behavior. 272 273 <b>-s</b> <i>servername</i> 274 The server name to send with the TLS Server Name Indication 275 (SNI) extension. When the server has DANE TLSA records, this 276 parameter is ignored and the TLSA base domain is used instead. 277 Otherwise, SNI is not used by default, but can be enabled by 278 specifying the desired value with this option. 279 280 <b>-S</b> Disable SMTP; that is, connect to an LMTP server. The default 281 port for LMTP over TCP is 24. Alternative ports can specified 282 by appending "<i>:servicename</i>" or ":<i>portnumber</i>" to the destination 283 argument. 284 285 <b>-t</b> <i>timeout</i> (default: <b>30</b>) 286 The TCP connection timeout to use. This is also the timeout for 287 reading the remote server's 220 banner. 288 289 <b>-T</b> <i>timeout</i> (default: <b>30</b>) 290 The SMTP/LMTP command timeout for EHLO/LHLO, STARTTLS and QUIT. 291 292 <b>-v</b> Enable verbose Postfix logging. Specify more than once to 293 increase the level of verbose logging. 294 295 <b>-w</b> Enable outgoing TLS wrapper mode, or SMTPS support. This is 296 typically provided on port 465 by servers that are compatible 297 with the ad-hoc SMTP in SSL protocol, rather than the standard 298 STARTTLS protocol. The destination <i>domain</i>:<i>port</i> should of course 299 provide such a service. 300 301 <b>-X</b> Enable <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> mode. This is an unsupported mode, for pro- 302 gram development only. 303 304 [<b>inet:</b>]<i>domain</i>[:<i>port</i>] 305 Connect via TCP to domain <i>domain</i>, port <i>port</i>. The default port is 306 <b>smtp</b> (or 24 with LMTP). With SMTP an MX lookup is performed to 307 resolve the domain to a host, unless the domain is enclosed in 308 <b>[]</b>. If you want to connect to a specific MX host, for instance 309 <i>mx1.example.com</i>, specify [<i>mx1.example.com</i>] as the destination 310 and <i>example.com</i> as a <b>match</b> argument. When using DNS, the desti- 311 nation domain is assumed fully qualified and no default domain 312 or search suffixes are applied; you must use fully-qualified 313 names or also enable <b>native</b> host lookups (these don't support 314 <b>dane</b> or <b>dane-only</b> as no DNSSEC validation information is avail- 315 able via <b>native</b> lookups). 316 317 <b>unix:</b><i>pathname</i> 318 Connect to the UNIX-domain socket at <i>pathname</i>. LMTP only. 319 320 <b>match ...</b> 321 With no match arguments specified, certificate peername matching 322 uses the compiled-in default strategies for each security level. 323 If you specify one or more arguments, these will be used as the 324 list of certificate or public-key digests to match for the <b>fin-</b> 325 <b>gerprint</b> level, or as the list of DNS names to match in the cer- 326 tificate at the <b>verify</b> and <b>secure</b> levels. If the security level 327 is <b>dane</b>, or <b>dane-only</b> the match names are ignored, and <b>hostname,</b> 328 <b>nexthop</b> strategies are used. 329 330<b>ENVIRONMENT</b> 331 <b>MAIL_CONFIG</b> 332 Read configuration parameters from a non-default location. 333 334 <b>MAIL_VERBOSE</b> 335 Same as <b>-v</b> option. 336 337<b>SEE ALSO</b> 338 <a href="smtp-source.1.html">smtp-source(1)</a>, SMTP/LMTP message source 339 <a href="smtp-sink.1.html">smtp-sink(1)</a>, SMTP/LMTP message dump 340 341<b>README FILES</b> 342 <a href="TLS_README.html">TLS_README</a>, Postfix STARTTLS howto 343 344<b>LICENSE</b> 345 The Secure Mailer license must be distributed with this software. 346 347<b>AUTHOR(S)</b> 348 Wietse Venema 349 IBM T.J. Watson Research 350 P.O. Box 704 351 Yorktown Heights, NY 10598, USA 352 353 Wietse Venema 354 Google, Inc. 355 111 8th Avenue 356 New York, NY 10011, USA 357 358 Viktor Dukhovni 359 360 POSTTLS-FINGER(1) 361</pre> </body> </html> 362