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