aboutsummaryrefslogtreecommitdiffstats
path: root/vendor/sabre/dav/docs/draft-daboo-carddav-directory-gateway-02.txt
diff options
context:
space:
mode:
Diffstat (limited to 'vendor/sabre/dav/docs/draft-daboo-carddav-directory-gateway-02.txt')
-rw-r--r--vendor/sabre/dav/docs/draft-daboo-carddav-directory-gateway-02.txt560
1 files changed, 560 insertions, 0 deletions
diff --git a/vendor/sabre/dav/docs/draft-daboo-carddav-directory-gateway-02.txt b/vendor/sabre/dav/docs/draft-daboo-carddav-directory-gateway-02.txt
new file mode 100644
index 000000000..63aa8b29c
--- /dev/null
+++ b/vendor/sabre/dav/docs/draft-daboo-carddav-directory-gateway-02.txt
@@ -0,0 +1,560 @@
+
+
+
+Network Working Group C. Daboo
+Internet-Draft Apple Inc.
+Updates: XXXX-CardDAV August 24, 2010
+(if approved)
+Intended status: Standards Track
+Expires: February 25, 2011
+
+
+ CardDAV Directory Gateway Extension
+ draft-daboo-carddav-directory-gateway-02
+
+Abstract
+
+ 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.
+
+Status of this Memo
+
+ 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). 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."
+
+ This Internet-Draft will expire on February 25, 2011.
+
+Copyright Notice
+
+ 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
+ (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 Simplified BSD License.
+
+
+
+Daboo Expires February 25, 2011 [Page 1]
+
+Internet-Draft CardDAV Directory Gateway Extension August 2010
+
+
+Table of Contents
+
+ 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3
+ 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 3
+ 3. CARDDAV:directory-gateway Property . . . . . . . . . . . . . . 4
+ 4. XML Element Definitions . . . . . . . . . . . . . . . . . . . 5
+ 4.1. CARDDAV:directory . . . . . . . . . . . . . . . . . . . . 5
+ 5. Client Guidelines . . . . . . . . . . . . . . . . . . . . . . 5
+ 6. Server Guidelines . . . . . . . . . . . . . . . . . . . . . . 6
+ 7. Security Considerations . . . . . . . . . . . . . . . . . . . 7
+ 8. IANA Consideration . . . . . . . . . . . . . . . . . . . . . . 8
+ 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 8
+ 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8
+ 10.1. Normative References . . . . . . . . . . . . . . . . . . . 8
+ 10.2. Informative References . . . . . . . . . . . . . . . . . . 9
+ Appendix A. Change History (to be removed prior to
+ publication as an RFC) . . . . . . . . . . . . . . . 9
+ Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 10
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo Expires February 25, 2011 [Page 2]
+
+Internet-Draft CardDAV Directory Gateway Extension August 2010
+
+
+1. Introduction and Overview
+
+ The CardDAV [I-D.ietf-vcarddav-carddav] protocol defines a standard
+ way of accessing, managing, and sharing contact information based on
+ the vCard [RFC2426] 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 Lightweight Directory
+ Access Protocol (LDAP) [RFC4510] 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.
+
+ 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.
+
+ 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.
+
+
+2. Conventions
+
+ 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].
+
+ The term "protected" is used in the Conformance field of property
+ definitions as defined in Section 15 of [RFC4918].
+
+ This document uses XML DTD fragments ([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:
+
+ 1. element names use the "DAV:" namespace,
+
+
+
+
+
+Daboo Expires February 25, 2011 [Page 3]
+
+Internet-Draft CardDAV Directory Gateway Extension August 2010
+
+
+ 2. element ordering is irrelevant unless explicitly stated,
+
+ 3. extension elements (elements not already defined as valid child
+ elements) may be added anywhere, except when explicitly stated
+ otherwise,
+
+ 4. extension attributes (attributes not already defined as valid for
+ this element) may be added anywhere, except when explicitly
+ stated otherwise.
+
+ 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.
+
+
+3. CARDDAV:directory-gateway Property
+
+ Name: directory-gateway
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Identifies URLs of CardDAV address book collections acting
+ as a directory gateway for the server.
+
+ Protected: MUST be protected.
+
+ allprop behavior: SHOULD NOT be returned by a PROPFIND DAV:allprop
+ request.
+
+ Description: The CARDDAV:directory-gateway identifies address book
+ collection resources that are directory gateway address books for
+ the server.
+
+ Definition:
+
+ <!ELEMENT directory-gateway (DAV:href*)>
+
+ Example:
+
+ <C:directory-gateway xmlns:D="DAV:"
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+ <D:href>/directory</D:href>
+ </C:directory-gateway>
+
+
+
+
+
+
+
+Daboo Expires February 25, 2011 [Page 4]
+
+Internet-Draft CardDAV Directory Gateway Extension August 2010
+
+
+4. XML Element Definitions
+
+4.1. CARDDAV:directory
+
+ Name: directory
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Used to indicate that an address book collection is a
+ directory gateway.
+
+ 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.
+
+ Definition:
+
+ <!ELEMENT directory EMPTY>
+
+ Example:
+
+ <D:resourcetype xmlns:D="DAV:"
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+ <D:collection/>
+ <C:addressbook/>
+ <C:directory/>
+ </D:resourcetype>
+
+
+5. Client Guidelines
+
+ Clients wishing to make use of directory gateway address books can
+ request the CARDDAV:directory-gateway property (Section 3) 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.
+
+ 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 CARDDAV:
+ directory element (Section 4.1).
+
+ 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 [I-D.ietf-vcarddav-carddav].
+
+
+
+Daboo Expires February 25, 2011 [Page 5]
+
+Internet-Draft CardDAV Directory Gateway Extension August 2010
+
+
+ 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.
+
+ 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.
+
+ 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
+ [I-D.ietf-vcarddav-carddav]) on the resource.
+
+
+6. Server Guidelines
+
+ 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.
+
+ 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 [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).
+
+ 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.
+
+
+
+Daboo Expires February 25, 2011 [Page 6]
+
+Internet-Draft CardDAV Directory Gateway Extension August 2010
+
+
+ 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.
+
+ 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.
+
+ 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.
+
+ 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.
+
+ 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 [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.
+
+
+7. Security Considerations
+
+ Servers MUST ensure that client requests against the directory
+
+
+
+Daboo Expires February 25, 2011 [Page 7]
+
+Internet-Draft CardDAV Directory Gateway Extension August 2010
+
+
+ gateway address book collection cannot use excessive resources (CPU,
+ memory, network bandwidth etc), given that the directory could be
+ large.
+
+ 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.
+
+ 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.
+
+
+8. IANA Consideration
+
+ This document does not require any actions on the part of IANA.
+
+
+9. Acknowledgments
+
+
+10. References
+
+10.1. Normative References
+
+ [I-D.ietf-vcarddav-carddav]
+ Daboo, C., "vCard Extensions to WebDAV (CardDAV)",
+ draft-ietf-vcarddav-carddav-10 (work in progress),
+ November 2009.
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [RFC2426] Dawson, F. and T. Howes, "vCard MIME Directory Profile",
+ RFC 2426, September 1998.
+
+ [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed
+ Authoring and Versioning (WebDAV)", RFC 4918, June 2007.
+
+ [W3C.REC-xml-20081126]
+ Paoli, J., Yergeau, F., Bray, T., Sperberg-McQueen, C.,
+ and E. Maler, "Extensible Markup Language (XML) 1.0 (Fifth
+
+
+
+Daboo Expires February 25, 2011 [Page 8]
+
+Internet-Draft CardDAV Directory Gateway Extension August 2010
+
+
+ Edition)", World Wide Web Consortium Recommendation REC-
+ xml-20081126, November 2008,
+ <http://www.w3.org/TR/2008/REC-xml-20081126>.
+
+10.2. Informative References
+
+ [RFC4510] Zeilenga, K., "Lightweight Directory Access Protocol
+ (LDAP): Technical Specification Road Map", RFC 4510,
+ June 2006.
+
+
+Appendix A. Change History (to be removed prior to publication as an
+ RFC)
+
+ Changes in -02
+
+ 1. Added CARDDAV:directory element for use in DAV:resourcetype
+
+ 2. Allow CARDDAV:directory-gateway to be multi-valued
+
+ 3. Explain how a server could implicit "scope" queries on different
+ directory gateway resources
+
+ Changes in -01
+
+ 1. Remove duplicated text in a couple of sections
+
+ 2. Add example of LDAP/generic database as possible directory
+ "sources"
+
+ 3. Add text to explain why the client needs to treat this as special
+ and thus the need for a property
+
+ 4. Added text to server guidelines indicating requirements for
+ handling vCard UID properties
+
+ 5. 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
+
+ 6. Added text to server guidelines indicating that server are free
+ to aggregate directory records from multiple sources
+
+ 7. 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
+
+
+
+
+
+Daboo Expires February 25, 2011 [Page 9]
+
+Internet-Draft CardDAV Directory Gateway Extension August 2010
+
+
+Author's Address
+
+ Cyrus Daboo
+ Apple Inc.
+ 1 Infinite Loop
+ Cupertino, CA 95014
+ USA
+
+ Email: cyrus@daboo.name
+ URI: http://www.apple.com/
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo Expires February 25, 2011 [Page 10]
+
generated by cgit v1.2.3 (git 2.25.1) at 2024-06-29 18:56:09 +0000