BURL ACCESS mapping table

As of Messaging Server 7.0, the MTA supports the BURL extension to SMTP SUBMIT, defined in RFC 4468 (Message Submission BURL Extension), and the  Message Store IMAP server supports RFC 4467 (IMAP - URLAUTH Extension). BURL permits an email client to refer, in submitted messages, to content to be retrieved (using the IMAP URLAUTH extension) from an IMAP  server. This allows email clients to submit messages including content without having to first download that content to the client and then  upload (submit it) directly to the SMTP SUBMIT server itself: to  include content by supplying a URL reference (including an  authentication token allowing access) to the location of the content on  an IMAP server. Availability of the BURL extension is controlled by the   mapping table, discussed below, and the  MTA options   and.

For the BURL extension to be made available, a  mapping  table must be defined. Note that BURL is specifically an SMTP SUBMIT  feature; in terms of MTA configuration, only channel(s) marked with the    channel option are capable of  offering BURL support.

Technical note:A client BURL command to an SMTP SUBMIT server for which BURL has not been enabled will be rejected with the error: 503 5.5.1 BURL has not been enabled. BURL is only supported (may only be enabled) on SMTP SUBMIT channels; a client BURL command to an LMTP server will be rejected with the error: 503 5.5.0 BURL illegal on LMTP port. while a client BURL command to an SMTP (non-SUBMIT) server will be rejected with the error: 503 5.5.1 BURL only allowed on submission port. The  mapping table controls, via two different probe  strings, first whether the BURL extension is advertised, and then  second, whether a client&#x27;s BURL command is accepted. The first probe is performed before responding to an EHLO command. It has the form: port_access-probe-info&#x7c;channel&#x7c;authentication-identity&#x7c; Here  consists of all the  information usually included in a    mapping table probe. It will be blank if BURL is being used in a "disconnected" context such  as batch SMTP. is the current source channel. is the user&#x27;s canonical authenticated login identity, normally    (that is, the  user&#x27;s LDAP   attribute value, an at sign, and the  canonical domain name in which the user&#x27;s entry resides as found during  domain lookup). will be blank if no authentication has been performed. The " " input flag will be set if SASL  authentication has been performed, and the " "  input flag will be set if TLS is in use; thus the mapping templates may  test using   and , respectively. In order to offer BURL support, the mapping output for this first probe  must set  ; it may also optionally provide a  space-separated list of supported URL types. is assumed if no explicit string is returned.

The second probe is performed when a BURL command is actually sent by the SUBMIT client and received by the SMTP SUBMIT server. In addition to the prior fields (described above), this second probe also includes  as a final   field the URL specified in  the client&#x27;s BURL command: port_access-probe-info&#x7c;channel&#x7c;authentication-identity&#x7c;client-url where  would normally be in URLAUTH  syntax as defined in RFC 4467 (IMAP - URLAUTH Extension). See RFC 4467 for details on URLAUTH syntax, but for a rough idea to better understand the remainder of this discussion, consider that for BURL  "submit user" access, the    will usually take a form along the lines of: imap://enc-user@hostport/optional-expire-clause;URLAUTH=submit+enc-user:mechanism:token (Other types of access in a URLAUTH and hence other forms of , such as for "anonymous"  access, are possible, but their use is more questionable---see the  "Security Considerations" section of RFC 4468 -- and  therefore the remainder of this discussion will focus on enabling only  "submit user" access.)

In this second (actual BURL command)  probe,  as in the prior  (advertise BURL) probe, the " " input flag will  be set if SASL authentication has been performed, and the  " " input flag will be set if TLS is in use;  thus the mapping templates may test using   and  , respectively.

