openldap/doc/rfc/rfc2657.txt

Network Working Group                                        R. Hedberg
Request for Comment: 2657                                     Catalogix
Category: Experimental                                      August 1999


                    LDAPv2 Client vs. the Index Mesh

Status of this Memo

   This memo defines an Experimental Protocol for the Internet
   community.  It does not specify an Internet standard of any kind.
   Discussion and suggestions for improvement are requested.
   Distribution of this memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (1999).  All Rights Reserved.

Abstract

   LDAPv2 clients as implemented according to RFC 1777 [1] have no
   notion on referral.  The integration between such a client and an
   Index Mesh, as defined by the Common Indexing Protocol [2], heavily
   depends on referrals and therefore needs to be handled in a special
   way.  This document defines one possible way of doing this.

1. Background

   During the development of the Common Indexing Protocol (CIP), one of
   the underlying assumptions was that the interaction between clients
   and the Index Mesh Servers [1] would heavily depend on the passing of
   referrals.  Protocols like LDAPv2 [2] that lack this functionality
   need to compensate for it by some means.  The way chosen in this memo
   is to add more intelligence into the client. There are two reasons
   behind this decision.  First, this is not a major enhancement that is
   needed and secondly, that the intelligence when dealing with the
   Index Mesh, with or the knowledge about referrals, eventually has to
   go into the client.

2. The clients view of the Index Mesh

   If a LDAPv2 client is going to be able to interact with the Index
   Mesh, the Mesh has to appear as something that is understandable to
   the client.  Basically, this consists of representing the index
   servers and their contained indexes in a defined directory
   information tree (DIT) [3,4] structure and a set of object classes
   and attribute types that have been proven to be useful in this
   context.



Hedberg                       Experimental                      [Page 1]

RFC 2657                 LDAPv2 vs. Index Mesh               August 1999


2.1 The CIP Object Classes

   Object class descriptions are written according to the BNF defined in
   [5].

2.1.1 cIPIndex

   The cIPIndex objectClass, if present in a entry, allows it to hold
   one indexvalue and information connected to this value.

   ( 1.2.752.17.3.9
     NAME 'cIPIndex'
     SUP 'top'
     STRUCTURAL
     MUST ( extendedDSI $ idx )
     MAY ( indexOCAT )
   )

2.1.2 cIPDataSet

   The cIPDataSet objectClass, if present in a entry, allows it to hold
   information concerning one DataSet.

   ( 1.2.752.17.3.10
     NAME 'cIPDataSet'
     SUP 'top'
     STRUCTURAL
     MUST ( dSI $ searchBase )
     MAY ( indexOCAT $ description $ indexType $
           accessPoint $ protocolVersion $ polledBy $
           updateIntervall $ securityOption $
           supplierURI $ consumerURI $ baseURI $
           attributeNamespace $ consistencyBase
      )
   )

2.2 The CIP attributeTypes

   The attributes idx, indexOCAT, extendedDSI, description,
   cIPIndexType, baseURI, dSI are used by a client accessing the index
   server.  The other attributes (accesspoint, protocolVersion,
   polledBy, updateIntervall, consumerURI, supplierURI and
   securityOption, attributeNamespace, consistencyBase) are all for
   usage in server to server interactions.







Hedberg                       Experimental                      [Page 2]

RFC 2657                 LDAPv2 vs. Index Mesh               August 1999


2.2.1 idx

   The index value, normally used as part of the RDN.

   ( 1.2.752.17.1.20
     NAME 'idx'
     EQUALITY caseIgnoreIA5Match
     SYNTAX IA5String
     SINGLE-VALUE
      )

2.2.2 dSI

   DataSet Identifier, a unique identifier for one particular set of
   information.  This should be an OID, but stored in a stringformat.

   ( 1.2.752.17.1.21
     NAME 'dSI'
     EQUALITY caseIgnoreIA5Match
     SYNTAX IA5String
   )

2.2.3 indexOCAT

   Describes the type of data that is stored in this entry, by using
   objectcClasses and attributeTypes. The information is stored as a
   objectClass name followed by a space and then an attributeType name.
   A typical example when dealing with whitepages information would be
   "person cn".

   ( 1.2.752.17.1.28
     NAME 'indexOCAT'
     EQUALITY caseIgnoreIA5Match
     SYNTAX IA5String
   )

