idnits 2.17.00 (12 Aug 2021) /tmp/idnits40193/draft-ietf-calext-caldav-attachments-04.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 seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (March 5, 2019) is 1166 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 1303 -- Looks like a reference, but probably isn't: '2' on line 1305 -- Looks like a reference, but probably isn't: '3' on line 1307 -- Looks like a reference, but probably isn't: '4' on line 1309 -- Looks like a reference, but probably isn't: '5' on line 1311 -- Looks like a reference, but probably isn't: '6' on line 1313 -- Looks like a reference, but probably isn't: '7' on line 1315 -- Looks like a reference, but probably isn't: '8' on line 1317 -- Looks like a reference, but probably isn't: '9' on line 1319 -- Looks like a reference, but probably isn't: '10' on line 1321 -- Looks like a reference, but probably isn't: '11' on line 1323 ** Obsolete normative reference: RFC 2518 (Obsoleted by RFC 4918) -- Obsolete informational reference (is this intentional?): RFC 7320 (Obsoleted by RFC 8820) Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 13 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Calendering Extensions C. Daboo 3 Internet-Draft Apple 4 Intended status: Informational A. Quillaud 5 Expires: September 6, 2019 Oracle 6 K. Murchison, Ed. 7 FastMail 8 March 5, 2019 10 CalDAV Managed Attachments 11 draft-ietf-calext-caldav-attachments-04 13 Abstract 15 This specification defines an extension to the calendar access 16 protocol (CalDAV) to allow attachments associated with iCalendar data 17 to be stored and managed on the server. 19 This specification documents existing code deployed by multiple 20 vendors. It is published as an Informational specification rather 21 than Standards Track due to its noncompliance with multiple best 22 current practices of HTTP. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at https://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on September 6, 2019. 41 Copyright Notice 43 Copyright (c) 2019 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (https://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 59 1.1. Rationale for Informational Status . . . . . . . . . . . 4 60 2. Conventions Used in This Document . . . . . . . . . . . . . . 4 61 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 4 62 3.1. Requirements . . . . . . . . . . . . . . . . . . . . . . 5 63 3.2. Discovering Support for Managed Attachments . . . . . . . 5 64 3.3. POST Request for Managing Attachments . . . . . . . . . . 5 65 3.3.1. action= Query Parameter . . . . . . . . . . . . . . . 6 66 3.3.2. rid= Query Parameter . . . . . . . . . . . . . . . . 6 67 3.3.3. managed-id= Query Parameter . . . . . . . . . . . . . 7 68 3.4. Adding attachments . . . . . . . . . . . . . . . . . . . 7 69 3.5. Updating Attachments . . . . . . . . . . . . . . . . . . 10 70 3.6. Removing Attachments via POST . . . . . . . . . . . . . . 13 71 3.7. Adding Existing Managed Attachments via PUT . . . . . . . 15 72 3.8. Updating Attachments via PUT . . . . . . . . . . . . . . 15 73 3.9. Removing Attachments via PUT . . . . . . . . . . . . . . 15 74 3.10. Retrieving Attachments . . . . . . . . . . . . . . . . . 16 75 3.11. Error Handling . . . . . . . . . . . . . . . . . . . . . 16 76 3.12. Additional Considerations . . . . . . . . . . . . . . . . 17 77 3.12.1. Quotas . . . . . . . . . . . . . . . . . . . . . . . 17 78 3.12.2. Access Control . . . . . . . . . . . . . . . . . . . 17 79 3.12.3. Redirects . . . . . . . . . . . . . . . . . . . . . 18 80 3.12.4. Processing Time . . . . . . . . . . . . . . . . . . 18 81 3.12.5. Automatic Clean-Up by Servers . . . . . . . . . . . 18 82 3.12.6. Sending Scheduling Messages with Attachments . . . . 18 83 3.12.7. Migrating Calendar Data . . . . . . . . . . . . . . 18 84 4. Modifications to iCalendar Syntax . . . . . . . . . . . . . . 19 85 4.1. SIZE Property Parameter . . . . . . . . . . . . . . . . . 19 86 4.2. FILENAME Property Parameter . . . . . . . . . . . . . . . 19 87 4.3. MANAGED-ID Property Parameter . . . . . . . . . . . . . . 20 88 5. Additional Message Header Fields . . . . . . . . . . . . . . 20 89 5.1. Cal-Managed-ID Response Header Field . . . . . . . . . . 20 90 6. Additional WebDAV Properties . . . . . . . . . . . . . . . . 21 91 6.1. CALDAV:managed-attachments-server-URL property . . . . . 21 92 6.2. CALDAV:max-attachment-size property . . . . . . . . . . . 22 93 6.3. CALDAV:max-attachments-per-resource property . . . . . . 23 94 7. Implementation Status . . . . . . . . . . . . . . . . . . . . 23 95 8. Security Considerations . . . . . . . . . . . . . . . . . . . 25 96 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 97 9.1. Parameter Registrations . . . . . . . . . . . . . . . . . 26 98 9.2. Message Header Field Registrations . . . . . . . . . . . 26 99 9.2.1. Cal-Managed-ID . . . . . . . . . . . . . . . . . . . 26 100 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 27 101 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 27 102 11.1. Normative References . . . . . . . . . . . . . . . . . . 27 103 11.2. Informative References . . . . . . . . . . . . . . . . . 28 104 11.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 29 105 Appendix A. Change History (To be removed by RFC Editor before 106 publication) . . . . . . . . . . . . . . . . . . . . 29 107 Appendix B. Example Involving Recurring Events . . . . . . . . . 32 108 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 39 110 1. Introduction 112 The iCalendar [RFC5545] data format is used to represent calendar 113 data and is used with iCalendar Transport-independent 114 Interoperability Protocol (iTIP) [RFC5546] to handle scheduling 115 operations between calendar users. 117 [RFC4791] defines the Calendaring Extensions to WebDAV (CalDAV), 118 based on HTTP [RFC7230], for accessing calendar data stored on a 119 server. 121 Calendar users often want to include attachments with their calendar 122 data events or tasks (for example a copy of a presentation, or the 123 meeting agenda). iCalendar provides an "ATTACH" property whose value 124 is either the inline Base64 encoded attachment data, or a URL 125 specifying the location of the attachment data. 127 Use of inline attachment data is not ideal with CalDAV because the 128 data would need to be uploaded to the server each time a change to 129 the calendar data is done - even minor changes such as a change to 130 the summary. Whilst a client could choose to use a URL value 131 instead, the problem then becomes where and how the client discovers 132 an appropriate URL to use and how it ensures that only those 133 attendees listed in the event or task are able to access it. 135 This specification solves this problem by having the client send the 136 attachment to the server, separately from the iCalendar data, and the 137 server takes care of adding appropriate "ATTACH" properties in the 138 iCalendar data as well as managing access privileges. The server can 139 also provide additional information to the client about each 140 attachment in the iCalendar data, such as the size and an identifier. 142 1.1. Rationale for Informational Status 144 Although this extension to CalDAV has wide deployment, its design 145 does not comply with some of the best current practices of HTTP, 146 namely: 148 o All operations on attachments are modeled as HTTP POST operations, 149 where the actual type of operation is specified using a query 150 parameter, instead of using separate HTTP POST, PUT, and DELETE 151 methods where appropriate. 153 o Specific query strings are hardwired into the protocol in 154 violation of Section 2.4 of [RFC7320]. 156 Additionally, this extension misuses the Content-Disposition header 157 field [RFC6266] as a request header field to convey a filename for an 158 attachment rather than using an existing request header field 159 suitable for that purpose, such as "Slug" (see Section 9.7 of 160 [RFC5023]). 162 Rather than creating interoperability problems with deployed code by 163 updating the design of this extension to be compliant with best 164 current practices and to allow this specification to be placed on the 165 Standards Track, it was decided to simply document how existing 166 implementations interoperate and to publish the document as 167 Informational. 169 2. Conventions Used in This Document 171 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 172 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 173 "OPTIONAL" in this document are to be interpreted as described in BCP 174 14 [1] [RFC2119] [RFC8174] when, and only when, they appear in all 175 capitals, as shown here. 177 The notation used in this memo is the ABNF notation of [RFC5234] as 178 used by iCalendar [RFC5545]. Any syntax elements shown below that 179 are not explicitly defined in this specification come from iCalendar 180 [RFC5545]. 182 3. Overview 184 There are four main operations a client needs to do with attachments 185 for calendar data: add, update, remove, and retrieve. The first 186 three operations are carried out by the client issuing an HTTP POST 187 request on the calendar object resource to which the attachment is 188 associated and specifying the appropriate "action" query parameter 189 (see Section 3.3). In the case of the remove operation, the client 190 can alternatively directly update the calendar object resource and 191 remove the relevant "ATTACH" properties (see Section 3.9). The 192 retrieve operation is accomplished by simply issuing an HTTP GET 193 request targeting the attachment URI specified by the calendar 194 resource's "ATTACH" property (see Section 3.10). 196 iCalendar data stored in a CalDAV calendar object resource can 197 contain multiple components when recurrences are involved. In such a 198 situation, the client needs to be able to target a specific 199 recurrence instance or multiple instances when adding or deleting 200 attachments. As a result, the POST request needs to provide a way 201 for the client to specify which recurrence instances should be 202 targeted for the attachment operation. This is accomplished through 203 use of additional query parameters on the POST request-URI. 205 3.1. Requirements 207 A server that supports the features described in this specification 208 is REQUIRED to support the CalDAV "calendar-access" [RFC4791] 209 features. 211 In addition, such a server SHOULD support the "return=representation" 212 Prefer header field [RFC7240] preference on successful HTTP PUT and 213 POST requests targeting existing calendar object resources, by 214 returning the new representation of that calendar resource (including 215 its new ETag header field value) in the response. 217 3.2. Discovering Support for Managed Attachments 219 A server supporting the features described in this specification MUST 220 include "calendar-managed-attachments" as a token in the DAV response 221 header field (as defined in Section 10.1 of [RFC4918]) from an 222 OPTIONS request on a calendar home collection. 224 A server might choose to not support storing managed attachments on a 225 per-recurrence instance basis (i.e., they can only be added to all 226 instances as a whole). If that is the case, the server MUST also 227 include "calendar-managed-attachments-no-recurrence" as a token in 228 the DAV response header field from an OPTIONS request on a calendar 229 home collection. When that field is present, clients MUST NOT 230 attempt any managed attachment operations that target specific 231 recurrence instances. 233 3.3. POST Request for Managing Attachments 235 An HTTP POST request is used to add, update, or remove attachments. 236 These requests are subject to the preconditions listed in 237 Section 3.11. The request-URI will contain various query parameters 238 to specify the behavior. 240 3.3.1. action= Query Parameter 242 The "action" query parameter is used to identify which attachment 243 operation the client is requesting. This parameter MUST be present 244 once on each POST request used to manage attachments. One of these 245 three values MUST be used: 247 attachment-add Indicates an operation that is adding an attachment 248 to a calendar object resource. See Section 3.4 for more details. 250 attachment-update Indicates an operation that is updating an 251 existing attachment on a calendar object resource. See 252 Section 3.5 for more details. 254 attachment-remove Indicates an operation that is removing an 255 attachment from a calendar object resource. See Section 3.6 for 256 more details. 258 Example: 260 https://calendar.example.com/events/1.ics?action=attachment-add 262 3.3.2. rid= Query Parameter 264 The "rid" query parameter is used to identify which recurrence 265 instances are being targeted by the client for the attachment 266 operation. This query parameter MUST contain one or more items, 267 separated by commas (0x2C). The item values can be in one of two 268 forms: 270 Master instance The value "M" (case-insensitive) refers to the 271 "master" recurrence instance, i.e., the component that does not 272 include a "RECURRENCE-ID" property. This item MUST be present 273 only once. 275 Specific instance A specific iCalendar instance is targeted by using 276 its "RECURRENCE-ID" value as the item value. That value MUST 277 correspond to the RECURRENCE-ID value as stored in the calendar 278 object resource (i.e. without any conversion to UTC). If multiple 279 items of this form are used, they MUST be unique values. For 280 example, to target a recurrence defined by property RECURRENCE- 281 ID;TZID=America/Montreal:20111022T160000, the query parameter 282 rid=20111022T160000 would be used. 284 If the "rid" query parameter is not present, all recurrence instances 285 in the calendar object resource are targeted. 287 The "rid" query parameter MUST NOT be present in the case of an 288 update operation, or if the server chooses not to support per- 289 recurrence instance managed attachments (see Section 3.1). 291 Example (targeting the master instance and a specific overridden 292 instance): 294 https://calendar.example.com/events/1.ics? 295 action=attachment-add&rid=M,20111022T160000 297 3.3.3. managed-id= Query Parameter 299 The "managed-id" query parameter is used to identify which "ATTACH" 300 property is being updated or removed. The value of this query 301 parameter MUST match the "MANAGED-ID" (Section 4.3) property 302 parameter value on the "ATTACH" property in the calendar object 303 resource instance(s) targeted by the request. 305 The "managed-id" query parameter MUST NOT be present in the case of 306 an add operation. 308 Example: 310 https://calendar.example.com/events/1.ics? 311 action=attachment-update&managed-id=aUNhbGVuZGFy 313 3.4. Adding attachments 315 To add an attachment to an existing calendar object resource, the 316 following occurs: 318 1. The client issues a POST request targeted at the calendar object 319 resource. 321 A. The request-URI will include an "action" query parameter with 322 the value "attachment-add" (see Section 3.3.1). 324 B. If all recurrence instances are having an attachment added, 325 the "rid" query parameter is not present in the request-URI. 326 If one or more specific recurrence instances are targeted, 327 then the request-URI will include a "rid" query parameter 328 containing the list of instances (see Section 3.3.2). 330 C. The body of the request contains the data for the attachment. 332 D. The client MUST include a valid Content-Type header field 333 describing the media type of the attachment (as required by 334 HTTP). 336 E. The client SHOULD include a Content-Disposition header field 337 [RFC6266] with a "type" parameter set to "attachment", and a 338 "filename" parameter that indicates the name of the 339 attachment. Note that the use of Content-Disposition as a 340 request header field is nonstandard and specific to this 341 protocol. 343 F. The client MAY include a Prefer header field [RFC7240] with 344 the "return=representation" preference to request that the 345 modified calendar object resource be returned as the body of 346 a successful response to the POST request. 348 2. When the server receives the POST request it does the following: 350 A. Validates that any recurrence instances referred to via the 351 "rid" query parameter are valid for the calendar object 352 resource being targeted. 354 B. Stores the supplied attachment data into a resource and 355 generates an appropriate URI for clients to access the 356 resource. 358 C. For each affected recurrence instance in the calendar object 359 resource targeted by the request, the server adds an "ATTACH" 360 property, whose value is the URI of the stored attachment. 361 The "ATTACH" property MUST contain a "MANAGED-ID" parameter 362 whose value is a unique identifier (within the context of the 363 server as a whole). The "ATTACH" property SHOULD contain an 364 "FMTTYPE" parameter whose value matches the Content-Type 365 header field value from the request. The "ATTACH" property 366 SHOULD contain an "FILENAME" parameter whose value matches 367 the Content-Disposition header field "filename" parameter 368 value from the request, taking into account the restrictions 369 expressed in Section 4.2. The "ATTACH" property SHOULD 370 include a "SIZE" parameter whose value represents the size in 371 octets of the attachment. If a specified recurrence instance 372 does not have a matching component in the calendar object 373 resource, then the server MUST modify the calendar object 374 resource to include an overridden component with the 375 appropriate "RECURRENCE-ID" property. 377 D. Upon successful creation of the attachment resource, and 378 modification of the targeted calendar object resource, the 379 server MUST return an appropriate HTTP success status 380 response and include a "Cal-Managed-ID" header field 381 containing the "MANAGED-ID" parameter value of the newly 382 created "ATTACH" property. The client can use the "Cal- 383 Managed-ID" header field value to correlate the attachment 384 with "ATTACH" properties added to the calendar object 385 resource. If the client included a Prefer header field with 386 the "return=representation" preference in the request, the 387 server SHOULD return the modified calendar object resource as 388 the body of the response. Otherwise, the server can expect 389 that the client will reload the calendar object resource with 390 a subsequent GET request to refresh any local cache. 392 In the following example, the client adds a new attachment to a non 393 recurring event and asks the server (via the Prefer [RFC7240] header 394 field) to return the modified version of that event in the response. 396 >> Request << 398 POST /events/64.ics?action=attachment-add HTTP/1.1 399 Host: cal.example.com 400 Content-Type: text/html; charset="utf-8" 401 Content-Disposition:attachment;filename=agenda.html 402 Content-Length: xxxx 403 Prefer: return=representation 405 406 407

