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
407Discuss 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: 959As 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 1634Something 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/