[CalendarServer-changes] [5471] CalendarServer/trunk
source_changes at macosforge.org
source_changes at macosforge.org
Mon Apr 12 14:07:23 PDT 2010
Revision: 5471
http://trac.macosforge.org/projects/calendarserver/changeset/5471
Author: cdaboo at apple.com
Date: 2010-04-12 14:07:19 -0700 (Mon, 12 Apr 2010)
Log Message:
-----------
directory-gateway WebDAV property support.
Modified Paths:
--------------
CalendarServer/trunk/calendarserver/tap/util.py
CalendarServer/trunk/twistedcaldav/carddavxml.py
CalendarServer/trunk/twistedcaldav/resource.py
CalendarServer/trunk/twistedcaldav/stdconfig.py
Added Paths:
-----------
CalendarServer/trunk/doc/RFC/draft-daboo-carddav-directory-gateway.txt
Modified: CalendarServer/trunk/calendarserver/tap/util.py
===================================================================
--- CalendarServer/trunk/calendarserver/tap/util.py 2010-04-12 20:48:56 UTC (rev 5470)
+++ CalendarServer/trunk/calendarserver/tap/util.py 2010-04-12 21:07:19 UTC (rev 5471)
@@ -282,7 +282,7 @@
directory, "/addressbooks/"
)
- directoryPath = os.path.join(config.DocumentRoot, "directory")
+ directoryPath = os.path.join(config.DocumentRoot, config.DirectoryAddressBook.name)
if config.DirectoryAddressBook.Enabled:
log.info("Setting up directory address book: %r" % (directoryBackedAddressBookResourceClass,))
@@ -321,7 +321,7 @@
if config.EnableCardDAV:
root.putChild('addressbooks', addressBookCollection)
if config.DirectoryAddressBook.Enabled:
- root.putChild('directory', directoryBackedAddressBookCollection)
+ root.putChild(config.DirectoryAddressBook.name, directoryBackedAddressBookCollection)
# /.well-known
if config.EnableWellKnown:
Added: CalendarServer/trunk/doc/RFC/draft-daboo-carddav-directory-gateway.txt
===================================================================
--- CalendarServer/trunk/doc/RFC/draft-daboo-carddav-directory-gateway.txt (rev 0)
+++ CalendarServer/trunk/doc/RFC/draft-daboo-carddav-directory-gateway.txt 2010-04-12 21:07:19 UTC (rev 5471)
@@ -0,0 +1,448 @@
+
+
+
+Network Working Group C. Daboo
+Internet-Draft Apple Inc.
+Intended status: Standards Track March 8, 2010
+Expires: September 9, 2010
+
+
+ CardDAV Directory Gateway Extension
+ draft-daboo-carddav-directory-gateway-01
+
+Abstract
+
+ This document defines and 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 to IETF in full conformance with the
+ provisions of BCP 78 and BCP 79.
+
+ Internet-Drafts are working documents of the Internet Engineering
+ Task Force (IETF), its areas, and its working groups. Note that
+ other groups may also distribute working documents as Internet-
+ Drafts.
+
+ 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."
+
+ The list of current Internet-Drafts can be accessed at
+ http://www.ietf.org/ietf/1id-abstracts.txt.
+
+ The list of Internet-Draft Shadow Directories can be accessed at
+ http://www.ietf.org/shadow.html.
+
+ This Internet-Draft will expire on September 9, 2010.
+
+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
+
+
+
+Daboo Expires September 9, 2010 [Page 1]
+
+Internet-Draft CardDAV Directory Gateway Extension March 2010
+
+
+ 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 BSD License.
+
+
+Table of Contents
+
+ 1. Introduction and Overview . . . . . . . . . . . . . . . . . . . 3
+ 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . 3
+ 3. CARDDAV:directory-gateway Property . . . . . . . . . . . . . . 4
+ 4. Client Guidelines . . . . . . . . . . . . . . . . . . . . . . . 4
+ 5. Server Guidelines . . . . . . . . . . . . . . . . . . . . . . . 5
+ 6. Security Considerations . . . . . . . . . . . . . . . . . . . . 6
+ 7. IANA Consideration . . . . . . . . . . . . . . . . . . . . . . 6
+ 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . 6
+ 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7
+ 9.1. Normative References . . . . . . . . . . . . . . . . . . . 7
+ 9.2. Informative References . . . . . . . . . . . . . . . . . . 7
+ Appendix A. Change History (to be removed prior to
+ publication as an RFC) . . . . . . . . . . . . . . . . 7
+ Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 8
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo Expires September 9, 2010 [Page 2]
+
+Internet-Draft CardDAV Directory Gateway Extension March 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 just 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 the directory gateway address book
+ collection resource. 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.
+
+ 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,
+
+ 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
+
+
+
+Daboo Expires September 9, 2010 [Page 3]
+
+Internet-Draft CardDAV Directory Gateway Extension March 2010
+
+
+ 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 the URL of a CardDAV address book collection
+ acting as the 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 an address
+ book collection resource that is the directory gateway address
+ book 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>
+
+
+4. Client Guidelines
+
+ Clients wishing to make use of the directory gateway address book can
+ request the CARDDAV:directory-gateway property 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
+
+
+
+Daboo Expires September 9, 2010 [Page 4]
+
+Internet-Draft CardDAV Directory Gateway Extension March 2010
+
+
+ by the server at that time.
+
+ Since the directory being exposed via the directory gateway address
+ book collection could be large, clients SHOULD use the feature to
+ 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].
+
+ 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. Instead, CARDDAV:addressbook-query REPORTs are used to
+ search for specific address book object resources.
+
+
+5. 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 use the feature to
+ 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.
+
+ Multiple directory sources could be available to the server. If the
+ server wished to expose data from all of these, it MUST use the
+ single directory gateway resource to do so, aggregating results from
+ each directory source. When doing so care is needed when dealing
+
+
+
+Daboo Expires September 9, 2010 [Page 5]
+
+Internet-Draft CardDAV Directory Gateway Extension March 2010
+
+
+ with potential records that refer to the same entity. Servers MAY
+ suppress any duplicates that they are able to determine themselves.
+
+ 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.
+
+ 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.
+
+
+6. Security Considerations
+
+ 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.
+
+ 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.
+
+
+7. IANA Consideration
+
+ This document does not require any actions on the part of IANA.
+
+
+8. Acknowledgments
+
+
+9. References
+
+
+
+
+Daboo Expires September 9, 2010 [Page 6]
+
+Internet-Draft CardDAV Directory Gateway Extension March 2010
+
+
+9.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
+ Edition)", World Wide Web Consortium Recommendation REC-
+ xml-20081126, November 2008,
+ <http://www.w3.org/TR/2008/REC-xml-20081126>.
+
+9.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 -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
+
+
+
+Daboo Expires September 9, 2010 [Page 7]
+
+Internet-Draft CardDAV Directory Gateway Extension March 2010
+
+
+ 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
+
+
+Author's Address
+
+ Cyrus Daboo
+ Apple Inc.
+ 1 Infinite Loop
+ Cupertino, CA 95014
+ USA
+
+ Email: cyrus at daboo.name
+ URI: http://www.apple.com/
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo Expires September 9, 2010 [Page 8]
+
Modified: CalendarServer/trunk/twistedcaldav/carddavxml.py
===================================================================
--- CalendarServer/trunk/twistedcaldav/carddavxml.py 2010-04-12 20:48:56 UTC (rev 5470)
+++ CalendarServer/trunk/twistedcaldav/carddavxml.py 2010-04-12 21:07:19 UTC (rev 5471)
@@ -734,6 +734,16 @@
(carddav_namespace, "param-filter"): (0, None)
}
+class DirectoryGateway(CardDAVElement):
+ """
+ CardDAV property on a principal to indicate where the directory geatway resource is.
+ """
+ name = "directory-gateway"
+ hidden = True
+ protected = True
+
+ allowed_children = { (davxml.dav_namespace, "href"): (1, 1) }
+
##
# Extensions to davxml.ResourceType
##
Modified: CalendarServer/trunk/twistedcaldav/resource.py
===================================================================
--- CalendarServer/trunk/twistedcaldav/resource.py 2010-04-12 20:48:56 UTC (rev 5470)
+++ CalendarServer/trunk/twistedcaldav/resource.py 2010-04-12 21:07:19 UTC (rev 5471)
@@ -1084,6 +1084,8 @@
if config.EnableCardDAV:
baseProperties += (carddavxml.AddressBookHomeSet.qname(),)
+ if config.DirectoryAddressBook.Enabled:
+ baseProperties += (carddavxml.DirectoryGateway.qname(),)
if config.EnableDropBox:
baseProperties += (customxml.DropBoxHomeURL.qname(),)
@@ -1169,6 +1171,10 @@
returnValue(carddavxml.AddressBookHomeSet(
*[davxml.HRef(url) for url in self.addressBookHomeURLs()]
))
+ elif name == "directory-gateway":
+ returnValue(carddavxml.DirectoryGateway(
+ davxml.HRef.fromString(joinURL("/", config.DirectoryAddressBook.name, "/"))
+ ))
result = (yield super(CalendarPrincipalResource, self).readProperty(property, request))
returnValue(result)
Modified: CalendarServer/trunk/twistedcaldav/stdconfig.py
===================================================================
--- CalendarServer/trunk/twistedcaldav/stdconfig.py 2010-04-12 20:48:56 UTC (rev 5470)
+++ CalendarServer/trunk/twistedcaldav/stdconfig.py 2010-04-12 21:07:19 UTC (rev 5471)
@@ -152,19 +152,6 @@
"EnableCalDAV" : True, # Enable CalDAV service
"EnableCardDAV" : True, # Enable CardDAV service
- # CardDAV Features
- "DirectoryAddressBook": {
- "Enabled": True,
- "type": "twistedcaldav.directory.opendirectorybacker.OpenDirectoryBackingService",
- "params": directoryAddressBookBackingServiceDefaultParams["twistedcaldav.directory.opendirectorybacker.OpenDirectoryBackingService"],
- },
- "AnonymousDirectoryAddressBookAccess": False, # Anonymous users may access directory address book
-
- "MaxAddressBookQueryResults":1000,
- "MaxAddressBookMultigetHrefs":5000,
-
- # /XXX CardDAV
-
#
# Data store
#
@@ -353,6 +340,20 @@
}
},
+ # CardDAV Features
+ "DirectoryAddressBook": {
+ "Enabled": True,
+ "type": "twistedcaldav.directory.opendirectorybacker.OpenDirectoryBackingService",
+ "params": directoryAddressBookBackingServiceDefaultParams["twistedcaldav.directory.opendirectorybacker.OpenDirectoryBackingService"],
+ "name": "directory"
+ },
+ "AnonymousDirectoryAddressBookAccess": False, # Anonymous users may access directory address book
+
+ "MaxAddressBookQueryResults":1000,
+ "MaxAddressBookMultigetHrefs":5000,
+
+ # /XXX CardDAV
+
#
# Web-based administration
#
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.macosforge.org/pipermail/calendarserver-changes/attachments/20100412/c2088d06/attachment-0001.html>
More information about the calendarserver-changes
mailing list