244 lines
7.7 KiB
HTML
244 lines
7.7 KiB
HTML
<!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> 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 | PROTO | HELO )
|
|
</p>
|
|
<p>
|
|
attribute-value = xtext
|
|
</p>
|
|
</blockquote>
|
|
|
|
<ul>
|
|
|
|
<li> <p> Attribute values are xtext encoded as per <a href="http://www.faqs.org/rfcs/rfc1891.html">RFC 1891</a>.
|
|
</p>
|
|
|
|
<li> <p> The NAME attribute specifies an 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 an 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 PROTO attribute specifies either SMTP or ESMTP.
|
|
</p>
|
|
|
|
<li> <p> The HELO attribute specifies an SMTP HELO parameter
|
|
value, 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 first, then HELO and PROTO. </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>
|
|
|
|
<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",
|
|
<a href="http://www.faqs.org/rfcs/rfc1891.html">RFC 1891</a>, January 1996. </p>
|
|
|
|
</body>
|
|
|
|
</html>
|