Additionally, for this second (actual received BURL command) probe, the vertical bar flag, , will be set if the original URL sent  by the client contained any vertical bars (which if present could  possibly confuse some sorts of access checks), and thus the mapping  entry template may test for vertical bars in the original client URL  using the   test; note that the    MTA option , if set,  will cause any vertical bar within the client&#x27;s original URL to be  replaced in the probe by the specified alternate character (with the  vertical bar input flag still being set). The mapping must set   for the URL to be accepted for processing. If   is also set, then the string result of the mapping  replaces the client&#x27;s entire originally specified URL. New in 7.4-18.01, if   is set, then the IMAP host name in the client&#x27;s  original URL will be replaced by the   of the  currently authenticated user; this tends to provide both better  security (by enforcing that BURL connections will only be made to a  site&#x27;s own   host(s)), and better performance (by  more likely connecting to the "correct" host), than relying  on the IMAP host name supplied by the user&#x27;s client. See Table of BURL_ACCESS mapping flags  for a summary of these available flags and tests.

®Available for the later (BURL command containing a URL) probes only; not available for the initial probe on whether or not to offer  the BURL extension

At an absolute minimum, a site&#x27;s  mapping table should be  configured to verify that a proper type of URL has been specified:  typically only   URLs should be allowed. Additionally, in the case of IMAP URLs used in SMTP SUBMIT message submission, a  check ought to be made to insure that the URL "belongs" to  the user: that is, that the access user in the URL matches the  authenticated   for the SUBMIT session. Indeed, typically sites will not even want to advertise BURL in the SMTP SUBMIT  server response unless and until the client has authenticated---in  terms of the   mapping table,  this means to start with an  entry that enables advertising BURL only if the    field in the initial  probe is non-empty. Additionally, it is almost always essential to restrict message fetching access via a BURL command&#x27;s   URL  to an  appropriate set of IMAP servers. As of 7.4-18.01, use of the   flag in the mapping template (right hand side) is a  simple way to enforce that only users&#x27; own   values  are used as the IMAP server in the eventually executed BURL command. Prior to 7.4-18.01, the  mapping table should  typically be  setup up to explicitly look for (match) a list of known, internal IMAP  servers (users&#x27; valid   values) and only allow BURL  commands using those IMAP server host names.

