mirror of
https://git.friendi.ca/friendica/friendica-addons.git
synced 2024-08-16 22:00:54 +00:00
560 lines
18 KiB
Text
560 lines
18 KiB
Text
|
||
|
||
|
||
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]
|
||
|