dav/SabreDAV/docs/draft-daboo-carddav-directory-gateway-02.txt

   1
   2
   3
   4 Network Working Group                                           C. Daboo
   5 Internet-Draft                                                Apple Inc.
   6 Updates: XXXX-CardDAV                                    August 24, 2010
   7 (if approved)
   8 Intended status: Standards Track
   9 Expires: February 25, 2011
  10
  11
  12                   CardDAV Directory Gateway Extension
  13                 draft-daboo-carddav-directory-gateway-02
  14
  15 Abstract
  16
  17    This document defines an extension to the vCard Extensions to WebDAV
  18    (CardDAV) protocol that allows a server to expose a directory as a
  19    read-only address book collection.
  20
  21 Status of this Memo
  22
  23    This Internet-Draft is submitted in full conformance with the
  24    provisions of BCP 78 and BCP 79.
  25
  26    Internet-Drafts are working documents of the Internet Engineering
  27    Task Force (IETF).  Note that other groups may also distribute
  28    working documents as Internet-Drafts.  The list of current Internet-
  29    Drafts is at http://datatracker.ietf.org/drafts/current/.
  30
  31    Internet-Drafts are draft documents valid for a maximum of six months
  32    and may be updated, replaced, or obsoleted by other documents at any
  33    time.  It is inappropriate to use Internet-Drafts as reference
  34    material or to cite them other than as "work in progress."
  35
  36    This Internet-Draft will expire on February 25, 2011.
  37
  38 Copyright Notice
  39
  40    Copyright (c) 2010 IETF Trust and the persons identified as the
  41    document authors.  All rights reserved.
  42
  43    This document is subject to BCP 78 and the IETF Trust's Legal
  44    Provisions Relating to IETF Documents
  45    (http://trustee.ietf.org/license-info) in effect on the date of
  46    publication of this document.  Please review these documents
  47    carefully, as they describe your rights and restrictions with respect
  48    to this document.  Code Components extracted from this document must
  49    include Simplified BSD License text as described in Section 4.e of
  50    the Trust Legal Provisions and are provided without warranty as
  51    described in the Simplified BSD License.
  52
  53
  54
  55 Daboo                   Expires February 25, 2011               [Page 1]
  56 \f
  57 Internet-Draft     CardDAV Directory Gateway Extension       August 2010
  58
  59
  60 Table of Contents
  61
  62    1.  Introduction and Overview  . . . . . . . . . . . . . . . . . .  3
  63    2.  Conventions  . . . . . . . . . . . . . . . . . . . . . . . . .  3
  64    3.  CARDDAV:directory-gateway Property . . . . . . . . . . . . . .  4
  65    4.  XML Element Definitions  . . . . . . . . . . . . . . . . . . .  5
  66      4.1.  CARDDAV:directory  . . . . . . . . . . . . . . . . . . . .  5
  67    5.  Client Guidelines  . . . . . . . . . . . . . . . . . . . . . .  5
  68    6.  Server Guidelines  . . . . . . . . . . . . . . . . . . . . . .  6
  69    7.  Security Considerations  . . . . . . . . . . . . . . . . . . .  7
  70    8.  IANA Consideration . . . . . . . . . . . . . . . . . . . . . .  8
  71    9.  Acknowledgments  . . . . . . . . . . . . . . . . . . . . . . .  8
  72    10. References . . . . . . . . . . . . . . . . . . . . . . . . . .  8
  73      10.1. Normative References . . . . . . . . . . . . . . . . . . .  8
  74      10.2. Informative References . . . . . . . . . . . . . . . . . .  9
  75    Appendix A.  Change History (to be removed prior to
  76                 publication as an RFC)  . . . . . . . . . . . . . . .  9
  77    Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 10
  78
  79
  80
  81
  82
  83
  84
  85
  86
  87
  88
  89
  90
  91
  92
  93
  94
  95
  96
  97
  98
  99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111 Daboo                   Expires February 25, 2011               [Page 2]
 112 \f
 113 Internet-Draft     CardDAV Directory Gateway Extension       August 2010
 114
 115
 116 1.  Introduction and Overview
 117
 118    The CardDAV [I-D.ietf-vcarddav-carddav] protocol defines a standard
 119    way of accessing, managing, and sharing contact information based on
 120    the vCard [RFC2426] format.  Often, in an enterprise or service
 121    provider environment, a directory of all users hosted on the server
 122    (or elsewhere) is available (for example via Lightweight Directory
 123    Access Protocol (LDAP) [RFC4510] or some direct database access).  It
 124    would be convenient for CardDAV clients if this directory were
 125    exposed as a "global" address book on the CardDAV server so it could
 126    be searched in the same way as personal address books are.  This
 127    specification defines a "directory gateway" feature extension to
 128    CardDAV to enable this.
 129
 130    This specification adds one new WebDAV property to principal
 131    resources that contains the URL to one or more directory gateway
 132    address book collection resources.  It is important for clients to be
 133    able to distinguish this address book collection from others because
 134    there are specific limitations involved in using it as described
 135    below.  To aid that, this specification defines an XML element that
 136    can be included as a child element of the DAV:resourcetype property
 137    of address book collections to identify them as directory gateways.
 138
 139    Note that this feature is in no way intended to replace full
 140    directory access - it is meant to simply provide a convenient way for
 141    CardDAV clients to query contact-related attributes in directory
 142    records.
 143
 144
 145 2.  Conventions
 146
 147    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
 148    "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
 149    document are to be interpreted as described in [RFC2119].
 150
 151    The term "protected" is used in the Conformance field of property
 152    definitions as defined in Section 15 of [RFC4918].
 153
 154    This document uses XML DTD fragments ([W3C.REC-xml-20081126], Section
 155    3.2) as a purely notational convention.  WebDAV request and response
 156    bodies cannot be validated by a DTD due to the specific extensibility
 157    rules defined in Section 17 of [RFC4918] and due to the fact that all
 158    XML elements defined by this specification use the XML namespace name
 159    "DAV:".  In particular:
 160
 161    1.  element names use the "DAV:" namespace,
 162
 163
 164
 165
 166
 167 Daboo                   Expires February 25, 2011               [Page 3]
 168 \f
 169 Internet-Draft     CardDAV Directory Gateway Extension       August 2010
 170
 171
 172    2.  element ordering is irrelevant unless explicitly stated,
 173
 174    3.  extension elements (elements not already defined as valid child
 175        elements) may be added anywhere, except when explicitly stated
 176        otherwise,
 177
 178    4.  extension attributes (attributes not already defined as valid for
 179        this element) may be added anywhere, except when explicitly
 180        stated otherwise.
 181
 182    When XML element types in the namespaces "DAV:" and
 183    "urn:ietf:params:xml:ns:carddav" are referenced in this document
 184    outside of the context of an XML fragment, the strings "DAV:" and
 185    "CARDDAV:" will be prefixed to the element types, respectively.
 186
 187
 188 3.  CARDDAV:directory-gateway Property
 189
 190    Name:  directory-gateway
 191
 192    Namespace:  urn:ietf:params:xml:ns:carddav
 193
 194    Purpose:  Identifies URLs of CardDAV address book collections acting
 195       as a directory gateway for the server.
 196
 197    Protected:  MUST be protected.
 198
 199    allprop behavior:  SHOULD NOT be returned by a PROPFIND DAV:allprop
 200       request.
 201
 202    Description:  The CARDDAV:directory-gateway identifies address book
 203       collection resources that are directory gateway address books for
 204       the server.
 205
 206    Definition:
 207
 208        <!ELEMENT directory-gateway (DAV:href*)>
 209
 210    Example:
 211
 212        <C:directory-gateway xmlns:D="DAV:"
 213           xmlns:C="urn:ietf:params:xml:ns:carddav">
 214          <D:href>/directory</D:href>
 215        </C:directory-gateway>
 216
 217
 218
 219
 220
 221
 222
 223 Daboo                   Expires February 25, 2011               [Page 4]
 224 \f
 225 Internet-Draft     CardDAV Directory Gateway Extension       August 2010
 226
 227
 228 4.  XML Element Definitions
 229
 230 4.1.  CARDDAV:directory
 231
 232    Name:  directory
 233
 234    Namespace:  urn:ietf:params:xml:ns:carddav
 235
 236    Purpose:  Used to indicate that an address book collection is a
 237       directory gateway.
 238
 239    Description:  This element appears in the DAV:resourcetype property
 240       on a address book collection resources that are directory
 241       gateways.  Clients can use the presence of this element to
 242       identify directory gateway collections when doing PROPFINDs to
 243       list collection contents.
 244
 245    Definition:
 246
 247    <!ELEMENT directory EMPTY>
 248
 249    Example:
 250
 251        <D:resourcetype xmlns:D="DAV:"
 252           xmlns:C="urn:ietf:params:xml:ns:carddav">
 253          <D:collection/>
 254          <C:addressbook/>
 255          <C:directory/>
 256        </D:resourcetype>
 257
 258
 259 5.  Client Guidelines
 260
 261    Clients wishing to make use of directory gateway address books can
 262    request the CARDDAV:directory-gateway property (Section 3) when
 263    examining other properties on the principal resource for the user.
 264    If the property is not present, then the directory gateway feature is
 265    not supported by the server at that time.
 266
 267    Clients can also detect the presence of directory gateway address
 268    book collections by retrieving the DAV:resourcetype property on
 269    collections that it lists, and look for the presence of the CARDDAV:
 270    directory element (Section 4.1).
 271
 272    Since the directory being exposed via a directory gateway address
 273    book collection could be large, clients SHOULD limit the number of
 274    results returned in an CARDDAV:addressbook-query REPORT as defined in
 275    Section 8.6.1 of [I-D.ietf-vcarddav-carddav].
 276
 277
 278
 279 Daboo                   Expires February 25, 2011               [Page 5]
 280 \f
 281 Internet-Draft     CardDAV Directory Gateway Extension       August 2010
 282
 283
 284    Clients MUST treat the directory gateway address book collection as a
 285    read-only collection, so HTTP methods that modify resource data or
 286    properties in the address book collection MUST NOT be used.
 287
 288    Clients SHOULD NOT attempt to cache the entire contents of the
 289    directory gateway address book collection resource by retrieving all
 290    resources, or trying to examine all the properties of all resources
 291    (e.g., via a PROPFIND Depth:1 request).  Instead, CARDDAV:
 292    addressbook-query REPORTs are used to search for specific address
 293    book object resources, and CARDDAV:multiget REPORTs and individual
 294    GET requests can be made to retrieve the actual vCard data for
 295    address book object resources found via a query.
 296
 297    When presenting directory gateway collections to the user, clients
 298    SHOULD use the DAV:displayname property on the corresponding address
 299    book collections as the name of the directory gateway.  This is
 300    important in the case where more than one directory gateway is
 301    available.  Clients MAY also provide descriptive information about
 302    each directory gateway by examining the CARDDAV:addressbook-
 303    description property (see Section 6.2.1 of
 304    [I-D.ietf-vcarddav-carddav]) on the resource.
 305
 306
 307 6.  Server Guidelines
 308
 309    Servers wishing to expose a directory gateway as an address book
 310    collection MUST include the CARDDAV:directory-gateway property on all
 311    principal resources of users expected to use the feature.
 312
 313    Since the directory being exposed via the directory gateway address
 314    book collection could be large, servers SHOULD truncate the number of
 315    results returned in an CARDDAV:addressbook-query REPORT as defined in
 316    Section 8.6.2 of [I-D.ietf-vcarddav-carddav].  In addition, servers
 317    SHOULD disallow requests that effectively enumerate the collection
 318    contents (e.g., PROPFIND Depth:1, trivial CARDDAV:addressbook-query,
 319    DAV:sync-collection REPORT).
 320
 321    Servers need to expose the directory information as a set of address
 322    book object resources in the directory gateway address book
 323    collection resource.  To do that, a mapping between the directory
 324    record format and the vCard data has to be applied.  In general, only
 325    directory record attributes that have a direct equivalent in vCard
 326    SHOULD be mapped.  It is up to individual implementations to
 327    determine which attributes to map.  But in all cases servers MUST
 328    generate valid vCard data as returned to the client.  In addition, as
 329    required by CardDAV, the UID vCard property MUST be present in the
 330    vCard data, and this value MUST be persistent from query to query for
 331    the same directory record.
 332
 333
 334
 335 Daboo                   Expires February 25, 2011               [Page 6]
 336 \f
 337 Internet-Draft     CardDAV Directory Gateway Extension       August 2010
 338
 339
 340    Multiple directory sources could be available to the server.  The
 341    server MAY use a single directory gateway resource to aggregate
 342    results from each directory source.  When doing so care is needed
 343    when dealing with potential records that refer to the same entity.
 344    Servers MAY suppress any duplicates that they are able to determine
 345    themselves.  Alternatively, multiple directory sources can be exposed
 346    as separate directory gateway resources.
 347
 348    For any directory source, a server MAY expose multiple directory
 349    gateway resources where each represents a different query "scope" for
 350    the directory.  Different scopes MAY be offered to different
 351    principals on the server.  For example, the server might expose an
 352    entire company directory for searching as the resource "/directory-
 353    all" to all principals, but then provide "/directory-department-XYZ"
 354    as another directory gateway that has a search scope that implicitly
 355    limits the search results to just the "XYZ" department.  Users in
 356    that department would then have a CARDDAV:directory-gateway property
 357    on their principal resource that included the "/directory-department-
 358    XYZ" resource.  Users in other departments would have corresponding
 359    directory gateway resources available to them.
 360
 361    Records in a directory can include data for more than just people,
 362    e.g, resources such as rooms or projectors, groups, computer systems
 363    etc.  It is up to individual implementations to determine the most
 364    appropriate "scope" for the data returned via the directory gateway
 365    by filtering the appropriate record types.  As above, servers could
 366    choose to expose people and resources under different directory
 367    gateway resources by implicitly limiting the search "scope" for each
 368    of those.
 369
 370    Servers MAY apply implementation defined access rules to determine,
 371    on a per-user basis, what records are returned to a particularly user
 372    and the content of those records exposed via vCard data.  This per-
 373    user behavior is in addition to the general security requirements
 374    detailed below.
 375
 376    When multiple directory gateway collections are present, servers
 377    SHOULD provide a DAV:displayname property on each that disambiguates
 378    them.  Servers MAY include a CARDDAV:addressbook-description property
 379    (see Section 6.2.1 of [I-D.ietf-vcarddav-carddav]) on each directory
 380    gateway resource to provide a description of the directory and any
 381    search "scope" that might be used, or any other useful information
 382    for users.
 383
 384
 385 7.  Security Considerations
 386
 387    Servers MUST ensure that client requests against the directory
 388
 389
 390
 391 Daboo                   Expires February 25, 2011               [Page 7]
 392 \f
 393 Internet-Draft     CardDAV Directory Gateway Extension       August 2010
 394
 395
 396    gateway address book collection cannot use excessive resources (CPU,
 397    memory, network bandwidth etc), given that the directory could be
 398    large.
 399
 400    Servers MUST take care not to expose sensitive directory record
 401    attributes in the vCard data via the directory gateway address book.
 402    In general only those properties that have direct correspondence in
 403    vCard SHOULD be exposed.
 404
 405    Servers need to determine whether it is appropriate for the directory
 406    information to be available via CardDAV to unauthenticated users.  If
 407    not, servers MUST ensure that unauthenticated users do not have
 408    access to the directory gateway address book object resource and its
 409    contents.  If unauthenticated access is allowed, servers MAY choose
 410    to limit the set of vCard properties that are searchable or returned
 411    in the address book object resources when unauthenticated requests
 412    are made.
 413
 414
 415 8.  IANA Consideration
 416
 417    This document does not require any actions on the part of IANA.
 418
 419
 420 9.  Acknowledgments
 421
 422
 423 10.  References
 424
 425 10.1.  Normative References
 426
 427    [I-D.ietf-vcarddav-carddav]
 428               Daboo, C., "vCard Extensions to WebDAV (CardDAV)",
 429               draft-ietf-vcarddav-carddav-10 (work in progress),
 430               November 2009.
 431
 432    [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
 433               Requirement Levels", BCP 14, RFC 2119, March 1997.
 434
 435    [RFC2426]  Dawson, F. and T. Howes, "vCard MIME Directory Profile",
 436               RFC 2426, September 1998.
 437
 438    [RFC4918]  Dusseault, L., "HTTP Extensions for Web Distributed
 439               Authoring and Versioning (WebDAV)", RFC 4918, June 2007.
 440
 441    [W3C.REC-xml-20081126]
 442               Paoli, J., Yergeau, F., Bray, T., Sperberg-McQueen, C.,
 443               and E. Maler, "Extensible Markup Language (XML) 1.0 (Fifth
 444
 445
 446
 447 Daboo                   Expires February 25, 2011               [Page 8]
 448 \f
 449 Internet-Draft     CardDAV Directory Gateway Extension       August 2010
 450
 451
 452               Edition)", World Wide Web Consortium Recommendation REC-
 453               xml-20081126, November 2008,
 454               <http://www.w3.org/TR/2008/REC-xml-20081126>.
 455
 456 10.2.  Informative References
 457
 458    [RFC4510]  Zeilenga, K., "Lightweight Directory Access Protocol
 459               (LDAP): Technical Specification Road Map", RFC 4510,
 460               June 2006.
 461
 462
 463 Appendix A.  Change History (to be removed prior to publication as an
 464              RFC)
 465
 466    Changes in -02
 467
 468    1.  Added CARDDAV:directory element for use in DAV:resourcetype
 469
 470    2.  Allow CARDDAV:directory-gateway to be multi-valued
 471
 472    3.  Explain how a server could implicit "scope" queries on different
 473        directory gateway resources
 474
 475    Changes in -01
 476
 477    1.  Remove duplicated text in a couple of sections
 478
 479    2.  Add example of LDAP/generic database as possible directory
 480        "sources"
 481
 482    3.  Add text to explain why the client needs to treat this as special
 483        and thus the need for a property
 484
 485    4.  Added text to server guidelines indicating requirements for
 486        handling vCard UID properties
 487
 488    5.  Added text to server guidelines explain that different record
 489        "types" may exist in the directory and the server is free to
 490        filter those as appropriate
 491
 492    6.  Added text to server guidelines indicating that server are free
 493        to aggregate directory records from multiple sources
 494
 495    7.  Added text to server guidelines indicating that servers are free
 496        to apply implementation defined access control to the returned
 497        data on a per-user basis
 498
 499
 500
 501
 502
 503 Daboo                   Expires February 25, 2011               [Page 9]
 504 \f
 505 Internet-Draft     CardDAV Directory Gateway Extension       August 2010
 506
 507
 508 Author's Address
 509
 510    Cyrus Daboo
 511    Apple Inc.
 512    1 Infinite Loop
 513    Cupertino, CA  95014
 514    USA
 515
 516    Email: cyrus@daboo.name
 517    URI:   http://www.apple.com/
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559 Daboo                   Expires February 25, 2011              [Page 10]
 560 \f