[Docs] [txt|pdf|xml|html] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01 02 03

Network Working Group                                           C. Daboo
Internet-Draft                                                     Apple
Intended status: Standards Track                             A. Quillaud
Expires: November 3, 2012                                         Oracle
                                                             May 2, 2012


                       CalDAV Managed Attachments
                   draft-daboo-caldav-attachments-01

Abstract

   This document defines how CalDAV servers can provide server managed
   collections to allow attachments associated with iCalendar data, to
   be stored and managed on the server.

Status of this Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   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."

   This Internet-Draft will expire on November 3, 2012.

Copyright Notice

   Copyright (c) 2012 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.




Daboo & Quillaud        Expires November 3, 2012                [Page 1]


Internet-Draft         CalDAV Managed Attachments               May 2012


Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
   2.  Conventions Used in This Document  . . . . . . . . . . . . . .  3
   3.  Open Issues (to be removed prior to publication as a RFC)  . .  4
   4.  Overview . . . . . . . . . . . . . . . . . . . . . . . . . . .  4
     4.1.  Requirements . . . . . . . . . . . . . . . . . . . . . . .  4
     4.2.  Discovering Support for Managed Attachments  . . . . . . .  5
     4.3.  POST Request for Managing Attachments  . . . . . . . . . .  5
     4.4.  Adding attachments . . . . . . . . . . . . . . . . . . . .  6
     4.5.  Updating Attachments . . . . . . . . . . . . . . . . . . .  9
     4.6.  Removing Attachments via POST  . . . . . . . . . . . . . . 12
     4.7.  Adding Existing Managed Attachments via PUT  . . . . . . . 13
     4.8.  Updating Attachments via PUT . . . . . . . . . . . . . . . 13
     4.9.  Removing Attachments via PUT . . . . . . . . . . . . . . . 13
     4.10. Retrieving Attachments . . . . . . . . . . . . . . . . . . 14
     4.11. Additional Considerations  . . . . . . . . . . . . . . . . 14
   5.  Modifications to iCalendar Syntax  . . . . . . . . . . . . . . 15
     5.1.  SIZE Property Parameter  . . . . . . . . . . . . . . . . . 15
     5.2.  FILENAME Property Parameter  . . . . . . . . . . . . . . . 16
     5.3.  MANAGED-ID Property Parameter  . . . . . . . . . . . . . . 16
     5.4.  MTAG Property Parameter  . . . . . . . . . . . . . . . . . 17
   6.  Additional Message Header Fields . . . . . . . . . . . . . . . 17
     6.1.  Cal-Managed-ID Response Header . . . . . . . . . . . . . . 17
   7.  Additional WebDAV properties . . . . . . . . . . . . . . . . . 18
     7.1.  CALDAV:managed-attachments-server-URL property . . . . . . 18
   8.  Security Considerations  . . . . . . . . . . . . . . . . . . . 19
   9.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 19
     9.1.  Parameter Registrations  . . . . . . . . . . . . . . . . . 19
     9.2.  Message Header Field Registrations . . . . . . . . . . . . 19
   10. Acknowledgments  . . . . . . . . . . . . . . . . . . . . . . . 19
   11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 20
     11.1. Normative References . . . . . . . . . . . . . . . . . . . 20
     11.2. Informative References . . . . . . . . . . . . . . . . . . 20
   Appendix A.  Change History (To be removed by RFC Editor
                before publication) . . . . . . . . . . . . . . . . . 21
   Appendix B.  Example Involving Recurring Events  . . . . . . . . . 21
   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 25













Daboo & Quillaud        Expires November 3, 2012                [Page 2]


Internet-Draft         CalDAV Managed Attachments               May 2012


1.  Introduction

   The iCalendar [RFC5545] data format is used to represent calendar
   data and is used with iTIP [RFC5546] to handle scheduling operations
   between calendar users.

   [RFC4791] defines the CalDAV Calendar Access protocol, based on HTTP
   [RFC2616], for accessing calendar data stored on a server.

   Calendar users often want to include attachments with their calendar
   data events or tasks (for example a copy of a presentation, or the
   meeting agenda). iCalendar provides an "ATTACH" property whose value
   is either the inline Base64 encoded attachment data, or a URL
   specifying the location of the attachment data.

   Use of inline attachment data is not ideal with CalDAV because the
   data would need to be uploaded to the server each time a change to
   the calendar data is done - even minor changes such as a change to
   the summary.  Whilst a client could choose to use a URL value
   instead, the problem then becomes where and how the client discovers
   an appropriate URL to use and how it ensures that only those
   attendees listed in the event or task are able to access it.

   This specification provides a solution to this problem whereby the
   client sends the attachment to the server separately from the
   iCalendar data and the server takes care of adding appropriate
   "ATTACH" properties in the iCalendar data as well as managing
   privileges .  The server can also provide additional information to
   the client about each attachment, such as the size and an identifier,
   so clients can manage their list of attachments directly from the
   calendar data.


2.  Conventions Used in This Document

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in
   [RFC2119].

   The notation used in this memo is the ABNF notation of [RFC5234] as
   used by iCalendar [RFC5545].  Any syntax elements shown below that
   are not explicitly defined in this specification come from iCalendar
   [RFC5545].







