mirror of
https://git.friendi.ca/friendica/friendica-addons.git
synced 2024-08-19 03:30:58 +00:00
561 lines
18 KiB
Text
561 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]
|
|||
|
|