Tech-invite3GPPspaceIETF RFCsSIP
929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 8607

Calendaring Extensions to WebDAV (CalDAV): Managed Attachments

Pages: 34
Informational
Part 2 of 2 – Pages 19 to 34
First   Prev   None

Top   ToC   RFC8607 - Page 19   prevText

4. Modifications to iCalendar Syntax

4.1. SIZE Property Parameter

Parameter Name: SIZE Purpose: To specify the size of an attachment. Format Definition: This property parameter is defined by the following notation: sizeparam = "SIZE" "=" paramtext ; positive integers Description: This property parameter MAY be specified on "ATTACH" properties. It indicates the size in octets of the corresponding attachment data. Since iCalendar integer values are restricted to a maximum value of 2147483647, the current property parameter is defined as text to allow an extended range to be used. Example: ATTACH;SIZE=1234:https://attachments.example.com/abcd.txt

4.2. FILENAME Property Parameter

Parameter Name: FILENAME Purpose: To specify the filename of a managed attachment. Format Definition: This property parameter is defined by the following notation: filenameparam = "FILENAME" "=" paramtext Description: This property parameter MAY be specified on "ATTACH" properties corresponding to managed attachments. Its value provides information on how to construct a filename for storing the attachment data. This parameter is very similar in nature to the Content-Disposition header field "filename" parameter and exposes the same security risks. As a consequence, clients MUST follow the guidelines expressed in Section 4.3 of [RFC6266] when consuming this property parameter value. Similarly, servers MUST follow those same guidelines before storing a value.
Top   ToC   RFC8607 - Page 20
   Example:

      ATTACH;FILENAME=agenda.html:
       https://attachments.example.com/rt452S

4.3. MANAGED-ID Property Parameter

Parameter Name: MANAGED-ID Purpose: To uniquely identify a managed attachment. Format Definition: This property parameter is defined by the following notation: managedidparam = "MANAGED-ID" "=" paramtext Description: This property parameter MUST be specified on "ATTACH" properties corresponding to managed attachments. Its value is generated by the server and uniquely identifies a managed attachment within the scope of the CalDAV server. This property parameter MUST NOT be present in the case of unmanaged attachments. Example: ATTACH;MANAGED-ID=aUNhbGVuZGFy: https://attachments.example.com/abcd.txt

5. Additional Message Header Fields

5.1. Cal-Managed-ID Response Header Field

The Cal-Managed-ID response header field provides the value of the "MANAGED-ID" property parameter corresponding to a newly added "ATTACH" property. ABNF: Cal-Managed-ID = "Cal-Managed-ID" ":" paramtext ; "paramtext" is defined in Section 3.1 of [RFC5545] Example: Cal-Managed-ID:aUNhbGVuZGFy
Top   ToC   RFC8607 - Page 21
   The Cal-Managed-ID header field MUST only be sent by an origin server
   in response to a successful POST request with an "action" query
   parameter set to "attachment-add" or "attachment-update".  It MUST
   only appear once in a response and MUST NOT appear in trailers.

   The Cal-Managed-ID header field is end to end and MUST be forwarded
   by intermediaries.  Intermediaries MUST NOT insert, delete, or modify
   a Cal-Managed-ID header field.

6. Additional WebDAV Properties

6.1. CALDAV:managed-attachments-server-URL Property

Name: managed-attachments-server-URL Namespace: urn:ietf:params:xml:ns:caldav Purpose: This property specifies the server base URI to use when retrieving managed attachments. Protected: This property MUST be protected as only the server can update the value. COPY/MOVE behavior: This property is only defined on a calendar home collection, which cannot be moved or copied. allprop behavior: This property SHOULD NOT be returned by a PROPFIND DAV:allprop request. Description: This property MAY be defined on a calendar home collection. If present, it contains either a single DAV:href XML element or none at all. When one DAV:href element is present, its value MUST be an absolute HTTP URI containing only the scheme (i.e., "https") and authority (i.e., host and port) parts. Whenever a managed attachment is to be retrieved via an HTTP GET, the client MUST construct the actual URL of the attachment by substituting the scheme and authority parts of the attachment URI (as stored in the iCalendar "ATTACH" property) with the present WebDAV property value. When no DAV:href element is present, the client MUST substitute the scheme and authority parts of the attachment URI with the scheme and authority part of the calendar home collection absolute URI.
Top   ToC   RFC8607 - Page 22
      In the absence of this property, the client can consider the
      attachment URI as its actual URL.

   Definition:

   <!ELEMENT managed-attachments-server-URL (DAV:href?)>

   Example:

   <C:managed-attachments-server-URL xmlns:D="DAV:"
       xmlns:C="urn:ietf:params:xml:ns:caldav">
     <D:href>https://attachstore.example.com</D:href>
   </C:managed-attachments-server-URL>