Daboo & Quillaud        Expires November 3, 2012                [Page 3]


Internet-Draft         CalDAV Managed Attachments               May 2012


3.  Open Issues (to be removed prior to publication as a RFC)

   1.  Do we need a way to allow for multiple attachments to be added,
       updated or removed in a single POST (batching)?

   2.  Do we need a way for the server to indicate limits for managed
       attachments (individual size, total size, total number etc).
       Also a way for a server to indicate it does not allow inline
       attachments?

   3.  Should we say anything about servers automatically stripping
       inline attachments and making them managed?

   4.  Do we want to allow reusing of an existing ATTACH (with MTAG/
       MANAGED-ID) in multiple calendar object resources (4.6)?


4.  Overview

   There are four main operations a client needs to do with attachments
   for calendar data: add, update, remove, and retrieve.  The first
   three operations are carried out by the client issuing an HTTP POST
   request on the calendar object resource to which the attachment is
   associated and specifying the appropriate action query parameter.  In
   the case of the remove operation, the client can alternatively
   directly update the calendar object resource and remove the relevant
   "ATTACH" properties.  The retrieve operation is accomplished by
   simply issuing an HTTP GET request targeting the attachment URI
   specified by the calendar resource's ATTACH property.

   iCalendar data stored in a CalDAV calendar object resource can
   contain multiple components when recurrences are involved.  In such a
   situation, the client needs to be able to target a specific
   recurrence instance or multiple instances when adding or deleting
   attachments.  As a result, the POST request needs to provide a way
   for the client to specify which recurrence instances should be
   targeted for the attachment operation.  This is accomplished through
   use of additional query parameters on the POST request-URI.

4.1.  Requirements

   A server that supports the features described in this document is
   REQUIRED to support the CalDAV "calendar-access" [RFC4791] features.

   In addition, such server MUST honor the "return-representation"
   Prefer header value [I-D.snell-http-prefer] on both HTTP PUT and POST
   successful requests targeting existing calendar object resources, by
   returning the new representation of that calendar resource (including



Daboo & Quillaud        Expires November 3, 2012                [Page 4]


Internet-Draft         CalDAV Managed Attachments               May 2012


   its new Etag header value) in the response.  The same behavior is
   expected in the case of a successful HTTP PUT request to create a new
   calendar object resource.

4.2.  Discovering Support for Managed Attachments

   A server supporting the features described in this document MUST
   include "calendar-managed-attachments" as a field in the DAV response
   header from an OPTIONS request on a calendar home collection.

4.3.  POST Request for Managing Attachments

   An HTTP POST request is used to add, update, or remove attachments.
   The request-URI will contain various query parameters to specify the
   behavior.

4.3.1.  action= Query Parameter

   The "action" query parameter is used to identify which attachment
   operation the client is requesting.  This parameter MUST be present
   once on each POST request used to manage attachments.  One of these
   three values MUST be used:

   attachment-add  Indicates an operation that is adding an attachment
      to a calendar object resource.  See Section 4.4 for more details.

   attachment-update  Indicates an operation that is updating an
      existing attachment on a calendar object resource.  See
      Section 4.5 for more details.

   attachment-remove  Indicates an operation that is removing an
      attachment on a calendar object resource.  See Section 4.6 for
      more details.

   Example:
   http://calendar.example.com/events/1.ics?action=attachment-add

4.3.2.  rid= Query Parameter

   The "rid" query parameter is used to identify which recurrence
   instances are being targeted by the client for the attachment
   operation.  This query parameter MUST contain one or more items,
   separated by commas (0x2C).  The item values can be in one of two
   forms:







Daboo & Quillaud        Expires November 3, 2012                [Page 5]


Internet-Draft         CalDAV Managed Attachments               May 2012


   Master instance  The value "M" (case-insensitive) refers to the
      "master" recurrence instance, i.e., the component that does not
      include a "RECURRENCE-ID" property.  This item MUST be present
      only once.

   Specific instance  A specific iCalendar instance is targeted by using
      its "RECURRENCE-ID" value as the item value.  That value MUST
      correspond to the RECURRENCE-ID value as stored in the calendar
      object resource (i.e. without any conversion to UTC).  If multiple
      items of this form are used, they MUST be unique values.

   If the "rid" query parameter is not present, all recurrence instances
   in the calendar object resource are targeted.

   The "rid" query parameter MUST NOT be present in the case of an
   update operation.

   Example:
   http://calendar.example.com/events/1.ics?
     action=attachment-add&rid=M,20111022T160000

4.3.3.  managed-id= Query Parameter

   The "managed-id" query parameter is used to identify which "ATTACH"
   property is being updated or removed.  The value of this query
   parameter MUST match the "MANAGED-ID" property parameter value on the
   "ATTACH" property in the calendar object resource instance(s)
   targeted by the request.

   The "managed-id" query parameter MUST NOT be present in the case of
   an add operation.

   Example:
   http://calendar.example.com/events/1.ics?
     action=attachment-update&managed-id=aUNhbGVuZGFy

