summaryrefslogtreecommitdiffstats
path: root/README_FILES/XCLIENT_README
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-10 19:59:03 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-10 19:59:03 +0000
commita848231ae0f346dc7cc000973fbeb65b0894ee92 (patch)
tree44b60b367c86723cc78383ef247885d72b388afe /README_FILES/XCLIENT_README
parentInitial commit. (diff)
downloadpostfix-a848231ae0f346dc7cc000973fbeb65b0894ee92.tar.xz
postfix-a848231ae0f346dc7cc000973fbeb65b0894ee92.zip
Adding upstream version 3.8.5.upstream/3.8.5
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'README_FILES/XCLIENT_README')
-rw-r--r--README_FILES/XCLIENT_README199
1 files changed, 199 insertions, 0 deletions
diff --git a/README_FILES/XCLIENT_README b/README_FILES/XCLIENT_README
new file mode 100644
index 0000000..89b11bf
--- /dev/null
+++ b/README_FILES/XCLIENT_README
@@ -0,0 +1,199 @@
+PPoossttffiixx XXCCLLIIEENNTT HHoowwttoo
+
+-------------------------------------------------------------------------------
+
+PPuurrppoossee ooff tthhee XXCCLLIIEENNTT eexxtteennssiioonn ttoo SSMMTTPP
+
+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:
+
+ 1. 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.
+
+ 2. 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.
+
+ 3. 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.
+
+XXCCLLIIEENNTT CCoommmmaanndd ssyynnttaaxx
+
+An example client-server conversation is given at the end of this document.
+
+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.
+
+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.
+
+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.
+
+ xclient-command = XCLIENT 1*( SP attribute-name"="attribute-value )
+
+ attribute-name = ( NAME | ADDR | PORT | PROTO | HELO | LOGIN | DESTADDR |
+ DESTPORT )
+
+ attribute-value = xtext
+
+ * Attribute values are xtext encoded as per RFC 1891.
+
+ * 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.
+
+ * 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 [].
+
+ * The PORT attribute specifies a remote SMTP client TCP port number as a
+ decimal number, or [UNAVAILABLE] when the information is unavailable.
+
+ * The PROTO attribute specifies either SMTP or ESMTP.
+
+ * 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 [].
+
+ * The DESTPORT attribute specifies a local SMTP server TCP port number as a
+ decimal number, or [UNAVAILABLE] when the information is unavailable.
+
+ * The HELO attribute specifies an SMTP HELO parameter value, or the value
+ [UNAVAILABLE] when the information is unavailable.
+
+ * The LOGIN attribute specifies a SASL login name, or the value [UNAVAILABLE]
+ when the information is unavailable.
+
+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.
+
+Note 2: [UNAVAILABLE], [TEMPUNAVAIL] and IPV6: may be specified in upper case,
+lower case or mixed case.
+
+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.
+
+Note 4: Some Postfix implementations do not implement the PORT or LOGIN
+attributes.
+
+XXCCLLIIEENNTT SSeerrvveerr rreessppoonnssee
+
+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.
+
+For practical reasons it is not always possible to reset the complete server
+state to the initial SMTP greeting protocol stage:
+
+ * 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.
+
+ * The SMTP server must not reset attributes that were received with the last
+ XCLIENT command. This includes HELO or PROTO attributes.
+
+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.
+
+XXCCLLIIEENNTT sseerrvveerr rreeppllyy ccooddeess
+
+ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
+ |CCooddee |MMeeaanniinngg |
+ |_ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
+ |220 |success |
+ |_ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
+ |421 |unable to proceed, disconnecting |
+ |_ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
+ |501 |bad command parameter syntax |
+ |_ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
+ |503 |mail transaction in progress |
+ |_ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
+ |550 |insufficient authorization |
+ |_ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
+ |other|connection rejected by connection-level access decision|
+ |_ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
+
+XXCCLLIIEENNTT EExxaammppllee
+
+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.
+
+ 220 server.example.com ESMTP Postfix
+ EEHHLLOO cclliieenntt..eexxaammppllee..ccoomm
+ 250-server.example.com
+ 250-PIPELINING
+ 250-SIZE 10240000
+ 250-VRFY
+ 250-ETRN
+ 250-XCLIENT NAME ADDR PROTO HELO
+ 250 8BITMIME
+ XXCCLLIIEENNTT NNAAMMEE==ssppiikkee..ppoorrccuuppiinnee..oorrgg AADDDDRR==116688..110000..118899..22
+ 220 server.example.com ESMTP Postfix
+ EEHHLLOO ssppiikkee..ppoorrccuuppiinnee..oorrgg
+ 250-server.example.com
+ 250-PIPELINING
+ 250-SIZE 10240000
+ 250-VRFY
+ 250-ETRN
+ 250-XCLIENT NAME ADDR PROTO HELO
+ 250 8BITMIME
+ MMAAIILL FFRROOMM::<<wwiieettssee@@ppoorrccuuppiinnee..oorrgg>>
+ 250 Ok
+ RRCCPPTT TTOO::<<uusseerr@@eexxaammppllee..ccoomm>>
+ 250 Ok
+ DDAATTAA
+ 354 End data with <CR><LF>.<CR><LF>
+ .. .. ..mmeessssaaggee ccoonntteenntt.. .. ..
+ ..
+ 250 Ok: queued as 763402AAE6
+ QQUUIITT
+ 221 Bye
+
+SSeeccuurriittyy
+
+The XCLIENT command changes audit trails and/or SMTP client access permissions.
+Use of this command must be restricted to authorized SMTP clients.
+
+SSMMTTPP ccoonnnneeccttiioonn ccaacchhiinngg
+
+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.
+
+RReeffeerreenncceess
+
+Moore, K, "SMTP Service Extension for Delivery Status Notifications", RFC 1891,
+January 1996.
+