aboutsummaryrefslogblamecommitdiffstats
path: root/vendor/sabre/dav/docs/draft-daboo-carddav-directory-gateway-02.txt
blob: 63aa8b29c24ef9e85059d8ae2e5b977c4e0c3c3c (plain) (tree)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
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
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
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
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]