1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
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->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 <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:<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="https://tools.ietf.org/html/rfc1891">RFC 1891</a>, January 1996. </p>
</body>
</html>
|