Thus as of 7.4-18.01, a minimal  mapping table might be  something like (and initial configuration will generate): BURL_ACCESS ! Initial entry to allow advertising BURL in EHLO response &#x2a;&#x7c;tcp_&#x2a;&#x7c;%&#x2a;&#x7c;                               imap$Y ! Allow BURL commands, connecting to user&#x27;s own mailHost &#x2a;&#x7c;&#x2a;@&#x2a;&#x7c;imap://&#x2a;;URLAUTH=submit+$1&#x2a;:&#x2a;       $:A$M$Y Or if hosted domains are in use, then include an additional entry to match the hosted domain user use: BURL_ACCESS ! Initial entry to allow advertising BURL in EHLO response &#x2a;&#x7c;tcp_&#x2a;&#x7c;%&#x2a;&#x7c;                                imap$Y ! Allow BURL commands, connecting to (default domain) user&#x27;s own mailHost &#x2a;&#x7c;&#x2a;@&#x2a;&#x7c;imap://&#x2a;;URLAUTH=submit+$1&#x2a;:&#x2a;        $:A$M$Y ! Allow BURL commands, connecting to (hosted domain) user&#x27;s own mailHost &#x2a;&#x7c;&#x2a;@&#x2a;&#x7c;imap://&#x2a;;URLAUTH=submit+$1&#x2a;%40$2&#x2a;:&#x2a;  $:A$M$Y A better minimal  mapping table, implementing the  recommended security provisions of RFC 4468 (that is, also requiring  TLS encryption as well as SMTP AUTH authentication in order to allow  BURL), would be (as of the 7.4-18.01 version): BURL_ACCESS ! Initial entry to allow advertising BURL in EHLO response, if TLS was used &#x2a;&#x7c;tcp_&#x2a;&#x7c;%&#x2a;&#x7c;                                $:T$Yimap ! Allow BURL commands, connecting to (default domain) user&#x27;s own mailHost &#x2a;&#x7c;&#x2a;@&#x2a;&#x7c;imap://&#x2a;;URLAUTH=submit+$1&#x2a;:&#x2a;        $:A$:T$M$Y ! Allow BURL commands, connecting to (hosted domain) user&#x27;s own mailHost &#x2a;&#x7c;&#x2a;@&#x2a;&#x7c;imap://&#x2a;;URLAUTH=submit+$1&#x2a;%40$2&#x2a;:&#x2a;  $:A$:T$M$Y In versions prior to 7.4-18.01, a minimal   mapping table  would be more verbose. For instance, the following makes use of a subsidiary X-IMAP-HOSTS mapping table to list a site&#x27;s valid IMAP  server host names. X-IMAP-HOSTS mail1.example.com         $Y mail2.example.com         $Y mail3.example.com         $Y BURL_ACCESS ! Initial entry to allow advertising BURL in EHLO response &#x2a;&#x7c;tcp_&#x2a;&#x7c;%&#x2a;&#x7c;                                   imap$Y ! Allow BURL commands that request connecting to one of the "known" IMAP hosts ! listed in the X-IMAP-HOSTS mapping table &#x2a;&#x7c;&#x2a;@&#x2a;&#x7c;imap://&#x2a;@&#x2a;/&#x2a;;URLAUTH=submit+$1&#x2a;:&#x2a;       $C$:A$&#x7c;X-IMAP-HOSTS;$4&#x7c;$Y$E ! Ditto for users in hosted domains &#x2a;&#x7c;&#x2a;@&#x2a;&#x7c;imap://&#x2a;@&#x2a;/&#x2a;;URLAUTH=submit+$1&#x2a;%40$2&#x2a;:&#x2a; $C$:A$&#x7c;X-IMAP-HOSTS;$4&#x7c;$Y$E Once the SMTP SUBMIT server has checked that BURL use should be allowed in a particular context, then in order to perform the IMAP URLAUTH  operation specified in a BURL command, the SMTP SUBMIT server has to  have the ability to log in to the IMAP server as the submit user. The   and    MTA options are used to accomplish this. specifies the submit user and defaults to the setting of the   IMAP option (in legacy configuration, the    configutil option) if not  specified. specifies the password which of course must match the value set for the submit user account. The   option has no default value.

Technical note:Once logged in as the submit user, then the BURL check of the hashed  authentication token in the URLAUTH is performed: only messages  accessible to the user issuing the BURL command will be fetched. That is, the submit user logs in, but it is not the submit user&#x27;s message  access that determines whether a message or message part can be fetched  and incorporated but rather the access of the original user is  validated from the URLAUTH.

When using BURL to fetch an entire, pre-composed message, a BURL command replaces the usual DATA command in an SMTP dialogue. Alternatively, when the SMTP extension CHUNKING is supported (see RFC 3030 and the  channel options), then  BURL and BDAT commands may be  interlaced---meaning that a new message may be composed incorporating  material (for instance, attachments) fetched via BURL commands. Unless explicitly disabled  (see   channel options),  the MTA&#x27;s TCP/IP channels  (and in particular its SMTP SUBMIT servers) by default support CHUNKING.

Note that new in 7.4-18.01, the MTA has a feature to force disconnection of the SMTP SUBMIT session if a user attempts "too many" bad  (failed) BURL commands: see the    channel option.

Note that as regards MTA message transaction logging, a message submitted using BURL will include a "U" modifier on its  "E" enqueue record, or include "UC" if both BURL  and CHUNKING were used; see  MTA transaction log entry format.

See also:
 * BURL MTA options
 * submit Option
 * PORT_ACCESS mapping table
 * mapping_paranoia MTA Option
 * MTA transaction log entry format
 * disconnectbadburllimit Option
 * chunkingserver Option
 * SMTP SUBMIT servers