2.2.5 supplierURI

   A URI describing which protocols, hostnames and ports should be used
   by an indexserver to interact with servers carrying indexinformation
   representing this dataSet.

     ( 1.2.752.17.1.22
      NAME 'supplierURI'
      EQUALITY caseIgnoreIA5Match
      SYNTAX IA5String
   )




Hedberg                       Experimental                      [Page 3]

RFC 2657                 LDAPv2 vs. Index Mesh               August 1999


2.2.6 baseURI

   The attribute value for this attribute is a LDAP URI. One can
   envisage other URI syntaxes, if the client knows about more access
   protocols besides LDAP, and the interaction between the client and
   the server can not use referrals for some reason.

   ( 1.2.752.17.1.26
     NAME 'baseURI'
     EQUALITY caseExactIA5Match
     SYNTAX IA5String
   )

2.2.7 protocolVersion

   At present, the Common Indexing Protocol version should be 3.

   ( 1.2.752.17.1.27
     NAME 'protocolVersion'
     EQUALITY numericStringMatch
     SYNTAX numericString
   )

2.2.8 cIPIndexType

   The type of index Object that is used to pass around index
   information.

   ( 1.2.752.17.1.29
     NAME 'cIPIndexType'
     EQUALITY caseIgnoreIA5Match
     SYNTAX IA5String
   )

2.2.10 polledBy

   The Distinguished Name of Index servers that polls data from this
   indexserver.

   ( 1.2.752.17.1.30
     NAME 'polledBy'
     EQUALITY distinguishedNameMatch
     SYNTAX DN
   )







Hedberg                       Experimental                      [Page 4]

RFC 2657                 LDAPv2 vs. Index Mesh               August 1999


2.2.11 updateIntervall

   The maximum duration in seconds between the generation of two updates
   by the supplier server.

   ( 1.2.752.17.1.31
     Name 'updateIntervall'
     EQUALITY numericStringMatch
     SYNTAX numericString
     SINGLE-VALUE
   )

2.2.12 securityOption

   Whether and how the supplier server should sign and encrypt the
   update before sending it to the consumer server.

   ( 1.2.752.17.1.32
     NAME 'securityOption'
     EQUALITY caseIgnoreIA5Match
     SYNTAX IA5String
     SINGLE-VALUE
   )

2.2.13 extendedDSI

   DataSet Identifier possibly followed by a space and a taglist, the
   later as specified by [6].

   ( 1.2.752.17.1.33
     NAME 'extendedDSI'
     EQUALITY caseIgnoreIA5Match
     SYNTAX IA5String
        )

2.2.14 consumerURI

   A URI describing which means a server can accept indexinformation.
   An example being a mailto URI for MIME email based index transport.

   ( 1.2.752.17.1.34
     NAME 'consumerURI'
     EQUALITY caseExactIA5Match
     SYNTAX IA5String
   )






Hedberg                       Experimental                      [Page 5]

RFC 2657                 LDAPv2 vs. Index Mesh               August 1999


2.2.15 attributeNamespace

   Any consumer supplier pair has to agree on what attribute that should
   be used and also possibly the meaning of the attributenames. The
   value of this attribute should, for example, be a URI pointing to a
   document wherein the agreement is described.

   ( 1.2.752.17.1.35 NAME 'attributeNamespace' EQUALITY
     caseExactIA5Match SYNTAX IA5String
   )

2.2.16 consistencyBase

   This attribute is specifically used by consumer supplier pairs that
   use the tagged index object [6].

   ( 1.2.752.17.1.36
     NAME 'consistencyBase'
     EQUALITY caseExactIA5Match
     SYNTAX IA5String
   )

3. The interaction between a client and the Index Mesh

   A client interaction with the Index Mesh consists of a couple of
   rather well defined actions. The first being to find a suitable index
   to start with, then to transverse the Index Mesh and finally to query
   the servers holding the original data.  Note when reading this text
   that what is discussed here is the client's perception of the DIT,
   how it is in fact implemented is not discussed.

3.1 Finding a Index Mesh

   This approach depends on the fact that every index server partaking
   in an Index Mesh is represented in the DIT by a entry of the type
   cIPDataSet, and has a distinguished name (DN) which most significant
   relative distinguished name (RDN) has the attributetype dSI.
   Therefore, finding a suitable indexserver to start the search from is
   a matter of searching the DIT at a suitable place for objects with
   the objectClass cIPIndexObject.  Every found entry can then be
   evaluated by looking at the description value as well as the
   indexOCAT value. The description string should be a human readable
   and understandable text that describes what the index server is
   indexing. An example of such a string could be, "This index covers
   all employees at Swedish Universities and University Colleges that
   has an email account". The indexOCAT attribute supplies information
   about which kind of entries and which attributes within these entries
   that the index information has emanated from.  For example, if the



