Network Working Group M. Crispin
INTERNET-DRAFT: IMAP URLAUTH University of Washington
C. Newman
Sun Microsystems
January 2004
Document: internet-drafts/draft-crispin-imap-urlauth-05.txt
Internet Message Access Protocol (IMAP) - URLAUTH Extension
Status of this Memo
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC 2026.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as
Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt
To view the list Internet-Draft Shadow Directories, see
http://www.ietf.org/shadow.html.
A revised version of this document will be submitted to the RFC
editor as an Informational Document for the Internet Community.
A revised version of this draft document will be submitted to the RFC
editor as a Proposed Standard for the Internet Community. Discussion
and suggestions for improvement are requested, and should be sent to
lemonade@IETF.ORG. This document will expire before 5 July 2004.
Distribution of this memo is unlimited.
Abstract
This document describes the URLAUTH extension to the Internet
Message Access Protocol (IMAP) (RFC 3501) and the IMAP URL Scheme
(IMAPURL) (RFC 2192). This extension provides a means by which an
IMAP client can create "signed" URLs carrying authorization to
access limited message data on the IMAP server.
An IMAP server which supports this extension indicates this with a
capability name of "URLAUTH".
Conventions Used in this Document
The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY"
in this document are to be interpreted as defined in [KEYWORDS].
The formal syntax use the Augmented Backus-Naur Form (ABNF)
notation including the core rules defined in Appendix A of [ABNF].
In examples, "C:" and "S:" indicate lines sent by the client and
server respectively. If a single "C:" or "S:" label applies to
multiple lines, then the line breaks between those lines are for
editorial clarity only and are not part of the actual protocol
exchange.
Introduction
In [IMAPURL], a URL of the form imap://fred@example.com/INBOX;uid=20
requires authorization as userid "fred".
The URLAUTH extension provides a means by which an authorized
user of an IMAP server can create signed IMAP URLs. A signed URL
conveys authorization (not authentication) to its data, and can be
used in another IMAP session to access specific content on the IMAP
server without otherwise providing authorization to any other data
owned by the signing user (including other data in the mailbox
specified in the URL).
A signed URL can be used in the argument to the BURL command in
message composition, as described in [COMPOSE], for such purposes
as a small client submitting a message forward or resend from an IMAP
mailbox without requiring the client to fetch that message data.
URLs are signed using an authentication signature mechanism name and
an authentication signature, which was generated using a secret mailbox
access generation key. An IMAP client client can request the server to
generate and assign a new mailbox access generation key (thus effectively
revoking all current URLs using URLAUTH with that mailbox access
generation key) but can not set it to a key of its own choosing.
[Should the key should be per-user or per-mailbox? Per-user would reduce
the number of keys needed and simplify the security model. It would also
require that the issuer's userid be before the "@" in the URL; bug or
feature? If this is done, MAILBOXKEY should be changed to something
else, and the stuff about it being returned at SELECT time should be
changed to "after authentication."]
IMAP URL Extensions
[IMAPURL] is extended by allowing the addition of ";AUTHID=<userid>",
";AUTHROLE=<role>", ";EXPIRE=<datetime>", and ";URLAUTH=<authsig>" to
the end of IMAP URLs which refer to specific message or message parts.
";URLAUTH=<authsig>" must be at the end of the URL, but otherwise the
order of these extensions does not matter.
This facility does not apply to any IMAP URL which returns to an
entire IMAP server, list of mailboxes, an entire IMAP mailbox, or
IMAP search results.
The ";AUTHID=<userid>" and ";AUTHROLE=<role>" specify which userids
are allowed the user of the signed URL. A signed URL MUST have one
or the other, but not both; nor may it have more than one.
When ";AUTHID=<userid>" is used, this specifies that use of this URL is
limited to IMAP sessions which are logged in as the specified userid
(that is, have authorization identity as that userid). If
";AUTHID=<userid>" is not used, then ";AUTHROLE=<role>" must be specified.
When ";AUTHROLE=<role>" is used, this indicates that only a userid
authorized to act in the given role is permitted to use this URL. The
currently defined roles are "compose" (a message composition entity),
"submit" (a message submission entity), "authuser" (any authorized user
of the IMAP server), and "anonymous" (anyone, including anonymous users
and authorized users of the IMAP server). If ";AUTHROLE=<role>" is not
used, then ";AUTHID=<userid>" must be specified.
When ";EXPIRE=<datetime>" is used, this indicates the latest date and
time that the URL is valid. After that date and time, the URL has
expired and server implementations MUST reject the URL. If
";EXPIRE=<datetime>" is not used, the URL has no expiration, but still
can be revoked as discussed below.
When ";URLAUTH=<authsig>" is used, this indicates a authentication
signature mechanism name and a 128-bit authentication signature,
represented as an ASCII-encoded hexadecimal string, which is used to
authorize the URL. The calculation of the authentication signature
depends upon the mechanism used.
Discussion on URLAUTH Authorization Issues
In [IMAPURL], the userid before the "@" in the URL has two purposes:
1) It provides context for user-specific mailbox paths such
as "INBOX".
2) It specifies that resolution of the URL requires logging in as
that user and limits use of that URL to only that user.
An obvious limitation of using the same field for both purposes is that
the URL can only be resolved by the mailbox owner.
URLAUTH overrides the second purpose of the userid in the IMAP URL and
by default permits the URL to be resolved by any user permitted by the
";AUTHID=<userid>" and ";AUTHROLE=<role>" specifiers.
The ";AUTHID=<userid>" option limits resolution of that URL to a
particular userid, whereas the ";AUTHROLE=<role>" option is more
general and simply requires the session be authorized by a user that
has been granted a special role within the authentication system.
Generation of Signed URLs
A signed URL is generated as follows.
An initial URL is built with no ";URLAUTH=<authsig>" field. An
authentication signature mechanism (such as the HMAC-MD5 mechansim
described below) is selected and used to calculate the authentication
signature, with the initial URL as the data and a secret known to the
IMAP server as the key. The signed URL is created by taking the
initial URL and appending ";URLAUTH=" followed by the authentication
signature mechanism name, a ":", and the ASCII-encoded hexadecimal
representation of the authentication signature.
Note: the reason why ASCII-encoded hexadecimal is used instead of
BASE64 is that the BASE64 representation may have "=" padding
characters which would be problematic in a URL.
Validation of Signed URLs
A signed URL is validated as follows.
The ";URLAUTH=<authsig>" portion of the URL is extracted, and the
<authsig> value split and saved as the signature mechanism and the
authentication signature. The remainder of the URL minus the
";URLAUTH=<authsig>" (the "rump URL") is analyzed to identify the
mailbox.
If the mailbox can not be identified, a signature is calculated
on the rump URL, using random "plausible" keys (selected by the server)
as needed, before returning a validation failure. This prevents timing
attacks aimed at identifying mailbox names.
If the mailbox can be identified, the signature is calculated on the
rump URL and the mailbox access generation key using the signature
mechanism. Validation is successful if, and only if, the calculated
signature matches the authentication signature supplied in
";URLAUTH=<authsig>".
Note: removal of the ";URLAUTH=<authsig>" portion of the URL is
the only operation applied to the signed URL to get the rump URL.
In particular, URL percent escape decoding and case-folding MUST
NOT occur.
HMAC-MD5 Authentication Signature Mechanism
The HMAC-MD5 authentication signature mechanism is defined here.
The HMAC-MD5 mechanism permits the client to generate signed URLs
without requiring the SIGNURL command, at the cost of requiring that
the server disclose the mailbox access generation key used to sign the
URL to the client.
The authentication signature is calculated as an [HMAC-MD5] checksum,
using the initial URL (the URL with no ";URLAUTH=<authsig>" field) as
the data and the mailbox access generation key as the key.
INTERNAL Authentication Signature Mechanism
The INTERNAL authentication signature mechanism is defined here.
The INTERNAL mechanism uses a mailbox access generation key that is not
disclosed to the client and an implementation-specific signature
generation algorithm. The mailbox access generation key used by the
INTERNAL mechanism can be changed with the CHANGEKEY command, but the
new key MUST NOT be disclosed
6.3.CHANGEKEY. CHANGEKEY Command
Arguments: mailbox name
optional mechanism name
Responses: none other than in result
Result: OK - changekey completed, new key in MAILBOXKEY status
response code
NO - changekey error: can't change key of that mailbox
BAD - command unknown or arguments invalid
The CHANGEKEY command requests the server to generate a new mailbox
access generation key for the given mailbox and mechanism. This will
either change an mailbox access generation key for the mailbox, or
establish a new one.
A successful CHANGEKEY with an authentication signature mechanism
that permits client key generation (such as HMAC-MD5) will return a
MAILBOXKEY status response code in the tagged OK result.
Any current IMAP session which has the mailbox selected will also
receive an untagged OK response with the MAILBOXKEY status response
code.
If the [ACL] or [ACL2] extension is present, the user must have "a"
(administrative) rights to the mailbox in order to perform a CHANGEKEY.
CHANGEKEY has the effect of revoking all current signed URLs on that
mailbox using that mechanism.
If the mechanism name is not provided, all keys are deleted and all
current signed URLs on that mailbox for all mechanisms are revoked.
Example:
C: a31 CHANGEKEY INBOX
S: a31 OK All mailbox keys revoked
C: a32 CHANGEKEY INBOX HMAC-MD5
S: a32 OK [MAILBOXKEY AUTH-MD5 P34OKhO7VEkCbsiYY8rGEg==] New key set
C: a33 CHANGEKEY INBOX INTERNAL
S: a33 OK New key set internally
6.3.SIGNURL. SIGNURL Command
Argument: one or more URL/mechanism pairs
Responses: untagged responses: SIGNURL
Result: OK - signurl completed
NO - signurl error: can't sign a URL
BAD - command unknown or arguments invalid
The SIGNURL command requests the server to generate a URLAUTH signed
URL for each of the given URLs using the given signing mechanism.
If the command is successful, a SIGNURL response code is returned
listing the requested URLs as signed URLs.
Example:
Note that lines which do not begin with "C:" or "S:" are
continuations of the previous line for typographical clarity and
are not separate lines in the protocol.
C: a777 SIGNURL "imap://joe@example.com/INBOX;uid=20;section=1.2
;authid=fred" HMAC-MD5
S: * SIGNURL "imap://joe@example.com/INBOX;uid=20;section=1.2
;authid=fred;urlauth=hmac-md5:91354a473744909de610943775f92038" {28}
S: Si vis pacem, para bellum.
S: a777 OK SIGNURL completed
6.3.URLFETCH. URLFETCH Command
Arguments: one or more URLs
Responses: untagged responses: URLFETCH
Result: OK - urlfetch completed
NO - urlfetch failed due to server internal error
BAD - command unknown or arguments invalid
The URLFETCH command requests that the server return the text data
associated with one or more IMAP URLs, as described in [IMAPURL]
and extended by this document. The data is returned for all
validated URLs, regardless of whether or not the session would
otherwise be able to access the mailbox containing that data via
SELECT or examine.
Note: This command does not require that the URL refer to the
selected mailbox; nor does it require that any mailbox be
selected. It does not in any way interfere with any selected
mailbox either.
The URLFETCH command MUST return an untagged URLFETCH response and
a tagged OK response to any URLFETCH command that is syntactically
valid. A NO response indicates a server internal failure which may
be resolved on later retry.
Note: the possibility of a NO response is to accommodate
implementations which would otherwise have to issue an
untagged BYE with a fatal error due to an inability to
respond to a valid request. In an ideal world, a server
SHOULD NOT issue a NO response.
The server MUST return NIL for any IMAP URL which returns to an
entire IMAP server, list of mailboxes, an entire IMAP mailbox, or
IMAP search results.
Example
Note that lines which do not begin with "C:" or "S:" are
continuations of the previous line for typographical clarity and
are not separate lines in the protocol. For clarity, this example
uses the LOGIN command which SHOULD NOT be used over a non-encrypted
communication path.
S: * OK [CAPABILITY IMAP4REV1 URLAUTH] example.com IMAP server ready
C: a001 LOGIN fred secret
S: a001 OK fred logged in
C: a002 URLFETCH "imap://joe@example.com/INBOX;uid=20;section=1.2
;authid=fred;urlauth=hmac-md5:91354a473744909de610943775f92038"
S: * URLFETCH "imap://joe@example.com/INBOX;uid=20;section=1.2
;authid=fred;urlauth=hmac-md5:91354a473744909de610943775f92038" {28}
S: Si vis pacem, para bellum.
S:
S: a002 OK URLFETCH completed
7.1.MAILBOXKEY. MAILBOXKEY Status Response Code
The MAILBOXKEY status response code is followed by a authentication
signature mechanism name and the BASE64 encoded form of the mailbox
access generation key to be used with this mechanism. This status
response code is returned in an untagged OK response in response to
a CHANGEKEY, SELECT, or EXAMINE command.
7.4.URLFETCH. URLFETCH Response
Contents: one or more URL/nstring pairs
The URLFETCH response returns the message text data associated with one or
more IMAP URLs, as described in [IMAPURL] and extended by this document.
This response occurs as the result of a URLFETCH command.
The returned data string is NIL if the URL is invalid for any reason
(including validation failure). If the URL is valid, but the IMAP
fetch of the body part returned NIL (this should not happen), the
returned data string should be the empty string ("") and not NIL.
Formal Syntax
The following syntax specification uses the Augmented Backus-Naur
Form (ABNF) notation as specified in [ABNF].
The following modifications are made to the Formal Syntax in [IMAP]:
changekey = "CHANGEKEY" SP mailbox [SP mechansim]
command-auth =/ urlfetch
mechanism = "HMAC-MD5" / "INTERNAL" / atom
; new mechanisms MUST be registered with IANA
resp-text-code =/ "MAILBOXKEY" SP mechanism SP base64
url = astring
; contains imapurl as defined below
urlfetch = "URLFETCH" SP 1*url
urlfetch-data = "*" SP "URLFETCH" 1*(url nstring)
The following modifications are made to the Formal Syntax in [IMAPURL]:
enc-urlauth = 32*HEXDIG
imessagepart = enc_mailbox [uidvalidity] iuid [isection] [iurlauth]
iurlauth = iauth [iexpire] ";URLAUTH=" mechanism ":" enc-urlauth
iauth = (";AUTHID=" iuserauth) / (";AUTHROLE=" iauthrole)
iauthrole = "compose" / "submit" / "authuser" / "anonymous"
iexpire = ";EXPIRE=" date-time
; date-time defined in [DATETIME]
Security Considerations
Security considerations are discussed throughout this memo.
The mailbox access generation key SHOULD have at least 128 bits of
entropy (refer to [RANDOM] for more details) and MUST NOT be guessable.
Signed URLs with using ";AUTHROLE=anonymous" can be used by anyone to
access the authorized data. Unless it is intended to provide public
access to the data authorized by this URL, ";AUTHROLE=anonymous" SHOULD
NOT be used, and MUST NOT be transmitted over a non-encrypted
communication path.
To simplify interoperability with a [COMPOSE] server, and to ensure
that only the [COMPOSE] server should use a signed URL, a well-known
authenticated userid for the URL SHOULD be defined and used (instead
of anonymous authentication) in conjunction with either
";AUTHID=<userid>", ";AUTHROLE=compose", or ";AUTHROLE=submit".
The MAILBOXKEY status response code exposes sensitive data. A server
implementation MUST implement a configuration that will not return
a MAILBOXKEY status response code unless some mechanism is provided
that protects the session from snooping, such as a TLS or SASL
security layer that provides confidentiality protection.
The calculation of an [HMAC-MD5] checksum with a "plausible" key if
the mailbox can not be identified is necessary to avoid attacks in
which the server is probed to see if a particular mailbox exists on
the server by measuring the amount of time taken to reject a known
bad name vs. some other name.
To protect against a computational denial-of-service attack, a server
MAY impose progressively longer delays on multiple URL requests that
fail validation.
IANA Considerations
URLAUTH authentication signture mechanisms are registered by
publishing a standards track or IESG approved experimental RFC. The
registry is currently located at:
[to be defined by IANA]
This document consitutes registration of the HMAC-MD5 and INTERNAL
URLAUTH authentication signature mechanisms.
References
The following references are normative:
[ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", RFC 2234, November 1997.
[ACL] Myers, J., "IMAP4 ACL Extension", RFC 2086, January 1997.
[ACL2] Melnikov, A., "IMAP4 ACL Extension",
draft-ietf-imapext-acl-08.txt (work in progress), June 2003.
[COMPOSE] Newman, C., "Message Composition",
draft-newman-lemonade-compose-00.txt (work in progress),
June 2003.
[DATETIME] Klyne, G., and Newman, C., "Date and Time on the Internet:
Timestamps", RFC 3339, July 2002.
[IMAP] Crispin, M., "Internet Message Access Protocol - Version
4rev1", RFC 3501, March 2003.
[IMAPURL] Newman, C., "IMAP URL Scheme", RFC 2192, September 1997.
[HMAC-MD5] Krawczyk, H., Bellare, M., and Canetti, R. "HMAC:
Keyed-Hashing for Message Authentication", RFC 2104,
February 1997.
[KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[MD5] Rivest, R., "The MD5 Message Digest Algorithm",
RFC 1321, MIT Laboratory for Computer Science, April 1992.
[MIME-IMB] Freed, N. and N. Borenstein, "MIME (Multipurpose Internet
Mail Extensions) Part One: Format of Internet Message
Bodies", RFC 2045, November 1996.
The following references are informative:
[RANDOM] Eastlake, D., Crocker, S., and Schiller, J., "Randomness
Recommendations for Security", RFC 1750, December 1994.
Author's Addresses
Mark R. Crispin
Networks and Distributed Computing
University of Washington
4545 15th Avenue NE
Seattle, WA 98105-4527
Phone: (206) 543-5762
EMail: MRC@CAC.Washington.EDU
Chris Newman
Sun Microsystems
1050 Lakes Drive
West Covina, CA 91790
EMail: chris.newman@sun.com
Intellectual Property Statement
The IETF takes no position regarding the validity or scope of any
intellectual property or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; neither does it represent that it
has made any effort to identify any such rights. Information on the
IETF's procedures with respect to rights in standards-track and
standards-related documentation can be found in BCP-11. Copies of
claims of rights made available for publication and any assurances of
licenses to be made available, or the result of an attempt made to
obtain a general license or permission for the use of such
proprietary rights by implementors or users of this specification can
be obtained from the IETF Secretariat.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights which may cover technology that may be required to practice
this standard. Please address the information to the IETF Executive
Director.
Full Copyright Statement
Copyright (C) The Internet Society (2003). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assignees.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Acknowledgement
Funding for the RFC Editor function is currently provided by the
Internet Society.