draft-ietf-vcarddav-carddav-09.txt   draft-ietf-vcarddav-carddav-10.txt 
Network Working Group C. Daboo Network Working Group C. Daboo
Internet-Draft Apple Internet-Draft Apple
Intended status: Standards Track September 16, 2009 Intended status: Standards Track November 9, 2009
Expires: March 20, 2010 Expires: May 13, 2010
vCard Extensions to WebDAV (CardDAV) vCard Extensions to WebDAV (CardDAV)
draft-ietf-vcarddav-carddav-09 draft-ietf-vcarddav-carddav-10
Status of this Memo Status of this Memo
This Internet-Draft is submitted to IETF in full conformance with the This Internet-Draft is submitted to IETF in full conformance with the
provisions of BCP 78 and BCP 79. This document may contain material provisions of BCP 78 and BCP 79. This document may contain material
from IETF Documents or IETF Contributions published or made publicly from IETF Documents or IETF Contributions published or made publicly
available before November 10, 2008. The person(s) controlling the available before November 10, 2008. The person(s) controlling the
copyright in some of this material may not have granted the IETF copyright in some of this material may not have granted the IETF
Trust the right to allow modifications of such material outside the Trust the right to allow modifications of such material outside the
IETF Standards Process. Without obtaining an adequate license from IETF Standards Process. Without obtaining an adequate license from
skipping to change at page 1, line 42 skipping to change at page 1, line 42
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on March 20, 2010. This Internet-Draft will expire on May 13, 2010.
Copyright Notice Copyright Notice
Copyright (c) 2009 IETF Trust and the persons identified as the Copyright (c) 2009 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents in effect on the date of Provisions Relating to IETF Documents in effect on the date of
publication of this document (http://trustee.ietf.org/license-info). publication of this document (http://trustee.ietf.org/license-info).
Please review these documents carefully, as they describe your rights Please review these documents carefully, as they describe your rights
skipping to change at page 2, line 22 skipping to change at page 2, line 22
Versioning (WebDAV) protocol to specify a standard way of accessing, Versioning (WebDAV) protocol to specify a standard way of accessing,
managing, and sharing contact information based on the vCard format. managing, and sharing contact information based on the vCard format.
Table of Contents Table of Contents
1. Introduction and Overview . . . . . . . . . . . . . . . . . . 4 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 4
2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 5
3. Requirements Overview . . . . . . . . . . . . . . . . . . . . 6 3. Requirements Overview . . . . . . . . . . . . . . . . . . . . 6
4. Address Book Data Model . . . . . . . . . . . . . . . . . . . 7 4. Address Book Data Model . . . . . . . . . . . . . . . . . . . 7
4.1. Address Book Server . . . . . . . . . . . . . . . . . . . 7 4.1. Address Book Server . . . . . . . . . . . . . . . . . . . 7
5. Address Book Resources . . . . . . . . . . . . . . . . . . . . 8 5. Address Book Resources . . . . . . . . . . . . . . . . . . . . 7
5.1. Address Object Resources . . . . . . . . . . . . . . . . . 8 5.1. Address Object Resources . . . . . . . . . . . . . . . . . 8
5.1.1. Data Type Conversion . . . . . . . . . . . . . . . . . 8 5.1.1. Data Type Conversion . . . . . . . . . . . . . . . . . 8
5.1.1.1. Additional Precondition for GET . . . . . . . . . 9 5.1.1.1. Additional Precondition for GET . . . . . . . . . 9
5.2. Address Book Collections . . . . . . . . . . . . . . . . . 9 5.2. Address Book Collections . . . . . . . . . . . . . . . . . 9
6. Address Book Feature . . . . . . . . . . . . . . . . . . . . . 10 6. Address Book Feature . . . . . . . . . . . . . . . . . . . . . 10
6.1. Address Book Support . . . . . . . . . . . . . . . . . . . 10 6.1. Address Book Support . . . . . . . . . . . . . . . . . . . 10
6.1.1. Example: Using OPTIONS for the Discovery of 6.1.1. Example: Using OPTIONS for the Discovery of
Support for CardDAV . . . . . . . . . . . . . . . . . 10 Support for CardDAV . . . . . . . . . . . . . . . . . 10
6.2. Address Book Properties . . . . . . . . . . . . . . . . . 10 6.2. Address Book Properties . . . . . . . . . . . . . . . . . 10
6.2.1. CARDDAV:addressbook-description Property . . . . . . . 11 6.2.1. CARDDAV:addressbook-description Property . . . . . . . 11
skipping to change at page 3, line 19 skipping to change at page 3, line 19
8.6.2. Truncation of Results . . . . . . . . . . . . . . . . 26 8.6.2. Truncation of Results . . . . . . . . . . . . . . . . 26
8.6.3. Example: Partial Retrieval of vCards Matching 8.6.3. Example: Partial Retrieval of vCards Matching
NICKNAME . . . . . . . . . . . . . . . . . . . . . . . 26 NICKNAME . . . . . . . . . . . . . . . . . . . . . . . 26
8.6.4. Example: Partial Retrieval of vCards Matching a 8.6.4. Example: Partial Retrieval of vCards Matching a
Full Name or Email Address . . . . . . . . . . . . . . 28 Full Name or Email Address . . . . . . . . . . . . . . 28
8.6.5. Example: Truncated Results . . . . . . . . . . . . . . 31 8.6.5. Example: Truncated Results . . . . . . . . . . . . . . 31
8.7. CARDDAV:addressbook-multiget Report . . . . . . . . . . . 32 8.7. CARDDAV:addressbook-multiget Report . . . . . . . . . . . 32
8.7.1. Example: CARDDAV:addressbook-multiget Report . . . . . 34 8.7.1. Example: CARDDAV:addressbook-multiget Report . . . . . 34
8.7.2. Example: CARDDAV:addressbook-multiget Report . . . . . 35 8.7.2. Example: CARDDAV:addressbook-multiget Report . . . . . 35
9. Client Guidelines . . . . . . . . . . . . . . . . . . . . . . 36 9. Client Guidelines . . . . . . . . . . . . . . . . . . . . . . 36
9.1. Restrict the Properties Returned . . . . . . . . . . . . . 37 9.1. Restrict the Properties Returned . . . . . . . . . . . . . 36
9.2. Use of Locking . . . . . . . . . . . . . . . . . . . . . . 37 9.2. Avoiding Lost Updates . . . . . . . . . . . . . . . . . . 37
9.3. Client Configuration . . . . . . . . . . . . . . . . . . . 37 9.3. Client Configuration . . . . . . . . . . . . . . . . . . . 37
9.4. Finding Other Users' Address Books . . . . . . . . . . . . 38 9.4. Finding Other Users' Address Books . . . . . . . . . . . . 37
10. XML Element Definitions . . . . . . . . . . . . . . . . . . . 38 10. XML Element Definitions . . . . . . . . . . . . . . . . . . . 38
10.1. CARDDAV:addressbook XML Element . . . . . . . . . . . . . 38 10.1. CARDDAV:addressbook XML Element . . . . . . . . . . . . . 38
10.2. CARDDAV:supported-collation XML Element . . . . . . . . . 39 10.2. CARDDAV:supported-collation XML Element . . . . . . . . . 38
10.3. CARDDAV:addressbook-query XML Element . . . . . . . . . . 39 10.3. CARDDAV:addressbook-query XML Element . . . . . . . . . . 39
10.4. CARDDAV:address-data XML Element . . . . . . . . . . . . . 40 10.4. CARDDAV:address-data XML Element . . . . . . . . . . . . . 39
10.4.1. CARDDAV:allprop XML Element . . . . . . . . . . . . . 41 10.4.1. CARDDAV:allprop XML Element . . . . . . . . . . . . . 41
10.4.2. CARDDAV:prop XML Element . . . . . . . . . . . . . . . 42 10.4.2. CARDDAV:prop XML Element . . . . . . . . . . . . . . . 41
10.5. CARDDAV:filter XML Element . . . . . . . . . . . . . . . . 42 10.5. CARDDAV:filter XML Element . . . . . . . . . . . . . . . . 42
10.5.1. CARDDAV:prop-filter XML Element . . . . . . . . . . . 43 10.5.1. CARDDAV:prop-filter XML Element . . . . . . . . . . . 43
10.5.2. CARDDAV:param-filter XML Element . . . . . . . . . . . 44 10.5.2. CARDDAV:param-filter XML Element . . . . . . . . . . . 44
10.5.3. CARDDAV:is-not-defined XML Element . . . . . . . . . . 45 10.5.3. CARDDAV:is-not-defined XML Element . . . . . . . . . . 45
10.5.4. CARDDAV:text-match XML Element . . . . . . . . . . . . 45 10.5.4. CARDDAV:text-match XML Element . . . . . . . . . . . . 45
10.6. CARDDAV:limit XML Element . . . . . . . . . . . . . . . . 46 10.6. CARDDAV:limit XML Element . . . . . . . . . . . . . . . . 46
10.6.1. CARDDAV:nresults XML Element . . . . . . . . . . . . . 47 10.6.1. CARDDAV:nresults XML Element . . . . . . . . . . . . . 46
10.7. CARDDAV:addressbook-multiget XML Element . . . . . . . . . 47 10.7. CARDDAV:addressbook-multiget XML Element . . . . . . . . . 47
11. Service Discovery via SRV Records . . . . . . . . . . . . . . 47 11. Service Discovery via SRV Records . . . . . . . . . . . . . . 47
12. Internationalization Considerations . . . . . . . . . . . . . 48 12. Internationalization Considerations . . . . . . . . . . . . . 48
13. Security Considerations . . . . . . . . . . . . . . . . . . . 48 13. Security Considerations . . . . . . . . . . . . . . . . . . . 48
14. IANA Consideration . . . . . . . . . . . . . . . . . . . . . . 49 14. IANA Consideration . . . . . . . . . . . . . . . . . . . . . . 49
14.1. Namespace Registration . . . . . . . . . . . . . . . . . . 49 14.1. Namespace Registration . . . . . . . . . . . . . . . . . . 49
15. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 49 15. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 49
16. References . . . . . . . . . . . . . . . . . . . . . . . . . . 49 16. References . . . . . . . . . . . . . . . . . . . . . . . . . . 49
16.1. Normative References . . . . . . . . . . . . . . . . . . . 49 16.1. Normative References . . . . . . . . . . . . . . . . . . . 49
16.2. Informative References . . . . . . . . . . . . . . . . . . 51 16.2. Informative References . . . . . . . . . . . . . . . . . . 51
Appendix A. Change History (to be removed prior to Appendix A. Change History (to be removed prior to
publication as an RFC) . . . . . . . . . . . . . . . 51 publication as an RFC) . . . . . . . . . . . . . . . 51
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 55 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 56
1. Introduction and Overview 1. Introduction and Overview
Address books containing contact information are a key component of Address books containing contact information are a key component of
personal information management tools, such as email, calendaring and personal information management tools, such as email, calendaring and
scheduling, and instant messaging clients. To date several protocols scheduling, and instant messaging clients. To date several protocols
have been used for remote access to contact data, including have been used for remote access to contact data, including
Lightweight Directory Access Protocol (LDAP) [RFC4510], Internet Lightweight Directory Access Protocol (LDAP) [RFC4510], Internet
Message Support Protocol (IMSP) [IMSP] and Application Configuration Message Support Protocol (IMSP) [IMSP] and Application Configuration
Access Protocol (ACAP) [RFC2244], together with SyncML used for Access Protocol (ACAP) [RFC2244], together with SyncML used for
skipping to change at page 4, line 51 skipping to change at page 4, line 51
7. Many limited clients (e.g. mobile devices) contain an HTTP stack 7. Many limited clients (e.g. mobile devices) contain an HTTP stack
which makes implementing WebDAV much easier than other protocols. which makes implementing WebDAV much easier than other protocols.
The key disadvantages of address book support in WebDAV are: The key disadvantages of address book support in WebDAV are:
1. Lack of change notification. Many of the alternative protocols 1. Lack of change notification. Many of the alternative protocols
also lack this ability. However, an extension for push also lack this ability. However, an extension for push
notifications could easily be developed. notifications could easily be developed.
2. Stateless nature of protocol can result in more data being sent
with each transaction to maintain per-user session across
requests.
vCard is a MIME directory profile aimed at encapsulating personal vCard is a MIME directory profile aimed at encapsulating personal
addressing and contact information about people. The specification addressing and contact information about people. The specification
of vCard was originally done by the Versit consortium, with a of vCard was originally done by the Versit consortium, with a
subsequent 3.0 version standardized by the IETF [RFC2426]. vCard is subsequent 3.0 version standardized by the IETF [RFC2426]. vCard is
in wide spread use in email clients and mobile devices as a means of in wide spread use in email clients and mobile devices as a means of
encapsulating address information for transport via email, or for encapsulating address information for transport via email, or for
import/export and synchronization operations. import/export and synchronization operations.
An update to vCard - vCard v4 - is currently being developed An update to vCard - vCard v4 - is currently being developed
[I-D.ietf-vcarddav-vcardrev]and is compatible with this [I-D.ietf-vcarddav-vcardrev]and is compatible with this
skipping to change at page 6, line 8 skipping to change at page 6, line 4
The namespace "urn:ietf:params:xml:ns:carddav" is reserved for the The namespace "urn:ietf:params:xml:ns:carddav" is reserved for the
XML elements defined in this specification, its revisions, and XML elements defined in this specification, its revisions, and
related CardDAV specifications. XML elements defined by individual related CardDAV specifications. XML elements defined by individual
implementations MUST NOT use the "urn:ietf:params:xml:ns:carddav" implementations MUST NOT use the "urn:ietf:params:xml:ns:carddav"
namespace, and instead should use a namespace that they control. namespace, and instead should use a namespace that they control.
When XML element types in the namespaces "DAV:" and When XML element types in the namespaces "DAV:" and
"urn:ietf:params:xml:ns:carddav" are referenced in this document "urn:ietf:params:xml:ns:carddav" are referenced in this document
outside of the context of an XML fragment, the strings "DAV:" and outside of the context of an XML fragment, the strings "DAV:" and
"CARDDAV:" will be prefixed to the element types, resposectively. "CARDDAV:" will be prefixed to the element types, respectively.
This document inherits, and sometimes extends, DTD productions from This document inherits, and sometimes extends, DTD productions from
Section 14 of [RFC4918]. Section 14 of [RFC4918].
Also note that some CardDAV XML element names are identical to WebDAV Also note that some CardDAV XML element names are identical to WebDAV
XML element names, though their namespace differs. Care must be XML element names, though their namespace differs. Care must be
taken not to confuse the two sets of names. taken not to confuse the two sets of names.
3. Requirements Overview 3. Requirements Overview
skipping to change at page 6, line 49 skipping to change at page 6, line 45
o MUST advertise support on all address book collections and address o MUST advertise support on all address book collections and address
object resources for the address book reports in the DAV: object resources for the address book reports in the DAV:
supported-report-set property, as defined in Versioning Extensions supported-report-set property, as defined in Versioning Extensions
to WebDAV [RFC3253]. to WebDAV [RFC3253].
In addition, a server: In addition, a server:
o SHOULD support vCard v4 [I-D.ietf-vcarddav-vcardrev] as a media o SHOULD support vCard v4 [I-D.ietf-vcarddav-vcardrev] as a media
type for the address object resource format; type for the address object resource format;
o SHOULD support the extended MKCOL method o SHOULD support the extended MKCOL method [RFC5689] to create
[I-D.ietf-vcarddav-webdav-mkcol] to create address book address book collections as defined in Section 6.3.1 of this
collections as defined in Section 6.3.1 of this document. document.
o SHOULD support the DAV:current-user-principal-URL property as o SHOULD support the DAV:current-user-principal-URL property as
defined in [RFC5397] to give clients a fast way to locate user defined in [RFC5397] to give clients a fast way to locate user
principals. principals.
4. Address Book Data Model 4. Address Book Data Model
As a brief overview, a CardDAV address book is modeled as a WebDAV As a brief overview, a CardDAV address book is modeled as a WebDAV
collection with a well defined structure; each of these address book collection with a well defined structure; each of these address book
collections contain a number of resources representing address collections contain a number of resources representing address
skipping to change at page 13, line 45 skipping to change at page 13, line 45
6.3. Creating Resources 6.3. Creating Resources
Address book collections and address object resources may be created Address book collections and address object resources may be created
by either a CardDAV client or by the CardDAV server. This by either a CardDAV client or by the CardDAV server. This
specification defines restrictions and a data model that both clients specification defines restrictions and a data model that both clients
and servers MUST adhere to when manipulating such address data. and servers MUST adhere to when manipulating such address data.
6.3.1. Extended MKCOL Method 6.3.1. Extended MKCOL Method
An HTTP request using the extended MKCOL method An HTTP request using the extended MKCOL method [RFC5689] can be used
[I-D.ietf-vcarddav-webdav-mkcol] can be used to create a new address to create a new address book collection resource. A server MAY
book collection resource. A server MAY restrict address book restrict address book collection creation to particular collections.
collection creation to particular collections.
To create an address book, the client sends an extended MKCOL request To create an address book, the client sends an extended MKCOL request
to the server and in the body of the request sets the DAV: to the server and in the body of the request sets the DAV:
resourcetype property to the resource type for an address book resourcetype property to the resource type for an address book
collection as defined in Section 5.2. collection as defined in Section 5.2.
Support for creating address books on the server is only RECOMMENDED Support for creating address books on the server is only RECOMMENDED
and not REQUIRED because some address book stores only support one and not REQUIRED because some address book stores only support one
address book per user (or principal), and those are typically pre- address book per user (or principal), and those are typically pre-
created for each account. However, servers and clients are strongly created for each account. However, servers and clients are strongly
skipping to change at page 24, line 27 skipping to change at page 24, line 27
The CARDDAV:addressbook-query REPORT performs a search for all The CARDDAV:addressbook-query REPORT performs a search for all
address object resources that match a specified filter. The response address object resources that match a specified filter. The response
of this report will contain all the WebDAV properties and address of this report will contain all the WebDAV properties and address
object resource data specified in the request. In the case of the object resource data specified in the request. In the case of the
CARDDAV:address-data XML element, one can explicitly specify the CARDDAV:address-data XML element, one can explicitly specify the
vCard properties that should be returned in the address object vCard properties that should be returned in the address object
resource data that matches the filter. resource data that matches the filter.
The format of this report is modeled on the PROPFIND method. The The format of this report is modeled on the PROPFIND method. The
request and response bodies of the CARDAV:addressbook-query report request and response bodies of the CARDDAV:addressbook-query report
use XML elements that are also used by PROPFIND. In particular the use XML elements that are also used by PROPFIND. In particular the
request can include XML elements to request WebDAV properties to be request can include XML elements to request WebDAV properties to be
returned. When that occurs the response should follow the same returned. When that occurs the response should follow the same
behavior as PROPFIND with respect to the DAV:multistatus response behavior as PROPFIND with respect to the DAV:multistatus response
elements used to return specific WebDAV property results. For elements used to return specific WebDAV property results. For
instance, a request to retrieve the value of a WebDAV property which instance, a request to retrieve the value of a WebDAV property which
does not exist is an error and MUST be noted with a response XML does not exist is an error and MUST be noted with a response XML
element which contains a 404 (Not Found) status value. element which contains a 404 (Not Found) status value.
Support for the CARDDAV:addressbook-query REPORT is REQUIRED. Support for the CARDDAV:addressbook-query REPORT is REQUIRED.
skipping to change at page 26, line 11 skipping to change at page 26, line 11
is useful when clients are only interested in a few matches, or only is useful when clients are only interested in a few matches, or only
have limited space to display results to users and thus don't need have limited space to display results to users and thus don't need
the overhead of receiving more than that. When the results are the overhead of receiving more than that. When the results are
truncated by the server, the server MUST follow the rules below for truncated by the server, the server MUST follow the rules below for
indicating a result set truncation to the client. indicating a result set truncation to the client.
8.6.2. Truncation of Results 8.6.2. Truncation of Results
A server MAY limit the number of resources in a response, for A server MAY limit the number of resources in a response, for
example, to limit the amount of work expended in processing a query, example, to limit the amount of work expended in processing a query,
or as the result of an explicit limit set by the client. If it does or as the result of an explicit limit set by the client. If the
so, the response MUST use status code 207, return a DAV:multistatus result set is truncated because of such a limit, the response MUST
response body, and indicate a status of 507 (Insufficient Storage) use status code 207, return a DAV:multistatus response body, and
for the request URI. That DAV:response element SHOULD include a DAV: indicate a status of 507 (Insufficient Storage) for the request URI.
error element with the DAV:number-of-matches-within-limits That DAV:response element SHOULD include a DAV:error element with the
precondition, as defined in [RFC3744] (Section 9.2). DAV:number-of-matches-within-limits precondition, as defined in
[RFC3744] (Section 9.2).
The server SHOULD also include the partial results in additional DAV: The server SHOULD also include the partial results in additional DAV:
response elements. If a client requested limit is being applied, the response elements. If a client requested limit is being applied, the
507 response for the request URI MUST NOT be included in calculating 507 response for the request URI MUST NOT be included in calculating
the limit (e.g., if the client requests that only a single result be the limit (e.g., if the client requests that only a single result be
returned, and multiple matches are present, then the DAV:multistatus returned, and multiple matches are present, then the DAV:multistatus
response will include one DAV:response for the matching resource and response will include one DAV:response for the matching resource and
one DAV:response for the 507 status on the request URI). one DAV:response for the 507 status on the request URI).
8.6.3. Example: Partial Retrieval of vCards Matching NICKNAME 8.6.3. Example: Partial Retrieval of vCards Matching NICKNAME
skipping to change at page 33, line 40 skipping to change at page 33, line 40
elements. Address data is returned in the CARDDAV:address-data elements. Address data is returned in the CARDDAV:address-data
element inside the DAV:prop element. element inside the DAV:prop element.
In the case of an error accessing any of the provided DAV:href In the case of an error accessing any of the provided DAV:href
resources, the server MUST return the appropriate error status resources, the server MUST return the appropriate error status
code in the DAV:status element of the corresponding DAV:response code in the DAV:status element of the corresponding DAV:response
element. element.
Preconditions: Preconditions:
(CARDAV:supported-address-data): The attributes "content-type" and (CARDDAV:supported-address-data): The attributes "content-type"
"version" of the CARDDAV:address-data XML elements (see and "version" of the CARDDAV:address-data XML elements (see
Section 10.4) specify a media type supported by the server for Section 10.4) specify a media type supported by the server for
address object resources. address object resources.
Postconditions: Postconditions:
None. None.
8.7.1. Example: CARDDAV:addressbook-multiget Report 8.7.1. Example: CARDDAV:addressbook-multiget Report
In this example, the client requests the server to return specific In this example, the client requests the server to return specific
skipping to change at page 36, line 34 skipping to change at page 36, line 34
HTTP/1.1 207 Multi-Status HTTP/1.1 207 Multi-Status
Date: Sat, 11 Nov 2006 09:32:12 GMT Date: Sat, 11 Nov 2006 09:32:12 GMT
Content-Type: text/xml; charset="utf-8" Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?> <?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:" <D:multistatus xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:carddav"> xmlns:C="urn:ietf:params:xml:ns:carddav">
<D:response> <D:response>
<D:response>
<D:href>/home/bernard/addressbook/vcf3.vcf</D:href> <D:href>/home/bernard/addressbook/vcf3.vcf</D:href>
<D:status>HTTP/1.1 415 Unsupported Media Type</D:status> <D:status>HTTP/1.1 415 Unsupported Media Type</D:status>
<D:error><C:supported-address-data-conversion/></D:error> <D:error><C:supported-address-data-conversion/></D:error>
<D:responsedescription>Unable to convert from vCard v3.0 <D:responsedescription>Unable to convert from vCard v3.0
to vCard v4.0</D:responsedescription> to vCard v4.0</D:responsedescription>
</D:response> </D:response>
</D:multistatus> </D:multistatus>
9. Client Guidelines 9. Client Guidelines
9.1. Restrict the Properties Returned 9.1. Restrict the Properties Returned
Clients may not need all the properties in a vCard object when Clients may not need all the properties in a vCard object when
presenting information to the user, or looking up specific items for presenting information to the user, or looking up specific items for
their email address, for example. Since some property data can be their email address, for example. Since some property data can be
large (e.g., PHOTO or SOUND with inline content) clients can choose large (e.g., PHOTO or SOUND with inline content) clients can choose
to ignore those by only requesting the specific items it knows it to ignore those by only requesting the specific items it knows it
will use, through use of the CARDDAV:address-data XML element in the will use, through use of the CARDDAV:address-data XML element in the
relevant reports. relevant reports.
skipping to change at page 37, line 20 skipping to change at page 37, line 16
to ignore those by only requesting the specific items it knows it to ignore those by only requesting the specific items it knows it
will use, through use of the CARDDAV:address-data XML element in the will use, through use of the CARDDAV:address-data XML element in the
relevant reports. relevant reports.
However, if a client needs to make a change to a vCard, it can only However, if a client needs to make a change to a vCard, it can only
change the entire vCard data via a PUT request. There is no way to change the entire vCard data via a PUT request. There is no way to
incrementally make a change to a set of properties within a vCard incrementally make a change to a set of properties within a vCard
object resource. As a result the client will have to cache the object resource. As a result the client will have to cache the
entire set of properties on a resource that is being changed. entire set of properties on a resource that is being changed.
9.2. Use of Locking 9.2. Avoiding Lost Updates
WebDAV [RFC4918] locks can be used to prevent two clients modifying
the same resource from either overwriting each others' changes
(though that problem can also be solved by using ETags) and also to
prevent the user from making changes that will conflict with another
set of changes. In a multi-user address book system, the address
book client could lock an address object resource while the user is
editing the vCard data, and unlock the address object resource when
the user finishes or cancels. Locks can also be used to prevent
changes while data is being reorganized. For example, an address
book client might lock two address book collections prior to moving a
bunch of address object resources from one to another.
Clients may request a lock timeout period that is appropriate to the When resources are accessed by multiple clients, the possibility of
use case. When the user explicitly decides to reserve a resource and clients overwriting each other's changes exists. To alleviate that,
prevent other changes, a long timeout might be appropriate, but in clients SHOULD use the If-Match request header on PUT requests with
cases when the client automatically decides to lock the resource the the ETag of the previously retrieved resource data to check whether
timeout should be short (and the client can always refresh the lock the resource was modified since it was previously retrieved. If a
should it need to). A short lock timeout means that if the client is pre-condition failure occurs, clients need to reload the resource and
unable to remove the lock, the other address book users aren't go through their own merge or conflict resolution process before
prevented from making changes. writing back the data (again using the If-Match check).
9.3. Client Configuration 9.3. Client Configuration
When CardDAV clients need to be configured, the key piece of When CardDAV clients need to be configured, the key piece of
information that they require is the principal-URL of the user whose information that they require is the principal-URL of the user whose
address book information is desired. Servers SHOULD support the DAV: address book information is desired. Servers SHOULD support the DAV:
current-user-principal-URL property as defined in [RFC5397] to give current-user-principal-URL property as defined in [RFC5397] to give
clients a fast way to locate user principals. clients a fast way to locate user principals.
Given support for SRV records (Section 11) and DAV:current-user- Given support for SRV records (Section 11) and DAV:current-user-
skipping to change at page 40, line 38 skipping to change at page 40, line 16
Finally, when used in an address book REPORT response, the Finally, when used in an address book REPORT response, the
CARDDAV:address-data XML element specifies the content of a CARDDAV:address-data XML element specifies the content of a
address object resource. Given that XML parsers normalize the address object resource. Given that XML parsers normalize the
two-character sequence CRLF (US-ASCII decimal 13 and US-ASCII two-character sequence CRLF (US-ASCII decimal 13 and US-ASCII
decimal 10) to a single LF character (US-ASCII decimal 10), the CR decimal 10) to a single LF character (US-ASCII decimal 10), the CR
character (US-ASCII decimal 13) MAY be omitted in address object character (US-ASCII decimal 13) MAY be omitted in address object
resources specified in the CARDDAV:address-data XML element. resources specified in the CARDDAV:address-data XML element.
Furthermore, address object resources specified in the CARDDAV: Furthermore, address object resources specified in the CARDDAV:
address-data XML element MAY be invalid per their media type address-data XML element MAY be invalid per their media type
specification if the CARDAV:address-data XML element part of the specification if the CARDDAV:address-data XML element part of the
address book REPORT request did not specify required vCard address book REPORT request did not specify required vCard
properties (e.g., UID, etc.) or specified a CARDDAV:prop XML properties (e.g., UID, etc.) or specified a CARDDAV:prop XML
element with the "novalue" attribute set to "yes". element with the "novalue" attribute set to "yes".
Note: The CARDDAV:address-data XML element is specified in requests Note: The CARDDAV:address-data XML element is specified in requests
and responses inside the DAV:prop XML element as if it were a and responses inside the DAV:prop XML element as if it were a
WebDAV property. However, the CARDDAV:address-data XML element is WebDAV property. However, the CARDDAV:address-data XML element is
not a WebDAV property and as such it is not returned in PROPFIND not a WebDAV property and as such it is not returned in PROPFIND
responses nor used in PROPPATCH requests. responses nor used in PROPPATCH requests.
skipping to change at page 43, line 4 skipping to change at page 42, line 46
NOTE: The CARDDAV:prop element defined here has the same name as the NOTE: The CARDDAV:prop element defined here has the same name as the
DAV:prop element defined in WebDAV. However, the CARDDAV:prop DAV:prop element defined in WebDAV. However, the CARDDAV:prop
element defined here uses the "urn:ietf:params:xml:ns:carddav" element defined here uses the "urn:ietf:params:xml:ns:carddav"
namespace, as opposed to the "DAV:" namespace used for the DAV:prop namespace, as opposed to the "DAV:" namespace used for the DAV:prop
element defined in WebDAV. element defined in WebDAV.
10.5. CARDDAV:filter XML Element 10.5. CARDDAV:filter XML Element
Name: filter Name: filter
Namespace: urn:ietf:params:xml:ns:carddav
Namespace: urn:ietf:params:xml:ns:carddav
Purpose: Determines which matching objects are returned. Purpose: Determines which matching objects are returned.
Description: The "filter" element specifies the search filter used Description: The "filter" element specifies the search filter used
to match address objects that should be returned by a report. The to match address objects that should be returned by a report. The
"test" attribute specifies whether any (logical OR) or all "test" attribute specifies whether any (logical OR) or all
(logical AND) of the prop-filter tests needs to match in order for (logical AND) of the prop-filter tests needs to match in order for
the overall filter to match. the overall filter to match.
Definition: Definition:
skipping to change at page 43, line 46 skipping to change at page 43, line 44
exists, and the CARDDAV:prop-filter is empty, or it matches any exists, and the CARDDAV:prop-filter is empty, or it matches any
specified CARDDAV:text-match or CARDDAV:param-filter specified CARDDAV:text-match or CARDDAV:param-filter
conditions. The "test" attribute specifies whether any conditions. The "test" attribute specifies whether any
(logical OR) or all (logical AND) of the text-filter and param- (logical OR) or all (logical AND) of the text-filter and param-
filter tests need to match in order for the overall filter to filter tests need to match in order for the overall filter to
match. match.
or: or:
* A vCard property of the type specified by the "name" attribute * A vCard property of the type specified by the "name" attribute
does not exist, and the CARDAV:is-not-defined element is does not exist, and the CARDDAV:is-not-defined element is
specified. specified.
vCard allows a "group" prefix to appear before a property name in vCard allows a "group" prefix to appear before a property name in
the vCard data. When the "name" attribute does not specify a the vCard data. When the "name" attribute does not specify a
group prefix, it MUST match properties in the vCard data without a group prefix, it MUST match properties in the vCard data without a
group prefix or with any group prefix. When the "name" attribute group prefix or with any group prefix. When the "name" attribute
includes a group prefix, it MUST match properties that have includes a group prefix, it MUST match properties that have
exactly the same group prefix and name. e.g.: a "name" set to exactly the same group prefix and name. e.g.: a "name" set to
"TEL" will match "TEL", "X-ABC.TEL", "X-ABC-1.TEL" vCard "TEL" will match "TEL", "X-ABC.TEL", "X-ABC-1.TEL" vCard
properties. A "name" set to "X-ABC.TEL" will match an "X-ABC.TEL" properties. A "name" set to "X-ABC.TEL" will match an "X-ABC.TEL"
skipping to change at page 48, line 36 skipping to change at page 48, line 30
details of character handling are covered in the description of that details of character handling are covered in the description of that
element (see Section 10.5.4). element (see Section 10.5.4).
13. Security Considerations 13. Security Considerations
HTTP protocol transactions are sent in the clear over the network HTTP protocol transactions are sent in the clear over the network
unless protection from snooping is negotiated. This can be unless protection from snooping is negotiated. This can be
accomplished by use of TLS as defined in [RFC2818]. In particular, accomplished by use of TLS as defined in [RFC2818]. In particular,
if HTTP Basic authentication [RFC2617] is available, the server MUST if HTTP Basic authentication [RFC2617] is available, the server MUST
allow TLS to be used at the same time, and SHOULD prevent use of allow TLS to be used at the same time, and SHOULD prevent use of
Basic authentication when TLS is not in use. Basic authentication when TLS is not in use. Clients SHOULD use TLS
whenever possible.
With the ACL extension [RFC3744] present, WebDAV allows control over With the ACL extension [RFC3744] present, WebDAV allows control over
who can access (read or write) any resource on the WebDAV server. In who can access (read or write) any resource on the WebDAV server. In
addition, WebDAV ACL provides for an "inheritance" mechanism, whereby addition, WebDAV ACL provides for an "inheritance" mechanism, whereby
resources may inherit access privileges from other resources. Often resources may inherit access privileges from other resources. Often
the "other" resource is a parent collection of the resource itself. the "other" resource is a parent collection of the resource itself.
Clients MUST take care to ensure users are aware of which address Servers are able to support address books that are "private"
books may be "private" (i.e. only accessible to them) and which are (accessible only to the "owner"), "shared" (accessible to the owner
"shared" (i.e. accessible to others). and other specified authenticated users), and "public" (accessible to
any authenticated or unauthenticated users). When provisioning
Since web servers are often the target of automated indexing address books of a particular type, servers MUST ensure that the
applications that gather data from the server, analyze it and extract correct privileges are applied on creation, and in particular private
'interesting' parts, great care must be taken when allowing and shared address books MUST NOT be accessible by unauthenticated
unauthenticated access to any address book or address object data. users (to prevent data from being automatically searched or indexed
by web "crawlers").
Clients MAY choose to warn users when they create address data in a Clients SHOULD warn users in an appropriate fashion when they copy or
public address book, copy or move address data into public address move address data from a private address book to a shared address
books, or change access privileges in such a way as to expose address book or public address book. Clients SHOULD provide a clear
data to unauthenticated users. indication as to which address books are private, shared or public.
Clients SHOULD provide an appropriate warning when changing access
privileges for a private or shared address book with data so as to
allow unauthenticated users access.
This specification currently relies on standard HTTP authentication This specification currently relies on standard HTTP authentication
mechanisms for identifying users. These comprise Basic and Digest mechanisms for identifying users. These comprise Basic and Digest
authentication [RFC2617] as well as TLS [RFC2818] using client-side authentication [RFC2617] as well as TLS [RFC2818] using client-side
certificates. certificates.
14. IANA Consideration 14. IANA Consideration
This document uses a URN to describe a new XML namespace conforming This document uses a URN to describe a new XML namespace conforming
to the registry mechanism described in [RFC3688]. to the registry mechanism described in [RFC3688].
skipping to change at page 49, line 49 skipping to change at page 49, line 48
16. References 16. References
16.1. Normative References 16.1. Normative References
[I-D.ietf-vcarddav-vcardrev] [I-D.ietf-vcarddav-vcardrev]
Perreault, S. and P. Resnick, "vCard Format Perreault, S. and P. Resnick, "vCard Format
Specification", draft-ietf-vcarddav-vcardrev-08 (work in Specification", draft-ietf-vcarddav-vcardrev-08 (work in
progress), July 2009. progress), July 2009.
[I-D.ietf-vcarddav-webdav-mkcol]
Daboo, C., "Extended MKCOL for WebDAV",
draft-ietf-vcarddav-webdav-mkcol-06 (work in progress),
August 2009.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2426] Dawson, F. and T. Howes, "vCard MIME Directory Profile", [RFC2426] Dawson, F. and T. Howes, "vCard MIME Directory Profile",
RFC 2426, September 1998. RFC 2426, September 1998.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
skipping to change at page 51, line 14 skipping to change at page 51, line 9
(TLS) Protocol Version 1.2", RFC 5246, August 2008. (TLS) Protocol Version 1.2", RFC 5246, August 2008.
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
Housley, R., and W. Polk, "Internet X.509 Public Key Housley, R., and W. Polk, "Internet X.509 Public Key
Infrastructure Certificate and Certificate Revocation List Infrastructure Certificate and Certificate Revocation List
(CRL) Profile", RFC 5280, May 2008. (CRL) Profile", RFC 5280, May 2008.
[RFC5397] Sanchez, W. and C. Daboo, "WebDAV Current Principal [RFC5397] Sanchez, W. and C. Daboo, "WebDAV Current Principal
Extension", RFC 5397, December 2008. Extension", RFC 5397, December 2008.
[RFC5689] Daboo, C., "Extended MKCOL for Web Distributed Authoring
and Versioning (WebDAV)", RFC 5689, September 2009.
[W3C.REC-xml-20081126] [W3C.REC-xml-20081126]
Paoli, J., Yergeau, F., Bray, T., Sperberg-McQueen, C., Paoli, J., Yergeau, F., Bray, T., Sperberg-McQueen, C.,
and E. Maler, "Extensible Markup Language (XML) 1.0 (Fifth and E. Maler, "Extensible Markup Language (XML) 1.0 (Fifth
Edition)", World Wide Web Consortium Recommendation REC- Edition)", World Wide Web Consortium Recommendation REC-
xml-20081126, November 2008, xml-20081126, November 2008,
<http://www.w3.org/TR/2008/REC-xml-20081126>. <http://www.w3.org/TR/2008/REC-xml-20081126>.
16.2. Informative References 16.2. Informative References
[IMSP] Myers, J., "IMSP - Internet Message Support Protocol", [IMSP] Myers, J., "IMSP - Internet Message Support Protocol",
skipping to change at page 51, line 36 skipping to change at page 51, line 34
[RFC2244] Newman, C. and J. Myers, "ACAP -- Application [RFC2244] Newman, C. and J. Myers, "ACAP -- Application
Configuration Access Protocol", RFC 2244, November 1997. Configuration Access Protocol", RFC 2244, November 1997.
[RFC4510] Zeilenga, K., "Lightweight Directory Access Protocol [RFC4510] Zeilenga, K., "Lightweight Directory Access Protocol
(LDAP): Technical Specification Road Map", RFC 4510, (LDAP): Technical Specification Road Map", RFC 4510,
June 2006. June 2006.
Appendix A. Change History (to be removed prior to publication as an Appendix A. Change History (to be removed prior to publication as an
RFC) RFC)
Changes in -10
1. Updated to MKColExt RFC reference.
2. GenART Review: changed to clients SHOULD support TLS.
3. GenART Review: changed security considerations in relation to
clients indicating which address books are private, shared or
public.
4. IESG Review: re-wrote section on locking to instead describe how
to avoid lost updates using ETags.
5. IESG Review: removed disadvantage describing stateless protocol
nature.
6. IESG Review: clarified that 507 is only returned when truncation
of the results set occurs.
7. IESG Review: added additional text in security considerations
about the handling private, shared and public address books.
8. Fixed typos.
9. Fixed some XML example errors.
Changes in -09 Changes in -09
1. AD Review: support for vCard v4 is now a SHOULD. 1. AD Review: support for vCard v4 is now a SHOULD.
2. As a result of the above, added a sub-section on content 2. As a result of the above, added a sub-section on content
conversion that defines a new precondition, and added an example conversion that defines a new precondition, and added an example
of a conversion failure when doing a multiget. of a conversion failure when doing a multiget.
Changes in -08 Changes in -08
 End of changes. 32 change blocks. 
77 lines changed or deleted 90 lines changed or added

This html diff was produced by rfcdiff 1.37a. The latest version is available from http://tools.ietf.org/tools/rfcdiff/