4.4.  Adding attachments

   To add an attachment to an existing calendar object resource, the
   following occurs:

   1.  The client issues a POST request targeted at the calendar object
       resource.

       A.  The request-URI will include an "action" query parameter with
           the value "attachment-add" (see Section 4.3.1).





Daboo & Quillaud        Expires November 3, 2012                [Page 6]


Internet-Draft         CalDAV Managed Attachments               May 2012


       B.  If all recurrence instances are having an attachment added,
           the "rid" query parameter is not present in the request-URI.
           If one or more specific recurrence instances are targeted,
           then the request-URI will include a "rid" query parameter
           containing the list of instances (see Section 4.3.2).

       C.  The body of the request contains the data for the attachment.

       D.  The client MUST include a valid Content-Type HTTP header
           describing the media type of the attachment (as required by
           HTTP).

       E.  The client SHOULD include a Content-Disposition HTTP header
           [RFC6266] with a "type" parameter set to "attachment", and a
           "filename" parameter that indicates the name of the
           attachment.

   2.  When the server receives the POST request it does the following:

       A.  Validates that any recurrence instances referred to via the
           "rid" query parameter are valid for the calendar object
           resource being targeted.

       B.  Stores the supplied attachment data into a resource and
           generates an appropriate URI for clients to access the
           resource.

       C.  For each affected recurrence instance in the calendar object
           resource targeted by the request, the server adds an "ATTACH"
           property, whose value is the URI of the stored attachment.
           The "ATTACH" property MUST contain a "MANAGED-ID" parameter
           whose value is a unique identifier (within the context of the
           server as a whole).  The "ATTACH" property MUST contain an
           "MTAG" parameter whose value represents the initial state of
           the attachment.  The "ATTACH" property SHOULD contain an
           "FMTTYPE" parameter whose value matches the Content-Type
           header value from the request.  The "ATTACH" property SHOULD
           contain an "FILENAME" parameter whose value matches the
           Content-Disposition header "Filename" parameter value from
           the request, taking into account the restrictions expressed
           in Section 5.2.  The "ATTACH" property SHOULD include a
           "SIZE" parameter whose value represents the size in octets of
           the attachment.  Note that if a specified recurrence instance
           does not have a matching component in the calendar object
           resource, then the server MUST modify the calendar object
           resource to include the overridden component with the
           appropriate "RECURRENCE-ID" property included.




Daboo & Quillaud        Expires November 3, 2012                [Page 7]


Internet-Draft         CalDAV Managed Attachments               May 2012


       D.  Upon successful creation of the attachment resource and
           modification of the targeted calendar object resource, the
           server MUST return a 201 HTTP status response and include a
           "Cal-Managed-ID" HTTP header containing the MANAGED-ID
           parameter value of the newly created "ATTACH" property.  The
           client can use the "Cal-Managed-ID" header value to correlate
           the attachment with "ATTACH" properties added to the calendar
           object resource.  It is expected that the client will
           immediately reload the calendar object resource to refresh
           any local cache.

   In the following example, the client adds a new attachment to a non
   recurring event and asks the server (via the Prefer
   [I-D.snell-http-prefer] HTTP header) to return the updated version of
   that event in the response.

   >> Request <<


   POST /events/64.ics?action=attachment-add HTTP/1.1
   Host: cal.example.com
   Content-Type: text/html; charset="utf-8"
   Content-Disposition:attachment;filename=agenda.html
   Content-Length: xxxx
   Prefer: return-representation

   <html>
     <body>
       <h1>Agenda</h1>
     </body>
   </html




















Daboo & Quillaud        Expires November 3, 2012                [Page 8]


Internet-Draft         CalDAV Managed Attachments               May 2012


   >> Response <<


   HTTP/1.1 201 Created
   Content-Type: text/calendar charset="utf-8"
   Content-Length: yyyy
   Content-Location: http://cal.example.com/events/64.ics
   ETag: "123456789-000-111"
   Cal-Managed-ID: 97S

   BEGIN:VCALENDAR
   VERSION:2.0
   PRODID:-//Example Corp.//CalDAV Server//EN
   BEGIN:VEVENT
   UID:20010712T182145Z-123401@example.com
   DTSTAMP:20120201T203412Z
   DTSTART:20120714T170000Z
   DTEND:20120715T040000Z
   SUMMARY:One-off meeting
   ATTACH;MANAGED-ID=97S;MTAG=987654321-555-441;FMT-TYPE=text/html;
    SIZE=xxxx;
    FILENAME=agenda.html:https://cal.example.com/attach/64/34X22R
   END:VEVENT
   END:VCALENDAR


4.5.  Updating Attachments

   To change the data of an existing managed attachment in a calendar
   object resource, the following occurs:

   1.  The client issues a POST request targeted at the calendar object
       resource.

       A.  The request-URI will include an "action" query parameter with
           the value "attachment-update" (see Section 4.3.1).

       B.  The request-URI will include an "managed-id" query parameter
           with the value matching that of the "MANAGED-ID" property
           parameter for the "ATTACH" property being updated (see
           Section 4.3.3).

       C.  The body of the request contains the updated data for the
           attachment.

       D.  The client MUST include a valid Content-Type header
           describing the media type of the attachment (as required by
           HTTP).



Daboo & Quillaud        Expires November 3, 2012                [Page 9]


Internet-Draft         CalDAV Managed Attachments               May 2012


       E.  The client SHOULD include a Content-Disposition header
           [RFC6266] with a "type" parameter set to "attachment", and a
           "filename" parameter that indicates the name of the
           attachment.

   2.  When the server receives the POST request it does the following:

       A.  Validates that the "managed-id" query parameter is valid for
           the calendar object resource.

       B.  Updates the content of the attachment resource corresponding
           to that managed-id with the supplied attachment data.

       C.  For each affected recurrence instance in the calendar object
           resource targeted by the request, the server updates the
           "ATTACH" property whose "MANAGED-ID" property parameter value
           matches the "managed-id" query parameter.  The "ATTACH"
           property value (attachment URI) MUST remain the same.  The
           "ATTACH" property MUST contain an "MTAG" parameter whose
           value represents the new state of the attachment.  The
           "ATTACH" property SHOULD contain an "FMTTYPE" parameter whose
           value matches the Content-Type header value from the request
           - this could differ from the original value if the media type
           of the updated attachment is different.  The "ATTACH"
           property SHOULD contain an "FILENAME" parameter whose value
           matches the Content-Disposition header "Filename" parameter
           value from the request, taking into account the restrictions
           expressed in Section 5.2.  The "ATTACH" property SHOULD
           include a "SIZE" parameter whose value represents the size in
           octets of the updated attachment.

       D.  Upon successful update of the attachment resource and
           modification of the targeted calendar object resource, the
           server MUST return a 200 HTTP status response.  It is
           expected that the client will immediately reload the calendar
           object resource to refresh any local cache.

   The update operation does not take an "rid" parameter and does not
   add, nor remove, any "ATTACH" property in the targetted calendar
   object resource.  To link an existing attachment to a new instance,
   the client simply does a PUT on the calendar object resource, adding
   an "ATTACH" property with the correct "MANAGED-ID" and URI value to
   that instance (see Section 4.7).

   In the following example, the client updates an existing attachment
   and asks the server (via the Prefer [I-D.snell-http-prefer] HTTP
   header) to return the updated version of that event in the response.




Daboo & Quillaud        Expires November 3, 2012               [Page 10]


Internet-Draft         CalDAV Managed Attachments               May 2012


   >> Request <<


   POST /events/64.ics?action=attachment-update&managed-id=97S HTTP/1.1
   Host: cal.example.com
   Content-Type: text/html; charset="utf-8"
   Content-Disposition:attachment;filename=agenda.html
   Content-Length: xxxx
   Prefer: return-representation

   <html>
     <body>
       <h1>Agenda</h1>
       <p>Discuss attachment draft</p>
     </body>
   </html



   >> Response <<


   HTTP/1.1 200 OK
   Content-Type: text/calendar charset="utf-8"
   Content-Length: yyyz
   Content-Location: http://cal.example.com/events/64.ics
   ETag: "123456789-000-222"

   BEGIN:VCALENDAR
   VERSION:2.0
   PRODID:-//Example Corp.//CalDAV Server//EN
   BEGIN:VEVENT
   UID:20010712T182145Z-123401@example.com
   DTSTAMP:20120201T203412Z
   DTSTART:20120714T170000Z
   DTEND:20120715T040000Z
   SUMMARY:One-off meeting
   ATTACH;MANAGED-ID=97S;MTAG=987654321-555-666;FMT-TYPE=text/html;
    SIZE=xxxy;
    FILENAME=agenda.html:https://cal.example.com/attach/64/34X22R
   END:VEVENT
   END:VCALENDAR









Daboo & Quillaud        Expires November 3, 2012               [Page 11]


Internet-Draft         CalDAV Managed Attachments               May 2012


4.6.  Removing Attachments via POST

   To remove an existing attachment from a calendar object, the
   following occurs:

   1.  The client issues a POST request targeted at the calendar object
       resource.

       A.  The request-URI will include an "action" query parameter with
           the value "attachment-remove" (see Section 4.3.1).

       B.  If all recurrence instances are having an attachment removed,
           the "rid" query parameter is not present in the request-URI.
           If one or more specific recurrence instances are targeted,
           then the request-URI will include a "rid" query parameter
           containing the list of instances (see Section 4.3.2).

       C.  The request-URI will include a "managed-id" query parameter
           with the value matching that of the "MANAGED-ID" property
           parameter for the "ATTACH" property being removed (see
           Section 4.3.3).

       D.  The body of the request will be empty.

   2.  When the server receives the POST request it does the following:

       A.  Validates that any recurrence instances referred to via the
           "rid" query parameter are valid for the calendar object
           resource being targeted.

       B.  Validates that the "managed-id" query parameter is valid for
           the calendar object resource and specific instances being
           targeted.

       C.  For each affected recurrence instance in the calendar object
           resource targeted by the request, the server removes the
           matching "ATTACH" property.  Note that if a specified
           recurrence instance does not have a matching component in the
           calendar object resource, then the server MUST modify the
           calendar object resource to include the overridden component
           with the appropriate "RECURRENCE-ID" property included, and
           the matching "ATTACH" property removed.  This later case is
           actually valid only if the master component does include the
           referenced "ATTACH" property.

       D.  If the attachment resource is no longer referenced by any
           instance of the calendar object resource, the server MUST
           delete the attachment resource.



Daboo & Quillaud        Expires November 3, 2012               [Page 12]


Internet-Draft         CalDAV Managed Attachments               May 2012


       E.  Upon successful removal of the attachment resource and
           modification of the targeted calendar object resource, the
           server MUST return a 200 HTTP status response.  It is
           expected that the client will immediately reload the calendar
           object resource to refresh any local cache.

   In the following example, the client deletes an existing attachment
   by passing its managed-id in the request.  The Prefer
   [I-D.snell-http-prefer] HTTP header is not set in the request so the
   calendar resource is not returned in the response.

   >> Request <<


   POST /events/64.ics?action=attachment-remove&managed-id=97S HTTP/1.1
   Host: cal.example.com
   Content-Length: 0



   >> Response <<


   HTTP/1.1 200 No Content
   Content-Length: 0



4.7.  Adding Existing Managed Attachments via PUT

   Clients can make use of existing managed attachments by adding the
   corresponding "ATTACH" property to calendar object resources (subject
   to the restrictions described in Section 4.11.2).

4.8.  Updating Attachments via PUT

   Servers MUST NOT allow clients to update attachment data directly via
   a PUT on the attachment URI (or via any other HTTP method that
   modifies content).

4.9.  Removing Attachments via PUT

   Clients can remove attachments by simply re-writing the calendar
   object resource data to remove the appropriate "ATTACH" properties.







Daboo & Quillaud        Expires November 3, 2012               [Page 13]


Internet-Draft         CalDAV Managed Attachments               May 2012


4.10.  Retrieving Attachments

   Clients retrieve attachments by simply issuing an HTTP GET request
   using the value of the corresponding "ATTACH" property as the
   request-URI, taking into account the substitution mechanism
   associated with the "CALDAV:managed-attachments-server-URL" property
   (see Section 7.1).

4.11.  Additional Considerations

4.11.1.  Error Handling

   TODO: error codes for each request.

4.11.2.  Access Control

   TODO: talk about authentication for attachment URIs, access limited
   to attendees only, or token based, only organizer able to re-use
   "ATTACH" properties.

4.11.3.  Redirects

   For POST requests that add or update attachment data, the server MAY
   issue an HTTP redirect to require the client to re-issue the POST
   request using a different request-URI.  As a result, it is always
   best for clients to use the "100 Continue" behavior defined in
   Section 8.2.3 of [RFC2616].  Using this mechanism ensures that, if a
   redirect does occur, the client does not needlessly send the
   attachment data.

   When servers do redirect clients to a different request-URI, they
   SHOULD ensure that the authentication/authorization for the
   redirected URI falls within the same domain realm as that of the
   original URI, so that the client can re-use credentials without
   having to prompt the user.

4.11.4.  Automatic Clean-up by servers

   Servers MAY automatically remove attachment data as appropriate, for
   example to regain the storage taken by unused attachments, or as the
   result of a virus scanning.  When doing so they SHOULD NOT modify
   calendar data referencing those attachments.  Instead they SHOULD
   return a 410 HTTP status response to any request on the removed
   attachment URI.







Daboo & Quillaud        Expires November 3, 2012               [Page 14]


Internet-Draft         CalDAV Managed Attachments               May 2012


4.11.5.  Sending Scheduling Messages with Attachments

   When a managed attachment is added, updated or removed from a
   calendar object resource, the server MUST ensure that a scheduling
   message is sent to update any Attendees with the changes, as per
   [I-D.desruisseaux-caldav-sched].

4.11.6.  Attendees managing Attachments

   TODO: how do we do this?  Organizer adds a property to calendar data
   to say attendees can add attachments, but how does scheduling happen?

4.11.7.  Other Client Considerations

   Clients can expect servers to take a while to respond to POST
   requests that include large attachment bodies.  Servers SHOULD use
   the "100 Continue" behavior defined in Section 8.2.3 of [RFC2616] to
   keep the client connection alive if the response will take some time.

   When exporting calendar data from a CalDAV server supporting managed
   attachments, clients SHOULD remove all "MANAGED-ID" property
   parameters from "ATTACH" properties in the calendar data.  Similarly
   when importing calendar data from another source, clients SHOULD
   remove any "MANAGED-ID" property parameters on "ATTACH" properties
   (failure to do so will likely result in the server removing those
   properties automatically).


5.  Modifications to iCalendar Syntax

5.1.  SIZE Property Parameter

   Parameter Name:  SIZE

   Purpose:  To specify the size of an attachment.

   Format Definition:  This property parameter is defined by the
      following notation:

   sizeparam = "SIZE" "=" paramtext
   ; positive integers

   Description:  This property parameter MAY be specified on "ATTACH"
      properties.  It indicates the size in octets of the corresponding
      attachment data.  Since iCalendar integer values are restricted to
      a maximum value of 2147483647, the current parameter is defined as
      text to allow an extended range to be used.




Daboo & Quillaud        Expires November 3, 2012               [Page 15]


Internet-Draft         CalDAV Managed Attachments               May 2012


   Example:

   ATTACH;SIZE=1234:http://attachments.example.com/abcd.txt

5.2.  FILENAME Property Parameter

   Parameter Name:  FILENAME

   Purpose:  To specify the file name of a managed attachment.

   Format Definition:  This property parameter is defined by the
      following notation:

   filenameparam = "FILENAME" "=" paramtext

   Description:  This property parameter MAY be specified on "ATTACH"
      properties corresponding to managed attachments.  Its value
      provides information on how to construct a filename for storing
      the attachment data.  This parameter is very similar in nature to
      the Content-Disposition HTTP header "filename" parameter and
      exposes the same security risks.  As a consequence, clients MUST
      follow the guidelines expressed in Section 4.3 of [RFC6266] when
      consuming this parameter value.  Similarly, servers MUST follow
      those same guidelines before storing a value.

   Example:

   ATTACH;FILENAME=agenda.html:http://attachments.example.c
    om/rt452S

5.3.  MANAGED-ID Property Parameter

   Parameter Name:  MANAGED-ID

   Purpose:  To uniquely identify a managed attachment.

   Format Definition:  This property parameter is defined by the
      following notation:

   managedidparam = "MANAGED-ID" "=" paramtext

   Description:  This property parameter MUST be specified on "ATTACH"
      properties corresponding to managed attachments.  Its value is
      generated by the server and uniquely identifies a managed
      attachment.  This property parameter MUST NOT be present in the
      case of non managed attachments.





Daboo & Quillaud        Expires November 3, 2012               [Page 16]


Internet-Draft         CalDAV Managed Attachments               May 2012


   Example:

   ATTACH;MANAGED-ID=aUNhbGVuZGFy:http://attachments.example.c
    om/abcd.txt

5.4.  MTAG Property Parameter

   Parameter Name:  MTAG

   Purpose:  To track changes made to a managed attachment.

   Format Definition:  This property parameter is defined by the
      following notation:

   mtagparam = "MTAG" "=" paramtext

   Description:  This property parameter MUST be specified on "ATTACH"
      properties corresponding to managed attachments.  Its value is an
      opaque token, that represents the state of the attachment resource
      at a given point in time.  It MUST be unique across all versions
      of a given resource.  Servers MUST change the MTAG value whenever
      an attachment resource content is modified, thus allowing clients
      to use it as a change token.  This property parameter MUST NOT be
      present in the case of non managed attachments.

   Example:

   ATTACH;MTOKEN=12C:http://attachments.example.c
    om/abcd.txt


6.  Additional Message Header Fields

6.1.  Cal-Managed-ID Response Header

   The Cal-Managed-ID response header provides the value of the
   MANAGED-ID parameter corresponding to a newly added ATTACH property.
   It MUST be sent only in response to a successful POST request with an
   action set to attachment-add.

       Cal-Managed-ID = "Cal-Managed-ID" ":" paramtext
       ; "paramtext" is defined in Section 3.1 of [RFC5545]

   Example:

   Cal-Managed-ID:aUNhbGVuZGFy





Daboo & Quillaud        Expires November 3, 2012               [Page 17]


Internet-Draft         CalDAV Managed Attachments               May 2012


7.  Additional WebDAV properties

7.1.  CALDAV:managed-attachments-server-URL property

   Name:  managed-attachments-server-URL

   Namespace:  urn:ietf:params:xml:ns:caldav

   Purpose:  Specifies the server base URI to use when retrieving
      managed attachments.

   Protected:  This property MUST be protected as only the server can
      update the value.

   COPY/MOVE behavior:  This property is only defined on a calendar home
      collection which cannot be moved or copied.

   Description:  This property MAY be defined on a calendar home
      collection.  If present, it contains zero or one DAV:href XML
      elements.

      When one DAV:href element is present, its value MUST be an
      absolute HTTP URI containing only the scheme (i.e. "https") and
      authority (i.e. host and port) parts .  Whenever a managed
      attachment is to be retrieved via an HTTP GET, the client MUST
      construct the actual URL of the attachment by substituting the
      scheme and authority parts of the attachment URI (as stored in the
      iCalendar ATTACH property) with the present WebDAV property value.

      When no DAV:href element is present, the client MUST substitute
      the scheme and authority parts of the attachment URI with the
      scheme and authority part of the calendar home collection absolute
      URI.

      In the absence of this property, the client can consider the
      attachment URI as its actual URL.

   Definition:

     <!ELEMENT managed-attachments-server-URL (DAV:href?)>

   Example:

     <C:managed-attachments-server-URL xmlns:D="DAV:"
         xmlns:C="urn:ietf:params:xml:ns:caldav">
       <D:href>https://attachstore.example.com</D:href>
     </C:managed-attachments-server-URL>




Daboo & Quillaud        Expires November 3, 2012               [Page 18]


Internet-Draft         CalDAV Managed Attachments               May 2012


8.  Security Considerations

   TODO:servers need to enforce quotas, attachments could contain
   malicious content (virus checking could be done)


