draft-ietf-calext-caldav-attachments-00.txt   draft-ietf-calext-caldav-attachments-01.txt 
Calendering Extensions C. Daboo Calendering Extensions C. Daboo
Internet-Draft Apple Internet-Draft Apple
Intended status: Standards Track A. Quillaud Intended status: Standards Track A. Quillaud
Expires: April 20, 2017 Oracle Expires: September 11, 2017 Oracle
K. Murchison, Ed. K. Murchison, Ed.
CMU CMU
October 17, 2016 March 10, 2017
CalDAV Managed Attachments CalDAV Managed Attachments
draft-ietf-calext-caldav-attachments-00 draft-ietf-calext-caldav-attachments-01
Abstract Abstract
This specification defines an extension to the calendar access This specification defines an extension to the calendar access
protocol (CalDAV) to allow attachments associated with iCalendar protocol (CalDAV) to allow attachments associated with iCalendar
data, to be stored and managed on the server. data, to be stored and managed on the server.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
skipping to change at page 1, line 35 skipping to change at page 1, line 35
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on April 20, 2017. This Internet-Draft will expire on September 11, 2017.
Copyright Notice Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the Copyright (c) 2017 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
skipping to change at page 2, line 16 skipping to change at page 2, line 16
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Conventions Used in This Document . . . . . . . . . . . . . . 3 2. Conventions Used in This Document . . . . . . . . . . . . . . 3
3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3.1. Requirements . . . . . . . . . . . . . . . . . . . . . . 4 3.1. Requirements . . . . . . . . . . . . . . . . . . . . . . 4
3.2. Discovering Support for Managed Attachments . . . . . . . 4 3.2. Discovering Support for Managed Attachments . . . . . . . 4
3.3. POST Request for Managing Attachments . . . . . . . . . . 4 3.3. POST Request for Managing Attachments . . . . . . . . . . 4
3.4. Adding attachments . . . . . . . . . . . . . . . . . . . 6 3.4. Adding attachments . . . . . . . . . . . . . . . . . . . 6
3.5. Updating Attachments . . . . . . . . . . . . . . . . . . 8 3.5. Updating Attachments . . . . . . . . . . . . . . . . . . 9
3.6. Removing Attachments via POST . . . . . . . . . . . . . . 11 3.6. Removing Attachments via POST . . . . . . . . . . . . . . 11
3.7. Adding Existing Managed Attachments via PUT . . . . . . . 13 3.7. Adding Existing Managed Attachments via PUT . . . . . . . 13
3.8. Updating Attachments via PUT . . . . . . . . . . . . . . 13 3.8. Updating Attachments via PUT . . . . . . . . . . . . . . 13
3.9. Removing Attachments via PUT . . . . . . . . . . . . . . 13 3.9. Removing Attachments via PUT . . . . . . . . . . . . . . 14
3.10. Retrieving Attachments . . . . . . . . . . . . . . . . . 13 3.10. Retrieving Attachments . . . . . . . . . . . . . . . . . 14
3.11. Additional Considerations . . . . . . . . . . . . . . . . 13 3.11. Additional Considerations . . . . . . . . . . . . . . . . 14
4. Modifications to iCalendar Syntax . . . . . . . . . . . . . . 16 4. Modifications to iCalendar Syntax . . . . . . . . . . . . . . 16
4.1. SIZE Property Parameter . . . . . . . . . . . . . . . . . 16 4.1. SIZE Property Parameter . . . . . . . . . . . . . . . . . 16
4.2. FILENAME Property Parameter . . . . . . . . . . . . . . . 16 4.2. FILENAME Property Parameter . . . . . . . . . . . . . . . 17
4.3. MANAGED-ID Property Parameter . . . . . . . . . . . . . . 17 4.3. MANAGED-ID Property Parameter . . . . . . . . . . . . . . 17
5. Additional Message Header Fields . . . . . . . . . . . . . . 17 5. Additional Message Header Fields . . . . . . . . . . . . . . 18
5.1. Cal-Managed-ID Response Header . . . . . . . . . . . . . 17 5.1. Cal-Managed-ID Response Header Field . . . . . . . . . . 18
6. Additional WebDAV properties . . . . . . . . . . . . . . . . 18 6. Additional WebDAV properties . . . . . . . . . . . . . . . . 18
6.1. CALDAV:managed-attachments-server-URL property . . . . . 18 6.1. CALDAV:managed-attachments-server-URL property . . . . . 18
6.2. CALDAV:max-attachment-size property . . . . . . . . . . . 19 6.2. CALDAV:max-attachment-size property . . . . . . . . . . . 19
6.3. CALDAV:max-attachments-per-resource property . . . . . . 20 6.3. CALDAV:max-attachments-per-resource property . . . . . . 20
7. Implementation Status . . . . . . . . . . . . . . . . . . . . 21 7. Implementation Status . . . . . . . . . . . . . . . . . . . . 21
8. Security Considerations . . . . . . . . . . . . . . . . . . . 23 8. Security Considerations . . . . . . . . . . . . . . . . . . . 23
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23
9.1. Parameter Registrations . . . . . . . . . . . . . . . . . 23 9.1. Parameter Registrations . . . . . . . . . . . . . . . . . 23
9.2. Message Header Field Registrations . . . . . . . . . . . 23 9.2. Message Header Field Registrations . . . . . . . . . . . 24
10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 24 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 24
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 24 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 24
11.1. Normative References . . . . . . . . . . . . . . . . . . 24 11.1. Normative References . . . . . . . . . . . . . . . . . . 24
11.2. Informative References . . . . . . . . . . . . . . . . . 25 11.2. Informative References . . . . . . . . . . . . . . . . . 25
11.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 25 11.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Appendix A. Change History (To be removed by RFC Editor before Appendix A. Change History (To be removed by RFC Editor before
publication) . . . . . . . . . . . . . . . . . . . . 26 publication) . . . . . . . . . . . . . . . . . . . . 26
Appendix B. Example Involving Recurring Events . . . . . . . . . 27 Appendix B. Example Involving Recurring Events . . . . . . . . . 28
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 31 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 31
1. Introduction 1. Introduction
The iCalendar [RFC5545] data format is used to represent calendar The iCalendar [RFC5545] data format is used to represent calendar
data and is used with iTIP [RFC5546] to handle scheduling operations data and is used with iTIP [RFC5546] to handle scheduling operations
between calendar users. between calendar users.
[RFC4791] defines the CalDAV Calendar Access protocol, based on HTTP [RFC4791] defines the CalDAV Calendar Access protocol, based on HTTP
[RFC7230], for accessing calendar data stored on a server. [RFC7230], for accessing calendar data stored on a server.
skipping to change at page 4, line 27 skipping to change at page 4, line 27
targeted for the attachment operation. This is accomplished through targeted for the attachment operation. This is accomplished through
use of additional query parameters on the POST request-URI. use of additional query parameters on the POST request-URI.
3.1. Requirements 3.1. Requirements
A server that supports the features described in this specification A server that supports the features described in this specification
is REQUIRED to support the CalDAV "calendar-access" [RFC4791] is REQUIRED to support the CalDAV "calendar-access" [RFC4791]
features. features.
In addition, such a server MUST support the "return=representation" In addition, such a server MUST support the "return=representation"
Prefer header value [RFC7240] on successful HTTP PUT and POST Prefer header field value [RFC7240] on successful HTTP PUT and POST
requests targeting existing calendar object resources, by returning requests targeting existing calendar object resources, by returning
the new representation of that calendar resource (including its new the new representation of that calendar resource (including its new
Etag header value) in the response. ETag header field value) in the response.
3.2. Discovering Support for Managed Attachments 3.2. Discovering Support for Managed Attachments
A server supporting the features described in this specification MUST A server supporting the features described in this specification MUST
include "calendar-managed-attachments" as a field in the DAV response include "calendar-managed-attachments" as a field in the DAV response
header from an OPTIONS request on a calendar home collection. header field from an OPTIONS request on a calendar home collection.
A server might choose to not support storing managed attachments on a A server might choose to not support storing managed attachments on a
per-recurrence instance basis (i.e., they can only be added to all per-recurrence instance basis (i.e., they can only be added to all
instances as a whole). If that is the case, the server MUST include instances as a whole). If that is the case, the server MUST include
"calendar-managed-attachments-no-recurrence" as a field in the DAV "calendar-managed-attachments-no-recurrence" as a field in the DAV
response header from an OPTIONS request on a calendar home response header field from an OPTIONS request on a calendar home
collection. When that field is present, clients MUST NOT attempt any collection. When that field is present, clients MUST NOT attempt any
managed attachment operations that target specific recurrence managed attachment operations that target specific recurrence
instances. instances.
3.3. POST Request for Managing Attachments 3.3. POST Request for Managing Attachments
An HTTP POST request is used to add, update, or remove attachments. An HTTP POST request is used to add, update, or remove attachments.
The request-URI will contain various query parameters to specify the The request-URI will contain various query parameters to specify the
behavior. behavior.
skipping to change at page 6, line 45 skipping to change at page 6, line 45
the value "attachment-add" (see Section 3.3.1). the value "attachment-add" (see Section 3.3.1).
B. If all recurrence instances are having an attachment added, B. If all recurrence instances are having an attachment added,
the "rid" query parameter is not present in the request-URI. the "rid" query parameter is not present in the request-URI.
If one or more specific recurrence instances are targeted, If one or more specific recurrence instances are targeted,
then the request-URI will include a "rid" query parameter then the request-URI will include a "rid" query parameter
containing the list of instances (see Section 3.3.2). containing the list of instances (see Section 3.3.2).
C. The body of the request contains the data for the attachment. C. The body of the request contains the data for the attachment.
D. The client MUST include a valid Content-Type HTTP header D. The client MUST include a valid Content-Type header field
describing the media type of the attachment (as required by describing the media type of the attachment (as required by
HTTP). HTTP).
E. The client SHOULD include a Content-Disposition HTTP header E. The client SHOULD include a Content-Disposition header field
[RFC6266] with a "type" parameter set to "attachment", and a [RFC6266] with a "type" parameter set to "attachment", and a
"filename" parameter that indicates the name of the "filename" parameter that indicates the name of the
attachment. attachment.
F. The client MAY include a Prefer header field [RFC7240] with
the "return=representation" preference to request that the
modified calendar object resource be returned as the body of
a successful response to the POST request.
2. When the server receives the POST request it does the following: 2. When the server receives the POST request it does the following:
A. Validates that any recurrence instances referred to via the A. Validates that any recurrence instances referred to via the
"rid" query parameter are valid for the calendar object "rid" query parameter are valid for the calendar object
resource being targeted. resource being targeted.
B. Stores the supplied attachment data into a resource and B. Stores the supplied attachment data into a resource and
generates an appropriate URI for clients to access the generates an appropriate URI for clients to access the
resource. resource.
C. For each affected recurrence instance in the calendar object C. For each affected recurrence instance in the calendar object
resource targeted by the request, the server adds an "ATTACH" resource targeted by the request, the server adds an "ATTACH"
property, whose value is the URI of the stored attachment. property, whose value is the URI of the stored attachment.
The "ATTACH" property MUST contain a "MANAGED-ID" parameter The "ATTACH" property MUST contain a "MANAGED-ID" parameter
whose value is a unique identifier (within the context of the whose value is a unique identifier (within the context of the
server as a whole). The "ATTACH" property SHOULD contain an server as a whole). The "ATTACH" property SHOULD contain an
"FMTTYPE" parameter whose value matches the Content-Type "FMTTYPE" parameter whose value matches the Content-Type
header value from the request. The "ATTACH" property SHOULD header field value from the request. The "ATTACH" property
contain an "FILENAME" parameter whose value matches the SHOULD contain an "FILENAME" parameter whose value matches
Content-Disposition header "filename" parameter value from the Content-Disposition header field "filename" parameter
the request, taking into account the restrictions expressed value from the request, taking into account the restrictions
in Section 4.2. The "ATTACH" property SHOULD include a expressed in Section 4.2. The "ATTACH" property SHOULD
"SIZE" parameter whose value represents the size in octets of include a "SIZE" parameter whose value represents the size in
the attachment. If a specified recurrence instance does not octets of the attachment. If a specified recurrence instance
have a matching component in the calendar object resource, does not have a matching component in the calendar object
then the server MUST modify the calendar object resource to resource, then the server MUST modify the calendar object
include the overridden component with the appropriate resource to include an overridden component with the
"RECURRENCE-ID" property included. appropriate "RECURRENCE-ID" property.
D. Upon successful creation of the attachment resource, and D. Upon successful creation of the attachment resource, and
modification of the targeted calendar object resource, the modification of the targeted calendar object resource, the
server MUST return an appropriate HTTP success status server MUST return an appropriate HTTP success status
response and include a "Cal-Managed-ID" HTTP header response and include a "Cal-Managed-ID" header field
containing the "MANAGED-ID" parameter value of the newly containing the "MANAGED-ID" parameter value of the newly
created "ATTACH" property. The client can use the "Cal- created "ATTACH" property. The client can use the "Cal-
Managed-ID" header value to correlate the attachment with Managed-ID" header field value to correlate the attachment
"ATTACH" properties added to the calendar object resource. with "ATTACH" properties added to the calendar object
It is expected that the client will immediately reload the resource. If the client included a Prefer header field with
calendar object resource to refresh any local cache, or use the "return=representation" preference in the request, the
the Prefer header "return=representation" option [RFC7240] to server SHOULD return the modified calendar object resource as
have the server return the modified calendar object resource the body of the response. Otherwise, the server can expect
data in the HTTP response. that the client will reload the calendar object resource with
a subsequent GET request to refresh any local cache.
In the following example, the client adds a new attachment to a non In the following example, the client adds a new attachment to a non
recurring event and asks the server (via the Prefer [RFC7240] HTTP recurring event and asks the server (via the Prefer [RFC7240] header
header) to return the updated version of that event in the response. field) to return the modified version of that event in the response.
>> Request << >> Request <<
POST /events/64.ics?action=attachment-add HTTP/1.1 POST /events/64.ics?action=attachment-add HTTP/1.1
Host: cal.example.com Host: cal.example.com
Content-Type: text/html; charset="utf-8" Content-Type: text/html; charset="utf-8"
Content-Disposition:attachment;filename=agenda.html Content-Disposition:attachment;filename=agenda.html
Content-Length: xxxx Content-Length: xxxx
Prefer: return=representation Prefer: return=representation
skipping to change at page 9, line 24 skipping to change at page 9, line 30
A. The request-URI will include an "action" query parameter with A. The request-URI will include an "action" query parameter with
the value "attachment-update" (see Section 3.3.1). the value "attachment-update" (see Section 3.3.1).
B. The request-URI will include a "managed-id" query parameter B. The request-URI will include a "managed-id" query parameter
with the value matching that of the "MANAGED-ID" parameter with the value matching that of the "MANAGED-ID" parameter
for the "ATTACH" property being updated (see Section 3.3.3). for the "ATTACH" property being updated (see Section 3.3.3).
C. The body of the request contains the updated data for the C. The body of the request contains the updated data for the
attachment. attachment.
D. The client MUST include a valid Content-Type header D. The client MUST include a valid Content-Type header field
describing the media type of the attachment (as required by describing the media type of the attachment (as required by
HTTP). HTTP).
E. The client SHOULD include a Content-Disposition header E. The client SHOULD include a Content-Disposition header field
[RFC6266] with a "type" parameter set to "attachment", and a [RFC6266] with a "type" parameter set to "attachment", and a
"filename" parameter that indicates the name of the "filename" parameter that indicates the name of the
attachment. attachment.
F. The client MAY include a Prefer header field [RFC7240] with
the "return=representation" preference to request that the
modified calendar object resource be returned as the body of
a successful response to the POST request.
2. When the server receives the POST request it does the following: 2. When the server receives the POST request it does the following:
A. Validates that the "managed-id" query parameter is valid for A. Validates that the "managed-id" query parameter is valid for
the calendar object resource. the calendar object resource.
B. Updates the content of the attachment resource corresponding B. Updates the content of the attachment resource corresponding
to that managed-id with the supplied attachment data. to that managed-id with the supplied attachment data.
C. For each affected recurrence instance in the calendar object C. For each affected recurrence instance in the calendar object
resource targeted by the request, the server updates the resource targeted by the request, the server updates the
"ATTACH" property whose "MANAGED-ID" property parameter value "ATTACH" property whose "MANAGED-ID" property parameter value
matches the "managed-id" query parameter. The "MANAGED-ID" matches the "managed-id" query parameter. The "MANAGED-ID"
parameter value is changed to allow other clients to detect parameter value is changed to allow other clients to detect
the update, and the property value (attachment URI) might the update, and the property value (attachment URI) might
also be changed. The "ATTACH" property SHOULD contain a also be changed. The "ATTACH" property SHOULD contain a
"FMTTYPE" parameter whose value matches the Content-Type "FMTTYPE" parameter whose value matches the Content-Type
header value from the request - this could differ from the header field value from the request - this could differ from
original value if the media type of the updated attachment is the original value if the media type of the updated
different. The "ATTACH" property SHOULD contain a "FILENAME" attachment is different. The "ATTACH" property SHOULD
parameter whose value matches the Content-Disposition header contain a "FILENAME" parameter whose value matches the
"filename" parameter value from the request, taking into Content-Disposition header field "filename" parameter value
account the restrictions expressed in Section 4.2. The from the request, taking into account the restrictions
"ATTACH" property SHOULD include a "SIZE" parameter whose expressed in Section 4.2. The "ATTACH" property SHOULD
value represents the size in octets of the updated include a "SIZE" parameter whose value represents the size in
attachment. octets of the updated attachment.
D. Upon successful update of the attachment resource, and D. Upon successful update of the attachment resource, and
modification of the targeted calendar object resource, the modification of the targeted calendar object resource, the
server MUST return an appropriate HTTP success status server MUST return an appropriate HTTP success status
response, and include a "Cal-Managed-ID" HTTP header response, and include a "Cal-Managed-ID" header field
containing the new value of the "MANAGED-ID" parameter. It containing the new value of the "MANAGED-ID" parameter. The
is expected that the client will immediately reload the client can use the "Cal-Managed-ID" header field value to
calendar object resource to refresh any local cache, or use correlate the attachment with "ATTACH" properties added to
the Prefer header "return=representation" option [RFC7240] to the calendar object resource. If the client included a
have the server return the modified calendar object resource Prefer header field with the "return=representation"
data in the HTTP response. preference in the request, the server SHOULD return the
modified calendar object resource as the body of the
response. Otherwise, the server can expect that the client
will reload the calendar object resource with a subsequent
GET request to refresh any local cache.
The update operation does not take a "rid" parameter and does not The update operation does not take a "rid" parameter and does not
add, or remove, any "ATTACH" property in the targetted calendar add, or remove, any "ATTACH" property in the targeted calendar object
object resource. To link an existing attachment to a new instance, resource. To link an existing attachment to a new instance, the
the client simply does a PUT on the calendar object resource, adding client simply does a PUT on the calendar object resource, adding an
an "ATTACH" property which duplicates the existing one (see "ATTACH" property which duplicates the existing one (see
Section 3.7). Section 3.7).
In the following example, the client updates an existing attachment In the following example, the client updates an existing attachment
and asks the server (via the Prefer [RFC7240] HTTP header) to return and asks the server (via the Prefer [RFC7240] header field) to return
the updated version of that event in the response. the updated version of that event in the response.
>> Request << >> Request <<
POST /events/64.ics?action=attachment-update&managed-id=97S HTTP/1.1 POST /events/64.ics?action=attachment-update&managed-id=97S HTTP/1.1
Host: cal.example.com Host: cal.example.com
Content-Type: text/html; charset="utf-8" Content-Type: text/html; charset="utf-8"
Content-Disposition:attachment;filename=agenda.html Content-Disposition:attachment;filename=agenda.html
Content-Length: xxxx Content-Length: xxxx
Prefer: return=representation Prefer: return=representation
skipping to change at page 12, line 5 skipping to change at page 12, line 21
then the request-URI will include a "rid" query parameter then the request-URI will include a "rid" query parameter
containing the list of instances (see Section 3.3.2). containing the list of instances (see Section 3.3.2).
C. The request-URI will include a "managed-id" query parameter C. The request-URI will include a "managed-id" query parameter
with the value matching that of the "MANAGED-ID" property with the value matching that of the "MANAGED-ID" property
parameter for the "ATTACH" property being removed (see parameter for the "ATTACH" property being removed (see
Section 3.3.3). Section 3.3.3).
D. The body of the request will be empty. D. The body of the request will be empty.
E. The client MAY include a Prefer header field [RFC7240] with
the "return=representation" preference to request that the
modified calendar object resource be returned as the body of
a successful response to the POST request.
2. When the server receives the POST request it does the following: 2. When the server receives the POST request it does the following:
A. Validates that any recurrence instances referred to via the A. Validates that any recurrence instances referred to via the
"rid" query parameter are valid for the calendar object "rid" query parameter are valid for the calendar object
resource being targeted. resource being targeted.
B. Validates that the "managed-id" query parameter is valid for B. Validates that the "managed-id" query parameter is valid for
the calendar object resource and specific instances being the calendar object resource and specific instances being
targeted. targeted.
C. For each affected recurrence instance in the calendar object C. For each affected recurrence instance in the calendar object
resource targeted by the request, the server removes the resource targeted by the request, the server removes the
matching "ATTACH" property. Note that if a specified matching "ATTACH" property. Note that if a specified
recurrence instance does not have a matching component in the recurrence instance does not have a matching component in the
calendar object resource, then the server MUST modify the calendar object resource, then the server MUST modify the
calendar object resource to include the overridden component calendar object resource to include an overridden component
with the appropriate "RECURRENCE-ID" property included, and with the appropriate "RECURRENCE-ID" property, and the
the matching "ATTACH" property removed. This later case is matching "ATTACH" property removed. This later case is
actually valid only if the master component does include the actually valid only if the master component does include the
referenced "ATTACH" property. referenced "ATTACH" property.
D. If the attachment resource is no longer referenced by any D. If the attachment resource is no longer referenced by any
instance of the calendar object resource, the server can instance of the calendar object resource, the server can
delete the attachment resource to free up storage space. delete the attachment resource to free up storage space.
E. Upon successful removal of the attachment resource and E. Upon successful removal of the attachment resource and
modification of the targeted calendar object resource, the modification of the targeted calendar object resource, the
server MUST return an appropriate HTTP success status server MUST return an appropriate HTTP success status
response. It is expected that the client will immediately response. If the client included a Prefer header field with
reload the calendar object resource to refresh any local the "return=representation" preference in the request, the
cache, or use the Prefer header "return=representation" server SHOULD return the modified calendar object resource as
option [RFC7240] to have the server return the modified the body of the response. Otherwise, the server can expect
calendar object resource data in the HTTP response. that the client will reload the calendar object resource with
a subsequent GET request to refresh any local cache.
In the following example, the client deletes an existing attachment In the following example, the client deletes an existing attachment
by passing its managed-id in the request. The Prefer [RFC7240] HTTP by passing its managed-id in the request. The Prefer [RFC7240]
header is not set in the request so the calendar object resource data header field is not set in the request so the calendar object
is not returned in the response. resource data is not returned in the response.
>> Request << >> Request <<
POST /events/64.ics?action=attachment-remove&managed-id=98S HTTP/1.1 POST /events/64.ics?action=attachment-remove&managed-id=98S HTTP/1.1
Host: cal.example.com Host: cal.example.com
Content-Length: 0 Content-Length: 0
>> Response << >> Response <<
HTTP/1.1 204 No Content HTTP/1.1 204 No Content
Content-Length: 0 Content-Length: 0
3.7. Adding Existing Managed Attachments via PUT 3.7. Adding Existing Managed Attachments via PUT
Clients can make use of existing managed attachments by adding the Clients can make use of existing managed attachments by adding the
corresponding "ATTACH" property to calendar object resources (subject corresponding "ATTACH" property to calendar object resources (subject
to the restrictions described in Section 3.11.3). When this occurs, to the restrictions described in Section 3.11.3). When this occurs,
skipping to change at page 13, line 24 skipping to change at page 13, line 46
servers SHOULD NOT change either the "MANAGED-ID" parameter value or servers SHOULD NOT change either the "MANAGED-ID" parameter value or
the "ATTACH" property value for any managed attachments - this the "ATTACH" property value for any managed attachments - this
ensures that clients do not have to download the attachment data ensures that clients do not have to download the attachment data
again if they already have it cached, because it is used in another again if they already have it cached, because it is used in another
calendar resource. calendar resource.
3.8. Updating Attachments via PUT 3.8. Updating Attachments via PUT
Servers MUST NOT allow clients to update attachment data directly via Servers MUST NOT allow clients to update attachment data directly via
a PUT on the attachment URI (or via any other HTTP method that a PUT on the attachment URI (or via any other HTTP method that
modifies content). Instead, attachments can only be manipulated via modifies content). Instead, attachments can only be updated via use
use of POST requests on the calendar data. of POST requests on the calendar data.
3.9. Removing Attachments via PUT 3.9. Removing Attachments via PUT
Clients can remove attachments by simply re-writing the calendar Clients can remove attachments by simply re-writing the calendar
object resource data to remove the appropriate "ATTACH" properties. object resource data to remove the appropriate "ATTACH" properties.
Servers MUST NOT allow clients to delete attachments directly via a Servers MUST NOT allow clients to delete attachments directly via a
DELETE request on the attachment URI. DELETE request on the attachment URI.
3.10. Retrieving Attachments 3.10. Retrieving Attachments
skipping to change at page 14, line 17 skipping to change at page 14, line 40
the CALDAV:max-attachment-size property value (Section 6.2) on the the CALDAV:max-attachment-size property value (Section 6.2) on the
calendar collection of the target calendar resource; calendar collection of the target calendar resource;
(CALDAV:max-attachments-per-resource): The addition of the (CALDAV:max-attachments-per-resource): The addition of the
attachment submitted in the POST request MUST result in the target attachment submitted in the POST request MUST result in the target
calendar resource having a number of managed attachments less than calendar resource having a number of managed attachments less than
or equal to the value of the CALDAV:max-attachments-per-resource or equal to the value of the CALDAV:max-attachments-per-resource
property value (Section 6.3) on the calendar collection of the property value (Section 6.3) on the calendar collection of the
target calendar resource; target calendar resource;
(CALDAV:valid-managed-id): The managed-id POST request query (CALDAV:valid-managed-id): The managed-id query parameter in the
parameter MUST contain a value corresponding to a "MANAGED-ID" POST request MUST contain a value corresponding to a "MANAGED-ID"
property parameter value in the iCalendar data targeted by the property parameter value in the iCalendar data targeted by the
request. request.
A POST request to add, modify, or delete a managed attachment results A POST request to add, modify, or delete a managed attachment results
in an implicit modification of the targeted calendar resource in an implicit modification of the targeted calendar resource
(equivalent of a PUT). As a consequence, clients should also be (equivalent of a PUT). As a consequence, clients should also be
prepared to handle preconditions associated with this implicit PUT. prepared to handle preconditions associated with this implicit PUT.
This includes (but is not limited to): This includes (but is not limited to):
(CALDAV:max-resource-size) (from Section 5.3.2.1 of [RFC4791]) (CALDAV:max-resource-size) (from Section 5.3.2.1 of [RFC4791])
skipping to change at page 14, line 29 skipping to change at page 15, line 4
property parameter value in the iCalendar data targeted by the property parameter value in the iCalendar data targeted by the
request. request.
A POST request to add, modify, or delete a managed attachment results A POST request to add, modify, or delete a managed attachment results
in an implicit modification of the targeted calendar resource in an implicit modification of the targeted calendar resource
(equivalent of a PUT). As a consequence, clients should also be (equivalent of a PUT). As a consequence, clients should also be
prepared to handle preconditions associated with this implicit PUT. prepared to handle preconditions associated with this implicit PUT.
This includes (but is not limited to): This includes (but is not limited to):
(CALDAV:max-resource-size) (from Section 5.3.2.1 of [RFC4791]) (CALDAV:max-resource-size) (from Section 5.3.2.1 of [RFC4791])
(DAV:quota-not-exceeded) (from Section 6 of [RFC4331]) (DAV:quota-not-exceeded) (from Section 6 of [RFC4331])
(DAV:sufficient-disk-space) (from Section 6 of [RFC4331]) (DAV:sufficient-disk-space) (from Section 6 of [RFC4331])
A PUT request to add or modify and existing calendar object resource A PUT request to add or modify and existing calendar object resource
can make reference to a managed attachment. The following new can make reference to an existing managed attachment. The following
preconditions is defined: new preconditions is defined:
(CALDAV:valid-managed-id-parameter): a "MANAGED-ID" property (CALDAV:valid-managed-id-parameter): a "MANAGED-ID" property
parameter value in the iCalendar data in the PUT request is not parameter value in the iCalendar data in the PUT request is not
valid (e.g., does not match any existing managed attachment). valid (e.g., does not match any existing managed attachment).
3.11.2. Quotas 3.11.2. Quotas
The WebDAV Quotas [RFC4331] specification defines two live WebDAV The WebDAV Quotas [RFC4331] specification defines two live WebDAV
properties (DAV:quota-available-bytes and DAV:quota-used-bytes) to properties (DAV:quota-available-bytes and DAV:quota-used-bytes) to
communicate storage quota information to clients. Server communicate storage quota information to clients. Server
skipping to change at page 15, line 29 skipping to change at page 15, line 48
events from adding, updating or removing managed attachments. In events from adding, updating or removing managed attachments. In
addition, the server MUST prevent a calendar user from re-using a addition, the server MUST prevent a calendar user from re-using a
managed attachment (based on its managed-id value), unless that user managed attachment (based on its managed-id value), unless that user
is the one who originally created the managed attachment. is the one who originally created the managed attachment.
3.11.4. Redirects 3.11.4. Redirects
For POST requests that add or update attachment data, the server MAY 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 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 request using a different request-URI. As a result, it is always
best for clients to use the "100 Continue" behavior defined in best for clients to use the "100-continue" expectation defined in
Section 5.1.1 of [RFC7231]. Using this mechanism ensures that, if a Section 5.1.1 of [RFC7231]. Using this mechanism ensures that, if a
redirect does occur, the client does not needlessly send the redirect does occur, the client does not needlessly send the
attachment data. attachment data.
3.11.5. Automatic Clean-up by servers 3.11.5. Automatic Clean-up by servers
Servers MAY automatically remove attachment data, for example to Servers MAY automatically remove attachment data, for example to
regain the storage taken by unused attachments, or as the result of a regain the storage taken by unused attachments, or as the result of a
virus scanning. When doing so they SHOULD NOT modify calendar data virus scanning. When doing so they SHOULD NOT modify calendar data
referencing those attachments. Instead they SHOULD return a 410 HTTP referencing those attachments. Instead they SHOULD respond with "410
status response to any request on the removed attachment URI. (Gone)" to any request on the removed attachment URI.
3.11.6. Sending Scheduling Messages with Attachments 3.11.6. Sending Scheduling Messages with Attachments
When a managed attachment is added, updated or removed from a When a managed attachment is added, updated or removed from a
calendar object resource, the server MUST ensure that a scheduling calendar object resource, the server MUST ensure that a scheduling
message is sent to update any attendees with the changes, as per message is sent to update any attendees with the changes, as per
[RFC6638]. [RFC6638].
3.11.7. Other Client Considerations 3.11.7. Other Client Considerations
Clients can expect servers to take a while to respond to POST Clients can expect servers to take a while to respond to POST
requests that include large attachment bodies. Servers SHOULD use requests that include large attachment bodies. Servers SHOULD use
the "100 Continue" behavior defined in Section 5.1.1 of [RFC7231] to the "102 (Processing)" interim response defined in Section 10.1 of
keep the client connection alive if the response will take some time. [RFC2518] to keep the client connection alive if the final response
will take some time.
When exporting calendar data from a CalDAV server supporting managed When exporting calendar data from a CalDAV server supporting managed
attachments, clients SHOULD remove all "MANAGED-ID" property attachments, clients SHOULD remove all "MANAGED-ID" property
parameters from "ATTACH" properties in the calendar data. Similarly parameters from "ATTACH" properties in the calendar data. Similarly
when importing calendar data from another source, clients SHOULD when importing calendar data from another source, clients SHOULD
remove any "MANAGED-ID" property parameters on "ATTACH" properties remove any "MANAGED-ID" property parameters on "ATTACH" properties
(failure to do so will likely result in the server removing those (failure to do so will likely result in the server removing those
properties automatically). properties automatically).
4. Modifications to iCalendar Syntax 4. Modifications to iCalendar Syntax
skipping to change at page 17, line 11 skipping to change at page 17, line 26
Format Definition: This property parameter is defined by the Format Definition: This property parameter is defined by the
following notation: following notation:
filenameparam = "FILENAME" "=" paramtext filenameparam = "FILENAME" "=" paramtext
Description: This property parameter MAY be specified on "ATTACH" Description: This property parameter MAY be specified on "ATTACH"
properties corresponding to managed attachments. Its value properties corresponding to managed attachments. Its value
provides information on how to construct a filename for storing provides information on how to construct a filename for storing
the attachment data. This parameter is very similar in nature to the attachment data. This parameter is very similar in nature to
the Content-Disposition HTTP header "filename" parameter and the Content-Disposition HTTP header field "filename" parameter and
exposes the same security risks. As a consequence, clients MUST exposes the same security risks. As a consequence, clients MUST
follow the guidelines expressed in Section 4.3 of [RFC6266] when follow the guidelines expressed in Section 4.3 of [RFC6266] when
consuming this parameter value. Similarly, servers MUST follow consuming this parameter value. Similarly, servers MUST follow
those same guidelines before storing a value. those same guidelines before storing a value.
Example: Example:
ATTACH;FILENAME=agenda.html:http://attachments.example.c ATTACH;FILENAME=agenda.html:http://attachments.example.c
om/rt452S om/rt452S
skipping to change at page 17, line 37 skipping to change at page 18, line 5
Format Definition: This property parameter is defined by the Format Definition: This property parameter is defined by the
following notation: following notation:
managedidparam = "MANAGED-ID" "=" paramtext managedidparam = "MANAGED-ID" "=" paramtext
Description: This property parameter MUST be specified on "ATTACH" Description: This property parameter MUST be specified on "ATTACH"
properties corresponding to managed attachments. Its value is properties corresponding to managed attachments. Its value is
generated by the server and uniquely identifies a managed generated by the server and uniquely identifies a managed
attachment. This property parameter MUST NOT be present in the attachment. This property parameter MUST NOT be present in the
case of non managed attachments. case of non-managed attachments.
Example: Example:
ATTACH;MANAGED-ID=aUNhbGVuZGFy:http://attachments.example.c ATTACH;MANAGED-ID=aUNhbGVuZGFy:http://attachments.example.c
om/abcd.txt om/abcd.txt
5. Additional Message Header Fields 5. Additional Message Header Fields
5.1. Cal-Managed-ID Response Header 5.1. Cal-Managed-ID Response Header Field
The Cal-Managed-ID response header provides the value of the MANAGED- The Cal-Managed-ID response header field provides the value of the
ID parameter corresponding to a newly added ATTACH property. It MUST MANAGED-ID parameter corresponding to a newly added ATTACH property.
be sent only in response to a successful POST request with an action It MUST be sent only in response to a successful POST request with an
set to attachment-add. action set to attachment-add or attachment-update.
Cal-Managed-ID = "Cal-Managed-ID" ":" paramtext Cal-Managed-ID = "Cal-Managed-ID" ":" paramtext
; "paramtext" is defined in Section 3.1 of [RFC5545] ; "paramtext" is defined in Section 3.1 of [RFC5545]
Example: Example:
Cal-Managed-ID:aUNhbGVuZGFy Cal-Managed-ID:aUNhbGVuZGFy
6. Additional WebDAV properties 6. Additional WebDAV properties
skipping to change at page 20, line 30 skipping to change at page 20, line 49
COPY/MOVE behavior: This property value MUST be preserved in COPY COPY/MOVE behavior: This property value MUST be preserved in COPY
and MOVE operations. and MOVE operations.
allprop behavior: SHOULD NOT be returned by a PROPFIND DAV:allprop allprop behavior: SHOULD NOT be returned by a PROPFIND DAV:allprop
request. request.
Description: The CALDAV:max-attachments-per-resource property is Description: The CALDAV:max-attachments-per-resource property is
used to specify a numeric value that represents the maximum number used to specify a numeric value that represents the maximum number
of managed attachments across all instances of a calendar object of managed attachments across all instances of a calendar object
resource stored in a calendar collection. Non managed attachments resource stored in a calendar collection. Non-managed attachments
are not counted toward that limit. The property is defined on the are not counted toward that limit. The property is defined on the
parent collection of the calendar object resource to which the parent collection of the calendar object resource to which the
attachment is associated. Any attempt to add a managed attachment attachment is associated. Any attempt to add a managed attachment
that would cause the calendar resource to exceed this limit MUST that would cause the calendar resource to exceed this limit MUST
result in an error, with the CALDAV:max-attachments-per-resource result in an error, with the CALDAV:max-attachments-per-resource
precondition (Section 3.11.1) being violated. In the absence of precondition (Section 3.11.1) being violated. In the absence of
this property, the client can assume that the server can handle this property, the client can assume that the server can handle
any number of managed attachments per calendar resource. any number of managed attachments per calendar resource.
Definition: Definition:
skipping to change at page 24, line 20 skipping to change at page 24, line 39
11. References 11. References
11.1. Normative References 11.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>. <http://www.rfc-editor.org/info/rfc2119>.
[RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D.
Jensen, "HTTP Extensions for Distributed Authoring --
WEBDAV", RFC 2518, DOI 10.17487/RFC2518, February 1999,
<http://www.rfc-editor.org/info/rfc2518>.
[RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration
Procedures for Message Header Fields", BCP 90, RFC 3864, Procedures for Message Header Fields", BCP 90, RFC 3864,
DOI 10.17487/RFC3864, September 2004, DOI 10.17487/RFC3864, September 2004,
<http://www.rfc-editor.org/info/rfc3864>. <http://www.rfc-editor.org/info/rfc3864>.
[RFC4331] Korver, B. and L. Dusseault, "Quota and Size Properties [RFC4331] Korver, B. and L. Dusseault, "Quota and Size Properties
for Distributed Authoring and Versioning (DAV) for Distributed Authoring and Versioning (DAV)
Collections", RFC 4331, DOI 10.17487/RFC4331, February Collections", RFC 4331, DOI 10.17487/RFC4331, February
2006, <http://www.rfc-editor.org/info/rfc4331>. 2006, <http://www.rfc-editor.org/info/rfc4331>.
skipping to change at page 26, line 8 skipping to change at page 26, line 35
[8] http://calendarserver.org/wiki/CalDAVTester [8] http://calendarserver.org/wiki/CalDAVTester
[9] http://www.apache.org/licenses/LICENSE-2.0.html [9] http://www.apache.org/licenses/LICENSE-2.0.html
[10] http://www.2doapp.com/ [10] http://www.2doapp.com/
Appendix A. Change History (To be removed by RFC Editor before Appendix A. Change History (To be removed by RFC Editor before
publication) publication)
Changes in calext-01:
1. Changed all instances of "header" to "header field".
2. Reworked wording of Prefer header field handling.
3. Switched to recommending 102 (Processing) interim response to
keep the client connection alive.
4. Fixed description of Cal-Managed-ID response header field to
state that it is also required in responses to successful
attachment-update.
5. Minor editorial changes.
Changes in calext-00: Changes in calext-00:
1. Added Murchison as editor. 1. Added Murchison as editor.
2. Updated HTTP references to RFC7230 and RFC7231. 2. Updated HTTP references to RFC7230 and RFC7231.
3. Updated Prefer header field references to RFC7240. 3. Updated Prefer header field references to RFC7240.
4. Added Implementation Status section. 4. Added Implementation Status section.
 End of changes. 49 change blocks. 
96 lines changed or deleted 138 lines changed or added

This html diff was produced by rfcdiff 1.45. The latest version is available from http://tools.ietf.org/tools/rfcdiff/