Agenda

408 409 410 >> Response << 412 HTTP/1.1 201 Created 413 Content-Type: text/calendar; charset="utf-8" 414 Content-Length: yyyy 415 Content-Location: https://cal.example.com/events/64.ics 416 ETag: "123456789-000-111" 417 Cal-Managed-ID: 97S 419 BEGIN:VCALENDAR 420 VERSION:2.0 421 PRODID:-//Example Corp.//CalDAV Server//EN 422 BEGIN:VEVENT 423 UID:20010712T182145Z-123401@example.com 424 DTSTAMP:20120201T203412Z 425 DTSTART:20120714T170000Z 426 DTEND:20120715T040000Z 427 SUMMARY:One-off meeting 428 ATTACH;MANAGED-ID=97S;FMTTYPE=text/html;SIZE=xxxx; 429 FILENAME=agenda.html:https://cal.example.com/attach/64/34X22R 430 END:VEVENT 431 END:VCALENDAR 433 3.5. Updating Attachments 435 When an attachment is updated the server MUST change the associated 436 "MANAGED-ID" parameter and MAY change the "ATTACH" property value. 437 With this approach, clients are able to determine when an attachment 438 has been updated by some other client by looking for a change to 439 either the "ATTACH" property value, or the "MANAGED-ID" parameter 440 value. 442 To change the data of an existing managed attachment in a calendar 443 object resource, the following occurs: 445 1. The client issues a POST request targeted at the calendar object 446 resource. 448 A. The request-URI will include an "action" query parameter with 449 the value "attachment-update" (see Section 3.3.1). 451 B. The request-URI will include a "managed-id" query parameter 452 with the value matching that of the "MANAGED-ID" parameter 453 for the "ATTACH" property being updated (see Section 3.3.3). 455 C. The body of the request contains the updated data for the 456 attachment. 458 D. The client MUST include a valid Content-Type header field 459 describing the media type of the attachment (as required by 460 HTTP). 462 E. The client SHOULD include a Content-Disposition header field 463 [RFC6266] with a "type" parameter set to "attachment", and a 464 "filename" parameter that indicates the name of the 465 attachment. 467 F. The client MAY include a Prefer header field [RFC7240] with 468 the "return=representation" preference to request that the 469 modified calendar object resource be returned as the body of 470 a successful response to the POST request. 472 2. When the server receives the POST request it does the following: 474 A. Validates that the "managed-id" query parameter is valid for 475 the calendar object resource. 477 B. Updates the content of the attachment resource corresponding 478 to that managed-id with the supplied attachment data. 480 C. For each affected recurrence instance in the calendar object 481 resource targeted by the request, the server updates the 482 "ATTACH" property whose "MANAGED-ID" property parameter value 483 matches the "managed-id" query parameter. The "MANAGED-ID" 484 parameter value is changed to allow other clients to detect 485 the update, and the property value (attachment URI) might 486 also be changed. The "ATTACH" property SHOULD contain a 487 "FMTTYPE" parameter whose value matches the Content-Type 488 header field value from the request - this could differ from 489 the original value if the media type of the updated 490 attachment is different. The "ATTACH" property SHOULD 491 contain a "FILENAME" parameter whose value matches the 492 Content-Disposition header field "filename" parameter value 493 from the request, taking into account the restrictions 494 expressed in Section 4.2. The "ATTACH" property SHOULD 495 include a "SIZE" parameter whose value represents the size in 496 octets of the updated attachment. 498 D. Upon successful update of the attachment resource, and 499 modification of the targeted calendar object resource, the 500 server MUST return an appropriate HTTP success status 501 response, and include a "Cal-Managed-ID" header field 502 containing the new value of the "MANAGED-ID" parameter. The 503 client can use the "Cal-Managed-ID" header field value to 504 correlate the attachment with "ATTACH" properties added to 505 the calendar object resource. If the client included a 506 Prefer header field with the "return=representation" 507 preference in the request, the server SHOULD return the 508 modified calendar object resource as the body of the 509 response. Otherwise, the server can expect that the client 510 will reload the calendar object resource with a subsequent 511 GET request to refresh any local cache. 513 The update operation does not take a "rid" parameter and does not 514 add, or remove, any "ATTACH" property in the targeted calendar object 515 resource. To link an existing attachment to a new instance, the 516 client simply does a PUT on the calendar object resource, adding an 517 "ATTACH" property which duplicates the existing one (see 518 Section 3.7). 520 In the following example, the client updates an existing attachment 521 and asks the server (via the Prefer [RFC7240] header field) to return 522 the updated version of that event in the response. 524 >> Request << 526 POST /events/64.ics?action=attachment-update&managed-id=97S HTTP/1.1 527 Host: cal.example.com 528 Content-Type: text/html; charset="utf-8" 529 Content-Disposition:attachment;filename=agenda.html 530 Content-Length: xxxx 531 Prefer: return=representation 533 534 535

