idnits 2.17.1 draft-ietf-calext-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 (July 23, 2017) is 2468 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 1189 -- Looks like a reference, but probably isn't: '2' on line 1191 -- Looks like a reference, but probably isn't: '3' on line 1193 -- Looks like a reference, but probably isn't: '4' on line 1195 -- Looks like a reference, but probably isn't: '5' on line 1197 -- Looks like a reference, but probably isn't: '6' on line 1199 -- Looks like a reference, but probably isn't: '7' on line 1201 -- Looks like a reference, but probably isn't: '8' on line 1203 -- Looks like a reference, but probably isn't: '9' on line 1205 -- Looks like a reference, but probably isn't: '10' on line 1207 ** Obsolete normative reference: RFC 2518 (Obsoleted by RFC 4918) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 11 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: January 24, 2018 Oracle 6 K. Murchison, Ed. 7 FastMail 8 July 23, 2017 10 CalDAV Managed Attachments 11 draft-ietf-calext-caldav-attachments-03 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 non-standard method of updating an 22 existing resource via 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 http://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 January 24, 2018. 41 Copyright Notice 43 Copyright (c) 2017 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 (http://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 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 60 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 3 61 3.1. Requirements . . . . . . . . . . . . . . . . . . . . . . 4 62 3.2. Discovering Support for Managed Attachments . . . . . . . 4 63 3.3. POST Request for Managing Attachments . . . . . . . . . . 5 64 3.4. Adding attachments . . . . . . . . . . . . . . . . . . . 6 65 3.5. Updating Attachments . . . . . . . . . . . . . . . . . . 9 66 3.6. Removing Attachments via POST . . . . . . . . . . . . . . 12 67 3.7. Adding Existing Managed Attachments via PUT . . . . . . . 14 68 3.8. Updating Attachments via PUT . . . . . . . . . . . . . . 14 69 3.9. Removing Attachments via PUT . . . . . . . . . . . . . . 14 70 3.10. Retrieving Attachments . . . . . . . . . . . . . . . . . 14 71 3.11. Error Handling . . . . . . . . . . . . . . . . . . . . . 15 72 3.12. Additional Considerations . . . . . . . . . . . . . . . . 16 73 4. Modifications to iCalendar Syntax . . . . . . . . . . . . . . 17 74 4.1. SIZE Property Parameter . . . . . . . . . . . . . . . . . 17 75 4.2. FILENAME Property Parameter . . . . . . . . . . . . . . . 18 76 4.3. MANAGED-ID Property Parameter . . . . . . . . . . . . . . 18 77 5. Additional Message Header Fields . . . . . . . . . . . . . . 19 78 5.1. Cal-Managed-ID Response Header Field . . . . . . . . . . 19 79 6. Additional WebDAV Properties . . . . . . . . . . . . . . . . 19 80 6.1. CALDAV:managed-attachments-server-URL property . . . . . 19 81 6.2. CALDAV:max-attachment-size property . . . . . . . . . . . 20 82 6.3. CALDAV:max-attachments-per-resource property . . . . . . 21 83 7. Implementation Status . . . . . . . . . . . . . . . . . . . . 22 84 8. Security Considerations . . . . . . . . . . . . . . . . . . . 24 85 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 86 9.1. Parameter Registrations . . . . . . . . . . . . . . . . . 24 87 9.2. Message Header Field Registrations . . . . . . . . . . . 24 88 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 25 89 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 25 90 11.1. Normative References . . . . . . . . . . . . . . . . . . 25 91 11.2. Informative References . . . . . . . . . . . . . . . . . 26 92 11.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 27 93 Appendix A. Change History (To be removed by RFC Editor before 94 publication) . . . . . . . . . . . . . . . . . . . . 27 95 Appendix B. Example Involving Recurring Events . . . . . . . . . 29 96 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 36 98 1. Introduction 100 The iCalendar [RFC5545] data format is used to represent calendar 101 data and is used with iTIP [RFC5546] to handle scheduling operations 102 between calendar users. 104 [RFC4791] defines the CalDAV Calendar Access protocol, based on HTTP 105 [RFC7230], for accessing calendar data stored on a server. 107 Calendar users often want to include attachments with their calendar 108 data events or tasks (for example a copy of a presentation, or the 109 meeting agenda). iCalendar provides an "ATTACH" property whose value 110 is either the inline Base64 encoded attachment data, or a URL 111 specifying the location of the attachment data. 113 Use of inline attachment data is not ideal with CalDAV because the 114 data would need to be uploaded to the server each time a change to 115 the calendar data is done - even minor changes such as a change to 116 the summary. Whilst a client could choose to use a URL value 117 instead, the problem then becomes where and how the client discovers 118 an appropriate URL to use and how it ensures that only those 119 attendees listed in the event or task are able to access it. 121 This specification solves this problem by having the client send the 122 attachment to the server, separately from the iCalendar data, and the 123 server takes care of adding appropriate "ATTACH" properties in the 124 iCalendar data as well as managing access privileges . The server can 125 also provide additional information to the client about each 126 attachment in the iCalendar data, such as the size and an identifier. 128 2. Conventions Used in This Document 130 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 131 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 132 "OPTIONAL" in this document are to be interpreted as described in 133 [RFC2119]. 135 The notation used in this memo is the ABNF notation of [RFC5234] as 136 used by iCalendar [RFC5545]. Any syntax elements shown below that 137 are not explicitly defined in this specification come from iCalendar 138 [RFC5545]. 140 3. Overview 142 There are four main operations a client needs to do with attachments 143 for calendar data: add, update, remove, and retrieve. The first 144 three operations are carried out by the client issuing an HTTP POST 145 request on the calendar object resource to which the attachment is 146 associated and specifying the appropriate "action" query parameter 147 (see Section 3.3). In the case of the remove operation, the client 148 can alternatively directly update the calendar object resource and 149 remove the relevant "ATTACH" properties (see Section 3.9). The 150 retrieve operation is accomplished by simply issuing an HTTP GET 151 request targeting the attachment URI specified by the calendar 152 resource's "ATTACH" property (see Section 3.10). 154 iCalendar data stored in a CalDAV calendar object resource can 155 contain multiple components when recurrences are involved. In such a 156 situation, the client needs to be able to target a specific 157 recurrence instance or multiple instances when adding or deleting 158 attachments. As a result, the POST request needs to provide a way 159 for the client to specify which recurrence instances should be 160 targeted for the attachment operation. This is accomplished through 161 use of additional query parameters on the POST request-URI. 163 3.1. Requirements 165 A server that supports the features described in this specification 166 is REQUIRED to support the CalDAV "calendar-access" [RFC4791] 167 features. 169 In addition, such a server SHOULD support the "return=representation" 170 Prefer header field [RFC7240] preference on successful HTTP PUT and 171 POST requests targeting existing calendar object resources, by 172 returning the new representation of that calendar resource (including 173 its new ETag header field value) in the response. 175 3.2. Discovering Support for Managed Attachments 177 A server supporting the features described in this specification MUST 178 include "calendar-managed-attachments" as a field in the DAV response 179 header field from an OPTIONS request on a calendar home collection. 181 A server might choose to not support storing managed attachments on a 182 per-recurrence instance basis (i.e., they can only be added to all 183 instances as a whole). If that is the case, the server MUST include 184 "calendar-managed-attachments-no-recurrence" as a field in the DAV 185 response header field from an OPTIONS request on a calendar home 186 collection. When that field is present, clients MUST NOT attempt any 187 managed attachment operations that target specific recurrence 188 instances. 190 3.3. POST Request for Managing Attachments 192 An HTTP POST request is used to add, update, or remove attachments. 193 The request-URI will contain various query parameters to specify the 194 behavior. 196 3.3.1. action= Query Parameter 198 The "action" query parameter is used to identify which attachment 199 operation the client is requesting. This parameter MUST be present 200 once on each POST request used to manage attachments. One of these 201 three values MUST be used: 203 attachment-add Indicates an operation that is adding an attachment 204 to a calendar object resource. See Section 3.4 for more details. 206 attachment-update Indicates an operation that is updating an 207 existing attachment on a calendar object resource. See 208 Section 3.5 for more details. 210 attachment-remove Indicates an operation that is removing an 211 attachment from a calendar object resource. See Section 3.6 for 212 more details. 214 Example: 216 http://calendar.example.com/events/1.ics?action=attachment-add 218 3.3.2. rid= Query Parameter 220 The "rid" query parameter is used to identify which recurrence 221 instances are being targeted by the client for the attachment 222 operation. This query parameter MUST contain one or more items, 223 separated by commas (0x2C). The item values can be in one of two 224 forms: 226 Master instance The value "M" (case-insensitive) refers to the 227 "master" recurrence instance, i.e., the component that does not 228 include a "RECURRENCE-ID" property. This item MUST be present 229 only once. 231 Specific instance A specific iCalendar instance is targeted by using 232 its "RECURRENCE-ID" value as the item value. That value MUST 233 correspond to the RECURRENCE-ID value as stored in the calendar 234 object resource (i.e. without any conversion to UTC). If multiple 235 items of this form are used, they MUST be unique values. 237 If the "rid" query parameter is not present, all recurrence instances 238 in the calendar object resource are targeted. 240 The "rid" query parameter MUST NOT be present in the case of an 241 update operation, or if the server chooses not to support per- 242 recurrence instance managed attachments (see Section 3.1). 244 Example: 246 http://calendar.example.com/events/1.ics? 247 action=attachment-add&rid=M,20111022T160000 249 3.3.3. managed-id= Query Parameter 251 The "managed-id" query parameter is used to identify which "ATTACH" 252 property is being updated or removed. The value of this query 253 parameter MUST match the "MANAGED-ID" property parameter value on the 254 "ATTACH" property in the calendar object resource instance(s) 255 targeted by the request. 257 The "managed-id" query parameter MUST NOT be present in the case of 258 an add operation. 260 Example: 262 http://calendar.example.com/events/1.ics? 263 action=attachment-update&managed-id=aUNhbGVuZGFy 265 3.4. Adding attachments 267 To add an attachment to an existing calendar object resource, the 268 following occurs: 270 1. The client issues a POST request targeted at the calendar object 271 resource. 273 A. The request-URI will include an "action" query parameter with 274 the value "attachment-add" (see Section 3.3.1). 276 B. If all recurrence instances are having an attachment added, 277 the "rid" query parameter is not present in the request-URI. 278 If one or more specific recurrence instances are targeted, 279 then the request-URI will include a "rid" query parameter 280 containing the list of instances (see Section 3.3.2). 282 C. The body of the request contains the data for the attachment. 284 D. The client MUST include a valid Content-Type header field 285 describing the media type of the attachment (as required by 286 HTTP). 288 E. The client SHOULD include a Content-Disposition header field 289 [RFC6266] with a "type" parameter set to "attachment", and a 290 "filename" parameter that indicates the name of the 291 attachment. 293 F. The client MAY include a Prefer header field [RFC7240] with 294 the "return=representation" preference to request that the 295 modified calendar object resource be returned as the body of 296 a successful response to the POST request. 298 2. When the server receives the POST request it does the following: 300 A. Validates that any recurrence instances referred to via the 301 "rid" query parameter are valid for the calendar object 302 resource being targeted. 304 B. Stores the supplied attachment data into a resource and 305 generates an appropriate URI for clients to access the 306 resource. 308 C. For each affected recurrence instance in the calendar object 309 resource targeted by the request, the server adds an "ATTACH" 310 property, whose value is the URI of the stored attachment. 311 The "ATTACH" property MUST contain a "MANAGED-ID" parameter 312 whose value is a unique identifier (within the context of the 313 server as a whole). The "ATTACH" property SHOULD contain an 314 "FMTTYPE" parameter whose value matches the Content-Type 315 header field value from the request. The "ATTACH" property 316 SHOULD contain an "FILENAME" parameter whose value matches 317 the Content-Disposition header field "filename" parameter 318 value from the request, taking into account the restrictions 319 expressed in Section 4.2. The "ATTACH" property SHOULD 320 include a "SIZE" parameter whose value represents the size in 321 octets of the attachment. If a specified recurrence instance 322 does not have a matching component in the calendar object 323 resource, then the server MUST modify the calendar object 324 resource to include an overridden component with the 325 appropriate "RECURRENCE-ID" property. 327 D. Upon successful creation of the attachment resource, and 328 modification of the targeted calendar object resource, the 329 server MUST return an appropriate HTTP success status 330 response and include a "Cal-Managed-ID" header field 331 containing the "MANAGED-ID" parameter value of the newly 332 created "ATTACH" property. The client can use the "Cal- 333 Managed-ID" header field value to correlate the attachment 334 with "ATTACH" properties added to the calendar object 335 resource. If the client included a Prefer header field with 336 the "return=representation" preference in the request, the 337 server SHOULD return the modified calendar object resource as 338 the body of the response. Otherwise, the server can expect 339 that the client will reload the calendar object resource with 340 a subsequent GET request to refresh any local cache. 342 In the following example, the client adds a new attachment to a non 343 recurring event and asks the server (via the Prefer [RFC7240] header 344 field) to return the modified version of that event in the response. 346 >> Request << 348 POST /events/64.ics?action=attachment-add HTTP/1.1 349 Host: cal.example.com 350 Content-Type: text/html; charset="utf-8" 351 Content-Disposition:attachment;filename=agenda.html 352 Content-Length: xxxx 353 Prefer: return=representation 355 356 357

