Network Working Group M. Crispin
INTERNET-DRAFT: IMAP URLAUTH University of Washington
C. Newman
Sun Microsystems
Document: internet-drafts/draft-crispin-imap-urlauth-08.txt July 2004
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 21 January 2005.
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 use "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 uses 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 [BURL], for such purposes as a memory (or
other resource) constrainted client submitting a message forward or resend
from an IMAP mailbox without requiring the client to fetch that message
data.
URLs are signed using a signature mechanism name and an authentication
signature, which is generated using a secret mailbox access key. An IMAP
client client can request the server to generate and assign a new mailbox
access key (thus effectively revoking all current URLs using URLAUTH with
that mailbox access key) but can not set the mailbox access key to a key
of its own choosing.
1. Concepts
1.1. Mailbox Access Key
The mailbox access key is a random string with at least 128 bits of
entropy. It is generated by software (not by the human user), and MUST
be unpredictable.
Each user has a table of mailboxes and an associated mailbox access key
for each mailbox. Consequently, the mailbox access key is per-user and
per-mailbox. In other words, two users sharing the same mailbox each have
a different mailbox access key for that mailbox; and each mailbox accessed
by a single user also has different mailbox access key.
1.2. Signatures
The signature is a deterministic string of at least 128 bits which an
entity with knowledge of the secret mailbox access key and signature
mechanism can use to verify the URL.
1.3. Signature Mechanisms
The signature mechanism is the algorithm by which the URL is signed and
subsequently verified, using the mailbox access key.
This specification defines the INTERNAL mechanism, which uses a signature
algorithm of the server's choosing (a modern and reasonably secure
algorithm such as HMAC-SHA1 is recommended) and does not involve
disclosure of the mailbox access key to the client.
Although this specification is extensible for other mechanisms, none
are defined in this document.
2. IMAP URL Extensions
[IMAPURL] is extended by allowing the addition of ;EXPIRE=<datetime>"
and ";URLAUTH=<access>:<mech>:<sig>" to IMAP URLs which refer to
specific message or message parts.
";URLAUTH=<access>:<mech>:<sig>" MUST be at the end of the URL.
This facility does not apply to, and MUST NOT be used with, any IMAP URL
which refers to an entire IMAP server, list of mailboxes, an entire IMAP
mailbox, or IMAP search results.
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=<access>:<mech>:<sig>" is used, this indicates the access
identifiers which are permitted to use this URL, the mechanism used to
sign the URL, and the signature.
The "submit+" access identifier, followed by a userid, indicates that
only a userid authorized as a message submission entity on behalf of the
specified userid is permitted to use this URL. The IMAP server does not
validate the specified userid but does validate that the IMAP session
has an authorization identity that is authorized as a message submission
entity. The authorized message submission entity MUST validate the
userid prior to contacting the IMAP server.
The "user+" access identifier, followed by a userid, indicates 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).
;;; Earlier versions of this document had access identifiers for "any
;;; authorized user" and anonymous. These are not needed for Lemonade
;;; submit-without-download and have been removed.
The signature is represented as an ASCII-encoded hexadecimal string,
which is used to authorize the URL. The length and the calculation of
the signature depends upon the mechanism used; but in all cases the
signature is at least 128 bits (and therefore 32 hexadecimal digits).
3. Discussion of 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
access identifier.
The "user+<userid>" access identifier limits resolution of that URL to a
particular userid, whereas the "submit+<userid>" access identifier is
more general and simply requires the session be authorized by a user
that has been granted a "submit" role within the authentication system.
This makes it impossible for an attacker, spying on the session, to use
the same URL, either directly or by submission to a message submission
entity.
4. Generation of Signed URLs
A signed URL is generated as follows.
An initial URL is built, ending with ";URLAUTH=<access>" but without the
":<mech>:<sig>" components. A signature mechanism is selected and used
to calculate the 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 ":" followed by the signature
mechanism name, ":", and the ASCII-encoded hexadecimal representation of
the authentication signature.
Note: ASCII-encoded hexadecimal is used instead of BASE64 because a
BASE64 representation may have "=" padding characters which would be
problematic in a URL.
In the INTERNAL mechanism, the mailbox access key for that mailbox is
the secret known to the IMAP server, and a server-selected algorithm
such as HMAC-SHA1 is used to to calculate the signature.
5. Validation of Signed URLs
A signed URL is validated as follows.
The URL is split at the ":" which separates "<access>" from "<mech>:<sig>"
in the ";URLAUTH=<access>:<mech>:<sig>" portion of the URL. The
"<mech>:<sig>" portion is first parsed and saved as the signature
mechanism and the signature. The URL is truncated, discarding the ":"
described above, to create a "rump URL" (the URL minus the ":" and the
"<mech>:sig" portion). The rump URL is then analyzed to identify the
mailbox.
If the mailbox cannot 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 a secret known to the IMAP server using the given signature
mechanism. Validation is successful if, and only if, the calculated
signature for that mechanism matches the signature supplied in
";URLAUTH=<access>:<mech>:<sig>".
Removal of the ":<mech>:<sig>" portion of the URL MUST be 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.
In the INTERNAL mechanism, the mailbox access key for that mailbox is
used as the secret known to the IMAP server, and the same
server-selected algorithm used for generating URLs is used to calculate
the signature for verification.
6. Additional Commands
These commands are extension to the [IMAP] base protocol.
The section headings of these commands are intended to correspond with
where they would be located in the base protocol document if they were
part of that document.
BASE.6.3.RESETKEY. RESETKEY Command
Arguments: optional mailbox name
optional mechanism name(s)
Responses: none other than in result
Result: OK - RESETKEY completed, URLMECH containing new data
NO - RESETKEY error: can't change key of that mailbox
BAD - command unknown or arguments invalid
The RESETKEY command has two forms.
The first form accepts a mailbox name as an argument, and generates a
new mailbox access key for the given mailbox in the user's mailbox
access key table, replacing any previous mailbox access key (and
revoking any URLs signed using that key) in that table. By default, the
mailbox access key is generated for the INTERNAL mechanism; other
mechanisms can be specified with the optional mechanism argument.
The second form, with no arguments, removes all mailbox access keys in
the user's mailbox access key table, revoking all URLs signed by the
user.
Any current IMAP session logged in as the user which has the mailbox
selected will receive an untagged OK response with the MAILBOXKEY
status response code.
Example:
C: a31 RESETKEY
S: a31 OK All keys removed
C: a32 RESETKEY INBOX
S: a32 OK [URLMECH INTERNAL] mechs
C: a33 RESETKEY INBOX XSAMPLE
S: a33 OK [URLMECH INTERNAL XSAMPLE=P34OKhO7VEkCbsiYY8rGEg==] mechs
BASE.6.3.SIGNURL. SIGNURL Command
Argument: one or more URL/mechanism pairs
Response: untagged response: 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
;urlauth=submit+fred" INTERNAL
S: * SIGNURL "imap://joe@example.com/INBOX;uid=20;section=1.2
;authid=fred;urlauth=submit+fred:internal:
91354a473744909de610943775f92038"
S: a777 OK SIGNURL completed
BASE.6.3.URLFETCH. URLFETCH Command
Argument: URL
Response: untagged response: 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 an 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 also does not in any way interfere with any selected
mailbox.
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.
This example is of a submit server, obtaining a message segment for
a message that it has already validated was submitted by "fred".
S: * OK [CAPABILITY IMAP4REV1 URLAUTH] example.com IMAP server ready
C: a001 LOGIN submitserver secret
S: a001 OK submitserver logged in
C: a002 URLFETCH "imap://joe@example.com/INBOX;uid=20;section=1.2
;urlauth=submit+fred:internal:
91354a473744909de610943775f92038"
S: * URLFETCH "imap://joe@example.com/INBOX;uid=20;section=1.2
;urlauth=submit+fred:internal:91354a473744909de610943775f92038" {28}
S: Si vis pacem, para bellum.
S:
S: a002 OK URLFETCH completed
7. Additional Responses
These responses are extensions to the [IMAP] base protocol.
The section headings of these responses are intended to correspond with
where they would be located in the base protocol document if they were
part of that document.
BASE.7.1.URLMECH. URLMECH Status Response Code
The URLMECH status response code is followed by a list of signature
mechanism names. Mechanism names other than INTERNAL may be appended
with an "=" and BASE64 encoded form of mechanism specific data.
This status response code is returned in an untagged OK response in
response to a RESETKEY, SELECT, or EXAMINE command.
BASE.7.4.URLFETCH. URLFETCH Response
Contents: URL/nstring pair
The URLFETCH response returns the message text data associated with an
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.
8. 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]:
resetkey = "RESETKEY" [SP mailbox *(SP mechanism)]
command-auth =/ resetkey / signurl / urlfetch
resp-text-code =/ "URLMECH" SP "INTERNAL" *(SP mechanism ["=" base64])
signurl = "SIGNURL" 1*(SP url SP mechanism)
signurl-data = "*" SP "SIGNURL" 1*(SP url)
url = astring
; contains imapurl as defined below
urlfetch = "URLFETCH" SP url
urlfetch-data = "*" SP "URLFETCH" SP url SP nstring
The following modifications are made to the Formal Syntax in [IMAPURL]:
enc-urlauth = 32*HEXDIG
imessagepart = enc_mailbox [uidvalidity] iuid [isection] [iurlauth]
iurlauth = [expire] ";URLAUTH=" access ":" mechanism ":" enc-urlauth
access = ("submit+" iuserauth) / ("user+" iuserauth)
expire = ";EXPIRE=" date-time
; date-time defined in [DATETIME]
mechanism = "INTERNAL" / 1*uchar
; new mechanisms MUST be registered with IANA
9. Security Considerations
Security considerations are discussed throughout this memo.
The mailbox access key SHOULD have at least 128 bits of entropy (refer
to [RANDOM] for more details) and MUST be unpredictable.
The URLMECH status response code may expose sensitive data in the
mechanism specific data for mechanisms other than INTERNAL. A server
implementation MUST implement a configuration that will not return
a URLMECH 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 a signature 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 INTERNAL URLAUTH
signature mechanism:
IMAP URLAUTH Authentication Signature Mechanism Registry
Mechanism Name Reference
-------------- ---------
INTERNAL [this document, to be filled in by IANA]
References
The following references are normative:
[ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", RFC 2234, November 1997.
[BURL] Newman, C., "Message Submission BURL Extension",
draft-newman-lemonade-burl-00.txt (work in progress),
March 2004.
[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.
[KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
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
IPR Disclosure Acknowledgement
By submitting this Internet-Draft, I certify that any applicable
patent or other IPR claims of which I am aware have been disclosed,
and any of which I become aware will be disclosed, in accordance with
RFC 3668.
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 (2004). This document is subject
to the rights, licenses and restrictions contained in BCP 78 and
except as set forth therein, the authors retain all their rights.
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE
REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE
INTERNET ENGINEERING TASK FORCE DISCLAIM 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.
Intellectual Property
The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights 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; nor does it
represent that it has made any independent effort to identify any
such rights. Information on the procedures with respect to
rights in RFC documents can be found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat 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 implementers or users of this
specification can be obtained from the IETF on-line IPR repository
at http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention
any copyrights, patents or patent applications, or other
proprietary rights that may cover technology that may be required
to implement this standard. Please address the information to the
IETF at ietf-ipr@ietf.org.
Acknowledgement
Funding for the RFC Editor function is currently provided by the
Internet Society.