9.  IANA Considerations

9.1.  Parameter Registrations

   This documents defines the following new iCalendar property
   parameters to be added to the registry defined in Section 8.2.3 of
   [RFC5545]:

          +--------------------+---------+----------------------+
          | Property Parameter | Status  | Reference            |
          +--------------------+---------+----------------------+
          | FILENAME           | Current | RFCXXXX, Section 5.2 |
          | MTAG               | Current | RFCXXXX, Section 5.4 |
          | SIZE               | Current | RFCXXXX, Section 5.1 |
          | MANAGED-ID         | Current | RFCXXXX, Section 5.3 |
          +--------------------+---------+----------------------+

9.2.  Message Header Field Registrations

   The message header fields below should be added to the Permanent
   Message Header Field Registry (see [RFC3864]).

9.2.1.  Cal-Managed-ID

   Header field name: Cal-Managed-ID

   Applicable protocol: http

   Status: standard

   Author/Change controller: IETF

   Specification document(s): this specification (Section 6.1)

   Related information: none


10.  Acknowledgments

   This specification came about via discussions at the Calendaring and
   Scheduling Consortium.




Daboo & Quillaud        Expires November 3, 2012               [Page 19]


Internet-Draft         CalDAV Managed Attachments               May 2012


11.  References

11.1.  Normative References

   [I-D.desruisseaux-caldav-sched]
              Daboo, C. and B. Desruisseaux, "CalDAV Scheduling
              Extensions to WebDAV", draft-desruisseaux-caldav-sched-10
              (work in progress), September 2011.

   [I-D.snell-http-prefer]
              Snell, J., "Prefer Header for HTTP",
              draft-snell-http-prefer-12 (work in progress),
              February 2012.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC2616]  Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
              Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
              Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.

   [RFC3864]  Klyne, G., Nottingham, M., and J. Mogul, "Registration
              Procedures for Message Header Fields", BCP 90, RFC 3864,
              September 2004.

   [RFC4791]  Daboo, C., Desruisseaux, B., and L. Dusseault,
              "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791,
              March 2007.

   [RFC5234]  Crocker, D. and P. Overell, "Augmented BNF for Syntax
              Specifications: ABNF", STD 68, RFC 5234, January 2008.

   [RFC5545]  Desruisseaux, B., "Internet Calendaring and Scheduling
              Core Object Specification (iCalendar)", RFC 5545,
              September 2009.

   [RFC6266]  Reschke, J., "Use of the Content-Disposition Header Field
              in the Hypertext Transfer Protocol (HTTP)", RFC 6266,
              June 2011.

11.2.  Informative References

   [RFC5546]  Daboo, C., "iCalendar Transport-Independent
              Interoperability Protocol (iTIP)", RFC 5546,
              December 2009.






Daboo & Quillaud        Expires November 3, 2012               [Page 20]


Internet-Draft         CalDAV Managed Attachments               May 2012


Appendix A.  Change History (To be removed by RFC Editor before
             publication)

   Changes in -01:

   1.   Tweaked OPTIONS capability wording.

   2.   Added section on clients expecting 100-Continue for delayed
        response.

   3.   Added text for clean-up and use of HTTP 410 on orphans.

   4.   Added text on removing "MANAGED-ID" when exporting/importing
        calendar data.

   5.   Added protocol examples.

   6.   Added MTAG property parameter on ATTACH property

   7.   Added FILENAME property parameter on ATTACH property

   8.   "id" query parameter is now "managed-id".

   9.   Use of Cal-Managed-ID header instead of Location header in
        responses.

   10.  rid query param MUST contain RECURRENCE-ID without any
        conversion to UTC (case of floating events).

   11.  Introduced CALDAV:managed-attachments-server-URL property

   12.  Made support for Prefer header a MUST for servers.


Appendix B.  Example Involving Recurring Events

   In the following example, the organizer of a recurring meeting adds
   an agenda (HTML attachment) to the corresponding calendar resource.
   Attendees of the meeting are granted read access to the newly created
   attachment resource.  Their own copy of the meeting is updated to
   include the new ATTACH property pointing to the attachment resource
   and they are notified of the change via their scheduling inbox.









Daboo & Quillaud        Expires November 3, 2012               [Page 21]


Internet-Draft         CalDAV Managed Attachments               May 2012


   >> Request <<


   POST /events/65.ics?action=attachment-add HTTP/1.1
   Host: cal.example.com
   Content-Type: text/html; charset="utf-8"
   Content-Disposition:attachment;filename=agenda.html
   Content-Length: xxxx
   Prefer: return-representation

   <html>
     <body>
       <h1>Agenda</h1>
       <p>As usual</p>
     </body>
   </html



































Daboo & Quillaud        Expires November 3, 2012               [Page 22]


Internet-Draft         CalDAV Managed Attachments               May 2012


   >> Response <<