Agenda

358 359 360 >> Response << 362 HTTP/1.1 201 Created 363 Content-Type: text/calendar; charset="utf-8" 364 Content-Length: yyyy 365 Content-Location: http://cal.example.com/events/64.ics 366 ETag: "123456789-000-111" 367 Cal-Managed-ID: 97S 369 BEGIN:VCALENDAR 370 VERSION:2.0 371 PRODID:-//Example Corp.//CalDAV Server//EN 372 BEGIN:VEVENT 373 UID:20010712T182145Z-123401@example.com 374 DTSTAMP:20120201T203412Z 375 DTSTART:20120714T170000Z 376 DTEND:20120715T040000Z 377 SUMMARY:One-off meeting 378 ATTACH;MANAGED-ID=97S;FMTTYPE=text/html;SIZE=xxxx; 379 FILENAME=agenda.html:https://cal.example.com/attach/64/34X22R 380 END:VEVENT 381 END:VCALENDAR 383 3.5. Updating Attachments 385 When an attachment is updated the server MUST change the associated 386 "MANAGED-ID" parameter and MAY change the "ATTACH" property value. 387 With this approach, clients are able to determine when an attachment 388 has been updated by some other client by looking for a change to 389 either the "ATTACH" property value, or the "MANAGED-ID" parameter 390 value. 392 To change the data of an existing managed attachment in a calendar 393 object resource, the following occurs: 395 1. The client issues a POST request targeted at the calendar object 396 resource. 398 A. The request-URI will include an "action" query parameter with 399 the value "attachment-update" (see Section 3.3.1). 401 B. The request-URI will include a "managed-id" query parameter 402 with the value matching that of the "MANAGED-ID" parameter 403 for the "ATTACH" property being updated (see Section 3.3.3). 405 C. The body of the request contains the updated data for the 406 attachment. 408 D. The client MUST include a valid Content-Type header field 409 describing the media type of the attachment (as required by 410 HTTP). 412 E. The client SHOULD include a Content-Disposition header field 413 [RFC6266] with a "type" parameter set to "attachment", and a 414 "filename" parameter that indicates the name of the 415 attachment. 417 F. The client MAY include a Prefer header field [RFC7240] with 418 the "return=representation" preference to request that the 419 modified calendar object resource be returned as the body of 420 a successful response to the POST request. 422 2. When the server receives the POST request it does the following: 424 A. Validates that the "managed-id" query parameter is valid for 425 the calendar object resource. 427 B. Updates the content of the attachment resource corresponding 428 to that managed-id with the supplied attachment data. 430 C. For each affected recurrence instance in the calendar object 431 resource targeted by the request, the server updates the 432 "ATTACH" property whose "MANAGED-ID" property parameter value 433 matches the "managed-id" query parameter. The "MANAGED-ID" 434 parameter value is changed to allow other clients to detect 435 the update, and the property value (attachment URI) might 436 also be changed. The "ATTACH" property SHOULD contain a 437 "FMTTYPE" parameter whose value matches the Content-Type 438 header field value from the request - this could differ from 439 the original value if the media type of the updated 440 attachment is different. The "ATTACH" property SHOULD 441 contain a "FILENAME" parameter whose value matches the 442 Content-Disposition header field "filename" parameter value 443 from the request, taking into account the restrictions 444 expressed in Section 4.2. The "ATTACH" property SHOULD 445 include a "SIZE" parameter whose value represents the size in 446 octets of the updated attachment. 448 D. Upon successful update of the attachment resource, and 449 modification of the targeted calendar object resource, the 450 server MUST return an appropriate HTTP success status 451 response, and include a "Cal-Managed-ID" header field 452 containing the new value of the "MANAGED-ID" parameter. The 453 client can use the "Cal-Managed-ID" header field value to 454 correlate the attachment with "ATTACH" properties added to 455 the calendar object resource. If the client included a 456 Prefer header field with the "return=representation" 457 preference in the request, the server SHOULD return the 458 modified calendar object resource as the body of the 459 response. Otherwise, the server can expect that the client 460 will reload the calendar object resource with a subsequent 461 GET request to refresh any local cache. 463 The update operation does not take a "rid" parameter and does not 464 add, or remove, any "ATTACH" property in the targeted calendar object 465 resource. To link an existing attachment to a new instance, the 466 client simply does a PUT on the calendar object resource, adding an 467 "ATTACH" property which duplicates the existing one (see 468 Section 3.7). 470 In the following example, the client updates an existing attachment 471 and asks the server (via the Prefer [RFC7240] header field) to return 472 the updated version of that event in the response. 474 >> Request << 476 POST /events/64.ics?action=attachment-update&managed-id=97S HTTP/1.1 477 Host: cal.example.com 478 Content-Type: text/html; charset="utf-8" 479 Content-Disposition:attachment;filename=agenda.html 480 Content-Length: xxxx 481 Prefer: return=representation 483 484 485

