idnits 2.17.1 draft-ietf-calext-caldav-attachments-01.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 (March 10, 2017) is 2604 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '1' on line 1177 -- Looks like a reference, but probably isn't: '2' on line 1179 -- Looks like a reference, but probably isn't: '3' on line 1181 -- Looks like a reference, but probably isn't: '4' on line 1183 -- Looks like a reference, but probably isn't: '5' on line 1185 -- Looks like a reference, but probably isn't: '6' on line 1187 -- Looks like a reference, but probably isn't: '7' on line 1189 -- Looks like a reference, but probably isn't: '8' on line 1191 -- Looks like a reference, but probably isn't: '9' on line 1193 -- Looks like a reference, but probably isn't: '10' on line 1195 ** 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: Standards Track A. Quillaud 5 Expires: September 11, 2017 Oracle 6 K. Murchison, Ed. 7 CMU 8 March 10, 2017 10 CalDAV Managed Attachments 11 draft-ietf-calext-caldav-attachments-01 13 Abstract 15 This specification defines an extension to the calendar access 16 protocol (CalDAV) to allow attachments associated with iCalendar 17 data, to be stored and managed on the server. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on September 11, 2017. 36 Copyright Notice 38 Copyright (c) 2017 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 54 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 55 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 3.1. Requirements . . . . . . . . . . . . . . . . . . . . . . 4 57 3.2. Discovering Support for Managed Attachments . . . . . . . 4 58 3.3. POST Request for Managing Attachments . . . . . . . . . . 4 59 3.4. Adding attachments . . . . . . . . . . . . . . . . . . . 6 60 3.5. Updating Attachments . . . . . . . . . . . . . . . . . . 9 61 3.6. Removing Attachments via POST . . . . . . . . . . . . . . 11 62 3.7. Adding Existing Managed Attachments via PUT . . . . . . . 13 63 3.8. Updating Attachments via PUT . . . . . . . . . . . . . . 13 64 3.9. Removing Attachments via PUT . . . . . . . . . . . . . . 14 65 3.10. Retrieving Attachments . . . . . . . . . . . . . . . . . 14 66 3.11. Additional Considerations . . . . . . . . . . . . . . . . 14 67 4. Modifications to iCalendar Syntax . . . . . . . . . . . . . . 16 68 4.1. SIZE Property Parameter . . . . . . . . . . . . . . . . . 16 69 4.2. FILENAME Property Parameter . . . . . . . . . . . . . . . 17 70 4.3. MANAGED-ID Property Parameter . . . . . . . . . . . . . . 17 71 5. Additional Message Header Fields . . . . . . . . . . . . . . 18 72 5.1. Cal-Managed-ID Response Header Field . . . . . . . . . . 18 73 6. Additional WebDAV properties . . . . . . . . . . . . . . . . 18 74 6.1. CALDAV:managed-attachments-server-URL property . . . . . 18 75 6.2. CALDAV:max-attachment-size property . . . . . . . . . . . 19 76 6.3. CALDAV:max-attachments-per-resource property . . . . . . 20 77 7. Implementation Status . . . . . . . . . . . . . . . . . . . . 21 78 8. Security Considerations . . . . . . . . . . . . . . . . . . . 23 79 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 80 9.1. Parameter Registrations . . . . . . . . . . . . . . . . . 23 81 9.2. Message Header Field Registrations . . . . . . . . . . . 24 82 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 24 83 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 24 84 11.1. Normative References . . . . . . . . . . . . . . . . . . 24 85 11.2. Informative References . . . . . . . . . . . . . . . . . 25 86 11.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 26 87 Appendix A. Change History (To be removed by RFC Editor before 88 publication) . . . . . . . . . . . . . . . . . . . . 26 89 Appendix B. Example Involving Recurring Events . . . . . . . . . 28 90 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 31 92 1. Introduction 94 The iCalendar [RFC5545] data format is used to represent calendar 95 data and is used with iTIP [RFC5546] to handle scheduling operations 96 between calendar users. 98 [RFC4791] defines the CalDAV Calendar Access protocol, based on HTTP 99 [RFC7230], for accessing calendar data stored on a server. 101 Calendar users often want to include attachments with their calendar 102 data events or tasks (for example a copy of a presentation, or the 103 meeting agenda). iCalendar provides an "ATTACH" property whose value 104 is either the inline Base64 encoded attachment data, or a URL 105 specifying the location of the attachment data. 107 Use of inline attachment data is not ideal with CalDAV because the 108 data would need to be uploaded to the server each time a change to 109 the calendar data is done - even minor changes such as a change to 110 the summary. Whilst a client could choose to use a URL value 111 instead, the problem then becomes where and how the client discovers 112 an appropriate URL to use and how it ensures that only those 113 attendees listed in the event or task are able to access it. 115 This specification solves this problem by having the client send the 116 attachment to the server, separately from the iCalendar data, and the 117 server takes care of adding appropriate "ATTACH" properties in the 118 iCalendar data as well as managing access privileges . The server can 119 also provide additional information to the client about each 120 attachment in the iCalendar data, such as the size and an identifier. 122 2. Conventions Used in This Document 124 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 125 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 126 "OPTIONAL" in this document are to be interpreted as described in 127 [RFC2119]. 129 The notation used in this memo is the ABNF notation of [RFC5234] as 130 used by iCalendar [RFC5545]. Any syntax elements shown below that 131 are not explicitly defined in this specification come from iCalendar 132 [RFC5545]. 134 3. Overview 136 There are four main operations a client needs to do with attachments 137 for calendar data: add, update, remove, and retrieve. The first 138 three operations are carried out by the client issuing an HTTP POST 139 request on the calendar object resource to which the attachment is 140 associated and specifying the appropriate "action" query parameter. 141 In the case of the remove operation, the client can alternatively 142 directly update the calendar object resource and remove the relevant 143 "ATTACH" properties. The retrieve operation is accomplished by 144 simply issuing an HTTP GET request targeting the attachment URI 145 specified by the calendar resource's "ATTACH" property. 147 iCalendar data stored in a CalDAV calendar object resource can 148 contain multiple components when recurrences are involved. In such a 149 situation, the client needs to be able to target a specific 150 recurrence instance or multiple instances when adding or deleting 151 attachments. As a result, the POST request needs to provide a way 152 for the client to specify which recurrence instances should be 153 targeted for the attachment operation. This is accomplished through 154 use of additional query parameters on the POST request-URI. 156 3.1. Requirements 158 A server that supports the features described in this specification 159 is REQUIRED to support the CalDAV "calendar-access" [RFC4791] 160 features. 162 In addition, such a server MUST support the "return=representation" 163 Prefer header field value [RFC7240] on successful HTTP PUT and POST 164 requests targeting existing calendar object resources, by returning 165 the new representation of that calendar resource (including its new 166 ETag header field value) in the response. 168 3.2. Discovering Support for Managed Attachments 170 A server supporting the features described in this specification MUST 171 include "calendar-managed-attachments" as a field in the DAV response 172 header field from an OPTIONS request on a calendar home collection. 174 A server might choose to not support storing managed attachments on a 175 per-recurrence instance basis (i.e., they can only be added to all 176 instances as a whole). If that is the case, the server MUST include 177 "calendar-managed-attachments-no-recurrence" as a field in the DAV 178 response header field from an OPTIONS request on a calendar home 179 collection. When that field is present, clients MUST NOT attempt any 180 managed attachment operations that target specific recurrence 181 instances. 183 3.3. POST Request for Managing Attachments 185 An HTTP POST request is used to add, update, or remove attachments. 186 The request-URI will contain various query parameters to specify the 187 behavior. 189 3.3.1. action= Query Parameter 191 The "action" query parameter is used to identify which attachment 192 operation the client is requesting. This parameter MUST be present 193 once on each POST request used to manage attachments. One of these 194 three values MUST be used: 196 attachment-add Indicates an operation that is adding an attachment 197 to a calendar object resource. See Section 3.4 for more details. 199 attachment-update Indicates an operation that is updating an 200 existing attachment on a calendar object resource. See 201 Section 3.5 for more details. 203 attachment-remove Indicates an operation that is removing an 204 attachment from a calendar object resource. See Section 3.6 for 205 more details. 207 Example: 209 http://calendar.example.com/events/1.ics?action=attachment-add 211 3.3.2. rid= Query Parameter 213 The "rid" query parameter is used to identify which recurrence 214 instances are being targeted by the client for the attachment 215 operation. This query parameter MUST contain one or more items, 216 separated by commas (0x2C). The item values can be in one of two 217 forms: 219 Master instance The value "M" (case-insensitive) refers to the 220 "master" recurrence instance, i.e., the component that does not 221 include a "RECURRENCE-ID" property. This item MUST be present 222 only once. 224 Specific instance A specific iCalendar instance is targeted by using 225 its "RECURRENCE-ID" value as the item value. That value MUST 226 correspond to the RECURRENCE-ID value as stored in the calendar 227 object resource (i.e. without any conversion to UTC). If multiple 228 items of this form are used, they MUST be unique values. 230 If the "rid" query parameter is not present, all recurrence instances 231 in the calendar object resource are targeted. 233 The "rid" query parameter MUST NOT be present in the case of an 234 update operation, or if the server chooses not to support per- 235 recurrence instance managed attachments (see Section 3.1). 237 Example: 239 http://calendar.example.com/events/1.ics? 240 action=attachment-add&rid=M,20111022T160000 242 3.3.3. managed-id= Query Parameter 244 The "managed-id" query parameter is used to identify which "ATTACH" 245 property is being updated or removed. The value of this query 246 parameter MUST match the "MANAGED-ID" property parameter value on the 247 "ATTACH" property in the calendar object resource instance(s) 248 targeted by the request. 250 The "managed-id" query parameter MUST NOT be present in the case of 251 an add operation. 253 Example: 255 http://calendar.example.com/events/1.ics? 256 action=attachment-update&managed-id=aUNhbGVuZGFy 258 3.4. Adding attachments 260 To add an attachment to an existing calendar object resource, the 261 following occurs: 263 1. The client issues a POST request targeted at the calendar object 264 resource. 266 A. The request-URI will include an "action" query parameter with 267 the value "attachment-add" (see Section 3.3.1). 269 B. If all recurrence instances are having an attachment added, 270 the "rid" query parameter is not present in the request-URI. 271 If one or more specific recurrence instances are targeted, 272 then the request-URI will include a "rid" query parameter 273 containing the list of instances (see Section 3.3.2). 275 C. The body of the request contains the data for the attachment. 277 D. The client MUST include a valid Content-Type header field 278 describing the media type of the attachment (as required by 279 HTTP). 281 E. The client SHOULD include a Content-Disposition header field 282 [RFC6266] with a "type" parameter set to "attachment", and a 283 "filename" parameter that indicates the name of the 284 attachment. 286 F. The client MAY include a Prefer header field [RFC7240] with 287 the "return=representation" preference to request that the 288 modified calendar object resource be returned as the body of 289 a successful response to the POST request. 291 2. When the server receives the POST request it does the following: 293 A. Validates that any recurrence instances referred to via the 294 "rid" query parameter are valid for the calendar object 295 resource being targeted. 297 B. Stores the supplied attachment data into a resource and 298 generates an appropriate URI for clients to access the 299 resource. 301 C. For each affected recurrence instance in the calendar object 302 resource targeted by the request, the server adds an "ATTACH" 303 property, whose value is the URI of the stored attachment. 304 The "ATTACH" property MUST contain a "MANAGED-ID" parameter 305 whose value is a unique identifier (within the context of the 306 server as a whole). The "ATTACH" property SHOULD contain an 307 "FMTTYPE" parameter whose value matches the Content-Type 308 header field value from the request. The "ATTACH" property 309 SHOULD contain an "FILENAME" parameter whose value matches 310 the Content-Disposition header field "filename" parameter 311 value from the request, taking into account the restrictions 312 expressed in Section 4.2. The "ATTACH" property SHOULD 313 include a "SIZE" parameter whose value represents the size in 314 octets of the attachment. If a specified recurrence instance 315 does not have a matching component in the calendar object 316 resource, then the server MUST modify the calendar object 317 resource to include an overridden component with the 318 appropriate "RECURRENCE-ID" property. 320 D. Upon successful creation of the attachment resource, and 321 modification of the targeted calendar object resource, the 322 server MUST return an appropriate HTTP success status 323 response and include a "Cal-Managed-ID" header field 324 containing the "MANAGED-ID" parameter value of the newly 325 created "ATTACH" property. The client can use the "Cal- 326 Managed-ID" header field value to correlate the attachment 327 with "ATTACH" properties added to the calendar object 328 resource. If the client included a Prefer header field with 329 the "return=representation" preference in the request, the 330 server SHOULD return the modified calendar object resource as 331 the body of the response. Otherwise, the server can expect 332 that the client will reload the calendar object resource with 333 a subsequent GET request to refresh any local cache. 335 In the following example, the client adds a new attachment to a non 336 recurring event and asks the server (via the Prefer [RFC7240] header 337 field) to return the modified version of that event in the response. 339 >> Request << 341 POST /events/64.ics?action=attachment-add HTTP/1.1 342 Host: cal.example.com 343 Content-Type: text/html; charset="utf-8" 344 Content-Disposition:attachment;filename=agenda.html 345 Content-Length: xxxx 346 Prefer: return=representation 348 349
350Discuss attachment draft
481 482 484 >> Response << 486 HTTP/1.1 200 OK 487 Content-Type: text/calendar; charset="utf-8" 488 Content-Length: yyyz 489 Content-Location: http://cal.example.com/events/64.ics 490 Cal-Managed-ID: 98S 491 ETag: "123456789-000-222" 493 BEGIN:VCALENDAR 494 VERSION:2.0 495 PRODID:-//Example Corp.//CalDAV Server//EN 496 BEGIN:VEVENT 497 UID:20010712T182145Z-123401@example.com 498 DTSTAMP:20120201T203412Z 499 DTSTART:20120714T170000Z 500 DTEND:20120715T040000Z 501 SUMMARY:One-off meeting 502 ATTACH;MANAGED-ID=98S;FMTTYPE=text/html;SIZE=xxxy; 503 FILENAME=agenda.html:https://cal.example.com/attach/64/34X22R 504 END:VEVENT 505 END:VCALENDAR 507 3.6. Removing Attachments via POST 509 To remove an existing attachment from a calendar object, the 510 following occurs: 512 1. The client issues a POST request targeted at the calendar object 513 resource. 515 A. The request-URI will include an "action" query parameter with 516 the value "attachment-remove" (see Section 3.3.1). 518 B. If all recurrence instances are having an attachment removed, 519 the "rid" query parameter is not present in the request-URI. 520 If one or more specific recurrence instances are targeted, 521 then the request-URI will include a "rid" query parameter 522 containing the list of instances (see Section 3.3.2). 524 C. The request-URI will include a "managed-id" query parameter 525 with the value matching that of the "MANAGED-ID" property 526 parameter for the "ATTACH" property being removed (see 527 Section 3.3.3). 529 D. The body of the request will be empty. 531 E. The client MAY include a Prefer header field [RFC7240] with 532 the "return=representation" preference to request that the 533 modified calendar object resource be returned as the body of 534 a successful response to the POST request. 536 2. When the server receives the POST request it does the following: 538 A. Validates that any recurrence instances referred to via the 539 "rid" query parameter are valid for the calendar object 540 resource being targeted. 542 B. Validates that the "managed-id" query parameter is valid for 543 the calendar object resource and specific instances being 544 targeted. 546 C. For each affected recurrence instance in the calendar object 547 resource targeted by the request, the server removes the 548 matching "ATTACH" property. Note that if a specified 549 recurrence instance does not have a matching component in the 550 calendar object resource, then the server MUST modify the 551 calendar object resource to include an overridden component 552 with the appropriate "RECURRENCE-ID" property, and the 553 matching "ATTACH" property removed. This later case is 554 actually valid only if the master component does include the 555 referenced "ATTACH" property. 557 D. If the attachment resource is no longer referenced by any 558 instance of the calendar object resource, the server can 559 delete the attachment resource to free up storage space. 561 E. Upon successful removal of the attachment resource and 562 modification of the targeted calendar object resource, the 563 server MUST return an appropriate HTTP success status 564 response. If the client included a Prefer header field with 565 the "return=representation" preference in the request, the 566 server SHOULD return the modified calendar object resource as 567 the body of the response. Otherwise, the server can expect 568 that the client will reload the calendar object resource with 569 a subsequent GET request to refresh any local cache. 571 In the following example, the client deletes an existing attachment 572 by passing its managed-id in the request. The Prefer [RFC7240] 573 header field is not set in the request so the calendar object 574 resource data is not returned in the response. 576 >> Request << 578 POST /events/64.ics?action=attachment-remove&managed-id=98S HTTP/1.1 579 Host: cal.example.com 580 Content-Length: 0 582 >> Response << 584 HTTP/1.1 204 No Content 585 Content-Length: 0 587 3.7. Adding Existing Managed Attachments via PUT 589 Clients can make use of existing managed attachments by adding the 590 corresponding "ATTACH" property to calendar object resources (subject 591 to the restrictions described in Section 3.11.3). When this occurs, 592 servers SHOULD NOT change either the "MANAGED-ID" parameter value or 593 the "ATTACH" property value for any managed attachments - this 594 ensures that clients do not have to download the attachment data 595 again if they already have it cached, because it is used in another 596 calendar resource. 598 3.8. Updating Attachments via PUT 600 Servers MUST NOT allow clients to update attachment data directly via 601 a PUT on the attachment URI (or via any other HTTP method that 602 modifies content). Instead, attachments can only be updated via use 603 of POST requests on the calendar data. 605 3.9. Removing Attachments via PUT 607 Clients can remove attachments by simply re-writing the calendar 608 object resource data to remove the appropriate "ATTACH" properties. 609 Servers MUST NOT allow clients to delete attachments directly via a 610 DELETE request on the attachment URI. 612 3.10. Retrieving Attachments 614 Clients retrieve attachments by issuing an HTTP GET request using the 615 value of the corresponding "ATTACH" property as the request-URI, 616 taking into account the substitution mechanism associated with the 617 "CALDAV:managed-attachments-server-URL" property (see Section 6.1). 619 3.11. Additional Considerations 621 3.11.1. Error Handling 623 This specification creates additional preconditions for the POST 624 method. 626 The new preconditions are: 628 (CALDAV:max-attachment-size): The attachment submitted in the POST 629 request MUST have an octet size less than or equal to the value of 630 the CALDAV:max-attachment-size property value (Section 6.2) on the 631 calendar collection of the target calendar resource; 633 (CALDAV:max-attachments-per-resource): The addition of the 634 attachment submitted in the POST request MUST result in the target 635 calendar resource having a number of managed attachments less than 636 or equal to the value of the CALDAV:max-attachments-per-resource 637 property value (Section 6.3) on the calendar collection of the 638 target calendar resource; 640 (CALDAV:valid-managed-id): The managed-id query parameter in the 641 POST request MUST contain a value corresponding to a "MANAGED-ID" 642 property parameter value in the iCalendar data targeted by the 643 request. 645 A POST request to add, modify, or delete a managed attachment results 646 in an implicit modification of the targeted calendar resource 647 (equivalent of a PUT). As a consequence, clients should also be 648 prepared to handle preconditions associated with this implicit PUT. 649 This includes (but is not limited to): 651 (CALDAV:max-resource-size) (from Section 5.3.2.1 of [RFC4791]) 652 (DAV:quota-not-exceeded) (from Section 6 of [RFC4331]) 654 (DAV:sufficient-disk-space) (from Section 6 of [RFC4331]) 656 A PUT request to add or modify and existing calendar object resource 657 can make reference to an existing managed attachment. The following 658 new preconditions is defined: 660 (CALDAV:valid-managed-id-parameter): a "MANAGED-ID" property 661 parameter value in the iCalendar data in the PUT request is not 662 valid (e.g., does not match any existing managed attachment). 664 3.11.2. Quotas 666 The WebDAV Quotas [RFC4331] specification defines two live WebDAV 667 properties (DAV:quota-available-bytes and DAV:quota-used-bytes) to 668 communicate storage quota information to clients. Server 669 implementations MAY choose to include managed attachments sizes when 670 calculating the amount of storage used by a particular resource. 672 3.11.3. Access Control 674 Access to the managed attachments store in a calendar object resource 675 SHOULD be restricted to only those calendar users who have access to 676 that calendar object either directly, or indirectly (via being an 677 attendee who would receive a scheduling message). 679 When accessing a managed attachment, clients SHOULD be prepared to 680 authenticate with the server storing the attachment resource. The 681 credentials required to access the managed attachment store could be 682 different from the ones used to access the CalDAV server. 684 This specification only allows organizers of scheduled events to add 685 managed attachments. Servers MUST prevent attendees of scheduled 686 events from adding, updating or removing managed attachments. In 687 addition, the server MUST prevent a calendar user from re-using a 688 managed attachment (based on its managed-id value), unless that user 689 is the one who originally created the managed attachment. 691 3.11.4. Redirects 693 For POST requests that add or update attachment data, the server MAY 694 issue an HTTP redirect to require the client to re-issue the POST 695 request using a different request-URI. As a result, it is always 696 best for clients to use the "100-continue" expectation defined in 697 Section 5.1.1 of [RFC7231]. Using this mechanism ensures that, if a 698 redirect does occur, the client does not needlessly send the 699 attachment data. 701 3.11.5. Automatic Clean-up by servers 703 Servers MAY automatically remove attachment data, for example to 704 regain the storage taken by unused attachments, or as the result of a 705 virus scanning. When doing so they SHOULD NOT modify calendar data 706 referencing those attachments. Instead they SHOULD respond with "410 707 (Gone)" to any request on the removed attachment URI. 709 3.11.6. Sending Scheduling Messages with Attachments 711 When a managed attachment is added, updated or removed from a 712 calendar object resource, the server MUST ensure that a scheduling 713 message is sent to update any attendees with the changes, as per 714 [RFC6638]. 716 3.11.7. Other Client Considerations 718 Clients can expect servers to take a while to respond to POST 719 requests that include large attachment bodies. Servers SHOULD use 720 the "102 (Processing)" interim response defined in Section 10.1 of 721 [RFC2518] to keep the client connection alive if the final response 722 will take some time. 724 When exporting calendar data from a CalDAV server supporting managed 725 attachments, clients SHOULD remove all "MANAGED-ID" property 726 parameters from "ATTACH" properties in the calendar data. Similarly 727 when importing calendar data from another source, clients SHOULD 728 remove any "MANAGED-ID" property parameters on "ATTACH" properties 729 (failure to do so will likely result in the server removing those 730 properties automatically). 732 4. Modifications to iCalendar Syntax 734 4.1. SIZE Property Parameter 736 Parameter Name: SIZE 738 Purpose: To specify the size of an attachment. 740 Format Definition: This property parameter is defined by the 741 following notation: 743 sizeparam = "SIZE" "=" paramtext 744 ; positive integers 746 Description: This property parameter MAY be specified on "ATTACH" 747 properties. It indicates the size in octets of the corresponding 748 attachment data. Since iCalendar integer values are restricted to 749 a maximum value of 2147483647, the current parameter is defined as 750 text to allow an extended range to be used. 752 Example: 754 ATTACH;SIZE=1234:http://attachments.example.com/abcd.txt 756 4.2. FILENAME Property Parameter 758 Parameter Name: FILENAME 760 Purpose: To specify the file name of a managed attachment. 762 Format Definition: This property parameter is defined by the 763 following notation: 765 filenameparam = "FILENAME" "=" paramtext 767 Description: This property parameter MAY be specified on "ATTACH" 768 properties corresponding to managed attachments. Its value 769 provides information on how to construct a filename for storing 770 the attachment data. This parameter is very similar in nature to 771 the Content-Disposition HTTP header field "filename" parameter and 772 exposes the same security risks. As a consequence, clients MUST 773 follow the guidelines expressed in Section 4.3 of [RFC6266] when 774 consuming this parameter value. Similarly, servers MUST follow 775 those same guidelines before storing a value. 777 Example: 779 ATTACH;FILENAME=agenda.html:http://attachments.example.c 780 om/rt452S 782 4.3. MANAGED-ID Property Parameter 784 Parameter Name: MANAGED-ID 786 Purpose: To uniquely identify a managed attachment. 788 Format Definition: This property parameter is defined by the 789 following notation: 791 managedidparam = "MANAGED-ID" "=" paramtext 793 Description: This property parameter MUST be specified on "ATTACH" 794 properties corresponding to managed attachments. Its value is 795 generated by the server and uniquely identifies a managed 796 attachment. This property parameter MUST NOT be present in the 797 case of non-managed attachments. 799 Example: 801 ATTACH;MANAGED-ID=aUNhbGVuZGFy:http://attachments.example.c 802 om/abcd.txt 804 5. Additional Message Header Fields 806 5.1. Cal-Managed-ID Response Header Field 808 The Cal-Managed-ID response header field provides the value of the 809 MANAGED-ID parameter corresponding to a newly added ATTACH property. 810 It MUST be sent only in response to a successful POST request with an 811 action set to attachment-add or attachment-update. 813 Cal-Managed-ID = "Cal-Managed-ID" ":" paramtext 814 ; "paramtext" is defined in Section 3.1 of [RFC5545] 816 Example: 818 Cal-Managed-ID:aUNhbGVuZGFy 820 6. Additional WebDAV properties 822 6.1. CALDAV:managed-attachments-server-URL property 824 Name: managed-attachments-server-URL 826 Namespace: urn:ietf:params:xml:ns:caldav 828 Purpose: Specifies the server base URI to use when retrieving 829 managed attachments. 831 Protected: This property MUST be protected as only the server can 832 update the value. 834 COPY/MOVE behavior: This property is only defined on a calendar home 835 collection which cannot be moved or copied. 837 allprop behavior: SHOULD NOT be returned by a PROPFIND DAV:allprop 838 request. 840 Description: This property MAY be defined on a calendar home 841 collection. If present, it contains zero or one DAV:href XML 842 elements. 844 When one DAV:href element is present, its value MUST be an 845 absolute HTTP URI containing only the scheme (i.e. "https") and 846 authority (i.e. host and port) parts . Whenever a managed 847 attachment is to be retrieved via an HTTP GET, the client MUST 848 construct the actual URL of the attachment by substituting the 849 scheme and authority parts of the attachment URI (as stored in the 850 iCalendar "ATTACH" property) with the present WebDAV property 851 value. 853 When no DAV:href element is present, the client MUST substitute 854 the scheme and authority parts of the attachment URI with the 855 scheme and authority part of the calendar home collection absolute 856 URI. 858 In the absence of this property, the client can consider the 859 attachment URI as its actual URL. 861 Definition: 863 865 Example: 867As usual
1312 1313 1314 >> Response << 1316 HTTP/1.1 201 Created 1317 Content-Type: text/calendar; charset="utf-8" 1318 Content-Length: yyyy 1319 Content-Location: http://cal.example.com/events/65.ics 1320 ETag: "123456789-000-111" 1321 Cal-Managed-ID: 97S 1323 BEGIN:VCALENDAR 1324 VERSION:2.0 1325 PRODID:-//Example Corp.//CalDAV Server//EN 1326 BEGIN:VTIMEZONE 1327 LAST-MODIFIED:20040110T032845Z 1328 TZID:America/Montreal 1329 BEGIN:DAYLIGHT 1330 DTSTART:20000404T020000 1331 RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4 1332 TZNAME:EDT 1333 TZOFFSETFROM:-0500 1334 TZOFFSETTO:-0400 1335 END:DAYLIGHT 1336 BEGIN:STANDARD 1337 DTSTART:20001026T020000 1338 RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10 1339 TZNAME:EST 1340 TZOFFSETFROM:-0400 1341 TZOFFSETTO:-0500 1342 END:STANDARD 1343 END:VTIMEZONE 1344 BEGIN:VEVENT 1345 UID:20010712T182145Z-123401@example.com 1346 DTSTAMP:20120201T203412Z 1347 DTSTART;TZID=America/Montreal:20120206T100000 1348 DURATION:PT1H 1349 RRULE:FREQ=WEEKLY 1350 SUMMARY:Planning Meeting 1351 ORGANIZER:mailto:cyrus@example.com 1352 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:cyrus@exampl 1353 e.com 1354 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:arnaudq@exam 1355 ple.com 1356 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=NEEDS-ACTION:mailto:mike@exa 1357 mple.com 1358 ATTACH;MANAGED-ID=97S;FMTTYPE=text/html;SIZE=xxxx; 1359 FILENAME=agenda.html:https://cal.example.com/attach/65/34X22R 1360 END:VEVENT 1361 END:VCALENDAR 1362 The organizer has a more specific agenda for the 20th of February 1363 meeting. It is added to that particular instance of the meeting by 1364 specifying the rid parameter. 1366 >> Request << 1368 POST /events/65.ics?action=attachment-add&rid=20120220T100000 HTTP/1.1 1369 Host: cal.example.com 1370 Content-Type: text/html; charset="utf-8" 1371 Content-Disposition:attachment;filename=agenda0220.html 1372 Content-Length: xxxx 1373 Prefer: return=representation 1375 1376 1377Something different, for a change
1379 1380 1382 >> Response << 1384 HTTP/1.1 201 Created 1385 Content-Type: text/calendar; charset="utf-8" 1386 Content-Length: yyyy 1387 Content-Location: http://cal.example.com/events/65.ics 1388 ETag: "123456789-000-222" 1389 Cal-Managed-ID: 33225 1391 BEGIN:VCALENDAR 1392 VERSION:2.0 1393 PRODID:-//Example Corp.//CalDAV Server//EN 1394 BEGIN:VTIMEZONE 1395 LAST-MODIFIED:20040110T032845Z 1396 TZID:America/Montreal 1397 BEGIN:DAYLIGHT 1398 DTSTART:20000404T020000 1399 RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4 1400 TZNAME:EDT 1401 TZOFFSETFROM:-0500 1402 TZOFFSETTO:-0400 1403 END:DAYLIGHT 1404 BEGIN:STANDARD 1405 DTSTART:20001026T020000 1406 RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10 1407 TZNAME:EST 1408 TZOFFSETFROM:-0400 1409 TZOFFSETTO:-0500 1410 END:STANDARD 1411 END:VTIMEZONE 1412 BEGIN:VEVENT 1413 UID:20010712T182145Z-123401@example.com 1414 DTSTAMP:20120201T203412Z 1415 DTSTART;TZID=America/Montreal:20120206T100000 1416 DURATION:PT1H 1417 RRULE:FREQ=WEEKLY 1418 SUMMARY:Planning Meeting 1419 ORGANIZER:mailto:cyrus@example.com 1420 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:cyrus@exampl 1421 e.com 1422 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:arnaudq@exam 1423 ple.com 1424 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=NEEDS-ACTION:mailto:mike@exa 1425 mple.com 1426 ATTACH;MANAGED-ID=97S;FMTTYPE=text/html;SIZE=xxxx; 1427 FILENAME=agenda.html:https://cal.example.com/attach/65/34X22R 1428 END:VEVENT 1429 BEGIN:VEVENT 1430 UID:20010712T182145Z-123401@example.com 1431 RECURRENCE-ID;TZID=America/Montreal:20120220T100000 1432 DTSTAMP:20120201T203412Z 1433 DTSTART;TZID=America/Montreal:20120220T100000 1434 DURATION:PT1H 1435 SUMMARY:Planning Meeting 1436 ORGANIZER:mailto:cyrus@example.com 1437 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:cyrus@example. 1438 com 1439 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:arnaudq@exampl 1440 e.com 1441 ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=NEEDS-ACTION:mailto:mike@examp 1442 le.com 1443 ATTACH;MANAGED-ID=33225;FMTTYPE=text/html;SIZE=xxxx; 1444 FILENAME=agenda0220.html:https://cal.example.com/attach/65/FGZ225 1445 END:VEVENT 1446 END:VCALENDAR 1448 Authors' Addresses 1450 Cyrus Daboo 1451 Apple Inc. 1452 1 Infinite Loop 1453 Cupertino, CA 95014 1454 USA 1456 Email: cyrus@daboo.name 1457 URI: http://www.apple.com/ 1458 Arnaud Quillaud 1459 Oracle Corporation 1460 180, Avenue de l'Europe 1461 Saint Ismier cedex 38334 1462 France 1464 Email: arnaud.quillaud@oracle.com 1465 URI: http://www.oracle.com/ 1467 Kenneth Murchison (editor) 1468 Carnegie Mellon University 1469 5000 Forbes Avenue 1470 Pittsburgh, PA 15213 1471 USA 1473 Email: murch@andrew.cmu.edu 1474 URI: http://www.cmu.edu/