BURL_ACCESS mapping table

From Messaging Server Technical Reference Wiki
Jump to: navigation, search



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 BURL_ACCESS mapping table, discussed below, and the MTA options imap_username and imap_password.

For the BURL extension to be made available, a BURL_ACCESS 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 submit 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 BURL_ACCESS mapping table controls, via two different probe strings, first whether the BURL extension is advertised, and then second, whether a client's BURL command is accepted. The first probe is performed before responding to an EHLO command. It has the form:

port_access-probe-info|channel|authentication-identity| 

Here port_access-probe-info consists of all the information usually included in a PORT_ACCESS mapping table probe. It will be blank if BURL is being used in a "disconnected" context such as batch SMTP. channel is the current source channel. authentication-identity is the user's canonical authenticated login identity, normally uid@canonical-domain (that is, the user's LDAP uid attribute value, an at sign, and the canonical domain name in which the user's entry resides as found during domain lookup). authentication-identity will be blank if no authentication has been performed. The "A" input flag will be set if SASL authentication has been performed, and the "T" input flag will be set if TLS is in use; thus the mapping templates may test using $:A and $:T, respectively. In order to offer BURL support, the mapping output for this first probe must set $Y; it may also optionally provide a space-separated list of supported URL types. imap 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 client-url field the URL specified in the client's BURL command:

port_access-probe-info|channel|authentication-identity|client-url

where client-url 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 client-url 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 client-url, 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) BURL_ACCESS probe, as in the prior (advertise BURL) probe, the "A" input flag will be set if SASL authentication has been performed, and the "T" input flag will be set if TLS is in use; thus the mapping templates may test using $:A and $:T, 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 mapping_paranoia MTA option , if set, will cause any vertical bar within the client'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 $Y for the URL to be accepted for processing. If $D is also set, then the string result of the mapping replaces the client's entire originally specified URL. New in 7.4-18.01, if $M is set, then the IMAP host name in the client's original URL will be replaced by the mailHost of the currently authenticated user; this tends to provide both better security (by enforcing that BURL connections will only be made to a site's own mailHost host(s)), and better performance (by more likely connecting to the "correct" host), than relying on the IMAP host name supplied by the user's client. See Table of BURL_ACCESS mapping flags for a summary of these available flags and tests.

BURL_ACCESS mapping flags
Flag Description
$Yurl-types For the initial (EHLO) probe, enable advertising BURL support, optionally providing via the string argument url-types a space-separated list of the URL types to advertise.
$Nstring For the later (BURL command) probes, reject access. If the optional string is supplied, use it as the (entire) SMTP rejection, including SMTP error code and extended code as well as text. If no such string is supplied, then the default SMTP error used for such rejections is

533 5.7.1 Access denied to specified URL.®
$I (New in 7.4-18.01) For the later (BURL command) probes, if specified in an entry with $N rejecting that BURL command, the $I means further to forcibly disconnect the session with disconnect reason text "BURL_ACCESS forced disconnect".®
$Y For the later (BURL command) probes, a plain $Y flag allows the BURL command.
$Dnew-url For the later (BURL command) probes, if $Y was also specified (allowing access), then use the specified new-url instead of the URL that the SMTP SUBMIT client provided.®
$M (New in 7.4-18.01) For the later (BURL command) probes that succeed, in the actual BURL command override the IMAP host name in the client-provided URL and instead connect to the host of the mailHost attribute of the currently authenticated user. The BURL command probe itself will be considered to fail if the currently authenticated user has no mailHost attribute set.®
$T (New in Messaging Server 7.0.5) For the later (BURL command) probes that succeed, force TLS use for opening the BURL URL (force TLS use in the connection to fetch the part specified in the client's BURL URL).®
$X (New in Messaging Server 7.0.5) For the later (BURL command) probes that succeed, forcibly disable TLS use for opening the BURL URL (force non-use of TLS in the connection to fetch the part specified in the client's BURL URL).®
Flag comparisons Description
$:| Match only if the original client URL included the vertical bar character, |®
$;| Match only if the original client URL included no vertical bar character, |®
$:A Match only if SASL (SMTP AUTH) was used.
$;A Match only if SASL (SMTP AUTH) was not used.
$:T Match only if TLS was used.
$;T Match only if TLS was not used.

®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's BURL_ACCESS mapping table should be configured to verify that a proper type of URL has been specified: typically only imap: 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 uid 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 BURL_ACCESS mapping table, this means to start with an entry that enables advertising BURL only if the authentication-identity field in the initial probe is non-empty. Additionally, it is almost always essential to restrict message fetching access via a BURL command's imap: URL to an appropriate set of IMAP servers. As of 7.4-18.01, use of the $M flag in the mapping template (right hand side) is a simple way to enforce that only users' own mailHost values are used as the IMAP server in the eventually executed BURL command. Prior to 7.4-18.01, the BURL_ACCESS mapping table should typically be setup up to explicitly look for (match) a list of known, internal IMAP servers (users' valid mailHost values) and only allow BURL commands using those IMAP server host names.

Thus as of 7.4-18.01, a minimal BURL_ACCESS mapping table might be something like (and initial configuration will generate):


BURL_ACCESS 
 
! Initial entry to allow advertising BURL in EHLO response 
   *|tcp_*|%*|                                imap$Y 
! Allow BURL commands, connecting to user's own mailHost 
   *|*@*|imap://*;URLAUTH=submit+$1*:*        $: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 
   *|tcp_*|%*|                                 imap$Y 
! Allow BURL commands, connecting to (default domain) user's own mailHost 
   *|*@*|imap://*;URLAUTH=submit+$1*:*         $:A$M$Y 
! Allow BURL commands, connecting to (hosted domain) user's own mailHost 
   *|*@*|imap://*;URLAUTH=submit+$1*%40$2*:*   $:A$M$Y 

A better minimal BURL_ACCESS 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 
   *|tcp_*|%*|                                 $:T$Yimap 
! Allow BURL commands, connecting to (default domain) user's own mailHost 
   *|*@*|imap://*;URLAUTH=submit+$1*:*         $:A$:T$M$Y 
! Allow BURL commands, connecting to (hosted domain) user's own mailHost 
   *|*@*|imap://*;URLAUTH=submit+$1*%40$2*:*   $:A$:T$M$Y 

In versions prior to 7.4-18.01, a minimal BURL_ACCESS mapping table would be more verbose. For instance, the following makes use of a subsidiary X-IMAP-HOSTS mapping table to list a site'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 
  *|tcp_*|%*|                                    imap$Y 
! Allow BURL commands that request connecting to one of the "known" IMAP hosts 
! listed in the X-IMAP-HOSTS mapping table 
  *|*@*|imap://*@*/*;URLAUTH=submit+$1*:*        $C$:A$|X-IMAP-HOSTS;$4|$Y$E 
! Ditto for users in hosted domains 
  *|*@*|imap://*@*/*;URLAUTH=submit+$1*%40$2*:*  $C$:A$|X-IMAP-HOSTS;$4|$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 imap_username and imap_password MTA options are used to accomplish this. imap_username specifies the submit user and defaults to the setting of the submituser IMAP option (in legacy configuration, the service.imap.submituser configutil option) if not specified. imap_password specifies the password which of course must match the value set for the submit user account. The imap_password 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'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 chunking* 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 nochunking* channel options), the MTA'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 disconnectbadburllimit 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: