[CalendarServer-changes] [10026] CalendarServer/trunk/doc/Extensions
source_changes at macosforge.org
source_changes at macosforge.org
Tue Nov 13 09:07:03 PST 2012
Revision: 10026
http://trac.calendarserver.org//changeset/10026
Author: cdaboo at apple.com
Date: 2012-11-13 09:07:03 -0800 (Tue, 13 Nov 2012)
Log Message:
-----------
Updated proxy spec to include current behaviors.
Modified Paths:
--------------
CalendarServer/trunk/doc/Extensions/caldav-proxy.txt
CalendarServer/trunk/doc/Extensions/caldav-proxy.xml
Modified: CalendarServer/trunk/doc/Extensions/caldav-proxy.txt
===================================================================
--- CalendarServer/trunk/doc/Extensions/caldav-proxy.txt 2012-11-13 01:02:14 UTC (rev 10025)
+++ CalendarServer/trunk/doc/Extensions/caldav-proxy.txt 2012-11-13 17:07:03 UTC (rev 10026)
@@ -2,12 +2,11 @@
Calendar Server Extension C. Daboo
- Apple Computer
- May 3, 2007
+ Apple Inc.
+ November 13, 2012
Calendar User Proxy Functionality in CalDAV
- caldav-cu-proxy-02
Abstract
@@ -25,14 +24,18 @@
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
+ 5.1. Feature Discovery . . . . . . . . . . . . . . . . . . . . 4
+ 5.2. Proxy Principal Resource . . . . . . . . . . . . . . . . . 4
+ 5.3. New Principal Properties . . . . . . . . . . . . . . . . . 8
+ 5.3.1. CS:calendar-proxy-read-for Property . . . . . . . . . 8
+ 5.3.2. CS:calendar-proxy-write-for Property . . . . . . . . . 8
+ 5.4. Privilege Provisioning . . . . . . . . . . . . . . . . . . 9
+ 6. Security Considerations . . . . . . . . . . . . . . . . . . . 10
+ 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
+ 8. Normative References . . . . . . . . . . . . . . . . . . . . . 10
+ Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 11
+ Appendix B. Change History . . . . . . . . . . . . . . . . . . . 11
+ Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 12
@@ -49,12 +52,9 @@
-
-
-
Daboo [Page 1]
- CalDAV Proxy May 2007
+ CalDAV Proxy November 2012
1. Introduction
@@ -110,7 +110,7 @@
Daboo [Page 2]
- CalDAV Proxy May 2007
+ CalDAV Proxy November 2012
this namespace are referenced in this document outside of the context
@@ -146,9 +146,13 @@
"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".
+ giving the CALDAV:schedule privilege [RFC6638] to the read-write
+ "proxy group".
+ On each user principal resource, the server maintains two WebDAV
+ properties containing lists of other user principals for which the
+ target principal is a read-only or read-write proxy.
+
3.2. Client
A client can see who the proxies are for the current principal by
@@ -157,24 +161,22 @@
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
+ CalDAV Proxy November 2012
- 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".
+ group" principal resource.
+ The client can find out who the current principal is a proxy for by
+ examining the CS:calendar-proxy-read-for and CS:calendar-proxy-write-
+ for properties, possibly using the DAV:expand-property REPORT to get
+ other useful properties about the principals being proxied for.
+
4. Open Issues
1. Do we want to separate read-write access to calendars vs the
@@ -194,8 +196,14 @@
5. New features in CalDAV
-5.1. Proxy Principal Resource
+5.1. Feature Discovery
+ A server that supports the features described in this document MUST
+ include "calendar-proxy" as a field in the DAV response header from
+ an OPTIONS request on any resource that supports these features.
+
+5.2. 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
@@ -209,6 +217,14 @@
resources that are groups contain the list of principals for calendar
users who can act as a read-only or read-write proxy respectively.
+
+
+
+Daboo [Page 4]
+
+ CalDAV Proxy November 2012
+
+
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
@@ -216,15 +232,6 @@
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>
@@ -265,24 +272,25 @@
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
+ CalDAV Proxy November 2012
<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:
+
+ <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>
@@ -324,17 +332,9 @@
-
-
-
-
-
-
-
-
Daboo [Page 6]
- CalDAV Proxy May 2007
+ CalDAV Proxy November 2012
>> Response <<
@@ -390,11 +390,84 @@
Daboo [Page 7]
- CalDAV Proxy May 2007
+ CalDAV Proxy November 2012
-5.2. Privilege Provisioning
+5.3. New Principal Properties
+ Each "regular" principal that is a proxy for other principals MUST
+ have the CS:calendar-proxy-read-for and CS:calendar-proxy-write-for
+ WebDAV properties available on its principal resource, to allow
+ clients to quickly find the "proxy for" information.
+
+5.3.1. CS:calendar-proxy-read-for Property
+
+ Name: calendar-proxy-read-for
+
+ Namespace: http://calendarserver.org/ns/
+
+ Purpose: Lists principals for whom the current principal is a read-
+ only proxy for.
+
+ Protected: This property MUST be protected.
+
+ PROPFIND behavior: This property SHOULD NOT be returned by a
+ PROPFIND allprop request (as defined in Section 14.2 of
+ [RFC4918]).
+
+ Description: This property allows a client to quickly determine the
+ principal for whom the current principal is a read-only proxy for.
+ The server MUST account for any group memberships of the current
+ principal that are either direct or indirect members of a proxy
+ group. e.g., if principal "A" assigns a group "G" as a read-only
+ proxy, and principal "B" is a member of group "G", then principal
+ "B" will see principal "A" listed in the CS:calendar-proxy-read-
+ for property on their principal resource.
+
+ Definition:
+
+ <!ELEMENT calendar-proxy-read-for (DAV:href*)>
+
+5.3.2. CS:calendar-proxy-write-for Property
+
+ Name: calendar-proxy-write-for
+
+ Namespace: http://calendarserver.org/ns/
+
+ Purpose: Lists principals for whom the current principal is a read-
+ write proxy for.
+
+ Protected: This property MUST be protected.
+
+
+
+
+
+
+Daboo [Page 8]
+
+ CalDAV Proxy November 2012
+
+
+ PROPFIND behavior: This property SHOULD NOT be returned by a
+ PROPFIND allprop request (as defined in Section 14.2 of
+ [RFC4918]).
+
+ Description: This property allows a client to quickly determine the
+ principal for whom the current principal is a read-write proxy
+ for. The server MUST account for any group memberships of the
+ current principal that are either direct or indirect members of a
+ proxy group. e.g., if principal "A" assigns a group "G" as a read-
+ write proxy, and principal "B" is a member of group "G", then
+ principal "B" will see principal "A" listed in the CS:calendar-
+ proxy-write-for property on their principal resource.
+
+ Definition:
+
+ <!ELEMENT calendar-proxy-write-for (DAV:href*)>
+
+5.4. 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:
@@ -407,14 +480,31 @@
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.
+ schedule privilege [RFC6638] 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:
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo [Page 9]
+
+ CalDAV Proxy November 2012
+
+
+ /
+ calendars/
+ users/
@@ -440,15 +530,6 @@
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>
@@ -471,12 +552,15 @@
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
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+
+
+Daboo [Page 10]
+
+ CalDAV Proxy November 2012
+
+
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D.
@@ -484,40 +568,55 @@
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.
+ 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.
+ [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed
+ Authoring and Versioning (WebDAV)", RFC 4918, June 2007.
+ [RFC6638] Daboo, C. and B. Desruisseaux, "Scheduling Extensions to
+ CalDAV", RFC 6638, June 2012.
+
+
Appendix A. Acknowledgments
This specification is the result of discussions between the Apple
calendar server and client teams.
+Appendix B. Change History
+ Changes in -03:
-Daboo [Page 9]
-
- CalDAV Proxy May 2007
+ 1. Added OPTIONS DAV header token.
+ 2. Added CS:calendar-proxy-read-for and CS:calendar-proxy-write-for
+ properties for faster discovery of proxy relationships.
-Appendix B. Change History
+ Changes in -02:
- Changes from -00:
-
1. Updated to RFC 4791 reference.
- Changes from -00:
+ Changes in -01:
1. Added more details on actual CalDAV protocol changes.
2. Changed namespace from http://apple.com/ns/calendarserver/ to
http://calendarserver.org/ns/.
+
+
+
+
+Daboo [Page 11]
+
+ CalDAV Proxy November 2012
+
+
3. Made "proxy group" principals child resources of their "owner"
principals.
@@ -527,7 +626,7 @@
Author's Address
Cyrus Daboo
- Apple Computer, Inc.
+ Apple, Inc.
1 Infinite Loop
Cupertino, CA 95014
USA
@@ -556,5 +655,18 @@
-Daboo [Page 10]
+
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo [Page 12]
Modified: CalendarServer/trunk/doc/Extensions/caldav-proxy.xml
===================================================================
--- CalendarServer/trunk/doc/Extensions/caldav-proxy.xml 2012-11-13 01:02:14 UTC (rev 10025)
+++ CalendarServer/trunk/doc/Extensions/caldav-proxy.xml 2012-11-13 17:07:03 UTC (rev 10026)
@@ -1,11 +1,12 @@
<?xml version="1.0" encoding="UTF-8"?>
+<?xml-stylesheet type="text/xsl" href="../rfc2629.xslt"?>
<!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'>
+<!ENTITY rfc4918 PUBLIC '' 'bibxml/reference.RFC.4918.xml'>
+<!ENTITY rfc6638 PUBLIC '' 'bibxml/reference.RFC.6638.xml'>
]>
<?rfc toc="yes"?>
<?rfc tocdepth="4"?>
@@ -17,12 +18,12 @@
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<?rfc private="Calendar Server Extension"?>
-<rfc ipr="none" docName='caldav-cu-proxy-02'>
+<rfc ipr="none" docName='caldav-cu-proxy-03'>
<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 abbrev="Apple Inc.">
+ Apple, Inc.
</organization>
<address>
<postal>
@@ -36,7 +37,7 @@
<uri>http://www.apple.com/</uri>
</address>
</author>
- <date year='2007'/>
+ <date/>
<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.
@@ -94,10 +95,13 @@
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".
+ Add an ACE to each of the calendar Inbox and Outbox collections giving the <xref target='RFC6638'>CALDAV:schedule privilege</xref> to the read-write "proxy group".
</t>
</list>
</t>
+ <t>
+ On each user principal resource, the server maintains two WebDAV properties containing lists of other user principals for which the target principal is a read-only or read-write proxy.
+ </t>
</section>
<section title='Client'>
<t>
@@ -107,11 +111,8 @@
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.
+ The client can find out who the current principal is a proxy for by examining the CS:calendar-proxy-read-for and CS:calendar-proxy-write-for properties, possibly using the DAV:expand-property REPORT to get other useful properties about the principals being proxied for.
</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>
@@ -135,6 +136,11 @@
</section>
<section title='New features in CalDAV' anchor='changes'>
+ <section title="Feature Discovery">
+ <t>
+ A server that supports the features described in this document MUST include "calendar-proxy" as a field in the DAV response header from an OPTIONS request on any resource that supports these features.
+ </t>
+ </section>
<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.
@@ -279,6 +285,47 @@
</figure>
</t>
</section>
+ <section title="New Principal Properties">
+ <t>
+ Each "regular" principal that is a proxy for other principals MUST have the CS:calendar-proxy-read-for and CS:calendar-proxy-write-for WebDAV properties available on its principal resource, to allow clients to quickly find the "proxy for" information.
+ </t>
+ <section title="CS:calendar-proxy-read-for Property">
+ <t>
+ <list style="hanging">
+ <t hangText="Name:">calendar-proxy-read-for</t>
+ <t hangText="Namespace:">http://calendarserver.org/ns/</t>
+ <t hangText="Purpose:">Lists principals for whom the current principal is a read-only proxy for.</t>
+ <t hangText="Protected:">This property MUST be protected.</t>
+ <t hangText="PROPFIND behavior:">This property SHOULD NOT be returned by a PROPFIND allprop request (as defined in Section 14.2 of <xref target="RFC4918"/>).</t>
+
+ <t hangText="Description:">This property allows a client to quickly determine the principal for whom the current principal is a read-only proxy for. The server MUST account for any group memberships of the current principal that are either direct or indirect members of a proxy group. e.g., if principal "A" assigns a group "G" as a read-only proxy, and principal "B" is a member of group "G", then principal "B" will see principal "A" listed in the CS:calendar-proxy-read-for property on their principal resource.</t>
+ <t hangText="Definition:">
+ <figure><artwork><![CDATA[
+ <!ELEMENT calendar-proxy-read-for (DAV:href*)>
+]]></artwork></figure>
+ </t>
+ </list>
+ </t>
+ </section>
+ <section title="CS:calendar-proxy-write-for Property">
+ <t>
+ <list style="hanging">
+ <t hangText="Name:">calendar-proxy-write-for</t>
+ <t hangText="Namespace:">http://calendarserver.org/ns/</t>
+ <t hangText="Purpose:">Lists principals for whom the current principal is a read-write proxy for.</t>
+ <t hangText="Protected:">This property MUST be protected.</t>
+ <t hangText="PROPFIND behavior:">This property SHOULD NOT be returned by a PROPFIND allprop request (as defined in Section 14.2 of <xref target="RFC4918"/>).</t>
+
+ <t hangText="Description:">This property allows a client to quickly determine the principal for whom the current principal is a read-write proxy for. The server MUST account for any group memberships of the current principal that are either direct or indirect members of a proxy group. e.g., if principal "A" assigns a group "G" as a read-write proxy, and principal "B" is a member of group "G", then principal "B" will see principal "A" listed in the CS:calendar-proxy-write-for property on their principal resource.</t>
+ <t hangText="Definition:">
+ <figure><artwork><![CDATA[
+ <!ELEMENT calendar-proxy-write-for (DAV:href*)>
+]]></artwork></figure>
+ </t>
+ </list>
+ </t>
+ </section>
+ </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:
@@ -286,7 +333,7 @@
<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.
+ Additionally, the CalDAV scheduling Inbox and Outbox calendar collections for the user allowing proxy access, MUST have the <xref target='RFC6638'>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:
@@ -348,7 +395,8 @@
&rfc2518;
&rfc3744;
&rfc4791;
- &I-D.desruisseaux-caldav-sched;
+ &rfc4918;
+ &rfc6638;
</references>
<!--
<references title='Informative References'>
@@ -360,14 +408,24 @@
</t>
</section>
<section title='Change History'>
- <t>Changes from -00:
+ <t>Changes in -03:
<list style='numbers'>
<t>
+ Added OPTIONS DAV header token.
+ </t>
+ <t>
+ Added CS:calendar-proxy-read-for and CS:calendar-proxy-write-for properties for faster discovery of proxy relationships.
+ </t>
+ </list>
+ </t>
+ <t>Changes in -02:
+ <list style='numbers'>
+ <t>
Updated to RFC 4791 reference.
</t>
</list>
</t>
- <t>Changes from -00:
+ <t>Changes in -01:
<list style='numbers'>
<t>
Added more details on actual CalDAV protocol changes.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.macosforge.org/pipermail/calendarserver-changes/attachments/20121113/fe487230/attachment-0001.html>
More information about the calendarserver-changes
mailing list