1<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" 2 "http://www.w3.org/TR/html4/loose.dtd"> 3 4<html> 5 6<head> 7 8<title>Postfix XCLIENT Howto</title> 9 10<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 11 12</head> 13 14<body> 15 16<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix XCLIENT Howto</h1> 17 18<hr> 19 20<h2>Purpose of the XCLIENT extension to SMTP</h2> 21 22<p> When an SMTP server announces support for the XCLIENT command, 23an SMTP client may send information that overrides one or more 24client-related session attributes. The XCLIENT command targets the 25following problems: </p> 26 27<ol> 28 29 <li> <p> Access control tests. SMTP server access rules are 30 difficult to verify when decisions can be triggered only by 31 remote clients. In order to facilitate access rule testing, 32 an authorized SMTP client test program needs the ability to 33 override the SMTP server's idea of the SMTP client hostname, 34 network address, and other client information, for the entire 35 duration of an SMTP session. </p> 36 37 <li> <p> Client software that downloads mail from an up-stream 38 mail server and injects it into a local MTA via SMTP. In order 39 to take advantage of the local MTA's SMTP server access rules, 40 the client software needs the ability to override the SMTP 41 server's idea of the remote client name, client address and 42 other information. Such information can typically be extracted 43 from the up-stream mail server's Received: message header. </p> 44 45 <li> <p> Post-filter access control and logging. With 46 Internet->filter->MTA style content filter applications, 47 the filter can be simplified if it can delegate decisions 48 concerning mail relay and other access control to the MTA. This 49 is especially useful when the filter acts as a transparent 50 proxy for SMTP commands. This requires that the filter can 51 override the MTA's idea of the SMTP client hostname, network 52 address, and other information. </p> 53 54</ol> 55 56<h2>XCLIENT Command syntax</h2> 57 58<p> An example client-server conversation is given at the end 59of this document. </p> 60 61<p> In SMTP server EHLO replies, the keyword associated with this 62extension is XCLIENT. It is followed by the names of the attributes 63that the XCLIENT implementation supports. </p> 64 65<p> The XCLIENT command may be sent at any time, except in the 66middle of a mail delivery transaction (i.e. between MAIL and DOT, 67or MAIL and RSET). The XCLIENT command may be pipelined when the 68server supports ESMTP command pipelining. To avoid triggering 69spamware detectors, the command should be sent at the end of a 70command group. </p> 71 72<p> The syntax of XCLIENT requests is described below. Upper case 73and quoted strings specify terminals, lowercase strings specify 74meta terminals, and SP is whitespace. Although command and attribute 75names are shown in upper case, they are in fact case insensitive. 76</p> 77 78<blockquote> 79<p> 80 xclient-command = XCLIENT 1*( SP attribute-name"="attribute-value ) 81</p> 82<p> 83 attribute-name = ( NAME | ADDR | PORT | PROTO | HELO | LOGIN | DESTADDR | DESTPORT ) 84</p> 85<p> 86 attribute-value = xtext 87</p> 88</blockquote> 89 90<ul> 91 92 <li> <p> Attribute values are xtext encoded as per RFC 1891. 93 </p> 94 95 <li> <p> The NAME attribute specifies a remote SMTP client 96 hostname (not an SMTP client address), [UNAVAILABLE] when client 97 hostname lookup failed due to a permanent error, or [TEMPUNAVAIL] 98 when the lookup error condition was transient. </p> 99 100 <li> <p> The ADDR attribute specifies a remote SMTP client 101 numerical IPv4 network address, an IPv6 address prefixed with 102 IPV6:, or [UNAVAILABLE] when the address information is 103 unavailable. Address information is not enclosed with []. </p> 104 105 <li> <p> The PORT attribute specifies a remote SMTP client TCP 106 port number as a decimal number, or [UNAVAILABLE] when the 107 information is unavailable. </p> 108 109 <li> <p> The PROTO attribute specifies either SMTP or ESMTP. 110 </p> 111 112 <li> <p> The DESTADDR attribute specifies a local SMTP server 113 numerical IPv4 network address, an IPv6 address prefixed with 114 IPV6:, or [UNAVAILABLE] when the address information is 115 unavailable. Address information is not enclosed with []. </p> 116 117 <li> <p> The DESTPORT attribute specifies a local SMTP server 118 TCP port number as a decimal number, or [UNAVAILABLE] when the 119 information is unavailable. </p> 120 121 <li> <p> The HELO attribute specifies an SMTP HELO parameter 122 value, or the value [UNAVAILABLE] when the information is 123 unavailable. </p> 124 125 <li> <p> The LOGIN attribute specifies a SASL login name, or 126 the value [UNAVAILABLE] when the information is unavailable. 127 </p> 128 129</ul> 130 131<p> Note 1: syntactically valid NAME and HELO attribute-value 132elements can be up to 255 characters long. The client must not send 133XCLIENT commands that exceed the 512 character limit for SMTP 134commands. To avoid exceeding the limit the client should send the 135information in multiple XCLIENT commands; for example, send NAME 136and ADDR last, after HELO and PROTO. Once ADDR is sent, the client 137is usually no longer authorized to send XCLIENT commands. </p> 138 139<p> Note 2: [UNAVAILABLE], [TEMPUNAVAIL] and IPV6: may be specified 140in upper case, lower case or mixed case. </p> 141 142<p> Note 3: Postfix implementations prior to version 2.3 do not 143xtext encode attribute values. Servers that wish to interoperate 144with these older implementations should be prepared to receive 145unencoded information. </p> 146 147<p> Note 4: Some Postfix implementations do not implement the PORT 148or LOGIN attributes. </p> 149 150<h2>XCLIENT Server response</h2> 151 152<p> Upon receipt of a correctly formatted XCLIENT command, the 153server resets state to the initial SMTP greeting protocol stage. 154Depending on the outcome of optional access decisions, the server 155responds with 220 or with a suitable rejection code. 156 157<p> For practical reasons it is not always possible to reset the 158complete server state to the initial SMTP greeting protocol stage: 159</p> 160 161<ul> 162 163<li> <p> TLS session information may not be reset, because turning off 164TLS leaves the connection in an undefined state. Consequently, the 165server may not announce STARTTLS when TLS is already active, and 166access decisions may be influenced by client certificate information 167that was received prior to the XCLIENT command. </p> 168 169<li> <p> The SMTP server must not reset attributes that were received 170with the last XCLIENT command. This includes HELO or PROTO attributes. 171</p> 172 173</ul> 174 175<p> NOTE: Postfix implementations prior to version 2.3 do not jump 176back to the initial SMTP greeting protocol stage. These older 177implementations will not correctly simulate connection-level access 178decisions under some conditions. </p> 179 180<h2> XCLIENT server reply codes </h2> 181 182<blockquote> 183 184<table border="1" bgcolor="#f0f0ff"> 185 186<tr> <th> Code </th> <th> Meaning </th> </tr> 187 188<tr> <td> 220 </td> <td> success </td> </tr> 189 190<tr> <td> 421 </td> <td> unable to proceed, disconnecting </td> </tr> 191 192<tr> <td> 501 </td> <td> bad command parameter syntax </td> </tr> 193 194<tr> <td> 503 </td> <td> mail transaction in progress </td> </tr> 195 196<tr> <td> 550 </td> <td> insufficient authorization </td> </tr> 197 198<tr> <td> other </td> <td> connection rejected by connection-level 199access decision </td> </tr> 200 201</table> 202 203</blockquote> 204 205<h2>XCLIENT Example</h2> 206 207<p> In the example, the client impersonates a mail originating 208system by passing all SMTP client information via the XCLIENT 209command. Information sent by the client is shown in bold font. 210</p> 211 212<blockquote> 213<pre> 214220 server.example.com ESMTP Postfix 215<b>EHLO client.example.com</b> 216250-server.example.com 217250-PIPELINING 218250-SIZE 10240000 219250-VRFY 220250-ETRN 221250-XCLIENT NAME ADDR PROTO HELO 222250 8BITMIME 223<b>XCLIENT NAME=spike.porcupine.org ADDR=168.100.189.2</b> 224220 server.example.com ESMTP Postfix 225<b>EHLO spike.porcupine.org</b> 226250-server.example.com 227250-PIPELINING 228250-SIZE 10240000 229250-VRFY 230250-ETRN 231250-XCLIENT NAME ADDR PROTO HELO 232250 8BITMIME 233<b>MAIL FROM:<wietse@porcupine.org></b> 234250 Ok 235<b>RCPT TO:<user@example.com></b> 236250 Ok 237<b>DATA</b> 238354 End data with <CR><LF>.<CR><LF> 239<b>. . .<i>message content</i>. . .</b> 240<b>.</b> 241250 Ok: queued as 763402AAE6 242<b>QUIT</b> 243221 Bye 244</pre> 245</blockquote> 246 247<h2>Security</h2> 248 249<p> The XCLIENT command changes audit trails and/or SMTP client 250access permissions. Use of this command must be restricted to 251authorized SMTP clients. </p> 252 253<h2>SMTP connection caching</h2> 254 255<p> XCLIENT attributes persist until the end of an SMTP session. 256If one session is used to deliver mail on behalf of different SMTP 257clients, the XCLIENT attributes need to be reset as appropriate 258before each MAIL FROM command. </p> 259 260<h2> References </h2> 261 262<p> Moore, K, "SMTP Service Extension for Delivery Status Notifications", 263RFC 1891, January 1996. </p> 264 265</body> 266 267</html> 268
