idnits 2.17.1
draft-daboo-caldav-attachments-03.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
No issues found here.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
-- The document date (February 5, 2014) is 3726 days in the past. Is this
intentional?
Checking references for intended status: Proposed Standard
----------------------------------------------------------------------------
(See RFCs 3967 and 4897 for information about using normative references
to lower-maturity documents in RFCs)
** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231,
RFC 7232, RFC 7233, RFC 7234, RFC 7235)
Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 1 comment (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 Network Working Group C. Daboo
3 Internet-Draft Apple
4 Intended status: Standards Track A. Quillaud
5 Expires: August 9, 2014 Oracle
6 February 5, 2014
8 CalDAV Managed Attachments
9 draft-daboo-caldav-attachments-03
11 Abstract
13 This specification defines an extension to the calendar access
14 protocol (CalDAV) to allow attachments associated with iCalendar
15 data, to be stored and managed on the server.
17 Status of this Memo
19 This Internet-Draft is submitted in full conformance with the
20 provisions of BCP 78 and BCP 79.
22 Internet-Drafts are working documents of the Internet Engineering
23 Task Force (IETF). Note that other groups may also distribute
24 working documents as Internet-Drafts. The list of current Internet-
25 Drafts is at http://datatracker.ietf.org/drafts/current/.
27 Internet-Drafts are draft documents valid for a maximum of six months
28 and may be updated, replaced, or obsoleted by other documents at any
29 time. It is inappropriate to use Internet-Drafts as reference
30 material or to cite them other than as "work in progress."
32 This Internet-Draft will expire on August 9, 2014.
34 Copyright Notice
36 Copyright (c) 2014 IETF Trust and the persons identified as the
37 document authors. All rights reserved.
39 This document is subject to BCP 78 and the IETF Trust's Legal
40 Provisions Relating to IETF Documents
41 (http://trustee.ietf.org/license-info) in effect on the date of
42 publication of this document. Please review these documents
43 carefully, as they describe your rights and restrictions with respect
44 to this document. Code Components extracted from this document must
45 include Simplified BSD License text as described in Section 4.e of
46 the Trust Legal Provisions and are provided without warranty as
47 described in the Simplified BSD License.
49 Table of Contents
51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
52 2. Conventions Used in This Document . . . . . . . . . . . . . . 3
53 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
54 3.1. Requirements . . . . . . . . . . . . . . . . . . . . . . . 4
55 3.2. Discovering Support for Managed Attachments . . . . . . . 4
56 3.3. POST Request for Managing Attachments . . . . . . . . . . 5
57 3.4. Adding attachments . . . . . . . . . . . . . . . . . . . . 6
58 3.5. Updating Attachments . . . . . . . . . . . . . . . . . . . 9
59 3.6. Removing Attachments via POST . . . . . . . . . . . . . . 12
60 3.7. Adding Existing Managed Attachments via PUT . . . . . . . 13
61 3.8. Updating Attachments via PUT . . . . . . . . . . . . . . . 13
62 3.9. Removing Attachments via PUT . . . . . . . . . . . . . . . 14
63 3.10. Retrieving Attachments . . . . . . . . . . . . . . . . . . 14
64 3.11. Additional Considerations . . . . . . . . . . . . . . . . 14
65 4. Modifications to iCalendar Syntax . . . . . . . . . . . . . . 16
66 4.1. SIZE Property Parameter . . . . . . . . . . . . . . . . . 16
67 4.2. FILENAME Property Parameter . . . . . . . . . . . . . . . 17
68 4.3. MANAGED-ID Property Parameter . . . . . . . . . . . . . . 17
69 5. Additional Message Header Fields . . . . . . . . . . . . . . . 18
70 5.1. Cal-Managed-ID Response Header . . . . . . . . . . . . . . 18
71 6. Additional WebDAV properties . . . . . . . . . . . . . . . . . 18
72 6.1. CALDAV:managed-attachments-server-URL property . . . . . . 18
73 6.2. CALDAV:max-attachment-size property . . . . . . . . . . . 19
74 6.3. CALDAV:max-attachments-per-resource property . . . . . . . 20
75 7. Security Considerations . . . . . . . . . . . . . . . . . . . 21
76 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21
77 8.1. Parameter Registrations . . . . . . . . . . . . . . . . . 21
78 8.2. Message Header Field Registrations . . . . . . . . . . . . 22
79 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 22
80 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 22
81 10.1. Normative References . . . . . . . . . . . . . . . . . . . 22
82 10.2. Informative References . . . . . . . . . . . . . . . . . . 23
83 Appendix A. Change History (To be removed by RFC Editor
84 before publication) . . . . . . . . . . . . . . . . . 23
85 Appendix B. Example Involving Recurring Events . . . . . . . . . 25
86 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 28
88 1. Introduction
90 The iCalendar [RFC5545] data format is used to represent calendar
91 data and is used with iTIP [RFC5546] to handle scheduling operations
92 between calendar users.
94 [RFC4791] defines the CalDAV Calendar Access protocol, based on HTTP
95 [RFC2616], for accessing calendar data stored on a server.
97 Calendar users often want to include attachments with their calendar
98 data events or tasks (for example a copy of a presentation, or the
99 meeting agenda). iCalendar provides an "ATTACH" property whose value
100 is either the inline Base64 encoded attachment data, or a URL
101 specifying the location of the attachment data.
103 Use of inline attachment data is not ideal with CalDAV because the
104 data would need to be uploaded to the server each time a change to
105 the calendar data is done - even minor changes such as a change to
106 the summary. Whilst a client could choose to use a URL value
107 instead, the problem then becomes where and how the client discovers
108 an appropriate URL to use and how it ensures that only those
109 attendees listed in the event or task are able to access it.
111 This specification solves this problem by having the client send the
112 attachment to the server, separately from the iCalendar data, and the
113 server takes care of adding appropriate "ATTACH" properties in the
114 iCalendar data as well as managing access privileges . The server
115 can also provide additional information to the client about each
116 attachment in the iCalendar data, such as the size and an identifier.
118 2. Conventions Used in This Document
120 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
121 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
122 "OPTIONAL" in this document are to be interpreted as described in
123 [RFC2119].
125 The notation used in this memo is the ABNF notation of [RFC5234] as
126 used by iCalendar [RFC5545]. Any syntax elements shown below that
127 are not explicitly defined in this specification come from iCalendar
128 [RFC5545].
130 3. Overview
132 There are four main operations a client needs to do with attachments
133 for calendar data: add, update, remove, and retrieve. The first
134 three operations are carried out by the client issuing an HTTP POST
135 request on the calendar object resource to which the attachment is
136 associated and specifying the appropriate "action" query parameter.
137 In the case of the remove operation, the client can alternatively
138 directly update the calendar object resource and remove the relevant
139 "ATTACH" properties. The retrieve operation is accomplished by
140 simply issuing an HTTP GET request targeting the attachment URI
141 specified by the calendar resource's "ATTACH" property.
143 iCalendar data stored in a CalDAV calendar object resource can
144 contain multiple components when recurrences are involved. In such a
145 situation, the client needs to be able to target a specific
146 recurrence instance or multiple instances when adding or deleting
147 attachments. As a result, the POST request needs to provide a way
148 for the client to specify which recurrence instances should be
149 targeted for the attachment operation. This is accomplished through
150 use of additional query parameters on the POST request-URI.
152 3.1. Requirements
154 A server that supports the features described in this specification
155 is REQUIRED to support the CalDAV "calendar-access" [RFC4791]
156 features.
158 In addition, such a server MUST support the "return=representation"
159 Prefer header value [I-D.snell-http-prefer] on successful HTTP PUT
160 and POST requests targeting existing calendar object resources, by
161 returning the new representation of that calendar resource (including
162 its new Etag header value) in the response.
164 3.2. Discovering Support for Managed Attachments
166 A server supporting the features described in this specification MUST
167 include "calendar-managed-attachments" as a field in the DAV response
168 header from an OPTIONS request on a calendar home collection.
170 A server might choose to not support storing managed attachments on a
171 per-recurrence instance basis (i.e., they can only be added to all
172 instances as a whole). If that is the case, the server MUST include
173 "calendar-managed-attachments-no-recurrence" as a field in the DAV
174 response header from an OPTIONS request on a calendar home
175 collection. When that field is present, clients MUST NOT attempt any
176 managed attachment operations that target specific recurrence
177 instances.
179 3.3. POST Request for Managing Attachments
181 An HTTP POST request is used to add, update, or remove attachments.
182 The request-URI will contain various query parameters to specify the
183 behavior.
185 3.3.1. action= Query Parameter
187 The "action" query parameter is used to identify which attachment
188 operation the client is requesting. This parameter MUST be present
189 once on each POST request used to manage attachments. One of these
190 three values MUST be used:
192 attachment-add Indicates an operation that is adding an attachment
193 to a calendar object resource. See Section 3.4 for more details.
195 attachment-update Indicates an operation that is updating an
196 existing attachment on a calendar object resource. See
197 Section 3.5 for more details.
199 attachment-remove Indicates an operation that is removing an
200 attachment on a calendar object resource. See Section 3.6 for
201 more details.
203 Example:
204 http://calendar.example.com/events/1.ics?action=attachment-add
206 3.3.2. rid= Query Parameter
208 The "rid" query parameter is used to identify which recurrence
209 instances are being targeted by the client for the attachment
210 operation. This query parameter MUST contain one or more items,
211 separated by commas (0x2C). The item values can be in one of two
212 forms:
214 Master instance The value "M" (case-insensitive) refers to the
215 "master" recurrence instance, i.e., the component that does not
216 include a "RECURRENCE-ID" property. This item MUST be present
217 only once.
219 Specific instance A specific iCalendar instance is targeted by using
220 its "RECURRENCE-ID" value as the item value. That value MUST
221 correspond to the RECURRENCE-ID value as stored in the calendar
222 object resource (i.e. without any conversion to UTC). If multiple
223 items of this form are used, they MUST be unique values.
225 If the "rid" query parameter is not present, all recurrence instances
226 in the calendar object resource are targeted.
228 The "rid" query parameter MUST NOT be present in the case of an
229 update operation, or if the server chooses not to support per-
230 recurrence instance managed attachments (see Section 3.1).
232 Example:
233 http://calendar.example.com/events/1.ics?
234 action=attachment-add&rid=M,20111022T160000
236 3.3.3. managed-id= Query Parameter
238 The "managed-id" query parameter is used to identify which "ATTACH"
239 property is being updated or removed. The value of this query
240 parameter MUST match the "MANAGED-ID" property parameter value on the
241 "ATTACH" property in the calendar object resource instance(s)
242 targeted by the request.
244 The "managed-id" query parameter MUST NOT be present in the case of
245 an add operation.
247 Example:
248 http://calendar.example.com/events/1.ics?
249 action=attachment-update&managed-id=aUNhbGVuZGFy
251 3.4. Adding attachments
253 To add an attachment to an existing calendar object resource, the
254 following occurs:
256 1. The client issues a POST request targeted at the calendar object
257 resource.
259 A. The request-URI will include an "action" query parameter with
260 the value "attachment-add" (see Section 3.3.1).
262 B. If all recurrence instances are having an attachment added,
263 the "rid" query parameter is not present in the request-URI.
264 If one or more specific recurrence instances are targeted,
265 then the request-URI will include a "rid" query parameter
266 containing the list of instances (see Section 3.3.2).
268 C. The body of the request contains the data for the attachment.
270 D. The client MUST include a valid Content-Type HTTP header
271 describing the media type of the attachment (as required by
272 HTTP).
274 E. The client SHOULD include a Content-Disposition HTTP header
275 [RFC6266] with a "type" parameter set to "attachment", and a
276 "filename" parameter that indicates the name of the
277 attachment.
279 2. When the server receives the POST request it does the following:
281 A. Validates that any recurrence instances referred to via the
282 "rid" query parameter are valid for the calendar object
283 resource being targeted.
285 B. Stores the supplied attachment data into a resource and
286 generates an appropriate URI for clients to access the
287 resource.
289 C. For each affected recurrence instance in the calendar object
290 resource targeted by the request, the server adds an "ATTACH"
291 property, whose value is the URI of the stored attachment.
292 The "ATTACH" property MUST contain a "MANAGED-ID" parameter
293 whose value is a unique identifier (within the context of the
294 server as a whole). The "ATTACH" property SHOULD contain an
295 "FMTTYPE" parameter whose value matches the Content-Type
296 header value from the request. The "ATTACH" property SHOULD
297 contain an "FILENAME" parameter whose value matches the
298 Content-Disposition header "filename" parameter value from
299 the request, taking into account the restrictions expressed
300 in Section 4.2. The "ATTACH" property SHOULD include a
301 "SIZE" parameter whose value represents the size in octets of
302 the attachment. If a specified recurrence instance does not
303 have a matching component in the calendar object resource,
304 then the server MUST modify the calendar object resource to
305 include the overridden component with the appropriate
306 "RECURRENCE-ID" property included.
308 D. Upon successful creation of the attachment resource, and
309 modification of the targeted calendar object resource, the
310 server MUST return an appropriate HTTP success status
311 response and include a "Cal-Managed-ID" HTTP header
312 containing the "MANAGED-ID" parameter value of the newly
313 created "ATTACH" property. The client can use the "Cal-
314 Managed-ID" header value to correlate the attachment with
315 "ATTACH" properties added to the calendar object resource.
316 It is expected that the client will immediately reload the
317 calendar object resource to refresh any local cache, or use
318 the Prefer header "return=representation" option
319 [I-D.snell-http-prefer] to have the server return the
320 modified calendar object resource data in the HTTP response.
322 In the following example, the client adds a new attachment to a non
323 recurring event and asks the server (via the Prefer
325 [I-D.snell-http-prefer] HTTP header) to return the updated version of
326 that event in the response.
328 >> Request <<
330 POST /events/64.ics?action=attachment-add HTTP/1.1
331 Host: cal.example.com
332 Content-Type: text/html; charset="utf-8"
333 Content-Disposition:attachment;filename=agenda.html
334 Content-Length: xxxx
335 Prefer: return=representation
337
338
339 Agenda
340
341
343 >> Response <<
345 HTTP/1.1 201 Created
346 Content-Type: text/calendar; charset="utf-8"
347 Content-Length: yyyy
348 Content-Location: http://cal.example.com/events/64.ics
349 ETag: "123456789-000-111"
350 Cal-Managed-ID: 97S
352 BEGIN:VCALENDAR
353 VERSION:2.0
354 PRODID:-//Example Corp.//CalDAV Server//EN
355 BEGIN:VEVENT
356 UID:20010712T182145Z-123401@example.com
357 DTSTAMP:20120201T203412Z
358 DTSTART:20120714T170000Z
359 DTEND:20120715T040000Z
360 SUMMARY:One-off meeting
361 ATTACH;MANAGED-ID=97S;FMTTYPE=text/html;SIZE=xxxx;
362 FILENAME=agenda.html:https://cal.example.com/attach/64/34X22R
363 END:VEVENT
364 END:VCALENDAR
366 3.5. Updating Attachments
368 When an attachment is updated the server MUST change the associated
369 "MANAGED-ID" parameter and MAY change the "ATTACH" property value.
370 With this approach, clients are able to determine when an attachment
371 has been updated by some other client by looking for a change to
372 either the "ATTACH" property value, or the "MANAGED-ID" parameter
373 value.
375 To change the data of an existing managed attachment in a calendar
376 object resource, the following occurs:
378 1. The client issues a POST request targeted at the calendar object
379 resource.
381 A. The request-URI will include an "action" query parameter with
382 the value "attachment-update" (see Section 3.3.1).
384 B. The request-URI will include a "managed-id" query parameter
385 with the value matching that of the "MANAGED-ID" parameter
386 for the "ATTACH" property being updated (see Section 3.3.3).
388 C. The body of the request contains the updated data for the
389 attachment.
391 D. The client MUST include a valid Content-Type header
392 describing the media type of the attachment (as required by
393 HTTP).
395 E. The client SHOULD include a Content-Disposition header
396 [RFC6266] with a "type" parameter set to "attachment", and a
397 "filename" parameter that indicates the name of the
398 attachment.
400 2. When the server receives the POST request it does the following:
402 A. Validates that the "managed-id" query parameter is valid for
403 the calendar object resource.
405 B. Updates the content of the attachment resource corresponding
406 to that managed-id with the supplied attachment data.
408 C. For each affected recurrence instance in the calendar object
409 resource targeted by the request, the server updates the
410 "ATTACH" property whose "MANAGED-ID" property parameter value
411 matches the "managed-id" query parameter. The "MANAGED-ID"
412 parameter value is changed to allow other clients to detect
413 the update, and the property value (attachment URI) might
414 also be changed. The "ATTACH" property SHOULD contain a
415 "FMTTYPE" parameter whose value matches the Content-Type
416 header value from the request - this could differ from the
417 original value if the media type of the updated attachment is
418 different. The "ATTACH" property SHOULD contain a "FILENAME"
419 parameter whose value matches the Content-Disposition header
420 "filename" parameter value from the request, taking into
421 account the restrictions expressed in Section 4.2. The
422 "ATTACH" property SHOULD include a "SIZE" parameter whose
423 value represents the size in octets of the updated
424 attachment.
426 D. Upon successful update of the attachment resource, and
427 modification of the targeted calendar object resource, the
428 server MUST return an appropriate HTTP success status
429 response, and include a "Cal-Managed-ID" HTTP header
430 containing the new value of the "MANAGED-ID" parameter. It
431 is expected that the client will immediately reload the
432 calendar object resource to refresh any local cache, or use
433 the Prefer header "return=representation" option
434 [I-D.snell-http-prefer] to have the server return the
435 modified calendar object resource data in the HTTP response.
437 The update operation does not take a "rid" parameter and does not
438 add, or remove, any "ATTACH" property in the targetted calendar
439 object resource. To link an existing attachment to a new instance,
440 the client simply does a PUT on the calendar object resource, adding
441 an "ATTACH" property which duplicates the existing one (see
442 Section 3.7).
444 In the following example, the client updates an existing attachment
445 and asks the server (via the Prefer [I-D.snell-http-prefer] HTTP
446 header) to return the updated version of that event in the response.
448 >> Request <<
450 POST /events/64.ics?action=attachment-update&managed-id=97S HTTP/1.1
451 Host: cal.example.com
452 Content-Type: text/html; charset="utf-8"
453 Content-Disposition:attachment;filename=agenda.html
454 Content-Length: xxxx
455 Prefer: return=representation
457
458
459 Agenda
460 Discuss attachment draft
461
462
464 >> Response <<
466 HTTP/1.1 200 OK
467 Content-Type: text/calendar; charset="utf-8"
468 Content-Length: yyyz
469 Content-Location: http://cal.example.com/events/64.ics
470 Cal-Managed-ID: 98S
471 ETag: "123456789-000-222"
473 BEGIN:VCALENDAR
474 VERSION:2.0
475 PRODID:-//Example Corp.//CalDAV Server//EN
476 BEGIN:VEVENT
477 UID:20010712T182145Z-123401@example.com
478 DTSTAMP:20120201T203412Z
479 DTSTART:20120714T170000Z
480 DTEND:20120715T040000Z
481 SUMMARY:One-off meeting
482 ATTACH;MANAGED-ID=98S;FMTTYPE=text/html;SIZE=xxxy;
483 FILENAME=agenda.html:https://cal.example.com/attach/64/34X22R
484 END:VEVENT
485 END:VCALENDAR
487 3.6. Removing Attachments via POST
489 To remove an existing attachment from a calendar object, the
490 following occurs:
492 1. The client issues a POST request targeted at the calendar object
493 resource.
495 A. The request-URI will include an "action" query parameter with
496 the value "attachment-remove" (see Section 3.3.1).
498 B. If all recurrence instances are having an attachment removed,
499 the "rid" query parameter is not present in the request-URI.
500 If one or more specific recurrence instances are targeted,
501 then the request-URI will include a "rid" query parameter
502 containing the list of instances (see Section 3.3.2).
504 C. The request-URI will include a "managed-id" query parameter
505 with the value matching that of the "MANAGED-ID" property
506 parameter for the "ATTACH" property being removed (see
507 Section 3.3.3).
509 D. The body of the request will be empty.
511 2. When the server receives the POST request it does the following:
513 A. Validates that any recurrence instances referred to via the
514 "rid" query parameter are valid for the calendar object
515 resource being targeted.
517 B. Validates that the "managed-id" query parameter is valid for
518 the calendar object resource and specific instances being
519 targeted.
521 C. For each affected recurrence instance in the calendar object
522 resource targeted by the request, the server removes the
523 matching "ATTACH" property. Note that if a specified
524 recurrence instance does not have a matching component in the
525 calendar object resource, then the server MUST modify the
526 calendar object resource to include the overridden component
527 with the appropriate "RECURRENCE-ID" property included, and
528 the matching "ATTACH" property removed. This later case is
529 actually valid only if the master component does include the
530 referenced "ATTACH" property.
532 D. If the attachment resource is no longer referenced by any
533 instance of the calendar object resource, the server can
534 delete the attachment resource to free up storage space.
536 E. Upon successful removal of the attachment resource and
537 modification of the targeted calendar object resource, the
538 server MUST return an appropriate HTTP success status
539 response. It is expected that the client will immediately
540 reload the calendar object resource to refresh any local
541 cache, or use the Prefer header "return=representation"
542 option [I-D.snell-http-prefer] to have the server return the
543 modified calendar object resource data in the HTTP response.
545 In the following example, the client deletes an existing attachment
546 by passing its managed-id in the request. The Prefer
547 [I-D.snell-http-prefer] HTTP header is not set in the request so the
548 calendar object resource data is not returned in the response.
550 >> Request <<
552 POST /events/64.ics?action=attachment-remove&managed-id=98S HTTP/1.1
553 Host: cal.example.com
554 Content-Length: 0
556 >> Response <<
558 HTTP/1.1 204 No Content
559 Content-Length: 0
561 3.7. Adding Existing Managed Attachments via PUT
563 Clients can make use of existing managed attachments by adding the
564 corresponding "ATTACH" property to calendar object resources (subject
565 to the restrictions described in Section 3.11.3). When this occurs,
566 servers SHOULD NOT change either the "MANAGED-ID" parameter value or
567 the "ATTACH" property value for any managed attachments - this
568 ensures that clients do not have to download the attachment data
569 again if they already have it cached, because it is used in another
570 calendar resource.
572 3.8. Updating Attachments via PUT
574 Servers MUST NOT allow clients to update attachment data directly via
575 a PUT on the attachment URI (or via any other HTTP method that
576 modifies content). Instead, attachments can only be manipulated via
577 use of POST requests on the calendar data.
579 3.9. Removing Attachments via PUT
581 Clients can remove attachments by simply re-writing the calendar
582 object resource data to remove the appropriate "ATTACH" properties.
583 Servers MUST NOT allow clients to delete attachments directly via a
584 DELETE request on the attachment URI.
586 3.10. Retrieving Attachments
588 Clients retrieve attachments by issuing an HTTP GET request using the
589 value of the corresponding "ATTACH" property as the request-URI,
590 taking into account the substitution mechanism associated with the
591 "CALDAV:managed-attachments-server-URL" property (see Section 6.1).
593 3.11. Additional Considerations
595 3.11.1. Error Handling
597 This specification creates additional preconditions for the POST
598 method.
600 The new preconditions are:
602 (CALDAV:max-attachment-size): The attachment submitted in the POST
603 request MUST have an octet size less than or equal to the value of
604 the CALDAV:max-attachment-size property value (Section 6.2) on the
605 calendar collection of the target calendar resource;
607 (CALDAV:max-attachments-per-resource): The addition of the
608 attachment submitted in the POST request MUST result in the target
609 calendar resource having a number of managed attachments less than
610 or equal to the value of the CALDAV:max-attachments-per-resource
611 property value (Section 6.3) on the calendar collection of the
612 target calendar resource;
614 (CALDAV:valid-managed-id): The managed-id POST request query
615 parameter MUST contain a value corresponding to a "MANAGED-ID"
616 property parameter value in the iCalendar data targeted by the
617 request.
619 A POST request to add, modify, or delete a managed attachment results
620 in an implicit modification of the targeted calendar resource
621 (equivalent of a PUT). As a consequence, clients should also be
622 prepared to handle preconditions associated with this implicit PUT.
623 This includes (but is not limited to):
625 (CALDAV:max-resource-size) (from Section 5.3.2.1 of [RFC4791])
626 (DAV:quota-not-exceeded) (from Section 6 of [RFC4331])
628 (DAV:sufficient-disk-space) (from Section 6 of [RFC4331])
630 A PUT request to add or modify and existing calendar object resource
631 can make reference to a managed attachment. The following new
632 preconditions is defined:
634 (CALDAV:valid-managed-id-parameter): a "MANAGED-ID" property
635 parameter value in the iCalendar data in the PUT request is not
636 valid (e.g., does not match any existing managed attachment).
638 3.11.2. Quotas
640 The WebDAV Quotas [RFC4331] specification defines two live WebDAV
641 properties (DAV:quota-available-bytes and DAV:quota-used-bytes) to
642 communicate storage quota information to clients. Server
643 implementations MAY choose to include managed attachments sizes when
644 calculating the amount of storage used by a particular resource.
646 3.11.3. Access Control
648 Access to the managed attachments store in a calendar object resource
649 SHOULD be restricted to only those calendar users who have access to
650 that calendar object either directly, or indirectly (via being an
651 attendee who would receive a scheduling message).
653 When accessing a managed attachment, clients SHOULD be prepared to
654 authenticate with the server storing the attachment resource. The
655 credentials required to access the managed attachment store could be
656 different from the ones used to access the CalDAV server.
658 This specification only allows organizers of scheduled events to add
659 managed attachments. Servers MUST prevent attendees of scheduled
660 events from adding, updating or removing managed attachments. In
661 addition, the server MUST prevent a calendar user from re-using a
662 managed attachment (based on its managed-id value), unless that user
663 is the one who originally created the managed attachment.
665 3.11.4. Redirects
667 For POST requests that add or update attachment data, the server MAY
668 issue an HTTP redirect to require the client to re-issue the POST
669 request using a different request-URI. As a result, it is always
670 best for clients to use the "100 Continue" behavior defined in
671 Section 8.2.3 of [RFC2616]. Using this mechanism ensures that, if a
672 redirect does occur, the client does not needlessly send the
673 attachment data.
675 3.11.5. Automatic Clean-up by servers
677 Servers MAY automatically remove attachment data, for example to
678 regain the storage taken by unused attachments, or as the result of a
679 virus scanning. When doing so they SHOULD NOT modify calendar data
680 referencing those attachments. Instead they SHOULD return a 410 HTTP
681 status response to any request on the removed attachment URI.
683 3.11.6. Sending Scheduling Messages with Attachments
685 When a managed attachment is added, updated or removed from a
686 calendar object resource, the server MUST ensure that a scheduling
687 message is sent to update any attendees with the changes, as per
688 [RFC6638].
690 3.11.7. Other Client Considerations
692 Clients can expect servers to take a while to respond to POST
693 requests that include large attachment bodies. Servers SHOULD use
694 the "100 Continue" behavior defined in Section 8.2.3 of [RFC2616] to
695 keep the client connection alive if the response will take some time.
697 When exporting calendar data from a CalDAV server supporting managed
698 attachments, clients SHOULD remove all "MANAGED-ID" property
699 parameters from "ATTACH" properties in the calendar data. Similarly
700 when importing calendar data from another source, clients SHOULD
701 remove any "MANAGED-ID" property parameters on "ATTACH" properties
702 (failure to do so will likely result in the server removing those
703 properties automatically).
705 4. Modifications to iCalendar Syntax
707 4.1. SIZE Property Parameter
709 Parameter Name: SIZE
711 Purpose: To specify the size of an attachment.
713 Format Definition: This property parameter is defined by the
714 following notation:
716 sizeparam = "SIZE" "=" paramtext
717 ; positive integers
718 Description: This property parameter MAY be specified on "ATTACH"
719 properties. It indicates the size in octets of the corresponding
720 attachment data. Since iCalendar integer values are restricted to
721 a maximum value of 2147483647, the current parameter is defined as
722 text to allow an extended range to be used.
724 Example:
726 ATTACH;SIZE=1234:http://attachments.example.com/abcd.txt
728 4.2. FILENAME Property Parameter
730 Parameter Name: FILENAME
732 Purpose: To specify the file name of a managed attachment.
734 Format Definition: This property parameter is defined by the
735 following notation:
737 filenameparam = "FILENAME" "=" paramtext
739 Description: This property parameter MAY be specified on "ATTACH"
740 properties corresponding to managed attachments. Its value
741 provides information on how to construct a filename for storing
742 the attachment data. This parameter is very similar in nature to
743 the Content-Disposition HTTP header "filename" parameter and
744 exposes the same security risks. As a consequence, clients MUST
745 follow the guidelines expressed in Section 4.3 of [RFC6266] when
746 consuming this parameter value. Similarly, servers MUST follow
747 those same guidelines before storing a value.
749 Example:
751 ATTACH;FILENAME=agenda.html:http://attachments.example.c
752 om/rt452S
754 4.3. MANAGED-ID Property Parameter
756 Parameter Name: MANAGED-ID
758 Purpose: To uniquely identify a managed attachment.
760 Format Definition: This property parameter is defined by the
761 following notation:
763 managedidparam = "MANAGED-ID" "=" paramtext
764 Description: This property parameter MUST be specified on "ATTACH"
765 properties corresponding to managed attachments. Its value is
766 generated by the server and uniquely identifies a managed
767 attachment. This property parameter MUST NOT be present in the
768 case of non managed attachments.
770 Example:
772 ATTACH;MANAGED-ID=aUNhbGVuZGFy:http://attachments.example.c
773 om/abcd.txt
775 5. Additional Message Header Fields
777 5.1. Cal-Managed-ID Response Header
779 The Cal-Managed-ID response header provides the value of the
780 MANAGED-ID parameter corresponding to a newly added ATTACH property.
781 It MUST be sent only in response to a successful POST request with an
782 action set to attachment-add.
784 Cal-Managed-ID = "Cal-Managed-ID" ":" paramtext
785 ; "paramtext" is defined in Section 3.1 of [RFC5545]
787 Example:
789 Cal-Managed-ID:aUNhbGVuZGFy
791 6. Additional WebDAV properties
793 6.1. CALDAV:managed-attachments-server-URL property
795 Name: managed-attachments-server-URL
797 Namespace: urn:ietf:params:xml:ns:caldav
799 Purpose: Specifies the server base URI to use when retrieving
800 managed attachments.
802 Protected: This property MUST be protected as only the server can
803 update the value.
805 COPY/MOVE behavior: This property is only defined on a calendar home
806 collection which cannot be moved or copied.
808 allprop behavior: SHOULD NOT be returned by a PROPFIND DAV:allprop
809 request.
811 Description: This property MAY be defined on a calendar home
812 collection. If present, it contains zero or one DAV:href XML
813 elements.
815 When one DAV:href element is present, its value MUST be an
816 absolute HTTP URI containing only the scheme (i.e. "https") and
817 authority (i.e. host and port) parts . Whenever a managed
818 attachment is to be retrieved via an HTTP GET, the client MUST
819 construct the actual URL of the attachment by substituting the
820 scheme and authority parts of the attachment URI (as stored in the
821 iCalendar "ATTACH" property) with the present WebDAV property
822 value.
824 When no DAV:href element is present, the client MUST substitute
825 the scheme and authority parts of the attachment URI with the
826 scheme and authority part of the calendar home collection absolute
827 URI.
829 In the absence of this property, the client can consider the
830 attachment URI as its actual URL.
832 Definition:
834
836 Example:
838
840 https://attachstore.example.com
841
843 6.2. CALDAV:max-attachment-size property
845 Name: max-attachment-size
847 Namespace: urn:ietf:params:xml:ns:caldav
849 Purpose: Provides a numeric value indicating the maximum attachment
850 size, in octets, that the server is willing to accept when a
851 managed attachment is stored on the server.
853 Protected: MUST be protected as it indicates limits provided by the
854 server.
856 COPY/MOVE behavior: This property value MUST be preserved in COPY
857 and MOVE operations.
859 allprop behavior: SHOULD NOT be returned by a PROPFIND DAV:allprop
860 request.
862 Description: The CALDAV:max-attachment-size property is used to
863 specify a numeric value that represents the maximum attachment
864 size, in octets, that the server is willing to accept when a
865 managed attachment is stored on the server. The property is
866 defined on the parent collection of the calendar object resource
867 to which the attachment is associated. Any attempt to store a
868 managed attachment exceeding this size MUST result in an error,
869 with the CALDAV:max-attachment-size precondition (Section 3.11.1)
870 being violated. In the absence of this property, the client can
871 assume that the server will allow storing an attachment of any
872 reasonable size.
874 Definition:
876
877
879 Example:
881 102400000
884 6.3. CALDAV:max-attachments-per-resource property
886 Name: max-attachments-per-resource
888 Namespace: urn:ietf:params:xml:ns:caldav
890 Purpose: Provides a numeric value indicating the maximum number of
891 managed attachments across all instances of a calendar object
892 resource stored in a calendar collection.
894 Protected: MUST be protected as it indicates limits provided by the
895 server.
897 COPY/MOVE behavior: This property value MUST be preserved in COPY
898 and MOVE operations.
900 allprop behavior: SHOULD NOT be returned by a PROPFIND DAV:allprop
901 request.
903 Description: The CALDAV:max-attachments-per-resource property is
904 used to specify a numeric value that represents the maximum number
905 of managed attachments across all instances of a calendar object
906 resource stored in a calendar collection. Non managed attachments
907 are not counted toward that limit. The property is defined on the
908 parent collection of the calendar object resource to which the
909 attachment is associated. Any attempt to add a managed attachment
910 that would cause the calendar resource to exceed this limit MUST
911 result in an error, with the CALDAV:max-attachments-per-resource
912 precondition (Section 3.11.1) being violated. In the absence of
913 this property, the client can assume that the server can handle
914 any number of managed attachments per calendar resource.
916 Definition:
918
919
921 Example:
923 12
927 7. Security Considerations
929 Malicious content could be introduced into the Calendar Server by way
930 of a managed attachment, and propagated to many end users via
931 scheduling. Servers SHOULD check managed attachments for malicious
932 or inappropriate content. Upon detecting of such content, servers
933 SHOULD remove the attachment, following the rules described in
934 Section 3.11.5.
936 8. IANA Considerations
938 8.1. Parameter Registrations
940 This specification defines the following new iCalendar property
941 parameters to be added to the registry defined in Section 8.2.3 of
942 [RFC5545]:
944 +--------------------+---------+----------------------+
945 | Property Parameter | Status | Reference |
946 +--------------------+---------+----------------------+
947 | FILENAME | Current | RFCXXXX, Section 4.2 |
948 | SIZE | Current | RFCXXXX, Section 4.1 |
949 | MANAGED-ID | Current | RFCXXXX, Section 4.3 |
950 +--------------------+---------+----------------------+
952 8.2. Message Header Field Registrations
954 The message header fields below should be added to the Permanent
955 Message Header Field Registry (see [RFC3864]).
957 8.2.1. Cal-Managed-ID
959 Header field name: Cal-Managed-ID
961 Applicable protocol: http
963 Status: standard
965 Author/Change controller: IETF
967 Specification document(s): this specification (Section 5.1)
969 Related information: none
971 9. Acknowledgments
973 This specification came about via discussions at the Calendaring and
974 Scheduling Consortium. Thanks in particular to Mike Douglass, Ken
975 Murchison, and Eric York.
977 10. References
979 10.1. Normative References
981 [I-D.snell-http-prefer]
982 Snell, J., "Prefer Header for HTTP",
983 draft-snell-http-prefer-18 (work in progress),
984 January 2013.
986 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
987 Requirement Levels", BCP 14, RFC 2119, March 1997.
989 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
990 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
991 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
993 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration
994 Procedures for Message Header Fields", BCP 90, RFC 3864,
995 September 2004.
997 [RFC4331] Korver, B. and L. Dusseault, "Quota and Size Properties fo
998 r Distributed Authoring and Versioning (DAV) Collections",
999 RFC 4331, February 2006.
1001 [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault,
1002 "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791,
1003 March 2007.
1005 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
1006 Specifications: ABNF", STD 68, RFC 5234, January 2008.
1008 [RFC5545] Desruisseaux, B., "Internet Calendaring and Scheduling
1009 Core Object Specification (iCalendar)", RFC 5545,
1010 September 2009.
1012 [RFC6266] Reschke, J., "Use of the Content-Disposition Header Field
1013 in the Hypertext Transfer Protocol (HTTP)", RFC 6266,
1014 June 2011.
1016 [RFC6638] Daboo, C. and B. Desruisseaux, "Scheduling Extensions to
1017 CalDAV", RFC 6638, June 2012.
1019 10.2. Informative References
1021 [RFC5546] Daboo, C., "iCalendar Transport-Independent
1022 Interoperability Protocol (iTIP)", RFC 5546,
1023 December 2009.
1025 Appendix A. Change History (To be removed by RFC Editor before
1026 publication)
1028 Changes in -03:
1030 1. Fixed some examples.
1032 2. Fixed return-representation -> return=representation.
1034 3. Added statement that servers must not allow clients to DELETE
1035 attachments directly.
1037 4. Added new preconditions for valid managed-id values.
1039 5. Filled out Access Control section.
1041 6. Allow servers to not support per-instance attachments and
1042 advertise that fact to clients.
1044 Changes in -02:
1046 1. MANAGED-ID changes on PUT.
1048 2. MTAG has been removed.
1050 3. Error pre-conditions added.
1052 4. Interaction with WebDAV QUOTA discussed.
1054 5. max-attachment-* limits added.
1056 6. Updated references.
1058 7. Removed MUST for specific 2xx codes in favor of generic success
1059 code.
1061 Changes in -01:
1063 1. Tweaked OPTIONS capability wording.
1065 2. Added section on clients expecting 100-Continue for delayed
1066 response.
1068 3. Added text for clean-up and use of HTTP 410 on orphans.
1070 4. Added text on removing "MANAGED-ID" when exporting/importing
1071 calendar data.
1073 5. Added protocol examples.
1075 6. Added MTAG property parameter on ATTACH property
1077 7. Added FILENAME property parameter on ATTACH property
1079 8. "id" query parameter is now "managed-id".
1081 9. Use of Cal-Managed-ID header instead of Location header in
1082 responses.
1084 10. rid query param MUST contain RECURRENCE-ID without any
1085 conversion to UTC (case of floating events).
1087 11. Introduced CALDAV:managed-attachments-server-URL property
1089 12. Made support for Prefer header a MUST for servers.
1091 Appendix B. Example Involving Recurring Events
1093 In the following example, the organizer of a recurring meeting adds
1094 an agenda (HTML attachment) to the corresponding calendar resource.
1095 Attendees of the meeting are granted read access to the newly created
1096 attachment resource. Their own copy of the meeting is updated to
1097 include the new ATTACH property pointing to the attachment resource
1098 and they are notified of the change via their scheduling inbox.
1100 >> Request <<
1102 POST /events/65.ics?action=attachment-add HTTP/1.1
1103 Host: cal.example.com
1104 Content-Type: text/html; charset="utf-8"
1105 Content-Disposition:attachment;filename=agenda.html
1106 Content-Length: xxxx
1107 Prefer: return=representation
1109
1110
1111 Agenda
1112 As usual
1113
1114
1116 >> Response <<
1117 HTTP/1.1 201 Created
1118 Content-Type: text/calendar; charset="utf-8"
1119 Content-Length: yyyy
1120 Content-Location: http://cal.example.com/events/65.ics
1121 ETag: "123456789-000-111"
1122 Cal-Managed-ID: 97S
1124 BEGIN:VCALENDAR
1125 VERSION:2.0
1126 PRODID:-//Example Corp.//CalDAV Server//EN
1127 BEGIN:VTIMEZONE
1128 LAST-MODIFIED:20040110T032845Z
1129 TZID:America/Montreal
1130 BEGIN:DAYLIGHT
1131 DTSTART:20000404T020000
1132 RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4
1133 TZNAME:EDT
1134 TZOFFSETFROM:-0500
1135 TZOFFSETTO:-0400
1136 END:DAYLIGHT
1137 BEGIN:STANDARD
1138 DTSTART:20001026T020000
1139 RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10
1140 TZNAME:EST
1141 TZOFFSETFROM:-0400
1142 TZOFFSETTO:-0500
1143 END:STANDARD
1144 END:VTIMEZONE
1145 BEGIN:VEVENT
1146 UID:20010712T182145Z-123401@example.com
1147 DTSTAMP:20120201T203412Z
1148 DTSTART;TZID=America/Montreal:20120206T100000
1149 DURATION:PT1H
1150 RRULE:FREQ=WEEKLY
1151 SUMMARY:Planning Meeting
1152 ORGANIZER:mailto:cyrus@example.com
1153 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:cyrus@exampl
1154 e.com
1155 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:arnaudq@exam
1156 ple.com
1157 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=NEEDS-ACTION:mailto:mike@exa
1158 mple.com
1159 ATTACH;MANAGED-ID=97S;FMTTYPE=text/html;SIZE=xxxx;
1160 FILENAME=agenda.html:https://cal.example.com/attach/65/34X22R
1161 END:VEVENT
1162 END:VCALENDAR
1163 The organizer has a more specific agenda for the 20th of February
1164 meeting. It is added to that particular instance of the meeting by
1165 specifying the rid parameter.
1167 >> Request <<
1169 POST /events/65.ics?action=attachment-add&rid=20120220T100000 HTTP/1.1
1170 Host: cal.example.com
1171 Content-Type: text/html; charset="utf-8"
1172 Content-Disposition:attachment;filename=agenda0220.html
1173 Content-Length: xxxx
1174 Prefer: return=representation
1176
1177
1178 Agenda
1179 Something different, for a change
1180
1181
1183 >> Response <<
1185 HTTP/1.1 201 Created
1186 Content-Type: text/calendar; charset="utf-8"
1187 Content-Length: yyyy
1188 Content-Location: http://cal.example.com/events/65.ics
1189 ETag: "123456789-000-222"
1190 Cal-Managed-ID: 33225
1192 BEGIN:VCALENDAR
1193 VERSION:2.0
1194 PRODID:-//Example Corp.//CalDAV Server//EN
1195 BEGIN:VTIMEZONE
1196 LAST-MODIFIED:20040110T032845Z
1197 TZID:America/Montreal
1198 BEGIN:DAYLIGHT
1199 DTSTART:20000404T020000
1200 RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4
1201 TZNAME:EDT
1202 TZOFFSETFROM:-0500
1203 TZOFFSETTO:-0400
1204 END:DAYLIGHT
1205 BEGIN:STANDARD
1206 DTSTART:20001026T020000
1207 RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10
1208 TZNAME:EST
1209 TZOFFSETFROM:-0400
1210 TZOFFSETTO:-0500
1211 END:STANDARD
1212 END:VTIMEZONE
1213 BEGIN:VEVENT
1214 UID:20010712T182145Z-123401@example.com
1215 DTSTAMP:20120201T203412Z
1216 DTSTART;TZID=America/Montreal:20120206T100000
1217 DURATION:PT1H
1218 RRULE:FREQ=WEEKLY
1219 SUMMARY:Planning Meeting
1220 ORGANIZER:mailto:cyrus@example.com
1221 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:cyrus@exampl
1222 e.com
1223 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:arnaudq@exam
1224 ple.com
1225 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=NEEDS-ACTION:mailto:mike@exa
1226 mple.com
1227 ATTACH;MANAGED-ID=97S;FMTTYPE=text/html;SIZE=xxxx;
1228 FILENAME=agenda.html:https://cal.example.com/attach/65/34X22R
1229 END:VEVENT
1230 BEGIN:VEVENT
1231 UID:20010712T182145Z-123401@example.com
1232 RECURRENCE-ID;TZID=America/Montreal:20120220T100000
1233 DTSTAMP:20120201T203412Z
1234 DTSTART;TZID=America/Montreal:20120220T100000
1235 DURATION:PT1H
1236 SUMMARY:Planning Meeting
1237 ORGANIZER:mailto:cyrus@example.com
1238 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:cyrus@example.
1239 com
1240 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:arnaudq@exampl
1241 e.com
1242 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=NEEDS-ACTION:mailto:mike@examp
1243 le.com
1244 ATTACH;MANAGED-ID=33225;FMTTYPE=text/html;SIZE=xxxx;
1245 FILENAME=agenda0220.html:https://cal.example.com/attach/65/FGZ225
1246 END:VEVENT
1247 END:VCALENDAR
1249 Authors' Addresses
1251 Cyrus Daboo
1252 Apple Inc.
1253 1 Infinite Loop
1254 Cupertino, CA 95014
1255 USA
1257 Email: cyrus@daboo.name
1258 URI: http://www.apple.com/
1260 Arnaud Quillaud
1261 Oracle Corporation
1262 180, Avenue de l'Europe
1263 Saint Ismier cedex, 38334
1264 France
1266 Email: arnaud.quillaud@oracle.com
1267 URI: http://www.oracle.com/