Agenda

486

Discuss attachment draft

487 488 489 >> Response << 491 HTTP/1.1 200 OK 492 Content-Type: text/calendar; charset="utf-8" 493 Content-Length: yyyz 494 Content-Location: http://cal.example.com/events/64.ics 495 Cal-Managed-ID: 98S 496 ETag: "123456789-000-222" 498 BEGIN:VCALENDAR 499 VERSION:2.0 500 PRODID:-//Example Corp.//CalDAV Server//EN 501 BEGIN:VEVENT 502 UID:20010712T182145Z-123401@example.com 503 DTSTAMP:20120201T203412Z 504 DTSTART:20120714T170000Z 505 DTEND:20120715T040000Z 506 SUMMARY:One-off meeting 507 ATTACH;MANAGED-ID=98S;FMTTYPE=text/html;SIZE=xxxy; 508 FILENAME=agenda.html:https://cal.example.com/attach/64/34X22R 509 END:VEVENT 510 END:VCALENDAR 512 3.6. Removing Attachments via POST 514 To remove an existing attachment from a calendar object, the 515 following occurs: 517 1. The client issues a POST request targeted at the calendar object 518 resource. 520 A. The request-URI will include an "action" query parameter with 521 the value "attachment-remove" (see Section 3.3.1). 523 B. If all recurrence instances are having an attachment removed, 524 the "rid" query parameter is not present in the request-URI. 525 If one or more specific recurrence instances are targeted, 526 then the request-URI will include a "rid" query parameter 527 containing the list of instances (see Section 3.3.2). 529 C. The request-URI will include a "managed-id" query parameter 530 with the value matching that of the "MANAGED-ID" property 531 parameter for the "ATTACH" property being removed (see 532 Section 3.3.3). 534 D. The body of the request will be empty. 536 E. The client MAY include a Prefer header field [RFC7240] with 537 the "return=representation" preference to request that the 538 modified calendar object resource be returned as the body of 539 a successful response to the POST request. 541 2. When the server receives the POST request it does the following: 543 A. Validates that any recurrence instances referred to via the 544 "rid" query parameter are valid for the calendar object 545 resource being targeted. 547 B. Validates that the "managed-id" query parameter is valid for 548 the calendar object resource and specific instances being 549 targeted. 551 C. For each affected recurrence instance in the calendar object 552 resource targeted by the request, the server removes the 553 matching "ATTACH" property. Note that if a specified 554 recurrence instance does not have a matching component in the 555 calendar object resource, then the server MUST modify the 556 calendar object resource to include an overridden component 557 with the appropriate "RECURRENCE-ID" property, and the 558 matching "ATTACH" property removed. This later case is 559 actually valid only if the master component does include the 560 referenced "ATTACH" property. 562 D. If the attachment resource is no longer referenced by any 563 instance of the calendar object resource, the server can 564 delete the attachment resource to free up storage space. 566 E. Upon successful removal of the attachment resource and 567 modification of the targeted calendar object resource, the 568 server MUST return an appropriate HTTP success status 569 response. If the client included a Prefer header field with 570 the "return=representation" preference in the request, the 571 server SHOULD return the modified calendar object resource as 572 the body of the response. Otherwise, the server can expect 573 that the client will reload the calendar object resource with 574 a subsequent GET request to refresh any local cache. 576 In the following example, the client deletes an existing attachment 577 by passing its managed-id in the request. The Prefer [RFC7240] 578 header field is not set in the request so the calendar object 579 resource data is not returned in the response. 581 >> Request << 583 POST /events/64.ics?action=attachment-remove&managed-id=98S HTTP/1.1 584 Host: cal.example.com 585 Content-Length: 0 587 >> Response << 589 HTTP/1.1 204 No Content 590 Content-Length: 0 592 3.7. Adding Existing Managed Attachments via PUT 594 Clients can make use of existing managed attachments by adding the 595 corresponding "ATTACH" property to calendar object resources (subject 596 to the restrictions described in Section 3.12.2). When this occurs, 597 servers SHOULD NOT change either the "MANAGED-ID" parameter value or 598 the "ATTACH" property value for any managed attachments - this 599 ensures that clients do not have to download the attachment data 600 again if they already have it cached, because it is used in another 601 calendar resource. 603 3.8. Updating Attachments via PUT 605 Servers MUST NOT allow clients to update attachment data directly via 606 a PUT on the attachment URI (or via any other HTTP method that 607 modifies content). Instead, attachments can only be updated via use 608 of POST requests on the calendar data. 610 3.9. Removing Attachments via PUT 612 Clients can remove attachments by simply re-writing the calendar 613 object resource data to remove the appropriate "ATTACH" properties. 614 Servers MUST NOT allow clients to delete attachments directly via a 615 DELETE request on the attachment URI. 617 3.10. Retrieving Attachments 619 Clients retrieve attachments by issuing an HTTP GET request using the 620 value of the corresponding "ATTACH" property as the request-URI, 621 taking into account the substitution mechanism associated with the 622 "CALDAV:managed-attachments-server-URL" property (see Section 6.1). 624 3.11. Error Handling 626 This specification creates additional preconditions for the POST 627 method. 629 The new preconditions are: 631 (CALDAV:max-attachment-size): The attachment submitted in the POST 632 request MUST have an octet size less than or equal to the value of 633 the CALDAV:max-attachment-size property value (Section 6.2) on the 634 calendar collection of the target calendar resource; 636 (CALDAV:max-attachments-per-resource): The addition of the 637 attachment submitted in the POST request MUST result in the target 638 calendar resource having a number of managed attachments less than 639 or equal to the value of the CALDAV:max-attachments-per-resource 640 property value (Section 6.3) on the calendar collection of the 641 target calendar resource; 643 (CALDAV:valid-managed-id): The managed-id query parameter in the 644 POST request MUST contain a value corresponding to a "MANAGED-ID" 645 property parameter value in the iCalendar data targeted by the 646 request. 648 A POST request to add, modify, or delete a managed attachment results 649 in an implicit modification of the targeted calendar resource 650 (equivalent of a PUT). As a consequence, clients should also be 651 prepared to handle preconditions associated with this implicit PUT. 652 This includes (but is not limited to): 654 (CALDAV:max-resource-size) (from Section 5.3.2.1 of [RFC4791]) 656 (DAV:quota-not-exceeded) (from Section 6 of [RFC4331]) 658 (DAV:sufficient-disk-space) (from Section 6 of [RFC4331]) 660 A PUT request to add or modify and existing calendar object resource 661 can make reference to an existing managed attachment. The following 662 new preconditions is defined: 664 (CALDAV:valid-managed-id-parameter): a "MANAGED-ID" property 665 parameter value in the iCalendar data in the PUT request is not 666 valid (e.g., does not match any existing managed attachment). 668 3.12. Additional Considerations 670 3.12.1. Quotas 672 The WebDAV Quotas [RFC4331] specification defines two live WebDAV 673 properties (DAV:quota-available-bytes and DAV:quota-used-bytes) to 674 communicate storage quota information to clients. Server 675 implementations MAY choose to include managed attachments sizes when 676 calculating the amount of storage used by a particular resource. 678 3.12.2. Access Control 680 Access to the managed attachments store in a calendar object resource 681 SHOULD be restricted to only those calendar users who have access to 682 that calendar object either directly, or indirectly (via being an 683 attendee who would receive a scheduling message). 685 When accessing a managed attachment, clients SHOULD be prepared to 686 authenticate with the server storing the attachment resource. The 687 credentials required to access the managed attachment store could be 688 different from the ones used to access the CalDAV server. 690 This specification only allows organizers of scheduled events to add 691 managed attachments. Servers MUST prevent attendees of scheduled 692 events from adding, updating or removing managed attachments. In 693 addition, the server MUST prevent a calendar user from re-using a 694 managed attachment (based on its managed-id value), unless that user 695 is the one who originally created the managed attachment. 697 3.12.3. Redirects 699 For POST requests that add or update attachment data, the server MAY 700 issue an HTTP redirect to require the client to re-issue the POST 701 request using a different request-URI. As a result, it is always 702 best for clients to use the "100-continue" expectation defined in 703 Section 5.1.1 of [RFC7231]. Using this mechanism ensures that, if a 704 redirect does occur, the client does not needlessly send the 705 attachment data. 707 3.12.4. Processing Time 709 Clients can expect servers to take a while to respond to POST 710 requests that include large attachment bodies. Servers SHOULD use 711 the "102 (Processing)" interim response defined in Section 10.1 of 712 [RFC2518] to keep the client connection alive if the POST request 713 will take significant time to complete. 715 3.12.5. Automatic Clean-Up by Servers 717 Servers MAY automatically remove attachment data, for example to 718 regain the storage taken by unused attachments, or as the result of a 719 virus scanning. When doing so they SHOULD NOT modify calendar data 720 referencing those attachments. Instead they SHOULD respond with "410 721 (Gone)" to any request on the removed attachment URI. 723 3.12.6. Sending Scheduling Messages with Attachments 725 When a managed attachment is added, updated or removed from a 726 calendar object resource, the server MUST ensure that a scheduling 727 message is sent to update any attendees with the changes, as per 728 [RFC6638]. 730 3.12.7. Migrating Calendar Data 732 When exporting calendar data from a CalDAV server supporting managed 733 attachments, clients SHOULD remove all "MANAGED-ID" property 734 parameters from "ATTACH" properties in the calendar data. Similarly 735 when importing calendar data from another source, clients SHOULD 736 remove any "MANAGED-ID" property parameters on "ATTACH" properties 737 (failure to do so will likely result in the server removing those 738 properties automatically). 740 4. Modifications to iCalendar Syntax 742 4.1. SIZE Property Parameter 744 Parameter Name: SIZE 746 Purpose: To specify the size of an attachment. 748 Format Definition: This property parameter is defined by the 749 following notation: 751 sizeparam = "SIZE" "=" paramtext 752 ; positive integers 754 Description: This property parameter MAY be specified on "ATTACH" 755 properties. It indicates the size in octets of the corresponding 756 attachment data. Since iCalendar integer values are restricted to 757 a maximum value of 2147483647, the current parameter is defined as 758 text to allow an extended range to be used. 760 Example: 762 ATTACH;SIZE=1234:http://attachments.example.com/abcd.txt 764 4.2. FILENAME Property Parameter 766 Parameter Name: FILENAME 768 Purpose: To specify the file name of a managed attachment. 770 Format Definition: This property parameter is defined by the 771 following notation: 773 filenameparam = "FILENAME" "=" paramtext 775 Description: This property parameter MAY be specified on "ATTACH" 776 properties corresponding to managed attachments. Its value 777 provides information on how to construct a filename for storing 778 the attachment data. This parameter is very similar in nature to 779 the Content-Disposition HTTP header field "filename" parameter and 780 exposes the same security risks. As a consequence, clients MUST 781 follow the guidelines expressed in Section 4.3 of [RFC6266] when 782 consuming this parameter value. Similarly, servers MUST follow 783 those same guidelines before storing a value. 785 Example: 787 ATTACH;FILENAME=agenda.html:http://attachments.example.c 788 om/rt452S 790 4.3. MANAGED-ID Property Parameter 792 Parameter Name: MANAGED-ID 794 Purpose: To uniquely identify a managed attachment. 796 Format Definition: This property parameter is defined by the 797 following notation: 799 managedidparam = "MANAGED-ID" "=" paramtext 801 Description: This property parameter MUST be specified on "ATTACH" 802 properties corresponding to managed attachments. Its value is 803 generated by the server and uniquely identifies a managed 804 attachment. This property parameter MUST NOT be present in the 805 case of non-managed attachments. 807 Example: 809 ATTACH;MANAGED-ID=aUNhbGVuZGFy:http://attachments.example.c 810 om/abcd.txt 812 5. Additional Message Header Fields 814 5.1. Cal-Managed-ID Response Header Field 816 The Cal-Managed-ID response header field provides the value of the 817 MANAGED-ID parameter corresponding to a newly added ATTACH property. 818 It MUST be sent only in response to a successful POST request with an 819 action set to attachment-add or attachment-update. 821 Cal-Managed-ID = "Cal-Managed-ID" ":" paramtext 822 ; "paramtext" is defined in Section 3.1 of [RFC5545] 824 Example: 826 Cal-Managed-ID:aUNhbGVuZGFy 828 6. Additional WebDAV Properties 830 6.1. CALDAV:managed-attachments-server-URL property 832 Name: managed-attachments-server-URL 834 Namespace: urn:ietf:params:xml:ns:caldav 836 Purpose: Specifies the server base URI to use when retrieving 837 managed attachments. 839 Protected: This property MUST be protected as only the server can 840 update the value. 842 COPY/MOVE behavior: This property is only defined on a calendar home 843 collection which cannot be moved or copied. 845 allprop behavior: SHOULD NOT be returned by a PROPFIND DAV:allprop 846 request. 848 Description: This property MAY be defined on a calendar home 849 collection. If present, it contains zero or one DAV:href XML 850 elements. 852 When one DAV:href element is present, its value MUST be an 853 absolute HTTP URI containing only the scheme (i.e. "https") and 854 authority (i.e. host and port) parts . Whenever a managed 855 attachment is to be retrieved via an HTTP GET, the client MUST 856 construct the actual URL of the attachment by substituting the 857 scheme and authority parts of the attachment URI (as stored in the 858 iCalendar "ATTACH" property) with the present WebDAV property 859 value. 861 When no DAV:href element is present, the client MUST substitute 862 the scheme and authority parts of the attachment URI with the 863 scheme and authority part of the calendar home collection absolute 864 URI. 866 In the absence of this property, the client can consider the 867 attachment URI as its actual URL. 869 Definition: 871 873 Example: 875 877 https://attachstore.example.com 878 880 6.2. CALDAV:max-attachment-size property 882 Name: max-attachment-size 884 Namespace: urn:ietf:params:xml:ns:caldav 886 Purpose: Provides a numeric value indicating the maximum attachment 887 size, in octets, that the server is willing to accept when a 888 managed attachment is stored on the server. 890 Protected: MUST be protected as it indicates limits provided by the 891 server. 893 COPY/MOVE behavior: This property value MUST be preserved in COPY 894 and MOVE operations. 896 allprop behavior: SHOULD NOT be returned by a PROPFIND DAV:allprop 897 request. 899 Description: The CALDAV:max-attachment-size property is used to 900 specify a numeric value that represents the maximum attachment 901 size, in octets, that the server is willing to accept when a 902 managed attachment is stored on the server. The property is 903 defined on the parent collection of the calendar object resource 904 to which the attachment is associated. Any attempt to store a 905 managed attachment exceeding this size MUST result in an error, 906 with the CALDAV:max-attachment-size precondition (Section 3.11) 907 being violated. In the absence of this property, the client can 908 assume that the server will allow storing an attachment of any 909 reasonable size. 911 Definition: 913 914 916 Example: 918 102400000 921 6.3. CALDAV:max-attachments-per-resource property 923 Name: max-attachments-per-resource 925 Namespace: urn:ietf:params:xml:ns:caldav 927 Purpose: Provides a numeric value indicating the maximum number of 928 managed attachments across all instances of a calendar object 929 resource stored in a calendar collection. 931 Protected: MUST be protected as it indicates limits provided by the 932 server. 934 COPY/MOVE behavior: This property value MUST be preserved in COPY 935 and MOVE operations. 937 allprop behavior: SHOULD NOT be returned by a PROPFIND DAV:allprop 938 request. 940 Description: The CALDAV:max-attachments-per-resource property is 941 used to specify a numeric value that represents the maximum number 942 of managed attachments across all instances of a calendar object 943 resource stored in a calendar collection. Non-managed attachments 944 are not counted toward that limit. The property is defined on the 945 parent collection of the calendar object resource to which the 946 attachment is associated. Any attempt to add a managed attachment 947 that would cause the calendar resource to exceed this limit MUST 948 result in an error, with the CALDAV:max-attachments-per-resource 949 precondition (Section 3.11) being violated. In the absence of 950 this property, the client can assume that the server can handle 951 any number of managed attachments per calendar resource. 953 Definition: 955 956 958 Example: 960 12 964 7. Implementation Status 966 < RFC Editor: before publication please remove this section and the 967 reference to [RFC7942] > 969 This section records the status of known implementations of the 970 protocol defined by this specification at the time of posting of this 971 Internet-Draft, and is based on a proposal described in [RFC7942]. 972 The description of implementations in this section is intended to 973 assist the IETF in its decision processes in progressing drafts to 974 RFCs. Please note that the listing of any individual implementation 975 here does not imply endorsement by the IETF. Furthermore, no effort 976 has been spent to verify the information presented here that was 977 supplied by IETF contributors. This is not intended as, and must not 978 be construed to be, a catalog of available implementations or their 979 features. Readers are advised to note that other implementations may 980 exist. 982 According to [RFC7942], "this will allow reviewers and working groups 983 to assign due consideration to documents that have the benefit of 984 running code, which may serve as evidence of valuable experimentation 985 and feedback that have made the implemented protocols more mature. 986 It is up to the individual working groups to use this information as 987 they see fit". 989 7.1. Calendar and Contacts Server 991 The open source Calendar and Contacts Server [1] project is a 992 standards-compliant server implementing the CalDAV protocol. This 993 production level implementation supports all of the requirements 994 described in this document and successfully interoperates with the 995 Apple Calendar, BusyCal, 2Do, and CalDAVTester client implementations 996 described below. This implementation is freely distributable under 997 the terms of the Apache License, Version 2.0 [2]. 999 7.2. Cyrus Server 1001 The open source Cyrus Server [3] project is a highly scalable 1002 enterprise mail system which also supports calendaring. This 1003 production level CalDAV implementation supports all of the 1004 requirements described in this document and successfully 1005 interoperates with the Apple Calendar and CalDAVTester client 1006 implementations described below. This implementation is freely 1007 distributable under a BSD style license from Computing Services at 1008 Carnegie Mellon University [4]. 1010 7.3. Oracle Communications Calendar Server 1012 The Oracle Communications Calendar Server [5] project is a standards- 1013 compliant, scalable, enterprise-ready calendaring solution. This 1014 production level CalDAV implementation supports all of the 1015 requirements described in this document and successfully 1016 interoperates with the Apple Calendar and CalDAVTester client 1017 implementations described below. This implementation is proprietary 1018 and available for a free trial and/or purchase from the vendor. 1020 7.4. Apple Calendar 1022 The widely used Apple Calendar [6] client is a standards-compliant 1023 client implementing the CalDAV protocol. This production level 1024 implementation supports all the requirements described in this 1025 document and successfully interoperates with the 1026 Calendar and Contacts Server, Cyrus Server, and 1027 Oracle Communications Calendar Server implementations described 1028 above. This client implementation is proprietary and is distributed 1029 as part of Apple's desktop operating systems. 1031 7.5. BusyCal 1033 BusyCal [7] is a standards-compliant calendar client for MacOS 1034 implementing the CalDAV protocol. This implementation supports all 1035 of the requirements described in this document and successfully 1036 interoperates with the Calendar and Contacts Server and Cyrus Server 1037 implementations described above. This implementation is proprietary 1038 and available for a free trial and/or purchase from the vendor. 1040 7.6. CalDAVTester 1042 CalDAVTester [8] is an open source test and performance application 1043 designed to work with CalDAV servers and tests various aspects of 1044 their protocol handling as well as performance. This widely used 1045 implementation supports all of the requirements described in this 1046 document and successfully interoperates with the server 1047 implementations described above. This implementation is freely 1048 distributable under the terms of the Apache License, Version 2.0 [9]. 1050 7.7. 2Do 1052 2Do [10] is a standards-complient calendar client for iOS which uses 1053 the CalDAV standard for communication. This implementation supports 1054 all of the requirements described in this document and successfully 1055 interoperates with the Calendar and Contacts Server implementation 1056 described above. This implementation is proprietary and available 1057 for purchase from the vendor. 1059 8. Security Considerations 1061 Malicious content could be introduced into the Calendar Server by way 1062 of a managed attachment, and propagated to many end users via 1063 scheduling. Servers SHOULD check managed attachments for malicious 1064 or inappropriate content. Upon detecting of such content, servers 1065 SHOULD remove the attachment, following the rules described in 1066 Section 3.12.5. 1068 9. IANA Considerations 1070 9.1. Parameter Registrations 1072 This specification defines the following new iCalendar property 1073 parameters to be added to the registry defined in Section 8.2.3 of 1074 [RFC5545]: 1076 +--------------------+---------+----------------------+ 1077 | Property Parameter | Status | Reference | 1078 +--------------------+---------+----------------------+ 1079 | SIZE | Current | RFCXXXX, Section 4.1 | 1080 | FILENAME | Current | RFCXXXX, Section 4.2 | 1081 | MANAGED-ID | Current | RFCXXXX, Section 4.3 | 1082 +--------------------+---------+----------------------+ 1084 9.2. Message Header Field Registrations 1086 The message header fields below should be added to the Permanent 1087 Message Header Field Registry (see [RFC3864]). 1089 9.2.1. Cal-Managed-ID 1091 Header field name: Cal-Managed-ID 1093 Applicable protocol: http 1094 Status: standard 1096 Author/Change controller: IETF 1098 Specification document(s): this specification (Section 5.1) 1100 Related information: none 1102 10. Acknowledgments 1104 This specification came about via discussions at the Calendaring and 1105 Scheduling Consortium. Thanks in particular to Mike Douglass and 1106 Eric York. 1108 11. References 1110 11.1. Normative References 1112 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1113 Requirement Levels", BCP 14, RFC 2119, 1114 DOI 10.17487/RFC2119, March 1997, 1115 . 1117 [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D. 1118 Jensen, "HTTP Extensions for Distributed Authoring -- 1119 WEBDAV", RFC 2518, DOI 10.17487/RFC2518, February 1999, 1120 . 1122 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 1123 Procedures for Message Header Fields", BCP 90, RFC 3864, 1124 DOI 10.17487/RFC3864, September 2004, 1125 . 1127 [RFC4331] Korver, B. and L. Dusseault, "Quota and Size Properties 1128 for Distributed Authoring and Versioning (DAV) 1129 Collections", RFC 4331, DOI 10.17487/RFC4331, February 1130 2006, . 1132 [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, 1133 "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, 1134 DOI 10.17487/RFC4791, March 2007, 1135 . 1137 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1138 Specifications: ABNF", STD 68, RFC 5234, 1139 DOI 10.17487/RFC5234, January 2008, 1140 . 1142 [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and 1143 Scheduling Core Object Specification (iCalendar)", 1144 RFC 5545, DOI 10.17487/RFC5545, September 2009, 1145 . 1147 [RFC6266] Reschke, J., "Use of the Content-Disposition Header Field 1148 in the Hypertext Transfer Protocol (HTTP)", RFC 6266, 1149 DOI 10.17487/RFC6266, June 2011, 1150 . 1152 [RFC6638] Daboo, C. and B. Desruisseaux, "Scheduling Extensions to 1153 CalDAV", RFC 6638, DOI 10.17487/RFC6638, June 2012, 1154 . 1156 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1157 Protocol (HTTP/1.1): Message Syntax and Routing", 1158 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1159 . 1161 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1162 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1163 DOI 10.17487/RFC7231, June 2014, 1164 . 1166 [RFC7240] Snell, J., "Prefer Header for HTTP", RFC 7240, 1167 DOI 10.17487/RFC7240, June 2014, 1168 . 1170 11.2. Informative References 1172 [RFC5546] Daboo, C., Ed., "iCalendar Transport-Independent 1173 Interoperability Protocol (iTIP)", RFC 5546, 1174 DOI 10.17487/RFC5546, December 2009, 1175 . 1177 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 1178 Code: The Implementation Status Section", BCP 205, 1179 RFC 7942, DOI 10.17487/RFC7942, July 2016, 1180 . 1182 [RFC8144] Murchison, K., "Use of the Prefer Header Field in Web 1183 Distributed Authoring and Versioning (WebDAV)", RFC 8144, 1184 DOI 10.17487/RFC8144, April 2017, 1185 . 1187 11.3. URIs 1189 [1] http://calendarserver.org/ 1191 [2] http://www.apache.org/licenses/LICENSE-2.0.html 1193 [3] http://www.cyrusimap.org/ 1195 [4] http://www.cmu.edu/computing/ 1197 [5] http://www.cyrusimap.org/ 1199 [6] http://www.apple.com/macos/ 1201 [7] http://www.busymac.com/busycal/ 1203 [8] http://calendarserver.org/wiki/CalDAVTester 1205 [9] http://www.apache.org/licenses/LICENSE-2.0.html 1207 [10] http://www.2doapp.com/ 1209 Appendix A. Change History (To be removed by RFC Editor before 1210 publication) 1212 Changes in calext-03: 1214 1. Changed to Informational based on feedback regarding non-standard 1215 method of updating an existing resource. 1217 2. Added references to sub-sections in Overview. 1219 3. Made support for Prefer header field a SHOULD for servers. 1221 4. Expanded recurring event examples to use conditional requests and 1222 to include the Expect header field. 1224 5. Minor editorial changes. 1226 Changes in calext-02: 1228 1. Moved "Error Handling" into its own sub-section. 1230 2. Split "Other Client Considerations" into "Processing Time" and 1231 "Migrating Calendar Data". 1233 Changes in calext-01: 1235 1. Changed all instances of "header" to "header field". 1237 2. Reworked wording of Prefer header field handling. 1239 3. Switched to recommending 102 (Processing) interim response to 1240 keep the client connection alive. 1242 4. Fixed description of Cal-Managed-ID response header field to 1243 state that it is also required in responses to successful 1244 attachment-update. 1246 5. Minor editorial changes. 1248 Changes in calext-00: 1250 1. Added Murchison as editor. 1252 2. Updated HTTP references to RFC7230 and RFC7231. 1254 3. Updated Prefer header field references to RFC7240. 1256 4. Added Implementation Status section. 1258 5. Minor editorial changes. 1260 Changes in daboo-03: 1262 1. Fixed some examples. 1264 2. Fixed return-representation -> return=representation. 1266 3. Added statement that servers must not allow clients to DELETE 1267 attachments directly. 1269 4. Added new preconditions for valid managed-id values. 1271 5. Filled out Access Control section. 1273 6. Allow servers to not support per-instance attachments and 1274 advertise that fact to clients. 1276 Changes in daboo-02: 1278 1. MANAGED-ID changes on PUT. 1280 2. MTAG has been removed. 1282 3. Error pre-conditions added. 1284 4. Interaction with WebDAV QUOTA discussed. 1286 5. max-attachment-* limits added. 1288 6. Updated references. 1290 7. Removed MUST for specific 2xx codes in favor of generic success 1291 code. 1293 Changes in daboo-01: 1295 1. Tweaked OPTIONS capability wording. 1297 2. Added section on clients expecting 100-Continue for delayed 1298 response. 1300 3. Added text for clean-up and use of HTTP 410 on orphans. 1302 4. Added text on removing "MANAGED-ID" when exporting/importing 1303 calendar data. 1305 5. Added protocol examples. 1307 6. Added MTAG property parameter on ATTACH property 1309 7. Added FILENAME property parameter on ATTACH property 1311 8. "id" query parameter is now "managed-id". 1313 9. Use of Cal-Managed-ID header instead of Location header in 1314 responses. 1316 10. rid query param MUST contain RECURRENCE-ID without any 1317 conversion to UTC (case of floating events). 1319 11. Introduced CALDAV:managed-attachments-server-URL property 1321 12. Made support for Prefer header a MUST for servers. 1323 Appendix B. Example Involving Recurring Events 1325 In the following example, the organizer of a recurring meeting makes 1326 an unsuccessful attempt to add an agenda (HTML attachment) to the 1327 corresponding calendar resource with a conditional request. Note 1328 that the client includes both the Expect and Prefer header fields in 1329 the request, thereby preventing itself from needlessly sending the 1330 attachment data, and requesting that the current resource be returned 1331 in the failure response (see Section 3.2 of [RFC8144]). 1333 >> Request << 1335 POST /events/65.ics?action=attachment-add HTTP/1.1 1336 Host: cal.example.com 1337 Content-Type: text/html; charset="utf-8" 1338 Content-Disposition: attachment;filename=agenda.html 1339 Content-Length: xxxx 1340 If-Match: "abcdefg-000" 1341 Expect: 100-continue 1342 Prefer: return=representation 1343 >> Final Response << 1345 HTTP/1.1 412 Precondition Failed 1346 Content-Type: text/calendar; charset="utf-8" 1347 Content-Length: yyyy 1348 Content-Location: http://cal.example.com/events/65.ics 1349 ETag: "123456789-000-000" 1351 BEGIN:VCALENDAR 1352 VERSION:2.0 1353 PRODID:-//Example Corp.//CalDAV Server//EN 1354 BEGIN:VTIMEZONE 1355 LAST-MODIFIED:20040110T032845Z 1356 TZID:America/Montreal 1357 BEGIN:DAYLIGHT 1358 DTSTART:20000404T020000 1359 RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4 1360 TZNAME:EDT 1361 TZOFFSETFROM:-0500 1362 TZOFFSETTO:-0400 1363 END:DAYLIGHT 1364 BEGIN:STANDARD 1365 DTSTART:20001026T020000 1366 RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10 1367 TZNAME:EST 1368 TZOFFSETFROM:-0400 1369 TZOFFSETTO:-0500 1370 END:STANDARD 1371 END:VTIMEZONE 1372 BEGIN:VEVENT 1373 UID:20010712T182145Z-123401@example.com 1374 DTSTAMP:20120201T203412Z 1375 DTSTART;TZID=America/Montreal:20120206T100000 1376 DURATION:PT1H 1377 RRULE:FREQ=WEEKLY 1378 SUMMARY:Planning Meeting 1379 ORGANIZER:mailto:cyrus@example.com 1380 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:cyrus@exampl 1381 e.com 1382 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:arnaudq@exam 1383 ple.com 1384 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=NEEDS-ACTION:mailto:mike@exa 1385 mple.com 1386 END:VEVENT 1387 END:VCALENDAR 1389 The organizer of a recurring meeting successfully adds an agenda 1390 (HTML attachment) to the corresponding calendar resource. Attendees 1391 of the meeting are granted read access to the newly created 1392 attachment resource. Their own copy of the meeting is updated to 1393 include the new ATTACH property pointing to the attachment resource 1394 and they are notified of the change via their scheduling inbox. 1396 >> Request << 1398 POST /events/65.ics?action=attachment-add HTTP/1.1 1399 Host: cal.example.com 1400 Content-Type: text/html; charset="utf-8" 1401 Content-Disposition: attachment;filename=agenda.html 1402 Content-Length: xxxx 1403 If-Match: "123456789-000-000" 1404 Expect: 100-continue 1405 Prefer: return=representation 1407 >> Interim Response << 1409 HTTP/1.1 100 Continue 1411 >> Request Body << 1413 1414 1415

