One document matched: draft-daboo-carddav-directory-gateway-02.xml
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="../rfc2629.xslt"?>
<!DOCTYPE rfc SYSTEM 'rfc2629.dtd' [
<!ENTITY rfc2119 SYSTEM 'bibxml/reference.RFC.2119.xml'>
<!ENTITY rfc2426 SYSTEM 'bibxml/reference.RFC.2426.xml'>
<!ENTITY rfc4510 SYSTEM 'bibxml/reference.RFC.4510.xml'>
<!ENTITY rfc4918 SYSTEM 'bibxml/reference.RFC.4918.xml'>
<!ENTITY W3C.REC-xml-20081126 SYSTEM 'bibxml4/reference.W3C.REC-xml-20081126.xml'>
<!ENTITY idCardDAV SYSTEM 'bibxml3/reference.I-D.ietf-vcarddav-carddav.xml'>
]>
<?rfc toc="yes"?>
<?rfc tocdepth="4"?><!-- default = 3 -->
<?rfc strict="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="std" ipr="trust200902" docName="draft-daboo-carddav-directory-gateway-02" updates="XXXX-CardDAV">
<front>
<title>CardDAV Directory Gateway Extension</title>
<author initials="C." surname="Daboo" fullname="Cyrus Daboo">
<organization abbrev="Apple Inc.">
Apple Inc.
</organization>
<address>
<postal>
<street>
1 Infinite Loop
</street>
<city>
Cupertino
</city>
<region>
CA
</region>
<code>95014</code>
<country>
USA
</country>
</postal>
<email>
cyrus@daboo.name
</email>
<uri>
http://www.apple.com/
</uri>
</address>
</author>
<date />
<area>
Applications
</area>
<abstract>
<t>
This document defines an extension to the vCard Extensions to WebDAV (CardDAV) protocol that allows a server to expose a directory as a read-only address book collection.
</t>
</abstract>
</front>
<middle>
<section title="Introduction and Overview">
<t>
The <xref target='I-D.ietf-vcarddav-carddav'>CardDAV</xref> protocol defines a standard way of accessing, managing, and sharing contact information based on the <xref target='RFC2426'>vCard</xref> format. Often, in an enterprise or service provider environment, a directory of all users hosted on the server (or elsewhere) is available (for example via <xref target="RFC4510">Lightweight Directory Access Protocol (LDAP)</xref> or some direct database access). It would be convenient for CardDAV clients if this directory were exposed as a "global" address book on the CardDAV server so it could be searched in the same way as personal address books are. This specification defines a "directory gateway" feature extension to CardDAV to enable this.
</t>
<t>
This specification adds one new WebDAV property to principal resources that contains the URL to one or more directory gateway address book collection resources. It is important for clients to be able to distinguish this address book collection from others because there are specific limitations involved in using it as described below. To aid that, this specification defines an XML element that can be included as a child element of the DAV:resourcetype property of address book collections to identify them as directory gateways.
</t>
<t>
Note that this feature is in no way intended to replace full directory access - it is meant to simply provide a convenient way for CardDAV clients to query contact-related attributes in directory records.
</t>
</section>
<section title="Conventions" anchor="conventions">
<t>
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in <xref target="RFC2119" />.
</t>
<t>
The term "protected" is used in the Conformance field of property definitions as defined in Section 15 of <xref target="RFC4918"/>.
</t>
<t>
This document uses XML DTD fragments (<xref target="W3C.REC-xml-20081126"/>, Section 3.2) as a purely notational convention. WebDAV request and response bodies cannot be validated by a DTD due to the specific extensibility rules defined in Section 17 of [RFC4918] and due to the fact that all XML elements defined by this specification use the XML namespace name "DAV:". In particular:
<list style='numbers'>
<t>element names use the "DAV:" namespace,</t>
<t>element ordering is irrelevant unless explicitly stated,</t>
<t>extension elements (elements not already defined as valid child elements) may be added anywhere, except when explicitly stated otherwise,</t>
<t>extension attributes (attributes not already defined as valid for this element) may be added anywhere, except when explicitly stated otherwise.</t>
</list>
</t>
<t>
When XML element types in the namespaces "DAV:" and "urn:ietf:params:xml:ns:carddav" are referenced in this document outside of the context of an XML fragment, the strings "DAV:" and "CARDDAV:" will be prefixed to the element types, respectively.
</t>
</section>
<section anchor="property" title="CARDDAV:directory-gateway Property">
<t>
<list style="hanging">
<t hangText="Name:">
directory-gateway
</t>
<t hangText="Namespace:">
urn:ietf:params:xml:ns:carddav
</t>
<t hangText="Purpose:">
Identifies URLs of CardDAV address book collections acting as a directory gateway for the server.
</t>
<t hangText="Protected:">
MUST be protected.
</t>
<t hangText="allprop behavior:">
SHOULD NOT be returned by a PROPFIND DAV:allprop request.
</t>
<t hangText="Description:">
The CARDDAV:directory-gateway identifies address book collection resources that are directory gateway address books for the server.
</t>
<t hangText="Definition:">
<figure>
<artwork><![CDATA[
<!ELEMENT directory-gateway (DAV:href*)>
]]></artwork>
</figure>
</t>
<t hangText="Example:">
<figure>
<artwork><![CDATA[
<C:directory-gateway xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:carddav">
<D:href>/directory</D:href>
</C:directory-gateway>
]]></artwork>
</figure>
</t>
</list>
</t>
</section>
<section title='XML Element Definitions'>
<section title="CARDDAV:directory" anchor="CARDDAV:directory">
<t>
<list style="hanging">
<t hangText="Name:">directory</t>
<t hangText="Namespace:">urn:ietf:params:xml:ns:carddav</t>
<t hangText="Purpose:">Used to indicate that an address book collection is a directory gateway.</t>
<t hangText="Description:">This element appears in the DAV:resourcetype property on a address book collection resources that are directory gateways. Clients can use the presence of this element to identify directory gateway collections when doing PROPFINDs to list collection contents.</t>
<t hangText="Definition:">
<figure>
<artwork><![CDATA[
<!ELEMENT directory EMPTY>]]></artwork>
</figure>
</t>
<t hangText="Example:">
<figure>
<artwork><![CDATA[
<D:resourcetype xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:carddav">
<D:collection/>
<C:addressbook/>
<C:directory/>
</D:resourcetype>
]]></artwork>
</figure>
</t>
</list>
</t>
</section>
</section>
<section title="Client Guidelines" anchor="Client_Guidelines">
<t>
Clients wishing to make use of directory gateway address books can request the <xref target='property'>CARDDAV:directory-gateway property</xref> when examining other properties on the principal resource for the user. If the property is not present, then the directory gateway feature is not supported by the server at that time.
</t>
<t>
Clients can also detect the presence of directory gateway address book collections by retrieving the DAV:resourcetype property on collections that it lists, and look for the presence of the <xref target='CARDDAV:directory'>CARDDAV:directory element</xref>.
</t>
<t>
Since the directory being exposed via a directory gateway address book collection could be large, clients SHOULD limit the number of results returned in an CARDDAV:addressbook-query REPORT as defined in Section 8.6.1 of <xref target='I-D.ietf-vcarddav-carddav'/>.
</t>
<t>
Clients MUST treat the directory gateway address book collection as a read-only collection, so HTTP methods that modify resource data or properties in the address book collection MUST NOT be used.
</t>
<t>
Clients SHOULD NOT attempt to cache the entire contents of the directory gateway address book collection resource by retrieving all resources, or trying to examine all the properties of all resources (e.g., via a PROPFIND Depth:1 request). Instead, CARDDAV:addressbook-query REPORTs are used to search for specific address book object resources, and CARDDAV:multiget REPORTs and individual GET requests can be made to retrieve the actual vCard data for address book object resources found via a query.
</t>
<t>
When presenting directory gateway collections to the user, clients SHOULD use the DAV:displayname property on the corresponding address book collections as the name of the directory gateway. This is important in the case where more than one directory gateway is available. Clients MAY also provide descriptive information about each directory gateway by examining the CARDDAV:addressbook-description property (see Section 6.2.1 of <xref target='I-D.ietf-vcarddav-carddav'/>) on the resource.
</t>
</section>
<section title="Server Guidelines">
<t>
Servers wishing to expose a directory gateway as an address book collection MUST include the CARDDAV:directory-gateway property on all principal resources of users expected to use the feature.
</t>
<t>
Since the directory being exposed via the directory gateway address book collection could be large, servers SHOULD truncate the number of results returned in an CARDDAV:addressbook-query REPORT as defined in Section 8.6.2 of <xref target='I-D.ietf-vcarddav-carddav'/>. In addition, servers SHOULD disallow requests that effectively enumerate the collection contents (e.g., PROPFIND Depth:1, trivial CARDDAV:addressbook-query, DAV:sync-collection REPORT).
</t>
<t>
Servers need to expose the directory information as a set of address book object resources in the directory gateway address book collection resource. To do that, a mapping between the directory record format and the vCard data has to be applied. In general, only directory record attributes that have a direct equivalent in vCard SHOULD be mapped. It is up to individual implementations to determine which attributes to map. But in all cases servers MUST generate valid vCard data as returned to the client. In addition, as required by CardDAV, the UID vCard property MUST be present in the vCard data, and this value MUST be persistent from query to query for the same directory record.
</t>
<t>
Multiple directory sources could be available to the server. The server MAY use a single directory gateway resource to aggregate results from each directory source. When doing so care is needed when dealing with potential records that refer to the same entity. Servers MAY suppress any duplicates that they are able to determine themselves. Alternatively, multiple directory sources can be exposed as separate directory gateway resources.
</t>
<t>
For any directory source, a server MAY expose multiple directory gateway resources where each represents a different query "scope" for the directory. Different scopes MAY be offered to different principals on the server. For example, the server might expose an entire company directory for searching as the resource "/directory-all" to all principals, but then provide "/directory-department-XYZ" as another directory gateway that has a search scope that implicitly limits the search results to just the "XYZ" department. Users in that department would then have a CARDDAV:directory-gateway property on their principal resource that included the "/directory-department-XYZ" resource. Users in other departments would have corresponding directory gateway resources available to them.
</t>
<t>
Records in a directory can include data for more than just people, e.g, resources such as rooms or projectors, groups, computer systems etc. It is up to individual implementations to determine the most appropriate "scope" for the data returned via the directory gateway by filtering the appropriate record types. As above, servers could choose to expose people and resources under different directory gateway resources by implicitly limiting the search "scope" for each of those.
</t>
<t>
Servers MAY apply implementation defined access rules to determine, on a per-user basis, what records are returned to a particularly user and the content of those records exposed via vCard data. This per-user behavior is in addition to the general security requirements detailed below.
</t>
<t>
When multiple directory gateway collections are present, servers SHOULD provide a DAV:displayname property on each that disambiguates them. Servers MAY include a CARDDAV:addressbook-description property (see Section 6.2.1 of <xref target='I-D.ietf-vcarddav-carddav'/>) on each directory gateway resource to provide a description of the directory and any search "scope" that might be used, or any other useful information for users.
</t>
</section>
<section title="Security Considerations">
<t>
Servers MUST ensure that client requests against the directory gateway address book collection cannot use excessive resources (CPU, memory, network bandwidth etc), given that the directory could be large.
</t>
<t>
Servers MUST take care not to expose sensitive directory record attributes in the vCard data via the directory gateway address book. In general only those properties that have direct correspondence in vCard SHOULD be exposed.
</t>
<t>
Servers need to determine whether it is appropriate for the directory information to be available via CardDAV to unauthenticated users. If not, servers MUST ensure that unauthenticated users do not have access to the directory gateway address book object resource and its contents. If unauthenticated access is allowed, servers MAY choose to limit the set of vCard properties that are searchable or returned in the address book object resources when unauthenticated requests are made.
</t>
</section>
<section title="IANA Consideration">
<t>
This document does not require any actions on the part of IANA.
</t>
</section>
<section title="Acknowledgments">
<t>
</t>
</section>
</middle>
<back>
<references title="Normative References">
&rfc2119;
&rfc2426;
&rfc4918;
&W3C.REC-xml-20081126;
&idCardDAV;
</references>
<references title="Informative References">
&rfc4510;
</references>
<section title="Change History (to be removed prior to publication as an RFC)">
<t>Changes in -02
<list style="numbers">
<t>Added CARDDAV:directory element for use in DAV:resourcetype</t>
<t>Allow CARDDAV:directory-gateway to be multi-valued</t>
<t>Explain how a server could implicit "scope" queries on different directory gateway resources</t>
</list>
</t>
<t>Changes in -01
<list style="numbers">
<t>Remove duplicated text in a couple of sections</t>
<t>Add example of LDAP/generic database as possible directory "sources"</t>
<t>Add text to explain why the client needs to treat this as special and thus the need for a property</t>
<t>Added text to server guidelines indicating requirements for handling vCard UID properties</t>
<t>Added text to server guidelines explain that different record "types" may exist in the directory and the server is free to filter those as appropriate</t>
<t>Added text to server guidelines indicating that server are free to aggregate directory records from multiple sources</t>
<t>Added text to server guidelines indicating that servers are free to apply implementation defined access control to the returned data on a per-user basis</t>
</list>
</t>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 23:56:29 |