6.2. CALDAV:max-attachment-size Property

Name: max-attachment-size Namespace: urn:ietf:params:xml:ns:caldav Purpose: This property provides a numeric value indicating the maximum attachment size, in octets, that the server is willing to accept when a managed attachment is stored on the server. Protected: This property MUST be protected as it indicates limits provided by the server. COPY/MOVE behavior: This property value MUST be preserved in COPY and MOVE operations. allprop behavior: This property SHOULD NOT be returned by a PROPFIND DAV:allprop request. Description: The "CALDAV:max-attachment-size" property is used to specify a numeric value that represents the maximum attachment size, in octets, that the server is willing to accept when a managed attachment is stored on the server. The property is defined on the parent collection of the calendar object resource to which the attachment is associated. Any attempt to store a managed attachment exceeding this size MUST result in an error, with the CALDAV:max-attachment-size precondition (Section 3.11) being violated. In the absence of this property, the client can assume that the server will allow storing an attachment of any reasonable size.
Top   ToC   RFC8607 - Page 23
   Definition:

   <!ELEMENT max-attachment-size (#PCDATA)>
   <!-- PCDATA value: a numeric value (positive decimal integer) -->

   Example:

   <C:max-attachment-size xmlns:C="urn:ietf:params:xml:ns:caldav"
        >102400000</C:max-attachment-size>

6.3. CALDAV:max-attachments-per-resource Property

Name: max-attachments-per-resource Namespace: urn:ietf:params:xml:ns:caldav Purpose: This property provides a numeric value indicating the maximum number of managed attachments across all instances of a calendar object resource stored in a calendar collection. Protected: This property MUST be protected as it indicates limits provided by the server. COPY/MOVE behavior: This property value MUST be preserved in COPY and MOVE operations. allprop behavior: This property SHOULD NOT be returned by a PROPFIND DAV:allprop request. Description: The "CALDAV:max-attachments-per-resource" property is used to specify a numeric value that represents the maximum number of managed attachments across all instances of a calendar object resource stored in a calendar collection. Unmanaged attachments are not counted toward that limit. The property is defined on the parent collection of the calendar object resource to which the attachment is associated. Any attempt to add a managed attachment that would cause the calendar resource to exceed this limit MUST result in an error, with the CALDAV:max-attachments-per-resource precondition (Section 3.11) being violated. In the absence of this property, the client can assume that the server can handle any number of managed attachments per calendar resource. Definition: <!ELEMENT max-attachments-per-resource (#PCDATA)> <!-- PCDATA value: a numeric value (positive decimal integer) -->
Top   ToC   RFC8607 - Page 24
   Example:

   <C:max-attachments-per-resource
       xmlns:C="urn:ietf:params:xml:ns:caldav"
        >12</C:max-attachments-per-resource>

7. Security Considerations

The security considerations in [RFC4791] and [RFC4918] apply to this extension. Additionally, servers need to be aware that a client could attack underlying storage by POSTing extremely large attachments and could attack processing time by uploading a recurring event with a large number of overrides and then repeatedly adding, updating, and deleting attachments. Malicious content could be introduced into the calendar server by way of a managed attachment, and propagated to many end users via scheduling. Servers SHOULD check managed attachments for malicious or inappropriate content. Upon detecting such content, servers SHOULD remove the attachment following the rules described in Section 3.12.5.

8. IANA Considerations

8.1. Parameter Registrations

This specification defines the following new iCalendar property parameters to be added to the "Parameters" registry defined in Section 8.2.4 of [RFC5545]: +------------+---------+-----------------------+ | Parameter | Status | Reference | +------------+---------+-----------------------+ | SIZE | Current | RFC 8607, Section 4.1 | | FILENAME | Current | RFC 8607, Section 4.2 | | MANAGED-ID | Current | RFC 8607, Section 4.3 | +------------+---------+-----------------------+
Top   ToC   RFC8607 - Page 25

8.2. Message Header Field Registrations

The message header fields below should be added to the "Permanent Message Header Field Names" registry (see [RFC3864]).

8.2.1. Cal-Managed-ID

Header field name: Cal-Managed-ID Protocol: http Status: standard Author/Change controller: IETF Reference: this specification (Section 5.1) Related information: none

9. References

9.1. Normative References

[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>. [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D. Jensen, "HTTP Extensions for Distributed Authoring -- WEBDAV", RFC 2518, DOI 10.17487/RFC2518, February 1999, <https://www.rfc-editor.org/info/rfc2518>. [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration Procedures for Message Header Fields", BCP 90, RFC 3864, DOI 10.17487/RFC3864, September 2004, <https://www.rfc-editor.org/info/rfc3864>. [RFC4331] Korver, B. and L. Dusseault, "Quota and Size Properties for Distributed Authoring and Versioning (DAV) Collections", RFC 4331, DOI 10.17487/RFC4331, February 2006, <https://www.rfc-editor.org/info/rfc4331>. [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, DOI 10.17487/RFC4791, March 2007, <https://www.rfc-editor.org/info/rfc4791>.
Top   ToC   RFC8607 - Page 26
   [RFC4918]  Dusseault, L., Ed., "HTTP Extensions for Web Distributed
              Authoring and Versioning (WebDAV)", RFC 4918,
              DOI 10.17487/RFC4918, June 2007,
              <https://www.rfc-editor.org/info/rfc4918>.

   [RFC5234]  Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
              Specifications: ABNF", STD 68, RFC 5234,
              DOI 10.17487/RFC5234, January 2008,
              <https://www.rfc-editor.org/info/rfc5234>.

   [RFC5545]  Desruisseaux, B., Ed., "Internet Calendaring and
              Scheduling Core Object Specification (iCalendar)",
              RFC 5545, DOI 10.17487/RFC5545, September 2009,
              <https://www.rfc-editor.org/info/rfc5545>.

   [RFC6266]  Reschke, J., "Use of the Content-Disposition Header Field
              in the Hypertext Transfer Protocol (HTTP)", RFC 6266,
              DOI 10.17487/RFC6266, June 2011,
              <https://www.rfc-editor.org/info/rfc6266>.

   [RFC6638]  Daboo, C. and B. Desruisseaux, "Scheduling Extensions to
              CalDAV", RFC 6638, DOI 10.17487/RFC6638, June 2012,
              <https://www.rfc-editor.org/info/rfc6638>.

   [RFC7230]  Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
              Protocol (HTTP/1.1): Message Syntax and Routing",
              RFC 7230, DOI 10.17487/RFC7230, June 2014,
              <https://www.rfc-editor.org/info/rfc7230>.

   [RFC7231]  Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
              Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
              DOI 10.17487/RFC7231, June 2014,
              <https://www.rfc-editor.org/info/rfc7231>.

   [RFC7240]  Snell, J., "Prefer Header for HTTP", RFC 7240,
              DOI 10.17487/RFC7240, June 2014,
              <https://www.rfc-editor.org/info/rfc7240>.

   [RFC7538]  Reschke, J., "The Hypertext Transfer Protocol Status Code
              308 (Permanent Redirect)", RFC 7538, DOI 10.17487/RFC7538,
              April 2015, <https://www.rfc-editor.org/info/rfc7538>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/info/rfc8174>.
Top   ToC   RFC8607 - Page 27

9.2. Informative References

[RFC5023] Gregorio, J., Ed. and B. de hOra, Ed., "The Atom Publishing Protocol", RFC 5023, DOI 10.17487/RFC5023, October 2007, <https://www.rfc-editor.org/info/rfc5023>. [RFC5546] Daboo, C., Ed., "iCalendar Transport-Independent Interoperability Protocol (iTIP)", RFC 5546, DOI 10.17487/RFC5546, December 2009, <https://www.rfc-editor.org/info/rfc5546>. [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, RFC 7320, DOI 10.17487/RFC7320, July 2014, <https://www.rfc-editor.org/info/rfc7320>. [RFC8144] Murchison, K., "Use of the Prefer Header Field in Web Distributed Authoring and Versioning (WebDAV)", RFC 8144, DOI 10.17487/RFC8144, April 2017, <https://www.rfc-editor.org/info/rfc8144>.
Top   ToC   RFC8607 - Page 28

Appendix A. Example Involving Recurring Events

In the following example, the organizer of a recurring meeting makes an unsuccessful attempt to add an agenda (HTML attachment) to the corresponding calendar resource with a conditional request. Note that the client includes both the Expect and Prefer header fields in the request, thereby preventing itself from needlessly sending the attachment data and requesting that the current resource be returned in the failure response (see Section 3.2 of [RFC8144]). >> Request << POST /events/65.ics?action=attachment-add HTTP/1.1 Host: cal.example.com Content-Type: text/html; charset="utf-8" Content-Disposition: attachment;filename=agenda.html Content-Length: 80 If-Match: "abcdefg-000" Expect: 100-continue Prefer: return=representation
Top   ToC   RFC8607 - Page 29
   >> Final Response <<

   HTTP/1.1 412 Precondition Failed
   Content-Type: text/calendar; charset="utf-8"
   Content-Length: 929
   Content-Location: https://cal.example.com/events/65.ics
   ETag: "123456789-000-000"

   BEGIN:VCALENDAR
   VERSION:2.0
   PRODID:-//Example Corp.//CalDAV Server//EN
   BEGIN:VTIMEZONE
   LAST-MODIFIED:20040110T032845Z
   TZID:America/Montreal
   BEGIN:DAYLIGHT
   DTSTART:20000404T020000
   RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4
   TZNAME:EDT
   TZOFFSETFROM:-0500
   TZOFFSETTO:-0400
   END:DAYLIGHT
   BEGIN:STANDARD
   DTSTART:20001026T020000
   RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10
   TZNAME:EST
   TZOFFSETFROM:-0400
   TZOFFSETTO:-0500
   END:STANDARD
   END:VTIMEZONE
   BEGIN:VEVENT
   UID:20010712T182145Z-123401@example.com
   DTSTAMP:20120201T203412Z
   DTSTART;TZID=America/Montreal:20120206T100000
   DURATION:PT1H
   RRULE:FREQ=WEEKLY
   SUMMARY:Planning Meeting
   ORGANIZER:mailto:cyrus@example.com
   ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:cyrus@exampl
    e.com
   ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:arnaudq@exam
    ple.com
   ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=NEEDS-ACTION:mailto:mike@exa
    mple.com
   END:VEVENT
   END:VCALENDAR
Top   ToC   RFC8607 - Page 30
   The organizer of a recurring meeting successfully adds an agenda
   (HTML attachment) to the corresponding calendar resource.  Attendees
   of the meeting are granted read access to the newly created
   attachment resource.  Their own copy of the meeting is updated to
   include the new "ATTACH" property pointing to the attachment
   resource, and they are notified of the change via their scheduling
   inbox.

   >> Request <<

   POST /events/65.ics?action=attachment-add HTTP/1.1
   Host: cal.example.com
   Content-Type: text/html; charset="utf-8"
   Content-Disposition: attachment;filename=agenda.html
   Content-Length: 80
   If-Match: "123456789-000-000"
   Expect: 100-continue
   Prefer: return=representation


   >> Interim Response <<

   HTTP/1.1 100 Continue


   >> Request Body <<

   <html>
     <body>
       <h1>Agenda</h1>
       <p>As usual</p>
     </body>
   </html>
Top   ToC   RFC8607 - Page 31
   >> Final Response <<

   HTTP/1.1 201 Created
   Content-Type: text/calendar; charset="utf-8"
   Content-Length: 1043
   Content-Location: https://cal.example.com/events/65.ics
   ETag: "123456789-000-111"
   Cal-Managed-ID: 97S

   BEGIN:VCALENDAR
   VERSION:2.0
   PRODID:-//Example Corp.//CalDAV Server//EN
   BEGIN:VTIMEZONE
   LAST-MODIFIED:20040110T032845Z
   TZID:America/Montreal
   BEGIN:DAYLIGHT
   DTSTART:20000404T020000
   RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4
   TZNAME:EDT
   TZOFFSETFROM:-0500
   TZOFFSETTO:-0400
   END:DAYLIGHT
   BEGIN:STANDARD
   DTSTART:20001026T020000
   RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10
   TZNAME:EST
   TZOFFSETFROM:-0400
   TZOFFSETTO:-0500
   END:STANDARD
   END:VTIMEZONE
   BEGIN:VEVENT
   UID:20010712T182145Z-123401@example.com
   DTSTAMP:20120201T203412Z
   DTSTART;TZID=America/Montreal:20120206T100000
   DURATION:PT1H
   RRULE:FREQ=WEEKLY
   SUMMARY:Planning Meeting
   ORGANIZER:mailto:cyrus@example.com
   ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:cyrus@exampl
    e.com
   ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:arnaudq@exam
    ple.com
   ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=NEEDS-ACTION:mailto:mike@exa
    mple.com
   ATTACH;MANAGED-ID=97S;FMTTYPE=text/html;SIZE=80;
    FILENAME=agenda.html:https://cal.example.com/attach/65/34X22R
   END:VEVENT
   END:VCALENDAR
Top   ToC   RFC8607 - Page 32
   The organizer has a more specific agenda for the 20th of February
   meeting.  It is added to that particular instance of the meeting by
   specifying the "rid" query parameter.  Note that an overridden
   instance is created with the "RECURRENCE-ID" property value matching
   the value of the "rid" query parameter in the request.  Also, note
   that the server takes significant time to complete the request and
   notifies the client accordingly.

   >> Request <<

  POST /events/65.ics?action=attachment-add&rid=20120220T100000 HTTP/1.1
  Host: cal.example.com
  Content-Type: text/html; charset="utf-8"
  Content-Disposition: attachment;filename=agenda0220.html
  Content-Length: 105
  If-Match: "123456789-000-111"
  Expect: 100-continue
  Prefer: return=representation


   >> Interim Response <<

   HTTP/1.1 100 Continue


   >> Request Body <<

   <html>
     <body>
       <h1>Agenda</h1>
       <p>Something different, for a change</p>
     </body>
   </html>


   >> Interim Response <<

   HTTP/1.1 102 Processing


   >> Final Response <<

   HTTP/1.1 201 Created
   Content-Type: text/calendar; charset="utf-8"
   Content-Length: 1661
   Content-Location: https://cal.example.com/events/65.ics
   ETag: "123456789-000-222"
   Cal-Managed-ID: 33225
Top   ToC   RFC8607 - Page 33
   BEGIN:VCALENDAR
   VERSION:2.0
   PRODID:-//Example Corp.//CalDAV Server//EN
   BEGIN:VTIMEZONE
   LAST-MODIFIED:20040110T032845Z
   TZID:America/Montreal
   BEGIN:DAYLIGHT
   DTSTART:20000404T020000
   RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4
   TZNAME:EDT
   TZOFFSETFROM:-0500
   TZOFFSETTO:-0400
   END:DAYLIGHT
   BEGIN:STANDARD
   DTSTART:20001026T020000
   RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10
   TZNAME:EST
   TZOFFSETFROM:-0400
   TZOFFSETTO:-0500
   END:STANDARD
   END:VTIMEZONE
   BEGIN:VEVENT
   UID:20010712T182145Z-123401@example.com
   DTSTAMP:20120201T203412Z
   DTSTART;TZID=America/Montreal:20120206T100000
   DURATION:PT1H
   RRULE:FREQ=WEEKLY
   SUMMARY:Planning Meeting
   ORGANIZER:mailto:cyrus@example.com
   ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:cyrus@exampl
    e.com
   ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:arnaudq@exam
    ple.com
   ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=NEEDS-ACTION:mailto:mike@exa
    mple.com
   ATTACH;MANAGED-ID=97S;FMTTYPE=text/html;SIZE=80;
    FILENAME=agenda.html:https://cal.example.com/attach/65/34X22R
   END:VEVENT
   BEGIN:VEVENT
   UID:20010712T182145Z-123401@example.com
   RECURRENCE-ID;TZID=America/Montreal:20120220T100000
   DTSTAMP:20120201T203412Z
   DTSTART;TZID=America/Montreal:20120220T100000
   DURATION:PT1H
   SUMMARY:Planning Meeting
   ORGANIZER:mailto:cyrus@example.com
   ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:cyrus@example.
    com
Top   ToC   RFC8607 - Page 34
   ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:arnaudq@exampl
    e.com
   ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=NEEDS-ACTION:mailto:mike@examp
    le.com
   ATTACH;MANAGED-ID=33225;FMTTYPE=text/html;SIZE=105;
    FILENAME=agenda0220.html:https://cal.example.com/attach/65/FGZ225
   END:VEVENT
   END:VCALENDAR

Acknowledgments

This specification came about via discussions at the Calendaring and Scheduling Consortium. Thanks in particular to Mike Douglass and Eric York.

Authors' Addresses

Cyrus Daboo Apple Inc. 1 Infinite Loop Cupertino, CA 95014 United States of America Email: cyrus@daboo.name URI: http://www.apple.com/ Arnaud Quillaud Oracle Corporation 180, Avenue de l'Europe Saint Ismier cedex 38334 France Email: arnaud.quillaud@oracle.com URI: http://www.oracle.com/ Kenneth Murchison (editor) FastMail US LLC 1429 Walnut St, Suite 1201 Philadephia, PA 19102 United States of America Email: murch@fastmailteam.com URI: http://www.fastmail.com/