postfix-master/XCLIENT_README.html

   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=us-ascii">
  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,
  23 an SMTP client may send information that overrides one or more
  24 client-related session attributes. The XCLIENT command targets the
  25 following 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-&gt;filter-&gt;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
  59 of this document. </p>
  60
  61 <p> In SMTP server EHLO replies, the keyword associated with this
  62 extension is XCLIENT. It is followed by the names of the attributes
  63 that the XCLIENT implementation supports.  </p>
  64
  65 <p> The XCLIENT command may be sent at any time, except in the
  66 middle of a mail delivery transaction (i.e.  between MAIL and DOT,
  67 or MAIL and RSET).  The XCLIENT command may be pipelined when the
  68 server supports ESMTP command pipelining. To avoid triggering
  69 spamware detectors, the command should be sent at the end of a
  70 command group.  </p>
  71
  72 <p> The syntax of XCLIENT requests is described below.  Upper case
  73 and quoted strings specify terminals, lowercase strings specify
  74 meta terminals, and SP is whitespace.  Although command and attribute
  75 names 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 )
  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 <a href="http://tools.ietf.org/html/rfc1891">RFC 1891</a>.
  93     </p>
  94
  95     <li> <p> The NAME attribute specifies an SMTP client hostname
  96     (not an SMTP client address), [UNAVAILABLE] when client hostname
  97     lookup failed due to a permanent error, or [TEMPUNAVAIL] when
  98     the lookup error condition was transient. </p>
  99
 100     <li> <p> The ADDR attribute specifies an SMTP client numerical
 101     IPv4 network address, an IPv6 address prefixed with IPV6:, or
 102     [UNAVAILABLE] when the address information is unavailable.
 103     Address information is not enclosed with []. </p>
 104
 105     <li> <p> The PORT attribute specifies the SMTP client TCP port
 106     number as a decimal number, or [UNAVAILABLE] when the information
 107     is unavailable.  </p>
 108
 109     <li> <p> The PROTO attribute specifies either SMTP or ESMTP.
 110     </p>
 111
 112     <li> <p> The HELO attribute specifies an SMTP HELO parameter
 113     value, or the value [UNAVAILABLE] when the information is
 114     unavailable.  </p>
 115
 116 </ul>
 117
 118 <p> Note 1: syntactically valid NAME and HELO attribute-value
 119 elements can be up to 255 characters long. The client must not send
 120 XCLIENT commands that exceed the 512 character limit for SMTP
 121 commands. To avoid exceeding the limit the client should send the
 122 information in multiple XCLIENT commands; for example, send NAME
 123 and ADDR first, then HELO and PROTO. </p>
 124
 125 <p> Note 2: [UNAVAILABLE], [TEMPUNAVAIL] and IPV6:  may be specified
 126 in upper case, lower case or mixed case. </p>
 127
 128 <p> Note 3: Postfix implementations prior to version 2.3 do not
 129 xtext encode attribute values. Servers that wish to interoperate
 130 with these older implementations should be prepared to receive
 131 unencoded information. </p>
 132
 133 <p> Note 4: Postfix implementations prior to version 2.5 do not
 134 implement the PORT attribute.  </p>
 135
 136 <h2>XCLIENT Server response</h2>
 137
 138 <p> Upon receipt of a correctly formatted XCLIENT command, the
 139 server resets state to the initial SMTP greeting protocol stage.
 140 Depending on the outcome of optional access decisions, the server
 141 responds with 220 or with a suitable rejection code.
 142
 143 <p> For practical reasons it is not always possible to reset the
 144 complete server state to the initial SMTP greeting protocol stage:
 145 </p>
 146
 147 <ul>
 148
 149 <li> <p> TLS session information may not be reset, because turning off
 150 TLS leaves the connection in an undefined state.  Consequently, the
 151 server may not announce STARTTLS when TLS is already active, and
 152 access decisions may be influenced by client certificate information
 153 that was received prior to the XCLIENT command. </p>
 154
 155 <li> <p> The SMTP server must not reset attributes that were received
 156 with the last XCLIENT command. This includes HELO or PROTO attributes.
 157 </p>
 158
 159 </ul>
 160
 161 <p> NOTE: Postfix implementations prior to version 2.3 do not jump
 162 back to the initial SMTP greeting protocol stage.  These older
 163 implementations will not correctly simulate connection-level access
 164 decisions under some conditions.  </p>
 165
 166 <h2> XCLIENT server reply codes </h2>
 167
 168 <blockquote>
 169
 170 <table border="1" bgcolor="#f0f0ff">
 171
 172 <tr> <th> Code </th> <th> Meaning </th> </tr>
 173
 174 <tr> <td> 220 </td> <td> success  </td> </tr>
 175
 176 <tr> <td> 421 </td> <td> unable to proceed, disconnecting </td> </tr>
 177
 178 <tr> <td> 501 </td> <td> bad command parameter syntax </td> </tr>
 179
 180 <tr> <td> 503 </td> <td> mail transaction in progress </td> </tr>
 181
 182 <tr> <td> 550 </td> <td> insufficient authorization </td> </tr>
 183
 184 <tr> <td> other </td> <td> connection rejected by connection-level
 185 access decision </td> </tr>
 186
 187 </table>
 188
 189 </blockquote>
 190
 191 <h2>XCLIENT Example</h2>
 192
 193 <p> In the example, the client impersonates a mail originating
 194 system by passing all SMTP client information via the XCLIENT
 195 command.  Information sent by the client is shown in bold font.
 196 </p>
 197
 198 <blockquote>
 199 <pre>
 200 220 server.example.com ESMTP Postfix
 201 <b>EHLO client.example.com</b>
 202 250-server.example.com
 203 250-PIPELINING
 204 250-SIZE 10240000
 205 250-VRFY
 206 250-ETRN
 207 250-XCLIENT NAME ADDR PROTO HELO
 208 250 8BITMIME
 209 <b>XCLIENT NAME=spike.porcupine.org ADDR=168.100.189.2</b>
 210 220 server.example.com ESMTP Postfix
 211 <b>EHLO spike.porcupine.org</b>
 212 250-server.example.com
 213 250-PIPELINING
 214 250-SIZE 10240000
 215 250-VRFY
 216 250-ETRN
 217 250-XCLIENT NAME ADDR PROTO HELO
 218 250 8BITMIME
 219 <b>MAIL FROM:&lt;wietse@porcupine.org&gt;</b>
 220 250 Ok
 221 <b>RCPT TO:&lt;user@example.com&gt;</b>
 222 250 Ok
 223 <b>DATA</b>
 224 354 End data with &lt;CR&gt;&lt;LF&gt;.&lt;CR&gt;&lt;LF&gt;
 225 <b>. . .<i>message content</i>. . .</b>
 226 <b>.</b>
 227 250 Ok: queued as 763402AAE6
 228 <b>QUIT</b>
 229 221 Bye
 230 </pre>
 231 </blockquote>
 232
 233 <h2>Security</h2>
 234
 235 <p> The XCLIENT command changes audit trails and/or SMTP client
 236 access permissions. Use of this command must be restricted to
 237 authorized SMTP clients. </p>
 238
 239 <h2>SMTP connection caching</h2>
 240
 241 <p> XCLIENT attributes persist until the end of an SMTP session.
 242 If one session is used to deliver mail on behalf of different SMTP
 243 clients, the XCLIENT attributes need to be reset as appropriate
 244 before each MAIL FROM command. </p>
 245
 246 <h2> References </h2>
 247
 248 <p> Moore, K, "SMTP Service Extension for Delivery Status Notifications",
 249 <a href="http://tools.ietf.org/html/rfc1891">RFC 1891</a>, January 1996. </p>
 250
 251 </body>
 252
 253 </html>