From b5896ba9f6047e7031e2bdee0622d543e11a6734 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 6 May 2024 03:46:30 +0200 Subject: Adding upstream version 3.4.23. Signed-off-by: Daniel Baumann --- html/XCLIENT_README.html | 267 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 267 insertions(+) create mode 100644 html/XCLIENT_README.html (limited to 'html/XCLIENT_README.html') diff --git a/html/XCLIENT_README.html b/html/XCLIENT_README.html new file mode 100644 index 0000000..a58a321 --- /dev/null +++ b/html/XCLIENT_README.html @@ -0,0 +1,267 @@ + + + + + + +Postfix XCLIENT Howto + + + + + + + +

Postfix XCLIENT Howto

+ +

Purpose of the XCLIENT extension to SMTP

+ +

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:

+ +

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.
+ +
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.
+ +
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.
+ +

+ +

XCLIENT Command syntax

+ +

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.

+ +

XCLIENT Server response

+ +

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.

+ +

XCLIENT server reply codes

+ +

+ + + + + + + + + + + + + + + + + +
Code Meaning
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
+ +

Code	Meaning
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

+ +

XCLIENT Example

+ +

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
+EHLO client.example.com
+250-server.example.com
+250-PIPELINING
+250-SIZE 10240000
+250-VRFY
+250-ETRN
+250-XCLIENT NAME ADDR PROTO HELO
+250 8BITMIME
+XCLIENT NAME=spike.porcupine.org ADDR=168.100.189.2
+220 server.example.com ESMTP Postfix
+EHLO spike.porcupine.org
+250-server.example.com
+250-PIPELINING
+250-SIZE 10240000
+250-VRFY
+250-ETRN
+250-XCLIENT NAME ADDR PROTO HELO
+250 8BITMIME
+MAIL FROM:<wietse@porcupine.org>
+250 Ok
+RCPT TO:<user@example.com>
+250 Ok
+DATA
+354 End data with <CR><LF>.<CR><LF>
+. . .message content. . .
+.
+250 Ok: queued as 763402AAE6
+QUIT
+221 Bye
+

+ +

Security

+ +

The XCLIENT command changes audit trails and/or SMTP client +access permissions. Use of this command must be restricted to +authorized SMTP clients.

+ +

SMTP connection caching

+ +

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.

+ +

References

+ +

Moore, K, "SMTP Service Extension for Delivery Status Notifications", +RFC 1891, January 1996.

+ + + + -- cgit v1.2.3