Hedberg                       Experimental                      [Page 6]

RFC 2657                 LDAPv2 vs. Index Mesh               August 1999


   indexOCAT attribute value is "person cn", one can deduce that this is
   an index over persons and not over roles, and that it is the
   attribute commonName that is indexed.

3.2 Searching the mesh

   Each index server has its information represented in the DIT as a
   very flat tree. In fact, it is only one level deep.


                            0 Indexservers cIPDataSet
                           /|\
                          / | \
                         /  |  \
                        0       0
      cIPDataSet entries     cIPIndex entries
      one for each DataSet   one for each index value
      that this server has   that this indexserver
      gathered indexes from. has.

   A search then consists of a set of searches.  The first being the
   search for the index entries that contains an indexvalue that matches
   what the user is looking for, and the second a search based on the
   DSI information in the extendedDSI attribute values returned from the
   first search.  In the case of the the cIPIndexType being tagged-
   index, the taglists should be compared to find which DSI it might be
   useful to pose further queries to.

   When doing these types of searches, the client should be aware of the
   fact that the index values disregarding their origin (attributeTypes)
   always are stored in the index server as values of the idx attribute.

   The object of the second search is to get information on the
   different DataSet involved, and should normally be performed as a
   read. Since the DataSet information probably will remain quite stable
   over time, this information lends itself very well to caching.  If at
   this stage there is more than one DataSet involved, the User
   interface might use the description value to aid the user in choosing
   which one to proceed with.  The content of the searchBase value of
   the DataSet tells the client whether it represents another index
   server (the most significant part of the dn is a dSI attribute) or if
   it is a end server.









Hedberg                       Experimental                      [Page 7]

RFC 2657                 LDAPv2 vs. Index Mesh               August 1999


3.3 Querying the end server

   When finally reaching the end server/servers that probably has the
   sought for information, the information in the indexOCAT attribute
   can be used to produce an appropriate filter.  If a search for "Rol*"
   in an index having an indexOCAT attribute value of "person cn"
   returns an idx entry with the idx value of "Roland", then an
   appropriate filter to use might be "&(|(cn=* roland *)(cn=roland
   *)(cn=* roland))(objectclass=person)".  A complete example of a
   search process is given in Appendix A.

4. Security Considerations

   Since this memo deals with client behavior, it does not add anything
   that either enhances or diminishes the security features that exists
   in LDAPv2.

5. Internationalization

   As with security, this memo neither enhances or diminishes the
   handling of internationalization in LDAPv2.

6. References

   [1] Yeong, W., Howes, T. and S. Kille, "Lightweight Directory Access
       Protocol", RFC 1777, March 1995.

   [2] Allen, J. and M. Mealling "The Architecture of the Common
       Indexing Protocol (CIP)", RFC 2651, August 1999.

   [3] The Directory: Overview of Concepts, Models and Service. CCITT
       Recommendation X.500, 1988.

   [4] Information Processing Systems -- Open Systems Interconnection --
       The Directory: Overview of Concepts, Models and Service. ISO/IEC
       JTC 1/SC21; International Standard 9594-1, 1988.

   [5] Wahl, M., Coulbeck, A., Howes, T. and S. Kille, "Lightweight
       Directory Access Protocol (v3): Attribute Syntax Definitions",
       RFC 2252, December 1997.

   [6] Hedberg, R., Greenblatt, B., Moats, R. and M. Wahl, "A Tagged
       Index Object for use in the Common Indexing Protocol", RFC 2654,
       August 1999.







Hedberg                       Experimental                      [Page 8]

RFC 2657                 LDAPv2 vs. Index Mesh               August 1999


7. Author's Address

   Roland Hedberg
   Catalogix
   Dalsveien 53
   0387 Oslo, Norway

   Phone: +47 23 08 29 96
   EMail: roland@catalogix.ac.se










































Hedberg                       Experimental                      [Page 9]

RFC 2657                 LDAPv2 vs. Index Mesh               August 1999


