[CalendarServer-changes] [6402] CalendarServer/trunk/doc/RFC
source_changes at macosforge.org
source_changes at macosforge.org
Wed Oct 6 07:56:17 PDT 2010
Revision: 6402
http://trac.macosforge.org/projects/calendarserver/changeset/6402
Author: cdaboo at apple.com
Date: 2010-10-06 07:56:16 -0700 (Wed, 06 Oct 2010)
Log Message:
-----------
Updated specs.
Modified Paths:
--------------
CalendarServer/trunk/doc/RFC/draft-daboo-srv-caldav.txt
CalendarServer/trunk/doc/RFC/draft-daboo-webdav-sync.txt
Modified: CalendarServer/trunk/doc/RFC/draft-daboo-srv-caldav.txt
===================================================================
--- CalendarServer/trunk/doc/RFC/draft-daboo-srv-caldav.txt 2010-10-06 14:54:17 UTC (rev 6401)
+++ CalendarServer/trunk/doc/RFC/draft-daboo-srv-caldav.txt 2010-10-06 14:56:16 UTC (rev 6402)
@@ -3,80 +3,84 @@
Network Working Group C. Daboo
Internet-Draft Apple Inc.
-Intended status: Standards Track October 4, 2009
-Expires: April 7, 2010
+Updates: 4791,CardDAV-RFC-to-be September 16, 2010
+(if approved)
+Intended status: Standards Track
+Expires: March 20, 2011
- Use of SRV records for locating CalDAV and CardDAV services
- draft-daboo-srv-caldav-01
+ Locating CalDAV and CardDAV services
+ draft-daboo-srv-caldav-10
+Abstract
+
+ This specification describes how DNS SRV records, DNS TXT records and
+ well-known URIs can be used together or separately to locate
+ Calendaring Extensions to WebDAV (CalDAV) or vCard Extensions to
+ WebDAV (CardDAV) services.
+
Status of This Memo
- This Internet-Draft is submitted to IETF in full conformance with the
+ This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
- Task Force (IETF), its areas, and its working groups. Note that
- other groups may also distribute working documents as Internet-
- Drafts.
+ Task Force (IETF). Note that other groups may also distribute
+ working documents as Internet-Drafts. The list of current Internet-
+ Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
- The list of current Internet-Drafts can be accessed at
- http://www.ietf.org/ietf/1id-abstracts.txt.
+ This Internet-Draft will expire on March 20, 2011.
- The list of Internet-Draft Shadow Directories can be accessed at
- http://www.ietf.org/shadow.html.
-
- This Internet-Draft will expire on April 7, 2010.
-
Copyright Notice
- Copyright (c) 2009 IETF Trust and the persons identified as the
+ Copyright (c) 2010 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
- Provisions Relating to IETF Documents in effect on the date of
- publication of this document (http://trustee.ietf.org/license-info).
- Please review these documents carefully, as they describe your rights
- and restrictions with respect to this document.
+ Provisions Relating to IETF Documents
+ (http://trustee.ietf.org/license-info) in effect on the date of
+ publication of this document. Please review these documents
+ carefully, as they describe your rights and restrictions with respect
+ to this document. Code Components extracted from this document must
+ include Simplified BSD License text as described in Section 4.e of
+ the Trust Legal Provisions and are provided without warranty as
-Abstract
- This specification describes how SRV records and well-known URIs can
- be used to locate Calendaring Extensions to WebDAV (CalDAV) or vCard
- Extensions to WebDAV (CardDAV) services.
+Daboo Expires March 20, 2011 [Page 1]
+
+Internet-Draft SRV for CalDAV & CardDAV September 2010
-Daboo Expires April 7, 2010 [Page 1]
-
-Internet-Draft SRV for CalDAV October 2009
+ described in the Simplified BSD License.
-
Table of Contents
- 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
- 2. Conventions Used in This Document . . . . . . . . . . . . . . . 3
- 3. CalDAV SRV Service Types . . . . . . . . . . . . . . . . . . . 4
- 4. CalDAV and CardDAV Service Well-Known URI . . . . . . . . . . . 4
- 4.1. Example: well-known URI as context path . . . . . . . . . . 4
- 4.2. Example: well-known URI redirects to actual context
- path . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
- 5. Client "Bootstrapping" Guidelines . . . . . . . . . . . . . . . 5
- 6. Security Considerations . . . . . . . . . . . . . . . . . . . . 6
- 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 6
- 7.1. caldav Well-Known URI Registration . . . . . . . . . . . . 7
- 7.2. carddav Well-Known URI Registration . . . . . . . . . . . . 7
- 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . 7
- 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7
- 9.1. Normative References . . . . . . . . . . . . . . . . . . . 7
- 9.2. Informative References . . . . . . . . . . . . . . . . . . 8
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
+ 2. Conventions Used in This Document . . . . . . . . . . . . . . 4
+ 3. CalDAV SRV Service Labels . . . . . . . . . . . . . . . . . . 4
+ 4. CalDAV and CardDAV Service TXT Records . . . . . . . . . . . . 4
+ 5. CalDAV and CardDAV Service Well-Known URI . . . . . . . . . . 5
+ 5.1. Example: well-known URI redirects to actual context
+ path . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
+ 6. Client "Bootstrapping" Procedures . . . . . . . . . . . . . . 5
+ 7. Guidance for Service Providers . . . . . . . . . . . . . . . . 8
+ 8. Security Considerations . . . . . . . . . . . . . . . . . . . 9
+ 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
+ 9.1. caldav Well-Known URI Registration . . . . . . . . . . . . 10
+ 9.2. carddav Well-Known URI Registration . . . . . . . . . . . 10
+ 9.3. SRV Service Label Registration . . . . . . . . . . . . . . 10
+ 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 10
+ 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 10
+ 11.1. Normative References . . . . . . . . . . . . . . . . . . . 10
+ 11.2. Informative References . . . . . . . . . . . . . . . . . . 12
Appendix A. Change History (to be removed prior to
- publication as an RFC) . . . . . . . . . . . . . . . . 9
+ publication as an RFC) . . . . . . . . . . . . . . . 13
@@ -104,33 +108,32 @@
-
-
-
-
-Daboo Expires April 7, 2010 [Page 2]
+Daboo Expires March 20, 2011 [Page 2]
-Internet-Draft SRV for CalDAV October 2009
+Internet-Draft SRV for CalDAV & CardDAV September 2010
1. Introduction
- [RFC2782] defines a DNS-based service discovery protocol that has
- been widely adopted as a means of locating particular services within
- a local area network and beyond, using SRV RR records.
-
- [RFC4791] defines the CalDAV Calendar Access protocol, based on HTTP
+ [RFC4791] defines the CalDAV calendar access protocol, based on HTTP
[RFC2616], for accessing calendar data stored on a server. CalDAV
clients need to be able to discover appropriate CalDAV servers within
their local area network and at other domains, e.g., to minimize the
- need for end users to know specific details such as hostname and port
- for their servers.
+ need for end users to know specific details such as the fully
+ qualified domain name (FQDN) and port number for their servers.
- [I-D.ietf-vcarddav-carddav] defines the CardDAV vCard Access protocol
- based on HTTP [RFC2616], for accessing contact data stored on a
- server. As with CalDAV, clients also need to be able to discover
- CardDAV servers.
+ [I-D.ietf-vcarddav-carddav] defines the CardDAV address book access
+ protocol based on HTTP [RFC2616], for accessing contact data stored
+ on a server. As with CalDAV, clients also need to be able to
+ discover CardDAV servers.
+ [RFC2782] defines a DNS-based service discovery protocol that has
+ been widely adopted as a means of locating particular services within
+ a local area network and beyond, using DNS SRV Resource Records
+ (RRs). This has been enhanced to provide additional service meta-
+ data by use of DNS TXT Resource Records as per
+ [I-D.cheshire-dnsext-dns-sd].
+
This specification defines new SRV service types for the CalDAV
protocol, and gives an example of how clients can use this together
with other protocol features to enable simple client configuration.
@@ -138,51 +141,52 @@
[I-D.ietf-vcarddav-carddav].
Another issue with CalDAV or CardDAV service discovery is that the
- service may not be located at the "root" URI of the HTTP server
- hosting it. For example, if CalDAV is implemented as a "servlet" in
- a web server "container", the servlet "context path" might be
+ service might not be located at the "root" URI of the HTTP server
+ hosting it. Thus a client needs to be able to determine the complete
+ path component of the Request-URI to use in HTTP requests: the
+ "context path". For example, if CalDAV is implemented as a "servlet"
+ in a web server "container", the servlet "context path" might be
"/caldav/". So the URI for the CalDAV service would be, e.g.,
"http://caldav.example.com/caldav/" rather than
- "http://caldav.example.com/". SRV records by themselves only provide
- a hostname and port for the service, not a path. Since the client
+ "http://caldav.example.com/". SRV RRs by themselves only provide a
+ FQDN and port number for the service, not a path. Since the client
"bootstrapping" process requires initial access to the "context path"
of the service, there needs to be a simple way for clients to also
discover what that path is.
This specification makes use of the "well known URI" feature
- [I-D.nottingham-site-meta] of HTTP servers to provide a well known
- URI for CalDAV or CardDAV services that clients can make use of. The
- well known URI will point to a resource on the server that might be
- the actual "context path" of the CalDAV or CardDAV service, or it
- might simply be a "stub" resource that provides a redirect to the
- actual "context path".
+ [RFC5785] of HTTP servers to provide a well known URI for CalDAV or
+ CardDAV services that clients can make use of. The well known URI
+ will point to a resource on the server that is simply a "stub"
+ resource that provides a redirect to the actual "context path"
+ resource representing the service endpoint.
-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
-
-Daboo Expires April 7, 2010 [Page 3]
+Daboo Expires March 20, 2011 [Page 3]
-Internet-Draft SRV for CalDAV October 2009
+Internet-Draft SRV for CalDAV & CardDAV September 2010
+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].
-3. CalDAV SRV Service Types
+3. CalDAV SRV Service Labels
- This specification adds two service types for use with SRV records:
+ This specification adds two SRV service labels for use with CalDAV:
- caldav: Identifies a CalDAV server that uses HTTP without transport
+ _caldav: Identifies a CalDAV server that uses HTTP without transport
layer security ([RFC2818]).
- caldavs: Identifies a CalDAV server that uses HTTP with transport
+ _caldavs: Identifies a CalDAV server that uses HTTP with transport
layer security ([RFC2818]).
- Clients SHOULD honor "TTL", "Priority" and "Weight" values in the SRV
- records, as described by [RFC2782].
+ Clients MUST honor "Priority" and "Weight" values in the SRV RRs, as
+ described by [RFC2782].
Example: service record for server without transport layer security
@@ -192,152 +196,316 @@
_caldavs._tcp SRV 0 1 443 calendar.example.com.
-4. CalDAV and CardDAV Service Well-Known URI
+4. CalDAV and CardDAV Service TXT Records
- Two "well-known" URIs are registered by this specification for CalDAV
- and CardDAV services, "caldav" and "carddav" respectively (see
- Section 7). These URIs point to a resource that the client can use
- as the "context path" for the service they are trying to use. The
- actual service could be located at that specific path. Alternatively
- the server MAY redirect HTTP requests for that resource (using the
- "301 Moved Permanently" status response) to the actual "context
- path". Clients MUST handle HTTP redirects on the well-known URI.
+ When SRV RRs are used to advertise CalDAV and CardDAV services, it is
+ also convenient to be able to specify a "context path" in the DNS to
+ be retrieved at the same time. To enable that, this specification
+ uses a TXT RR that follows the syntax defined in Section 6 of
+ [I-D.cheshire-dnsext-dns-sd] and defines a "path" key for use in that
+ record. The value of the key MUST be the actual "context path" to
+ the corresponding service on the server.
-4.1. Example: well-known URI as context path
+ A site might provide TXT records in addition to SRV records for each
+ service. When present, clients MUST use the "path" value as the
+ "context path" for the service in HTTP requests. When not present,
+ clients use the ".well-known" URI approach described next.
- A CalDAV server has a "context path" that is the same as the well-
- known URI, so the client will use "/.well-known/caldav" as the path
- for its "bootstrapping" process after it has first found the hostname
- and port via an SRV lookup.
+ Example: text record for service with transport layer security
-4.2. Example: well-known URI redirects to actual context path
+ _caldavs._tcp TXT path=/caldav
+
+
+
+
+
+Daboo Expires March 20, 2011 [Page 4]
+
+Internet-Draft SRV for CalDAV & CardDAV September 2010
+
+
+5. CalDAV and CardDAV Service Well-Known URI
+
+ Two ".well-known" URIs are registered by this specification for
+ CalDAV and CardDAV services, "caldav" and "carddav" respectively (see
+ Section 9). These URIs point to a resource that the client can use
+ as the initial "context path" for the service they are trying to
+ connect to. The server MUST redirect HTTP requests for that resource
+ to the actual "context path" using one of the available mechanisms
+ provided by HTTP (e.g., using a 301, 303, 307 response). Clients
+ MUST handle HTTP redirects on the ".well-known" URI. Servers MUST
+ NOT locate the actual CalDAV or CardDAV service endpoint at the
+ ".well-known" URI as per Section 1.1 of [RFC5785].
+
+ Servers SHOULD set an appropriate Cache-Control header value (as per
+ Section 14.9 of [RFC2616]) in the redirect response to ensure caching
+ occurs or does not occur as needed, or as required by the type of
+ response generated. For example, if it is anticipated that the
+ location of the redirect might change over time, then a "no-cache"
+ value would be used.
+
+ To facilitate "context path's" that might differ from user to user,
+ the server MAY require authentication when a client tries to access
+ the ".well-known" URI (i.e., the server would return a 401 status
+ response to the unauthenticated request from the client, then return
+ the redirect response only after a successful authentication by the
+ client).
+
+5.1. Example: well-known URI redirects to actual context path
+
A CalDAV server has a "context path" that is "/servlet/caldav". The
client will use "/.well-known/caldav" as the path for its
- "bootstrapping" process after it has first found the hostname and
- port via an SRV lookup. When the client makes its initial HTTP
- request against "/.well-known/caldav", the server would issue an HTTP
+ "bootstrapping" process after it has first found the FQDN and port
+ number via an SRV lookup or via manual entry of information by the
+ user which the client can parse suitable information from. When the
+ client makes an HTTP request against "/.well-known/caldav", the
+ server would issue an HTTP redirect response with a Location response
+ header using the path "/servlet/caldav". The client would then
+ "follow" this redirect to the new resource and continue making HTTP
+ requests there to complete its "bootstrapping" process.
+6. Client "Bootstrapping" Procedures
+ This section describes a procedure that CalDAV or CardDAV clients
+ SHOULD use to do their initial configuration based on minimal user
+ input. The goal is to determine an http: or https: URI that
+ describes the full path to the user's principal-URL [RFC3744].
-Daboo Expires April 7, 2010 [Page 4]
+
+
+
+
+Daboo Expires March 20, 2011 [Page 5]
-Internet-Draft SRV for CalDAV October 2009
+Internet-Draft SRV for CalDAV & CardDAV September 2010
- 301 redirect response with a Location response header using the path
- "/servlet/caldav". The client would then "follow" this redirect to
- the new resource and continue making HTTP requests there to complete
- its "bootstrapping" process.
+ 1. Processing user input:
-5. Client "Bootstrapping" Guidelines
+ * For a CalDAV server:
- This section describes a procedure that CalDAV or CardDAV clients MAY
- use to do their initial configuration based on minimal user input.
+ + Minimal input from a user would consist of a calendar user
+ address and a password. A calendar user address is defined
+ by iCalendar [RFC5545] to be a URI [RFC3986]. Provided a
+ user identifier and a domain name can be extracted from the
+ URI, this simple "bootstrap" configuration can be done.
- For a CalDAV server, minimal input from a user would consist of a
- calendar user address. A calendar user address is defined by
- iCalendar [RFC5545] to be a URI [RFC3986]. Provided a user
- identifier and a domain name can be extracted from the URI, this
- simple "bootstrap" configuration can be done.
+ + If the calendar user address is a "mailto:" [RFC2368] URI,
+ the "mailbox" portion of the URI is examined and the
+ "local-part" and "domain" portions extracted.
- If the calendar user address is a "mailto:" [RFC2368] URI, the
- "mailbox" portion of the URI is examined and the "local-part" and
- "domain" portions extracted. The "local-part" is used for the user
- identifier and the "domain" is used as the service domain.
+ + If the calendar user address is an "http:" [RFC2616] or
+ "https:" [RFC2818] URI, the "userinfo" and "host" portion
+ of the URI [RFC3986] is extracted.
- If the calendar user address is an "http:" [RFC2616] or "https:"
- [RFC2818] URI, the "userinfo" and "host" portion of the URI is
- extracted. The "userinfo" is used for the user identifier and the
- "host" is used as the service domain.
+ * For a CardDAV server:
- For a CardDAV server, minimal input from a user would consist of
- their email address [RFC5322] for the domain where the CardDAV
- service is hosted. The "mailbox" portion of the email address is
- examined and the "local-part" and "domain" portions extracted. The
- "local-part" is used for the user identifier and the "domain" is used
- as the service domain.
+ + Minimal input from a user would consist of their email
+ address [RFC5322] for the domain where the CardDAV service
+ is hosted, and a password. The "mailbox" portion of the
+ email address is examined and the "local-part" and "domain"
+ portions extracted.
- Once the user identifier and service domain have been extracted, the
- following is done:
+ 2. Determination of service FQDN and port number:
- 1. An SRV lookup for _caldavs._tcp (for CalDAV) or _carddavs._tcp
- (for CardDAV) is done against the extracted service domain.
+ * An SRV lookup for _caldavs._tcp (for CalDAV) or _carddavs._tcp
+ (for CardDAV) is done with the extracted "domain" as the
+ service domain.
- 2. If no result is found for that, the client can try _caldav._tcp
- (for CalDAV) or _carddav._tcp (for CardDAV) provided non-SSL
- connections are appropriate.
+ * If no result is found, the client can try _caldav._tcp (for
+ CalDAV) or _carddav._tcp (for CardDAV) provided non-SSL
+ connections are appropriate.
- 3. If an SRV record is returned the client extracts the server host
- name and port number.
+ * If an SRV record is returned, the client extracts the target
+ FQDN and port number. In the case of multiple SRV records
+ returned, the client MUST use the priority and weight fields
+ in the record to determine which one to pick (as per
+ [RFC2782]).
- 4. The client does an authenticated "PROPFIND" [RFC4791] request
- using the user identifier, host name and port number and a
+ * If an SRV record is not found, the client will need to prompt
+ the user to enter the FQDN and port number information
+ directly, or use some other heuristic, for example using the
+ extracted "domain" as the FQDN and default HTTPS or HTTP port
+ numbers. In this situation clients MUST first attempt an HTTP
+ connection with transport layer security.
-Daboo Expires April 7, 2010 [Page 5]
+Daboo Expires March 20, 2011 [Page 6]
-Internet-Draft SRV for CalDAV October 2009
+Internet-Draft SRV for CalDAV & CardDAV September 2010
- request URI of "/.well-known/caldav" (for CalDAV) or "/.well-
- known/carddav" (for CardDAV). The body of the request should
- include the DAV:current-user-principal [RFC5397] property as one
- of the properties to return. Note that clients MUST properly
- handle HTTP redirect responses for the request.
+ 3. Determination of initial "context path":
- 5. If the server returns a 404 Not Found HTTP status response to the
- request on the well-known URI, clients MAY try repeating the
- request on the "root" URI "/".
+ * When an SRV lookup is done and a valid SRV record returned,
+ the client MUST also query for a corresponding TXT record and
+ check for the presence of a "path" key in its response. If
+ present, the value of the "path" key is used for the initial
+ "context path".
- 6. If the DAV:current-user-principal property is returned on the
- initial request, the client uses that value for the principal-URI
- of the authenticated user. With that, it can do a "PROPFIND" on
- the principal-URI and discover additional properties for
- configuration.
+ * When an initial "context path" has not been determined from a
+ TXT record, the initial "context path" is taken to be "/.well-
+ known/caldav" (for CalDAV) or "/.well-known/carddav" (for
+ CardDAV).
- 7. If the DAV:current-user-principal property is not returned, then
- the client will need to request the principal-URI path from the
- user in order to continue with configuration.
+ * If the initial "context path" derived from a TXT record
+ generates HTTP errors when targeted by requests, the client
+ SHOULD repeat its bootstrap procedure using the appropriate
+ ".well-known" URI instead.
-6. Security Considerations
+ 4. Determination of user identifier:
+ * The client will need to make authenticated HTTP requests to
+ the service. Typically a "user identifier" is required for
+ some form of user/password authentication. When a user
+ identifier is required, clients MUST first use the "mailbox"
+ portion of the calendar user address provided by the user in
+ the case of a "mailto:" address, and if that results in an
+ authentication failure, SHOULD fall back to using the "local-
+ part" extracted from the "mailto:" address. For an "http:" or
+ "https:" calendar user address, the "userinfo" portion is used
+ as the user identifier for authentication. This is in line
+ with the guidance outlined in Section 7. If these user
+ identifiers result in authentication failure, the client
+ SHOULD prompt the user for a valid identifier.
+
+ 5. Connecting to the service:
+
+ * Subsequent to configuration, the client will make HTTP
+ requests to the service. When using "_caldavs" or "_carddavs"
+ services, a transport layer security negotiation is done
+ immediately upon connection. The client MUST do certificate
+ verification using the procedure outlined in Section 4 of
+ [I-D.saintandre-tls-server-id-check] in regard to verification
+ with an SRV RR as the starting point.
+
+ * The client does a "PROPFIND" [RFC4918] request with the
+ request URI set to the initial "context path". The body of
+ the request SHOULD include the DAV:current-user-principal
+ [RFC5397] property as one of the properties to return. Note
+
+
+
+Daboo Expires March 20, 2011 [Page 7]
+
+Internet-Draft SRV for CalDAV & CardDAV September 2010
+
+
+ that clients MUST properly handle HTTP redirect responses for
+ the request. The server will use the HTTP authentication
+ procedure outlined in [RFC2617] or use some other appropriate
+ authentication schemes to authenticate the user.
+
+ * If the server returns a 404 Not Found HTTP status response to
+ the request on the initial "context path", clients MAY try
+ repeating the request on the "root" URI "/" or prompt the user
+ for a suitable path.
+
+ * If the DAV:current-user-principal property is returned on the
+ request, the client uses that value for the principal-URL of
+ the authenticated user. With that, it can execute a
+ "PROPFIND" request on the principal-URL and discover
+ additional properties for configuration (e.g., calendar or
+ address book "home" collections).
+
+ * If the DAV:current-user-principal property is not returned,
+ then the client will need to request the principal-URL path
+ from the user in order to continue with configuration.
+
+ Once a successful account discovery step has been done, clients
+ SHOULD cache the service details that were successfully used (user
+ identity, principal-URL with full scheme/host/port details), and re-
+ use those when connecting again at a later time.
+
+ If a subsequent connection attempt fails, or authentication fails
+ persistently, clients SHOULD re-try the SRV lookup and account
+ discovery to "refresh" the cached data.
+
+7. Guidance for Service Providers
+
+ Service providers wanting to offer CalDAV or CardDAV services that
+ can be configured by clients using SRV records need to follow certain
+ procedures to ensure proper operation.
+
+ o CalDAV or CardDAV servers SHOULD be configured to allow
+ authentication with calendar user addresses (just taking the
+ "mailbox" portion of any "mailto:" URI) or email addresses
+ respectively, or "user identifiers" extracted from them. In the
+ former case, the addresses MUST NOT conflict with other forms of
+ permitted user login name. In the latter case, the extracted
+ "user identifiers" need to be unique across the server and MUST
+ NOT conflict with any login name on the server.
+
+ o Servers MUST force authentication for "PROPFIND" requests that
+ retrieve the DAV:current-user-principal property to ensure that
+ the value of the DAV:current-user-principal property returned
+
+
+
+Daboo Expires March 20, 2011 [Page 8]
+
+Internet-Draft SRV for CalDAV & CardDAV September 2010
+
+
+ corresponds to the principal-URL of the user making the request.
+
+ o If the service provider uses transport layer security, the service
+ provider MUST ensure a certificate is installed that can be
+ verified by clients using the procedure outlined in Section 4 of
+ [I-D.saintandre-tls-server-id-check] in regard to verification
+ with an SRV RR as the starting point.
+
+ o Install the appropriate SRV records for the offered services.
+ Optionally include TXT records.
+
+8. Security Considerations
+
Clients that support transport layer security as defined by [RFC2818]
- SHOULD try the "caldavs" or "carddavs" services first before trying
- the "caldav" or "carddav" services respectively. If a user has
+ SHOULD try the "_caldavs" or "_carddavs" services first before trying
+ the "_caldav" or "_carddav" services respectively. If a user has
explicitly requested a connection with transport layer security, the
- client MUST NOT use any service information returned for the "caldav"
- or "carddav" services. Clients MUST follow the certificate
- verification process specified in
+ client MUST NOT use any service information returned for the
+ "_caldav" or "_carddav" services. Clients MUST follow the
+ certificate verification process specified in
[I-D.saintandre-tls-server-id-check].
- A malicious attacker with access to the DNS server data can
- potentially cause clients to connect to any server chosen by the
- attacker. In the absence of a secure DNS option, clients SHOULD
- check that the host name returned in the SRV record matches the
- original service domain that was queried. If the host is not in the
- queried domain, clients SHOULD verify with the user that the SRV host
- name is suitable for use before executing any CalDAV or CardDAV
- requests against the host.
+ A malicious attacker with access to the DNS server data, or able to
+ get spoofed answers cached in a recursive resolver, can potentially
+ cause clients to connect to any server chosen by the attacker. In
+ the absence of a secure DNS option, clients SHOULD check that the
+ target FQDN returned in the SRV record matches the original service
+ domain that was queried. If the target FQDN is not in the queried
+ domain, clients SHOULD verify with the user that the SRV target FQDN
+ is suitable for use before executing any connections to the host.
+ Alternatively, if transport layer security is being used for the
+ service, clients MUST use the procedure outlined in Section 4 of
+ [I-D.saintandre-tls-server-id-check] to verify the service.
-7. IANA Considerations
+ Implementations of TLS [RFC5246], used as the basis for transport
+ layer security ([RFC2818]), typically support multiple versions of
+ the protocol as well as the older Secure Sockets Layer (SSL)
+ protocol. Because of known security vulnerabilities, clients and
+ servers MUST NOT request, offer, or use SSL 2.0. See Appendix E.2 of
+ [RFC5246] for further details.
- This document defines two "well-known" URIs using the registration
- procedure and template from Section 5.1 of
- [I-D.nottingham-site-meta].
+9. IANA Considerations
+ This document defines two ".well-known" URIs using the registration
+ procedure and template from Section 5.1 of [RFC5785].
-Daboo Expires April 7, 2010 [Page 6]
+
+Daboo Expires March 20, 2011 [Page 9]
-Internet-Draft SRV for CalDAV October 2009
+Internet-Draft SRV for CalDAV & CardDAV September 2010
-7.1. caldav Well-Known URI Registration
+9.1. caldav Well-Known URI Registration
URI suffix: caldav
@@ -347,7 +515,7 @@
Related information: See also [RFC4791].
-7.2. carddav Well-Known URI Registration
+9.2. carddav Well-Known URI Registration
URI suffix: carddav
@@ -357,45 +525,51 @@
Related information: See also [I-D.ietf-vcarddav-carddav].
-8. Acknowledgments
+9.3. SRV Service Label Registration
+ Service labels have been registered according to
+ <http://www.dns-sd.org/ServiceTypes.html> [1] and will be
+ incorporated into IANA once a new registry is available there.
+
+10. Acknowledgments
+
This specification was suggested by discussion that took place within
the Calendaring and Scheduling Consortium's CalDAV Technical
- Committee. The authors thank the participants of that group for
- their input. The "bootstrapping" process is based on diagrams
- developed by Wilfredo Sanchez.
+ Committee. The author thanks the following for their contributions:
+ Stuart Cheshire, Bernard Desruisseaux, Eran Hammer-Lahav, Helge Hess,
+ Arnaud Quillaud, Wilfredo Sanchez, and Joe Touch.
-9. References
+11. References
-9.1. Normative References
+11.1. Normative References
+ [I-D.cheshire-dnsext-dns-sd] Cheshire, S. and M. Krochmal,
+ "DNS-Based Service Discovery",
+ draft-cheshire-dnsext-dns-sd-06
+ (work in progress), March 2010.
+
[I-D.ietf-vcarddav-carddav] Daboo, C., "vCard Extensions to
WebDAV (CardDAV)",
- draft-ietf-vcarddav-carddav-09
+ draft-ietf-vcarddav-carddav-10
(work in progress),
- September 2009.
+ November 2009.
- [I-D.nottingham-site-meta] Nottingham, M. and E. Hammer-
- Lahav, "Defining Well-Known
- URIs",
- draft-nottingham-site-meta-03
- (work in progress),
- September 2009.
- [I-D.saintandre-tls-server-id-check] Saint-Andre, P., Zeilenga, K.,
- and J. Hodges, "Server Identity
- Verification in Application
-
-
-Daboo Expires April 7, 2010 [Page 7]
+Daboo Expires March 20, 2011 [Page 10]
-Internet-Draft SRV for CalDAV October 2009
+Internet-Draft SRV for CalDAV & CardDAV September 2010
- Protocols", draft-saintandre-
- tls-server-id-check-02 (work in
- progress), October 2009.
+ [I-D.saintandre-tls-server-id-check] Saint-Andre, P. and J. Hodges,
+ "Representation and
+ Verification of Domain-Based
+ Application Service Identity in
+ Certificates Used with
+ Transport Layer Security", draf
+ t-saintandre-tls-server-id-
+ check-09 (work in progress),
+ August 2010.
[RFC2119] Bradner, S., "Key words for use
in RFCs to Indicate Requirement
@@ -413,6 +587,14 @@
Transfer Protocol -- HTTP/1.1",
RFC 2616, June 1999.
+ [RFC2617] Franks, J., Hallam-Baker, P.,
+ Hostetler, J., Lawrence, S.,
+ Leach, P., Luotonen, A., and L.
+ Stewart, "HTTP Authentication:
+ Basic and Digest Access
+ Authentication", RFC 2617,
+ June 1999.
+
[RFC2782] Gulbrandsen, A., Vixie, P., and
L. Esibov, "A DNS RR for
specifying the location of
@@ -422,6 +604,21 @@
[RFC2818] Rescorla, E., "HTTP Over TLS",
RFC 2818, May 2000.
+ [RFC3744] Clemm, G., Reschke, J., Sedlar,
+ E., and J. Whitehead, "Web
+ Distributed Authoring and
+ Versioning (WebDAV)
+ Access Control Protocol",
+
+
+
+Daboo Expires March 20, 2011 [Page 11]
+
+Internet-Draft SRV for CalDAV & CardDAV September 2010
+
+
+ RFC 3744, May 2004.
+
[RFC3986] Berners-Lee, T., Fielding, R.,
and L. Masinter, "Uniform
Resource Identifier (URI):
@@ -433,34 +630,171 @@
Extensions to WebDAV (CalDAV)",
RFC 4791, March 2007.
-9.2. Informative References
+ [RFC4918] Dusseault, L., "HTTP Extensions
+ for Web Distributed Authoring
+ and Versioning (WebDAV)",
+ RFC 4918, June 2007.
+ [RFC5246] Dierks, T. and E. Rescorla,
+ "The Transport Layer Security
+ (TLS) Protocol Version 1.2",
+ RFC 5246, August 2008.
+
[RFC5322] Resnick, P., Ed., "Internet
Message Format", RFC 5322,
October 2008.
[RFC5397] Sanchez, W. and C. Daboo,
"WebDAV Current Principal
+ Extension", RFC 5397,
+ December 2008.
+ [RFC5785] Nottingham, M. and E. Hammer-
+ Lahav, "Defining Well-Known
+ Uniform Resource Identifiers
+ (URIs)", RFC 5785, April 2010.
+11.2. Informative References
-Daboo Expires April 7, 2010 [Page 8]
-
-Internet-Draft SRV for CalDAV October 2009
-
-
- Extension", RFC 5397,
- December 2008.
-
[RFC5545] Desruisseaux, B., "Internet
Calendaring and Scheduling Core
Object Specification
(iCalendar)", RFC 5545,
September 2009.
+URIs
+
+ [1] <http://www.dns-sd.org/ServiceTypes.html>
+
+
+
+Daboo Expires March 20, 2011 [Page 12]
+
+Internet-Draft SRV for CalDAV & CardDAV September 2010
+
+
Appendix A. Change History (to be removed prior to publication as an
RFC)
+ Changes in -09:
+
+ 1. IESG Review: minor editorial changes.
+
+ 2. GenART Review: minor editorial changes.
+
+ 3. GenART Review: "guideline" -> "procedure".
+
+ 4. GenART Review: "port" -> "port number".
+
+ 5. GenART Review: added definition of "context path".
+
+ 6. GenART Review: clarified OPTIONAL nature of suggested client
+ procedure.
+
+ 7. GenART Review: clarified that TXT lookup is an additional query.
+
+ 8. IESG Review: now allow any HTTP redirect response, not just 301.
+
+ 9. IESG Review: added text on cache interaction with redirect.
+
+ Changes in -10:
+
+ 1. AD Review: make client procedure a SHOULD.
+
+ Changes in -08:
+
+ 1. Clarify that email address is a valid input in Section 7 for
+ CardDAV.
+
+ 2. Clarified aspects of DAV:current-user-principal handling for
+ servers.
+
+ 3. Added additional text to indicate TXT being used in abstract and
+ introduction.
+
+ Changes in -07:
+
+ 1. Add password to required minimal user input
+
+ 2. Section 3 -> Section 4 of server-id check draft.
+
+ Changes in -06:
+
+
+
+
+
+Daboo Expires March 20, 2011 [Page 13]
+
+Internet-Draft SRV for CalDAV & CardDAV September 2010
+
+
+ 1. Last call comments: Revised title, abstract and text to indicate
+ that SRV and .well-known can be done separately.
+
+ 2. Revised IANA section to use dns-sd registry for now.
+
+ 3. Added optional TXT RR with path key for service context path in
+ the DNS
+
+ 4. Re-organized client bootstrap to take account of TXT and to call-
+ out the different "phases" involved via a numbered list.
+
+ Changes in -05:
+
+ 1. AD Review: Added "Updates" for 4791 and CardDAV.
+
+ 2. AD Review: Changed SHOULD to MUST for honoring priority and
+ weight.
+
+ 3. AD Review: Added additional reference to 3986 when talking about
+ userinfo/host portions of the URI.
+
+ 4. AD Review: Changed section reference for tls-server-id-check
+ draft.
+
+ 5. AD Review: Changed should to SHOULD when describing PROPFIND
+ request and made 5397 normative.
+
+ 6. AD Review: Made 3744 and 5322 normative references.
+
+ 7. AD Review: Added IANA SRV registration request.
+
+ Changes in -04:
+
+ 1. Added addition text to client guidelines indicating that clients
+ cache the discovery details and can re-do discovery if
+ connections later fail.
+
+ 2. Changed principal-URI to principal-URL.
+
+ Changes in -03:
+
+ 1. Updated to RFC 5785 reference.
+
+ 2. Added SSL v2 restriction from srv-email document added after IESG
+ review.
+
+ 3. Tweaked client/server guidelines to better match HTTP challenge/
+ response authentication mechanism.
+
+
+
+Daboo Expires March 20, 2011 [Page 14]
+
+Internet-Draft SRV for CalDAV & CardDAV September 2010
+
+
+ Changes in -02:
+
+ 1. Re-organized introduction.
+
+ 2. Brought terminology into line with srv-email document which has
+ been through last call.
+
+ 3. Brought security section into line with srv-email document which
+ has been through last call.
+
Changes in -01:
1. Added discovery of CardDAV service.
@@ -500,5 +834,7 @@
-Daboo Expires April 7, 2010 [Page 9]
+
+
+Daboo Expires March 20, 2011 [Page 15]
Modified: CalendarServer/trunk/doc/RFC/draft-daboo-webdav-sync.txt
===================================================================
--- CalendarServer/trunk/doc/RFC/draft-daboo-webdav-sync.txt 2010-10-06 14:54:17 UTC (rev 6401)
+++ CalendarServer/trunk/doc/RFC/draft-daboo-webdav-sync.txt 2010-10-06 14:56:16 UTC (rev 6402)
@@ -4,12 +4,12 @@
Network Working Group C. Daboo
Internet-Draft Apple, Inc.
Intended status: Standards Track A. Quillaud
-Expires: May 22, 2010 Sun Microsystems
- November 18, 2009
+Expires: April 8, 2011 Oracle
+ October 5, 2010
Collection Synchronization for WebDAV
- draft-daboo-webdav-sync-02
+ draft-daboo-webdav-sync-04
Abstract
@@ -27,48 +27,43 @@
Status of This Memo
- This Internet-Draft is submitted to IETF in full conformance with the
+ This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
- Task Force (IETF), its areas, and its working groups. Note that
- other groups may also distribute working documents as Internet-
- Drafts.
+ Task Force (IETF). Note that other groups may also distribute
+ working documents as Internet-Drafts. The list of current Internet-
+ Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
- The list of current Internet-Drafts can be accessed at
- http://www.ietf.org/ietf/1id-abstracts.txt.
+ This Internet-Draft will expire on April 8, 2011.
- The list of Internet-Draft Shadow Directories can be accessed at
- http://www.ietf.org/shadow.html.
+Copyright Notice
- This Internet-Draft will expire on May 22, 2010.
+ Copyright (c) 2010 IETF Trust and the persons identified as the
+ document authors. All rights reserved.
-Copyright Notice
+ This document is subject to BCP 78 and the IETF Trust's Legal
+ Provisions Relating to IETF Documents
-Daboo & Quillaud Expires May 22, 2010 [Page 1]
+Daboo & Quillaud Expires April 8, 2011 [Page 1]
-Internet-Draft WebDAV Sync November 2009
+Internet-Draft WebDAV Sync October 2010
- Copyright (c) 2009 IETF Trust and the persons identified as the
- document authors. All rights reserved.
-
- This document is subject to BCP 78 and the IETF Trust's Legal
- Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
- described in the BSD License.
+ described in the Simplified BSD License.
This document may contain material from IETF Documents or IETF
Contributions published or made publicly available before November
@@ -108,44 +103,53 @@
-Daboo & Quillaud Expires May 22, 2010 [Page 2]
-
-Internet-Draft WebDAV Sync November 2009
-Table of Contents
- 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
- 2. Conventions Used in This Document . . . . . . . . . . . . . . 3
- 3. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 4
- 4. WebDAV Synchronization . . . . . . . . . . . . . . . . . . . . 4
- 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 4
- 4.2. DAV:sync-collection report . . . . . . . . . . . . . . . . 5
- 4.3. Types of changes reported . . . . . . . . . . . . . . . . 7
- 4.3.1. New resource . . . . . . . . . . . . . . . . . . . . . 7
- 4.3.2. Modified resource . . . . . . . . . . . . . . . . . . 7
- 4.3.3. Removed resource . . . . . . . . . . . . . . . . . . . 7
- 4.4. Example: Initial DAV:sync-collection REPORT . . . . . . . 8
- 4.5. Example: DAV:sync-collection Report with token . . . . . . 10
- 5. DAV:sync-token Property . . . . . . . . . . . . . . . . . . . 11
- 6. XML Element Definitions . . . . . . . . . . . . . . . . . . . 12
- 6.1. DAV:sync-collection XML Element . . . . . . . . . . . . . 12
- 6.2. DAV:sync-token XML Element . . . . . . . . . . . . . . . . 12
- 6.3. DAV:multistatus XML Element . . . . . . . . . . . . . . . 13
- 6.4. DAV:sync-response XML Element . . . . . . . . . . . . . . 13
- 7. Security Considerations . . . . . . . . . . . . . . . . . . . 14
- 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14
- 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 14
- 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 14
- 10.1. Normative References . . . . . . . . . . . . . . . . . . . 14
- 10.2. Informative References . . . . . . . . . . . . . . . . . . 14
- Appendix A. Change History (to be removed prior to
- publication as an RFC) . . . . . . . . . . . . . . . 15
+Daboo & Quillaud Expires April 8, 2011 [Page 2]
+
+Internet-Draft WebDAV Sync October 2010
+Table of Contents
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
+ 2. Conventions Used in This Document . . . . . . . . . . . . . . 4
+ 3. WebDAV Synchronization . . . . . . . . . . . . . . . . . . . . 5
+ 3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 5
+ 3.2. DAV:sync-collection Report . . . . . . . . . . . . . . . . 6
+ 3.3. Depth behavior . . . . . . . . . . . . . . . . . . . . . . 7
+ 3.4. Types of Changes Reported on Initial Synchronization . . . 8
+ 3.5. Types of Changes Reported on Subsequent
+ Synchronizations . . . . . . . . . . . . . . . . . . . . . 8
+ 3.5.1. Changed Resource . . . . . . . . . . . . . . . . . . . 8
+ 3.5.2. Removed Resource . . . . . . . . . . . . . . . . . . . 9
+ 3.6. Truncation of Results . . . . . . . . . . . . . . . . . . 9
+ 3.7. Limiting Results . . . . . . . . . . . . . . . . . . . . . 10
+ 3.8. Example: Initial DAV:sync-collection Report . . . . . . . 11
+ 3.9. Example: DAV:sync-collection Report with Token . . . . . . 12
+ 3.10. Example: Initial DAV:sync-collection Report with
+ Truncation . . . . . . . . . . . . . . . . . . . . . . . . 15
+ 3.11. Example: Initial DAV:sync-collection Report with Limit . . 16
+ 3.12. Example: DAV:sync-collection Report with Unsupported
+ Limit . . . . . . . . . . . . . . . . . . . . . . . . . . 18
+ 3.13. Example: Depth:infinity initial DAV:sync-collection
+ Report . . . . . . . . . . . . . . . . . . . . . . . . . . 18
+ 4. DAV:sync-token Property . . . . . . . . . . . . . . . . . . . 21
+ 5. XML Element Definitions . . . . . . . . . . . . . . . . . . . 21
+ 5.1. DAV:sync-collection XML Element . . . . . . . . . . . . . 22
+ 5.2. DAV:sync-token XML Element . . . . . . . . . . . . . . . . 22
+ 5.3. DAV:multistatus XML Element . . . . . . . . . . . . . . . 22
+ 6. Security Considerations . . . . . . . . . . . . . . . . . . . 23
+ 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23
+ 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 23
+ 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 23
+ 9.1. Normative References . . . . . . . . . . . . . . . . . . . 23
+ 9.2. Informative References . . . . . . . . . . . . . . . . . . 24
+ Appendix A. Change History (to be removed prior to
+ publication as an RFC) . . . . . . . . . . . . . . . 24
@@ -160,13 +164,9 @@
-
-
-
-
-Daboo & Quillaud Expires May 22, 2010 [Page 3]
+Daboo & Quillaud Expires April 8, 2011 [Page 3]
-Internet-Draft WebDAV Sync November 2009
+Internet-Draft WebDAV Sync October 2010
1. Introduction
@@ -220,9 +220,9 @@
-Daboo & Quillaud Expires May 22, 2010 [Page 4]
+Daboo & Quillaud Expires April 8, 2011 [Page 4]
-Internet-Draft WebDAV Sync November 2009
+Internet-Draft WebDAV Sync October 2010
When an XML element type in the "DAV:" namespace is referenced in
@@ -232,29 +232,10 @@
This document inherits, and sometimes extends, DTD productions from
Section 14 of [RFC4918].
-3. Open Issues
+3. WebDAV Synchronization
- 1. We are extending the multistatus response element in a
- significant way. The DAV:sync-response differs from a regular
- DAV:response because, in the case of a created or modified
- resource, it contains both a DAV:status (201 for created, 200 for
- modified) and a DAV:propstat. The DAV:response on the other hand
- contains either a DAV:status or a DAV:propstat but not both.
- Shall we define a DAV:multisyncstatus response element instead of
- overloading DAV:multistatus ?
+3.1. Overview
- 2. Do clients really need to be notified that a resource was created
- versus modified ? They should be able to figure that out by
- looking at the state of their current cache. If this information
- is not necessary, the response would not need to contain a DAV:
- status along with the DAV:propstat. This would allow the use of
- a regular multistatus (simply extended with a sync-token
- element).
-
-4. WebDAV Synchronization
-
-4.1. Overview
-
One way to synchronize data between two entities is to use some form
of synchronization token. The token defines the state of the data
being synchronized at a particular point in time. It can then be
@@ -274,196 +255,320 @@
The server also returns a new token representing the new state at the
time the report was run.
-
-
-Daboo & Quillaud Expires May 22, 2010 [Page 5]
-
-Internet-Draft WebDAV Sync November 2009
-
-
- Typically the first time a client connects to the server it will need
- to be informed of the entire state of the collection (i.e., a full
- list of all resources that are currently contained in the
+ Typically, the first time a client connects to the server it will
+ need to be informed of the entire state of the collection (i.e., a
+ full list of all resources that are currently contained in the
collection). That is done by the client sending an empty token value
to the server. This indicates to the server that a full listing is
- required. As an alternative, the client may choose to do its first
+ required.
+
+ As an alternative, the client might choose to do its first
synchronization using some other mechanism on the collection (e.g.
some other form of batch resource information retrieval such as
PROPFIND, SEARCH [RFC5323], or specialized REPORTs such as those
defined in CalDAV [RFC4791] and CardDAV [I-D.ietf-vcarddav-carddav])
and ask for the DAV:sync-token property to be returned. This
- property (defined in Section 5) contains the same token that can be
+ property (defined in Section 4) contains the same token that can be
used later on to issue a DAV:sync-collection report.
- In some cases a server may only wish to maintain a limited amount of
- history about changes to a collection. In that situation it will
+ In some cases a server might only wish to maintain a limited amount
+ of history about changes to a collection. In that situation it will
+
+
+
+Daboo & Quillaud Expires April 8, 2011 [Page 5]
+
+Internet-Draft WebDAV Sync October 2010
+
+
return an error to the client when the client presents a token that
is "out of date". At that point the client has to fall back to
synchronizing the entire collection by re-running the report request
- using an empty token value. ACL changes may also cause a token to
- become invalid.
+ using an empty token value.
-4.2. DAV:sync-collection report
+3.2. DAV:sync-collection Report
- This specification defines the DAV:sync-collection report.
+ If the DAV:sync-collection report is implemented by a WebDAV server,
+ then the server MUST list the report in the "DAV:supported-report-
+ set" property on any collection supporting synchronization.
- If this report is implemented by a WebDAV server, then the server
- MUST list the report in the "DAV:supported-report-set" property on
- any collection supporting synchronization.
-
To implement the behavior for this report a server needs to keep
- track of changes to any resources in a collection. This includes
- noting the addition of new resources, changes to existing resources
- and removal of resources (where "removal" could be the result of a
- DELETE or MOVE WebDAV request). Only internal members of the
- collection (as defined in [RFC4918]) are to be considered. The
- server will track each change and provide a synchronization "token"
- to the client that describes the state of the server at a specific
- point in time. This "token" is returned as part of the response to
- the "sync-collection" report. Clients include the last token they
- got from the server in the next "sync-collection" report that they
- execute and the server provides the changes from the previous state,
- represented by the token, to the current state, represented by the
- new token returned.
+ track of changes to any member resources in a collection (as defined
+ in Section 3 of [RFC4918]). This includes noting the addition of new
+ resources, changes to existing resources and removal of resources.
+ The server will track each change and provide a synchronization
+ "token" to the client that describes the state of the server at a
+ specific point in time. This "token" is returned as part of the
+ response to the "sync-collection" report. Clients include the last
+ token they got from the server in the next "sync-collection" report
+ that they execute and the server provides the changes from the
+ previous state, represented by the token, to the current state,
+ represented by the new token returned.
The synchronization token itself is an "opaque" string - i.e., the
- actual string data has no specific meaning or syntax. A simple
- implementation of such a token would be a numeric counter that counts
+ actual string data has no specific meaning or syntax. For example, a
+ simple implementation of such a token could be a numeric counter that
+ counts each change as it occurs and relates that change to the
+ specific object that changed.
-
-
-Daboo & Quillaud Expires May 22, 2010 [Page 6]
-
-Internet-Draft WebDAV Sync November 2009
-
-
- each change as it occurs and relates that change to the specific
- object that changed.
-
Marshalling:
- The request URI MUST be a collection. The request body MUST be a
- DAV:sync-collection XML element (see Section 6.1), which MUST
- contain one DAV:sync-token XML element, and optionally a DAV:
- propstat XML element.
+ The request URI MUST identify a collection. The request body MUST
+ be a DAV:sync-collection XML element (see Section 5.1), which MUST
+ contain one DAV:sync-token XML element, and one DAV:prop XML
+ element, and MAY contain a DAV:limit XML element.
- The request MUST include a Depth header with a value of "1".
+ The request MUST include a Depth header with a value of "1" or
+ "infinity".
The response body for a successful request MUST be a DAV:
multistatus XML element, which MUST contain one DAV:sync-token
- element in addition to any DAV:sync-response elements.
-
- The response body for a successful DAV:sync-collection report
- request MUST contain a DAV:sync-response element for each resource
+ element in addition to one DAV:response element for each resource
that was created, has changed or been deleted since the last
synchronization operation as specified by the DAV:sync-token
provided in the request. A given resource MUST appear only once
in the response.
- The DAV:status element in each DAV:sync-response element is used
- to indicate how the resource may have changed:
- A status code of '201 Created' is used to indicate resources
- that are new.
- A status code of '200 OK' is used to indicate resources that
- have changed.
- A status code of '404 Not Found' is used to indicate resources
- that have been removed.
+Daboo & Quillaud Expires April 8, 2011 [Page 6]
+
+Internet-Draft WebDAV Sync October 2010
- The conditions under which each type of change may occur is
- further described in Section 4.3.
+ The content of each DAV:response element differs depending on how
+ the resource was altered:
+
+ For resources that have changed (i.e., are new or have been
+ modified) the DAV:response MUST contain at least one DAV:
+ propstat element and MUST NOT contain any DAV:status element.
+
+ For resources that have been removed, the DAV:response MUST
+ contain one DAV:status with a value set to '404 Not Found' and
+ MUST NOT contain any DAV:propstat element.
+
+ For child collection resources that are unable to support the
+ DAV:sync-collection report, the DAV:response MUST contain one
+ DAV:status with a value set to '405 Method Not Allowed' and
+ MUST NOT contain any DAV:propstat element.
+
+ The conditions under which each type of change can occur is
+ further described in Section 3.5.
+
Preconditions:
(DAV:valid-sync-token): The DAV:sync-token element value MUST map
to a valid token previously returned by the server. A token may
become invalid as the result of being "out of date" (out of the
range of change history maintained by the server), or for other
- reasons (e.g. collection deleted, then recreated, ACL changes,
- etc...).
+ reasons (e.g. collection deleted, then recreated, access control
+ changes, etc...).
Postconditions:
+ (DAV:number-of-matches-within-limits): The number of changes
+ reported in the response must fall within the client specified
+ limit. This condition might be triggered if a client requests a
+ limit on the number of responses (as per Section 3.7) but the
+ server is unable to truncate the result set at or below that
+ limit.
+3.3. Depth behavior
-Daboo & Quillaud Expires May 22, 2010 [Page 7]
+ The DAV:sync-collection report supports both Depth:1 and Depth:
+ infinity request headers.
+
+ o When the client specifies Depth:1, only additions, changes or
+ removals of immediate children of the collection specified as the
+ request URI are reported.
+
+ o When the client specifies Depth:infinity, additions, changes or
+ removals of any child resource of the collection specified as the
+
+
+
+Daboo & Quillaud Expires April 8, 2011 [Page 7]
-Internet-Draft WebDAV Sync November 2009
+Internet-Draft WebDAV Sync October 2010
- None.
+ request URI are reported, provided child collections themselves
+ also support the DAV:sync-collection report.
-4.3. Types of changes reported
+ o DAV:sync-token values returned by the server are not specific to
+ the value of the Depth header used in the request. As such
+ clients MAY use a DAV:sync-token value from a request with one
+ Depth value for a similar request with a different Depth value,
+ however the utility of this is limited.
- Three types of resource state changes can be returned by the DAV:
- sync-collection report (new, modified, removed). This section
- further defines under which condition each of them shall be used. It
- also clarifies the case where a resource may have undergone multiple
- changes in between two synchronizations.
+ Note that when a server supports Depth:infinity reports, it might not
+ be possible to synchronize some child collections within the
+ collection targeted by the report. In such cases the server is
+ REQUIRED to return a DAV:response with status '405 Method Not
+ Allowed' to inform the client that alternative methods have to be
+ used to synchronize the contents of those collections. The 405
+ response MUST be sent once, when the collection is first reported to
+ the client.
-4.3.1. New resource
+3.4. Types of Changes Reported on Initial Synchronization
- A resource MUST be reported as new if it has been mapped directly
- under the target collection since the request sync token was
+ When the DAV:sync-collection request contains an empty DAV:sync-token
+ element, the server MUST return all members of the collection (taking
+ account of Depth header requirements as per Section 3.3, and optional
+ truncation of results set as per Section 3.6) and it MUST NOT return
+ any removed resources. All types of resource (collection or non-
+ collection) MUST be reported.
+
+3.5. Types of Changes Reported on Subsequent Synchronizations
+
+ When the DAV:sync-collection request contains a valid value for the
+ DAV:sync-token element, two types of resource state changes can be
+ returned (changed or removed). This section defines what triggers
+ each of these to be returned. It also clarifies the case where a
+ resource may have undergone multiple changes between two
+ synchronization report requests. In all cases, the Depth header
+ requirements as per Section 3.3, and optional truncation of results
+ set as per Section 3.6, are taken into account by the server.
+
+3.5.1. Changed Resource
+
+ A resource MUST be reported as changed if it has been mapped as an
+ member of the target collection since the request sync-token was
generated. This includes resources that have been mapped as the
- result of a COPY, MOVE or BIND ([I-D.ietf-webdav-bind]) operation.
- This also includes collection resources that have been created.
+ result of a COPY, MOVE or BIND [RFC5842] request. All types of
+ resource (collection or non-collection) MUST be reported.
In the case where a mapping between a resource and the target
collection was removed, then a new mapping with the same URI created,
- the new resource MUST be reported as new, while the old resource MUST
- NOT be reported as removed. For example, if a resource was deleted,
- then recreated using the same URI, it should be reported as a new
- resource only.
- A resource MAY be reported as new if the user issuing the request was
- granted access to this resource, due to access control changes.
-4.3.2. Modified resource
- A resource MUST be reported as modified if it is not reported as new
- and if its entity tag value (defined in [RFC2616]) has changed since
- the request sync token was generated. In other words, the new
- resource change indicator takes precedence over the modified resource
- change indicator.
+Daboo & Quillaud Expires April 8, 2011 [Page 8]
+
+Internet-Draft WebDAV Sync October 2010
- Collection resources MUST NOT be returned as modified. Instead
- clients are expected to synchronize changes in child collection
- resources on an individual basis.
-4.3.3. Removed resource
+ the new resource MUST be reported as changed while the old resource
+ MUST NOT be reported as removed. For example, if a resource was
+ deleted, then recreated using the same URI, it should be reported as
+ a changed resource only.
+ A resource MUST be reported as changed if its entity tag value
+ (defined in Section 3.11 of [RFC2616]) has changed since the request
+ sync-token was generated.
+
+ A resource MAY be reported as changed if the user issuing the request
+ was granted access to this resource, due to access control changes.
+
+ Collection resources MUST be returned as changed if they have an
+ entity tag associated with them and that entity tag changes. There
+ is no guarantee that changes to members of a collection will result
+ in a change in any entity tag of that collection, so clients cannot
+ rely on a series of Depth:1 reports at multiple levels to track all
+ changes within a collection. Instead Depth:infinity has to be used.
+
+3.5.2. Removed Resource
+
A resource MUST be reported as removed if its mapping under the
- target collection has been removed since the request sync token was
+ target collection has been removed since the request sync-token was
generated, and it has not been re-mapped since it was removed. This
includes resources that have been unmapped as the result of a MOVE or
- UNBIND ([I-D.ietf-webdav-bind]) operation. This also includes
- collection resources that have been removed.
+ UNBIND [RFC5842] operation. This also includes collection resources
+ that have been removed, including ones that themselves do not support
+ the DAV:sync-collection report.
+ If a resource was created (and possibly modified), then removed
+ between two synchronization report requests, it MUST be reported as
+ removed. This ensures that a client that creates a resource is
+ informed of the removal of the resource, if the removal occurs before
+ the client has had a chance to request a synchronization report.
+ A resource MAY be reported as removed if the user issuing the request
+ no longer has access to this resource, due to access control changes.
-Daboo & Quillaud Expires May 22, 2010 [Page 8]
+ For a Depth:infinity report where a collection is removed, the server
+ MUST NOT report the removal of any resources that are members of the
+ removed collection. Clients MUST assume that if a collection is
+ reported as being removed, then all internal members of that
+ collection have also been removed.
+
+3.6. Truncation of Results
+
+ A server MAY limit the number of resources in a response, for
+ example, to limit the amount of work expended in processing a
+
+
+
+Daboo & Quillaud Expires April 8, 2011 [Page 9]
-Internet-Draft WebDAV Sync November 2009
+Internet-Draft WebDAV Sync October 2010
- If a resource was created (and possibly modified), then removed in
- between two synchronizations, it MUST NOT be reported as new,
- modified or removed.
+ request, or as the result of an explicit limit set by the client. If
+ the result set is truncated, the response MUST use status code 207,
+ return a DAV:multistatus response body, and indicate a status of 507
+ (Insufficient Storage) for the request URI. That DAV:response
+ element SHOULD include a DAV:error element with the DAV:number-of-
+ matches-within-limits precondition, as defined in [RFC3744] (Section
+ 9.2). DAV:response elements for all the changes being reported are
+ also included.
- A resource MAY be reported as removed if the user issuing the request
- has no longer access to this resource, due to access control changes.
+ When truncation occurs, the DAV:sync-token value returned in the
+ response MUST represent the correct state for the partial set of
+ changes returned. That allows the client to use the returned DAV:
+ sync-token to fetch the next set of changes. In this way the client
+ can effectively "page" through the entire set of changes in a
+ consistent manner.
-4.4. Example: Initial DAV:sync-collection REPORT
+ Clients MUST handle the 507 status on the request-URI in the response
+ to the report.
+ For example, consider a server that records changes using a
+ monotonically increasing integer to represent a "revision number" and
+ uses that quantity as the DAV:sync-token value. Assume the last DAV:
+ sync-token used by the client was "10", and since then 15 additional
+ changes have occurred. If the client executes a DAV:sync-collection
+ request with a DAV:sync-token of "10", without a limit the server
+ would return 15 DAV:response elements and a DAV:sync-token with value
+ "25". But if the server choose to limit responses to at most 10
+ changes, then it would return only 10 DAV:response elements and a
+ DAV:sync-token with value "20", together with an addition DAV:
+ response element for the request-URI with a status code of 507.
+ Subsequently, the client can re-issue the request with the DAV:sync-
+ token value returned from the server and fetch the remaining 5
+ changes.
+
+3.7. Limiting Results
+
+ A client can limit the number of results returned by the server
+ through use of the DAV:limit element ([RFC5323], Section 5.17) in the
+ request body. This is useful when clients have limited space or
+ bandwidth for the results. If a server is unable to truncate the
+ result at or below the requested number, then it MUST fail the
+ request with a DAV:number-of-matches-within-limits post-condition
+ error. When the results can be correctly limited by the server, the
+ server MUST follow the rules above for indicating a result set
+ truncation to the client.
+
+
+
+
+
+
+Daboo & Quillaud Expires April 8, 2011 [Page 10]
+
+Internet-Draft WebDAV Sync October 2010
+
+
+3.8. Example: Initial DAV:sync-collection Report
+
In this example, the client is making its first synchronization
request to the server, so the DAV:sync-token element in the request
- is empty. It also asks for the DAV:getetag property. The server
- responds with the items currently in the targeted collection
- (indicating that they are 'new' via the '201 Created' status code).
- The current synchronization token is also returned.
+ is empty. It also asks for the DAV:getetag property and for a
+ proprietary property. The server responds with the items currently
+ in the targeted collection. The current synchronization token is
+ also returned.
>> Request <<
@@ -477,34 +582,153 @@
<?xml version="1.0" encoding="utf-8" ?>
<D:sync-collection xmlns:D="DAV:">
<D:sync-token/>
- <D:prop>
+ <D:prop xmlns:R="urn:ns.example.com:boxschema">
<D:getetag/>
+ <R:bigbox/>
</D:prop>
</D:sync-collection>
+ >> Response <<
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:">
+ <D:response>
+ <D:href
+ >http://webdav.example.com/home/cyrusdaboo/test.doc</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:getetag>"00001-abcd1"</D:getetag>
+ <R:bigbox xmlns:R="urn:ns.example.com:boxschema">
+ <R:BoxType>Box type A</R:BoxType>
+ </R:bigbox>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+Daboo & Quillaud Expires April 8, 2011 [Page 11]
+
+Internet-Draft WebDAV Sync October 2010
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href
+ >http://webdav.example.com/home/cyrusdaboo/vcard.vcf</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:getetag>"00002-abcd1"</D:getetag>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ <D:propstat>
+ <D:prop>
+ <R:bigbox xmlns:R="urn:ns.example.com:boxschema"/>
+ </D:prop>
+ <D:status>HTTP/1.1 404 Not Found</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href
+ >http://webdav.example.com/home/cyrusdaboo/calendar.ics</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:getetag>"00003-abcd1"</D:getetag>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ <D:propstat>
+ <D:prop>
+ <R:bigbox xmlns:R="urn:ns.example.com:boxschema"/>
+ </D:prop>
+ <D:status>HTTP/1.1 404 Not Found</D:status>
+ </D:propstat>
+ </D:response>
+ <D:sync-token>1234</D:sync-token>
+ </D:multistatus>
+3.9. Example: DAV:sync-collection Report with Token
+ In this example, the client is making a synchronization request to
+ the server and is using the DAV:sync-token element returned from the
+ last report it ran on this collection. The server responds, listing
+ the items that have been added, changed or removed. The (new)
+ current synchronization token is also returned.
-Daboo & Quillaud Expires May 22, 2010 [Page 9]
+Daboo & Quillaud Expires April 8, 2011 [Page 12]
-Internet-Draft WebDAV Sync November 2009
+Internet-Draft WebDAV Sync October 2010
+ >> Request <<
+
+
+ REPORT /home/cyrusdaboo/ HTTP/1.1
+ Host: webdav.example.com
+ Depth: 1
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:sync-collection xmlns:D="DAV:">
+ <D:sync-token>1234</D:sync-token>
+ <D:prop xmlns:R="urn:ns.example.com:boxschema">
+ <D:getetag/>
+ <R:bigbox/>
+ </D:prop>
+ </D:sync-collection>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo & Quillaud Expires April 8, 2011 [Page 13]
+
+Internet-Draft WebDAV Sync October 2010
+
+
>> Response <<
@@ -514,60 +738,61 @@
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:">
- <D:sync-response>
+ <D:response>
<D:href
- >http://webdav.example.com/home/cyrusdaboo/test.doc</D:href>
- <D:status>HTTP/1.1 201 Created</D:status>
+ >http://webdav.example.com/home/cyrusdaboo/file.xml</D:href>
<D:propstat>
<D:prop>
- <D:getetag>"00001-abcd1"</D:getetag>
+ <D:getetag>"00004-abcd1"</D:getetag>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
- </D:sync-response>
- <D:sync-response>
+ <D:propstat>
+ <D:prop>
+ <R:bigbox xmlns:R="urn:ns.example.com:boxschema"/>
+ </D:prop>
+ <D:status>HTTP/1.1 404 Not Found</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
<D:href
>http://webdav.example.com/home/cyrusdaboo/vcard.vcf</D:href>
- <D:status>HTTP/1.1 201 Created</D:status>
<D:propstat>
<D:prop>
- <D:getetag>"00002-abcd1"</D:getetag>
+ <D:getetag>"00002-abcd2"</D:getetag>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
- </D:sync-response>
- <D:sync-response>
- <D:href
- >http://webdav.example.com/home/cyrusdaboo/calendar.ics</D:href>
- <D:status>HTTP/1.1 201 Created</D:status>
<D:propstat>
<D:prop>
- <D:getetag>"00003-abcd1"</D:getetag>
+ <R:bigbox xmlns:R="urn:ns.example.com:boxschema"/>
</D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
+ <D:status>HTTP/1.1 404 Not Found</D:status>
</D:propstat>
- </D:sync-response>
- <D:sync-token>1234</D:sync-token>
+ </D:response>
+ <D:response>
+ <D:href
+ >http://webdav.example.com/home/cyrusdaboo/test.doc</D:href>
+ <D:status>HTTP/1.1 404 Not Found</D:status>
+ </D:response>
+ <D:sync-token>1238</D:sync-token>
</D:multistatus>
-
-
-
-
-Daboo & Quillaud Expires May 22, 2010 [Page 10]
+Daboo & Quillaud Expires April 8, 2011 [Page 14]
-Internet-Draft WebDAV Sync November 2009
+Internet-Draft WebDAV Sync October 2010
-4.5. Example: DAV:sync-collection Report with token
+3.10. Example: Initial DAV:sync-collection Report with Truncation
- In this example, the client is making a synchronization request to
- the server and is using the DAV:sync-token element returned from the
- last report it ran on this collection. The server responds listing
- the items that have been added, changed or removed. The (new)
- current synchronization token is also returned.
+ In this example, the client is making its first synchronization
+ request to the server, so the DAV:sync-token element in the request
+ is empty. It also asks for the DAV:getetag property. The server
+ responds with the items currently in the targeted collection, but
+ truncated at two items. The synchronization token for the truncated
+ result set is returned.
>> Request <<
@@ -580,7 +805,7 @@
<?xml version="1.0" encoding="utf-8" ?>
<D:sync-collection xmlns:D="DAV:">
- <D:sync-token>1234</D:sync-token>
+ <D:sync-token/>
<D:prop>
<D:getetag/>
</D:prop>
@@ -611,10 +836,9 @@
-
-Daboo & Quillaud Expires May 22, 2010 [Page 11]
+Daboo & Quillaud Expires April 8, 2011 [Page 15]
-Internet-Draft WebDAV Sync November 2009
+Internet-Draft WebDAV Sync October 2010
>> Response <<
@@ -626,53 +850,295 @@
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:">
- <D:sync-response>
+ <D:response>
<D:href
- >http://webdav.example.com/home/cyrusdaboo/file.xml</D:href>
- <D:status>HTTP/1.1 201 Created</D:status>
+ >http://webdav.example.com/home/cyrusdaboo/test.doc</D:href>
<D:propstat>
<D:prop>
- <D:getetag>"00004-abcd1"</D:getetag>
+ <D:getetag>"00001-abcd1"</D:getetag>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
- </D:sync-response>
- <D:sync-response>
+ </D:response>
+ <D:response>
<D:href
>http://webdav.example.com/home/cyrusdaboo/vcard.vcf</D:href>
- <D:status>HTTP/1.1 200 OK</D:status>
<D:propstat>
<D:prop>
- <D:getetag>"00002-abcd2"</D:getetag>
+ <D:getetag>"00002-abcd1"</D:getetag>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
- </D:sync-response>
- <D:sync-response>
+ </D:response>
+ <D:response>
+ <D:href
+ >http://webdav.example.com/home/cyrusdaboo/</D:href>
+ <D:status>HTTP/1.1 507 Insufficient Storage</D:status>
+ <D:error><D:number-of-matches-within-limits/></D:error>
+ </D:response>
+ <D:sync-token>1233</D:sync-token>
+ </D:multistatus>
+
+
+3.11. Example: Initial DAV:sync-collection Report with Limit
+
+ In this example, the client is making its first synchronization
+ request to the server, so the DAV:sync-token element in the request
+ is empty. It requests a limit of 1 for the responses returned by the
+ server. It also asks for the DAV:getetag property. The server
+ responds with the items currently in the targeted collection, but
+ truncated at one item. The synchronization token for the truncated
+ result set is returned.
+
+
+
+Daboo & Quillaud Expires April 8, 2011 [Page 16]
+
+Internet-Draft WebDAV Sync October 2010
+
+
+ >> Request <<
+
+
+ REPORT /home/cyrusdaboo/ HTTP/1.1
+ Host: webdav.example.com
+ Depth: 1
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:sync-collection xmlns:D="DAV:">
+ <D:sync-token/>
+ <D:limit>
+ <D:nresults>1</D:nresults>
+ </D:limit>
+ <D:prop>
+ <D:getetag/>
+ </D:prop>
+ </D:sync-collection>
+
+
+ >> Response <<
+
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:">
+ <D:response>
<D:href
>http://webdav.example.com/home/cyrusdaboo/test.doc</D:href>
- <D:status>HTTP/1.1 404 Not Found</D:status>
- </D:sync-response>
- <D:sync-token>1238</D:sync-token>
+ <D:propstat>
+ <D:prop>
+ <D:getetag>"00001-abcd1"</D:getetag>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href
+ >http://webdav.example.com/home/cyrusdaboo/</D:href>
+ <D:status>HTTP/1.1 507 Insufficient Storage</D:status>
+ <D:error><D:number-of-matches-within-limits/></D:error>
+ </D:response>
+ <D:sync-token>1232</D:sync-token>
</D:multistatus>
-5. DAV:sync-token Property
- Name: sync-token
+Daboo & Quillaud Expires April 8, 2011 [Page 17]
+
+Internet-Draft WebDAV Sync October 2010
- Namespace: DAV:
+3.12. Example: DAV:sync-collection Report with Unsupported Limit
+ In this example, the client is making a synchronization request to
+ the server with a valid DAV:sync-token element value. It requests a
+ limit of 100 for the responses returned by the server. It also asks
+ for the DAV:getetag property. The server is unable to limit the
+ results to the maximum specified by the client, so it responds with a
+ 507 status code and appropriate post-condition error code.
+ >> Request <<
+ REPORT /home/cyrusdaboo/ HTTP/1.1
+ Host: webdav.example.com
+ Depth: 1
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
-Daboo & Quillaud Expires May 22, 2010 [Page 12]
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:sync-collection xmlns:D="DAV:">
+ <D:sync-token>1232</D:sync-token>
+ <D:limit>
+ <D:nresults>100</D:nresults>
+ </D:limit>
+ <D:prop>
+ <D:getetag/>
+ </D:prop>
+ </D:sync-collection>
+
+
+ >> Response <<
+
+
+ HTTP/1.1 507 Insufficient Storage
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:error xmlns:D="DAV:">
+ <D:number-of-matches-within-limits/>
+ </D:error>
+
+
+3.13. Example: Depth:infinity initial DAV:sync-collection Report
+
+ In this example, the client is making its first synchronization
+ request to the server, so the DAV:sync-token element in the request
+ is empty, and it is using Depth:infinity. It also asks for the DAV:
+
+
+
+Daboo & Quillaud Expires April 8, 2011 [Page 18]
-Internet-Draft WebDAV Sync November 2009
+Internet-Draft WebDAV Sync October 2010
+ getetag property and for a proprietary property. The server responds
+ with the items currently in the targeted collection. The current
+ synchronization token is also returned.
+
+ The collection /home/cyrusdaboo/collection1/ exists and has one child
+ resource which is also reported. The collection /home/cyrusdaboo/
+ collection2/ exists but has no child resources. The collection
+ /home/cyrusdaboo/shared/ is returned with a 405 status indicating
+ that a collection exists but it is unable to report on changes within
+ it in the scope of the current Depth:infinity report. Instead the
+ client can try a DAV:sync-collection report directly on the
+ collection URI.
+
+ >> Request <<
+
+
+ REPORT /home/cyrusdaboo/ HTTP/1.1
+ Host: webdav.example.com
+ Depth: 1
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:sync-collection xmlns:D="DAV:">
+ <D:sync-token/>
+ <D:prop xmlns:R="urn:ns.example.com:boxschema">
+ <D:getetag/>
+ <R:bigbox/>
+ </D:prop>
+ </D:sync-collection>
+
+
+ >> Response <<
+
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:">
+ <D:response>
+ <D:href
+ >/home/cyrusdaboo/collection1/</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:getetag>"00001-abcd1"</D:getetag>
+ <R:bigbox xmlns:R="urn:ns.example.com:boxschema">
+
+
+
+Daboo & Quillaud Expires April 8, 2011 [Page 19]
+
+Internet-Draft WebDAV Sync October 2010
+
+
+ <R:BoxType>Box type A</R:BoxType>
+ </R:bigbox>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href
+ >/home/cyrusdaboo/collection1/test.doc</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:getetag>"00001-abcd1"</D:getetag>
+ <R:bigbox xmlns:R="urn:ns.example.com:boxschema">
+ <R:BoxType>Box type A</R:BoxType>
+ </R:bigbox>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href
+ >/home/cyrusdaboo/collection2/</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:getetag>"00002-abcd1"</D:getetag>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ <D:propstat>
+ <D:prop>
+ <R:bigbox xmlns:R="urn:ns.example.com:boxschema"/>
+ </D:prop>
+ <D:status>HTTP/1.1 404 Not Found</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href
+ >/home/cyrusdaboo/calendar.ics</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:getetag>"00003-abcd1"</D:getetag>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ <D:propstat>
+ <D:prop>
+ <R:bigbox xmlns:R="urn:ns.example.com:boxschema"/>
+ </D:prop>
+
+
+
+Daboo & Quillaud Expires April 8, 2011 [Page 20]
+
+Internet-Draft WebDAV Sync October 2010
+
+
+ <D:status>HTTP/1.1 404 Not Found</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href
+ >/home/cyrusdaboo/shared/</D:href>
+ <D:status>HTTP/1.1 405 Method Not Allowed</D:status>
+ </D:response>
+ <D:sync-token>1234</D:sync-token>
+ </D:multistatus>
+
+
+4. DAV:sync-token Property
+
+ Name: sync-token
+
+ Namespace: DAV:
+
Purpose: Contains the value of the synchronization token as it would
be returned by a DAV:sync-collection report.
@@ -690,7 +1156,7 @@
contains the value of the synchronization token as it would be
returned by a DAV:sync-collection report on that resource at the
same point in time. It SHOULD NOT be returned by a PROPFIND DAV:
- allprop request (as defined in [RFC4918]).
+ allprop request (as defined in Section 14.2 of [RFC4918]).
Definition:
@@ -698,37 +1164,40 @@
<!ELEMENT sync-token #PCDATA>
-6. XML Element Definitions
+5. XML Element Definitions
-6.1. DAV:sync-collection XML Element
- Name: sync-collection
- Namespace: DAV:
- Purpose: WebDAV report used to synchronize data between client and
- server.
- Description: See Section 4.
+Daboo & Quillaud Expires April 8, 2011 [Page 21]
+
+Internet-Draft WebDAV Sync October 2010
- <!ELEMENT sync-collection (sync-token, DAV:prop?)>
+5.1. DAV:sync-collection XML Element
-6.2. DAV:sync-token XML Element
+ Name: sync-collection
+ Namespace: DAV:
+ Purpose: WebDAV report used to synchronize data between client and
+ server.
+ Description: See Section 3.
+ <!ELEMENT sync-collection (sync-token, DAV:limit?, DAV:prop)>
-Daboo & Quillaud Expires May 22, 2010 [Page 13]
-
-Internet-Draft WebDAV Sync November 2009
+ <!-- DAV:limit defined in RFC 5323, Section 5.17 -->
+ <!-- DAV:prop defined in RFC 4918, Section 14.18 -->
+5.2. DAV:sync-token XML Element
+
Name: sync-token
Namespace: DAV:
@@ -736,14 +1205,14 @@
Purpose: The synchronization token provided by the server and
returned by the client.
- Description: See Section 4.
+ Description: See Section 3.
<!ELEMENT sync-token CDATA>
-6.3. DAV:multistatus XML Element
+5.3. DAV:multistatus XML Element
Name: multistatus
@@ -752,57 +1221,48 @@
Purpose: Extends the DAV:multistatus element to include
synchronization details.
- Description: See Section 4.
+ Description: See Section 3.
- <!ELEMENT multistatus ((DAV:response*, DAV:responsedescription?) |
- (DAV:sync-response*, DAV:sync-token,
- DAV:responsedescription?))>
-6.4. DAV:sync-response XML Element
- Name: sync-response
+Daboo & Quillaud Expires April 8, 2011 [Page 22]
+
+Internet-Draft WebDAV Sync October 2010
- Namespace: DAV:
- Purpose: Contains the synchronization results returned by the
- server.
+ <!ELEMENT multistatus (DAV:response*, DAV:responsedescription?,
+ sync-token?) >
- Description: See Section 4.
+ <!-- DAV:multistatus originally defined in RFC 4918, Section 14.16
+ but overridden here to add the DAV:sync-token element -->
+ <!-- DAV:response defined in RFC 4918, Section 14.24 -->
+ <!-- DAV:responsedescription defined in RFC 4918, Section 14.25 -->
+6. Security Considerations
- <!ELEMENT sync-response (DAV:href, DAV:status, DAV:propstat?)>
-
-
-
-
-
-Daboo & Quillaud Expires May 22, 2010 [Page 14]
-
-Internet-Draft WebDAV Sync November 2009
-
-
-7. Security Considerations
-
This extension does not introduce any new security concerns than
those already described in HTTP and WebDAV.
-8. IANA Considerations
+7. IANA Considerations
This document does not require any actions on the part of IANA.
-9. Acknowledgments
+8. Acknowledgments
The following individuals contributed their ideas and support for
writing this specification: Bernard Desruisseaux, Mike Douglass, Ciny
- Joy and Julian Reschke.
+ Joy, Andrew McMillan, Julian Reschke, and Wilfredo Sanchez. We would
+ like to thank the Calendaring and Scheduling Consortium for
+ facilitating interoperability testing for early implementations of
+ this specification.
-10. References
+9. References
-10.1. Normative References
+9.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs
to Indicate Requirement Levels", BCP 14,
@@ -814,51 +1274,95 @@
Protocol -- HTTP/1.1", RFC 2616,
June 1999.
+ [RFC3744] Clemm, G., Reschke, J., Sedlar, E., and
+ J. Whitehead, "Web Distributed Authoring
+ and Versioning (WebDAV)
+ Access Control Protocol", RFC 3744,
+ May 2004.
+
[RFC4918] Dusseault, L., "HTTP Extensions for Web
+
+
+
+Daboo & Quillaud Expires April 8, 2011 [Page 23]
+
+Internet-Draft WebDAV Sync October 2010
+
+
Distributed Authoring and Versioning
(WebDAV)", RFC 4918, June 2007.
- [W3C.REC-xml-20081126] Sperberg-McQueen, C., Yergeau, F., Bray,
- T., Paoli, J., and E. Maler, "Extensible
- Markup Language (XML) 1.0 (Fifth
- Edition)", World Wide Web Consortium
- Recommendation REC-xml-20081126,
- November 2008, <http://www.w3.org/TR/
- 2008/REC-xml-20081126>.
+ [RFC5323] Reschke, J., Reddy, S., Davis, J., and
+ A. Babich, "Web Distributed Authoring
+ and Versioning (WebDAV) SEARCH",
+ RFC 5323, November 2008.
-10.2. Informative References
+ [W3C.REC-xml-20081126] Paoli, J., Yergeau, F., Bray, T.,
+ Sperberg-McQueen, C., and E. Maler,
+ "Extensible Markup Language (XML) 1.0
+ (Fifth Edition)", World Wide Web
+ Consortium Recommendation REC-xml-
+ 20081126, November 2008, <http://
+ www.w3.org/TR/2008/REC-xml-20081126>.
+9.2. Informative References
+
[I-D.ietf-vcarddav-carddav] Daboo, C., "vCard Extensions to WebDAV
(CardDAV)",
draft-ietf-vcarddav-carddav-10 (work in
progress), November 2009.
+ [RFC4791] Daboo, C., Desruisseaux, B., and L.
+ Dusseault, "Calendaring Extensions to
+ WebDAV (CalDAV)", RFC 4791, March 2007.
+ [RFC5842] Clemm, G., Crawford, J., Reschke, J.,
+ and J. Whitehead, "Binding Extensions to
+ Web Distributed Authoring and Versioning
+ (WebDAV)", RFC 5842, April 2010.
+Appendix A. Change History (to be removed prior to publication as an
+ RFC)
-Daboo & Quillaud Expires May 22, 2010 [Page 15]
+ Changes in -04:
+
+ 1. Depth:infinity support added.
+
+ 2. Collection resources are now reported as changed if they have a
+ valid entity tag associated with them.
+
+ Changes in -03:
+
+ 1. Changed D:propstat to D:prop in marshalling.
+
+ 2. Added request for dead property in examples.
+
+
+
+
+Daboo & Quillaud Expires April 8, 2011 [Page 24]
-Internet-Draft WebDAV Sync November 2009
+Internet-Draft WebDAV Sync October 2010
- [I-D.ietf-webdav-bind] Clemm, G., Crawford, J., Reschke, J.,
- and J. Whitehead, "Binding Extensions to
- Web Distributed Authoring and Versioning
- (WebDAV)", draft-ietf-webdav-bind-26
- (work in progress), September 2009.
+ 3. Made D:prop mandatory in request so that D:response always
+ contains at least one D:propstat as per WebDAV definition.
- [RFC4791] Daboo, C., Desruisseaux, B., and L.
- Dusseault, "Calendaring Extensions to
- WebDAV (CalDAV)", RFC 4791, March 2007.
+ 4. Removed DAV:status from response when resource is created/
+ modified, thus allowing to get rid of DAV:sync-response in favor
+ of a regular DAV:response. As a consequence, there is no longer
+ any difference in the report between created and modified
+ resources.
- [RFC5323] Reschke, J., Reddy, S., Davis, J., and
- A. Babich, "Web Distributed Authoring
- and Versioning (WebDAV) SEARCH",
- RFC 5323, November 2008.
+ 5. Resource created, then removed between 2 sync MUST be returned as
+ removed.
-Appendix A. Change History (to be removed prior to publication as an
- RFC)
+ 6. Added ability for server to truncate results and indicate such to
+ the client.
+ 7. Added ability for client to request the server to limit the
+ result set.
+
Changes in -02:
1. Added definition of sync-token WebDAV property.
@@ -892,9 +1396,9 @@
-Daboo & Quillaud Expires May 22, 2010 [Page 16]
+Daboo & Quillaud Expires April 8, 2011 [Page 25]
-Internet-Draft WebDAV Sync November 2009
+Internet-Draft WebDAV Sync October 2010
Authors' Addresses
@@ -910,13 +1414,13 @@
Arnaud Quillaud
- Sun Microsystems
+ Oracle Corporation
180, Avenue de l'Europe
Saint Ismier cedex, 38334
France
- EMail: arnaud.quillaud at sun.com
- URI: http://www.sun.com/
+ EMail: arnaud.quillaud at oracle.com
+ URI: http://www.oracle.com/
@@ -948,5 +1452,5 @@
-Daboo & Quillaud Expires May 22, 2010 [Page 17]
-
\ No newline at end of file
+Daboo & Quillaud Expires April 8, 2011 [Page 26]
+
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.macosforge.org/pipermail/calendarserver-changes/attachments/20101006/3ff63161/attachment-0001.html>
More information about the calendarserver-changes
mailing list