diff options
Diffstat (limited to 'proto/XCLIENT_README.html')
| -rw-r--r-- | proto/XCLIENT_README.html | 267 |
1 files changed, 267 insertions, 0 deletions
diff --git a/proto/XCLIENT_README.html b/proto/XCLIENT_README.html new file mode 100644 index 0000000..e4e2f0a --- /dev/null +++ b/proto/XCLIENT_README.html @@ -0,0 +1,267 @@ +<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> + +<html> + +<head> + +<title>Postfix XCLIENT Howto</title> + +<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> + +</head> + +<body> + +<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix XCLIENT Howto</h1> + +<hr> + +<h2>Purpose of the XCLIENT extension to SMTP</h2> + +<p> When an SMTP server announces support for the XCLIENT command, +an SMTP client may send information that overrides one or more +client-related session attributes. The XCLIENT command targets the +following problems: </p> + +<ol> + + <li> <p> Access control tests. SMTP server access rules are + difficult to verify when decisions can be triggered only by + remote clients. In order to facilitate access rule testing, + an authorized SMTP client test program needs the ability to + override the SMTP server's idea of the SMTP client hostname, + network address, and other client information, for the entire + duration of an SMTP session. </p> + + <li> <p> Client software that downloads mail from an up-stream + mail server and injects it into a local MTA via SMTP. In order + to take advantage of the local MTA's SMTP server access rules, + the client software needs the ability to override the SMTP + server's idea of the remote client name, client address and + other information. Such information can typically be extracted + from the up-stream mail server's Received: message header. </p> + + <li> <p> Post-filter access control and logging. With + Internet->filter->MTA style content filter applications, + the filter can be simplified if it can delegate decisions + concerning mail relay and other access control to the MTA. This + is especially useful when the filter acts as a transparent + proxy for SMTP commands. This requires that the filter can + override the MTA's idea of the SMTP client hostname, network + address, and other information. </p> + +</ol> + +<h2>XCLIENT Command syntax</h2> + +<p> An example client-server conversation is given at the end +of this document. </p> + +<p> In SMTP server EHLO replies, the keyword associated with this +extension is XCLIENT. It is followed by the names of the attributes +that the XCLIENT implementation supports. </p> + +<p> The XCLIENT command may be sent at any time, except in the +middle of a mail delivery transaction (i.e. between MAIL and DOT, +or MAIL and RSET). The XCLIENT command may be pipelined when the +server supports ESMTP command pipelining. To avoid triggering +spamware detectors, the command should be sent at the end of a +command group. </p> + +<p> The syntax of XCLIENT requests is described below. Upper case +and quoted strings specify terminals, lowercase strings specify +meta terminals, and SP is whitespace. Although command and attribute +names are shown in upper case, they are in fact case insensitive. +</p> + +<blockquote> +<p> + xclient-command = XCLIENT 1*( SP attribute-name"="attribute-value ) +</p> +<p> + attribute-name = ( NAME | ADDR | PORT | PROTO | HELO | LOGIN | DESTADDR | DESTPORT ) +</p> +<p> + attribute-value = xtext +</p> +</blockquote> + +<ul> + + <li> <p> Attribute values are xtext encoded as per RFC 1891. + </p> + + <li> <p> The NAME attribute specifies a remote SMTP client + hostname (not an SMTP client address), [UNAVAILABLE] when client + hostname lookup failed due to a permanent error, or [TEMPUNAVAIL] + when the lookup error condition was transient. </p> + + <li> <p> The ADDR attribute specifies a remote SMTP client + numerical IPv4 network address, an IPv6 address prefixed with + IPV6:, or [UNAVAILABLE] when the address information is + unavailable. Address information is not enclosed with []. </p> + + <li> <p> The PORT attribute specifies a remote SMTP client TCP + port number as a decimal number, or [UNAVAILABLE] when the + information is unavailable. </p> + + <li> <p> The PROTO attribute specifies either SMTP or ESMTP. + </p> + + <li> <p> The DESTADDR attribute specifies a local SMTP server + numerical IPv4 network address, an IPv6 address prefixed with + IPV6:, or [UNAVAILABLE] when the address information is + unavailable. Address information is not enclosed with []. </p> + + <li> <p> The DESTPORT attribute specifies a local SMTP server + TCP port number as a decimal number, or [UNAVAILABLE] when the + information is unavailable. </p> + + <li> <p> The HELO attribute specifies an SMTP HELO parameter + value, or the value [UNAVAILABLE] when the information is + unavailable. </p> + + <li> <p> The LOGIN attribute specifies a SASL login name, or + the value [UNAVAILABLE] when the information is unavailable. + </p> + +</ul> + +<p> Note 1: syntactically valid NAME and HELO attribute-value +elements can be up to 255 characters long. The client must not send +XCLIENT commands that exceed the 512 character limit for SMTP +commands. To avoid exceeding the limit the client should send the +information in multiple XCLIENT commands; for example, send NAME +and ADDR last, after HELO and PROTO. Once ADDR is sent, the client +is usually no longer authorized to send XCLIENT commands. </p> + +<p> Note 2: [UNAVAILABLE], [TEMPUNAVAIL] and IPV6: may be specified +in upper case, lower case or mixed case. </p> + +<p> Note 3: Postfix implementations prior to version 2.3 do not +xtext encode attribute values. Servers that wish to interoperate +with these older implementations should be prepared to receive +unencoded information. </p> + +<p> Note 4: Some Postfix implementations do not implement the PORT +or LOGIN attributes. </p> + +<h2>XCLIENT Server response</h2> + +<p> Upon receipt of a correctly formatted XCLIENT command, the +server resets state to the initial SMTP greeting protocol stage. +Depending on the outcome of optional access decisions, the server +responds with 220 or with a suitable rejection code. + +<p> For practical reasons it is not always possible to reset the +complete server state to the initial SMTP greeting protocol stage: +</p> + +<ul> + +<li> <p> TLS session information may not be reset, because turning off +TLS leaves the connection in an undefined state. Consequently, the +server may not announce STARTTLS when TLS is already active, and +access decisions may be influenced by client certificate information +that was received prior to the XCLIENT command. </p> + +<li> <p> The SMTP server must not reset attributes that were received +with the last XCLIENT command. This includes HELO or PROTO attributes. +</p> + +</ul> + +<p> NOTE: Postfix implementations prior to version 2.3 do not jump +back to the initial SMTP greeting protocol stage. These older +implementations will not correctly simulate connection-level access +decisions under some conditions. </p> + +<h2> XCLIENT server reply codes </h2> + +<blockquote> + +<table border="1" bgcolor="#f0f0ff"> + +<tr> <th> Code </th> <th> Meaning </th> </tr> + +<tr> <td> 220 </td> <td> success </td> </tr> + +<tr> <td> 421 </td> <td> unable to proceed, disconnecting </td> </tr> + +<tr> <td> 501 </td> <td> bad command parameter syntax </td> </tr> + +<tr> <td> 503 </td> <td> mail transaction in progress </td> </tr> + +<tr> <td> 550 </td> <td> insufficient authorization </td> </tr> + +<tr> <td> other </td> <td> connection rejected by connection-level +access decision </td> </tr> + +</table> + +</blockquote> + +<h2>XCLIENT Example</h2> + +<p> In the example, the client impersonates a mail originating +system by passing all SMTP client information via the XCLIENT +command. Information sent by the client is shown in bold font. +</p> + +<blockquote> +<pre> +220 server.example.com ESMTP Postfix +<b>EHLO client.example.com</b> +250-server.example.com +250-PIPELINING +250-SIZE 10240000 +250-VRFY +250-ETRN +250-XCLIENT NAME ADDR PROTO HELO +250 8BITMIME +<b>XCLIENT NAME=spike.porcupine.org ADDR=168.100.189.2</b> +220 server.example.com ESMTP Postfix +<b>EHLO spike.porcupine.org</b> +250-server.example.com +250-PIPELINING +250-SIZE 10240000 +250-VRFY +250-ETRN +250-XCLIENT NAME ADDR PROTO HELO +250 8BITMIME +<b>MAIL FROM:<wietse@porcupine.org></b> +250 Ok +<b>RCPT TO:<user@example.com></b> +250 Ok +<b>DATA</b> +354 End data with <CR><LF>.<CR><LF> +<b>. . .<i>message content</i>. . .</b> +<b>.</b> +250 Ok: queued as 763402AAE6 +<b>QUIT</b> +221 Bye +</pre> +</blockquote> + +<h2>Security</h2> + +<p> The XCLIENT command changes audit trails and/or SMTP client +access permissions. Use of this command must be restricted to +authorized SMTP clients. </p> + +<h2>SMTP connection caching</h2> + +<p> XCLIENT attributes persist until the end of an SMTP session. +If one session is used to deliver mail on behalf of different SMTP +clients, the XCLIENT attributes need to be reset as appropriate +before each MAIL FROM command. </p> + +<h2> References </h2> + +<p> Moore, K, "SMTP Service Extension for Delivery Status Notifications", +RFC 1891, January 1996. </p> + +</body> + +</html> |