Agenda

1416

As usual

1417 1418 1419 >> Final Response << 1421 HTTP/1.1 201 Created 1422 Content-Type: text/calendar; charset="utf-8" 1423 Content-Length: yyyy 1424 Content-Location: http://cal.example.com/events/65.ics 1425 ETag: "123456789-000-111" 1426 Cal-Managed-ID: 97S 1428 BEGIN:VCALENDAR 1429 VERSION:2.0 1430 PRODID:-//Example Corp.//CalDAV Server//EN 1431 BEGIN:VTIMEZONE 1432 LAST-MODIFIED:20040110T032845Z 1433 TZID:America/Montreal 1434 BEGIN:DAYLIGHT 1435 DTSTART:20000404T020000 1436 RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4 1437 TZNAME:EDT 1438 TZOFFSETFROM:-0500 1439 TZOFFSETTO:-0400 1440 END:DAYLIGHT 1441 BEGIN:STANDARD 1442 DTSTART:20001026T020000 1443 RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10 1444 TZNAME:EST 1445 TZOFFSETFROM:-0400 1446 TZOFFSETTO:-0500 1447 END:STANDARD 1448 END:VTIMEZONE 1449 BEGIN:VEVENT 1450 UID:20010712T182145Z-123401@example.com 1451 DTSTAMP:20120201T203412Z 1452 DTSTART;TZID=America/Montreal:20120206T100000 1453 DURATION:PT1H 1454 RRULE:FREQ=WEEKLY 1455 SUMMARY:Planning Meeting 1456 ORGANIZER:mailto:cyrus@example.com 1457 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:cyrus@exampl 1458 e.com 1459 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:arnaudq@exam 1460 ple.com 1461 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=NEEDS-ACTION:mailto:mike@exa 1462 mple.com 1463 ATTACH;MANAGED-ID=97S;FMTTYPE=text/html;SIZE=xxxx; 1464 FILENAME=agenda.html:https://cal.example.com/attach/65/34X22R 1465 END:VEVENT 1466 END:VCALENDAR 1467 The organizer has a more specific agenda for the 20th of February 1468 meeting. It is added to that particular instance of the meeting by 1469 specifying the rid parameter. Note that the server takes significant 1470 time to complete the request and notifies the client accordingly. 1472 >> Request << 1474 POST /events/65.ics?action=attachment-add&rid=20120220T100000 HTTP/1.1 1475 Host: cal.example.com 1476 Content-Type: text/html; charset="utf-8" 1477 Content-Disposition: attachment;filename=agenda0220.html 1478 Content-Length: xxxx 1479 If-Match: "123456789-000-111" 1480 Expect: 100-continue 1481 Prefer: return=representation 1483 >> Interim Response << 1485 HTTP/1.1 100 Continue 1487 >> Request Body << 1489 1490 1491