Agenda

536

Discuss attachment draft

537 538 539 >> Response << 541 HTTP/1.1 200 OK 542 Content-Type: text/calendar; charset="utf-8" 543 Content-Length: yyyz 544 Content-Location: https://cal.example.com/events/64.ics 545 Cal-Managed-ID: 98S 546 ETag: "123456789-000-222" 548 BEGIN:VCALENDAR 549 VERSION:2.0 550 PRODID:-//Example Corp.//CalDAV Server//EN 551 BEGIN:VEVENT 552 UID:20010712T182145Z-123401@example.com 553 DTSTAMP:20120201T203412Z 554 DTSTART:20120714T170000Z 555 DTEND:20120715T040000Z 556 SUMMARY:One-off meeting 557 ATTACH;MANAGED-ID=98S;FMTTYPE=text/html;SIZE=xxxy; 558 FILENAME=agenda.html:https://cal.example.com/attach/64/34X22R 559 END:VEVENT 560 END:VCALENDAR 562 3.6. Removing Attachments via POST 564 To remove an existing attachment from a calendar object, the 565 following occurs: 567 1. The client issues a POST request targeted at the calendar object 568 resource. 570 A. The request-URI will include an "action" query parameter with 571 the value "attachment-remove" (see Section 3.3.1). 573 B. If all recurrence instances are having an attachment removed, 574 the "rid" query parameter is not present in the request-URI. 575 If one or more specific recurrence instances are targeted, 576 then the request-URI will include a "rid" query parameter 577 containing the list of instances (see Section 3.3.2). 579 C. The request-URI will include a "managed-id" query parameter 580 with the value matching that of the "MANAGED-ID" property 581 parameter for the "ATTACH" property being removed (see 582 Section 3.3.3). 584 D. The body of the request will be empty. 586 E. The client MAY include a Prefer header field [RFC7240] with 587 the "return=representation" preference to request that the 588 modified calendar object resource be returned as the body of 589 a successful response to the POST request. 591 2. When the server receives the POST request it does the following: 593 A. Validates that any recurrence instances referred to via the 594 "rid" query parameter are valid for the calendar object 595 resource being targeted. 597 B. Validates that the "managed-id" query parameter is valid for 598 the calendar object resource and specific instances being 599 targeted. 601 C. For each affected recurrence instance in the calendar object 602 resource targeted by the request, the server removes the 603 matching "ATTACH" property. Note that if a specified 604 recurrence instance does not have a matching component in the 605 calendar object resource, then the server MUST modify the 606 calendar object resource to include an overridden component 607 with the appropriate "RECURRENCE-ID" property, and the 608 matching "ATTACH" property removed. This later case is 609 actually valid only if the master component does include the 610 referenced "ATTACH" property. 612 D. If the attachment resource is no longer referenced by any 613 instance of the calendar object resource, the server can 614 delete the attachment resource to free up storage space. 616 E. Upon successful removal of the attachment resource and 617 modification of the targeted calendar object resource, the 618 server MUST return an appropriate HTTP success status 619 response. If the client included a Prefer header field with 620 the "return=representation" preference in the request, the 621 server SHOULD return the modified calendar object resource as 622 the body of the response. Otherwise, the server can expect 623 that the client will reload the calendar object resource with 624 a subsequent GET request to refresh any local cache. 626 In the following example, the client deletes an existing attachment 627 by passing its managed-id in the request. The Prefer [RFC7240] 628 header field is not set in the request so the calendar object 629 resource data is not returned in the response. 631 >> Request << 633 POST /events/64.ics?action=attachment-remove&managed-id=98S HTTP/1.1 634 Host: cal.example.com 635 Content-Length: 0 637 >> Response << 639 HTTP/1.1 204 No Content 640 Content-Length: 0 642 3.7. Adding Existing Managed Attachments via PUT 644 Clients can make use of existing managed attachments by adding the 645 corresponding "ATTACH" property to calendar object resources (subject 646 to the restrictions described in Section 3.12.2) 648 If a managed attachment is used in more than calendar resource, 649 servers SHOULD NOT change either the "MANAGED-ID" parameter value or 650 the "ATTACH" property value for these attachments - this ensures that 651 clients do not have to download the attachment data again if they 652 already have it cached. Additionally, servers SHOULD validate "SIZE" 653 parameter values and replace incorrect values with the actual sizes 654 of existing attachments. 656 These PUT requests are subject to the preconditions listed in 657 Section 3.11. 659 3.8. Updating Attachments via PUT 661 Servers MUST NOT allow clients to update attachment data directly via 662 a PUT on the attachment URI (or via any other HTTP method that 663 modifies content). Instead, attachments can only be updated via use 664 of POST requests on the calendar data. 666 3.9. Removing Attachments via PUT 668 Clients can remove attachments by simply re-writing the calendar 669 object resource data to remove the appropriate "ATTACH" properties. 670 Servers MUST NOT allow clients to delete attachments directly via a 671 DELETE request on the attachment URI. 673 3.10. Retrieving Attachments 675 Clients retrieve attachments by issuing an HTTP GET request using the 676 value of the corresponding "ATTACH" property as the request-URI, 677 taking into account the substitution mechanism associated with the 678 "CALDAV:managed-attachments-server-URL" property (see Section 6.1). 680 3.11. Error Handling 682 This specification creates additional preconditions for the POST 683 method. 685 The new preconditions are: 687 (CALDAV:max-attachment-size): The attachment submitted in the POST 688 request MUST have an octet size less than or equal to the value of 689 the CALDAV:max-attachment-size property value (Section 6.2) on the 690 calendar collection of the target calendar resource; 692 (CALDAV:max-attachments-per-resource): The addition of the 693 attachment submitted in the POST request MUST result in the target 694 calendar resource having a number of managed attachments less than 695 or equal to the value of the CALDAV:max-attachments-per-resource 696 property value (Section 6.3) on the calendar collection of the 697 target calendar resource; 699 (CALDAV:valid-action): The action query parameter in the POST 700 request MUST contain one of "attachment-add", "attachment-update", 701 or "attachment-remove". 703 (CALDAV:valid-rid): The rid query parameter in the POST request 704 MUST NOT be present for an attachment-update action, and MUST 705 contain the value "M" and/or values corresponding to "RECURRENCE- 706 ID" property values in the iCalendar data targeted by the request. 708 (CALDAV:valid-managed-id): The managed-id query parameter in the 709 POST request MUST NOT be present for an attachment-add action, and 710 MUST contain a value corresponding to a "MANAGED-ID" property 711 parameter value in the iCalendar data targeted by the request. 713 A POST request to add, modify, or delete a managed attachment results 714 in an implicit modification of the targeted calendar resource 715 (equivalent of a PUT). As a consequence, clients should also be 716 prepared to handle preconditions associated with this implicit PUT. 717 This includes (but is not limited to): 719 (CALDAV:max-resource-size) (from Section 5.3.2.1 of [RFC4791]) 720 (DAV:quota-not-exceeded) (from Section 6 of [RFC4331]) 722 (DAV:sufficient-disk-space) (from Section 6 of [RFC4331]) 724 A PUT request to add or modify and existing calendar object resource 725 can make reference to an existing managed attachment. The following 726 new preconditions is defined: 728 (CALDAV:valid-managed-id-parameter): a "MANAGED-ID" property 729 parameter value in the iCalendar data in the PUT request is not 730 valid (e.g., does not match any existing managed attachment). 732 If a precondition for a request is not satisfied: 734 1. The response status of the request MUST either be 403 735 (Forbidden), if the request should not be repeated because it 736 will always fail, or 409 (Conflict), if it is expected that the 737 user might be able to resolve the conflict and resubmit the 738 request. 740 2. The appropriate XML element MUST be returned as the child of a 741 top-level DAV:error element in the response body. 743 3.12. Additional Considerations 745 3.12.1. Quotas 747 The WebDAV Quotas [RFC4331] specification defines two live WebDAV 748 properties (DAV:quota-available-bytes and DAV:quota-used-bytes) to 749 communicate storage quota information to clients. Server 750 implementations MAY choose to include managed attachments sizes when 751 calculating the amount of storage used by a particular resource. 753 3.12.2. Access Control 755 Access to the managed attachments store in a calendar object resource 756 SHOULD be restricted to only those calendar users who have access to 757 that calendar object either directly, or indirectly (via being an 758 attendee who would receive a scheduling message). 760 When accessing a managed attachment, clients SHOULD be prepared to 761 authenticate with the server storing the attachment resource. The 762 credentials required to access the managed attachment store could be 763 different from the ones used to access the CalDAV server. 765 This specification only allows organizers of scheduled events to add 766 managed attachments. Servers MUST prevent attendees of scheduled 767 events from adding, updating or removing managed attachments. In 768 addition, the server MUST prevent a calendar user from re-using a 769 managed attachment (based on its managed-id value), unless that user 770 is the one who originally created the managed attachment. 772 3.12.3. Redirects 774 For POST requests that add or update attachment data, the server MAY 775 issue a 307 (Temporary Redirect) [RFC7231] or 308 (Permanent 776 Redirect) [RFC7538] response to require the client to re-issue the 777 POST request using a different request-URI. As a result, clients 778 SHOULD use the "100-continue" expectation defined in Section 5.1.1 of 779 [RFC7231]. Using this mechanism ensures that, if a redirect does 780 occur, the client does not needlessly send the attachment data. 782 3.12.4. Processing Time 784 Clients can expect servers to take a while to respond to POST 785 requests that include large attachment bodies. Servers SHOULD use 786 the "102 (Processing)" interim response defined in Section 10.1 of 787 [RFC2518] to keep the client connection alive if the POST request 788 will take significant time to complete. 790 3.12.5. Automatic Clean-Up by Servers 792 Servers MAY automatically remove attachment data, for example to 793 regain the storage taken by unused attachments, or as the result of a 794 virus scanning. When doing so they SHOULD NOT modify calendar data 795 referencing those attachments. Instead they SHOULD respond with "410 796 (Gone)" to any request on the removed attachment URI. 798 3.12.6. Sending Scheduling Messages with Attachments 800 When a managed attachment is added, updated or removed from a 801 calendar object resource, the server MUST ensure that a scheduling 802 message is sent to update any attendees with the changes, as per 803 [RFC6638]. 805 3.12.7. Migrating Calendar Data 807 When exporting calendar data from a CalDAV server supporting managed 808 attachments, clients SHOULD remove all "MANAGED-ID" property 809 parameters from "ATTACH" properties in the calendar data. Similarly 810 when importing calendar data from another source, clients SHOULD 811 remove any "MANAGED-ID" property parameters on "ATTACH" properties 812 (failure to do so will likely result in the server removing those 813 properties automatically). 815 4. Modifications to iCalendar Syntax 817 4.1. SIZE Property Parameter 819 Parameter Name: SIZE 821 Purpose: To specify the size of an attachment. 823 Format Definition: This property parameter is defined by the 824 following notation: 826 sizeparam = "SIZE" "=" paramtext 827 ; positive integers 829 Description: This property parameter MAY be specified on "ATTACH" 830 properties. It indicates the size in octets of the corresponding 831 attachment data. Since iCalendar integer values are restricted to 832 a maximum value of 2147483647, the current parameter is defined as 833 text to allow an extended range to be used. 835 Example: 837 ATTACH;SIZE=1234:https://attachments.example.com/abcd.txt 839 4.2. FILENAME Property Parameter 841 Parameter Name: FILENAME 843 Purpose: To specify the file name of a managed attachment. 845 Format Definition: This property parameter is defined by the 846 following notation: 848 filenameparam = "FILENAME" "=" paramtext 850 Description: This property parameter MAY be specified on "ATTACH" 851 properties corresponding to managed attachments. Its value 852 provides information on how to construct a filename for storing 853 the attachment data. This parameter is very similar in nature to 854 the Content-Disposition HTTP header field "filename" parameter and 855 exposes the same security risks. As a consequence, clients MUST 856 follow the guidelines expressed in Section 4.3 of [RFC6266] when 857 consuming this parameter value. Similarly, servers MUST follow 858 those same guidelines before storing a value. 860 Example: 862 ATTACH;FILENAME=agenda.html:https://attachments.example.c 863 om/rt452S 865 4.3. MANAGED-ID Property Parameter 867 Parameter Name: MANAGED-ID 869 Purpose: To uniquely identify a managed attachment. 871 Format Definition: This property parameter is defined by the 872 following notation: 874 managedidparam = "MANAGED-ID" "=" paramtext 876 Description: This property parameter MUST be specified on "ATTACH" 877 properties corresponding to managed attachments. Its value is 878 generated by the server and uniquely identifies a managed 879 attachment within the scope of the CalDAV server. This property 880 parameter MUST NOT be present in the case of non-managed 881 attachments. 883 Example: 885 ATTACH;MANAGED-ID=aUNhbGVuZGFy:https://attachments.example.c 886 om/abcd.txt 888 5. Additional Message Header Fields 890 5.1. Cal-Managed-ID Response Header Field 892 The Cal-Managed-ID response header field provides the value of the 893 MANAGED-ID parameter corresponding to a newly added ATTACH property. 895 ABNF: 897 Cal-Managed-ID = "Cal-Managed-ID" ":" paramtext 898 ; "paramtext" is defined in Section 3.1 of [RFC5545] 900 Example: 902 Cal-Managed-ID:aUNhbGVuZGFy 904 The Cal-Managed-ID header field MUST only be sent by an origin server 905 in response to a successful POST request with an action set to 906 attachment-add or attachment-update. It MUST only appear once in a 907 response and MUST NOT appear in trailers. 909 The Cal-Managed-ID header field is end to end and MUST be forwarded 910 by intermediaries. Intermediaries MUST NOT insert, delete, or modify 911 a Cal-Managed-ID header field. 913 6. Additional WebDAV Properties 915 6.1. CALDAV:managed-attachments-server-URL property 917 Name: managed-attachments-server-URL 919 Namespace: urn:ietf:params:xml:ns:caldav 921 Purpose: Specifies the server base URI to use when retrieving 922 managed attachments. 924 Protected: This property MUST be protected as only the server can 925 update the value. 927 COPY/MOVE behavior: This property is only defined on a calendar home 928 collection which cannot be moved or copied. 930 allprop behavior: SHOULD NOT be returned by a PROPFIND DAV:allprop 931 request. 933 Description: This property MAY be defined on a calendar home 934 collection. If present, it contains zero or one DAV:href XML 935 elements. 937 When one DAV:href element is present, its value MUST be an 938 absolute HTTP URI containing only the scheme (i.e. "https") and 939 authority (i.e. host and port) parts . Whenever a managed 940 attachment is to be retrieved via an HTTP GET, the client MUST 941 construct the actual URL of the attachment by substituting the 942 scheme and authority parts of the attachment URI (as stored in the 943 iCalendar "ATTACH" property) with the present WebDAV property 944 value. 946 When no DAV:href element is present, the client MUST substitute 947 the scheme and authority parts of the attachment URI with the 948 scheme and authority part of the calendar home collection absolute 949 URI. 951 In the absence of this property, the client can consider the 952 attachment URI as its actual URL. 954 Definition: 956 957 Example: 959 961 https://attachstore.example.com 962 964 6.2. CALDAV:max-attachment-size property 966 Name: max-attachment-size 968 Namespace: urn:ietf:params:xml:ns:caldav 970 Purpose: Provides a numeric value indicating the maximum attachment 971 size, in octets, that the server is willing to accept when a 972 managed attachment is stored on the server. 974 Protected: MUST be protected as it indicates limits provided by the 975 server. 977 COPY/MOVE behavior: This property value MUST be preserved in COPY 978 and MOVE operations. 980 allprop behavior: SHOULD NOT be returned by a PROPFIND DAV:allprop 981 request. 983 Description: The CALDAV:max-attachment-size property is used to 984 specify a numeric value that represents the maximum attachment 985 size, in octets, that the server is willing to accept when a 986 managed attachment is stored on the server. The property is 987 defined on the parent collection of the calendar object resource 988 to which the attachment is associated. Any attempt to store a 989 managed attachment exceeding this size MUST result in an error, 990 with the CALDAV:max-attachment-size precondition (Section 3.11) 991 being violated. In the absence of this property, the client can 992 assume that the server will allow storing an attachment of any 993 reasonable size. 995 Definition: 997 998 1000 Example: 1002 102400000 1005 6.3. CALDAV:max-attachments-per-resource property 1007 Name: max-attachments-per-resource 1009 Namespace: urn:ietf:params:xml:ns:caldav 1011 Purpose: Provides a numeric value indicating the maximum number of 1012 managed attachments across all instances of a calendar object 1013 resource stored in a calendar collection. 1015 Protected: MUST be protected as it indicates limits provided by the 1016 server. 1018 COPY/MOVE behavior: This property value MUST be preserved in COPY 1019 and MOVE operations. 1021 allprop behavior: SHOULD NOT be returned by a PROPFIND DAV:allprop 1022 request. 1024 Description: The CALDAV:max-attachments-per-resource property is 1025 used to specify a numeric value that represents the maximum number 1026 of managed attachments across all instances of a calendar object 1027 resource stored in a calendar collection. Non-managed attachments 1028 are not counted toward that limit. The property is defined on the 1029 parent collection of the calendar object resource to which the 1030 attachment is associated. Any attempt to add a managed attachment 1031 that would cause the calendar resource to exceed this limit MUST 1032 result in an error, with the CALDAV:max-attachments-per-resource 1033 precondition (Section 3.11) being violated. In the absence of 1034 this property, the client can assume that the server can handle 1035 any number of managed attachments per calendar resource. 1037 Definition: 1039 1040 1042 Example: 1044 12 1048 7. Implementation Status 1050 < RFC Editor: before publication please remove this section, the 1051 reference to [RFC7942], and any resulting "URIs" references sub- 1052 section. > 1053 This section records the status of known implementations of the 1054 protocol defined by this specification at the time of posting of this 1055 Internet-Draft, and is based on a proposal described in [RFC7942]. 1056 The description of implementations in this section is intended to 1057 assist the IETF in its decision processes in progressing drafts to 1058 RFCs. Please note that the listing of any individual implementation 1059 here does not imply endorsement by the IETF. Furthermore, no effort 1060 has been spent to verify the information presented here that was 1061 supplied by IETF contributors. This is not intended as, and must not 1062 be construed to be, a catalog of available implementations or their 1063 features. Readers are advised to note that other implementations may 1064 exist. 1066 According to [RFC7942], "this will allow reviewers and working groups 1067 to assign due consideration to documents that have the benefit of 1068 running code, which may serve as evidence of valuable experimentation 1069 and feedback that have made the implemented protocols more mature. 1070 It is up to the individual working groups to use this information as 1071 they see fit". 1073 7.1. Calendar and Contacts Server 1075 The open source Calendar and Contacts Server [2] project is a 1076 standards-compliant server implementing the CalDAV protocol. This 1077 production level implementation supports all of the requirements 1078 described in this document and successfully interoperates with the 1079 Apple Calendar, BusyCal, 2Do, and CalDAVTester client implementations 1080 described below. This implementation is freely distributable under 1081 the terms of the Apache License, Version 2.0 [3]. 1083 7.2. Cyrus Server 1085 The open source Cyrus Server [4] project is a highly scalable 1086 enterprise mail system which also supports calendaring. This 1087 production level CalDAV implementation supports all of the 1088 requirements described in this document and successfully 1089 interoperates with the Apple Calendar and CalDAVTester client 1090 implementations described below. This implementation is freely 1091 distributable under a BSD style license from Computing Services at 1092 Carnegie Mellon University [5]. 1094 7.3. Oracle Communications Calendar Server 1096 The Oracle Communications Calendar Server [6] project is a standards- 1097 compliant, scalable, enterprise-ready calendaring solution. This 1098 production level CalDAV implementation supports all of the 1099 requirements described in this document and successfully 1100 interoperates with the Apple Calendar and CalDAVTester client 1101 implementations described below. This implementation is proprietary 1102 and available for a free trial and/or purchase from the vendor. 1104 7.4. Apple Calendar 1106 The widely used Apple Calendar [7] client is a standards-compliant 1107 client implementing the CalDAV protocol. This production level 1108 implementation supports all the requirements described in this 1109 document and successfully interoperates with the 1110 Calendar and Contacts Server, Cyrus Server, and 1111 Oracle Communications Calendar Server implementations described 1112 above. This client implementation is proprietary and is distributed 1113 as part of Apple's desktop operating systems. 1115 7.5. BusyCal 1117 BusyCal [8] is a standards-compliant calendar client for MacOS 1118 implementing the CalDAV protocol. This implementation supports all 1119 of the requirements described in this document and successfully 1120 interoperates with the Calendar and Contacts Server and Cyrus Server 1121 implementations described above. This implementation is proprietary 1122 and available for a free trial and/or purchase from the vendor. 1124 7.6. CalDAVTester 1126 CalDAVTester [9] is an open source test and performance application 1127 designed to work with CalDAV servers and tests various aspects of 1128 their protocol handling as well as performance. This widely used 1129 implementation supports all of the requirements described in this 1130 document and successfully interoperates with the server 1131 implementations described above. This implementation is freely 1132 distributable under the terms of the Apache License, Version 2.0 1133 [10]. 1135 7.7. 2Do 1137 2Do [11] is a standards-complient calendar client for iOS which uses 1138 the CalDAV standard for communication. This implementation supports 1139 all of the requirements described in this document and successfully 1140 interoperates with the Calendar and Contacts Server implementation 1141 described above. This implementation is proprietary and available 1142 for purchase from the vendor. 1144 8. Security Considerations 1146 The security considerations in [RFC4791] and [RFC4918] apply to this 1147 extension. Additionally, servers need to be aware that a client 1148 could attack underlying storage by POSTing extremely large 1149 attachments and could attack processing time by uploading a recurring 1150 event with a large number of overrides and then repeatedly adding, 1151 updating, and deleting attachments. 1153 Malicious content could be introduced into the calendar server by way 1154 of a managed attachment, and propagated to many end users via 1155 scheduling. Servers SHOULD check managed attachments for malicious 1156 or inappropriate content. Upon detecting of such content, servers 1157 SHOULD remove the attachment, following the rules described in 1158 Section 3.12.5. 1160 9. IANA Considerations 1162 9.1. Parameter Registrations 1164 This specification defines the following new iCalendar property 1165 parameters to be added to the registry defined in Section 8.2.3 of 1166 [RFC5545]: 1168 +--------------------+---------+----------------------+ 1169 | Property Parameter | Status | Reference | 1170 +--------------------+---------+----------------------+ 1171 | SIZE | Current | RFCXXXX, Section 4.1 | 1172 | FILENAME | Current | RFCXXXX, Section 4.2 | 1173 | MANAGED-ID | Current | RFCXXXX, Section 4.3 | 1174 +--------------------+---------+----------------------+ 1176 9.2. Message Header Field Registrations 1178 The message header fields below should be added to the Permanent 1179 Message Header Field Registry (see [RFC3864]). 1181 9.2.1. Cal-Managed-ID 1183 Header field name: Cal-Managed-ID 1185 Applicable protocol: http 1187 Status: standard 1189 Author/Change controller: IETF 1191 Specification document(s): this specification (Section 5.1) 1193 Related information: none 1195 10. Acknowledgments 1197 This specification came about via discussions at the Calendaring and 1198 Scheduling Consortium. Thanks in particular to Mike Douglass and 1199 Eric York. 1201 11. References 1203 11.1. Normative References 1205 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1206 Requirement Levels", BCP 14, RFC 2119, 1207 DOI 10.17487/RFC2119, March 1997, 1208 . 1210 [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D. 1211 Jensen, "HTTP Extensions for Distributed Authoring -- 1212 WEBDAV", RFC 2518, DOI 10.17487/RFC2518, February 1999, 1213 . 1215 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 1216 Procedures for Message Header Fields", BCP 90, RFC 3864, 1217 DOI 10.17487/RFC3864, September 2004, 1218 . 1220 [RFC4331] Korver, B. and L. Dusseault, "Quota and Size Properties 1221 for Distributed Authoring and Versioning (DAV) 1222 Collections", RFC 4331, DOI 10.17487/RFC4331, February 1223 2006, . 1225 [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, 1226 "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, 1227 DOI 10.17487/RFC4791, March 2007, 1228 . 1230 [RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed 1231 Authoring and Versioning (WebDAV)", RFC 4918, 1232 DOI 10.17487/RFC4918, June 2007, 1233 . 1235 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1236 Specifications: ABNF", STD 68, RFC 5234, 1237 DOI 10.17487/RFC5234, January 2008, 1238 . 1240 [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and 1241 Scheduling Core Object Specification (iCalendar)", 1242 RFC 5545, DOI 10.17487/RFC5545, September 2009, 1243 . 1245 [RFC6266] Reschke, J., "Use of the Content-Disposition Header Field 1246 in the Hypertext Transfer Protocol (HTTP)", RFC 6266, 1247 DOI 10.17487/RFC6266, June 2011, 1248 . 1250 [RFC6638] Daboo, C. and B. Desruisseaux, "Scheduling Extensions to 1251 CalDAV", RFC 6638, DOI 10.17487/RFC6638, June 2012, 1252 . 1254 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1255 Protocol (HTTP/1.1): Message Syntax and Routing", 1256 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1257 . 1259 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1260 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1261 DOI 10.17487/RFC7231, June 2014, 1262 . 1264 [RFC7240] Snell, J., "Prefer Header for HTTP", RFC 7240, 1265 DOI 10.17487/RFC7240, June 2014, 1266 . 1268 [RFC7538] Reschke, J., "The Hypertext Transfer Protocol Status Code 1269 308 (Permanent Redirect)", RFC 7538, DOI 10.17487/RFC7538, 1270 April 2015, . 1272 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1273 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1274 May 2017, . 1276 11.2. Informative References 1278 [RFC5023] Gregorio, J., Ed. and B. de hOra, Ed., "The Atom 1279 Publishing Protocol", RFC 5023, DOI 10.17487/RFC5023, 1280 October 2007, . 1282 [RFC5546] Daboo, C., Ed., "iCalendar Transport-Independent 1283 Interoperability Protocol (iTIP)", RFC 5546, 1284 DOI 10.17487/RFC5546, December 2009, 1285 . 1287 [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, 1288 RFC 7320, DOI 10.17487/RFC7320, July 2014, 1289 . 1291 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 1292 Code: The Implementation Status Section", BCP 205, 1293 RFC 7942, DOI 10.17487/RFC7942, July 2016, 1294 . 1296 [RFC8144] Murchison, K., "Use of the Prefer Header Field in Web 1297 Distributed Authoring and Versioning (WebDAV)", RFC 8144, 1298 DOI 10.17487/RFC8144, April 2017, 1299 . 1301 11.3. URIs 1303 [1] https://tools.ietf.org/html/bcp14 1305 [2] http://calendarserver.org/ 1307 [3] http://www.apache.org/licenses/LICENSE-2.0.html 1309 [4] http://www.cyrusimap.org/ 1311 [5] http://www.cmu.edu/computing/ 1313 [6] http://www.cyrusimap.org/ 1315 [7] http://www.apple.com/macos/ 1317 [8] http://www.busymac.com/busycal/ 1319 [9] http://calendarserver.org/wiki/CalDAVTester 1321 [10] http://www.apache.org/licenses/LICENSE-2.0.html 1323 [11] http://www.2doapp.com/ 1325 Appendix A. Change History (To be removed by RFC Editor before 1326 publication) 1328 Changes in calext-04: 1330 1. Added text explaining why this document is being published as 1331 Informational. 1333 2. Further specified Cal-Managed-ID per Section 8.3.1 of RFC 7231. 1335 3. Specified that the MANAGED-ID parameter value is unique within 1336 the scope of the server. 1338 4. Added more text regarding preconditions. 1340 5. Added text about specific DoS attack vectors. 1342 6. Editorial changes from Gren Elliot and Phillip Kewisch. 1344 7. Editorial changes from Adam Roach. 1346 8. Editorial changes from Alexey Melnikov. 1348 9. Added reference to RFC4918. 1350 10. Minor editorial changes. 1352 Changes in calext-03: 1354 1. Changed to Informational based on feedback regarding non-standard 1355 method of updating an existing resource. 1357 2. Added references to sub-sections in Overview. 1359 3. Made support for Prefer header field a SHOULD for servers. 1361 4. Expanded recurring event examples to use conditional requests and 1362 to include the Expect header field. 1364 5. Minor editorial changes. 1366 Changes in calext-02: 1368 1. Moved "Error Handling" into its own sub-section. 1370 2. Split "Other Client Considerations" into "Processing Time" and 1371 "Migrating Calendar Data". 1373 Changes in calext-01: 1375 1. Changed all instances of "header" to "header field". 1377 2. Reworked wording of Prefer header field handling. 1379 3. Switched to recommending 102 (Processing) interim response to 1380 keep the client connection alive. 1382 4. Fixed description of Cal-Managed-ID response header field to 1383 state that it is also required in responses to successful 1384 attachment-update. 1386 5. Minor editorial changes. 1388 Changes in calext-00: 1390 1. Added Murchison as editor. 1392 2. Updated HTTP references to RFC7230 and RFC7231. 1394 3. Updated Prefer header field references to RFC7240. 1396 4. Added Implementation Status section. 1398 5. Minor editorial changes. 1400 Changes in daboo-03: 1402 1. Fixed some examples. 1404 2. Fixed return-representation -> return=representation. 1406 3. Added statement that servers must not allow clients to DELETE 1407 attachments directly. 1409 4. Added new preconditions for valid managed-id values. 1411 5. Filled out Access Control section. 1413 6. Allow servers to not support per-instance attachments and 1414 advertise that fact to clients. 1416 Changes in daboo-02: 1418 1. MANAGED-ID changes on PUT. 1420 2. MTAG has been removed. 1422 3. Error pre-conditions added. 1424 4. Interaction with WebDAV QUOTA discussed. 1426 5. max-attachment-* limits added. 1428 6. Updated references. 1430 7. Removed MUST for specific 2xx codes in favor of generic success 1431 code. 1433 Changes in daboo-01: 1435 1. Tweaked OPTIONS capability wording. 1437 2. Added section on clients expecting 100-Continue for delayed 1438 response. 1440 3. Added text for clean-up and use of HTTP 410 on orphans. 1442 4. Added text on removing "MANAGED-ID" when exporting/importing 1443 calendar data. 1445 5. Added protocol examples. 1447 6. Added MTAG property parameter on ATTACH property 1449 7. Added FILENAME property parameter on ATTACH property 1451 8. "id" query parameter is now "managed-id". 1453 9. Use of Cal-Managed-ID header instead of Location header in 1454 responses. 1456 10. rid query param MUST contain RECURRENCE-ID without any 1457 conversion to UTC (case of floating events). 1459 11. Introduced CALDAV:managed-attachments-server-URL property 1461 12. Made support for Prefer header a MUST for servers. 1463 Appendix B. Example Involving Recurring Events 1465 In the following example, the organizer of a recurring meeting makes 1466 an unsuccessful attempt to add an agenda (HTML attachment) to the 1467 corresponding calendar resource with a conditional request. Note 1468 that the client includes both the Expect and Prefer header fields in 1469 the request, thereby preventing itself from needlessly sending the 1470 attachment data, and requesting that the current resource be returned 1471 in the failure response (see Section 3.2 of [RFC8144]). 1473 >> Request << 1475 POST /events/65.ics?action=attachment-add HTTP/1.1 1476 Host: cal.example.com 1477 Content-Type: text/html; charset="utf-8" 1478 Content-Disposition: attachment;filename=agenda.html 1479 Content-Length: xxxx 1480 If-Match: "abcdefg-000" 1481 Expect: 100-continue 1482 Prefer: return=representation 1483 >> Final Response << 1485 HTTP/1.1 412 Precondition Failed 1486 Content-Type: text/calendar; charset="utf-8" 1487 Content-Length: yyyy 1488 Content-Location: https://cal.example.com/events/65.ics 1489 ETag: "123456789-000-000" 1491 BEGIN:VCALENDAR 1492 VERSION:2.0 1493 PRODID:-//Example Corp.//CalDAV Server//EN 1494 BEGIN:VTIMEZONE 1495 LAST-MODIFIED:20040110T032845Z 1496 TZID:America/Montreal 1497 BEGIN:DAYLIGHT 1498 DTSTART:20000404T020000 1499 RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4 1500 TZNAME:EDT 1501 TZOFFSETFROM:-0500 1502 TZOFFSETTO:-0400 1503 END:DAYLIGHT 1504 BEGIN:STANDARD 1505 DTSTART:20001026T020000 1506 RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10 1507 TZNAME:EST 1508 TZOFFSETFROM:-0400 1509 TZOFFSETTO:-0500 1510 END:STANDARD 1511 END:VTIMEZONE 1512 BEGIN:VEVENT 1513 UID:20010712T182145Z-123401@example.com 1514 DTSTAMP:20120201T203412Z 1515 DTSTART;TZID=America/Montreal:20120206T100000 1516 DURATION:PT1H 1517 RRULE:FREQ=WEEKLY 1518 SUMMARY:Planning Meeting 1519 ORGANIZER:mailto:cyrus@example.com 1520 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:cyrus@exampl 1521 e.com 1522 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:arnaudq@exam 1523 ple.com 1524 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=NEEDS-ACTION:mailto:mike@exa 1525 mple.com 1526 END:VEVENT 1527 END:VCALENDAR 1529 The organizer of a recurring meeting successfully adds an agenda 1530 (HTML attachment) to the corresponding calendar resource. Attendees 1531 of the meeting are granted read access to the newly created 1532 attachment resource. Their own copy of the meeting is updated to 1533 include the new ATTACH property pointing to the attachment resource 1534 and they are notified of the change via their scheduling inbox. 1536 >> Request << 1538 POST /events/65.ics?action=attachment-add HTTP/1.1 1539 Host: cal.example.com 1540 Content-Type: text/html; charset="utf-8" 1541 Content-Disposition: attachment;filename=agenda.html 1542 Content-Length: xxxx 1543 If-Match: "123456789-000-000" 1544 Expect: 100-continue 1545 Prefer: return=representation 1547 >> Interim Response << 1549 HTTP/1.1 100 Continue 1551 >> Request Body << 1553 1554 1555

