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