Agenda

1492

Something different, for a change

1493 1494 1496 >> Interim Response << 1498 HTTP/1.1 102 Processing 1500 >> Final Response << 1502 HTTP/1.1 201 Created 1503 Content-Type: text/calendar; charset="utf-8" 1504 Content-Length: yyyy 1505 Content-Location: http://cal.example.com/events/65.ics 1506 ETag: "123456789-000-222" 1507 Cal-Managed-ID: 33225 1509 BEGIN:VCALENDAR 1510 VERSION:2.0 1511 PRODID:-//Example Corp.//CalDAV Server//EN 1512 BEGIN:VTIMEZONE 1513 LAST-MODIFIED:20040110T032845Z 1514 TZID:America/Montreal 1515 BEGIN:DAYLIGHT 1516 DTSTART:20000404T020000 1517 RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4 1518 TZNAME:EDT 1519 TZOFFSETFROM:-0500 1520 TZOFFSETTO:-0400 1521 END:DAYLIGHT 1522 BEGIN:STANDARD 1523 DTSTART:20001026T020000 1524 RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10 1525 TZNAME:EST 1526 TZOFFSETFROM:-0400 1527 TZOFFSETTO:-0500 1528 END:STANDARD 1529 END:VTIMEZONE 1530 BEGIN:VEVENT 1531 UID:20010712T182145Z-123401@example.com 1532 DTSTAMP:20120201T203412Z 1533 DTSTART;TZID=America/Montreal:20120206T100000 1534 DURATION:PT1H 1535 RRULE:FREQ=WEEKLY 1536 SUMMARY:Planning Meeting 1537 ORGANIZER:mailto:cyrus@example.com 1538 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:cyrus@exampl 1539 e.com 1540 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:arnaudq@exam 1541 ple.com 1542 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=NEEDS-ACTION:mailto:mike@exa 1543 mple.com 1544 ATTACH;MANAGED-ID=97S;FMTTYPE=text/html;SIZE=xxxx; 1545 FILENAME=agenda.html:https://cal.example.com/attach/65/34X22R 1546 END:VEVENT 1547 BEGIN:VEVENT 1548 UID:20010712T182145Z-123401@example.com 1549 RECURRENCE-ID;TZID=America/Montreal:20120220T100000 1550 DTSTAMP:20120201T203412Z 1551 DTSTART;TZID=America/Montreal:20120220T100000 1552 DURATION:PT1H 1553 SUMMARY:Planning Meeting 1554 ORGANIZER:mailto:cyrus@example.com 1555 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:cyrus@example. 1556 com 1557 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:arnaudq@exampl 1558 e.com 1559 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=NEEDS-ACTION:mailto:mike@examp 1560 le.com 1561 ATTACH;MANAGED-ID=33225;FMTTYPE=text/html;SIZE=xxxx; 1562 FILENAME=agenda0220.html:https://cal.example.com/attach/65/FGZ225 1563 END:VEVENT 1564 END:VCALENDAR 1566 Authors' Addresses 1568 Cyrus Daboo 1569 Apple Inc. 1570 1 Infinite Loop 1571 Cupertino, CA 95014 1572 USA 1574 Email: cyrus@daboo.name 1575 URI: http://www.apple.com/ 1577 Arnaud Quillaud 1578 Oracle Corporation 1579 180, Avenue de l'Europe 1580 Saint Ismier cedex 38334 1581 France 1583 Email: arnaud.quillaud@oracle.com 1584 URI: http://www.oracle.com/ 1586 Kenneth Murchison (editor) 1587 FastMail Pty Ltd. 1588 Level 1, 91 William Street 1589 Melbourne, VIC 3000 1590 Australia 1592 Email: murch@fastmail.com 1593 URI: http://www.fastmail.com/