Agenda

1556

As usual

1557 1558 1559 >> Final Response << 1561 HTTP/1.1 201 Created 1562 Content-Type: text/calendar; charset="utf-8" 1563 Content-Length: yyyy 1564 Content-Location: https://cal.example.com/events/65.ics 1565 ETag: "123456789-000-111" 1566 Cal-Managed-ID: 97S 1568 BEGIN:VCALENDAR 1569 VERSION:2.0 1570 PRODID:-//Example Corp.//CalDAV Server//EN 1571 BEGIN:VTIMEZONE 1572 LAST-MODIFIED:20040110T032845Z 1573 TZID:America/Montreal 1574 BEGIN:DAYLIGHT 1575 DTSTART:20000404T020000 1576 RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4 1577 TZNAME:EDT 1578 TZOFFSETFROM:-0500 1579 TZOFFSETTO:-0400 1580 END:DAYLIGHT 1581 BEGIN:STANDARD 1582 DTSTART:20001026T020000 1583 RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10 1584 TZNAME:EST 1585 TZOFFSETFROM:-0400 1586 TZOFFSETTO:-0500 1587 END:STANDARD 1588 END:VTIMEZONE 1589 BEGIN:VEVENT 1590 UID:20010712T182145Z-123401@example.com 1591 DTSTAMP:20120201T203412Z 1592 DTSTART;TZID=America/Montreal:20120206T100000 1593 DURATION:PT1H 1594 RRULE:FREQ=WEEKLY 1595 SUMMARY:Planning Meeting 1596 ORGANIZER:mailto:cyrus@example.com 1597 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:cyrus@exampl 1598 e.com 1599 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:arnaudq@exam 1600 ple.com 1601 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=NEEDS-ACTION:mailto:mike@exa 1602 mple.com 1603 ATTACH;MANAGED-ID=97S;FMTTYPE=text/html;SIZE=xxxx; 1604 FILENAME=agenda.html:https://cal.example.com/attach/65/34X22R 1605 END:VEVENT 1606 END:VCALENDAR 1607 The organizer has a more specific agenda for the 20th of February 1608 meeting. It is added to that particular instance of the meeting by 1609 specifying the rid parameter. Note that an overridden instance is 1610 created with the RECURRENCE-ID property value matching the value of 1611 the "rid" query parameter in the request. Also note that the server 1612 takes significant time to complete the request and notifies the 1613 client accordingly. 1615 >> Request << 1617 POST /events/65.ics?action=attachment-add&rid=20120220T100000 HTTP/1.1 1618 Host: cal.example.com 1619 Content-Type: text/html; charset="utf-8" 1620 Content-Disposition: attachment;filename=agenda0220.html 1621 Content-Length: xxxx 1622 If-Match: "123456789-000-111" 1623 Expect: 100-continue 1624 Prefer: return=representation 1626 >> Interim Response << 1628 HTTP/1.1 100 Continue 1630 >> Request Body << 1632 1633 1634

