1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/docs/rfc/rfc4467.txt	Mon Sep 14 15:17:45 2009 +0900
     1.3 @@ -0,0 +1,1011 @@
     1.4 +
     1.5 +
     1.6 +
     1.7 +
     1.8 +
     1.9 +
    1.10 +Network Working Group                                         M. Crispin
    1.11 +Request for Comments: 4467                      University of Washington
    1.12 +Updates: 3501                                                   May 2006
    1.13 +Category: Standards Track
    1.14 +
    1.15 +
    1.16 +      Internet Message Access Protocol (IMAP) - URLAUTH Extension
    1.17 +
    1.18 +Status of This Memo
    1.19 +
    1.20 +   This document specifies an Internet standards track protocol for the
    1.21 +   Internet community, and requests discussion and suggestions for
    1.22 +   improvements.  Please refer to the current edition of the "Internet
    1.23 +   Official Protocol Standards" (STD 1) for the standardization state
    1.24 +   and status of this protocol.  Distribution of this memo is unlimited.
    1.25 +
    1.26 +Copyright Notice
    1.27 +
    1.28 +   Copyright (C) The Internet Society (2006).
    1.29 +
    1.30 +Abstract
    1.31 +
    1.32 +   This document describes the URLAUTH extension to the Internet Message
    1.33 +   Access Protocol (IMAP) (RFC 3501) and the IMAP URL Scheme (IMAPURL)
    1.34 +   (RFC 2192).  This extension provides a means by which an IMAP client
    1.35 +   can use URLs carrying authorization to access limited message data on
    1.36 +   the IMAP server.
    1.37 +
    1.38 +   An IMAP server that supports this extension indicates this with a
    1.39 +   capability name of "URLAUTH".
    1.40 +
    1.41 +1.  Introduction
    1.42 +
    1.43 +   In [IMAPURL], a URL of the form imap://fred@example.com/INBOX/;uid=20
    1.44 +   requires authorization as userid "fred".  However, [IMAPURL] implies
    1.45 +   that it only supports authentication and confuses the concepts of
    1.46 +   authentication and authorization.
    1.47 +
    1.48 +   The URLAUTH extension defines an authorization mechanism for IMAP
    1.49 +   URLs to replace [IMAPURL]'s authentication-only mechanism.  URLAUTH
    1.50 +   conveys authorization in the URL string itself and reuses a portion
    1.51 +   of the syntax of the [IMAPURL] authentication mechanism to convey the
    1.52 +   authorization identity (which also defines the default namespace in
    1.53 +   [IMAP]).
    1.54 +
    1.55 +   The URLAUTH extension provides a means by which an authorized user of
    1.56 +   an IMAP server can create URLAUTH-authorized IMAP URLs.  A URLAUTH-
    1.57 +   authorized URL conveys authorization (not authentication) to the data
    1.58 +
    1.59 +
    1.60 +
    1.61 +Crispin                     Standards Track                     [Page 1]
    1.62 +
    1.63 +RFC 4467                IMAP - URLAUTH Extension                May 2006
    1.64 +
    1.65 +
    1.66 +   addressed by that URL.  This URL can be used in another IMAP session
    1.67 +   to access specific content on the IMAP server, without otherwise
    1.68 +   providing authorization to any other data (such as other data in the
    1.69 +   mailbox specified in the URL) owned by the authorizing user.
    1.70 +
    1.71 +   Conceptually, a URLAUTH-authorized URL can be thought of as a "pawn
    1.72 +   ticket" that carries no authentication information and can be
    1.73 +   redeemed by whomever presents it.  However, unlike a pawn ticket,
    1.74 +   URLAUTH has optional mechanisms to restrict the usage of a URLAUTH-
    1.75 +   authorized URL.  Using these mechanisms, URLAUTH-authorized URLs can
    1.76 +   be usable by:
    1.77 +
    1.78 +      . anonymous (the "pawn ticket" model)
    1.79 +      . authenticated users only
    1.80 +      . a specific authenticated user only
    1.81 +      . message submission acting on behalf of a specific user only
    1.82 +
    1.83 +   There is also a mechanism for expiration.
    1.84 +
    1.85 +   A URLAUTH-authorized URL can be used in the argument to the BURL
    1.86 +   command in message composition, as described in [BURL], for such
    1.87 +   purposes as allowing a client (with limited memory or other
    1.88 +   resources) to submit a message forward or to resend from an IMAP
    1.89 +   mailbox without requiring the client to fetch that message data.
    1.90 +
    1.91 +   The URLAUTH is generated using an authorization mechanism name and an
    1.92 +   authorization token, which is generated using a secret mailbox access
    1.93 +   key.  An IMAP client can request that the server generate and assign
    1.94 +   a new mailbox access key (thus effectively revoking all current URLs
    1.95 +   using URLAUTH with the old mailbox access key) but cannot set the
    1.96 +   mailbox access key to a key of its own choosing.
    1.97 +
    1.98 +1.1.  Conventions Used in this Document
    1.99 +
   1.100 +   The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY"
   1.101 +   in this document are to be interpreted as defined in [KEYWORDS].
   1.102 +
   1.103 +   The formal syntax uses the Augmented Backus-Naur Form (ABNF) notation
   1.104 +   including the core rules defined in Appendix A of [ABNF].
   1.105 +
   1.106 +   In examples, "C:" and "S:" indicate lines sent by the client and
   1.107 +   server, respectively.  If a single "C:" or "S:" label applies to
   1.108 +   multiple lines, then the line breaks between those lines are for
   1.109 +   editorial clarity only and are not part of the actual protocol
   1.110 +   exchange.
   1.111 +
   1.112 +
   1.113 +
   1.114 +
   1.115 +
   1.116 +
   1.117 +Crispin                     Standards Track                     [Page 2]
   1.118 +
   1.119 +RFC 4467                IMAP - URLAUTH Extension                May 2006
   1.120 +
   1.121 +
   1.122 +2.  Concepts
   1.123 +
   1.124 +2.1.  URLAUTH
   1.125 +
   1.126 +   The URLAUTH is a component, appended at the end of a URL, that
   1.127 +   conveys authorization to access the data addressed by that URL.  It
   1.128 +   contains an authorized access identifier, an authorization mechanism
   1.129 +   name, and an authorization token.  The authorization token is
   1.130 +   generated from the URL, the authorized access identifier, the
   1.131 +   authorization mechanism name, and a mailbox access key.
   1.132 +
   1.133 +2.2.  Mailbox Access Key
   1.134 +
   1.135 +   The mailbox access key is a random string with at least 128 bits of
   1.136 +   entropy.  It is generated by software (not by the human user) and
   1.137 +   MUST be unpredictable.
   1.138 +
   1.139 +   Each user has a table of mailboxes and an associated mailbox access
   1.140 +   key for each mailbox.  Consequently, the mailbox access key is per-
   1.141 +   user and per-mailbox.  In other words, two users sharing the same
   1.142 +   mailbox each have a different mailbox access key for that mailbox,
   1.143 +   and each mailbox accessed by a single user also has a different
   1.144 +   mailbox access key.
   1.145 +
   1.146 +2.3.  Authorized Access Identifier
   1.147 +
   1.148 +   The authorized access identifier restricts use of the URLAUTH
   1.149 +   authorized URL to certain users authorized on the server, as
   1.150 +   described in section 3.
   1.151 +
   1.152 +2.4.  Authorization Mechanism
   1.153 +
   1.154 +   The authorization mechanism is the algorithm by which the URLAUTH is
   1.155 +   generated and subsequently verified, using the mailbox access key.
   1.156 +
   1.157 +2.4.1.  INTERNAL Authorization Mechanism
   1.158 +
   1.159 +   This specification defines the INTERNAL mechanism, which uses a token
   1.160 +   generation algorithm of the server's choosing and does not involve
   1.161 +   disclosure of the mailbox access key to the client.
   1.162 +
   1.163 +      Note: The token generation algorithm chosen by the server
   1.164 +      implementation should be modern and reasonably secure.  At the
   1.165 +      time of the writing of this document, an [HMAC] such as HMAC-SHA1
   1.166 +      is recommended.
   1.167 +
   1.168 +
   1.169 +
   1.170 +
   1.171 +
   1.172 +
   1.173 +Crispin                     Standards Track                     [Page 3]
   1.174 +
   1.175 +RFC 4467                IMAP - URLAUTH Extension                May 2006
   1.176 +
   1.177 +
   1.178 +      If it becomes necessary to change the token generation algorithm
   1.179 +      of the INTERNAL mechanism (e.g., because an attack against the
   1.180 +      current algorithm has been discovered), all currently existing
   1.181 +      URLAUTH-authorized URLs are invalidated by the change in
   1.182 +      algorithm.  Since this would be an unpleasant surprise to
   1.183 +      applications that depend upon the validity of a URLAUTH-authorized
   1.184 +      URL, and there is no good way to do a bulk update of existing
   1.185 +      deployed URLs, it is best to avoid this situation by using a
   1.186 +      secure algorithm as opposed to one that is "good enough".
   1.187 +
   1.188 +      Server implementations SHOULD consider the possibility of changing
   1.189 +      the algorithm.  In some cases, it may be desirable to implement
   1.190 +      the change of algorithm in a way that newly-generated tokens use
   1.191 +      the new algorithm, but that for a limited period of time tokens
   1.192 +      using either the new or old algorithm can be validated.
   1.193 +      Consequently, the server SHOULD incorporate some means of
   1.194 +      identifying the token generation algorithm within the token.
   1.195 +
   1.196 +   Although this specification is extensible for other mechanisms, none
   1.197 +   are defined in this document.  In addition to the mechanism name
   1.198 +   itself, other mechanisms may have mechanism-specific data, which is
   1.199 +   to be interpreted according to the definition of that mechanism.
   1.200 +
   1.201 +2.5.  Authorization Token
   1.202 +
   1.203 +   The authorization token is a deterministic string of at least 128
   1.204 +   bits that an entity with knowledge of the secret mailbox access key
   1.205 +   and URL authorization mechanism can use to verify the URL.
   1.206 +
   1.207 +3.  IMAP URL Extensions
   1.208 +
   1.209 +   [IMAPURL] is extended by allowing the addition of
   1.210 +   ";EXPIRE=<datetime>" and ";URLAUTH=<access>:<mech>:<token>" to IMAP
   1.211 +   URLs that refer to a specific message or message parts.
   1.212 +
   1.213 +   The URLAUTH is comprised of ";URLAUTH=<access>:<mech>:<token>" and
   1.214 +   MUST be at the end of the URL.
   1.215 +
   1.216 +   URLAUTH does not apply to, and MUST NOT be used with, any IMAP URL
   1.217 +   that refers to an entire IMAP server, a list of mailboxes, an entire
   1.218 +   IMAP mailbox, or IMAP search results.
   1.219 +
   1.220 +   When ";EXPIRE=<datetime>" is used, this indicates the latest date and
   1.221 +   time that the URL is valid.  After that date and time, the URL has
   1.222 +   expired, and server implementations MUST reject the URL.  If
   1.223 +   ";EXPIRE=<datetime>" is not used, the URL has no expiration, but
   1.224 +   still can be revoked as discussed below.
   1.225 +
   1.226 +
   1.227 +
   1.228 +
   1.229 +Crispin                     Standards Track                     [Page 4]
   1.230 +
   1.231 +RFC 4467                IMAP - URLAUTH Extension                May 2006
   1.232 +
   1.233 +
   1.234 +   The URLAUTH takes the form ";URLAUTH=<access>:<mech>:<token>".  It is
   1.235 +   composed of three parts.  The <access> portion provides the
   1.236 +   authorized access identifiers, which may constrain the operations and
   1.237 +   users that are permitted to use this URL.  The <mech> portion
   1.238 +   provides the authorization mechanism used by the IMAP server to
   1.239 +   generate the authorization token that follows.  The <token> portion
   1.240 +   provides the authorization token.
   1.241 +
   1.242 +   The "submit+" access identifier prefix, followed by a userid,
   1.243 +   indicates that only a userid authorized as a message submission
   1.244 +   entity on behalf of the specified userid is permitted to use this
   1.245 +   URL.  The IMAP server does not validate the specified userid but does
   1.246 +   validate that the IMAP session has an authorization identity that is
   1.247 +   authorized as a message submission entity.  The authorized message
   1.248 +   submission entity MUST validate the userid prior to contacting the
   1.249 +   IMAP server.
   1.250 +
   1.251 +   The "user+" access identifier prefix, followed by a userid, indicates
   1.252 +   that use of this URL is limited to IMAP sessions that are logged in
   1.253 +   as the specified userid (that is, have authorization identity as that
   1.254 +   userid).
   1.255 +
   1.256 +      Note: If a SASL mechanism that provides both authorization and
   1.257 +      authentication identifiers is used to authenticate to the IMAP
   1.258 +      server, the "user+" access identifier MUST match the authorization
   1.259 +      identifier.
   1.260 +
   1.261 +   The "authuser" access identifier indicates that use of this URL is
   1.262 +   limited to IMAP sessions that are logged in as an authorized user
   1.263 +   (that is, have authorization identity as an authorized user) of that
   1.264 +   IMAP server.  Use of this URL is prohibited to anonymous IMAP
   1.265 +   sessions.
   1.266 +
   1.267 +   The "anonymous" access identifier indicates that use of this URL is
   1.268 +   not restricted by session authorization identity; that is, any IMAP
   1.269 +   session in authenticated or selected state (as defined in [IMAP]),
   1.270 +   including anonymous sessions, may issue a URLFETCH using this URL.
   1.271 +
   1.272 +   The authorization token is represented as an ASCII-encoded
   1.273 +   hexadecimal string, which is used to authorize the URL.  The length
   1.274 +   and the calculation of the authorization token depends upon the
   1.275 +   mechanism used; but, in all cases, the authorization token is at
   1.276 +   least 128 bits (and therefore at least 32 hexadecimal digits).
   1.277 +
   1.278 +
   1.279 +
   1.280 +
   1.281 +
   1.282 +
   1.283 +
   1.284 +
   1.285 +Crispin                     Standards Track                     [Page 5]
   1.286 +
   1.287 +RFC 4467                IMAP - URLAUTH Extension                May 2006
   1.288 +
   1.289 +
   1.290 +4.  Discussion of URLAUTH Authorization Issues
   1.291 +
   1.292 +   In [IMAPURL], the userid before the "@" in the URL has two purposes:
   1.293 +
   1.294 +      1) It provides context for user-specific mailbox paths such as
   1.295 +         "INBOX".
   1.296 +
   1.297 +      2) It specifies that resolution of the URL requires logging in as
   1.298 +         that user and limits use of that URL to only that user.
   1.299 +
   1.300 +   An obvious limitation of using the same field for both purposes is
   1.301 +   that the URL can only be resolved by the mailbox owner.
   1.302 +
   1.303 +   URLAUTH overrides the second purpose of the userid in the IMAP URL
   1.304 +   and by default permits the URL to be resolved by any user permitted
   1.305 +   by the access identifier.
   1.306 +
   1.307 +   The "user+<userid>" access identifier limits resolution of that URL
   1.308 +   to a particular userid, whereas the "submit+<userid>" access
   1.309 +   identifier is more general and simply requires that the session be
   1.310 +   authorized by a user that has been granted a "submit" role within the
   1.311 +   authentication system.  Use of either of these access identifiers
   1.312 +   makes it impossible for an attacker, spying on the session, to use
   1.313 +   the same URL, either directly or by submission to a message
   1.314 +   submission entity.
   1.315 +
   1.316 +   The "authuser" and "anonymous" access identifiers do not have this
   1.317 +   level of protection and should be used with caution.  These access
   1.318 +   identifiers are primarily useful for public export of data from an
   1.319 +   IMAP server, without requiring that it be copied to a web or
   1.320 +   anonymous FTP server.  Refer to the Security Considerations for more
   1.321 +   details.
   1.322 +
   1.323 +5.  Generation of URLAUTH-Authorized URLs
   1.324 +
   1.325 +   A URLAUTH-authorized URL is generated from an initial URL as follows:
   1.326 +
   1.327 +   An initial URL is built, ending with ";URLAUTH=<access>" but without
   1.328 +   the ":<mech>:<token>" components.  An authorization mechanism is
   1.329 +   selected and used to calculate the authorization token, with the
   1.330 +   initial URL as the data and a secret known to the IMAP server as the
   1.331 +   key.  The URLAUTH-authorized URL is generated by taking the initial
   1.332 +   URL and appending ":", the URL authorization mechanism name, ":", and
   1.333 +   the ASCII-encoded hexadecimal representation of the authorization
   1.334 +   token.
   1.335 +
   1.336 +
   1.337 +
   1.338 +
   1.339 +
   1.340 +
   1.341 +Crispin                     Standards Track                     [Page 6]
   1.342 +
   1.343 +RFC 4467                IMAP - URLAUTH Extension                May 2006
   1.344 +
   1.345 +
   1.346 +      Note: ASCII-encoded hexadecimal is used instead of BASE64 because
   1.347 +      a BASE64 representation may have "=" padding characters, which
   1.348 +      would be problematic in a URL.
   1.349 +
   1.350 +   In the INTERNAL mechanism, the mailbox access key for that mailbox is
   1.351 +   the secret known to the IMAP server, and a server-selected algorithm
   1.352 +   is used as described in section 2.4.1.
   1.353 +
   1.354 +6.  Validation of URLAUTH-authorized URLs
   1.355 +
   1.356 +   A URLAUTH-authorized URL is validated as follows:
   1.357 +
   1.358 +   The URL is split at the ":" that separates "<access>" from
   1.359 +   "<mech>:<token>" in the ";URLAUTH=<access>:<mech>:<token>" portion of
   1.360 +   the URL.  The "<mech>:<token>" portion is first parsed and saved as
   1.361 +   the authorization mechanism and the authorization token.  The URL is
   1.362 +   truncated, discarding the ":" described above, to create a "rump URL"
   1.363 +   (the URL minus the ":" and the "<mech>:<token>" portion).  The rump
   1.364 +   URL is then analyzed to identify the mailbox.
   1.365 +
   1.366 +   If the mailbox cannot be identified, an authorization token is
   1.367 +   calculated on the rump URL, using random "plausible" keys (selected
   1.368 +   by the server) as needed, before returning a validation failure.
   1.369 +   This prevents timing attacks aimed at identifying mailbox names.
   1.370 +
   1.371 +   If the mailbox can be identified, the authorization token is
   1.372 +   calculated on the rump URL and a secret known to the IMAP server
   1.373 +   using the given URL authorization mechanism.  Validation is
   1.374 +   successful if, and only if, the calculated authorization token for
   1.375 +   that mechanism matches the authorization token supplied in
   1.376 +   ";URLAUTH=<access>:<mech>:<token>".
   1.377 +
   1.378 +   Removal of the ":<mech>:<token>" portion of the URL MUST be the only
   1.379 +   operation applied to the URLAUTH-authorized URL to get the rump URL.
   1.380 +   In particular, URL percent escape decoding and case-folding
   1.381 +   (including to the domain part of the URL) MUST NOT occur.
   1.382 +
   1.383 +   In the INTERNAL mechanism, the mailbox access key for that mailbox is
   1.384 +   used as the secret known to the IMAP server, and the same server-
   1.385 +   selected algorithm used for generating URLs is used to calculate the
   1.386 +   authorization token for verification.
   1.387 +
   1.388 +
   1.389 +
   1.390 +
   1.391 +
   1.392 +
   1.393 +
   1.394 +
   1.395 +
   1.396 +
   1.397 +Crispin                     Standards Track                     [Page 7]
   1.398 +
   1.399 +RFC 4467                IMAP - URLAUTH Extension                May 2006
   1.400 +
   1.401 +
   1.402 +7.  Additional Commands
   1.403 +
   1.404 +   These commands are extensions to the [IMAP] base protocol.
   1.405 +
   1.406 +   The section headings of these commands are intended to correspond
   1.407 +   with where they would be located in the base protocol document if
   1.408 +   they were part of that document.
   1.409 +
   1.410 +BASE.6.3.RESETKEY.  RESETKEY Command
   1.411 +
   1.412 +   Arguments:  optional mailbox name
   1.413 +               optional mechanism name(s)
   1.414 +
   1.415 +   Responses:  none other than in result
   1.416 +
   1.417 +   Result:     OK - RESETKEY completed, URLMECH containing new data
   1.418 +               NO - RESETKEY error: can't change key of that mailbox
   1.419 +               BAD - command unknown or arguments invalid
   1.420 +
   1.421 +   The RESETKEY command has two forms.
   1.422 +
   1.423 +   The first form accepts a mailbox name as an argument and generates a
   1.424 +   new mailbox access key for the given mailbox in the user's mailbox
   1.425 +   access key table, replacing any previous mailbox access key (and
   1.426 +   revoking any URLs that were authorized with a URLAUTH using that key)
   1.427 +   in that table.  By default, the mailbox access key is generated for
   1.428 +   the INTERNAL mechanism; other mechanisms can be specified with the
   1.429 +   optional mechanism argument.
   1.430 +
   1.431 +   The second form, with no arguments, removes all mailbox access keys
   1.432 +   in the user's mailbox access key table, revoking all URLs currently
   1.433 +   authorized using URLAUTH by the user.
   1.434 +
   1.435 +   Any current IMAP session logged in as the user that has the mailbox
   1.436 +   selected will receive an untagged OK response with the URLMECH status
   1.437 +   response code (see section BASE.7.1.URLMECH for more details about
   1.438 +   the URLMECH status response code).
   1.439 +
   1.440 +   Example:
   1.441 +
   1.442 +      C: a31 RESETKEY
   1.443 +      S: a31 OK All keys removed
   1.444 +      C: a32 RESETKEY INBOX
   1.445 +      S: a32 OK [URLMECH INTERNAL] mechs
   1.446 +      C: a33 RESETKEY INBOX XSAMPLE
   1.447 +      S: a33 OK [URLMECH INTERNAL XSAMPLE=P34OKhO7VEkCbsiYY8rGEg==] done
   1.448 +
   1.449 +
   1.450 +
   1.451 +
   1.452 +
   1.453 +Crispin                     Standards Track                     [Page 8]
   1.454 +
   1.455 +RFC 4467                IMAP - URLAUTH Extension                May 2006
   1.456 +
   1.457 +
   1.458 +BASE.6.3.GENURLAUTH.  GENURLAUTH Command
   1.459 +
   1.460 +      Argument:   one or more URL/mechanism pairs
   1.461 +
   1.462 +      Response:   untagged response: GENURLAUTH
   1.463 +
   1.464 +      Result:     OK - GENURLAUTH completed
   1.465 +                  NO - GENURLAUTH error: can't generate a URLAUTH
   1.466 +                  BAD - command unknown or arguments invalid
   1.467 +
   1.468 +   The GENURLAUTH command requests that the server generate a URLAUTH-
   1.469 +   authorized URL for each of the given URLs using the given URL
   1.470 +   authorization mechanism.
   1.471 +
   1.472 +   The server MUST validate each supplied URL as follows:
   1.473 +
   1.474 +      (1) The mailbox component of the URL MUST refer to an existing
   1.475 +          mailbox.
   1.476 +
   1.477 +      (2) The server component of the URL MUST contain a valid userid
   1.478 +          that identifies the owner of the mailbox access key table that
   1.479 +          will be used to generate the URLAUTH-authorized URL.  As a
   1.480 +          consequence, the iserver rule of [IMAPURL] is modified so that
   1.481 +          iuserauth is mandatory.
   1.482 +
   1.483 +             Note: the server component of the URL is generally the
   1.484 +             logged in userid and server.  If not, then the logged in
   1.485 +             userid and server MUST have owner-type access to the
   1.486 +             mailbox access key table owned by the userid and server
   1.487 +             indicated by the server component of the URL.
   1.488 +
   1.489 +      (3) There is a valid access identifier that, in the case of
   1.490 +          "submit+" and "user+", will contain a valid userid.  This
   1.491 +          userid is not necessarily the same as the owner userid
   1.492 +          described in (2).
   1.493 +
   1.494 +      (4) The server MAY also verify that the iuid and/or isection
   1.495 +          components (if present) are valid.
   1.496 +
   1.497 +   If any of the above checks fail, the server MUST return a tagged BAD
   1.498 +   response with the following exception.  If an invalid userid is
   1.499 +   supplied as the mailbox access key owner and/or as part of the access
   1.500 +   identifier, the server MAY issue a tagged OK response with a
   1.501 +   generated mailbox key that always fails validation when used with a
   1.502 +   URLFETCH command.  This exception prevents an attacker from
   1.503 +   validating userids.
   1.504 +
   1.505 +
   1.506 +
   1.507 +
   1.508 +
   1.509 +Crispin                     Standards Track                     [Page 9]
   1.510 +
   1.511 +RFC 4467                IMAP - URLAUTH Extension                May 2006
   1.512 +
   1.513 +
   1.514 +   If there is currently no mailbox access key for the given mailbox in
   1.515 +   the owner's mailbox access key table, one is automatically generated.
   1.516 +   That is, it is not necessary to use RESETKEY prior to first-time use
   1.517 +   of GENURLAUTH.
   1.518 +
   1.519 +   If the command is successful, a GENURLAUTH response code is returned
   1.520 +   listing the requested URLs as URLAUTH-authorized URLs.
   1.521 +
   1.522 +   Examples:
   1.523 +
   1.524 +      C: a775 GENURLAUTH "imap://joe@example.com/INBOX/;uid=20/
   1.525 +         ;section=1.2" INTERNAL
   1.526 +      S: a775 BAD missing access identifier in supplied URL
   1.527 +      C: a776 GENURLAUTH "imap://example.com/Shared/;uid=20/
   1.528 +         ;section=1.2;urlauth=submit+fred" INTERNAL
   1.529 +      S: a776 BAD missing owner username in supplied URL
   1.530 +      C: a777 GENURLAUTH "imap://joe@example.com/INBOX/;uid=20/
   1.531 +         ;section=1.2;urlauth=submit+fred" INTERNAL
   1.532 +      S: * GENURLAUTH "imap://joe@example.com/INBOX/;uid=20/;section=1.2
   1.533 +         ;urlauth=submit+fred:internal:91354a473744909de610943775f92038"
   1.534 +      S: a777 OK GENURLAUTH completed
   1.535 +
   1.536 +BASE.6.3.URLFETCH.  URLFETCH Command
   1.537 +
   1.538 +      Argument:   one or more URLs
   1.539 +
   1.540 +      Response:   untagged response: URLFETCH
   1.541 +
   1.542 +      Result:     OK - urlfetch completed
   1.543 +                  NO - urlfetch failed due to server internal error
   1.544 +                  BAD - command unknown or arguments invalid
   1.545 +
   1.546 +   The URLFETCH command requests that the server return the text data
   1.547 +   associated with the specified IMAP URLs, as described in [IMAPURL]
   1.548 +   and extended by this document.  The data is returned for all
   1.549 +   validated URLs, regardless of whether or not the session would
   1.550 +   otherwise be able to access the mailbox containing that data via
   1.551 +   SELECT or EXAMINE.
   1.552 +
   1.553 +      Note: This command does not require that the URL refer to the
   1.554 +      selected mailbox; nor does it require that any mailbox be
   1.555 +      selected.  It also does not in any way interfere with any selected
   1.556 +      mailbox.
   1.557 +
   1.558 +
   1.559 +
   1.560 +
   1.561 +
   1.562 +
   1.563 +
   1.564 +
   1.565 +Crispin                     Standards Track                    [Page 10]
   1.566 +
   1.567 +RFC 4467                IMAP - URLAUTH Extension                May 2006
   1.568 +
   1.569 +
   1.570 +   The URLFETCH command effectively executes with the access of the
   1.571 +   userid in the server component of the URL (which is generally the
   1.572 +   userid that issued the GENURLAUTH).  By itself, the URLAUTH does NOT
   1.573 +   grant access to the data; once validated, it grants whatever access
   1.574 +   to the data is held by the userid in the server component of the URL.
   1.575 +   That access may have changed since the GENURLAUTH was done.
   1.576 +
   1.577 +   The URLFETCH command MUST return an untagged URLFETCH response and a
   1.578 +   tagged OK response to any URLFETCH command that is syntactically
   1.579 +   valid.  A NO response indicates a server internal failure that may be
   1.580 +   resolved on later retry.
   1.581 +
   1.582 +      Note: The possibility of a NO response is to accommodate
   1.583 +      implementations that would otherwise have to issue an untagged BYE
   1.584 +      with a fatal error due to an inability to respond to a valid
   1.585 +      request.  In an ideal world, a server SHOULD NOT issue a NO
   1.586 +      response.
   1.587 +
   1.588 +   The server MUST return NIL for any IMAP URL that references an entire
   1.589 +   IMAP server, a list of mailboxes, an entire IMAP mailbox, or IMAP
   1.590 +   search results.
   1.591 +
   1.592 +   Example:
   1.593 +
   1.594 +      Note: For clarity, this example uses the LOGIN command, which
   1.595 +      SHOULD NOT be used over a non-encrypted communication path.
   1.596 +
   1.597 +      This example is of a submit server, obtaining a message segment
   1.598 +      for a message that it has already validated was submitted by
   1.599 +      "fred".
   1.600 +
   1.601 +      S: * OK [CAPABILITY IMAP4REV1 URLAUTH] example.com IMAP server
   1.602 +      C: a001 LOGIN submitserver secret
   1.603 +      S: a001 OK submitserver logged in
   1.604 +      C: a002 URLFETCH "imap://joe@example.com/INBOX/;uid=20/
   1.605 +         ;section=1.2;urlauth=submit+fred:internal
   1.606 +         :91354a473744909de610943775f92038"
   1.607 +      S: * URLFETCH "imap://joe@example.com/INBOX/;uid=20/;section=1.2
   1.608 +         ;urlauth=submit+fred:internal
   1.609 +         :91354a473744909de610943775f92038" {28}
   1.610 +      S: Si vis pacem, para bellum.
   1.611 +      S:
   1.612 +      S: a002 OK URLFETCH completed
   1.613 +
   1.614 +
   1.615 +
   1.616 +
   1.617 +
   1.618 +
   1.619 +
   1.620 +
   1.621 +Crispin                     Standards Track                    [Page 11]
   1.622 +
   1.623 +RFC 4467                IMAP - URLAUTH Extension                May 2006
   1.624 +
   1.625 +
   1.626 +8.  Additional Responses
   1.627 +
   1.628 +   These responses are extensions to the [IMAP] base protocol.
   1.629 +
   1.630 +   The section headings of these responses are intended to correspond
   1.631 +   with where they would be located in the base protocol document if
   1.632 +   they were part of that document.
   1.633 +
   1.634 +BASE.7.1.URLMECH.  URLMECH Status Response Code
   1.635 +
   1.636 +   The URLMECH status response code is followed by a list of URL
   1.637 +   authorization mechanism names.  Mechanism names other than INTERNAL
   1.638 +   may be appended with an "=" and BASE64-encoded form of mechanism-
   1.639 +   specific data.
   1.640 +
   1.641 +   This status response code is returned in an untagged OK response in
   1.642 +   response to a RESETKEY, SELECT, or EXAMINE command.  In the case of
   1.643 +   the RESETKEY command, this status response code can be sent in the
   1.644 +   tagged OK response instead of requiring a separate untagged OK
   1.645 +   response.
   1.646 +
   1.647 +   Example:
   1.648 +
   1.649 +      C: a33 RESETKEY INBOX XSAMPLE
   1.650 +      S: a33 OK [URLMECH INTERNAL XSAMPLE=P34OKhO7VEkCbsiYY8rGEg==] done
   1.651 +
   1.652 +   In this example, the server supports the INTERNAL mechanism and an
   1.653 +   experimental mechanism called XSAMPLE, which also holds some
   1.654 +   mechanism-specific data (the name "XSAMPLE" is for illustrative
   1.655 +   purposes only).
   1.656 +
   1.657 +BASE.7.4.GENURLAUTH.   GENURLAUTH Response
   1.658 +
   1.659 +   Contents:   One or more URLs
   1.660 +
   1.661 +   The GENURLAUTH response returns the URLAUTH-authorized URL(s)
   1.662 +   requested by a GENURLAUTH command.
   1.663 +
   1.664 +   Example:
   1.665 +
   1.666 +      C: a777 GENURLAUTH "imap://joe@example.com/INBOX/;uid=20/
   1.667 +         ;section=1.2;urlauth=submit+fred" INTERNAL
   1.668 +      S: * GENURLAUTH "imap://joe@example.com/INBOX/;uid=20/;section=1.2
   1.669 +         ;urlauth=submit+fred:internal:91354a473744909de610943775f92038"
   1.670 +      S: a777 OK GENURLAUTH completed
   1.671 +
   1.672 +
   1.673 +
   1.674 +
   1.675 +
   1.676 +
   1.677 +Crispin                     Standards Track                    [Page 12]
   1.678 +
   1.679 +RFC 4467                IMAP - URLAUTH Extension                May 2006
   1.680 +
   1.681 +
   1.682 +BASE.7.4.URLFETCH.  URLFETCH Response
   1.683 +
   1.684 +   Contents:   One or more URL/nstring pairs
   1.685 +
   1.686 +   The URLFETCH response returns the message text data associated with
   1.687 +   one or more IMAP URLs, as described in [IMAPURL] and extended by this
   1.688 +   document.  This response occurs as the result of a URLFETCH command.
   1.689 +
   1.690 +   The returned data string is NIL if the URL is invalid for any reason
   1.691 +   (including validation failure).  If the URL is valid, but the IMAP
   1.692 +   fetch of the body part returned NIL (this should not happen), the
   1.693 +   returned data string should be the empty string ("") and not NIL.
   1.694 +
   1.695 +      Note: This command does not require that the URL refer to the
   1.696 +      selected mailbox; nor does it require that any mailbox be
   1.697 +      selected.  It also does not in any way interfere with any selected
   1.698 +      mailbox.
   1.699 +
   1.700 +   Example:
   1.701 +
   1.702 +      C: a002 URLFETCH "imap://joe@example.com/INBOX/;uid=20/
   1.703 +         ;section=1.2;urlauth=submit+fred:internal
   1.704 +         :91354a473744909de610943775f92038"
   1.705 +      S: * URLFETCH "imap://joe@example.com/INBOX/;uid=20/;section=1.2
   1.706 +         ;urlauth=submit+fred:internal
   1.707 +         :91354a473744909de610943775f92038" {28}
   1.708 +      S: Si vis pacem, para bellum.
   1.709 +      S:
   1.710 +      S: a002 OK URLFETCH completed
   1.711 +
   1.712 +9.  Formal Syntax
   1.713 +
   1.714 +   The following syntax specification uses the Augmented Backus-Naur
   1.715 +   Form (ABNF) notation as specified in [ABNF].
   1.716 +
   1.717 +   The following modifications are made to the Formal Syntax in [IMAP]:
   1.718 +
   1.719 +resetkey        = "RESETKEY" [SP mailbox *(SP mechanism)]
   1.720 +
   1.721 +capability      =/ "URLAUTH"
   1.722 +
   1.723 +command-auth    =/ resetkey / genurlauth / urlfetch
   1.724 +
   1.725 +resp-text-code  =/ "URLMECH" SP "INTERNAL" *(SP mechanism ["=" base64])
   1.726 +
   1.727 +genurlauth      = "GENURLAUTH" 1*(SP url-rump SP mechanism)
   1.728 +
   1.729 +genurlauth-data = "*" SP "GENURLAUTH" 1*(SP url-full)
   1.730 +
   1.731 +
   1.732 +
   1.733 +Crispin                     Standards Track                    [Page 13]
   1.734 +
   1.735 +RFC 4467                IMAP - URLAUTH Extension                May 2006
   1.736 +
   1.737 +
   1.738 +url-full        = astring
   1.739 +                     ; contains authimapurlfull as defined below
   1.740 +
   1.741 +url-rump        = astring
   1.742 +                     ; contains authimapurlrump as defined below
   1.743 +
   1.744 +urlfetch        = "URLFETCH" 1*(SP url-full)
   1.745 +
   1.746 +urlfetch-data   = "*" SP "URLFETCH" 1*(SP url-full SP nstring)
   1.747 +
   1.748 +   The following extensions are made to the Formal Syntax in [IMAPURL]:
   1.749 +
   1.750 +authimapurl     = "imap://" enc-user [iauth] "@" hostport "/"
   1.751 +                     imessagepart
   1.752 +                     ; replaces "imapurl" and "iserver" rules for
   1.753 +                     ; URLAUTH authorized URLs
   1.754 +
   1.755 +authimapurlfull = authimapurl iurlauth
   1.756 +
   1.757 +authimapurlrump = authimapurl iurlauth-rump
   1.758 +
   1.759 +enc-urlauth     = 32*HEXDIG
   1.760 +
   1.761 +enc-user        = 1*achar
   1.762 +                     ; same as "enc_user" in RFC 2192
   1.763 +
   1.764 +iurlauth        = iurlauth-rump ":" mechanism ":" enc-urlauth
   1.765 +
   1.766 +iurlauth-rump   = [expire] ";URLAUTH=" access
   1.767 +
   1.768 +access          = ("submit+" enc-user) / ("user+" enc-user) /
   1.769 +                    "authuser" / "anonymous"
   1.770 +
   1.771 +expire          = ";EXPIRE=" date-time
   1.772 +                      ; date-time defined in [DATETIME]
   1.773 +
   1.774 +mechanism       = "INTERNAL" / 1*(ALPHA / DIGIT / "-" / ".")
   1.775 +                     ; case-insensitive
   1.776 +                     ; new mechanisms MUST be registered with IANA
   1.777 +
   1.778 +
   1.779 +
   1.780 +
   1.781 +
   1.782 +
   1.783 +
   1.784 +
   1.785 +
   1.786 +
   1.787 +
   1.788 +
   1.789 +Crispin                     Standards Track                    [Page 14]
   1.790 +
   1.791 +RFC 4467                IMAP - URLAUTH Extension                May 2006
   1.792 +
   1.793 +
   1.794 +10.  Security Considerations
   1.795 +
   1.796 +   Security considerations are discussed throughout this memo.
   1.797 +
   1.798 +   The mailbox access key SHOULD have at least 128 bits of entropy
   1.799 +   (refer to [RANDOM] for more details) and MUST be unpredictable.
   1.800 +
   1.801 +   The server implementation of the INTERNAL mechanism SHOULD consider
   1.802 +   the possibility of needing to change the token generation algorithm,
   1.803 +   and SHOULD incorporate some means of identifying the token generation
   1.804 +   algorithm within the token.
   1.805 +
   1.806 +   The URLMECH status response code may expose sensitive data in the
   1.807 +   mechanism-specific data for mechanisms other than INTERNAL.  A server
   1.808 +   implementation MUST implement a configuration that will not return a
   1.809 +   URLMECH status response code unless some mechanism is provided that
   1.810 +   protects the session from snooping, such as a TLS or SASL security
   1.811 +   layer that provides confidentiality protection.
   1.812 +
   1.813 +   The calculation of an authorization token with a "plausible" key if
   1.814 +   the mailbox can not be identified is necessary to avoid attacks in
   1.815 +   which the server is probed to see if a particular mailbox exists on
   1.816 +   the server by measuring the amount of time taken to reject a known
   1.817 +   bad name versus some other name.
   1.818 +
   1.819 +   To protect against a computational denial-of-service attack, a server
   1.820 +   MAY impose progressively longer delays on multiple URL requests that
   1.821 +   fail validation.
   1.822 +
   1.823 +   The decision to use the "authuser" access identifier should be made
   1.824 +   with caution.  An "authuser" access identifier can be used by any
   1.825 +   authorized user of the IMAP server; therefore, use of this access
   1.826 +   identifier should be limited to content that may be disclosed to any
   1.827 +   authorized user of the IMAP server.
   1.828 +
   1.829 +   The decision to use the "anonymous" access identifier should be made
   1.830 +   with extreme caution.  An "anonymous" access identifier can be used
   1.831 +   by anyone; therefore, use of this access identifier should be limited
   1.832 +   to content that may be disclosed to anyone.  Many IMAP servers do not
   1.833 +   permit anonymous access; in this case, the "anonymous" access
   1.834 +   identifier is equivalent to "authuser", but this MUST NOT be relied
   1.835 +   upon.
   1.836 +
   1.837 +   Although this specification does not prohibit the theoretical
   1.838 +   capability to generate a URL with a server component other than the
   1.839 +   logged in userid and server, this capability should only be provided
   1.840 +
   1.841 +
   1.842 +
   1.843 +
   1.844 +
   1.845 +Crispin                     Standards Track                    [Page 15]
   1.846 +
   1.847 +RFC 4467                IMAP - URLAUTH Extension                May 2006
   1.848 +
   1.849 +
   1.850 +   when the logged in userid/server has been authorized as equivalent to
   1.851 +   the server component userid/server, or otherwise has access to that
   1.852 +   userid/server mailbox access key table.
   1.853 +
   1.854 +11.  IANA Considerations
   1.855 +
   1.856 +   This document constitutes registration of the URLAUTH capability in
   1.857 +   the imap4-capabilities registry.
   1.858 +
   1.859 +   URLAUTH authorization mechanisms are registered by publishing a
   1.860 +   standards track or IESG-approved experimental RFC.  The registry is
   1.861 +   currently located at:
   1.862 +
   1.863 +http://www.iana.org/assignments/urlauth-authorization-mechanism-registry
   1.864 +
   1.865 +   This registry is case-insensitive.
   1.866 +
   1.867 +   This document constitutes registration of the INTERNAL URLAUTH
   1.868 +   authorization mechanism.
   1.869 +
   1.870 +   IMAP URLAUTH Authorization Mechanism Registry
   1.871 +
   1.872 +      Mechanism Name           Reference
   1.873 +      --------------           ---------
   1.874 +      INTERNAL                 [RFC4467]
   1.875 +
   1.876 +
   1.877 +
   1.878 +
   1.879 +
   1.880 +
   1.881 +
   1.882 +
   1.883 +
   1.884 +
   1.885 +
   1.886 +
   1.887 +
   1.888 +
   1.889 +
   1.890 +
   1.891 +
   1.892 +
   1.893 +
   1.894 +
   1.895 +
   1.896 +
   1.897 +
   1.898 +
   1.899 +
   1.900 +
   1.901 +Crispin                     Standards Track                    [Page 16]
   1.902 +
   1.903 +RFC 4467                IMAP - URLAUTH Extension                May 2006
   1.904 +
   1.905 +
   1.906 +12.  Normative References
   1.907 +
   1.908 +   [ABNF]     Crocker, D. and P. Overell, "Augmented BNF for Syntax
   1.909 +              Specifications: ABNF", RFC 4234, October 2005.
   1.910 +
   1.911 +   [BURL]     Newman, C., "Message Submission BURL Extension", RFC 4468,
   1.912 +              May 2006.
   1.913 +
   1.914 +   [DATETIME] Klyne, G. and C. Newman, "Date and Time on the Internet:
   1.915 +              Timestamps", RFC 3339, July 2002.
   1.916 +
   1.917 +   [IMAP]     Crispin, M., "Internet Message Access Protocol - Version
   1.918 +              4rev1", RFC 3501, March 2003.
   1.919 +
   1.920 +   [IMAPURL]  Newman, C., "IMAP URL Scheme", RFC 2192, September 1997.
   1.921 +
   1.922 +   [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
   1.923 +              Requirement Levels", BCP 14, RFC 2119, March 1997.
   1.924 +
   1.925 +13.  Informative References
   1.926 +
   1.927 +   [HMAC]     Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed-
   1.928 +              Hashing for Message Authentication", RFC 2104, February
   1.929 +              1997.
   1.930 +
   1.931 +   [RANDOM]   Eastlake, D., 3rd, Schiller, J., and S. Crocker,
   1.932 +              "Randomness Requirements for Security", BCP 106, RFC 4086,
   1.933 +              June 2005.
   1.934 +
   1.935 +Author's Address
   1.936 +
   1.937 +   Mark R. Crispin
   1.938 +   Networks and Distributed Computing
   1.939 +   University of Washington
   1.940 +   4545 15th Avenue NE
   1.941 +   Seattle, WA  98105-4527
   1.942 +
   1.943 +   Phone: (206) 543-5762
   1.944 +   EMail: MRC@CAC.Washington.EDU
   1.945 +
   1.946 +
   1.947 +
   1.948 +
   1.949 +
   1.950 +
   1.951 +
   1.952 +
   1.953 +
   1.954 +
   1.955 +
   1.956 +
   1.957 +Crispin                     Standards Track                    [Page 17]
   1.958 +
   1.959 +RFC 4467                IMAP - URLAUTH Extension                May 2006
   1.960 +
   1.961 +
   1.962 +Full Copyright Statement
   1.963 +
   1.964 +   Copyright (C) The Internet Society (2006).
   1.965 +
   1.966 +   This document is subject to the rights, licenses and restrictions
   1.967 +   contained in BCP 78, and except as set forth therein, the authors
   1.968 +   retain all their rights.
   1.969 +
   1.970 +   This document and the information contained herein are provided on an
   1.971 +   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
   1.972 +   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
   1.973 +   ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
   1.974 +   INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
   1.975 +   INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
   1.976 +   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
   1.977 +
   1.978 +Intellectual Property
   1.979 +
   1.980 +   The IETF takes no position regarding the validity or scope of any
   1.981 +   Intellectual Property Rights or other rights that might be claimed to
   1.982 +   pertain to the implementation or use of the technology described in
   1.983 +   this document or the extent to which any license under such rights
   1.984 +   might or might not be available; nor does it represent that it has
   1.985 +   made any independent effort to identify any such rights.  Information
   1.986 +   on the procedures with respect to rights in RFC documents can be
   1.987 +   found in BCP 78 and BCP 79.
   1.988 +
   1.989 +   Copies of IPR disclosures made to the IETF Secretariat and any
   1.990 +   assurances of licenses to be made available, or the result of an
   1.991 +   attempt made to obtain a general license or permission for the use of
   1.992 +   such proprietary rights by implementers or users of this
   1.993 +   specification can be obtained from the IETF on-line IPR repository at
   1.994 +   http://www.ietf.org/ipr.
   1.995 +
   1.996 +   The IETF invites any interested party to bring to its attention any
   1.997 +   copyrights, patents or patent applications, or other proprietary
   1.998 +   rights that may cover technology that may be required to implement
   1.999 +   this standard.  Please address the information to the IETF at
  1.1000 +   ietf-ipr@ietf.org.
  1.1001 +
  1.1002 +Acknowledgement
  1.1003 +
  1.1004 +   Funding for the RFC Editor function is provided by the IETF
  1.1005 +   Administrative Support Activity (IASA).
  1.1006 +
  1.1007 +
  1.1008 +
  1.1009 +
  1.1010 +
  1.1011 +
  1.1012 +
  1.1013 +Crispin                     Standards Track                    [Page 18]
  1.1014 +