Calendar Server Extension C. Daboo Apple February 3, 2010 Private Calendar Components in CalDAV Abstract This document defines an extension to CalDAV that enables a client to mark events with an access classification (e.g., "private") so that other calendar users have restricted rights to view the data in the calendar component. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Conventions Used in This Document . . . . . . . . . . . . . . 2 3. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 2 4. New features . . . . . . . . . . . . . . . . . . . . . . . . . 3 4.1. iCalendar Changes . . . . . . . . . . . . . . . . . . . . 3 4.1.1. Changes to VCALENDAR Object . . . . . . . . . . . . . 3 4.1.2. Restricted Access Property . . . . . . . . . . . . . . 3 4.2. CalDAV Changes . . . . . . . . . . . . . . . . . . . . . . 4 4.2.1. OPTIONS Request . . . . . . . . . . . . . . . . . . . 4 4.2.1.1. Example: Using OPTIONS for the Discovery of Private Event Support . . . . . . . . . . . . . . 5 4.2.2. Data Restrictions . . . . . . . . . . . . . . . . . . 5 4.2.2.1. Changing the X-CALENDARSERVER-ACCESS value . . . . 5 4.2.2.2. X-CALENDARSERVER-ACCESS set to PUBLIC . . . . . . 5 4.2.2.3. X-CALENDARSERVER-ACCESS set to PRIVATE . . . . . . 5 4.2.2.4. X-CALENDARSERVER-ACCESS set to CONFIDENTIAL . . . 6 4.2.2.5. X-CALENDARSERVER-ACCESS set to RESTRICTED . . . . 6 4.2.3. Changes to WebDAV Privileges when X-CALENDARSERVER-ACCESS is used . . . . . . . . . . . 7 4.2.4. Summary of behavior . . . . . . . . . . . . . . . . . 8 4.2.5. CalDAV Scheduling . . . . . . . . . . . . . . . . . . 10 4.2.6. New pre-conditions for PUT . . . . . . . . . . . . . . 10 4.2.7. New pre-condition for POST . . . . . . . . . . . . . . 10 5. Security Considerations . . . . . . . . . . . . . . . . . . . 11 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 7. Normative References . . . . . . . . . . . . . . . . . . . . . 11 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 12 Appendix B. Change History . . . . . . . . . . . . . . . . . . . 12 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 13 Daboo [Page 1] CalDAV Private Calendar Components February 2010 1. Introduction Internet calendaring and scheduling standards are defined by iCalendar [RFC5545] and iTIP [RFC5546]. The CalDAV [RFC4791] standard defines a way to access calendar data stored on a server. CalDAV uses WebDAV ACLs [RFC3744] to allow a calendar user to grant rights to other users to see the calendar data stored on the server. This is an "all or nothing" behavior, i.e. if another user is granted the DAV:read privilege to a calendar component, then that user can read all the calendar data in the calendar resource stored on the server. It is often the case that a calendar user wants to give "restricted" access to portions of the calendar data. e.g., allow another calendar user to see only the start and end times of an event, but not other information (such as summary, description, location, attendee list etc). There is currently no way to do that with CalDAV. This specification defines a new iCalendar property that can be stored in a calendar component on the CalDAV server that triggers restricted access rights for other users., in addition to the standard rights granted by WebDAV ACLs. In some cases use of this property will result in the server implicitly changing the WebDAV ACLs granted by users. 2. Conventions Used in This Document The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. When XML element types in the namespaces "DAV:" and "urn:ietf:params:xml:ns:caldav" are referenced in this document outside of the context of an XML fragment, the string "DAV:" and "CALDAV:" will be prefixed to the element type names respectively. The namespace "http://calendarserver.org/ns/" is used for XML elements defined in this specification. When XML element types in this namespace are referenced in this document outside of the context of an XML fragment, the string "CS:" will be prefixed to the element type names respectively. 3. Open Issues Daboo [Page 2] CalDAV Private Calendar Components February 2010 1. None right now. 4. New features 4.1. iCalendar Changes This specification introduces a new iCalendar property "X-CALENDARSERVER-ACCESS" that can be used only as a property in a "VCALENDAR" object. 4.1.1. Changes to VCALENDAR Object The definition of the properties allowed in a "VCALENDAR" object is extended as follows: calprops /= ; 'access'is optional, ; but MUST NOT occur more than once access Note that the property is applied to the top-level "VCALENDAR" object which means that the access rights being set apply to the entire iCalendar object (and thus entire CalDAV resource) when stored on a CalDAV server. This specification does not define a way to restrict access on a per-component or per-instance basis within a single CalDAV calendar resource. 4.1.2. Restricted Access Property Property Name: X-CALENDARSERVER-ACCESS Purpose: The property is used to indicate restricted access rights to the iCalendar data. Value Type: TEXT Property Parameters: Non-standard property parameters can be specified on this property. Conformance: The property can be specified at most once in an iCalendar object. Description: The access property is used to restrict access to the calendar data when it is stored on a CalDAV server only. Note that this property has no meaning when used in other types of calendar Daboo [Page 3] CalDAV Private Calendar Components February 2010 store or when sent via an iTIP message. When used on a CalDAV server, the CalDAV server guarantees that the appropriate calendar data access restrictions are applied based on the value of this property. The access values are defined as follows: +--------------+----------------------------------------------------+ | Access Value | Description | +--------------+----------------------------------------------------+ | PUBLIC | All of the calendar data is visible. | | | | | PRIVATE | None of the calendar data is visible. | | | | | CONFIDENTIAL | Only start and end time of each instance is | | | visible. | | | | | RESTRICTED | Only start and end time, summary and location of | | | each instance is visible. | +--------------+----------------------------------------------------+ Format Definition: The property is defined by the following notation: access = "X-CALENDARSERVER-ACCESS" accessparam ":" accessvalue CRLF accessparam = *(";" xparam) accessvalue = "PUBLIC" / "PRIVATE" / "CONFIDENTIAL" / "RESTRICTED" / x-name ;Default is PUBLIC Example: The following is an example of this property: X-CALENDARSERVER-ACCESS:PRIVATE 4.2. CalDAV Changes 4.2.1. OPTIONS Request A server supporting the features described in this document MUST include "calendarserver-private-events" as a field in the DAV response header from an OPTIONS request on all calendar resources. A value of "calendarserver-private-events" in the DAV response header MUST indicate that the server supports all MUST level requirements specified in this document. Daboo [Page 4] CalDAV Private Calendar Components February 2010 4.2.1.1. Example: Using OPTIONS for the Discovery of Private Event Support >> Request << OPTIONS /home/cyrus/calendars/ HTTP/1.1 Host: cal.example.com >> Response << HTTP/1.1 200 OK Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE Allow: PROPFIND, PROPPATCH, LOCK, UNLOCK, REPORT, ACL DAV: 1, 2, access-control, calendar-access DAV: calendarserver-private-events Date: Sat, 11 Nov 2006 09:32:12 GMT Content-Length: 0 In this example, the OPTIONS method returns the value "calendarserver-private-events" in the DAV response header to indicate that the collection "/home/cyrus/calendars/" supports the behavior defined in this specification. 4.2.2. Data Restrictions The following restrictions on access to calendar data are applied when the "X-CALENDARSERVER-ACCESS" is present in a calendar resource. 4.2.2.1. Changing the X-CALENDARSERVER-ACCESS value Only the authorized principal identified by the DAV:owner property value on the calendar resource is allowed to store an iCalendar object with the "X-CALENDARSERVER-ACCESS" icalendar property value set to anything other than "PUBLIC". This ensures that a non-owner principal cannot "lock themselves out of" access to a calendar resource, with no way to undo their actions. 4.2.2.2. X-CALENDARSERVER-ACCESS set to PUBLIC There are no additional restrictions beyond normal WebDAV access control applied to the calendar resource for this access restriction. 4.2.2.3. X-CALENDARSERVER-ACCESS set to PRIVATE There are no additional restrictions beyond normal WebDAV access control applied to the calendar resource for this access restriction. Note that in this case the server will explicitly set WebDAV ACLs to prevent access to the data by any principal other than the one Daboo [Page 5] CalDAV Private Calendar Components February 2010 indicated in the DAV:owner property on the calendar resource. 4.2.2.4. X-CALENDARSERVER-ACCESS set to CONFIDENTIAL In addition to normal WebDAV access control, a calendar user authorized as a principal that is not the DAV:owner of the calendar resource can retrieve or match on only the following iCalendar properties (assuming these properties actually occur in the calendar object): +-----------+-------------------------------------------------------+ | Component | Allowed Properties | +-----------+-------------------------------------------------------+ | VCALENDAR | PRODID VERSION CALSCALE X-CALENDARSERVER-ACCESS | | | | | VEVENT | UID RECURRENCE-ID SEQUENCE DTSTAMP STATUS TRANSP | | | DTSTART DTEND DURATION RRULE RDATE EXDATE | | | | | VTODO | UID RECURRENCE-ID SEQUENCE DTSTAMP STATUS DTSTART | | | COMPLETED DUE DURATION RRULE RDATE EXDATE | | | | | VJOURNAL | UID RECURRENCE-ID SEQUENCE DTSTAMP STATUS DTSTART | | | RRULE RDATE EXDATE | | | | | VFREEBUSY | UID DTSTAMP DTSTART DTEND DURATION FREEBUSY | | | | | VTIMEZONE | All Properties | +-----------+-------------------------------------------------------+ In addition, VALARM components MUST NOT be returned. Note that retrieval of the iCalendar data applies to any method that can return iCalendar data. In particular, some CalDAV REPORTs are able to return iCalendar data, which MUST be restricted as above. In addition, the CALDAV:calendar-query REPORT allows for searching on iCalendar data. Searching MUST only match components, properties or parameters on properties that are listed above. 4.2.2.5. X-CALENDARSERVER-ACCESS set to RESTRICTED In addition to normal WebDAV access control, a calendar user authorized as a principal that is not the DAV:owner of the calendar resource can retrieve or match on only the following iCalendar properties (assuming these properties actually occur in the calendar object): Daboo [Page 6] CalDAV Private Calendar Components February 2010 +-----------+-------------------------------------------------------+ | Component | Allowed Properties | +-----------+-------------------------------------------------------+ | VCALENDAR | PRODID VERSION CALSCALE X-CALENDARSERVER-ACCESS | | | | | VEVENT | UID RECURRENCE-ID SEQUENCE DTSTAMP STATUS TRANSP | | | DTSTART DTEND DURATION RRULE RDATE EXDATE SUMMARY | | | LOCATION | | | | | VTODO | UID RECURRENCE-ID SEQUENCE DTSTAMP STATUS DTSTART | | | COMPLETED DUE DURATION RRULE RDATE EXDATE SUMMARY | | | LOCATION | | | | | VJOURNAL | UID RECURRENCE-ID SEQUENCE DTSTAMP STATUS DTSTART | | | RRULE RDATE EXDATE SUMMARY | | | | | VFREEBUSY | UID DTSTAMP DTSTART DTEND DURATION FREEBUSY | | | | | VTIMEZONE | All Properties | +-----------+-------------------------------------------------------+ In addition, VALARM components MUST NOT be returned. Note that retrieval of the iCalendar data applies to any method that can return iCalendar data. In particular, some CalDAV REPORTs are able to return iCalendar data, which MUST be restricted as above. In addition, the CALDAV:calendar-query REPORT allows for searching on iCalendar data. Searching MUST only match components, properties or parameters on properties that are listed above. 4.2.3. Changes to WebDAV Privileges when X-CALENDARSERVER-ACCESS is used When a CalDAV client stores a calendar resource on a CalDAV server, the CalDAV server MUST apply the following ACLs to the resource based on the "X-CALENDARSERVER-ACCESS" property in the calendar data. +--------------+----------------------------------------------------+ | Access Value | Applied Privileges | +--------------+----------------------------------------------------+ | PUBLIC | Normal privileges | | | | | PRIVATE | The DAV:read and DAV:write privileges MUST be | | | denied to all principals that are not the | | | DAV:owner. | | | | Daboo [Page 7] CalDAV Private Calendar Components February 2010 | CONFIDENTIAL | The DAV:write privilege MUST be denied to all | | | principals that are not the DAV:owner. | | | | | RESTRICTED | The DAV:write privilege MUST be denied to all | | | principals that are not the DAV:owner. | +--------------+----------------------------------------------------+ The server MUST examine the "X-CALENDARSERVER-ACCESS" property each time a calendar resource is stored and re-apply any WebDAV ACL restrictions based on the new value. 4.2.4. Summary of behavior For each value of "X-CALENDARSERVER-ACCESS" different effects occur based on the WebDAV request method used by a client. +--------------+-------------------+--------------------------------+ | Restriction | Method | Affect on non-owner principals | +--------------+-------------------+--------------------------------+ | PUBLIC | Any Method | Normal ACLs apply. | | | | | | PRIVATE | Any Method | As per Section 4.2.3 non-owner | | | | principals will have been | | | | denied access via WebDAV ACLs | | | | so will not be able to see the | | | | calendar resource or its data, | | | | or operate on it in any way. | | | | | | CONFIDENTIAL | GET | The data returned will be | | | | limited to only the calendar | | | | properties listed in | | | | Section 4.2.2.4. | | | PUT | As per Section 4.2.3, | | | | non-owner principals will not | | | | have the DAV:write privilege | | | | to the calendar resource so | | | | PUT is forbidden. | | | DELETE | Normal ACLs apply. | | | PROPFIND | Normal ACLs apply. | | | PROPPATCH | As per Section 4.2.3, | | | | non-owner principals will not | | | | have the DAV:write privilege | | | | to the calendar resource so | | | | PUT is forbidden. | Daboo [Page 8] CalDAV Private Calendar Components February 2010 | | REPORT - | Any CALDAV:calendar-data | | | calendar-multiget | returned in the XML response | | | | MUST be limited to only the | | | | calendar properties listed in | | | | Section 4.2.2.4. | | | REPORT - | Any CALDAV:calendar-data | | | calendar-query | returned in the XML response | | | | MUST be limited to only the | | | | calendar properties listed in | | | | Section 4.2.2.4. The server | | | | MUST not allow a query to | | | | match a calendar property that | | | | is not listed in | | | | Section 4.2.2.4. | | | REPORT - | Normal ACLs apply. | | | free-busy-query | | | | | | | RESTRICTED | GET | The data returned will be | | | | limited to only the calendar | | | | properties listed in | | | | Section 4.2.2.5. | | | PUT | As per Section 4.2.3, | | | | non-owner principals will not | | | | have the DAV:write privilege | | | | to the calendar resource so | | | | PUT is forbidden. | | | DELETE | Normal ACLs apply. | | | PROPFIND | Normal ACLs apply. | | | PROPPATCH | As per Section 4.2.3, | | | | non-owner principals will not | | | | have the DAV:write privilege | | | | to the calendar resource so | | | | PUT is forbidden. | | | REPORT - | Any CALDAV:calendar-data | | | calendar-multiget | returned in the XML response | | | | MUST be limited to only the | | | | calendar properties listed in | | | | Section 4.2.2.5. | | | REPORT - | Any CALDAV:calendar-data | | | calendar-query | returned in the XML response | | | | MUST be limited to only the | | | | calendar properties listed in | | | | Section 4.2.2.5. The server | | | | MUST not allow a query to | | | | match a calendar property that | | | | is not listed in | | | | Section 4.2.2.5. | Daboo [Page 9] CalDAV Private Calendar Components February 2010 | | REPORT - | Normal ACLs apply. | | | free-busy-query | | +--------------+-------------------+--------------------------------+ 4.2.5. CalDAV Scheduling When the CalDAV scheduling [I-D.desruisseaux-caldav-sched] feature is enabled on the CalDAV server, the following behavior is required: Clients MUST NOT include the "X-CALENDARSERVER-ACCESS" iCalendar property in any calendar objects used in an HTTP POST request against a calendaring Outbox collection. Servers MUST fail an HTTP POST request on a calendar Outbox collection where the calendar data contains an "X-CALENDARSERVER- ACCESS" iCalendar property. 4.2.6. New pre-conditions for PUT The following pre-conditions for a PUT request against a calendar resource are defined: (CS:valid-access-restriction-change):Only the DAV:owner principal is allowed to store a calendar resource where the calendar data contains an "X-CALENDARSERVER-ACCESS" property with a value other than "PUBLIC". (CS:valid-access-restriction):The "X-CALENDARSERVER-ACCESS" property value in the iCalendar data in the request body has to be a value recognized by the server. If these pre-conditions are violated the server MUST return a DAV: error response with the appropriate XML element indicating the pre- condition being violated in the response to the PUT request. 4.2.7. New pre-condition for POST The following pre-conditions for a POST request against a calendar Outbox collection are defined: (CS:no-access-restrictions):iCalendar data sent in a POST request on a calendar Outbox collection MUST NOT contain a "X-CALENDARSERVER-ACCESS" iCalendar property. If these pre-conditions are violated the server MUST return a DAV: error response with the appropriate XML element indicating the pre- condition being violated in the response to the PUT request. Daboo [Page 10] CalDAV Private Calendar Components February 2010 5. Security Considerations It is not possible to have private events in a calendar Inbox collection as the "X-CALENDARSERVER-ACCESS" iCalendar property cannot be used in an iTIP message sent via CalDAV scheduling. As a result, any one with read access to the calendar Inbox collection will be able to see all the calendar data in any calendar resource in that collection. This specification leaves open the possibility of having additional standard or non-standard values for the "X-CALENDARSERVER-ACCESS" iCalendar property. This possibility requires special attention by servers and clients, as detailed below: o Servers MUST reject any iCalendar component with an "X-CALENDARSERVER-ACCESS" property value that is not recognized. o Clients MUST accept and preserve any "X-CALENDARSERVER-ACCESS" property values in iCalendar data. In the case of a value that the client does not recognize, the following actions can be taken: * Present the access state to the user in an "indeterminate" state and allow them to change it to any of the values known to the client. However, if the user chooses not to change it, the original value MUST be preserved. * Treat the unknown value as "PUBLIC". The access restrictions defined here are dependent on the value of the DAV:owner property on a calendar resource. Servers MUST ensure that this property value cannot be changed by unauthorized users. Ideally it could be treated as a "live" property whose value can never be changed via WebDAV protocol. 6. IANA Considerations This document does not require any actions on the part of IANA. 7. Normative References [I-D.desruisseaux-caldav-sched] Daboo, C. and B. Desruisseaux, "CalDAV Scheduling Extensions to WebDAV", draft-desruisseaux-caldav-sched-08 (work in progress), August 2009. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Daboo [Page 11] CalDAV Private Calendar Components February 2010 Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC3744] Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, "Web Distributed Authoring and Versioning (WebDAV) Access Control Protocol", RFC 3744, May 2004. [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, March 2007. [RFC5545] Desruisseaux, B., "Internet Calendaring and Scheduling Core Object Specification (iCalendar)", RFC 5545, September 2009. [RFC5546] Daboo, C., "iCalendar Transport-Independent Interoperability Protocol (iTIP)", RFC 5546, December 2009. Appendix A. Acknowledgments This specification is the result of discussions between the Apple calendar server and client teams. Also thanks to Filip Navara for comments. Appendix B. Change History Changes since -01 1. Fixed typo. 2. Updated to new 5545 and 5546 specs. Changes since -00 1. Added security text on how to deal with unrecognized values. 2. Make explicit use of DAV:owner property. 3. Added comment on keeping DAV:owner value secure. 4. Added text about who is allowed to change the property value. 5. Added new pre-conditions for PUT & POST. Daboo [Page 12] CalDAV Private Calendar Components February 2010 Author's Address Cyrus Daboo Apple Inc. 1 Infinite Loop Cupertino, CA 95014 USA Email: cyrus@daboo.name URI: http://www.apple.com/ Daboo [Page 13]