external/ibm-public/postfix/dist/README_FILES/XFORWARD_README

   1 P\bPo\bos\bst\btf\bfi\bix\bx X\bXF\bFO\bOR\bRW\bWA\bAR\bRD\bD H\bHo\bow\bwt\bto\bo
   2
   3 -------------------------------------------------------------------------------
   4
   5 P\bPu\bur\brp\bpo\bos\bse\be o\bof\bf t\bth\bhe\be X\bXF\bFO\bOR\bRW\bWA\bAR\bRD\bD e\bex\bxt\bte\ben\bns\bsi\bio\bon\bn t\bto\bo S\bSM\bMT\bTP\bP
   6
   7 When an SMTP server announces support for the XFORWARD command, an SMTP client
   8 may send information that overrides one or more client-related logging
   9 attributes. The XFORWARD command targets the following problem:
  10
  11   * Logging after SMTP-based content filter. With the deployment of Internet-
  12     >MTA1->filter->MTA2 style content filter applications, the logging of
  13     client and message identifying information changes when MTA1 gives the mail
  14     to the content filter. To simplify the interpretation of MTA2 logging, it
  15     would help if MTA1 could forward remote client and/or message identifying
  16     information through the content filter to MTA2, so that the information
  17     could be logged as part of mail handling transactions.
  18
  19 This extension is implemented as a separate EMSTP command, and can be used to
  20 transmit client or message attributes incrementally. It is not implemented by
  21 passing additional parameters via the MAIL FROM command, because doing so would
  22 require extending the MAIL FROM command length limit by another 600 or more
  23 characters beyond the space that is already needed to support other extensions
  24 such as AUTH and DSN.
  25
  26 X\bXF\bFO\bOR\bRW\bWA\bAR\bRD\bD C\bCo\bom\bmm\bma\ban\bnd\bd s\bsy\byn\bnt\bta\bax\bx
  27
  28 An example of a client-server conversation is given at the end of this
  29 document.
  30
  31 In SMTP server EHLO replies, the keyword associated with this extension is
  32 XFORWARD. The keyword is followed by the names of the attributes that the
  33 XFORWARD implementation supports.
  34
  35 After receiving the server's announcement for XFORWARD support, the client may
  36 send XFORWARD requests at any time except in the middle of a mail delivery
  37 transaction (i.e. between MAIL and RSET or DOT). The command may be pipelined
  38 when the server supports ESMTP command pipelining.
  39
  40 The syntax of XFORWARD requests is described below. Upper case and quoted
  41 strings specify terminals, lowercase strings specify meta terminals, and SP is
  42 whitespace. Although command and attribute names are shown in upper case, they
  43 are in fact case insensitive.
  44
  45     xforward-command = XFORWARD 1*( SP attribute-name"="attribute-value )
  46
  47     attribute-name = ( NAME | ADDR | PORT | PROTO | HELO | SOURCE )
  48
  49     attribute-value = xtext
  50
  51   * Attribute values are xtext encoded as per RFC 1891.
  52
  53   * The NAME attribute specifies the up-stream hostname, or [UNAVAILABLE] when
  54     the information is unavailable. The hostname may be a non-DNS hostname.
  55
  56   * The ADDR attribute specifies the up-stream network address: a numerical
  57     IPv4 network address, an IPv6 address prefixed with IPV6:, or [UNAVAILABLE]
  58     when the address information is unavailable. Address information is not
  59     enclosed with [].
  60
  61   * The PORT attribute specifies an up-stream client TCP port number in
  62     decimal, or [UNAVAILABLE] when the information is unavailable.
  63
  64   * The PROTO attribute specifies the mail protocol for receiving mail from the
  65     up-stream host. This may be an SMTP or non-SMTP protocol name of up to 64
  66     characters, or [UNAVAILABLE] when the information is unavailable.
  67
  68   * The HELO attribute specifies the hostname that the up-stream host announced
  69     itself with (not necessarily via the SMTP HELO command), or [UNAVAILABLE]
  70     when the information is unavailable. The hostname may be a non-DNS
  71     hostname.
  72
  73   * The SOURCE attribute specifies LOCAL when the message was received from a
  74     source that is local with respect to the up-stream host (for example, the
  75     message originated from the up-stream host itself), REMOTE for all other
  76     mail, or [UNAVAILABLE] when the information is unavailable. The down-stream
  77     MTA may decide to enable features such as header munging or address
  78     qualification with mail from local sources but not other sources.
  79
  80 Note 1: an attribute-value element must not be longer than 255 characters
  81 (specific attributes may impose shorter lengths). After xtext decoding,
  82 attribute values must not contain control characters, non-ASCII characters,
  83 whitespace, or other characters that are special in message headers.
  84
  85 Note 2: DNS hostnames can be up to 255 characters long. The XFORWARD client
  86 implementation must not send XFORWARD commands that exceed the 512 character
  87 limit for SMTP commands.
  88
  89 Note 3: [UNAVAILABLE] may be specified in upper case, lower case or mixed case.
  90
  91 Note 4: Postfix implementations prior to version 2.3 do not xtext encode
  92 attribute values. Servers that wish to interoperate with these older
  93 implementations should be prepared to receive unencoded information.
  94
  95 X\bXF\bFO\bOR\bRW\bWA\bAR\bRD\bD S\bSe\ber\brv\bve\ber\br o\bop\bpe\ber\bra\bat\bti\bio\bon\bn
  96
  97 The server maintains a set of XFORWARD attributes with forwarded information,
  98 in addition the current SMTP session attributes. Normally, all XFORWARD
  99 attributes are in the undefined state, and the server uses the current SMTP
 100 session attributes for logging purposes.
 101
 102 Upon receipt of an initial XFORWARD command, the SMTP server initializes all
 103 XFORWARD attributes to [UNAVAILABLE]. With each valid XFORWARD command, the
 104 server updates XFORWARD attributes with the specified values.
 105
 106 The server must not mix client attributes from XFORWARD with client attributes
 107 from the current SMTP session.
 108
 109 At the end of each MAIL FROM transaction (i.e. RSET or DOT), the server resets
 110 all XFORWARD attributes to the undefined state, and is ready to receive another
 111 initial XFORWARD command.
 112
 113 X\bXF\bFO\bOR\bRW\bWA\bAR\bRD\bD S\bSe\ber\brv\bve\ber\br r\bre\bep\bpl\bly\by c\bco\bod\bde\bes\bs
 114
 115      _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b
 116     |C\bCo\bod\bde\be|M\bMe\bea\ban\bni\bin\bng\bg                         |
 117     |_\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b |
 118     |250 |success                         |
 119     |_\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b |
 120     |421 |unable to proceed, disconnecting|
 121     |_\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b |
 122     |501 |bad command parameter syntax    |
 123     |_\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b |
 124     |503 |mail transaction in progress    |
 125     |_\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b |
 126     |550 |insufficient authorization      |
 127     |_\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b |
 128
 129 X\bXF\bFO\bOR\bRW\bWA\bAR\bRD\bD E\bEx\bxa\bam\bmp\bpl\ble\be
 130
 131 In the following example, information sent by the client is shown in bold font.
 132
 133     220 server.example.com ESMTP Postfix
 134     E\bEH\bHL\bLO\bO c\bcl\bli\bie\ben\bnt\bt.\b.e\bex\bxa\bam\bmp\bpl\ble\be.\b.c\bco\bom\bm
 135     250-server.example.com
 136     250-PIPELINING
 137     250-SIZE 10240000
 138     250-VRFY
 139     250-ETRN
 140     250-XFORWARD NAME ADDR PROTO HELO
 141     250 8BITMIME
 142     X\bXF\bFO\bOR\bRW\bWA\bAR\bRD\bD N\bNA\bAM\bME\bE=\b=s\bsp\bpi\bik\bke\be.\b.p\bpo\bor\brc\bcu\bup\bpi\bin\bne\be.\b.o\bor\brg\bg A\bAD\bDD\bDR\bR=\b=1\b16\b68\b8.\b.1\b10\b00\b0.\b.1\b18\b89\b9.\b.2\b2 P\bPR\bRO\bOT\bTO\bO=\b=E\bES\bSM\bMT\bTP\bP
 143     250 Ok
 144     X\bXF\bFO\bOR\bRW\bWA\bAR\bRD\bD H\bHE\bEL\bLO\bO=\b=s\bsp\bpi\bik\bke\be.\b.p\bpo\bor\brc\bcu\bup\bpi\bin\bne\be.\b.o\bor\brg\bg
 145     250 Ok
 146     M\bMA\bAI\bIL\bL F\bFR\bRO\bOM\bM:\b:<\b<w\bwi\bie\bet\bts\bse\be@\b@p\bpo\bor\brc\bcu\bup\bpi\bin\bne\be.\b.o\bor\brg\bg>\b>
 147     250 Ok
 148     R\bRC\bCP\bPT\bT T\bTO\bO:\b:<\b<u\bus\bse\ber\br@\b@e\bex\bxa\bam\bmp\bpl\ble\be.\b.c\bco\bom\bm>\b>
 149     250 Ok
 150     D\bDA\bAT\bTA\bA
 151     354 End data with <CR><LF>.<CR><LF>
 152     .\b. .\b. .\b.m\bme\bes\bss\bsa\bag\bge\be c\bco\bon\bnt\bte\ben\bnt\bt.\b. .\b. .\b.
 153     .\b.
 154     250 Ok: queued as 3CF6B2AAE8
 155     Q\bQU\bUI\bIT\bT
 156     221 Bye
 157
 158 S\bSe\bec\bcu\bur\bri\bit\bty\by
 159
 160 The XFORWARD command changes audit trails. Use of this command must be
 161 restricted to authorized clients.
 162
 163 S\bSM\bMT\bTP\bP c\bco\bon\bnn\bne\bec\bct\bti\bio\bon\bn c\bca\bac\bch\bhi\bin\bng\bg
 164
 165 SMTP connection caching makes it possible to deliver multiple messages within
 166 the same SMTP session. The XFORWARD attributes are reset after the MAIL FROM
 167 transaction completes (after RSET or DOT), so there is no risk of information
 168 leakage.
 169
 170 R\bRe\bef\bfe\ber\bre\ben\bnc\bce\bes\bs
 171
 172 Moore, K, "SMTP Service Extension for Delivery Status Notifications", RFC 1891,
 173 January 1996.
 174