Agenda

1635

Something different, for a change

1636 1637 1639 >> Interim Response << 1641 HTTP/1.1 102 Processing 1643 >> Final Response << 1645 HTTP/1.1 201 Created 1646 Content-Type: text/calendar; charset="utf-8" 1647 Content-Length: yyyy 1648 Content-Location: https://cal.example.com/events/65.ics 1649 ETag: "123456789-000-222" 1650 Cal-Managed-ID: 33225 1651 BEGIN:VCALENDAR 1652 VERSION:2.0 1653 PRODID:-//Example Corp.//CalDAV Server//EN 1654 BEGIN:VTIMEZONE 1655 LAST-MODIFIED:20040110T032845Z 1656 TZID:America/Montreal 1657 BEGIN:DAYLIGHT 1658 DTSTART:20000404T020000 1659 RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4 1660 TZNAME:EDT 1661 TZOFFSETFROM:-0500 1662 TZOFFSETTO:-0400 1663 END:DAYLIGHT 1664 BEGIN:STANDARD 1665 DTSTART:20001026T020000 1666 RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10 1667 TZNAME:EST 1668 TZOFFSETFROM:-0400 1669 TZOFFSETTO:-0500 1670 END:STANDARD 1671 END:VTIMEZONE 1672 BEGIN:VEVENT 1673 UID:20010712T182145Z-123401@example.com 1674 DTSTAMP:20120201T203412Z 1675 DTSTART;TZID=America/Montreal:20120206T100000 1676 DURATION:PT1H 1677 RRULE:FREQ=WEEKLY 1678 SUMMARY:Planning Meeting 1679 ORGANIZER:mailto:cyrus@example.com 1680 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:cyrus@exampl 1681 e.com 1682 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:arnaudq@exam 1683 ple.com 1684 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=NEEDS-ACTION:mailto:mike@exa 1685 mple.com 1686 ATTACH;MANAGED-ID=97S;FMTTYPE=text/html;SIZE=xxxx; 1687 FILENAME=agenda.html:https://cal.example.com/attach/65/34X22R 1688 END:VEVENT 1689 BEGIN:VEVENT 1690 UID:20010712T182145Z-123401@example.com 1691 RECURRENCE-ID;TZID=America/Montreal:20120220T100000 1692 DTSTAMP:20120201T203412Z 1693 DTSTART;TZID=America/Montreal:20120220T100000 1694 DURATION:PT1H 1695 SUMMARY:Planning Meeting 1696 ORGANIZER:mailto:cyrus@example.com 1697 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:cyrus@example. 1698 com 1700 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:arnaudq@exampl 1701 e.com 1702 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=NEEDS-ACTION:mailto:mike@examp 1703 le.com 1704 ATTACH;MANAGED-ID=33225;FMTTYPE=text/html;SIZE=xxxx; 1705 FILENAME=agenda0220.html:https://cal.example.com/attach/65/FGZ225 1706 END:VEVENT 1707 END:VCALENDAR 1709 Authors' Addresses 1711 Cyrus Daboo 1712 Apple Inc. 1713 1 Infinite Loop 1714 Cupertino, CA 95014 1715 USA 1717 Email: cyrus@daboo.name 1718 URI: http://www.apple.com/ 1720 Arnaud Quillaud 1721 Oracle Corporation 1722 180, Avenue de l'Europe 1723 Saint Ismier cedex 38334 1724 France 1726 Email: arnaud.quillaud@oracle.com 1727 URI: http://www.oracle.com/ 1729 Kenneth Murchison (editor) 1730 FastMail US LLC 1731 1429 Walnut St, Suite 1201 1732 Philadephia, PA 19102 1733 USA 1735 Email: murch@fastmailteam.com 1736 URI: http://www.fastmail.com/