git.sur5r.net Git - openldap/blob - doc/drafts/draft-ietf-ldapext-refer-xx.txt

   1 IETF LDAPEXT Working Group                                Roland Hedberg
   2 Internet-Draft                                                 Catalogix
   3 Expires: January 12, 2000                                  July 12, 2000
   4
   5
   6
   7
   8
   9                     Referrals in LDAP Directories
  10                   <draft-ietf-ldapext-refer-00.txt>
  11
  12
  13
  14
  15 Status of this Memo
  16
  17    This document is an Internet-Draft and is in full conformance with
  18    all provisions of Section 10 of RFC2026.
  19
  20    Internet-Drafts are working documents of the Internet Engineering
  21    Task Force (IETF), its areas, and its working groups. Note that
  22    other groups may also distribute working documents as
  23    Internet-Drafts.
  24
  25    Internet-Drafts are draft documents valid for a maximum of six
  26    months and may be updated, replaced, or obsoleted by other documents
  27    at any time. It is inappropriate to use Internet-Drafts as reference
  28    material or to cite them other than as "work in progress."
  29
  30
  31      The list of current Internet-Drafts can be accessed at
  32      http://www.ietf.org/ietf/1id-abstracts.txt
  33
  34      The list of Internet-Draft Shadow Directories can be accessed at
  35      http://www.ietf.org/shadow.html.
  36
  37
  38    This Internet-Draft will expire on January 12, 2000.
  39
  40 Copyright Notice
  41
  42    Copyright (C) The Internet Society (2000). All Rights Reserved.
  43
  44
  45
  46
  47
  48
  49
  50
  51
  52
  53
  54
  55 Hedberg           Expires September 30, 2000                   [Page 1]
  56
  57 Internet-Draft    LDAP Knowledge references                   July 2000
  58
  59 Abstract
  60
  61    This document defines two reference attributes and associated "referral"
  62    object class for representing generic knowledge information in LDAP
  63    directories [RFC2251].
  64    The attribute uses URIs [RFC1738] to represent knowledge,
  65    enabling LDAP and non-LDAP services alike to be referenced.
  66    The object class can be used to construct entries in an LDAP directory
  67    containing references to other directories or services. This document
  68    also defines procedures directory servers should follow when supporting
  69    these schema elements and when responding to requests for which the
  70    directory server does not contain the requested object but may contain
  71    some knowledge of the location of the requested object.
  72
  73
  74 1.  Background and intended usage
  75
  76    The broadening of interest in LDAP directories beyond their use as front
  77    ends to X.500 directories has created a need to represent knowledge
  78    information in a more general way. Knowledge information is information
  79    about one or more servers maintained in another server, used to link
  80    servers and services together.
  81
  82    This document is based on the following basic assumptions:
  83
  84    - several naming domains
  85    The usage of LDAP as a access protocol to other than X.500 servers has
  86    created islands of directory service systems containing one or more
  87    LDAP servers. Each of these islands are free to pick their own naming
  88    domain. And that they also do; some use the old country,organization,
  89    organizationalUnit naming scheme[X.521], some use the newer domain name
  90    based naming scheme but these two are in no way the only ones in use. The
  91    existence of several naming domains are in itself no real problem as
  92    long as they produce unique names for the objects in the directory.
  93    Still naming schemes like the domain name based one, might easily create
  94    non-continues naming structures because some toplevel domain names
  95    might no find organizations that are interested and/or willing
  96    to manage them. Therefor tree transversal might not longer be possible
  97    except in parts of the whole tree.
  98
  99    - authoritive structure vs directory structure
 100    In some instances even if a part of the tree is delegated to one
 101    organization, the organization doing the delegation might want to
 102    remain as the authority for the baseobject of the delegated tree.
 103
 104    - support for onelevel searches
 105    At points in the tree where the responsibility for all or almost all
 106    of the children of a object is delegated to different organizations
 107    and resides in different directory servers a one-level search is not
 108    very efficient if not supported by special facilities in the directory
 109    as such.
 110
 111 Hedberg           Expires September 30, 2000                    [Page 2]
 112
 113 Internet-Draft    LDAP Knowledge references                   July 2000
 114
 115    -- directory server discovery
 116    LDAP servers that do not use dc nameing or are not registered with
 117    SRV records in the DNS are very hard to find.
 118
 119    This document defines a general method of representing knowledge
 120    information in LDAP directories, based on URIs.
 121    Two types of knowledge reference are defined: refer and subRefer.
 122
 123    The key words "MUST", "SHOULD", and "MAY" used in this document are to
 124    be interpreted as described in [RFC2119].
 125
 126 2. Knowledge references
 127
 128 2.1 The refer attribute
 129
 130    ( 1.2.752.17.1.100
 131      NAME 'refer'
 132      DESC 'URL reference'
 133      EQUALITY caseExactIA5Match
 134      SYNTAX 1.3.6.1.4.1.1466.115.121.1.26
 135      USAGE distributedOperation )
 136
 137    The refer attribute type has IA5 syntax and is case sensitive.
 138    It is multivalued. Values placed in the attribute MUST conform to the
 139    specification given for the labeledURI attribute as defined in [RFC2079].
 140
 141    The labeledURI specification defines a format that is a URI,
 142    optionally followed by whitespace and a label. This document does not
 143    make use of the label portion of the syntax. Future documents MAY enable
 144    new functionality by imposing additional structure on the label portion
 145    of the syntax as it appears in a refer attribute.
 146    If the URI contained in a refer attribute refers to an LDAP
 147    server, it must be in the LDAP URI format described in [RFC2255].
 148
 149    When returning a referral result, the server must not return the label
 150    portion of the labeledURI as part of the referral. Only the URI portion
 151    of the refer attributes should be returned.
 152
 153    The refer attribute can be further specified by the use of options as
 154    defined in section 4.1.5 of [RFC2251]. This document defines five
 155    options and their use. Future documents might defined other options.
 156
 157    The options defined are:
 158   "me", "sup", "cross", "nssr" and "sub" .
 159
 160    'refer;me' is used to hold the reference of this server, and is always
 161    held in the root DSE
 162
 163    'refer;sup' is used to hold the reference of a server superior to this
 164    one in this global LDAP naming domain e.g. a server holding the dc=com,
 165    dc=se, or the c=se node. The 'refer;sup' is always held in the root DSE.
 166
 167 Hedberg           Expires September 30, 2000                    [Page 3]
 168
 169 Internet-Draft    LDAP Knowledge references                   July 2000
 170
 171    'refer;cross' indicates that this is a cross reference pointing to another
 172    naming context within or outside this global LDAP naming domain.
 173
 174    'refer;sub' indicates that this is a subordinate reference pointing to
 175    a subordinate naming context in this global LDAP naming domain.
 176
 177    'refer;nssr' indicates that this is a non-specific subordinate reference
 178    pointing to a subordinate naming context in this global LDAP naming domain.
 179
 180
 181 3. Use of the knowledge attribute
 182
 183    Except when the manageDsaIT control (documented in section 6 of this
 184    document) is present in the operation request, the refer attribute is not
 185    visible to clients, except as its value is returned in referrals or con-
 186    tinuation references.
 187
 188    If the manageDsaIT control is not set, and the entry named in a request
 189    contains the refer attribute, and the entry is not the root DSE, the
 190    server returns an LDAPResult with the resultCode field set to "referral"
 191    and the referral field set to contain the value(s) of the refer attribute
 192    minus any optional trailing whitespace and labels that might be present.
 193
 194    If the manageDsaIT control is not set, and an entry containing the ref
 195    attribute is in the scope of a one level or subtree search request, the
 196    server returns a SearchResultReference for each such entry containing
 197    the value(s) of the entry's refer attribute.
 198
 199    When the manageDsaIT control is present in a request, the server will
 200    treat an entry containing the refer attribute as an ordinary entry, and
 201    the refer attribute as an ordinary attribute, and the server will not
 202    return referrals or continuation references corresponding to refer
 203    attributes.
 204
 205
 206 4 Behaviour specification
 207
 208 4.1 Name resolution for any operation
 209
 210    Clients SHOULD perform at least simple "depth-of-referral count" loop
 211    detection by incrementing a counter each time a new set of referrals is
 212    received. (The maximum value for this count SHOULD be twice the number
 213    of RDNs in the target object less one, to allow for ascending and
 214    descending the DIT.) Clients MAY perform more sophisticated loop
 215    detection, for example not chasing the same referral twice.
 216
 217    Case 1: The target entry is not held by the server and is
 218    superior to some entry held by the server.
 219
 220    If the server DSE contains a "refer;sup" attribute then
 221    the server will return an LDAPResult with the result code field set
 222
 223 Hedberg           Expires September 30, 2000                    [Page 4]
 224
 225 Internet-Draft    LDAP Knowledge references                   July 2000
 226
 227    to referral, and the referral field set to contain the value(s) of
 228    the "refer;sup" attribute minus any optional trailing whitespace and
 229    labels that might be present.
 230
 231    Case 2: The target entry is not held by the server and is
 232    subordinate to some entry, held by the server, that contains a
 233    refer attribute.
 234
 235    The server will return an LDAPResult with the result code field set
 236    to referral, and the referral field set to contain the value(s) of
 237    the refer attribute minus any optional trailing whitespace and labels
 238    that might be present.
 239
 240    Case 3: The target entry is held by the server and contains a
 241    refer attribute without the 'nssr' option.
 242
 243    The server will return an LDAPResult with the result code field set
 244    to referral, and the referral field set to contain the value(s) of
 245    the refer attribute minus any optional trailing whitespace and labels
 246    that might be present.
 247
 248    Case 4: The target entry is not held by the server, and is not
 249    subordinate or superior to any object held by the server.
 250
 251    If the server contains a "refer;cross" attribute
 252    in the root DSE with a baseobject that is either the same or
 253    superior to the target entry then
 254    the server will return an LDAPResult with the result code field set
 255    to referral, and the referral field set to contain the value(s) of
 256    these refer attributes minus any optional trailing whitespace and labels
 257    that might be present.
 258
 259
 260 4.2 Search evaluation
 261
 262    For search operations, once the base object has been found and
 263    determined NOT to contain a refer attribute without the 'nssr'
 264    option, the search may progress.
 265
 266 4.2.1 base-level
 267
 268    If the entry matches the filter and does NOT contain a refer attribute
 269    it will be returned to the client as described in [RFC2251].
 270    If the entry matches the filter contains a refer attribute without
 271    the 'nssr' option it will be returned as a referral as described here.
 272
 273    If a matching entry contains a refer attribute and the URI
 274    contained in the refer attribute is NOT an LDAP URI [RFC2255],
 275    the server should return the URI value contained in the refer
 276    attribute of that entry in a SearchResultReference.
 277
 278
 279 Hedberg           Expires September 30, 2000                    [Page 5]
 280
 281 Internet-Draft    LDAP Knowledge references                   July 2000
 282
 283
 284    If a matching entry contains a refer attribute in the LDAP
 285    URI syntax, the server will return an SearchResultReference
 286    containing the value(s) of the refer attribute minus any optional
 287    trailing whitespace and labels that might be present.
 288    The URL from the refer attribute must be modified before it is
 289    returned by adding or substituting a "base" scope into the URL. If the
 290    URL does not contain a scope specifier, the "base" scope specifier must
 291    be added. If the URL does contain a scope specifier, the existing scope
 292    specifier must be replaced by the "base" scope.
 293
 294 4.2.2 One-level
 295
 296    Any entries matching the filter and one level scope that
 297    do NOT contain a refer attribute are returned to the client normally as
 298    described in [RFC2251]. Any entries matching the filter and one level
 299    scope that contains a refer attribute without the 'nssr' option must
 300    be returned as referrals as described here.
 301
 302    If a matching entry contains a refer attribute and the URI
 303    contained in the refer attribute is NOT an LDAP URI [RFC2255],
 304    the server should return the URI value contained in the refer
 305    attribute of that entry in a SearchResultReference.
 306
 307    If a matching entry contains a refer attribute in the LDAP
 308    URI syntax, the server will return an SearchResultReference
 309    containing the value(s) of the refer attribute minus any optional
 310    trailing whitespace and labels that might be present.
 311    The URL from the refer attribute must be modified before it is
 312    returned by adding or substituting a "base" scope into the URL. If the
 313    URL does not contain a scope specifier, the "base" scope specifier must
 314    be added. If the URL does contain a scope specifier, the existing scope
 315    specifier must be replaced by the "base" scope.
 316
 317 4.2.3 Subtree search evaluation
 318
 319    Any entries, held by the server, matching the filter and
 320    subtree scope that do NOT contain a refer attribute or contains
 321    a refer attribute with the 'nssr' option are
 322    returned to the client normally as described in [RFC2251].
 323    Any entries matching the subtree scope and containing a refer
 324    attribute must be returned as referrals as described here.
 325
 326    If a matching entry contains a refer attribute and the URI
 327    contained in that attribute is NOT an LDAP URI [RFC2255],
 328    the server should return the URI value contained in the refer
 329    attribute of that entry in a SearchResultReference.
 330
 331
 332
 333
 334
 335 Hedberg           Expires September 30, 2000                    [Page 6]
 336
 337 Internet-Draft    LDAP Knowledge references                   July 2000
 338
 339    If a matching entry contains a refer attribute in the LDAP
 340    URI syntax, the server will return an SearchResultReference
 341    containing the value(s) of the refer attribute minus any
 342    optional trailing whitespace and labels that might be present.
 343
 344    N.B. in subtree search evaluation a entry containing a
 345    refer attribut with the 'nssr' option might appear twice in the
 346    result, first as a entry and then as a reference. A client
 347    following all references might therefore end up with a resultset
 348    containing two representations of the same entry, one from the
 349    server getting the original query and one from the server
 350    that the 'nssr' reference points to.
 351
 352
 353 5. The referral object class
 354
 355    The referral object class is defined as follows.
 356
 357    ( 1.2.752.17.2.10
 358      NAME 'referral'
 359      SUP top
 360      STRUCTURAL
 361      MAY ( refer ) )
 362
 363    The referral object class is a subclass of top and may contain the
 364    refer attribute. The referral object class should, in general,
 365    be used in conjunction with the extensibleObject object class to support
 366    the naming attributes used in the entry's distinguished name.
 367
 368    Servers must support the refer attributes through use of the
 369    referral object class. Any named reference must be of the referral
 370    object class and will likely also be of the extensibleObject object
 371    class to support naming and use of other attributes.
 372
 373
 374 6. The manageDsaIT control
 375
 376    A client MAY specify the following control when issuing a search, com-
 377    pare, add, delete, modify, or modifyDN request.
 378
 379    The control type is 2.16.840.1.113730.3.4.2.  The control SHOULD be
 380    marked as critical.  There is no value; the controlValue field is
 381    absent.
 382
 383    This control causes entries with the knowledge reference attributes to be
 384    treated as normal entries, allowing clients to read and modify these entries.
 385
 386
 387
 388
 389
 390
 391 Hedberg           Expires September 30, 2000                    [Page 7]
 392
 393 Internet-Draft    LDAP Knowledge references                   July 2000
 394
 395
 396 7. Superior Reference
 397
 398    This document defines two types of knowledge references that point to
 399    parts of the naming context that is above of beyone the part held by a server.
 400    The 'sup' option when referring to a LDAP server that holds a
 401    naming context that is closer to the root of the same naming context and
 402    'other' when referring to a LDAP server that holds a naming
 403    context that belongs to a different naming domain then the one the
 404    server belongs to.
 405
 406    Thus if the server receives a request for an operation where the
 407    target entry is a entry closer to the root than the naming
 408    context held the server and if the server holds a 'refer;sup' attribute
 409    in the DSE, then the server MUST return an LDAPResult with the result
 410    code field set to referral, and the referral field set to contain the
 411    value(s) of the 'refer;sub' attribute minus any optional trailing
 412    whitespace and labels that might be present.
 413
 414    On the other hand if the server receives a request for an operation
 415    where the target entry is a entry that belongs to a other naming domain
 416    and if there is any 'refer;other' attributes in the DSE with a base entry
 417    that belongs to the same naming domain as the target entry and is
 418    closer to the root then the target entry, then the server SHOULD return
 419    an LDAPResult with the result code field set to referral, and the referral
 420    field set to contain the value(s) of the 'refer;other' attribute minus
 421    any optional trailing hitespace and labels that might be present.
 422
 423
 424 8. Security Considerations
 425
 426    This document defines mechanisms that can be used to "glue" LDAP (and
 427    other) servers together. The information used to specify this glue
 428    information should be protected from unauthorized modification.  If the
 429    server topology information itself is not public information, the
 430    information should be protected from unauthorized access as well.
 431
 432
 433 9. References
 434
 435    [RFC1738]
 436     Berners-Lee, T., Masinter, L., and McCahill, M., "Uniform Resource
 437     Locators (URL)", RFC 1738, CERN, Xerox Corporation, University of
 438     Minnesota, December 1994,
 439
 440    [RFC2079]
 441     M. Smith, "Definition of an X.500 Attribute Type and an Object Class
 442     to Hold Uniform Resource Identifiers (URIs)", RFC 2079, January
 443     1997.
 444
 445
 446
 447 Hedberg           Expires September 30, 2000                    [Page 8]
 448
 449 Internet-Draft    LDAP Knowledge references                   July 2000
 450
 451
 452    [RFC2119]
 453     S. Bradner, "Key Words for use in RFCs to Indicate Requirement Lev-
 454     els", RFC 2119, March 1997. (Format: TXT=4723 bytes) (Also BCP0014)
 455     (Status: BEST CURRENT PRACTICE)
 456
 457    [RFC2251]
 458     M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol
 459     (v3)", RFC 2251, December 1997.  1997.
 460
 461    [RFC2255]
 462     T. Howes, M. Smith, "The LDAP URL Format", RFC 2255, December, 1997.
 463     (Format: TXT=20685 bytes) (Status: PROPOSED STANDARD)
 464
 465    [X500]
 466     ITU-T Rec. X.501, "The Directory: Models", 1993.
 467
 468    [X521]
 469     ITU-T Rec. X.521, "---------------------", 1993.
 470
 471
 472 12. Acknowledgements
 473
 474    This draft is heavily based on the previous drafts on knowledge
 475    references in LDAP written by Christopher Lukas, Tim Howes,
 476    Michael Roszkowski, Mark C. Smith, Mark Wahl and David Chadwick.
 477    Peter Valkenburg and Henny Bekker has also made valueable
 478    contributions.
 479
 480
 481 13. Authors Address
 482
 483    Roland Hedberg
 484    Catalogix
 485    Dalsveien 53
 486    0775 Oslo
 487    Norway
 488    EMail: Roland@catalogix.se
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503 Hedberg           Expires September 30, 2000                    [Page 9]
 504
 505 Internet-Draft    LDAP Knowledge references                   July 2000
 506
 507
 508    Appendix A
 509
 510    Example of usage.
 511    Information stored in a server.
 512
 513      dn:
 514      objectclass: referral
 515      refer;me: ldap://hostCAT/dc=cat,dc=se
 516      refer;sup: ldap://hostSE/dc=se
 517      refer;cross: ldap://hostNO/dc=no
 518      refer;cross: ldap://hostNL/c=nl
 519
 520      dn: dc=cat,dc=se
 521      objectclass: domain
 522      dc: cat
 523
 524      dn: dc=one,dc=cat,dc=se
 525      objectclass: extendedObject
 526      objectclass: referral
 527      refer;nssr: ldap://hostCAT1/dc=one,dc=cat,dc=se
 528      ou: one
 529      l: umea
 530
 531      dc: dc=two,dc=cat,dc=se
 532      objectclass: referral
 533      objectclass: extendedObject
 534      refer;sub: ldap://hostCAT2/dc=two,dc=cat,dc=se
 535
 536      dn: dc=three,dc=cat,dc=se
 537      objectclass: referral
 538      objectclass: extendedObject
 539      refer;cross: ldap://hostCAT3/dc=cat,dc=nl
 540
 541      dc: dc=four,dc=cat,dc=se
 542      objectclass: domain
 543      objectclass: extendedObject
 544      ou: four
 545      l: umea
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559 Hedberg           Expires September 30, 2000                    [Page 10]
 560
 561 Internet-Draft    LDAP Knowledge references                   July 2000
 562
 563
 564    ==========================================
 565       A number of descriptive cases
 566    ==========================================
 567
 568    case 1: One-level search, target object on the server
 569      search
 570        baseobject: dc=cat,dc=se
 571        scope:      onelevel
 572        filter:     (objectclass=*)
 573        attributes: ou
 574
 575      returns
 576        searchResultEntry {
 577          dn: dc=one,dc=cat,dc=se
 578          ou: one
 579        }
 580        searchResultReference {
 581          ldapurl: ldap://hostCAT2/dc=two,dc=cat,dc=se
 582        }
 583        searchResultReference {
 584          ldapurl: ldap://hostCAT3/dc=cat,dc=nl
 585        }
 586        searchResultEntry {
 587          dn: dc=four,dc=cat,dc=se
 588          ou: four
 589        }
 590        searchResultDone {
 591          resultCode: success
 592        }
 593
 594    case 2: Subtree search, target object on the server
 595      search
 596        baseobject: dc=cat,dc=se
 597        scope:      subtree
 598        filter:     (objectclass=*)
 599        attributes: ou
 600
 601      returns
 602        searchResultEntry {
 603          dn: dc=one,dc=cat,dc=se
 604          ou: one
 605        }
 606        searchResultReference {
 607          ldapurl: ldap://hostCAT1/dc=one,dc=cat,dc=se
 608        }
 609        searchResultReference {
 610          ldapurl: ldap://hostCAT2/dc=two,dc=cat,dc=se
 611        }
 612
 613
 614
 615 Hedberg           Expires September 30, 2000                  [Page 11]
 616
 617 Internet-Draft    LDAP Knowledge references                   July 2000
 618
 619
 620        searchResultReference {
 621          ldapurl: ldap://hostCAT3/dc=cat,dc=nl
 622        }
 623        searchResultEntry {
 624          dn: dc=four,dc=cat,dc=se
 625          ou: four
 626        }
 627        searchResultDone {
 628          resultCode: success
 629        }
 630
 631    case 3: base search, target entry contains a 'refer;nssr' attribute
 632      search
 633        baseobject: dc=one,dc=cat,dc=se
 634        scope:      base
 635        filter:     (objectclass=*)
 636        attributes: ou
 637
 638      returns
 639        searchResultEntry {
 640          dn: dc=one,dc=cat,dc=se
 641          ou: four
 642        }
 643        searchResultDone {
 644          resultCode: success
 645        }
 646
 647    case 4: base search, target entry contains a 'refer;sub' attribute
 648      search
 649        baseobject: dc=two,dc=cat,dc=se
 650        scope:      base
 651        filter:     (objectclass=*)
 652        attributes: ou
 653
 654      returns
 655        searchResultDone {
 656          resultCode: referral
 657          matchedDN: dc=two,dc=cat,dc=se
 658          referral: ldap://hostCAT2/dc=two,dc=cat,dc=se
 659        }
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671 Hedberg           Expires September 30, 2000                    [Page 12]
 672
 673 Internet-Draft    LDAP Knowledge references                   July 2000
 674
 675
 676   case 5: one-level search, target entry contains a 'refer;nssr' attribute
 677      search
 678        baseobject: dc=one,dc=cat,dc=se
 679        scope:      onelevel
 680        filter:     (objectclass=*)
 681        attributes: ou
 682
 683        searchResultDone {
 684          resultCode: referral
 685          matchedDN: dc=one,dc=cat,dc=se
 686          referral: ldap://hostCAT1/dc=one,dc=cat,dc=nu
 687        }
 688
 689   case 6: Search on area above the baseobject of the server
 690      search
 691        baseobject: dc=pi,dc=se
 692        scope:      subtree
 693        filter:     (objectclass=*)
 694        attributes: ou
 695
 696      returns
 697        searchResultDone {
 698          resultCode: referral
 699          matchedDN:  dc=se
 700          referral:   ldap://hostSE/dc=se
 701       }
 702
 703
 704
 705   case 7: Search on area beyond, but not below the baseobject
 706         of the server
 707      search
 708        baseobject: o=surfnet,c=nl
 709        scope:      base
 710        filter:     (objectclass=*)
 711
 712      returns
 713        searchResultDone {
 714          resultCode: referral
 715          matchedDN:  c=nl
 716          referral:   ldap://hostNL/c=NL
 717        }
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727 Hedberg           Expires September 30, 2000                    [Page 13]
 728