[CalendarServer-changes] [2176] CalendarServer/trunk/doc/Extensions
source_changes at macosforge.org
source_changes at macosforge.org
Fri Feb 22 20:20:49 PST 2008
Revision: 2176
http://trac.macosforge.org/projects/calendarserver/changeset/2176
Author: cdaboo at apple.com
Date: 2008-02-22 20:20:49 -0800 (Fri, 22 Feb 2008)
Log Message:
-----------
Added XML versions of the files. Removed the resync extension as no one is interested in this.
Added Paths:
-----------
CalendarServer/trunk/doc/Extensions/caldav-ctag.txt
CalendarServer/trunk/doc/Extensions/caldav-ctag.xml
CalendarServer/trunk/doc/Extensions/caldav-proxy.txt
CalendarServer/trunk/doc/Extensions/caldav-proxy.xml
CalendarServer/trunk/doc/Extensions/icalendar-maskuids.xml
Removed Paths:
-------------
CalendarServer/trunk/doc/Extensions/caldav-ctag-02.txt
CalendarServer/trunk/doc/Extensions/caldav-proxy-02.txt
CalendarServer/trunk/doc/Extensions/caldav-resync-02.txt
Deleted: CalendarServer/trunk/doc/Extensions/caldav-ctag-02.txt
===================================================================
--- CalendarServer/trunk/doc/Extensions/caldav-ctag-02.txt 2008-02-22 05:07:34 UTC (rev 2175)
+++ CalendarServer/trunk/doc/Extensions/caldav-ctag-02.txt 2008-02-23 04:20:49 UTC (rev 2176)
@@ -1,336 +0,0 @@
-
-
-
-Calendar Server Extension C. Daboo
- Apple
- May 3, 2007
-
-
- Calendar Collection Entity Tag (CTag) in CalDAV
- caldav-ctag-02
-
-Abstract
-
- This specification defines an extension to CalDAV that provides a
- fast way for a client to determine whether the contents of a calendar
- collection may have changed.
-
-
-Table of Contents
-
- 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
- 2. Conventions Used in This Document . . . . . . . . . . . . . . . 2
- 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
- 3.1. Server . . . . . . . . . . . . . . . . . . . . . . . . . . 3
- 3.2. Client . . . . . . . . . . . . . . . . . . . . . . . . . . 3
- 4. New features in CalDAV . . . . . . . . . . . . . . . . . . . . 3
- 4.1. getctag WebDAV Property . . . . . . . . . . . . . . . . . . 4
- 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 4
- 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 5
- 7. Normative References . . . . . . . . . . . . . . . . . . . . . 5
- Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 5
- Appendix B. Change History . . . . . . . . . . . . . . . . . . . . 5
- Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 6
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Daboo [Page 1]
-
- CalDAV Proxy May 2007
-
-
-1. Introduction
-
- In CalDAV [RFC4791] calendar data is stored in calendar collection
- resources. Clients need to "poll" calendar collections in order to
- find out what has changed since the last time they examined it.
- Currently that involves having to do a PROPFIND Depth:1 HTTP request,
- or a CALDAV:calendar-query REPORT request. When a calendar
- collection contains a large number of calendar resources those
- operations become expensive on the server.
-
- Calendar users often configure their clients to poll at short time
- intervals. So polling traffic to the server will be high, even
- though the frequency at which changes actually occur to a calendar is
- typically low.
-
- To improve on performance, this specification defines a new "calendar
- collection entity tag" (CTag) WebDAV property that is defined on
- calendar collections. When the calendar collection changes, the CTag
- value changes. Thus a client can cache the CTag at some point in
- time, then poll the collection only (i.e. PROPFIND Depth:0 HTTP
- requests) and determine if a change has happened based on the
- returned CTag value. If there is a change, it can then fall back to
- doing the full (Depth:1) poll of the collection to actually determine
- which resources in the collection changed.
-
- This extension also defines CTag's on CalDAV scheduling
- [I-D.desruisseaux-caldav-sched] Inbox and Outbox collections.
-
-
-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.
-
-
-
-
-
-
-Daboo [Page 2]
-
- CalDAV Proxy May 2007
-
-
-3. Overview
-
-3.1. Server
-
- For each calendar or scheduling Inbox or Outbox collection on the
- server, a new CS:getctag WebDAV property is present.
-
- The property value is an "opaque" token whose value is guaranteed to
- be unique over the lifetime of any calendar or scheduling Inbox or
- Outbox collection at a specific URI.
-
- Whenever a calendar resource is added to, modified or deleted from
- the calendar collection, the value of the CS:getctag property MUST
- change. Typically this change will occur when the DAV:getetag
- property on a child resource changes due to some protocol action. It
- could be the result of a change to the body or properties of the
- resource.
-
-3.2. Client
-
- The client starts off with an empty string as the initial value for
- the cached CTag of a calendar or scheduling Inbox or Outbox
- collection that it intends to synchronize with.
-
- When polling a calendar or scheduling Inbox or Outbox collection, the
- client issues a PROPFIND Depth:0 HTTP request, asking for the CS:
- getctag property to be returned.
-
- If the returned value of CS:getctag property matches the one
- currently cached for the calendar or scheduling Inbox or Outbox
- collection, then the collection contents have not changed and no
- further action is required until the next poll.
-
- If the returned value of CS:getctag property does not match the one
- found previously, then the contents of the calendar or scheduling
- Inbox or Outbox collection have changed. At that point the client
- should re-issue the PROPFIND Depth:1 request to get the collection
- changes in detail and the CS:getctag property value corresponding to
- the new state. The new CSgetctag property value should replace the
- one currently cached for that calendar or scheduling Inbox or Outbox
- collection.
-
-
-4. New features in CalDAV
-
-
-
-
-
-
-
-Daboo [Page 3]
-
- CalDAV Proxy May 2007
-
-
-4.1. getctag WebDAV Property
-
- Name: getctag
-
- Namespace: http://calendarserver.org/ns/
-
- Purpose: Specifies a "synchronization" token used to indicate when
- the contents of a calendar or scheduling Inbox or Outbox
- collection have changed.
-
- Conformance: This property MUST be defined on a calendar or
- scheduling Inbox or Outbox collection resource. It MUST be
- protected and SHOULD be returned by a PROPFIND DAV:allprop request
- (as defined in Section 12.14.1 of [RFC2518]).
-
- Description: The CS:getctag property allows clients to quickly
- determine if the contents of a calendar or scheduling Inbox or
- Outbox collection have changed since the last time a
- "synchronization" operation was done. The CS:getctag property
- value MUST change each time the contents of the calendar or
- scheduling Inbox or Outbox collection change, and each change MUST
- result in a value that is different from any other used with that
- collection URI.
-
- Definition:
-
- <!ELEMENT getctag #PCDATA>
-
- Example:
-
- <T:getctag xmlns:T="http://calendarserver.org/ns/"
- >ABCD-GUID-IN-THIS-COLLECTION-20070228T122324010340</T:getctag>
-
-
-5. Security Considerations
-
- The CS:getctag property value changes whenever any resource in the
- collection or scheduling Inbox or Outbox changes. Thus a change to a
- resource that a user does not have read access to will result in a
- change in the CTag and the user will know that a change occurred.
- However, that user will not able to get additional details about
- exactly what changed as WebDAV ACLs [RFC3744] will prevent that. So
- this does expose the fact that there are potentially "hidden"
- resources in a calendar collection, but it does not expose any
- details about them.
-
-
-
-
-
-
-Daboo [Page 4]
-
- CalDAV Proxy May 2007
-
-
-6. IANA Considerations
-
- This document does not require any actions on the part of IANA.
-
-
-7. Normative References
-
- [I-D.desruisseaux-caldav-sched]
- Desruisseaux, B., "Scheduling Extensions to CalDAV",
- draft-desruisseaux-caldav-sched-03 (work in progress),
- January 2007.
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D.
- Jensen, "HTTP Extensions for Distributed Authoring --
- WEBDAV", RFC 2518, February 1999.
-
- [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.
-
-
-Appendix A. Acknowledgments
-
- This specification is the result of discussions between the Apple
- calendar server and client teams.
-
-
-Appendix B. Change History
-
- Changes from -01:
-
- 1. Updated to RFC4791 reference.
-
- 2. Added text indicating that ctag applies to schedule Inbox and
- Outbox as well.
-
- Changes from -00:
-
- 1. Relaxed requirement so that any type of change to a child
- resource can trigger a CTag change (similar behavior to ETag).
-
-
-
-
-Daboo [Page 5]
-
- CalDAV Proxy May 2007
-
-
-Author's Address
-
- Cyrus Daboo
- Apple Inc.
- 1 Infinite Loop
- Cupertino, CA 95014
- USA
-
- Email: cyrus at daboo.name
- URI: http://www.apple.com/
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Daboo [Page 6]
-
Copied: CalendarServer/trunk/doc/Extensions/caldav-ctag.txt (from rev 2175, CalendarServer/trunk/doc/Extensions/caldav-ctag-02.txt)
===================================================================
--- CalendarServer/trunk/doc/Extensions/caldav-ctag.txt (rev 0)
+++ CalendarServer/trunk/doc/Extensions/caldav-ctag.txt 2008-02-23 04:20:49 UTC (rev 2176)
@@ -0,0 +1,336 @@
+
+
+
+Calendar Server Extension C. Daboo
+ Apple
+ May 3, 2007
+
+
+ Calendar Collection Entity Tag (CTag) in CalDAV
+ caldav-ctag-02
+
+Abstract
+
+ This specification defines an extension to CalDAV that provides a
+ fast way for a client to determine whether the contents of a calendar
+ collection may have changed.
+
+
+Table of Contents
+
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
+ 2. Conventions Used in This Document . . . . . . . . . . . . . . . 2
+ 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
+ 3.1. Server . . . . . . . . . . . . . . . . . . . . . . . . . . 3
+ 3.2. Client . . . . . . . . . . . . . . . . . . . . . . . . . . 3
+ 4. New features in CalDAV . . . . . . . . . . . . . . . . . . . . 3
+ 4.1. getctag WebDAV Property . . . . . . . . . . . . . . . . . . 4
+ 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 4
+ 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 5
+ 7. Normative References . . . . . . . . . . . . . . . . . . . . . 5
+ Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 5
+ Appendix B. Change History . . . . . . . . . . . . . . . . . . . . 5
+ Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 6
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo [Page 1]
+
+ CalDAV Proxy May 2007
+
+
+1. Introduction
+
+ In CalDAV [RFC4791] calendar data is stored in calendar collection
+ resources. Clients need to "poll" calendar collections in order to
+ find out what has changed since the last time they examined it.
+ Currently that involves having to do a PROPFIND Depth:1 HTTP request,
+ or a CALDAV:calendar-query REPORT request. When a calendar
+ collection contains a large number of calendar resources those
+ operations become expensive on the server.
+
+ Calendar users often configure their clients to poll at short time
+ intervals. So polling traffic to the server will be high, even
+ though the frequency at which changes actually occur to a calendar is
+ typically low.
+
+ To improve on performance, this specification defines a new "calendar
+ collection entity tag" (CTag) WebDAV property that is defined on
+ calendar collections. When the calendar collection changes, the CTag
+ value changes. Thus a client can cache the CTag at some point in
+ time, then poll the collection only (i.e. PROPFIND Depth:0 HTTP
+ requests) and determine if a change has happened based on the
+ returned CTag value. If there is a change, it can then fall back to
+ doing the full (Depth:1) poll of the collection to actually determine
+ which resources in the collection changed.
+
+ This extension also defines CTag's on CalDAV scheduling
+ [I-D.desruisseaux-caldav-sched] Inbox and Outbox collections.
+
+
+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.
+
+
+
+
+
+
+Daboo [Page 2]
+
+ CalDAV Proxy May 2007
+
+
+3. Overview
+
+3.1. Server
+
+ For each calendar or scheduling Inbox or Outbox collection on the
+ server, a new CS:getctag WebDAV property is present.
+
+ The property value is an "opaque" token whose value is guaranteed to
+ be unique over the lifetime of any calendar or scheduling Inbox or
+ Outbox collection at a specific URI.
+
+ Whenever a calendar resource is added to, modified or deleted from
+ the calendar collection, the value of the CS:getctag property MUST
+ change. Typically this change will occur when the DAV:getetag
+ property on a child resource changes due to some protocol action. It
+ could be the result of a change to the body or properties of the
+ resource.
+
+3.2. Client
+
+ The client starts off with an empty string as the initial value for
+ the cached CTag of a calendar or scheduling Inbox or Outbox
+ collection that it intends to synchronize with.
+
+ When polling a calendar or scheduling Inbox or Outbox collection, the
+ client issues a PROPFIND Depth:0 HTTP request, asking for the CS:
+ getctag property to be returned.
+
+ If the returned value of CS:getctag property matches the one
+ currently cached for the calendar or scheduling Inbox or Outbox
+ collection, then the collection contents have not changed and no
+ further action is required until the next poll.
+
+ If the returned value of CS:getctag property does not match the one
+ found previously, then the contents of the calendar or scheduling
+ Inbox or Outbox collection have changed. At that point the client
+ should re-issue the PROPFIND Depth:1 request to get the collection
+ changes in detail and the CS:getctag property value corresponding to
+ the new state. The new CSgetctag property value should replace the
+ one currently cached for that calendar or scheduling Inbox or Outbox
+ collection.
+
+
+4. New features in CalDAV
+
+
+
+
+
+
+
+Daboo [Page 3]
+
+ CalDAV Proxy May 2007
+
+
+4.1. getctag WebDAV Property
+
+ Name: getctag
+
+ Namespace: http://calendarserver.org/ns/
+
+ Purpose: Specifies a "synchronization" token used to indicate when
+ the contents of a calendar or scheduling Inbox or Outbox
+ collection have changed.
+
+ Conformance: This property MUST be defined on a calendar or
+ scheduling Inbox or Outbox collection resource. It MUST be
+ protected and SHOULD be returned by a PROPFIND DAV:allprop request
+ (as defined in Section 12.14.1 of [RFC2518]).
+
+ Description: The CS:getctag property allows clients to quickly
+ determine if the contents of a calendar or scheduling Inbox or
+ Outbox collection have changed since the last time a
+ "synchronization" operation was done. The CS:getctag property
+ value MUST change each time the contents of the calendar or
+ scheduling Inbox or Outbox collection change, and each change MUST
+ result in a value that is different from any other used with that
+ collection URI.
+
+ Definition:
+
+ <!ELEMENT getctag #PCDATA>
+
+ Example:
+
+ <T:getctag xmlns:T="http://calendarserver.org/ns/"
+ >ABCD-GUID-IN-THIS-COLLECTION-20070228T122324010340</T:getctag>
+
+
+5. Security Considerations
+
+ The CS:getctag property value changes whenever any resource in the
+ collection or scheduling Inbox or Outbox changes. Thus a change to a
+ resource that a user does not have read access to will result in a
+ change in the CTag and the user will know that a change occurred.
+ However, that user will not able to get additional details about
+ exactly what changed as WebDAV ACLs [RFC3744] will prevent that. So
+ this does expose the fact that there are potentially "hidden"
+ resources in a calendar collection, but it does not expose any
+ details about them.
+
+
+
+
+
+
+Daboo [Page 4]
+
+ CalDAV Proxy May 2007
+
+
+6. IANA Considerations
+
+ This document does not require any actions on the part of IANA.
+
+
+7. Normative References
+
+ [I-D.desruisseaux-caldav-sched]
+ Desruisseaux, B., "Scheduling Extensions to CalDAV",
+ draft-desruisseaux-caldav-sched-03 (work in progress),
+ January 2007.
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D.
+ Jensen, "HTTP Extensions for Distributed Authoring --
+ WEBDAV", RFC 2518, February 1999.
+
+ [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.
+
+
+Appendix A. Acknowledgments
+
+ This specification is the result of discussions between the Apple
+ calendar server and client teams.
+
+
+Appendix B. Change History
+
+ Changes from -01:
+
+ 1. Updated to RFC4791 reference.
+
+ 2. Added text indicating that ctag applies to schedule Inbox and
+ Outbox as well.
+
+ Changes from -00:
+
+ 1. Relaxed requirement so that any type of change to a child
+ resource can trigger a CTag change (similar behavior to ETag).
+
+
+
+
+Daboo [Page 5]
+
+ CalDAV Proxy May 2007
+
+
+Author's Address
+
+ Cyrus Daboo
+ Apple Inc.
+ 1 Infinite Loop
+ Cupertino, CA 95014
+ USA
+
+ Email: cyrus at daboo.name
+ URI: http://www.apple.com/
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo [Page 6]
+
Added: CalendarServer/trunk/doc/Extensions/caldav-ctag.xml
===================================================================
--- CalendarServer/trunk/doc/Extensions/caldav-ctag.xml (rev 0)
+++ CalendarServer/trunk/doc/Extensions/caldav-ctag.xml 2008-02-23 04:20:49 UTC (rev 2176)
@@ -0,0 +1,181 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE rfc SYSTEM 'rfc2629.dtd' [
+<!ENTITY rfc2119 PUBLIC '' 'bibxml/reference.RFC.2119.xml'>
+<!ENTITY rfc2518 PUBLIC '' 'bibxml/reference.RFC.2518.xml'>
+<!ENTITY rfc3744 PUBLIC '' 'bibxml/reference.RFC.3744.xml'>
+<!ENTITY rfc4791 PUBLIC '' 'bibxml/reference.RFC.4791.xml'>
+<!ENTITY I-D.desruisseaux-caldav-sched PUBLIC '' 'bibxml3/reference.I-D.desruisseaux-caldav-sched.xml'>
+]>
+<?rfc toc="yes"?>
+<?rfc tocdepth="4"?>
+<?rfc strict="yes"?>
+<?rfc comments="yes"?>
+<?rfc inline="yes"?>
+<?rfc symrefs="yes"?>
+<?rfc sortrefs="yes"?>
+<?rfc compact="yes"?>
+<?rfc subcompact="no"?>
+<?rfc private="Calendar Server Extension"?>
+<rfc ipr="none" docName='caldav-ctag-02'>
+ <front>
+ <title abbrev="CalDAV Proxy">Calendar Collection Entity Tag (CTag) in CalDAV</title>
+ <author initials="C." surname="Daboo" fullname="Cyrus Daboo">
+ <organization abbrev="Apple">
+ Apple Inc.
+ </organization>
+ <address>
+ <postal>
+ <street>1 Infinite Loop</street>
+ <city>Cupertino</city>
+ <region>CA</region>
+ <code>95014</code>
+ <country>USA</country>
+ </postal>
+ <email>cyrus at daboo.name</email>
+ <uri>http://www.apple.com/</uri>
+ </address>
+ </author>
+ <date year='2007'/>
+ <abstract>
+ <t>
+ This specification defines an extension to CalDAV that provides a fast way for a client to determine whether the contents of a calendar collection may have changed.
+ </t>
+ </abstract>
+ </front>
+ <middle>
+ <section title='Introduction'>
+ <t>
+ In <xref target="RFC4791">CalDAV</xref> calendar data is stored in calendar collection resources. Clients need to "poll" calendar collections in order to find out what has changed since the last time they examined it. Currently that involves having to do a PROPFIND Depth:1 HTTP request, or a CALDAV:calendar-query REPORT request. When a calendar collection contains a large number of calendar resources those operations become expensive on the server.
+ </t>
+ <t>
+ Calendar users often configure their clients to poll at short time intervals. So polling traffic to the server will be high, even though the frequency at which changes actually occur to a calendar is typically low.
+ </t>
+ <t>
+ To improve on performance, this specification defines a new "calendar collection entity tag" (CTag) WebDAV property that is defined on calendar collections. When the calendar collection changes, the CTag value changes. Thus a client can cache the CTag at some point in time, then poll the collection only (i.e. PROPFIND Depth:0 HTTP requests) and determine if a change has happened based on the returned CTag value. If there is a change, it can then fall back to doing the full (Depth:1) poll of the collection to actually determine which resources in the collection changed.
+ </t>
+ <t>
+ This extension also defines CTag's on <xref target="I-D.desruisseaux-caldav-sched">CalDAV scheduling</xref> Inbox and Outbox collections.
+ </t>
+ </section>
+ <section title='Conventions Used in This Document'>
+ <t>
+ 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 <xref target='RFC2119' />.
+ </t>
+ <t>
+ 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.
+ </t>
+ <t>
+ 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.
+ </t>
+ </section>
+
+ <section title='Overview' anchor='overview'>
+ <section title='Server'>
+ <t>
+ For each calendar or scheduling Inbox or Outbox collection on the server, a new CS:getctag WebDAV property is present.
+ </t>
+ <t>
+ The property value is an "opaque" token whose value is guaranteed to be unique over the lifetime of any calendar or scheduling Inbox or Outbox collection at a specific URI.
+ </t>
+ <t>
+ Whenever a calendar resource is added to, modified or deleted from the calendar collection, the value of the CS:getctag property MUST change. Typically this change will occur when the DAV:getetag property on a child resource changes due to some protocol action. It could be the result of a change to the body or properties of the resource.
+ </t>
+ </section>
+ <section title='Client'>
+ <t>
+ The client starts off with an empty string as the initial value for the cached CTag of a calendar or scheduling Inbox or Outbox collection that it intends to synchronize with.
+ </t>
+ <t>
+ When polling a calendar or scheduling Inbox or Outbox collection, the client issues a PROPFIND Depth:0 HTTP request, asking for the CS:getctag property to be returned.
+ </t>
+ <t>
+ If the returned value of CS:getctag property matches the one currently cached for the calendar or scheduling Inbox or Outbox collection, then the collection contents have not changed and no further action is required until the next poll.
+ </t>
+ <t>
+ If the returned value of CS:getctag property does not match the one found previously, then the contents of the calendar or scheduling Inbox or Outbox collection have changed. At that point the client should re-issue the PROPFIND Depth:1 request to get the collection changes in detail and the CS:getctag property value corresponding to the new state. The new CS:getctag property value should replace the one currently cached for that calendar or scheduling Inbox or Outbox collection.
+ </t>
+ </section>
+ </section>
+
+ <section title='New features in CalDAV' anchor='changes'>
+ <section title='getctag WebDAV Property'>
+ <t>
+ <list style="hanging">
+ <t hangText="Name:">
+ getctag
+ </t>
+ <t hangText="Namespace:">
+ http://calendarserver.org/ns/
+ </t>
+ <t hangText="Purpose:">
+ Specifies a "synchronization" token used to indicate when the contents of a calendar or scheduling Inbox or Outbox collection have changed.
+ </t>
+ <t hangText="Conformance:">
+ This property MUST be defined on a calendar or scheduling Inbox or Outbox collection resource. It MUST be protected and SHOULD be returned by a PROPFIND DAV:allprop request (as defined in Section 12.14.1 of <xref target="RFC2518" />).
+ </t>
+ <t hangText="Description:">
+ The CS:getctag property allows clients to quickly determine if the contents of a calendar or scheduling Inbox or Outbox collection have changed since the last time a "synchronization" operation was done. The CS:getctag property value MUST change each time the contents of the calendar or scheduling Inbox or Outbox collection change, and each change MUST result in a value that is different from any other used with that collection URI.
+ </t>
+ <t hangText="Definition:">
+ <figure>
+ <artwork><![CDATA[
+ <!ELEMENT getctag #PCDATA>
+ ]]></artwork>
+ </figure>
+ </t>
+ <t hangText="Example:">
+ <figure>
+ <artwork><![CDATA[
+ <T:getctag xmlns:T="http://calendarserver.org/ns/"
+ >ABCD-GUID-IN-THIS-COLLECTION-20070228T122324010340</T:getctag>
+ ]]></artwork>
+ </figure>
+ </t>
+ </list>
+ </t>
+ </section>
+ </section>
+
+ <section title='Security Considerations'>
+ <t>
+ The CS:getctag property value changes whenever any resource in the collection or scheduling Inbox or Outbox changes. Thus a change to a resource that a user does not have read access to will result in a change in the CTag and the user will know that a change occurred. However, that user will not able to get additional details about exactly what changed as WebDAV ACLs <xref target='RFC3744'/> will prevent that. So this does expose the fact that there are potentially "hidden" resources in a calendar collection, but it does not expose any details about them.
+ </t>
+ </section>
+ <section title='IANA Considerations'>
+ <t>
+ This document does not require any actions on the part of IANA.
+ </t>
+ </section>
+ </middle>
+ <back>
+ <references title='Normative References'>
+ &rfc2119;
+ &rfc2518;
+ &rfc3744;
+ &rfc4791;
+ &I-D.desruisseaux-caldav-sched;
+ </references>
+<!--
+<references title='Informative References'>
+</references>
+-->
+ <section title='Acknowledgments'>
+ <t>
+ This specification is the result of discussions between the Apple calendar server and client teams.
+ </t>
+ </section>
+ <section title='Change History'>
+ <t>Changes from -01:
+ <list style='numbers'>
+ <t>Updated to RFC4791 reference.</t>
+ <t>Added text indicating that ctag applies to schedule Inbox and Outbox as well.</t>
+ </list>
+ </t>
+ <t>Changes from -00:
+ <list style='numbers'>
+ <t>Relaxed requirement so that any type of change to a child resource can trigger a CTag change (similar behavior to ETag).</t>
+ </list>
+ </t>
+ </section>
+ </back>
+</rfc>
Deleted: CalendarServer/trunk/doc/Extensions/caldav-proxy-02.txt
===================================================================
--- CalendarServer/trunk/doc/Extensions/caldav-proxy-02.txt 2008-02-22 05:07:34 UTC (rev 2175)
+++ CalendarServer/trunk/doc/Extensions/caldav-proxy-02.txt 2008-02-23 04:20:49 UTC (rev 2176)
@@ -1,560 +0,0 @@
-
-
-
-Calendar Server Extension C. Daboo
- Apple Computer
- May 3, 2007
-
-
- Calendar User Proxy Functionality in CalDAV
- caldav-cu-proxy-02
-
-Abstract
-
- This specification defines an extension to CalDAV that makes it easy
- for clients to setup and manage calendar user proxies, using the
- WebDAV Access Control List extension as a basis.
-
-
-Table of Contents
-
- 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
- 2. Conventions Used in This Document . . . . . . . . . . . . . . 2
- 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
- 3.1. Server . . . . . . . . . . . . . . . . . . . . . . . . . . 3
- 3.2. Client . . . . . . . . . . . . . . . . . . . . . . . . . . 3
- 4. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 4
- 5. New features in CalDAV . . . . . . . . . . . . . . . . . . . . 4
- 5.1. Proxy Principal Resource . . . . . . . . . . . . . . . . . 4
- 5.2. Privilege Provisioning . . . . . . . . . . . . . . . . . . 8
- 6. Security Considerations . . . . . . . . . . . . . . . . . . . 9
- 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
- 8. Normative References . . . . . . . . . . . . . . . . . . . . . 9
- Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 9
- Appendix B. Change History . . . . . . . . . . . . . . . . . . . 10
- Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 10
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Daboo [Page 1]
-
- CalDAV Proxy May 2007
-
-
-1. Introduction
-
- CalDAV [RFC4791] provides a way for calendar users to store calendar
- data and exchange this data via scheduling operations. Based on the
- WebDAV protocol [RFC2518], it also includes the ability to manage
- access to calendar data via the WebDAV ACL extension [RFC3744].
-
- It is often common for a calendar user to delegate some form of
- responsibility for their calendar and schedules to another calendar
- user (e.g., a boss allows an assistant to check a calendar or to send
- and accept scheduling invites on his behalf). The user handling the
- calendar data on behalf of someone else is often referred to as a
- "calendar user proxy".
-
- Whilst CalDAV does have fine-grained access control features that can
- be used to setup complex sharing and management of calendars, often
- the proxy behavior required is an "all-or-nothing" approach - i.e.
- the proxy has access to all the calendars or to no calendars (in
- which case they are of course not a proxy). So a simple way to
- manage access to an entire set of calendars and scheduling ability
- would be handy.
-
- In addition, calendar user agents will often want to display to a
- user who has proxy access to their calendars, or to whom they are
- acting as a proxy. Again, CalDAV's access control discovery and
- report features can be used to do that, but with fine-grained control
- that exists, it can be hard to tell who is a "real" proxy as opposed
- to someone just granted rights to some subset of calendars. Again, a
- simple way to discover proxy information would be handy.
-
-
-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 namespace "DAV:" are referenced in this
- document outside of the context of an XML fragment, the string "DAV:"
- will be prefixed to the element type names.
-
- 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
-
-
-
-Daboo [Page 2]
-
- CalDAV Proxy May 2007
-
-
- 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. Overview
-
-3.1. Server
-
- For each calendar user principal on the server, the server will
- generate two group principals - "proxy groups". One is used to hold
- the list of principals who have read-only proxy access to the main
- principal's calendars, the other holds the list of principals who
- have read-write and scheduling proxy access. NB these new group
- principals would have no equivalent in Open Directory.
-
- Privileges on each "proxy group" principal will be set so that the
- "owner" has the ability to change property values.
-
- The "proxy group" principals will be child resources of the user
- principal resource with specific resource types and thus are easy to
- discover. As a result the user principal resources will also be
- collection resources.
-
- When provisioning the calendar user home collection, the server will:
-
- a. Add an ACE to the calendar home collection giving the read-only
- "proxy group" inheritable read access.
-
- b. Add an ACE to the calendar home collection giving the read-write
- "proxy group" inheritable read-write access.
-
- c. Add an ACE to each of the calendar Inbox and Outbox collections
- giving the CALDAV:schedule privilege
- [I-D.desruisseaux-caldav-sched] to the read-write "proxy group".
-
-3.2. Client
-
- A client can see who the proxies are for the current principal by
- examining the principal resource for the two "proxy group" properties
- and then looking at the DAV:group-member-set property of each.
-
- The client can edit the list of proxies for the current principal by
- editing the DAV:group-member-set property on the relevant "proxy
- group" principal resource.
-
- The client can find out who the current principal is a proxy for by
- running a DAV:principal-match REPORT on the principal collection.
-
-
-
-Daboo [Page 3]
-
- CalDAV Proxy May 2007
-
-
- Alternatively, the client can find out who the current principal is a
- proxy for by examining the DAV:group-membership property on the
- current principal resource looking for membership in other users'
- "proxy groups".
-
-
-4. Open Issues
-
- 1. Do we want to separate read-write access to calendars vs the
- ability to schedule as a proxy?
-
- 2. We may want to restrict changing properties on the proxy group
- collections to just the DAV:group-member-set property?
-
- 3. There is no way for a proxy to be able to manage the list of
- proxies. We could allow the main calendar user DAV:write-acl on
- their "proxy group" principals, in which case they could grant
- others the right to modify the group membership.
-
- 4. Should the "proxy group" principals also be collections given
- that the regular principal resources will be?
-
-
-5. New features in CalDAV
-
-5.1. Proxy Principal Resource
-
- Each "regular" principal resource that needs to allow calendar user
- proxy support MUST be a collection resource. i.e. in addition to
- including the DAV:principal XML element in the DAV:resourcetype
- property on the resource, it MUST also include the DAV:collection XML
- element.
-
- Each "regular" principal resource MUST contain two child resources
- with names "calendar-proxy-read" and "calendar-proxy-write" (note
- that these are only suggested names - the server could choose any
- unique name for these). These resources are themselves principal
- resources that are groups contain the list of principals for calendar
- users who can act as a read-only or read-write proxy respectively.
-
- The server MUST include the CS:calendar-proxy-read or CS:calendar-
- proxy-write XML elements in the DAV:resourcetype property of the
- child resources, respectively. This allows clients to discover the
- "proxy group" principals by using a PROPFIND, Depth:1 request on the
- current user's principal resource and requesting the DAV:resourcetype
- property be returned. The element type declarations are:
-
-
-
-
-
-Daboo [Page 4]
-
- CalDAV Proxy May 2007
-
-
- <!ELEMENT calendar-proxy-read EMPTY>
-
- <!ELEMENT calendar-proxy-write EMPTY>
-
- The server MUST allow the "parent" principal to change the DAV:group-
- member-set property on each of the "child" "proxy group" principal
- resources. When a principal is listed as a member of the "child"
- resource, the server MUST include the "child" resource URI in the
- DAV:group-membership property on the included principal resource.
- Note that this is just "normal" behavior for a group principal.
-
- An example principal resource layout might be:
-
- + /
- + principals/
- + users/
- + cyrus/
- calendar-proxy-read
- calendar-proxy-write
- + red/
- calendar-proxy-read
- calendar-proxy-write
- + wilfredo/
- calendar-proxy-read
- calendar-proxy-write
-
- If the principal "cyrus" wishes to have the principal "red" act as a
- calendar user proxy on his behalf and have the ability to change
- items on his calendar or schedule meetings on his behalf, then he
- would add the principal resource URI for "red" to the DAV:group-
- member-set property of the principal resource /principals/users/
- cyrus/calendar-proxy-write, giving:
-
- <DAV:group-member-set>
- <DAV:href>/principals/users/red/</DAV:href>
- </DAV:group-member-set>
-
- The DAV:group-membership property on the resource /principals/users/
- red/ would be:
-
- <DAV:group-membership>
- <DAV:href>/principals/users/cyrus/calendar-proxy-write</DAV:href>
- </DAV:group-membership>
-
- If the principal "red" was also a read-only proxy for the principal
- "wilfredo", then the DA:group-membership property on the resource
- /principals/users/red/ would be:
-
-
-
-
-Daboo [Page 5]
-
- CalDAV Proxy May 2007
-
-
- <DAV:group-membership>
- <DAV:href>/principals/users/cyrus/calendar-proxy-write</DAV:href>
- <DAV:href>/principals/users/wilfredo/calendar-proxy-read</DAV:href>
- </DAV:group-membership>
-
- Thus a client can discover to which principals a particular principal
- is acting as a calendar user proxy for by examining the DAV:group-
- membership property.
-
- An alternative to discovering which principals a user can proxy as is
- to use the WebDAV ACL principal-match report, targeted at the
- principal collections available on the server.
-
- Example:
-
- >> Request <<
-
- REPORT /principals/ HTTP/1.1
- Host: cal.example.com
- Depth: 0
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
- Authorization: Digest username="red",
- realm="cal.example.com", nonce="...",
- uri="/principals/", response="...", opaque="..."
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:principal-match xmlns:D="DAV:">
- <D:self/>
- <D:prop>
- <D:resourcetype/>
- </D:prop>
- </D:principal-match>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Daboo [Page 6]
-
- CalDAV Proxy May 2007
-
-
- >> Response <<
-
- HTTP/1.1 207 Multi-Status
- Date: Fri, 10 Nov 2006 09:32:12 GMT
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D="DAV:"
- xmlns:A="http://calendarserver.org/ns/">
- <D:response>
- <D:href>/principals/users/red/</D:href>
- <D:propstat>
- <D:prop>
- <D:resourcetype>
- <D:principal/>
- <D:collection/>
- </D:resourcetype>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- </D:response>
- <D:response>
- <D:href>/principals/users/cyrus/calendar-proxy-write</D:href>
- <D:propstat>
- <D:prop>
- <D:resourcetype>
- <D:principal/>
- <A:calendar-proxy-write/>
- </D:resourcetype>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- </D:response>
- <D:response>
- <D:href>/principals/users/wilfredo/calendar-proxy-read</D:href>
- <D:propstat>
- <D:prop>
- <D:resourcetype>
- <D:principal/>
- <A:calendar-proxy-read/>
- </D:resourcetype>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- </D:response>
- </D:multistatus>
-
-
-
-
-Daboo [Page 7]
-
- CalDAV Proxy May 2007
-
-
-5.2. Privilege Provisioning
-
- In order for a calendar user proxy to be able to access the calendars
- of the user they are proxying for the server MUST ensure that the
- privileges on the relevant calendars are setup accordingly:
-
- The DAV:read privilege MUST be granted for read-only and read-
- write calendar user proxy principals
-
- The DAV:write privilege MUST be granted for read-write calendar
- user proxy principals.
-
- Additionally, the CalDAV scheduling Inbox and Outbox calendar
- collections for the user allowing proxy access, MUST have the CALDAV:
- schedule privilege [I-D.desruisseaux-caldav-sched] granted for read-
- write calendar user proxy principals.
-
- Note that with a suitable repository layout, a server may be able to
- grant the appropriate privileges on a parent collection and ensure
- that all the contained collections and resources inherit that. For
- example, given the following repository layout:
-
- + /
- + calendars/
- + users/
- + cyrus/
- inbox
- outbox
- home
- work
- + red/
- inbox
- outbox
- work
- soccer
- + wilfredo/
- inbox
- outbox
- home
- work
- flying
-
- In order for the principal "red" to act as a read-write proxy for the
- principal "cyrus", the following WebDAV ACE will need to be granted
- on the resource /calendars/users/cyrus/ and all children of that
- resource:
-
-
-
-
-
-Daboo [Page 8]
-
- CalDAV Proxy May 2007
-
-
- <DAV:ace>
- <DAV:principal>
- <DAV:href>/principals/users/cyrus/calendar-proxy-write</DAV:href>
- </DAV:principal>
- <DAV:privileges>
- <DAV:grant><DAV:read/><DAV:write/></DAV:grant>
- </DAV:privileges>
- </DAV:ace>
-
-
-6. Security Considerations
-
- TBD
-
-
-7. IANA Considerations
-
- This document does not require any actions on the part of IANA.
-
-
-8. Normative References
-
- [I-D.desruisseaux-caldav-sched]
- Desruisseaux, B., "Scheduling Extensions to CalDAV",
- draft-desruisseaux-caldav-sched-03 (work in progress),
- January 2007.
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D.
- Jensen, "HTTP Extensions for Distributed Authoring --
- WEBDAV", RFC 2518, February 1999.
-
- [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.
-
-
-Appendix A. Acknowledgments
-
- This specification is the result of discussions between the Apple
- calendar server and client teams.
-
-
-
-
-Daboo [Page 9]
-
- CalDAV Proxy May 2007
-
-
-Appendix B. Change History
-
- Changes from -00:
-
- 1. Updated to RFC 4791 reference.
-
- Changes from -00:
-
- 1. Added more details on actual CalDAV protocol changes.
-
- 2. Changed namespace from http://apple.com/ns/calendarserver/ to
- http://calendarserver.org/ns/.
-
- 3. Made "proxy group" principals child resources of their "owner"
- principals.
-
- 4. The "proxy group" principals now have their own resourcetype.
-
-
-Author's Address
-
- Cyrus Daboo
- Apple Computer, Inc.
- 1 Infinite Loop
- Cupertino, CA 95014
- USA
-
- Email: cyrus at daboo.name
- URI: http://www.apple.com/
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Daboo [Page 10]
-
Copied: CalendarServer/trunk/doc/Extensions/caldav-proxy.txt (from rev 2175, CalendarServer/trunk/doc/Extensions/caldav-proxy-02.txt)
===================================================================
--- CalendarServer/trunk/doc/Extensions/caldav-proxy.txt (rev 0)
+++ CalendarServer/trunk/doc/Extensions/caldav-proxy.txt 2008-02-23 04:20:49 UTC (rev 2176)
@@ -0,0 +1,560 @@
+
+
+
+Calendar Server Extension C. Daboo
+ Apple Computer
+ May 3, 2007
+
+
+ Calendar User Proxy Functionality in CalDAV
+ caldav-cu-proxy-02
+
+Abstract
+
+ This specification defines an extension to CalDAV that makes it easy
+ for clients to setup and manage calendar user proxies, using the
+ WebDAV Access Control List extension as a basis.
+
+
+Table of Contents
+
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
+ 2. Conventions Used in This Document . . . . . . . . . . . . . . 2
+ 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
+ 3.1. Server . . . . . . . . . . . . . . . . . . . . . . . . . . 3
+ 3.2. Client . . . . . . . . . . . . . . . . . . . . . . . . . . 3
+ 4. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 4
+ 5. New features in CalDAV . . . . . . . . . . . . . . . . . . . . 4
+ 5.1. Proxy Principal Resource . . . . . . . . . . . . . . . . . 4
+ 5.2. Privilege Provisioning . . . . . . . . . . . . . . . . . . 8
+ 6. Security Considerations . . . . . . . . . . . . . . . . . . . 9
+ 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
+ 8. Normative References . . . . . . . . . . . . . . . . . . . . . 9
+ Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 9
+ Appendix B. Change History . . . . . . . . . . . . . . . . . . . 10
+ Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 10
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo [Page 1]
+
+ CalDAV Proxy May 2007
+
+
+1. Introduction
+
+ CalDAV [RFC4791] provides a way for calendar users to store calendar
+ data and exchange this data via scheduling operations. Based on the
+ WebDAV protocol [RFC2518], it also includes the ability to manage
+ access to calendar data via the WebDAV ACL extension [RFC3744].
+
+ It is often common for a calendar user to delegate some form of
+ responsibility for their calendar and schedules to another calendar
+ user (e.g., a boss allows an assistant to check a calendar or to send
+ and accept scheduling invites on his behalf). The user handling the
+ calendar data on behalf of someone else is often referred to as a
+ "calendar user proxy".
+
+ Whilst CalDAV does have fine-grained access control features that can
+ be used to setup complex sharing and management of calendars, often
+ the proxy behavior required is an "all-or-nothing" approach - i.e.
+ the proxy has access to all the calendars or to no calendars (in
+ which case they are of course not a proxy). So a simple way to
+ manage access to an entire set of calendars and scheduling ability
+ would be handy.
+
+ In addition, calendar user agents will often want to display to a
+ user who has proxy access to their calendars, or to whom they are
+ acting as a proxy. Again, CalDAV's access control discovery and
+ report features can be used to do that, but with fine-grained control
+ that exists, it can be hard to tell who is a "real" proxy as opposed
+ to someone just granted rights to some subset of calendars. Again, a
+ simple way to discover proxy information would be handy.
+
+
+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 namespace "DAV:" are referenced in this
+ document outside of the context of an XML fragment, the string "DAV:"
+ will be prefixed to the element type names.
+
+ 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
+
+
+
+Daboo [Page 2]
+
+ CalDAV Proxy May 2007
+
+
+ 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. Overview
+
+3.1. Server
+
+ For each calendar user principal on the server, the server will
+ generate two group principals - "proxy groups". One is used to hold
+ the list of principals who have read-only proxy access to the main
+ principal's calendars, the other holds the list of principals who
+ have read-write and scheduling proxy access. NB these new group
+ principals would have no equivalent in Open Directory.
+
+ Privileges on each "proxy group" principal will be set so that the
+ "owner" has the ability to change property values.
+
+ The "proxy group" principals will be child resources of the user
+ principal resource with specific resource types and thus are easy to
+ discover. As a result the user principal resources will also be
+ collection resources.
+
+ When provisioning the calendar user home collection, the server will:
+
+ a. Add an ACE to the calendar home collection giving the read-only
+ "proxy group" inheritable read access.
+
+ b. Add an ACE to the calendar home collection giving the read-write
+ "proxy group" inheritable read-write access.
+
+ c. Add an ACE to each of the calendar Inbox and Outbox collections
+ giving the CALDAV:schedule privilege
+ [I-D.desruisseaux-caldav-sched] to the read-write "proxy group".
+
+3.2. Client
+
+ A client can see who the proxies are for the current principal by
+ examining the principal resource for the two "proxy group" properties
+ and then looking at the DAV:group-member-set property of each.
+
+ The client can edit the list of proxies for the current principal by
+ editing the DAV:group-member-set property on the relevant "proxy
+ group" principal resource.
+
+ The client can find out who the current principal is a proxy for by
+ running a DAV:principal-match REPORT on the principal collection.
+
+
+
+Daboo [Page 3]
+
+ CalDAV Proxy May 2007
+
+
+ Alternatively, the client can find out who the current principal is a
+ proxy for by examining the DAV:group-membership property on the
+ current principal resource looking for membership in other users'
+ "proxy groups".
+
+
+4. Open Issues
+
+ 1. Do we want to separate read-write access to calendars vs the
+ ability to schedule as a proxy?
+
+ 2. We may want to restrict changing properties on the proxy group
+ collections to just the DAV:group-member-set property?
+
+ 3. There is no way for a proxy to be able to manage the list of
+ proxies. We could allow the main calendar user DAV:write-acl on
+ their "proxy group" principals, in which case they could grant
+ others the right to modify the group membership.
+
+ 4. Should the "proxy group" principals also be collections given
+ that the regular principal resources will be?
+
+
+5. New features in CalDAV
+
+5.1. Proxy Principal Resource
+
+ Each "regular" principal resource that needs to allow calendar user
+ proxy support MUST be a collection resource. i.e. in addition to
+ including the DAV:principal XML element in the DAV:resourcetype
+ property on the resource, it MUST also include the DAV:collection XML
+ element.
+
+ Each "regular" principal resource MUST contain two child resources
+ with names "calendar-proxy-read" and "calendar-proxy-write" (note
+ that these are only suggested names - the server could choose any
+ unique name for these). These resources are themselves principal
+ resources that are groups contain the list of principals for calendar
+ users who can act as a read-only or read-write proxy respectively.
+
+ The server MUST include the CS:calendar-proxy-read or CS:calendar-
+ proxy-write XML elements in the DAV:resourcetype property of the
+ child resources, respectively. This allows clients to discover the
+ "proxy group" principals by using a PROPFIND, Depth:1 request on the
+ current user's principal resource and requesting the DAV:resourcetype
+ property be returned. The element type declarations are:
+
+
+
+
+
+Daboo [Page 4]
+
+ CalDAV Proxy May 2007
+
+
+ <!ELEMENT calendar-proxy-read EMPTY>
+
+ <!ELEMENT calendar-proxy-write EMPTY>
+
+ The server MUST allow the "parent" principal to change the DAV:group-
+ member-set property on each of the "child" "proxy group" principal
+ resources. When a principal is listed as a member of the "child"
+ resource, the server MUST include the "child" resource URI in the
+ DAV:group-membership property on the included principal resource.
+ Note that this is just "normal" behavior for a group principal.
+
+ An example principal resource layout might be:
+
+ + /
+ + principals/
+ + users/
+ + cyrus/
+ calendar-proxy-read
+ calendar-proxy-write
+ + red/
+ calendar-proxy-read
+ calendar-proxy-write
+ + wilfredo/
+ calendar-proxy-read
+ calendar-proxy-write
+
+ If the principal "cyrus" wishes to have the principal "red" act as a
+ calendar user proxy on his behalf and have the ability to change
+ items on his calendar or schedule meetings on his behalf, then he
+ would add the principal resource URI for "red" to the DAV:group-
+ member-set property of the principal resource /principals/users/
+ cyrus/calendar-proxy-write, giving:
+
+ <DAV:group-member-set>
+ <DAV:href>/principals/users/red/</DAV:href>
+ </DAV:group-member-set>
+
+ The DAV:group-membership property on the resource /principals/users/
+ red/ would be:
+
+ <DAV:group-membership>
+ <DAV:href>/principals/users/cyrus/calendar-proxy-write</DAV:href>
+ </DAV:group-membership>
+
+ If the principal "red" was also a read-only proxy for the principal
+ "wilfredo", then the DA:group-membership property on the resource
+ /principals/users/red/ would be:
+
+
+
+
+Daboo [Page 5]
+
+ CalDAV Proxy May 2007
+
+
+ <DAV:group-membership>
+ <DAV:href>/principals/users/cyrus/calendar-proxy-write</DAV:href>
+ <DAV:href>/principals/users/wilfredo/calendar-proxy-read</DAV:href>
+ </DAV:group-membership>
+
+ Thus a client can discover to which principals a particular principal
+ is acting as a calendar user proxy for by examining the DAV:group-
+ membership property.
+
+ An alternative to discovering which principals a user can proxy as is
+ to use the WebDAV ACL principal-match report, targeted at the
+ principal collections available on the server.
+
+ Example:
+
+ >> Request <<
+
+ REPORT /principals/ HTTP/1.1
+ Host: cal.example.com
+ Depth: 0
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+ Authorization: Digest username="red",
+ realm="cal.example.com", nonce="...",
+ uri="/principals/", response="...", opaque="..."
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:principal-match xmlns:D="DAV:">
+ <D:self/>
+ <D:prop>
+ <D:resourcetype/>
+ </D:prop>
+ </D:principal-match>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo [Page 6]
+
+ CalDAV Proxy May 2007
+
+
+ >> Response <<
+
+ HTTP/1.1 207 Multi-Status
+ Date: Fri, 10 Nov 2006 09:32:12 GMT
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:"
+ xmlns:A="http://calendarserver.org/ns/">
+ <D:response>
+ <D:href>/principals/users/red/</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:resourcetype>
+ <D:principal/>
+ <D:collection/>
+ </D:resourcetype>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href>/principals/users/cyrus/calendar-proxy-write</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:resourcetype>
+ <D:principal/>
+ <A:calendar-proxy-write/>
+ </D:resourcetype>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href>/principals/users/wilfredo/calendar-proxy-read</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:resourcetype>
+ <D:principal/>
+ <A:calendar-proxy-read/>
+ </D:resourcetype>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ </D:multistatus>
+
+
+
+
+Daboo [Page 7]
+
+ CalDAV Proxy May 2007
+
+
+5.2. Privilege Provisioning
+
+ In order for a calendar user proxy to be able to access the calendars
+ of the user they are proxying for the server MUST ensure that the
+ privileges on the relevant calendars are setup accordingly:
+
+ The DAV:read privilege MUST be granted for read-only and read-
+ write calendar user proxy principals
+
+ The DAV:write privilege MUST be granted for read-write calendar
+ user proxy principals.
+
+ Additionally, the CalDAV scheduling Inbox and Outbox calendar
+ collections for the user allowing proxy access, MUST have the CALDAV:
+ schedule privilege [I-D.desruisseaux-caldav-sched] granted for read-
+ write calendar user proxy principals.
+
+ Note that with a suitable repository layout, a server may be able to
+ grant the appropriate privileges on a parent collection and ensure
+ that all the contained collections and resources inherit that. For
+ example, given the following repository layout:
+
+ + /
+ + calendars/
+ + users/
+ + cyrus/
+ inbox
+ outbox
+ home
+ work
+ + red/
+ inbox
+ outbox
+ work
+ soccer
+ + wilfredo/
+ inbox
+ outbox
+ home
+ work
+ flying
+
+ In order for the principal "red" to act as a read-write proxy for the
+ principal "cyrus", the following WebDAV ACE will need to be granted
+ on the resource /calendars/users/cyrus/ and all children of that
+ resource:
+
+
+
+
+
+Daboo [Page 8]
+
+ CalDAV Proxy May 2007
+
+
+ <DAV:ace>
+ <DAV:principal>
+ <DAV:href>/principals/users/cyrus/calendar-proxy-write</DAV:href>
+ </DAV:principal>
+ <DAV:privileges>
+ <DAV:grant><DAV:read/><DAV:write/></DAV:grant>
+ </DAV:privileges>
+ </DAV:ace>
+
+
+6. Security Considerations
+
+ TBD
+
+
+7. IANA Considerations
+
+ This document does not require any actions on the part of IANA.
+
+
+8. Normative References
+
+ [I-D.desruisseaux-caldav-sched]
+ Desruisseaux, B., "Scheduling Extensions to CalDAV",
+ draft-desruisseaux-caldav-sched-03 (work in progress),
+ January 2007.
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D.
+ Jensen, "HTTP Extensions for Distributed Authoring --
+ WEBDAV", RFC 2518, February 1999.
+
+ [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.
+
+
+Appendix A. Acknowledgments
+
+ This specification is the result of discussions between the Apple
+ calendar server and client teams.
+
+
+
+
+Daboo [Page 9]
+
+ CalDAV Proxy May 2007
+
+
+Appendix B. Change History
+
+ Changes from -00:
+
+ 1. Updated to RFC 4791 reference.
+
+ Changes from -00:
+
+ 1. Added more details on actual CalDAV protocol changes.
+
+ 2. Changed namespace from http://apple.com/ns/calendarserver/ to
+ http://calendarserver.org/ns/.
+
+ 3. Made "proxy group" principals child resources of their "owner"
+ principals.
+
+ 4. The "proxy group" principals now have their own resourcetype.
+
+
+Author's Address
+
+ Cyrus Daboo
+ Apple Computer, Inc.
+ 1 Infinite Loop
+ Cupertino, CA 95014
+ USA
+
+ Email: cyrus at daboo.name
+ URI: http://www.apple.com/
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo [Page 10]
+
Added: CalendarServer/trunk/doc/Extensions/caldav-proxy.xml
===================================================================
--- CalendarServer/trunk/doc/Extensions/caldav-proxy.xml (rev 0)
+++ CalendarServer/trunk/doc/Extensions/caldav-proxy.xml 2008-02-23 04:20:49 UTC (rev 2176)
@@ -0,0 +1,388 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE rfc SYSTEM 'rfc2629.dtd' [
+<!ENTITY rfc2119 PUBLIC '' 'bibxml/reference.RFC.2119.xml'>
+<!ENTITY rfc2518 PUBLIC '' 'bibxml/reference.RFC.2518.xml'>
+<!ENTITY rfc3744 PUBLIC '' 'bibxml/reference.RFC.3744.xml'>
+<!ENTITY rfc4791 PUBLIC '' 'bibxml/reference.RFC.4791.xml'>
+<!ENTITY I-D.dusseault-caldav PUBLIC '' 'bibxml3/reference.I-D.dusseault-caldav.xml'>
+<!ENTITY I-D.desruisseaux-caldav-sched PUBLIC '' 'bibxml3/reference.I-D.desruisseaux-caldav-sched.xml'>
+]>
+<?rfc toc="yes"?>
+<?rfc tocdepth="4"?>
+<?rfc strict="yes"?>
+<?rfc comments="yes"?>
+<?rfc inline="yes"?>
+<?rfc symrefs="yes"?>
+<?rfc sortrefs="yes"?>
+<?rfc compact="yes"?>
+<?rfc subcompact="no"?>
+<?rfc private="Calendar Server Extension"?>
+<rfc ipr="none" docName='caldav-cu-proxy-02'>
+ <front>
+ <title abbrev="CalDAV Proxy">Calendar User Proxy Functionality in CalDAV</title>
+ <author initials="C." surname="Daboo" fullname="Cyrus Daboo">
+ <organization abbrev="Apple Computer">
+ Apple Computer, Inc.
+ </organization>
+ <address>
+ <postal>
+ <street>1 Infinite Loop</street>
+ <city>Cupertino</city>
+ <region>CA</region>
+ <code>95014</code>
+ <country>USA</country>
+ </postal>
+ <email>cyrus at daboo.name</email>
+ <uri>http://www.apple.com/</uri>
+ </address>
+ </author>
+ <date year='2007'/>
+ <abstract>
+ <t>
+ This specification defines an extension to CalDAV that makes it easy for clients to setup and manage calendar user proxies, using the WebDAV Access Control List extension as a basis.
+ </t>
+ </abstract>
+ </front>
+ <middle>
+ <section title='Introduction'>
+ <t>
+ <xref target="RFC4791">CalDAV</xref> provides a way for calendar users to store calendar data and exchange this data via scheduling operations. Based on the WebDAV protocol <xref target='RFC2518' />, it also includes the ability to manage access to calendar data via the WebDAV ACL extension <xref target='RFC3744' />.
+ </t>
+ <t>
+ It is often common for a calendar user to delegate some form of responsibility for their calendar and schedules to another calendar user (e.g., a boss allows an assistant to check a calendar or to send and accept scheduling invites on his behalf). The user handling the calendar data on behalf of someone else is often referred to as a "calendar user proxy".
+ </t>
+ <t>
+ Whilst CalDAV does have fine-grained access control features that can be used to setup complex sharing and management of calendars, often the proxy behavior required is an "all-or-nothing" approach - i.e. the proxy has access to all the calendars or to no calendars (in which case they are of course not a proxy). So a simple way to manage access to an entire set of calendars and scheduling ability would be handy.
+ </t>
+ <t>
+ In addition, calendar user agents will often want to display to a user who has proxy access to their calendars, or to whom they are acting as a proxy. Again, CalDAV's access control discovery and report features can be used to do that, but with fine-grained control that exists, it can be hard to tell who is a "real" proxy as opposed to someone just granted rights to some subset of calendars. Again, a simple way to discover proxy information would be handy.
+ </t>
+ </section>
+ <section title='Conventions Used in This Document'>
+ <t>
+ 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 <xref target='RFC2119' />.
+ </t>
+ <t>
+ When XML element types in the namespace "DAV:" are referenced in this document outside of the context of an XML fragment, the string "DAV:" will be prefixed to the element type names.
+ </t>
+ <t>
+ 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.
+ </t>
+ <t>
+ 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.
+ </t>
+ </section>
+
+ <section title='Overview' anchor='overview'>
+ <section title='Server'>
+ <t>
+ For each calendar user principal on the server, the server will generate two group principals - "proxy groups". One is used to hold the list of principals who have read-only proxy access to the main principal's calendars, the other holds the list of principals who have read-write and scheduling proxy access. NB these new group principals would have no equivalent in Open Directory.
+ </t>
+ <t>
+ Privileges on each "proxy group" principal will be set so that the "owner" has the ability to change property values.
+ </t>
+ <t>
+ The "proxy group" principals will be child resources of the user principal resource with specific resource types and thus are easy to discover. As a result the user principal resources will also be collection resources.
+ </t>
+ <t>
+ When provisioning the calendar user home collection, the server will:
+ <list style='letters'>
+ <t>
+ Add an ACE to the calendar home collection giving the read-only "proxy group" inheritable read access.
+ </t>
+ <t>
+ Add an ACE to the calendar home collection giving the read-write "proxy group" inheritable read-write access.
+ </t>
+ <t>
+ Add an ACE to each of the calendar Inbox and Outbox collections giving the <xref target='I-D.desruisseaux-caldav-sched'>CALDAV:schedule privilege</xref> to the read-write "proxy group".
+ </t>
+ </list>
+ </t>
+ </section>
+ <section title='Client'>
+ <t>
+ A client can see who the proxies are for the current principal by examining the principal resource for the two "proxy group" properties and then looking at the DAV:group-member-set property of each.
+ </t>
+ <t>
+ The client can edit the list of proxies for the current principal by editing the DAV:group-member-set property on the relevant "proxy group" principal resource.
+ </t>
+ <t>
+ The client can find out who the current principal is a proxy for by running a DAV:principal-match REPORT on the principal collection.
+ </t>
+ <t>
+ Alternatively, the client can find out who the current principal is a proxy for by examining the DAV:group-membership property on the current principal resource looking for membership in other users' "proxy groups".
+ </t>
+ </section>
+ </section>
+
+ <section title="Open Issues">
+ <t>
+ <list style="numbers">
+ <t>
+ Do we want to separate read-write access to calendars vs the ability to schedule as a proxy?
+ </t>
+ <t>
+ We may want to restrict changing properties on the proxy group collections to just the DAV:group-member-set property?
+ </t>
+ <t>
+ There is no way for a proxy to be able to manage the list of proxies. We could allow the main calendar user DAV:write-acl on their "proxy group" principals, in which case they could grant others the right to modify the group membership.
+ </t>
+ <t>
+ Should the "proxy group" principals also be collections given that the regular principal resources will be?
+ </t>
+ </list>
+ </t>
+ </section>
+
+ <section title='New features in CalDAV' anchor='changes'>
+ <section title='Proxy Principal Resource'>
+ <t>
+ Each "regular" principal resource that needs to allow calendar user proxy support MUST be a collection resource. i.e. in addition to including the DAV:principal XML element in the DAV:resourcetype property on the resource, it MUST also include the DAV:collection XML element.
+ </t>
+ <t>
+ Each "regular" principal resource MUST contain two child resources with names "calendar-proxy-read" and "calendar-proxy-write" (note that these are only suggested names - the server could choose any unique name for these). These resources are themselves principal resources that are groups contain the list of principals for calendar users who can act as a read-only or read-write proxy respectively.
+ </t>
+ <t>
+ The server MUST include the CS:calendar-proxy-read or CS:calendar-proxy-write XML elements in the DAV:resourcetype property of the child resources, respectively. This allows clients to discover the "proxy group" principals by using a PROPFIND, Depth:1 request on the current user's principal resource and requesting the DAV:resourcetype property be returned. The element type declarations are:
+ <figure>
+ <artwork><![CDATA[
+<!ELEMENT calendar-proxy-read EMPTY>
+
+<!ELEMENT calendar-proxy-write EMPTY>
+ ]]></artwork>
+ </figure>
+ </t>
+ <t>
+ The server MUST allow the "parent" principal to change the DAV:group-member-set property on each of the "child" "proxy group" principal resources. When a principal is listed as a member of the "child" resource, the server MUST include the "child" resource URI in the DAV:group-membership property on the included principal resource. Note that this is just "normal" behavior for a group principal.
+ </t>
+ <t>
+ An example principal resource layout might be:
+ <figure>
+ <artwork><![CDATA[
+ + /
+ + principals/
+ + users/
+ + cyrus/
+ calendar-proxy-read
+ calendar-proxy-write
+ + red/
+ calendar-proxy-read
+ calendar-proxy-write
+ + wilfredo/
+ calendar-proxy-read
+ calendar-proxy-write
+ ]]></artwork>
+ </figure>
+ If the principal "cyrus" wishes to have the principal "red" act as a calendar user proxy on his behalf and have the ability to change items on his calendar or schedule meetings on his behalf, then he would add the principal resource URI for "red" to the DAV:group-member-set property of the principal resource /principals/users/cyrus/calendar-proxy-write, giving:
+ <figure>
+ <artwork><![CDATA[
+<DAV:group-member-set>
+ <DAV:href>/principals/users/red/</DAV:href>
+</DAV:group-member-set>
+ ]]></artwork>
+ </figure>
+ The DAV:group-membership property on the resource /principals/users/red/ would be:
+ <figure>
+ <artwork><![CDATA[
+<DAV:group-membership>
+ <DAV:href>/principals/users/cyrus/calendar-proxy-write</DAV:href>
+</DAV:group-membership>
+ ]]></artwork>
+ </figure>
+ </t>
+ <t>
+ If the principal "red" was also a read-only proxy for the principal "wilfredo", then the DA:group-membership property on the resource /principals/users/red/ would be:
+ <figure>
+ <artwork><![CDATA[
+<DAV:group-membership>
+ <DAV:href>/principals/users/cyrus/calendar-proxy-write</DAV:href>
+ <DAV:href>/principals/users/wilfredo/calendar-proxy-read</DAV:href>
+</DAV:group-membership>
+ ]]></artwork>
+ </figure>
+ Thus a client can discover to which principals a particular principal is acting as a calendar user proxy for by examining the DAV:group-membership property.
+ </t>
+ <t>
+ An alternative to discovering which principals a user can proxy as is to use the WebDAV ACL principal-match report, targeted at the principal collections available on the server.
+ </t>
+ <t>Example:
+ <figure>
+ <preamble>>> Request <<</preamble>
+ <artwork><![CDATA[
+REPORT /principals/ HTTP/1.1
+Host: cal.example.com
+Depth: 0
+Content-Type: application/xml; charset="utf-8"
+Content-Length: xxxx
+Authorization: Digest username="red",
+ realm="cal.example.com", nonce="...",
+ uri="/principals/", response="...", opaque="..."
+
+<?xml version="1.0" encoding="utf-8" ?>
+<D:principal-match xmlns:D="DAV:">
+ <D:self/>
+ <D:prop>
+ <D:resourcetype/>
+ </D:prop>
+</D:principal-match>
+ ]]></artwork>
+ </figure>
+ <figure>
+ <preamble>>> Response <<</preamble>
+ <artwork><![CDATA[
+HTTP/1.1 207 Multi-Status
+Date: Fri, 10 Nov 2006 09:32:12 GMT
+Content-Type: application/xml; charset="utf-8"
+Content-Length: xxxx
+
+<?xml version="1.0" encoding="utf-8" ?>
+<D:multistatus xmlns:D="DAV:"
+ xmlns:A="http://calendarserver.org/ns/">
+ <D:response>
+ <D:href>/principals/users/red/</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:resourcetype>
+ <D:principal/>
+ <D:collection/>
+ </D:resourcetype>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href>/principals/users/cyrus/calendar-proxy-write</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:resourcetype>
+ <D:principal/>
+ <A:calendar-proxy-write/>
+ </D:resourcetype>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href>/principals/users/wilfredo/calendar-proxy-read</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:resourcetype>
+ <D:principal/>
+ <A:calendar-proxy-read/>
+ </D:resourcetype>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+</D:multistatus>
+ ]]></artwork>
+ </figure>
+ </t>
+ </section>
+ <section title='Privilege Provisioning'>
+ <t>
+ In order for a calendar user proxy to be able to access the calendars of the user they are proxying for the server MUST ensure that the privileges on the relevant calendars are setup accordingly:
+ <list>
+ <t>The DAV:read privilege MUST be granted for read-only and read-write calendar user proxy principals</t>
+ <t>The DAV:write privilege MUST be granted for read-write calendar user proxy principals.</t>
+ </list>
+ Additionally, the CalDAV scheduling Inbox and Outbox calendar collections for the user allowing proxy access, MUST have the <xref target='I-D.desruisseaux-caldav-sched'>CALDAV:schedule privilege</xref> granted for read-write calendar user proxy principals.
+ </t>
+ <t>
+ Note that with a suitable repository layout, a server may be able to grant the appropriate privileges on a parent collection and ensure that all the contained collections and resources inherit that. For example, given the following repository layout:
+ <figure>
+ <artwork><![CDATA[
+ + /
+ + calendars/
+ + users/
+ + cyrus/
+ inbox
+ outbox
+ home
+ work
+ + red/
+ inbox
+ outbox
+ work
+ soccer
+ + wilfredo/
+ inbox
+ outbox
+ home
+ work
+ flying
+ ]]></artwork>
+ </figure>
+ In order for the principal "red" to act as a read-write proxy for the principal "cyrus", the following WebDAV ACE will need to be granted on the resource /calendars/users/cyrus/ and all children of that resource:
+ <figure>
+ <artwork><![CDATA[
+<DAV:ace>
+ <DAV:principal>
+ <DAV:href>/principals/users/cyrus/calendar-proxy-write</DAV:href>
+ </DAV:principal>
+ <DAV:privileges>
+ <DAV:grant><DAV:read/><DAV:write/></DAV:grant>
+ </DAV:privileges>
+</DAV:ace>
+ ]]></artwork>
+ </figure>
+ </t>
+
+ </section>
+ </section>
+
+ <section title='Security Considerations'>
+ <t>
+ TBD
+ </t>
+ </section>
+ <section title='IANA Considerations'>
+ <t>
+ This document does not require any actions on the part of IANA.
+ </t>
+ </section>
+ </middle>
+ <back>
+ <references title='Normative References'>
+ &rfc2119;
+ &rfc2518;
+ &rfc3744;
+ &rfc4791;
+ &I-D.desruisseaux-caldav-sched;
+ </references>
+<!--
+<references title='Informative References'>
+</references>
+-->
+ <section title='Acknowledgments'>
+ <t>
+ This specification is the result of discussions between the Apple calendar server and client teams.
+ </t>
+ </section>
+ <section title='Change History'>
+ <t>Changes from -00:
+ <list style='numbers'>
+ <t>
+ Updated to RFC 4791 reference.
+ </t>
+ </list>
+ </t>
+ <t>Changes from -00:
+ <list style='numbers'>
+ <t>
+ Added more details on actual CalDAV protocol changes.
+ </t>
+ <t>
+ Changed namespace from http://apple.com/ns/calendarserver/ to http://calendarserver.org/ns/.
+ </t>
+ <t>
+ Made "proxy group" principals child resources of their "owner" principals.
+ </t>
+ <t>
+ The "proxy group" principals now have their own resourcetype.
+ </t>
+ </list>
+ </t>
+ </section>
+ </back>
+</rfc>
Deleted: CalendarServer/trunk/doc/Extensions/caldav-resync-02.txt
===================================================================
--- CalendarServer/trunk/doc/Extensions/caldav-resync-02.txt 2008-02-22 05:07:34 UTC (rev 2175)
+++ CalendarServer/trunk/doc/Extensions/caldav-resync-02.txt 2008-02-23 04:20:49 UTC (rev 2176)
@@ -1,616 +0,0 @@
-
-
-
-Calendar Server Extension C. Daboo
- Apple
- May 3, 2007
-
-
- CalDAV Fast Resynchronization
- caldav-resync-02
-
-Abstract
-
- This specification defines an extension to CalDAV that allows a
- client to quickly determine differences between calendar data it has
- cached and the current state of that data on the server.
-
-
-Table of Contents
-
- 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
- 2. Conventions Used in This Document . . . . . . . . . . . . . . 3
- 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
- 4. New features in CalDAV . . . . . . . . . . . . . . . . . . . . 4
- 4.1. CS:calendar-resync REPORT . . . . . . . . . . . . . . . . 4
- 4.1.1. Example: Initial CALDAV:calendar-resync REPORT . . . . 6
- 4.1.2. Example: Successful CALDAV:calendar-resync REPORT . . 7
- 5. XML Element Definitions . . . . . . . . . . . . . . . . . . . 9
- 5.1. CS:calendar-resync XML Element . . . . . . . . . . . . . . 9
- 5.2. CS:resource XML Element . . . . . . . . . . . . . . . . . 10
- 6. Security Considerations . . . . . . . . . . . . . . . . . . . 10
- 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
- 8. Normative References . . . . . . . . . . . . . . . . . . . . . 10
- Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 11
- Appendix B. Change History . . . . . . . . . . . . . . . . . . . 11
- Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 11
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Daboo [Page 1]
-
- CalDAV Resynchronization May 2007
-
-
-1. Introduction
-
- CalDAV [RFC4791] provides a way for calendar users to store calendar
- data and exchange this data via scheduling operations. Due to the
- stateless nature of the HTTP [RFC2616] and WebDAV [RFC2518]
- protocols, on which CalDAV is built, there is no notification of
- changes to server data that a client can utilize during a "session"
- to keep its state synchronized with the server. In the absence of
- this the client is forced to poll the server at regular intervals in
- order to check for changes to calendar collections.
-
- Currently, re-synchronizing a calendar collection consists of three
- steps.
-
- The first is to issue a PROPFIND request to retrieve the CS:
- getctag [CTAG] property on a calendar collection. If the value of
- that has changed since the last such poll, the client moves to the
- second step.
-
- In the second step the client issues a PROPFIND (Depth:1) on a
- calendar collection to fetch the DAV:href values and DAV:getetag
- properties of all immediate child resources within that
- collection. It then compares the results of that with the cached
- DAV:href/DAV:getetag values it has to determine what has changed
- on the server. For resources that are no longer on the server, it
- will remove its local copy, for resources that are new or have
- changed on the server, the client moves to the third step.
-
- In the third step the client fetches all the data for new and
- changed resources. For this, it can use a single CALDAV:multiget
- REPORT on a calendar collection to retrieve all the changed data
- in one go.
-
- Thus a re-synchronizing, where at least one calendar object resource
- has changed, involves three requests. The second PROPFIND (Depth:1)
- can be expensive on large calendars in that a significant amount of
- data is returned, when in fact the changes are small.
-
- To improve the performance of client synchronization, this
- specification defines a new CalDAV CS:calendar-resync REPORT that
- allows a client to request the server to return information about
- changes to calendar object resources in a calendar collection only.
- This can be accomplished in a single round trip.
-
- Note, that from a server load standpoint, it is still more efficient
- if a client uses the CS:getctag property to first determine whether
- any changes have taken place before using the CS:calendar-resync
- REPORT to find any changes. This is particularly true for short
-
-
-
-Daboo [Page 2]
-
- CalDAV Resynchronization May 2007
-
-
- polling intervals.
-
-
-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. Overview
-
- The first time a client "connects" to a server and examines a
- calendar collection, it will download and cache the data for all
- calendar object resources in that collection, if it wishes to
- maintain a complete cache of all such resources.
-
- Subsequently, when the client wishes to check for changes it will
- issue a CS:calendar-resync REPORT request to the server targeting the
- calendar collection URI. In the report body it will include all DAV:
- href/DAV:getetag value pairs it has stored for cached data.
-
- When the server receives the client report request, it will compare
- the list of DAV:href/DAV:getetag pairs with the current list
- accessible to the current user.
-
- The server will then return in a response information about only
- those resources that are new, have changed, or have been deleted on
- the server. Resources that are unchanged are not returned in the
- response.
-
- The client can update its cache using the server results returned in
- the response.
-
-
-
-
-
-
-
-Daboo [Page 3]
-
- CalDAV Resynchronization May 2007
-
-
-4. New features in CalDAV
-
- This section describes the changes to the base CalDAV access
- [RFC4791] and scheduling [I-D.desruisseaux-caldav-sched] drafts.
-
-4.1. CS:calendar-resync REPORT
-
- The CALDAV:calendar-resync REPORT is used to retrieve calendar object
- resources that are new, changed, deleted or had privileges changed.
- This report is similar to the CALDAV:calendar-multiget REPORT (see
- [RFC4791]), except that it takes a list of CS:resource elements,
- instead of DAV:href elements, to determine which calendar object
- resources to return.
-
- Marshalling:
-
- The request body MUST be a CALDAV:calendar-resync XML element (see
- Section 5.1)
-
- The Request-URI MUST be a calendar collection resource (see
- [RFC4791]), or a scheduling Inbox or Outbox collection (see
- [I-D.desruisseaux-caldav-sched]). The DAV:href elements inside of
- the CS:resource elements MUST all refer to calendar object
- resources within the collection. As a result, the "Depth" header
- MUST be ignored by the server and SHOULD NOT be sent by the
- client.
-
- The response body for a successful request MUST be a DAV:
- multistatus XML element.
-
- The response body for a successful CALDAV:calendar-resync REPORT
- request MUST contain a DAV:response element for each calendar
- object resource referenced by the provided set of DAV:href
- elements inside of each CS:resource element. Calendar data is
- being returned in the CALDAV:calendar-data element inside the DAV:
- prop element.
-
- For each CS:resource element in the request, the server examines
- the DAV:href and DAV:getetag element values, and uses the
- following procedure to build the response:
-
- If the resource referenced by the DAV:href element is not an
- immediate child of the collection targeted by the request-URI,
- the server adds a DAV:response element with a DAV:status
- element with the status set to "400 Bad Request".
-
- If the resource referenced by the DAV:href element does not
- exist, the server adds a DAV:response element with a DAV:status
-
-
-
-Daboo [Page 4]
-
- CalDAV Resynchronization May 2007
-
-
- element with the status set to "404 Not Found".
-
- If the resource referenced by the DAV:href element is not
- readable by the currently authenticated user, the server adds a
- DAV:response element with a DAV:status element with the status
- set to "403 Forbidden".
-
- If the resource referenced by the DAV:href element exists and
- is readable, but the DAV:getetag value in the request does not
- match the current DAV:getetag property value on the resource,
- the server adds a DAV:response element with a DAV:status
- element with the status set to "200 OK". The server also
- includes in the DAV:response any properties requested by the
- client in its request.
-
- If the resource referenced by the DAV:href element exists and
- is readable, and the DAV:getetag value in the request matches
- the current DAV:getetag property value on the resource, the
- server does not add a DAV:response for that resource.
-
- For each resource in the calendar collection referenced by the
- request-URI on the server that does not have a corresponding CS:
- resource entry in the client's request, the server carries out the
- following procedure to build the response:
-
- If the resource is not readable by the currently authenticated
- user, the server ignores it.
-
- If the resource is readable, the server adds a DAV:response
- element with a DAV:status element with the status set to "200
- OK". The server also includes in the DAV:response any
- properties requested by the client in its request.
-
- Preconditions:
-
- (CALDAV:supported-calendar-data): The attributes "content-type"
- and "version" of the CALDAV:calendar-data XML elements (see
- [RFC4791]) specify a media type supported by the server for
- calendar object resources.
-
- Postconditions:
-
- None.
-
-
-
-
-
-
-
-
-Daboo [Page 5]
-
- CalDAV Resynchronization May 2007
-
-
-4.1.1. Example: Initial CALDAV:calendar-resync REPORT
-
- In this example, the client requests the server to synchronize a
- calendar that it has not cached before. As a result the client
- request does not include any CS:resource elements. The response from
- the server indicates the presence of three resources in the calendar.
-
- >> Request <<
-
- REPORT /cyrus/work/ HTTP/1.1
- Host: cal.example.com
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <C:calendar-resync xmlns:D="DAV:"
- xmlns:C="urn:ietf:params:xml:ns:caldav"
- xmlns:CS="http://calendarserver.org/ns/">
- <D:prop>
- <D:getetag/>
- </D:prop>
- </C:calendar-resync>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Daboo [Page 6]
-
- CalDAV Resynchronization May 2007
-
-
- >> Response <<
-
- HTTP/1.1 207 Multi-Status
- Date: Sat, 11 Nov 2006 09:32:12 GMT
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D="DAV:"
- xmlns:C="urn:ietf:params:xml:ns:caldav">
- <D:response>
- <D:href>http://cal.example.com/cyrus/work/mtg1.ics</D:href>
- <D:propstat>
- <D:prop>
- <D:getetag>"MTG1-0011"</D:getetag>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- </D:response>
- <D:response>
- <D:href>http://cal.example.com/cyrus/work/mtg2.ics</D:href>
- <D:propstat>
- <D:prop>
- <D:getetag>"MTG2-0021"</D:getetag>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- </D:response>
- <D:response>
- <D:href>http://cal.example.com/cyrus/work/mtg3.ics</D:href>
- <D:propstat>
- <D:prop>
- <D:getetag>"MTG3-0031"</D:getetag>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- </D:response>
- </D:multistatus>
-
-4.1.2. Example: Successful CALDAV:calendar-resync REPORT
-
- In this example, the client requests the server to synchronize the
- calendar previously cached. The DAV:getetag property is requested
- and returned as part of the response. Note that in this example, the
- resource at http://cal.example.com/bernard/work/mtg1.ics no longer
- exists, the resource at http://cal.example.com/cyrus/work/mtg2.ics
- exists but has changed, the resource at
- http://cal.example.com/cyrus/work/mtg3.ics exists and has not
-
-
-
-Daboo [Page 7]
-
- CalDAV Resynchronization May 2007
-
-
- changed, and a new resource at
- http://cal.example.com/cyrus/work/mtg4.ics exists.
-
- >> Request <<
-
- REPORT /cyrus/work/ HTTP/1.1
- Host: cal.example.com
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <C:calendar-resync xmlns:D="DAV:"
- xmlns:C="urn:ietf:params:xml:ns:caldav"
- xmlns:CS="http://calendarserver.org/ns/">
- <D:prop>
- <D:getetag/>
- </D:prop>
- <CS:resource>
- <D:href>/cyrus/work/mtg1.ics</D:href>
- <D:getetag>MTG1-0011</D:getetag>
- </CS:resource>
- <CS:resource>
- <D:href>/cyrus/work/mtg2.ics</D:href>
- <D:getetag>MTG2-0021</D:getetag>
- </CS:resource>
- <CS:resource>
- <D:href>/cyrus/work/mtg3.ics</D:href>
- <D:getetag>MTG3-0031</D:getetag>
- </CS:resource>
- </C:calendar-resync>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Daboo [Page 8]
-
- CalDAV Resynchronization May 2007
-
-
- >> Response <<
-
- HTTP/1.1 207 Multi-Status
- Date: Sat, 11 Nov 2006 09:32:12 GMT
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D="DAV:"
- xmlns:C="urn:ietf:params:xml:ns:caldav">
- <D:response>
- <D:href>http://cal.example.com/cyrus/work/mtg1.ics</D:href>
- <D:status>HTTP/1.1 404 Not Found</D:status>
- </D:response>
- <D:response>
- <D:href>http://cal.example.com/cyrus/work/mtg2.ics</D:href>
- <D:propstat>
- <D:prop>
- <D:getetag>"MTG2-0022"</D:getetag>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- </D:response>
- <D:response>
- <D:href>http://cal.example.com/cyrus/work/mtg4.ics</D:href>
- <D:propstat>
- <D:prop>
- <D:getetag>"MTG4-0041"</D:getetag>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- </D:response>
- </D:multistatus>
-
-
-5. XML Element Definitions
-
-5.1. CS:calendar-resync XML Element
-
- Name: calendar-resync
- Namespace: http://calendarserver.org/ns/
- Purpose: Used as the root element in a REPORT request to find
- changes to a calendar collection.
- Description: See Section 4.1.
-
-
-
-
-
-
-
-Daboo [Page 9]
-
- CalDAV Resynchronization May 2007
-
-
- Definition:
-
- <!ELEMENT calendar-resync ((DAV:allprop |
- DAV:propname |
- DAV:prop)?,
- resource*)>
-
-5.2. CS:resource XML Element
-
- Name: resource
- Namespace: http://calendarserver.org/ns/
- Purpose: Used to hold DAV:href/DAV:getetag pairs to indicate to a
- server what data a client has cached.
- Description: See Section 4.1.
- Definition:
-
- <!ELEMENT resource (href, getetag)>
-
-
-6. Security Considerations
-
- When determining changes to the set of resources the client has
- cached, the server MUST take into consideration WebDAV ACLs on the
- resources it has stored for the user making the request. In
- particular, the addition or removal of the DAV:read privilege MUST
- result in appropriate change notification to a client.
-
-
-7. IANA Considerations
-
- This document does not require any actions on the part of IANA.
-
-
-8. Normative References
-
- [CTAG] Daboo, C., "Calendar Collection Entity Tag (CTag) in
- CalDAV", March 2007, <file:caldav-ctag-01.txt>.
-
- [I-D.desruisseaux-caldav-sched]
- Desruisseaux, B., "Scheduling Extensions to CalDAV",
- draft-desruisseaux-caldav-sched-03 (work in progress),
- January 2007.
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D.
- Jensen, "HTTP Extensions for Distributed Authoring --
-
-
-
-Daboo [Page 10]
-
- CalDAV Resynchronization May 2007
-
-
- WEBDAV", RFC 2518, February 1999.
-
- [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
- Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
- Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
-
- [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault,
- "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791,
- March 2007.
-
-
-Appendix A. Acknowledgments
-
- This specification is the result of discussions between the Apple
- calendar server and client teams.
-
-
-Appendix B. Change History
-
- Changes from -00:
- 1. Fixed some typos.
-
-
-Author's Address
-
- Cyrus Daboo
- Apple Inc.
- 1 Infinite Loop
- Cupertino, CA 95014
- USA
-
- Email: cdaboo at apple.com
- URI: http://www.apple.com/
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Daboo [Page 11]
-
Added: CalendarServer/trunk/doc/Extensions/icalendar-maskuids.xml
===================================================================
--- CalendarServer/trunk/doc/Extensions/icalendar-maskuids.xml (rev 0)
+++ CalendarServer/trunk/doc/Extensions/icalendar-maskuids.xml 2008-02-23 04:20:49 UTC (rev 2176)
@@ -0,0 +1,196 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE rfc SYSTEM 'rfc2629.dtd' [
+<!ENTITY rfc2119 PUBLIC '' 'bibxml/reference.RFC.2119.xml'>
+<!ENTITY rfc2445 PUBLIC '' 'bibxml/reference.RFC.2445.xml'>
+<!ENTITY rfc2446 PUBLIC '' 'bibxml/reference.RFC.2446.xml'>
+<!ENTITY rfc4791 PUBLIC '' 'bibxml/reference.RFC.4791.xml'>
+<!ENTITY I-D.desruisseaux-caldav-sched PUBLIC '' 'bibxml3/reference.I-D.desruisseaux-caldav-sched.xml'>
+]>
+<?rfc toc="yes"?>
+<?rfc tocdepth="4"?>
+<?rfc strict="yes"?>
+<?rfc comments="yes"?>
+<?rfc inline="yes"?>
+<?rfc symrefs="yes"?>
+<?rfc sortrefs="yes"?>
+<?rfc compact="yes"?>
+<?rfc subcompact="no"?>
+<?rfc private="Calendar Server Extension"?>
+<rfc ipr="none" docName='icalendar-maskuids-03'>
+ <front>
+ <title abbrev="iCalendar Mask UIDs">Masking existing meetings in iCalendar free busy requests</title>
+ <author initials="C." surname="Daboo" fullname="Cyrus Daboo">
+ <organization abbrev="Apple">
+ Apple Inc.
+ </organization>
+ <address>
+ <postal>
+ <street>1 Infinite Loop</street>
+ <city>Cupertino</city>
+ <region>CA</region>
+ <code>95014</code>
+ <country>USA</country>
+ </postal>
+ <email>cyrus at daboo.name</email>
+ <uri>http://www.apple.com/</uri>
+ </address>
+ </author>
+ <date year='2007'/>
+ <abstract>
+ <t>
+ This document defines an extension to the iTIP calendar scheduling protocol to allow an organizer to have a specific event that may exist on an attendee's calendar ignored when the attendee calculates and returns their free-busy information after a request from the organizer.
+ </t>
+ </abstract>
+ </front>
+ <middle>
+ <section title='Introduction'>
+ <t>
+ Internet calendaring and scheduling standards are defined by <xref target="RFC2445">iCalendar</xref> and <xref target="RFC2446">iTIP</xref>. One of the scheduling operations supported by iTIP is the ability of a meeting organizer to request free-busy time information from attendees of a meeting. To do that, the organizer creates an iCalendar VFREEBUSY component with start and end times corresponding to the interval over which free-busy time needs to be known, and then sends that component in an iTIP REQUEST message to each attendee. Attendees determine their own free-busy information over the specified interval and return that in a VFREEBUSY component sent back to the organizer.
+ </t>
+ <t>
+ It is often the case that an existing meeting that has previously been "booked" with attendees, needs to be re-scheduled. To do that the organizer may again check free-busy status for each attendee to try and determine a suitable time for the re-scheduled meeting. One problem with this is that with the current protocol, free-busy information returned by attendees will include a block of busy time corresponding to the meeting that has already been booked. Whilst the organizer could choose to treat that time as free for each attendee given that a known meeting exists, that would not take into account the possibility that an attendee choose to be double-booked for some reason.
+ </t>
+ <t>
+ What would be useful is a way for an organizer to ask attendees to ignore a certain meeting (specifically the one being re-scheduled) when asking for free-busy time in order to determine when to re-schedule a meeting.
+ </t>
+ <t>
+ This specification defines a new iCalendar property that an organizer can include in a VFREEBUSY request that instructs an attendee's calendar user agent to ignore any matching events when calculating free-busy information sent back in a response.
+ </t>
+ </section>
+ <section title='Conventions Used in This Document'>
+ <t>
+ 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 <xref target='RFC2119' />.
+ </t>
+ </section>
+
+ <section title="Open Issues">
+ <t>
+ <list style="numbers">
+ <t>
+ Do we want some kind of indicator in the iTIP reply so that the organizer's CUA knows whether X-CALENDARSERVER-MASK-UID was used (supported) or not?
+ </t>
+ </list>
+ </t>
+ </section>
+
+ <section title='New features in iCalendar' anchor='changes'>
+ <section title='Mask UID Property'>
+ <t>Property Name: X-CALENDARSERVER-MASK-UID</t>
+
+ <t>Purpose: This property indicates the unique identifier for a calendar component that is to be ignored when calculating free-busy time.</t>
+
+ <t>Value Type: TEXT</t>
+
+ <t>Property Parameters: Non-standard property parameters can be specified on this property.</t>
+
+ <t>Conformance: The property MAY be specified in a "VFREEBUSY" calendar component, but MUST occur only once. It only has significance when used in an iTIP VFREEBUSY request.</t>
+
+ <t>The value of this property MUST be a unique identifier of another iCalendar component that an organizer might believe exists on an attendee's calendar.</t>
+
+ <t>As per the iCalendar UID property, implementations MUST be able to receive and persist values of at least 255 characters for this property.</t>
+
+ <t>Formal Definition: The property is defined by the following notation:</t>
+
+ <t>maskuid = "X-CALENDARSERVER-MASK-UID" maskuidparam ":" text CRLF</t>
+
+ <t>maskuidparam = *(";" xparam)</t>
+
+ <t>Example: The following is an example of this property:</t>
+
+ <t>X-CALENDARSERVER-MASK-UID:4000F192713-0052 at example.com</t>
+
+ </section>
+ <section title='Free/Busy Component'>
+ <t>This specification extends the definition of the VFREEBUSY component (see Section 4.6.4 of <xref target="RFC2445"/>) to allow zero or one X-CALENDARSERVER-MASK-UID properties to be present.</t>
+ <figure>
+ <preamble>Formal Definition: (extends <xref target="RFC2445"/>)</preamble>
+ <artwork>
+ fbprop /= *(
+
+ ; the following are optional,
+ ; but MUST NOT occur more than once
+
+ maskuid
+
+ )
+ </artwork>
+ </figure>
+
+
+ </section>
+ <section title='iTIP'>
+ <t>This specification extends the VFREEBUSY request requirements (see Section 3.3.2 of <xref target="RFC2446"/>) to allow zero or one X-CALENDARSERVER-MASK-UID properties to be present in a VFREEBUSY component sent in a METHOD:REQUEST iTIP message.</t>
+ <t>When a calendar user agent receives a VFREEBUSY request containing a X-CALENDARSERVER-MASK-UID property, it processes the free-busy request as usual with the exception that any components that would contribute busy time to the free-busy response MUST have their UIDs checked, and if:
+
+ <list>
+ <t>they have a UID that matches the value of the X-CALENDARSERVER-MASK-UID property;</t>
+ <t>and
+ <list>
+ <t>they have an ORGANIZER property value that is the same as the ORGANIZER property value on the VFREEBUSY request component;</t>
+ <t>or</t>
+ <t>they do not have an ORGANIZER property and the calendar user whose free-busy is being checked is the same as the ORGANIZER property value in the VFREEBUSY request component;</t>
+ </list>
+ </t>
+ </list>
+ then they should be ignored and not contribute busy time.</t>
+ </section>
+
+ </section>
+
+ <section title="Interaction with CalDAV Servers">
+ <t>
+ The CalDAV <xref target="RFC4791">access</xref> and <xref target="I-D.desruisseaux-caldav-sched">scheduling</xref> extensions to WebDAV define a server-based calendar and scheduling protocol. The scheduling portion of that uses iTIP messaging to send requests and get responses from calendar users.
+ </t>
+ <t>
+ CalDAV servers MAY support the X-CALENDARSERVER-MASK-UID property on any iTIP VFREEBUSY requests sent to the server. To do that, a server simply follows the procedure described above to remove the matching UID from the free busy result, applying the appropriate restrictions with respect to ORGANIZER property.
+ </t>
+ </section>
+
+ <section title='Security Considerations'>
+ <t>
+ Calendar user agents processing a VFREEBUSY request with a X-CALENDARSERVER-MASK-UID property present MUST ensure that only components whose ORGANIZER property value matches that of the VFREEBUSY request component are ignored when calculating free-busy time, or ensure that there is no ORGANIZER property in the component to be ignored and the requesting calendar user is the same as the responding calendar user. This ensures that organizers can only mask out meetings that they themselves have scheduled, rather than meetings proposed by other people, or unscheduled events on their own calendars. This also ensures that only the original organizer of a meeting can determine whether that meeting actually appears on someone else's calendar by using the free-busy time requests with and without a masked UID as a probe.
+ </t>
+ </section>
+ <section title='IANA Considerations'>
+ <t>
+ This document does not require any actions on the part of IANA.
+ </t>
+ </section>
+ </middle>
+ <back>
+ <references title='Normative References'>
+ &rfc2119;
+ &rfc2445;
+ &rfc2446;
+ &rfc4791;
+ &I-D.desruisseaux-caldav-sched;
+ </references>
+<!--
+<references title='Informative References'>
+</references>
+-->
+ <section title='Acknowledgments'>
+ <t>
+ This specification is the result of discussions between the Apple calendar server and client teams.
+ </t>
+ </section>
+ <section title='Change History'>
+ <t>Changes since -02
+ <list style="numbers">
+ <t>Allowing masking of ORGANIZER-less events for the case where the ORGANIZER of the REQUEST is the same as the ATTENDEE being requested.</t>
+ </list>
+ </t>
+ <t>Changes since -01
+ <list style="numbers">
+ <t>Added section for support in CalDAV servers.</t>
+ </list>
+ </t>
+ <t>Changes since -00
+ <list style="numbers">
+ <t>Change to allow at most one X-CALENDARSERVER-MASK-UID property.</t>
+ <t>Change name to X-CALENDARSERVER-MASK-UID.</t>
+ </list>
+ </t>
+ </section>
+ </back>
+</rfc>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.macosforge.org/pipermail/calendarserver-changes/attachments/20080222/9c01e921/attachment-0001.html
More information about the calendarserver-changes
mailing list