summaryrefslogtreecommitdiffstats
path: root/html/XCLIENT_README.html
diff options
context:
space:
mode:
Diffstat (limited to 'html/XCLIENT_README.html')
-rw-r--r--html/XCLIENT_README.html268
1 files changed, 268 insertions, 0 deletions
diff --git a/html/XCLIENT_README.html b/html/XCLIENT_README.html
new file mode 100644
index 0000000..2286294
--- /dev/null
+++ b/html/XCLIENT_README.html
@@ -0,0 +1,268 @@
+<!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=utf-8">
+<link rel='stylesheet' type='text/css' href='postfix-doc.css'>
+
+</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-&gt;filter-&gt;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 <a href="https://tools.ietf.org/html/rfc1891">RFC 1891</a>.
+ </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:&lt;wietse@porcupine.org&gt;</b>
+250 Ok
+<b>RCPT TO:&lt;user@example.com&gt;</b>
+250 Ok
+<b>DATA</b>
+354 End data with &lt;CR&gt;&lt;LF&gt;.&lt;CR&gt;&lt;LF&gt;
+<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",
+<a href="https://tools.ietf.org/html/rfc1891">RFC 1891</a>, January 1996. </p>
+
+</body>
+
+</html>