Appendix A - Sample Session

   Below is a sample of a session between a LDAPv2 client and an index
   server mesh as specified in this memo.

   The original question of the session is to find the email address of
   a person by the name, "Roland Hedberg", who is working at "Umea
   University" in Sweden.

   Step 1.

   A singlelevel search with the baseaddress "c=SE" and the filter
   "(objectclass=cipDataset)" was issued.

   The following results were received:

   DN: dSI=1.2.752.17.5.0,c=SE
   dsi= 1.2.752.17.5.0
   description= "index over employees with emailaddresses within Swedish
   higher education"
   indexOCAT= "cn person"
   cIPIndexType= "x-tagged-index-1" ;
   searchBase= "dsi=1.2.752.17.5.0,c=SE"
   protocolVersion = 3

   DN: dSI=1.2.752.23.1.3,c=SE
   dsi= 1.2.752.23.1.3
   description= "index over Swedish lawyers"
   indexOCAT= "cn person"
   cIPIndexType= "x-tagged-index-1" ;
   searchBase= "dsi=1.2.752.23.1.3,c=SE"
   protocolVersion = 3

   Step 2.

   Since the first index seemed to cover the interesting population, a
   single level search with the baseaddress "dsi=1.2.752.17.5.0,c=SE"
   and the filter "(|(idx=roland)(idx=hedberg))" was issued.

   The following results were received:

   DN: idx=Roland,dSI=1.2.752.17.5.0,c=SE
   idx= Roland
   extendedDSI= 1.2.752.17.5.10 1,473,612,879,1024
   extendedDSI= 1.2.752.17.5.14 35,78,150,200
   extendedDSI= 1.2.752.17.5.16 187,2031,3167,5284,6034-6040
   extendedDSI= 1.2.752.17.5.17 17




Hedberg                       Experimental                     [Page 10]

RFC 2657                 LDAPv2 vs. Index Mesh               August 1999


   DN: idx=Hedberg,dSI=1.2.752.17.5.0,c=SE
   idx= Hedberg
   extendedDSI= 1.2.752.17.5.8  24,548-552,1066
   extendedDSI= 1.2.752.17.5.10 473,512,636,777,1350
   extendedDSI= 1.2.752.17.5.14 84,112,143,200
   extendedDSI= 1.2.752.17.5.15 1890-1912
   extendedDSI= 1.2.752.17.5.17 44

   A comparison between the two sets of extendedDSIs shows that two
   datasets 1.2.752.17.5.10 and 1.2.752.17.5.14 contains persons named
   "Roland" and "Hedberg". Therefore, the next step would be to see what
   the datasets represent.  A comparison like this should normally not
   be left to the user.

   Step. 3

   Two baselevel searches, one for
   "dsi=1.2.752.17.5.10,dsi=1.2.752.17.5.0,c=SE" and the other for
   "dsi=1.2.752.17.5.14,dsi=1.2.752.17.5.0,c=SE" with the filter
   "(objectclass=cipdataset)" were issued.

   The following results were received:

   DN: dSI=1.2.752.17.5.10,dSI=1.2.752.17.5.0,c=SE
   dsi= 1.2.752.17.5.10
   description= "Employees at Umea University,Sweden"
   indexOCAT= "person cn"
   searchBase= "o=Umea Universitet,c=SE"

   respectively

   DN: dSI=1.2.752.17.5.14,dSI=1.2.752.17.5.0,c=SE
   dsi= 1.2.752.17.5.14
   description= "Employees at Lund University,Sweden"
   indexOCAT= "person cn"
   searchBase= "o=Lunds Universitet,c=SE"

   Step 4

   Based on the descriptions for the two datasets, "1.2.752.17.5.10" was
   chosen as the best to proceed with.  From the searchbase attribute
   value, it was clear that this was a base server.  The query now has
   to be somewhat modified.  One possibility would be to issue a query
   with the baseobject "o=Umea Universitet,c=SE" and the filter
   "(&(cn=Roland Hedberg)(objectclass=person))"






Hedberg                       Experimental                     [Page 11]

RFC 2657                 LDAPv2 vs. Index Mesh               August 1999


Full Copyright Statement

   Copyright (C) The Internet Society (1999).  All Rights Reserved.

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implementation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph are
   included on all such copies and derivative works.  However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than
   English.

   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assigns.

   This document and the information contained herein is provided on an
   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Acknowledgement

   Funding for the RFC Editor function is currently provided by the
   Internet Society.



















Hedberg                       Experimental                     [Page 12]