HTTP/1.1 201 Created
Content-Type: text/calendar charset="utf-8"
Content-Length: yyyy
Content-Location: http://cal.example.com/events/65.ics
ETag: "123456789-000-111"
Cal-Managed-ID: 97S

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example Corp.//CalDAV Server//EN
BEGIN:VTIMEZONE
LAST-MODIFIED:20040110T032845Z
TZID:US/Eastern
BEGIN:DAYLIGHT
DTSTART:20000404T020000
RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4
TZNAME:EDT
TZOFFSETFROM:-0500
TZOFFSETTO:-0400
END:DAYLIGHT
BEGIN:STANDARD
DTSTART:20001026T020000
RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10
TZNAME:EST
TZOFFSETFROM:-0400
TZOFFSETTO:-0500
END:STANDARD
END:VTIMEZONE
BEGIN:VEVENT
UID:20010712T182145Z-123401@example.com
DTSTAMP:20120201T203412Z
DTSTART;TZID=US/Eastern:20120206T100000
DURATION:PT1H
RRULE:FREQ=WEEKLY
SUMMARY:Planning Meeting
ORGANIZER:mailto:cyrus@example.com
ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:cyrus@example.com
ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:arnaudq@example.com
ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=NEEDS-ACTION:mailto:mike@example.com
ATTACH;MANAGED-ID=97S;MTAG=987654321-555-441;FMT-TYPE=text/html;
 SIZE=xxxx;
 FILENAME=agenda.html:https://cal.example.com/attach/65/34X22R
END:VEVENT
END:VCALENDAR




Daboo & Quillaud        Expires November 3, 2012               [Page 23]


Internet-Draft         CalDAV Managed Attachments               May 2012


   The organizer has a more specific agenda for the 20th of February
   meeting.  It is added to that particular instance of the meeting by
   specifying the rid parameter.

   >> Request <<


  POST /events/65.ics?action=attachment-add&rid=20120220T100000 HTTP/1.1
  Host: cal.example.com
  Content-Type: text/html; charset="utf-8"
  Content-Disposition:attachment;filename=agenda0220.html
  Content-Length: xxxx
  Prefer: return-representation

  <html>
    <body>
      <h1>Agenda</h1>
      <p>Something different, for a change</p>
    </body>
  </html



   >> Response <<


HTTP/1.1 201 Created
Content-Type: text/calendar charset="utf-8"
Content-Length: yyyy
Content-Location: http://cal.example.com/events/65.ics
ETag: "123456789-000-222"
Cal-Managed-ID: 33225

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example Corp.//CalDAV Server//EN
BEGIN:VTIMEZONE
LAST-MODIFIED:20040110T032845Z
TZID:US/Eastern
BEGIN:DAYLIGHT
DTSTART:20000404T020000
RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4
TZNAME:EDT
TZOFFSETFROM:-0500
TZOFFSETTO:-0400
END:DAYLIGHT
BEGIN:STANDARD
DTSTART:20001026T020000



Daboo & Quillaud        Expires November 3, 2012               [Page 24]


Internet-Draft         CalDAV Managed Attachments               May 2012


RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10
TZNAME:EST
TZOFFSETFROM:-0400
TZOFFSETTO:-0500
END:STANDARD
END:VTIMEZONE
BEGIN:VEVENT
UID:20010712T182145Z-123401@example.com
DTSTAMP:20120201T203412Z
DTSTART;TZID=US/Eastern:20120206T100000
DURATION:PT1H
RRULE:FREQ=WEEKLY
SUMMARY:Planning Meeting
ORGANIZER:mailto:cyrus@example.com
ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:cyrus@example.com
ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:arnaudq@example.com
ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=NEEDS-ACTION:mailto:mike@example.com
ATTACH;MANAGED-ID=97S;MTAG=987654321-555-441;FMT-TYPE=text/html;
 SIZE=xxxx;
 FILENAME=agenda.html:https://cal.example.com/attach/65/34X22R
END:VEVENT
BEGIN:VEVENT
UID:20010712T182145Z-123401@example.com
RECURRENCE-ID;TZID=US/Eastern:20120220T100000
DTSTAMP:20120201T203412Z
DTSTART;TZID=US/Eastern:20120220T100000
DURATION:PT1H
SUMMARY:Planning Meeting
ORGANIZER:mailto:cyrus@example.com
ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:cyrus@example.com
ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:arnaudq@example.com
ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=NEEDS-ACTION:mailto:mike@example.com
ATTACH;MANAGED-ID=33225;MTAG=987654321-555-263;FMT-TYPE=text/html;
 SIZE=xxxx;
 FILENAME=agenda0220.html:https://cal.example.com/attach/65/FGZ225
END:VEVENT
END:VCALENDAR














Daboo & Quillaud        Expires November 3, 2012               [Page 25]


Internet-Draft         CalDAV Managed Attachments               May 2012


Authors' Addresses

   Cyrus Daboo
   Apple Inc.
   1 Infinite Loop
   Cupertino, CA  95014
   USA

   Email: cyrus@daboo.name
   URI:   http://www.apple.com/


   Arnaud Quillaud
   Oracle Corporation
   180, Avenue de l'Europe
   Saint Ismier cedex,   38334
   France

   Email: arnaud.quillaud@oracle.com
   URI:   http://www.oracle.com/































Daboo & Quillaud        Expires November 3, 2012               [Page 26]


Html markup produced by rfcmarkup 1.129d, available from https://tools.ietf.org/tools/rfcmarkup/