Internet Message Access Protocol (IMAP) - URLAUTH Extension
updated by
Extracted elements (26)
GENURLAUTH allows a server to return a tagged OK with a dummy generated key when an invalid userid is supplied, rather than always returning BAD, to prevent an attacker from using the command to enumerate valid userids on the server.
The authorization token is encoded as ASCII hexadecimal rather than BASE64 because BASE64 representations may have '=' padding characters, which would be problematic in a URL context.
The INTERNAL mechanism incorporates a means of identifying the token generation algorithm within the token so that if the algorithm must be changed (e.g., due to a discovered attack), the server can support a transition period validating tokens under either the old or new algorithm.
URLAUTH is conceptually a 'pawn ticket' that carries no authentication information and can be redeemed by whomever presents it (subject to access identifier restrictions). This design separates authorization from authentication, allowing scoped access delegation without sharing credentials.
URLAUTH overrides the second purpose of the userid in the IMAP URL (authentication requirement) defined in RFC 2192 (IMAPURL), replacing it with an authorization mechanism. The authimapurl grammar replaces the 'imapurl' and 'iserver' rules from RFC 2192 for URLAUTH-authorized URLs, making iuserauth mandatory.
During URLAUTH URL validation, removal of the ':<mech>:<token>' portion to produce the rump URL MUST be the only operation applied; URL percent escape decoding and case-folding (including to the domain part) MUST NOT occur.
The GENURLAUTH command MUST validate that the mailbox component refers to an existing mailbox, the server component contains a valid owner userid, and there is a valid access identifier; if checks fail the server MUST return a tagged BAD response, with an exception allowing a tagged OK with a dummy key when an invalid userid is supplied to prevent userid enumeration.
The mailbox access key MUST be unpredictable and SHOULD have at least 128 bits of entropy.
The URLFETCH command MUST return an untagged URLFETCH response and a tagged OK response to any syntactically valid URLFETCH command; a NO response indicates a server internal failure. The server MUST return NIL for URLs referring to an entire server, mailbox list, entire mailbox, or search results.
URLAUTH MUST be at the end of the URL and MUST NOT be used with any IMAP URL that refers to an entire IMAP server, a list of mailboxes, an entire IMAP mailbox, or IMAP search results.
When ';EXPIRE=<datetime>' is used, server implementations MUST reject the URL after that date and time has passed.
Four authorized access identifiers are defined: 'submit+<userid>' (limited to message submission entities acting on behalf of that userid), 'user+<userid>' (limited to sessions logged in as that specific userid), 'authuser' (any authenticated IMAP session), and 'anonymous' (any IMAP session including anonymous).
The GENURLAUTH command requests that the server generate URLAUTH-authorized URLs for one or more supplied URL/mechanism pairs. The server validates each URL for mailbox existence, valid owner userid, valid access identifier, and optionally uid/section validity, then returns the complete URLAUTH-authorized URLs in a GENURLAUTH response.
The INTERNAL authorization mechanism uses a server-chosen token generation algorithm (HMAC-SHA1 recommended at time of writing) and does not involve disclosure of the mailbox access key to the client. The server SHOULD incorporate a means of identifying the token generation algorithm within the token to allow future algorithm changes.
The mailbox access key is a per-user, per-mailbox random string with at least 128 bits of entropy, generated by software (not the human user). Two users sharing the same mailbox each have a different mailbox access key for that mailbox.
The RESETKEY command generates a new mailbox access key for a specified mailbox (revoking all existing URLAUTH URLs for that mailbox), or with no arguments removes all mailbox access keys for the user (revoking all URLAUTH URLs). The server returns a URLMECH status response code on success.
The URLFETCH command requests the server return message text data for one or more URLAUTH-authorized IMAP URLs. It executes with the access rights of the userid in the server component of the URL and does not require any mailbox to be selected, nor does it interfere with any selected mailbox.
The URLMECH status response code lists URL authorization mechanism names supported for a mailbox; it is returned in an untagged OK in response to RESETKEY, SELECT, or EXAMINE commands. Mechanisms other than INTERNAL may include BASE64-encoded mechanism-specific data appended after '='.
URL validation uses a 'rump URL' (the URLAUTH URL with the ':<mech>:<token>' suffix stripped). If the mailbox cannot be identified, the server calculates an authorization token using random 'plausible' keys before returning a validation failure, to prevent timing attacks on mailbox name existence.
URLAUTH is a component appended at the end of an IMAP URL that conveys authorization to access the addressed data. It contains an authorized access identifier, an authorization mechanism name, and an authorization token generated from the URL, the access identifier, the mechanism name, and a secret mailbox access key.
This document registers the 'URLAUTH' capability in the IANA imap4-capabilities registry and establishes the IMAP URLAUTH Authorization Mechanism Registry. New mechanisms must be registered via a standards-track or IESG-approved experimental RFC. The INTERNAL mechanism is the initial registered entry.
The 'authuser' access identifier should be used with caution as it permits any authorized IMAP user to access the URL. The 'anonymous' access identifier should be used with extreme caution as it permits anyone, and MUST NOT be assumed equivalent to 'authuser' even on servers that disallow anonymous access.
The URLMECH status response code may expose sensitive mechanism-specific data; a server MUST implement a configuration that suppresses URLMECH unless a session protection mechanism (TLS or SASL confidentiality layer) is active.
To protect against computational denial-of-service attacks, a server MAY impose progressively longer delays on multiple URL validation requests that fail. Timing attack prevention (using dummy key calculations for unrecognized mailboxes) is also required during URLAUTH validation.
The full URLAUTH URL grammar requires 'imap://' followed by enc-user, optional iauth, '@', hostport, '/', imessagepart, and iurlauth. The iurlauth component is composed as iurlauth-rump ':' mechanism ':' enc-urlauth, where enc-urlauth is at least 32 hex digits.
The URLAUTH URL extension takes the form ';URLAUTH=<access>:<mech>:<token>' where the authorization token is an ASCII-encoded hexadecimal string of at least 32 hex digits (128 bits). The optional expiry component takes the form ';EXPIRE=<datetime>' per RFC 3339.