From: Kurt Zeilenga Date: Sat, 5 Jan 2002 02:40:10 +0000 (+0000) Subject: Trim some old/experimental RFCs X-Git-Tag: LDBM_PRE_GIANT_RWLOCK~282 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=879733f9f7c6f57cd69d7ca5db40a180cd6ef18a;p=openldap Trim some old/experimental RFCs --- diff --git a/doc/rfc/INDEX b/doc/rfc/INDEX index 2765487d27..27e5596db9 100644 --- a/doc/rfc/INDEX +++ b/doc/rfc/INDEX @@ -1,13 +1,7 @@ This is an index of RFC contained in this directory: rfc1274.txt COSINE and Internet X.500 Schema (PS) -rfc1279.txt X.500 and Domains (E) -rfc1430.txt Plan for Deploying an Internet X.500 Directory Service (I) -rfc1617.txt Naming and Structuring Guidelines for X.500 Directory Pilots (I) -rfc1798.txt Connection-less LDAP (PS) -rfc1823.txt LDAP C API (I) rfc2079.txt X.500 Attribute Type and an Object Class to Hold URIs (PS) -rfc2218.txt Common Schema for the Internet White Pages Service (PS) rfc2247.txt Using Domains in LDAP DNs (PS) rfc2251.txt LDAPv3 Protocol (PS) rfc2252.txt LDAPv3 Attribute Types (PS) @@ -23,14 +17,12 @@ rfc2587.txt Internet X.509 PKI LDAPv2 Schema (PS) rfc2589.txt LDAPv3: Dynamic Directory Services Extensions (PS) rfc2596.txt Use of Language Codes in LDAP (PS) rfc2649.txt LDAPv3 Operational Signatures (E) -rfc2657.txt LDAPv2 Client vs. the Index Mesh (E) rfc2696.txt LDAP Simple Paged Result Control (I) rfc2713.txt LDAP Java schema (I) rfc2714.txt LDAP CORBA schema (I) rfc2798.txt LDAP inetOrgPerson schema (I) rfc2829.txt LDAPv3: Authentication Method (PS) rfc2830.txt LDAPv3: StartTLS (PS) -rfc2831.txt SASL/DIGEST-MD5 (PS) rfc2849.txt LDIFv1 (PS) rfc2891.txt LDAPv3: Server Side Sorting of Search Results (PS) rfc3045.txt Storing Vendor Information in the LDAP root DSE (I) diff --git a/doc/rfc/rfc1279.txt b/doc/rfc/rfc1279.txt deleted file mode 100644 index e389bd2ac3..0000000000 --- a/doc/rfc/rfc1279.txt +++ /dev/null @@ -1,839 +0,0 @@ - - - - - - -Network Working Group S.E. Hardcastle-Kille -Requests for Comments 1279 University College London - November 1991 - - - - - - - - X.500 and Domains - - - - - - - - - -Status of this Memo - This memo defines an Experimental Protocol for the Internet - community. Discussion and suggestions for improvement are - requested. Please refer to the current edition of the ``IAB - Official Protocol Standards'' for the standardization state and - status of this protocol. Distribution of this memo is unlimited. -Abstract - - This RFCconsiders X.500 in relation to Internet and UK Domains. - A basic model of X.500 providing a higher level and more - descriptive naming structure is emphasised. In addition, a - mapping of domains onto X.500 is proposed, which gives a range of - new management and user facilities over and above those currently - available. This specification proposes an experimental new - mechanism to access and manage domain information on the Internet - and in the UK Academic Community. There is no current intention - to provide an operational replacement for DNS. - - - - -RFC 1279 X.500 and Domains November 1991 - - -1 The Domain Name System - -The Domain (Nameserver) System (DNS) provides a hierarchical resource -labelling system [Moc87a] [Moc87b] [Lar83]. Example domains are: - -MIT.EDU -VENERA.ISI.EDU -CS.UCL.AC.UK - - -Entries usually have a single name, although pointers to entries (not -subtrees) may be provided by CNAME records. Information (resource -records) is associated with each entry. Name components are typically -chosen to be shortish (e.g., ``CS''). -RFC 822 mailbox names are closely related [Cro82]. For example: - - - - -The local-part of the RFC 822 mailbox can be considered as one level -lower in the domain hierarchy. - - -2 X.500 - -The OSI Directory, usually known as X.500, provides a very general -naming framework [CCI88]. A basic usage of X.500 is to provide -Organisationally Structured Names. A Schema for this is defined -within the standard. Name components will typically have longish -values. This is an example directory name represented in Tabular -form: - - - Country GB - Organisation University College London - Organisational Unit Computer Science - Common Name Stephen E. Hardcastle-Kille - -This can also be written in the ``User Friendly Name'' notation -defined in [HK91]. This syntax is used for names in the rest of this -document: - - - Stephen E. Hardcastle-Kille, Computer Science, - -Hardcastle-Kille Page 1 - - - - -RFC 1279 X.500 and Domains November 1991 - - - University College London, GB - -This type of structure is termed ``organisational X.500''. This is a -subset of the general capabilities. - - -3 The basic model - - X.500 has as much relation to the DNS as DNS has to ARP. Paul - Mockapetris - - -This is, essentially, the position adopted here. The basic model is -that organisational X.500 is providing a layer of naming at the level -above domain names. These structured names can be considered to form -a naming layer above domain names. There are the following key -differences: - - o Organisational X.500 tends to use longer and more descriptive - values - - o The organisational X.500 DIT is slightly shallower than the DNS - tree - - o X.500 has a richer information framework than DNS - - -These differences suggest that the following should NOT be done: - - o Represent X.500 information in the DNS - - o Have an algorithmic mapping between the two hierarchies - -This note proposes to represent DNS information in the DIT, and to -provide for a loose coupling between the two trees. This note does -not propose an equivalencing of X.500 and Domains. - -The proposed model is illustrated in Figure 1. Both an organisational -and domain structure is represented in the DIT, by use of appropriate -object classes and attribute types. A weak linkage is provided -between the two parts of the tree by use of special attributes. Here, -the linkage is 1:1, but it may be more complex for some parts of the -organisational DIT or domain namespace. The linkage is achieved by -use of special attributes, as described in Section 11. - -Hardcastle-Kille Page 2 - - - - -RFC 1279 X.500 and Domains November 1991 - - - - - - - - - - - j jZ Z - - j j ZZ - jj Z Z - jjj ZZ - -Domain Component=UK Country Name=GB - | - | - | -Domain Component=AC Organisation Name=Univeristy College London - - * BB - ss BBB - -Domain Component=UCL Org Unit Name=Computer Science - | * - - || ss -Domain Component=CS Common Name=Steve Kille - - | * - | ss - -Domain Component=S.Kille - Figure 1: Example X.500 tree - - - - - - - - - - - -Hardcastle-Kille Page 3 - - - - -RFC 1279 X.500 and Domains November 1991 - - -4 Representing Domains in X.500 - -Domains are at the level below X.500 names of the form illustrated in -the previous section. However, it is also possible to use X.500 in -other ways. In particular, there are benefits from representing -Domains in X.500. Note that this is very different to equivalencing, -as no attempt is made to represent X.500 information within the domain -scheme. There are the following potential advantages: - - - o Domain Services (DNS and NRS) could be replaced with an OSI - service (some may not view this as an advantage). This is - particularly attractive for OSI services, where use of a non-OSI - directory may be inappropriate. - - o For Internet sites, access to domain information (beyond MX - records) could be provided for systems registered remotely. For - UK Academic Community sites, access to domain information for - domains not registered in the NRS could be given. For sites - neither on the Internet nor in the UK Academic Community there - will usually be even more of an advantage, as they usually have - very limited information on domains. - - o Assuming that information is downloaded from an X.500 database - into a DNS or NRS system, the remote management facilities of - X.500 could be used. This is possible because of the extra - security features of X.500. - - Note: For initial work, the converse situation of information - being mastered in Domain Databases and uploaded into the X.500 - DIT is more likely. - - o User access to the domain data, and in particular searching, could - be provided. This would allow users to browse the domain - namespace, and to determine information associated with the - domains. - - o The X.500 framework would allow for additional management - information to be stored, and to relate the domain names into a - more complex structure of information. For example, this might - allow for the managers of a system to be identified, and - information on how to contact the manager. - - - -Hardcastle-Kille Page 4 - - - - -RFC 1279 X.500 and Domains November 1991 - - - o A facility to map RFC 822 mailbox into a Directory Name (and thus - access other user information on the basis of this key) could be - provided. This may be useful for the user to determine - information about a message originator. - - o This technique may be useful to facilitate introduction of - security, as it will enable certificates to be associated with - domains and mailboxes. This may be very useful for the privacy - enchanced mail work [Lin89]. - - -5 Representing Domain Names - -A new attribute syntax is defined: - - -CaseIgnoreIA5StringSyntax ATTRIBUTE-SYNTAX - IA5String - MATCHES FOR EQUALITY SUBSTRINGS ORDERING - - -A new attribute and two new object classes are defined: - - -DomainComponent ATTRIBUTE - WITH ATTRIBUTE-SYNTAX caseIgnoreIA5StringSyntax - SINGLE VALUE - -Domain OBJECT-CLASS - SUBCLASS OF top - MUST CONTAIN -DomainComponent" - MAY CONTAIN -AssociatedName, - organizationName, - organizationalAttributeSet, - manager" - -RFC822Mailbox OBJECT-CLASS - SUBCLASS OF Domain - MAY CONTAIN -commonName, - surname, - description, - telephoneNumber, - postalAttributeSet, - telecommunicationAttributeSet " - -Hardcastle-Kille Page 5 - - - - -RFC 1279 X.500 and Domains November 1991 - - -Note that the attribute AssociatedName is defined in Section 11. The -manager attribute is defined in the COSINE and Internet naming -architecture [BHK91]. It allows a manager to be associated with the -domain, which is useful where the manager of the domain is different -to the manager of the object defined by the AssociatedName. This will -allow any domain to be represented in an X.500 hierarchy. The local -part of an RFC 822 mailbox is treated as a special sort of domain -component, and so these can be represented in the tree as a natural -extension of the hierarchy. -For example, consider the mailbox S.Kille@cs.ucl.ac.uk. This will -lead to the following structure in the DIT: - - ___________________________________________ - |_Object_Class__|RDN_Type________|RDN_Value_| - | Domain |DomainComponent |UK | - | Domain |DomainComponent |AC | - | Domain |DomainComponent |UCL | - | Domain |DomainComponent |CS | - |_RFC822Mailbox_|DomainComponent_|S.Kille__ | - -This can be represented in User Friendly Name format as: - - -DomainComponent=S.Kille, DomainComponent=CS, DomainComponent=UCL, -DomainComponent=AC, DomainComponent=UK - -Note that the RFC822Mailbox Object Class is a subclass of Domain. -Some attributes are allowed to be associated with these objects. -There may be other additional management attributes which it is useful -to define (e.g., Machine Type, Owner, Location etc.). This allows -some information which truly belongs to the domain to be represented -there. It also allows for further information to be associated with -the domain/mailbox when there is not a relevant part of the -organisationally structure DIT to be pointed at. When there is an -associated part of the DIT, information from that part of the DIT -should not be duplicated in the domain entry. - - -6 Wildcards - - -Wildcards are supported by having "*" as a special domain component -name. If there is a need to emulate wildcard matching using the -directory, the following algorithm must be employed. For example, the - -Hardcastle-Kille Page 6 - - - - -RFC 1279 X.500 and Domains November 1991 - - -wildcard entry for *.*.PODUNK.COM would be represented in the DIT as: - - DomainComponent=*, DomainComponent=*, - DomainComponent=MIT, DomainComponent=COM - - -If A.B.PODUNK.COM is looked up in the directory, the query will fail -and indicate that two components are matched. A substitution should -be made, and *.*.PODUNK.COM looked up explicitly to identify the -associated information. - - -7 DNS Information - -DNS information can be associated with an entry in the DIT. It is -important that this is done in a manner which is exactly equivalent to -the information stored in the DNS. This will allow the DIT to have -information loaded from the DNS or vice versa. All (authoritative) -records associated with a domain will be stored in the DIT. There is -no attempt made by the OSI Directory to emulate DNS caching or TTL -handling. It is assumed that the master entries are maintained by use -of DNS Zone Transfer (or equivalent), and that they can be treated as -authoritative. There is a need to define an attribute syntax which -represents a DNS record. This then allows DNS records to be stored in -the DIT. There are three possible encodings of this record: - -ASN.1 Encoded This is the most natural approach in terms of X.500. - However, it would require all users of this service to handle the - new syntax, which would be awkward. There is a problem with - handling the resource format in a general manner. - -DNS Binary Encoded Use the formally defined record syntax. This - would be convenient for access to the data by DNS related - software, but would be an awkward encoding for independent X.500 - DUAs. - -Text encoded Use of a text encoding derived from the DNS - specifications. This is straightforward to map onto DNS protocol, - and easy to support in a naive X.500 DUA. This approach is chosen. - - -The syntax is defined in IA5 characters. The BNF of the record uses -the definitions of section 5.1 of RFC 1035. It is - - -Hardcastle-Kille Page 7 - - - - -RFC 1279 X.500 and Domains November 1991 - - - [ ";" ] - -Three examples of this (for domain C.ISI.EDU) might be: - - -500 A 10.1.0.52 ; Basic address record -IN 600 MX 10 VENERA.ISI.EDU. ; MX record -600 IN MX 10 VENERA.ISI.EDU. ; MX record - other order - -Note that: - - - o The class and TTL may be in either order (following RFC 1035) - - o The class defaults to IN - - o Domains must always be fully specified (i.e., master file - abbreviate rules are not used). - - o The TTL for a record must always be present (this saves looking at - the parent entry to find the SOA record). - - o Records (e.g., SOA) may be multiline. Lines should be separated - with the two IA5 characters . - -CNAME records are mapped symmetrically onto Directory Aliases. - -This is now defined in terms of attribute and object class -definitions. A single record type is defined, as opposed to one -attribute type per record type. This allows the definition to not -require extension when new DNS Record types are define. However, -there is some loss of efficiency if only a single record type is -needed, as filtering must be done by the DUA. -Similarly, no distinction is made on the basis of DNS class. This -means that if there are two class hierarchies, that they must be -represented in a single DIT, and that information for different -classes must be separated by DUA filtering. - - -DNSDomain OBJECT-CLASS - SUBCLASS OF Domain - MAY CONTAIN - - DNSRecord " - - -Hardcastle-Kille Page 8 - - - - -RFC 1279 X.500 and Domains November 1991 - - -DNSRecord ATTRIBUTE - ATTRIBUTE-SYNTAX IA5String - MATCHES FOR EQUALITY - - -Lookup of a domain is achieved by translating it algorithmically to a -Distinguished Name (DN), and reading back attributes desired. This -information can be managed and searched in a straightforward fashion. - -The information may also be downloaded into a DNS database. This -should be done by use of zone transfer. A tool to perform zone -transfer (in both directions) between a DNS Server and a DSA would -seem to be both straightforward and useful. This would be a key tool -in a transition to X.500 based management of the DNS. It would also -allow a large part of the DNS namespace to be rapidly made available -in an X.500 pilot. -Inverse information can be derived by the usual IN-ADDR domain, which -will be represented in the same manner in the DIT. - - -8 NRS Information - -Information associated with the UK NRS (Name Registration Scheme) can -be handled in a similar manner [Lar83]. This is being developed in a -separate document by Alan Turland. - - -9 Application Entity Titles - -In many cases, Application entities will be closely related to -domains. In some cases, it may be appropriate to give Application -Entities names which are related to the DNS part of the DIT. In this -case, the Domain Name will be used to identify the application, and -the entry for the domain will also be of object class Application -Process. The children of this entry will identify Application -Entities, with names such as ``FTAM Service''. - - -10 Networks - - -It is clearly useful to represent networks within the DIT. A short -note on how to do this is given here. It is likely that this -specification will later be evolved in a separate document. This - -Hardcastle-Kille Page 9 - - - - -RFC 1279 X.500 and Domains November 1991 - - -defines an Object Class for a general network, and shows how it can be -subclassed to define technology specific networks. - -Network OBJECT-CLASS - SUBCLASS OF TOP - MAY CONTAIN - - Manager, - Locality, - Description " - -IPNetwork OBJECT-CLASS - SUBCLASS OF Network - MUST CONTAIN -AssociatedDomain" - - -The Network Object Class allows networks to be defined, and for useful -attributes to be associated with the entry. A network will often -appear in more than one organisational structure, and this linkage -should be achieved by use of aliases. This grouping can facilitate -management of networks. -The subclass IPNetwork mandates linkage into the DNS part of the DIT. -This will be represented in the DIT using the structures of RFC 1101 -[Moc89]. Both of the domains which identify the network should be -represented in the Object Class. For example, a network might have -the (user friendly) name: - - UCL-Ethernet, University College London, GB - - -This would have associated domains 0.0.40.128.IN-ADDR.ARPA and -UCL-ETHERNET.UCL.AC.UK. These would both have the analogous DIT -representations. For example: - -DomainComponent=0, DomainComponent=0, DomainComponent=40, -DomainComponent=128, DomainComponent=IN-ADDR, DomainComponent=ARPA - - -11 Linkage - - -There is a need to associate the organisational X.500 DIT and the DNS -tree. The objects represented are different (Domain 6= Organisation; -Person 6= RFC 822 Mailbox). Therefore aliasing is not an appropriate -linkage. However, in many cases, there is a linkage which is rather - -Hardcastle-Kille Page 10 - - - - -RFC 1279 X.500 and Domains November 1991 - - -stronger than that implied by the seeAlso attribute. Therefore, we -define new attributes, which represent this stronger cross-linkage. -The same mechanism can be used to link a domains with an Application -Entity or an Application Process. -Links from the organisational X.500 DIT to the DNS tree are provided -by a new attribute, which could be present in Organisation or -Organisational Unit entries. - - -ObjectWithAssociatedDomain OBJECT-CLASS - SUBCLASS OF top - MUST CONTAIN -AssociatedDomain" - -AssociatedDomain ATTRIBUTE - WITH ATTRIBUTE-SYNTAX ia5StringSyntax - -For example, the organisational entry: - - University College London, GB - - -would have an attribute: - - AssociatedDomain = UCL.AC.UK - - -Similarly, an RFC 822 mailbox attribute is used to link entries of -Person Object Class to their associated DNS entry. This attribute is -defined in the Cosine and Internet Naming Architecture [BHK91]. -Conversely, there are pointers from the DNS represented tree into the -organisational X.500 DIT: - - -AssociatedName ATTRIBUTE - WITH ATTRIBUTE-SYNTAX distinguishedNameSyntax - -This attribute is associated with the Domain object class. - -This entry is used to provide linkage from the DNS X.500 Hierarchy -into the organisational X.500 hierarchy. Where such entries do not -exist, attributes in the DNS entry (such as phone number) may be used. -It is recommended that information is not duplicated. The preferred -setup is for the DNS attributes to be rather skeletal, with pointers -into the organisational X.500 DIT. - -Hardcastle-Kille Page 11 - - - - -RFC 1279 X.500 and Domains November 1991 - - -For example, the domain UCL.AC.UK would be represented in the DIT as: - - DomainComponent=UCL, DomainComponent=AC, - DomainComponent=UK - - -This entry would have in it an AssociatedName attribute with value: - - University College London, GB - - -This example shows a simple case with 1:1 linkage. There are cases -where a domain might be associated with multiple organisations, or an -organisation with multiple domains. - - -12 Conclusions and proposals for evaluation - -Experiments should be undertaken to determine the practicality and -utility of this scheme, in a pilot environment. A possible approach -to this experimentation is described in Appendix A. -Object Identifiers have been assigned for this purpose in the Cosine -and Internet Naming Architecture [BHK91]. - - -References - -[BHK91] P. Barker and S.E. Hardcastle-Kille. The COSINE and Internet - X.500 schema. Request for Comments RFC 1274, Department of - Computer Science, University College London, November 1991. - -[CCI88] The Directory --- overview of concepts, models and services, - December 1988. CCITT X.500 Series Recommendations. - -[Cro82] D.H. Crocker. Standard of the format of ARPA internet text - messages. Request for Comments 822, University of Delaware, - August 1982. - -[HK91] S.E. Hardcastle-Kille. Using the OSI directory to achieve - user friendly naming. Request for Comments in preparation, - Department of Computer Science, University College London, - November 1991. - - - -Hardcastle-Kille Page 12 - - - - -RFC 1279 X.500 and Domains November 1991 - - -[Lar83] J. Larmouth. JNT name registration technical guide, April - 1983. - -[Lin89] J. Linn. Privacy Enhancement for Internet Electronic Mail: - Part 1 --- Message Encipherment and Authentication - Procedures. Request for Comments 1113, Bolt, Beranek, and - Newman, August 1989. - -[Moc87a] P. Mockapetris. Domain names - concepts and facilities. - Request for Comments RFC 1034, USC/Information Sciences - Institute, November 1987. - -[Moc87b] P. Mockapetris. Domain names - implementation and - specification. Request for Comments RFC 1035, - USC/Information Sciences Institute, November 1987. - -[Moc89] P. Mockapetris. DNS encoding of network names and other - types. Request for Comments RFC 1101, USC/Information - Sciences Institute, April 1989. - - -13 Security Considerations - -This memo does not directly address security issues. However, due to -the facilities of X.500, this proposal could lead to a more secure way -to access and manage domain information. - - -14 Author's Address - - Steve Hardcastle-Kille - Department of Computer Science - University College London - Gower Street - WC1E 6BT - England - - Phone: +44-71-380-7294 - - - EMail: S.Kille@CS.UCL.AC.UK - - - - -Hardcastle-Kille Page 13 - - - - -RFC 1279 X.500 and Domains November 1991 - - -A Possible Deployment Approach - -This appendix notes a possible approach to deploying an experiment to -evaluate this mechanism. The following components of a possible -experiment are noted. - - -1. User tool. This will take a domain or mailbox as input. This - will be looked up in the DIT. This tool should be capable of: - - o Attempting to correct user input - - o Helping browsing - - o Looking up information associated with the domain (or mailbox) - and associated name, in particular the manager (of both domain - and associated name) and information on the manager (e.g., - phone number and mailbox). - - o Supply DNS records - - o Handle IN-ADDR.ARPA inverse lookups if supplied with an IP - Address - - o Look up networks - -2. A procedural library to allow user interfaces to make easy use of - these facilities. - -3. Zone transfer tool. This will use the zone transfer protocol to - transfer information between a DSA and Domain Nameserver. When - writing to the DSA, attributes in an entry which are not DNS - records should remain untouched. - -4. Linkage patching tool. When the organisational DIT is - established, associated domain pointers are usually inserted. A - tool can be written to search the DIT and insert the reverse - pointers. - -5. DNS Manager Tool. This will allow user addition of additional - information into the DNS part of the DIT. A standard DUA can - probably be used for this. - - - -Hardcastle-Kille Page 14 - - - - -RFC 1279 X.500 and Domains November 1991 - - -6. Mailbox download tool. This will allow download of local - mailboxes, with pointers to the user entries. - -7. Emulation DNS Server, using the Directory as a database. The - server should maintain a permanent connection to its local DSA. As - there is no OSI bind, the response of this server can be at least - as fast as a normal DNS server. There can be two variants of this - server. - - (a) Using a local DSA as a local database but using DNS - distributed operations. - - (b) Do all lookups in the directory (using Directory Distributed - Operations). - -An initial experiment is straightforward. The Zone Transfer Tool (3) -can be used to download a large part of the DNS space into a single -DSA (there will be some restrictions, as parts of the DNS hierarchy do -not permit zone transfer). This can be used repeatedly to maintain -the information. The linkage patching tool (4) can be used to put in -pointers to parts of the DIT. The user tool can then be used (by all -sites participation the the directory pilot) to look up domain -information. This will allow the utility of the approach to be -evaluated. The manager tool (5) will allow extra information to be -added to parts of the DNS tree. - -The next stage will be to distribute the DNS part of the DIT over -multiple DSAs using Directory distribution techniques. -The emulation DNS Server (7) will be useful to ensure that equivalent -functionality is being offered by the Directory. It can also be used -to examine performance differences. -A final step is to master some parts of the DNS hierarchy in the DIT. -Because of the zone transfer technique, this will be entirely -transparent to the DNS user. Management benefits can then be -examined. - - - - - - - - - - -Hardcastle-Kille Page 15 - diff --git a/doc/rfc/rfc1430.txt b/doc/rfc/rfc1430.txt deleted file mode 100644 index a5d9f6077c..0000000000 --- a/doc/rfc/rfc1430.txt +++ /dev/null @@ -1,1123 +0,0 @@ - - - - - - -Network Working Group S. Hardcastle-Kille -Request for Comments: 1430 ISODE-Consortium - E. Huizer - SURFnet bv - V. Cerf - Corporation for National Research Initiatives - R. Hobby - University of California, Davis - S. Kent - Bolt, Beranek and Newman - February 1993 - - - A Strategic Plan for Deploying an - Internet X.500 Directory Service - -Status of this Memo - - This memo provides information for the Internet community. It does - not specify an Internet standard. Distribution of this memo is - unlimited. - -Abstract - - There are a number of reasons why a new Internet Directory Service is - required. This document describes an overall strategy for deploying - a Directory Service on the Internet, based on the OSI X.500 Directory - Service. It then describes in more detail the initial steps which - need to be taken in order to achieve these goals, and how work - already undertaken by Internet Engineering Task Force Working Groups - (IETF WGs) is working towards these goals. - -Table of Contents - - 1. REQUIREMENTS 2 - 2. SUMMARY OF SOLUTION 3 - 3. INFORMATION FRAMEWORK 3 - 3.1 The Technical Model 3 - 3.2 Extending the Technical Model 4 - 3.3 The Operational Model 5 - 4. NAME ASSIGNMENT 5 - 5. DIRECTORY INFRASTRUCTURE 6 - 5.1 Short Term Requirements 7 - 5.2 Medium Term Requirements 9 - 5.3 Long Term Requirements 9 - 6. DATAMANAGEMENT 9 - 6.1 Legal Issues 10 - 7. TECHNICAL ISSUES 10 - - - -Hardcastle-Kille, Huizer, Cerf, Hobby & Kent [Page 1] - -RFC 1430 X.500 Strategy February 1993 - - - 7.1 Schema 11 - 7.2 Use on the Internet 11 - 7.3 Replication of Knowledge and Data 12 - 7.4 Presentation of Directory Names 13 - 7.5 DSA Naming and MD Structure 13 - 8. SECURITY 13 - 8.1 Directory Provision of Authentication 14 - 8.2 Directory Security 15 - 9. RELATION TO DNS 16 - 10. EXTERNAL CONNECTIONS 16 - 11. REFERENCES 17 - 12. Security Considerations 19 - 13. Authors' Addresses 20 - -1. REQUIREMENTS - - There is substantial interest in establishing a new Directory Service - on the Internet. In the short term, there is pressure to establish - two new services: - - - White Pages lookup of users; - - - Support for X.509 Authentication for a range of applications in - particular for Privacy Enhanced mail [Lin89]. - - In the medium term, there are likely to be many requirements for - Directory Services, including: - - - General resource lookup, for information ranging from committee - structures to bibliographic data; - - - Support of management of the Internet infrastructure, and - integration of configuration information into the higher level - directory; - - - Support of applications on the Internet. For example: - - o Electronic distribution lists; - o Capability information on advanced user agents; - o Location of files and archive services. - - - Support for Mail Handling Systems; Be they RFC-822 based or X.400 - based (IETF MHS-DS WG), e.g.,: - - o Support for routing; - o Info on User agent capabilities; essential for a usage of - Multimedia mail like MIME (Multipurpose Internet Mail - Extensions). - - - -Hardcastle-Kille, Huizer, Cerf, Hobby & Kent [Page 2] - -RFC 1430 X.500 Strategy February 1993 - - - For the longer term, more sophisticated usages of X.500 are possible - extending it into a useful and fast yellow pages service. - -2. SUMMARY OF SOLUTION - - In principle, the current Internet Domain Name System (DNS) could be - used for many of these functions, with appropriate extensions. - However, it is suggested that a higher level of directory service is - needed. It is proposed to establish an Internet Directory Service - based on X.500. This provides appropriate functionality for the - services envisaged and gives flexibility for future extension. This - extension could be achieved either by tracking the evolution of the - OSI Standard or by work specific to the Internet. In practice, it is - likely to be a mixture of both. - - By deploying X.500 in some form on the Internet, a truly global and - universal Directory Service can be built that will provide Internet - users with fast access to all kinds of data. The X.500 Directory - Service in this case may range from a simple white pages service - (information on people and services) to coupling various existing - databases and information repositories in a universal way. - - Currently, several different but cooperating X.500 Directory Services - pilots are taking place on the Internet. These pilots form an - important base for experimenting with this new service. Starting with - these pilots, with the X.500 products arriving on the market today, - and given sufficient funding for the central services described in - this paper an operational X.500 Directory Service can be deployed. - - The final goal of the strategy described in this paper is to deploy a - fully operational Directory Service on the Internet, providing the - functions mentioned in the previous section. - -3. INFORMATION FRAMEWORK - - The most critical aspect of the Directory Service is to establish an - Internet Information Framework. When establishing a sophisticated - distributed directory with a coherent information framework, it - involves substantial effort to map data onto this framework. This - effort is an operational effort and far outweighs the technical - effort of establishing servers and user agents. - -3.1 The Technical Model - - By choosing the X.500 model as a basis for the information framework, - it will also be part of a (future) global information framework. The - key aspects of this model are: - - - - -Hardcastle-Kille, Huizer, Cerf, Hobby & Kent [Page 3] - -RFC 1430 X.500 Strategy February 1993 - - - - A hierarchical navigational system that couples distributed - databases (of various kinds), which allows for management of the - data by the organization/person responsible for the data; - - - Each object in this information structure (called the Directory - Information Tree, DIT) is represented as an entry; - - - Objects are typed by an "object class", which permits multiple - inheritance; - - - An object is described by a set of attributes; - - - Each attribute is typed. Attribute types are hierarchical; - - - Each attribute type has an associated attribute syntax, which may - be generic or shared with other attributes (e.g., Integer Syntax; - Distinguished name Syntax); This allows for representation of - simple attributes (e.g., strings or bitmaps) or complex ones with - detailed structures. - - - Each entry has an unambiguous and unique global name; - - - Alternate hierarchies may be built by use of aliases or pointers of - distinguished name syntax. - - This framework allows for representation of basic objects such as - users within organizations. It is also highly extensible, and so can - be used for a range of other applications. - -3.2 Extending the Technical Model - - In the longer term, the model could be extended to deal with a number - of other requirements which potentially must be met by an Internet - Directory Service. Possible extensions include: - - - Support of ordered attributes (needed by some applications such as - message storage); - - - Extensions to allow unification with management information, - associated with SNMP (Simple Network Management Protocol) [CFSD90] - or other management protocols; - - - Handling of non-hierarchical data in a better manner for searching - and retrieval, whilst retaining the basic hierarchy for management - purposes. This is essentially building a general purpose resource - location service on top of the basic infrastructure. It will need - work on the information model, and not just the access protocols. - - - - -Hardcastle-Kille, Huizer, Cerf, Hobby & Kent [Page 4] - -RFC 1430 X.500 Strategy February 1993 - - - It is noted that although X.500 may not provide the ultimate solution - to information retrieval, it has good potential for solving a lot of - information service related problems. - -3.3 The Operational Model - - To make the Directory Service with a coherent information framework - really operational requires a lot of effort. The most probable - operational model is one where larger organizations on the Internet - maintain their part of the DIT on their own DSA (Directory System - Agent). Smaller organizations will "rent" DSA space from regional - networks or other service providers. Together these DSAs will form - the Internet Directory Service Infrastructure. To couple the various - parts of the DIT that are contained on these Internet DSAs, a special - DSA containing the Root for the naming hierarchy within the DIT has - to be established and maintained. - - The following tasks can be foreseen: - - - Defining the naming hierarchy; See section 4. - - Creating the Directory Infrastructure; See section 5. - - Getting the Data into the directory; and - - Managing the data in the Directory. See section 6. - -4. NAME ASSIGNMENT - - In order to deploy the Internet Directory Service, it is important to - define how the naming hierarchy will be structured. Although the - basic model suggests a simple monolithic "database" containing all of - the Internet's information infrastructure, with a namespace divided - along geographic boundaries, this may not be the definite model that - turns out to be the most appropriate to the Internet. Different - models may evolve according to the needs of the Internet and the - applications used on the Internet (i.e., some parts of the DIT may be - assigned at the root for the Internet). Below this one can envisage - several loosely coupled namespaces each with their own area of - applicability. This should be handled as a part of the general - operation of a directory service. An example of this might be - assignment of a representation of the Domain Namespace under the root - of the DIT. This is further discussed in [BHK91a]. - - However, the core DIT information will be nationally assigned. The - parts of the DIT below country level will be managed differently in - each country. In many countries, registration authorities will be - established according to the OSI Standard [ISO]. This has been done - in some countries by the national ISO member body representative (for - example in the UK by BSI). - - - - -Hardcastle-Kille, Huizer, Cerf, Hobby & Kent [Page 5] - -RFC 1430 X.500 Strategy February 1993 - - - The lower parts of the hierarchy will, in general, be delegated to - organizations who will have control over Name Assignment in that part - of the tree. There is no reason to mandate how to assign this - hierarchy, although it is appropriate to give guidelines. Proposed - solutions to assignment of namespace are given in [BHK92]. - - In North America, there is an alternative approach being developed by - the North American Directory Forum (NADF), which leverages existing - registration mechanisms [For91]. It is not yet clear what form a - final North American Directory Service will take. It is expected that - similar initiatives will be taken in other places, such as Europe. - For the Internet, the Internet Society (ISOC) has been suggested as a - possible Naming Authority. - - A discussion of the main issues involved with representing the Real - World in the Directory Service is part of the work undertaken by the - IETF OSI DS Working Group. - - The core of the Internet Directory will therefore come to exist of a - country based structure with different national naming schemes below - the countries. It is clearly desirable that the Internet Directory - Service follows any evolving national and international hierarchies. - However, this should not be allowed to cause undue delay. The - strategy proposed is to proceed with name assignment as needed, and - to establish interim registration authorities where necessary, taking - practical steps to be aligned with emerging national authorities - wherever possible. - - It is suggested that the Internet Directory Service does two things: - - First, each national part of the Internet DIT namespace should be - delegated to an appropriate organization, which will usually be in - the country of question. Second, the delegated organization should - assign names for that country as part of the Internet Directory - Service. This should be done in a manner which is appropriately - aligned with any emerging local or national service, but does not - unduly delay the deployment of the Internet Directory Service. For - most countries, this will fit in as a natural evolution of the early - directory piloting, where operators of pilots have acted as interim - name registration authorities. - -5. DIRECTORY INFRASTRUCTURE - - To provide access to the Internet Directory Service, an - infrastructure has to be built. Although the technical components of - an X.500 infrastructure are clear: DSAs (that hold the actual data) - and DUAs (that allow users and applications to access the data), a - lot more is needed for deployment of an Internet Directory Service. - - - -Hardcastle-Kille, Huizer, Cerf, Hobby & Kent [Page 6] - -RFC 1430 X.500 Strategy February 1993 - - - The Integrated Directory Services (IDS) Working Group of the IETF is - playing a key role in solving most of the issues that are related to - the building of an appropriate infrastructure. - - Many of the issues cited in this section have come forward out of - interim pilots that have been established on the Internet: - - PSI White Pages Pilot - This is a pilot service which is operating X.500 on the Internet. - In many ways it is operating as an Internet wide pilot. - - FOX - Fielding Operational X.500, a project to explore the development - and interoperability of X.500 implementations. - - Paradise (Piloting A ReseArch DIrectory Service in Europe) - This project has been providing the necessary glue to hold the - various national activities together [Par91]. - -5.1 Short Term Requirements - - - Central Operations. There is a need for a number of operations - to be managed as a service for the whole Internet. These services - are: - - o A root DSA; containing the top-level of the DIT, has to be - provided. Currently, this root DSA is managed by the Paradise - project. - - o Name assignment; Inserting names into the Directory, this has - been discussed in section 4. This could be done in conjunction - with the appropriate Registration Authority or by the - Registration Authority. In most cases it is likely to be the - former, and mechanisms will need to be set up to allow - organizations to get their names installed into the directory, - either direct or through the registration authority. - - o Knowledge management; i.e., the information on "which DSA holds - what part of the DIT, and how can that DSA be accessed". DSAs - will be established by Organizations. There will be a need to - centrally coordinate the management of the knowledge information - associated with these DSAs. This is likely to be coupled to the - name assignment. - - o Knowledge and Data replication; For the Directory to perform - well, knowledge and data high up in the DIT must be - significantly replicated. A service must be provided to make - replicated information available to DSAs that need it. - - - -Hardcastle-Kille, Huizer, Cerf, Hobby & Kent [Page 7] - -RFC 1430 X.500 Strategy February 1993 - - - It is suggested that for the time being, Paradise should be used - as the initial basis for handling the top-level of the DIT and for - provision of the central services. However, the services mentioned - above need to be provided at a national level for every - participating country in the Internet Directory Service. Whenever - an organization starts a new country branch of the DIT in the - Internet Directory Service the central operations will have to - help out to make sure that these services will be properly - installed on a national level. - - - An effective service will need to have sufficient implementations, - in order to give full coverage over different hardware and software - platforms, and to demonstrate openness. The recent Directory - Information Services (pilot) Infrastructure Working Group's (DISI) - Survey of Directory Implementations suggests that there will not be - a problem here. This provides a list of available X.500 - implementations and their capabilities [LW91]. - - - An executive summary, necessary to convince the management of - computer centers to invest manpower into setting up a X.500 - Directory Service. This is provided by DISI [WR92]. - - - Due to the possible different and rather independent structured - namespaces that can be envisaged in the DIT for different purposes, - DUAs will have to be "tuned intelligently" for the applications that - they are used for. - - - To allow users easy access to the Internet Directory Service even - from low powered workstations, a lightweight protocol has to be - developed over TCP/IP. Already two private protocols that do this - have been developed: The Michigan DIXIE protocol [HSB91] and the PSI - Directory Assistance Service [Ros91]. The IETF OSI Directory - Services Working Group (OSI-DS WG) is currently working on a - standard lightweight protocol called LDAP. - - - Although the Internet Directory Service does not have to make any - mandatory requirements about the use of lower layers, it is noted - that the use of STD 35, RFC 1006 to allow use of OSI applications on - top of TCP/IP is essential for deployment in the Internet. Other - stacks like the ones using CLNS, CONS and X.25(80) will probably - also be deployed in parts of the Internet. DSAs with different - stacks will be linked through use of either application level relays - (chaining) or Transport Service bridges. - - - There are multiple issues that are not dealt with (properly) in the - X.500 standard and thus prevent the building of an Internet - Directory service. Intermediate solutions for these issues have to - be established in an "open" way. The results will have to be - - - -Hardcastle-Kille, Huizer, Cerf, Hobby & Kent [Page 8] - -RFC 1430 X.500 Strategy February 1993 - - - deployed as well as to be fed back into the relevant standard - committees. The IETF OSI-DS WG deals with these issues. Section 7 - describes several of these issues. - - - Site support. The IETF IDS WG is looking at providing the necessary - documentation to help with the provision of support for Directory - users at participating sites. - -5.2 Medium Term Requirements - - - Enhanced performance is necessary to allow for a real global usage; - - - The schema has to be extended to allow for various kinds of data, - e.g.,: - - o NIC data; - o Resource location; - - - Support for Internet Message Handling services (RFC-822, MIME and - X.400). This work is already undertaken by the IETF MHS-DS WG. - -5.3 Long Term Requirements - - - To make sure that X.500 evolves into an operational service, it is - essential to track its evolution, and to feed back into the - evolution process. - - - Interface existing RDBMS into the Directory Service. - - - To increase the performance of the directory, and thereby making it - useful for an even wider range of applications (e.g., policy based - routing), a lightweight protocol for access and system usage is - needed. - -6. DATAMANAGEMENT - - The whole of the Directory Infrastructure won't stand much chance - without proper datamanagement of the data contained within the DIT. - Procedures need to be established to assure a certain Level of - Quality of the data contained in the DIT. - - Due to the very nature of X.500, the management of the data is - distributed over various sources. This has the obvious advantage that - the data will be maintained by the owner of the data. It does - however, make it quite impossible to describe one single procedure - for datamanagement. - - - - - -Hardcastle-Kille, Huizer, Cerf, Hobby & Kent [Page 9] - -RFC 1430 X.500 Strategy February 1993 - - - For the Internet Directory Service, guidelines will have to be - developed (by the IETF IDS WG), to help organizations that start with - deployment of X.500 on how to manage data in their part of the DIT. - The guidelines should describe a minimum level of quality that has to - be supplied to make the service operational. The IETF OSI-DS WG will - initiate a pilot on Quality of Service parameters in the Directory, - that will be of use. - - Pilot datamanagement projects will have to be done (e.g., existing - databases should be connected to the Internet Directory Service). - Tools that are developed to achieve this should be made available to - the Internet community for possible future use. - -6.1 Legal Issues - - Most countries connected to the Internet have some sort of law that - dictates how data on people can and cannot be made available. These - laws deal with privacy and registration issues, and will differ from - country to country. It is suggested that each of the national - organizations within the Internet that manages the Internet Directory - Services master for that country, undertake some research as to the - applicability of laws within that country on data made public through - use of X.500. - - In the mean time, a general "User Bill of Rights" should be - established to indicate what the proper use of the Internet Directory - Service is. This "Bill of Rights" could be drafted by the IETF IDS - WG. As a basis, the NADF "User Bill of Rights" [For92] can be used. - -7. TECHNICAL ISSUES - - The IETF has established the OSI-DS WG. The major component of the - initial work of this group is to establish a technical framework for - deploying a Directory Service on the Internet, making use of the - X.500 protocols and services [CCI88b]. This section describes the - work already done by this working group, which has been implicitly - focused on the technical infrastructure needed to deploy the Internet - Directory service. - - The OSI Directory Standards do not yet contain sufficient specifics - to enable the Internet Directory Service to be built. Full openness - and interoperability are a key goal, so we may need Internet specific - agreements, at least until the ISO standards are more complete. This - section notes areas where the standards do not have sufficient - coverage, and indicates the RFCs which have been written to overcome - these problems. - - The work is being limited to (reasonably well) understood issues. - - - -Hardcastle-Kille, Huizer, Cerf, Hobby & Kent [Page 10] - -RFC 1430 X.500 Strategy February 1993 - - - This means that whilst we will attempt to solve a wider range of - problems, not all potential requirements will necessarily be met. - - The technical work is done in conjunction with the RARE WG on Network - Application Support WG (formerly RARE WG3). The IETF WGs and the RARE - WG have a common technical mailing list. It is intended that this - will lead to a common European and North American technical approach. - -7.1 Schema - - A Directory needs to be used in the context of an Information - Framework. The standard directory provides a number of a attributes - and object classes to enable basic operation. It is certain that the - Internet community will have requirements for additional attributes - and object classes. There is a need to establish a mechanism to - register such information. - - Pilots in the European RARE Community and the US PSI White Pages - Pilot have based their information framework on the THORN and RARE - Naming Architecture. This architecture should be used for the - Internet Directory Service, in conjunction with COSINE based services - in Europe. A revised version of the Naming Architecture, with a - mechanism for registration of new attributes and object classes, has - been released as RFC 1274 [BHK91a]. - -7.2 Use on the Internet - - It is a recognized policy on the Internet to deploy OSI Applications - over non-OSI lower layers (such as STD 35, RFC 1006) [RC87]. This - policy allows deployment of OSI Applications before an OSI lower - layer infrastructure has been deployed. Thus, the Internet Directory - Service will decouple deployment of the OSI Directory from deployment - of the OSI lower layers. As the Internet Directory service will - extend into the far corners of the Internet namespace, where the - underlying technology is not always TCP/IP, the Internet Directory - Service will not make any mandatory requirements about use of lower - layers. When configuring the Internet Directory Services, variations - in the lower layers must be considered. The following options are - possible: - - - Operation on top of TCP/IP using a lightweight protocol. - - - Operation over TCP/IP using STD 35, RFC 1006. This is a practical - requirement of deployment at very many Internet sites, and is the - basis of the existing services. It is highly recommended that all - participating DSAs support this stack. - - - Use of OSI Network Service (Connection Oriented or Connectionless). - - - -Hardcastle-Kille, Huizer, Cerf, Hobby & Kent [Page 11] - -RFC 1430 X.500 Strategy February 1993 - - - - X.25(80) will probably not be used in the core infrastructure of - the Internet Directory Service, but is the basis of some European - activities. It may be needed later to interconnect with US - commercial systems not on the Internet. There will be a practical - need to interwork with DSAs which only support this stack. - - This approach has the following implications: - - 1. There is a need to represent TCP/IP addresses within OSI Network - Addresses. This is specified in RFC 1277 [HK91a]. - - 2. It will be desirable to have a uniform method to present Network - Addresses of this style. Therefore, a string representation of - presentation addresses is specified in RFC 1278 [HK91d]. - - 3. This approach leads to the situation where not all DSAs can - communicate directly due the different choice of lower layers. - This is already a practical result of many European sites operating - DSAs over X.25. When the Internet Directory Service is deployed, - the issue of which DSAs operate which stacks must be considered in - order to achieve a coherent service. In particular, there may be a - need to require DSAs that serve parts higher up in the DIT to serve - multiple stacks. This will be tackled as an operational issue. - - 4. There may be a requirement to extend the distributed operations, so - that there is no requirement for full connectivity (i.e., each DSA - supports each stack). A solution to this problem, by defining - "relay DSAs" is specified in RFC 1276 [HK91b]. - -7.3 Replication of Knowledge and Data - - There are a number of requirements on replication, both of data (the - actual information on objects in the directory) and knowledge (the - information on where do I find what data) information, which must be - met before an Internet Directory can be deployed. The 1988 standard - cannot be used as is, because it does not deal with replication or - caching. This leads to serious problems with performance. There is a - partial solution available in the 1992 version of the standard, - however there are no products available yet that implement this - solution. These issues are discussed in more detail in RFC 1275 - [HK91c]. - - As it took too long for 1992 implementations to arrive to be of any - help to the already rapidly growing pilot that urgently needed a - solution, an option was chosen to use a simple interim approach as - defined in RFC 1276. It will be clearly emphasized that this is an - interim approach, which will be phased out as soon as the appropriate - standards are available and stable implementations are deployed. The - - - -Hardcastle-Kille, Huizer, Cerf, Hobby & Kent [Page 12] - -RFC 1430 X.500 Strategy February 1993 - - - interim approach is based on the approach used in the QUIPU - Implementation and it is widely deployed in the existing pilots. - -7.4 Presentation of Directory Names - - The standard does not specify a means to present directory names to - the user. This is seen as a serious deficiency, and a standard for - presenting directory names is required. For Distinguished Names, a - string representation is defined in [HK92a]. However, as the - distinguished name is not very friendly for the user, a more user - oriented specification of a standard format for representing names, - and procedures to resolve them is chosen on the Internet, and is - specified in [HK92b]. - -7.5 DSA Naming and MD Structure - - There are some critical issues related to naming of DSAs and the - structure of Directory Management Domains. The main issues are: - - - It is hard to achieve very high replication of knowledge - information as this is very widely spread; - - - There is a need to give DSAs more reasonable names, which will - contain an indication on the role of the DSA; This is necessary for - DSAs high up the DIT. - - - There is too much DIT clutter in the current pilots; - - - There is no real concept of a DMD (Directory Management Domain) - authority. - - These will be significant as the directory increases in size by - orders of magnitude. The IETF OSI-DS WG is working to develop a - solution in this area. - -8. SECURITY - - A Directory can be an important component in the overall provision of - security in a distributed system environment, especially when - public-key cryptographic technology is employed. The directory can - serve as a repository for authentication information, which, in turn, - forms the basis of a number of OSI Authentication Services (e.g., - X.400) and non-OSI Services (e.g., privacy-enhanced mail, PEM). The - directory may also use this and other stored authentication - information to provide a wide range of security Services used by the - Directory system itself. - - - - - -Hardcastle-Kille, Huizer, Cerf, Hobby & Kent [Page 13] - -RFC 1430 X.500 Strategy February 1993 - - -8.1 Directory Provision of Authentication - - The directory will be used to provide X.509 strong authentication. - This places minimal requirements on the directory. To use this - infrastructure, users of authentication services must have access to - the directory. In practice, this type of authentication can be - deployed only on a limited scale without use of a directory, and so - this provision is critical for applications such as Privacy Enhanced - Mail [Lin93]. The PEM development is considering issues relating to - deploying Certification Authorities, and this discussion is not - duplicated here. - - PEM defines a key management architecture based on the use of - public-key certificates, in support of the message encipherment and - authentication procedures defined in [Lin93]. The PEM certificate - management design [Ken93] makes use of the authentication framework - defined by X.509. In this framework, as adopted by PEM, a - "certification authority" representing an organization applies a - digital signature to a collection of data consisting of a user's - public component, various information that serves to identify the - user, and the identity of the organization whose signature is - affixed. This establishes a binding between these user credentials, - the user's public component and the organization which vouches for - this binding. The resulting, signed, data item is called a - certificate. The organization identified as the certifying authority - for the certificate is the "issuer" of that certificate. The format - of the certificate is defined in X.509. - - In signing the certificate, the certification authority vouches for - the user's identification, in the context specified by the identity - of the issuer. Various types of organization may issue certificates, - including corporate, educational, professional, or governmental - entities. Moreover, these issuers may operate under different - certification policies, so that not all certificates may be equally - credible (i.e., some certificates may be more trustworthy as accurate - identifiers of users, organizations, mailing lists, etc). The PEM - certificate management design allows for this diversity of - certification policies, while ensuring that any certificate can be - traced unambiguously to the policy under which it was issued. - - The digital signature is affixed on behalf of that organization and - is in a form which can be recognized by all members of the privacy- - enhanced electronic mail community. This ability to universally - verify any PEM certificate results because the PEM certification - design is a singly rooted tree, in which the Internet Society acts as - the root. Once generated, certificates can be stored in directory - servers, transmitted via unsecure message exchanges, or distributed - via any other means that make certificates easily accessible to - - - -Hardcastle-Kille, Huizer, Cerf, Hobby & Kent [Page 14] - -RFC 1430 X.500 Strategy February 1993 - - - message originators, without regard for the security of the - transmission medium. - -8.2 Directory Security - - A number of security services are possible with the directory: - - Peer Authentication at Bind - Authentication (one or two way) between DUA/DSA and DSA/DSA, - established during the bind operation. This authentication may be - provided using simple passwords (not recommended), one-way hashed - passwords (more secure), or via public key cryptography (most - secure). The various authentication options are specified in - X.500(88), but most existent implementations implement only simple - password authentication. - - Per-operation Authentication and Integrity - This is usually used to identify the DUA originating an operation - to the Directory (e.g., to authenticate prior to data - modification). It may also be used to verify the identity of the - DSA which provided data in a response to the user. In both - examples, the integrity of the data also is ensured through the - use of digital signatures. This is specified in X.500(88), but not - yet widely implemented. - - Single Entry Access Control - This is used to control which users (DUAs) can access and modify - data within an entry. This is specified in X.500(92) and most DSA - implementations provide this function. - - Multiple Entry Access Control - This is used to control search and list operations, in order to - allow location of information by searching, but to deter - "trawling" of information and organizational structure. Usually, - these access controls are limited in their ability to prevent - trawling because of the conflicting goal of allowing a certain - level of legitimate browsing in support of "white pages" - functionality. - - Service Authorization - This allows DSAs to control service in a data independent manner, - based on peer authentication. For example, one might prevent - students from making non-local queries, while permitting such - queries by faculty and staff. - - - - - - - -Hardcastle-Kille, Huizer, Cerf, Hobby & Kent [Page 15] - -RFC 1430 X.500 Strategy February 1993 - - - Security Policy - This term encompasses the security goals for which data access - control, service authorization, and authentication mechanisms are - used to implement. For example, a local security policy might - require that all directory database modifications employ strong - authentication and originate from a computer at a known (local) - location. - - Data Confidentiality - The directory does not include explicit features to protect the - confidentiality of data while in transit (e.g., between a DUA and - DSA or between DSAs). Instead, it is assured that lower layer - security protocols or other local security facilities will be - employed to provide this security service. Ongoing work on - adaptation of the Network Layer Security Protocol (NLSP) is a - candidate for provision of this security service with directories. - - There is no specification of any Internet-wide security policy for - directories, nor are there currently any security mechanisms required - of all directories. Deployment of a directory could be based on a - variety of policies: - - - Read only system, containing only public data and restricted to - local modification. - - - Use of X.509 authentication, and private access control mechanisms - (this will not allow open access control management, but this is not - seen as a fundamental problem). - - It will be important to understand if global Internet requirements - for minimum essential directory security mechanisms will be required - to promote widespread use of directories. We recommend that an - informational RFC be written to analyze this issue, with an - operational policy guidelines or applicability statement RFC to - follow. - -9. RELATION TO DNS - - It is important to establish the relationship between the proposed - Internet Directory, and the existing Domain Name System. An - Experimental Protocol RFC (RFC 1279) proposes a mapping of DNS - information onto the Directory. Experiments should be conducted in - this area [HK91e]. - -10. EXTERNAL CONNECTIONS - - It will be important for this activity to maintain suitable external - liaisons. In particular to: - - - -Hardcastle-Kille, Huizer, Cerf, Hobby & Kent [Page 16] - -RFC 1430 X.500 Strategy February 1993 - - - Other Directory Services and Directory Pilots - - To ensure a service which is coherent with other groups building - X.500 services. e.g.,: - - - Paradise - - NADF - - FOX - - PSI White Pages - - Standards Bodies - - To feed back experience gained from this activity, so that the - next round of standards meets as many of the Internet requirements - as possible. e.g.,: - - - CCITT/ISO - - RARE WG-NAS - - EWOS/OIW - - ETSI - -11. REFERENCES - - - [BHK91a] Barker, P., and S. Hardcastle-Kille, "The COSINE and - Internet X.500 Schema", RFC 1274, Department of Computer - Science, University College London, November 1991. - - [BHK92] Barker, P., and S. Hardcastle-Kille, "Naming Guidelines for - Directory Pilots", RFC 1384, Department of Computer Science, - University College London, ISODE Consortium, January 1993. - - [CCI88a] The Directory --- authentication framework, December 1988. - CCITT Recommendation X.509. - - [CCI88b] The Directory --- overview of concepts, models and services, - December 1988. CCITT X.500 Series Recommendations. - - [CCI90] The Directory --- part 9 --- replication, October 1990. - ISO/IEC CD 9594-9 Ottawa output. - - [CFSD90] Case, J., Fedor, M., Schoffstall, M., and J. Davin, "A - Simple Network Management Protocol", STD 15, RFC 1157, - SNMP Research, Performance Systems International, MIT - Laboratory for Computer Science, May 1990. - - - - - - -Hardcastle-Kille, Huizer, Cerf, Hobby & Kent [Page 17] - -RFC 1430 X.500 Strategy February 1993 - - - [For91] The North American Directory Forum, "A Naming Scheme - for C=US", RFC 1255, NADF, September 1991. - Also NADF-175. (See also RFC 1417.) - - [For92] The North American directory Forum, "User Bill of Rights - for Entries and Listing in the Public Directory", RFC 1295, - NADF, January 1992. (See also RFC 1417.) - - [HK91a] Hardcastle-Kille, S., "Encoding network addresses to - support operation over non-OSI lower layers", RFC 1277, - Department of Computer Science, University College London, - November 1991. - - [HK91b] Hardcastle-Kille, S., "Replication and distributed - operations extensions to provide an internet directory - using X.500", RFC 1276, Department of Computer Science, - University College London, November 1991. - - [HK91c] Hardcastle-Kille, S., "Replication requirement to - provide an internet directory using X.500", RFC 1275, - Department of Computer Science, University College - London, November 1991. - - [HK91d] Hardcastle-Kille, S., "A string encoding of presentation - address", RFC 1278, Department of Computer Science, - University College London, November 1991. - - [HK91e] Hardcastle-Kille, S., "X.500 and domains", RFC 1279, - Department of Computer Science, University College - London, November 1991. - - [HK92a] Hardcastle-Kille, S., "A string representation of - Distinguished Names", Department of Computer Science, - University College London, Work in Progress. - - [HK92b] Hardcastle-Kille, S., "Using the OSI directory to achieve - user friendly naming", Department of Computer Science, - University College London, Work in Progress. - - [HSB91] Howes, R., Smith, M., and B. Beecher, "DIXIE Protocol - Specification", RFC 1249, University of Michigan, - July 1991. - - [ISO] Procedures for the operation of OSI registration - authorities --- part 1: general procedures. ISO/IEC 9834-1. - - - - - - -Hardcastle-Kille, Huizer, Cerf, Hobby & Kent [Page 18] - -RFC 1430 X.500 Strategy February 1993 - - - [Ken93] Kent, S., "Privacy Enhancement for Internet Electronic - Mail: Part II - Certificate-based Key Management, RFC 1422, - BBN, February 1993. - - [Kil88] Kille, S., "The QUIPU Directory Service", In IFIP WG 6.5 - Conference on Message Handling Systems and Distributed - Applications, pages 173--186. North Holland Publishing, - October 1988. - - [Kil89] Kille, S., "The THORN and RARE Naming Architecture", - Technical report, Department of Computer Science, - University College London, June 1989. THORN Report UCL-64 - (version 2). - - [Lin93] Linn, J., "Privacy Enhancement for Internet Electronic - Mail: Part I - Message Encryption and Authentication - Procedures", RFC 1421, February 1993. - - [LW91] Lang, R., and R. Wright, "A Catalog of Available X.500 - Implementations", FYI 11, RFC 1292, SRI International, - Lawrence Berkeley Laboratory, January 1992. - - [Lyn91] Lynch, C., "The Z39.50 information retrieval protocol: An - overview and status report", Computer Communication Review, - 21(1):58--70, January 1991. - - [Par91] Paradise International Report, Cosine. Paradise project, - Department of Computer Science, University College London. - November 1991. - - [RC87] Rose, M., and D. Cass, "ISO Transport Services on - top of the TCP", STD 35, RFC 1006, Northrop Corporation - Technology Center, May 1987. - - [Ros91] Rose, M., "Directory Assistance Service", RFC 1202, - Performance Systems International, February 1991. - - [WR92] Weider, C., and J. Reynolds, "Executive Introduction to - Directory Services Using the X.500 Protocol", FYI 13, - RFC 1308, ANS, ISI, March 1992. - -12. Security Considerations - - Security issues are discussed in Section 8. - - - - - - - -Hardcastle-Kille, Huizer, Cerf, Hobby & Kent [Page 19] - -RFC 1430 X.500 Strategy February 1993 - - -13. Authors' Addresses - - Steve Hardcastle-Kille - ISODE Consortium - PO box 505 - SW11 1DX London - England - Phone: +44-71-223-4062 - EMail: S.Kille@isode.com - - - Erik Huizer - SURFnet bv - PO box 19035 - 3501 DA Utrecht - The Netherlands - Phone: +31-30 310290 - Email: Erik.Huizer@SURFnet.nl - - - Vinton Cerf - Corporation for National Research Initiatives - 1895 Preston White Drive, Suite 100 - Reston, VA 22091 - Phone: (703) 620-8990 - EMail: vcerf@cnri.reston.va.us - - - Russ Hobby - University of California, Davis - Computing Services - Surge II Room 1400 - Davis, CA 95616 - Phone: (916) 752-0236 - EMail: rdhobby@ucdavis.edu - - - Steve Kent - Bolt, Beranek, and Newman - 50 Moulton Street - Cambridge, MA 02138 - Phone: (617) 873-3988 - EMail: skent@bbn.com - - - - - - - - -Hardcastle-Kille, Huizer, Cerf, Hobby & Kent [Page 20] - \ No newline at end of file diff --git a/doc/rfc/rfc1617.txt b/doc/rfc/rfc1617.txt deleted file mode 100644 index ce57779844..0000000000 --- a/doc/rfc/rfc1617.txt +++ /dev/null @@ -1,1571 +0,0 @@ - - - - - - -Network Working Group P. Barker -Request for Comments: 1617 University College London -RARE Technical Report: 11 S. Kille -Obsoletes: 1384 ISODE Consortium -Category: Informational T. Lenggenhager - SWITCH - May 1994 - - - Naming and Structuring Guidelines for X.500 Directory Pilots - -Status of this Memo - - This memo provides information for the Internet community. This memo - does not specify an Internet standard of any kind. Distribution of - this memo is unlimited. - -Abstract - - Deployment of a Directory will benefit from following certain - guidelines. This document defines a number of naming and structuring - guidelines focused on White Pages usage. Alignment to these - guidelines is recommended for directory pilots. The final version of - this document will replace RFC 1384. - -Table of Contents - - 1. Introduction 2 - 2. DIT Structure 3 - 2.1. Structure Rules 3 - 2.2. The Top Level of the DIT 3 - 2.3. Countries 4 - 2.4. Organisations 5 - 2.4.1. Directory Manager, Postmaster & Secretary 5 - 2.4.2. Depth of tree 6 - 2.4.3. Real World Organisational Structure 7 - 2.5. Multi-National Organisations 7 - 2.5.1. The Multi-National as a Single Entity 7 - 2.5.2. The Multi-National as a Loose Confederation 8 - 2.5.3. Loosely Linked DIT Sub-Trees 9 - 2.5.4. Summary of Advantages and Disadvantages of the - Above Approaches 9 - 3. Naming Style 10 - 3.1. Multi-Component Relative Distinguished Names 11 - 3.2. National Guidelines for Naming 11 - 3.3. Naming Organisation and Organisational Unit Names 11 - 3.4. Naming Human Users 12 - 3.5. Application Entities 13 - - - -RARE Working Group on Network Applications Support (WG-NAP) [Page 1] - -RFC 1617 Naming and Structuring Guidelines for X.500 May 1994 - - - 4. Attribute Values 13 - 4.1. Basic Attribute Syntaxes 13 - 4.1.1. Printable String 14 - 4.1.2. IA5 String - T.50 14 - 4.1.3. Teletex String - T.61 14 - 4.1.4. Case Ignore String 14 - 4.1.5. Distinguished Name 14 - 4.2. Languages & Transliteration 14 - 4.2.1. Languages other than English 15 - 4.2.2. Transliteration 15 - 4.3. Access control 15 - 4.4. Selected Attributes 16 - 4.4.1. Personal Attributes 16 - 4.4.2. Organisational Attributes 18 - 4.4.3. Local Attributes 19 - 4.4.4. Miscellaneous Attributes 20 - 4.4.5. MHS Attributes 21 - 4.4.6. Postal Attributes 21 - 4.4.7. Telecom Attributes 22 - 5. Miscellany 22 - 5.1. Schema consistency of aliases 22 - 5.2. Organisational Units 23 - 6. References 23 - 7. Security Considerations 23 - 8. Authors' Addresses 24 - 9. Appendix - Example Entries 25 - -1. Introduction - - The intended audience for this document are mainly data managers - using X.500 Directory Services. With the help of these guidelines it - should be easier for them to define the structure for the part of the - Directory Information Tree they want to model, e.g., the - representation of their organisation in the Directory. In addition, - decisions like which data elements to store for each kind of entry - shall be supported. - - These guidelines concentrate mainly on the White Pages use of the - Directory, the X.500 application with most operational experience - today, nonetheless many recommendations are also valid for other - applications of the Directory. - - As a pre-requisite to this document, it is assumed that the COSINE - and Internet X.500 Schema is followed [1]. - - - - - - - -RARE Working Group on Network Applications Support (WG-NAP) [Page 2] - -RFC 1617 Naming and Structuring Guidelines for X.500 May 1994 - - -2. DIT Structure - - The majority of this document is concerned with DIT structure, naming - and the usage of attributes for organisations, organisational units - and personal entries. - - This section briefly notes five other key issues. - -2.1 Structure Rules - - A DIT structure is suggested in Annex B of X.521 [2], and it is - recommended that Directory Pilots for White Pages services should - follow these guidelines. Some simple restrictions should be applied, - as described below. For further usage of the Directory like e-mail - routing with the Directory or storage of network information in the - Directory it will be necessary to follow the guidelines specified in - the respective documents. - - One of the few exceptions to the basic DIT structure is, that - international organisations will be stored immediately under the root - of the tree. Multi-national organisations will be stored within the - framework outlined, but with some use of aliases and attributes such - as seeAlso to help bind together the constituent parts of these - organisations. This is discussed in more detail in section 2.5. - - A general rule for the depth of a subtree is as follows: When a - subtree is mainly accessed via searching, it should be as flat as - possible to improve the performance, when the access will be mainly - through read operations, the depth of the subtree is not a - significant parameter for performance. - -2.2 The Top Level of the DIT - - The following information will be present at the top level of the - DIT: - - Participating Countries - - According to the standard the RDN is the ISO 3166 country code. In - addition, the entries should contain suitable values of the - friendlyCountryName attribute specified in RFC 1274. Use of this - attribute is described in more detail in section 4.4.4. - - International Organisations - - An international organisation is an organisation, such as the - United Nations, which inherently has a brief and scope covering - many nations. Such organisations might be considered to be - - - -RARE Working Group on Network Applications Support (WG-NAP) [Page 3] - -RFC 1617 Naming and Structuring Guidelines for X.500 May 1994 - - - supra-national and this, indeed, is the raison-d'etre of such - organisations. Such organisations will almost all be governmental - or quasi-governmental. A multi-national organisation is an - organisation which operates in more than one country, but is not - supra-national. This classification includes the large commercial - organisations whose production and sales are spread throughout a - large number of countries. - - International organisations may be registered at the top level. - This will not be done for multi-national organisations. Currently - three organisations are registered so far: Inmarsat, Internet and - North Atlantic Treaty Organization. - - Localities - - A few localities will be registered under the root. The chief - purpose of these locality entries is to provide a "natural" parent - node for organisations which are supra-national, and yet which do - not have global authority in their particular field. Such - organisations will usually be governmental or quasi-governmental. - Example localities might include: Europe, Africa, West Indies. - Example organisations within Europe might include: European Court - of Justice, European Space Agency, European Commission. - - DSA Information - - Some information on DSAs may be needed at the top level. This - should be kept to a minimum. - - The only directory information for which there is a recognised top - level registration authority is countries. Registration of other - information at the top level may potentially cause problems. At this - stage, it is argued that the benefit of limiting additional top level - registrations outweighs these problems. However, this potential - problem should be noted by anyone making use of such a registration. - -2.3 Countries - - The national standardisation bodies will define national guidelines - for the structure of the national part of the DIT. In the interim, - the following simple structure should suffice. The country entry will - appear immediately beneath the root of the tree. Organisations which - have national significance should have entries immediately beneath - their respective country entries. Smaller organisations which are - only known in a particular locality should be placed underneath - locality entries representing states or similar geographical - divisions. Entry for private persons will be listed under the - locality entries. An example plan evolving for the US is the work of - - - -RARE Working Group on Network Applications Support (WG-NAP) [Page 4] - -RFC 1617 Naming and Structuring Guidelines for X.500 May 1994 - - - the North American Directory Forum [3]. Another example is the - organisation of the X.500 namespace as standardized in Australia [4]. - -2.4 Organisations - - Large organisations will probably need to be sub-divided by - organisational units to help in the disambiguation of entries for - people with common names. Entries for people and roles will be stored - beneath organisations or organisational units. - - The organisation entry itself shall contain the information necessary - to contact the organisation: for example, postal address, telephone - and fax numbers. - - Although the structure of organisations often changes considerably - over time, the aim should be to minimise the number of changes to the - DIT. Note that renaming a superior, department entry has the effect - of changing the DN of all subordinate entries. This has an - undesirable impact on the service for several reasons. Alias entries - and certain attributes or ordinary entries such as seeAlso, secretary - and roleOccupant use DNs to maintain links with other entries. These - references are one-way only and the Directory standard offers no - support to automatically update all references to an entry once its - DN changes. - -2.4.1 Directory Manager, Postmaster & Secretary - - Similar to messaging, where every domain has its postmaster address - it is highly recommended that each organisation in the X.500 - Directory has two entries: Postmaster and Directory Manager. In - addition, Secretary entries for an organisation and its units should - be listed. If this guidance is followed, users will benefit because - it will be straightforward to find the right contacts for questions - or problems with the service. - - These entries should use the object class organizationalRole with the - roleOccupant attributes containing the distinguished names of the - persons in charge of this role. The values - - CN=Directory Manager - - CN=Postmaster - - CN=Secretary - - should be added as additional values whenever another language than - English is used for the name of the entries. - - - - -RARE Working Group on Network Applications Support (WG-NAP) [Page 5] - -RFC 1617 Naming and Structuring Guidelines for X.500 May 1994 - - -2.4.2 Depth of tree - - The broad recommendation for White Pages is that the DIT should be as - flat as possible. A flat tree means that Directory names will be - relatively short, and probably somewhat similar in length and - component structure to paper mail addresses. A deep DIT would imply - long Directory names, with somewhat arbitrary component parts, with a - result which it is argued seems less natural. Any artificiality in - the choice of names militates against successful querying. - - A presumption behind this style of naming is that most querying will - be supported by the user specifying convenient strings of characters - which will be mapped onto powerful search operations. The - alternative approach of the user browsing their way down the tree and - selecting names from large numbers of possibilities may be more - appropriate in some cases, and a deeper tree facilitates this. - However, these guidelines recommend a shallow tree, and implicitly a - search oriented approach. - - It may be considered that there are two determinants of DIT depth: - first, how far down the DIT an organisation is placed; second, the - structure of the DIT within organisations. - - The structure of the upper levels of the tree will be determined in - due course by various registration authorities, and the pilot will - have to work within the given structure. However, it is important - that the various pilots are cognisant of what the structures are - likely to be, and move early to adopt these structures. - - The other principal determinant of DIT depth is whether an - organisation splits its entries over a number of organisational - units, and if so, the number of levels. The recommendation here is - that this sub-division of organisations is kept to a minimum. A - maximum of two levels of organisational unit should suffice even for - large organisations. Organisations with only a few tens or hundreds - of employees should strongly consider not using organisational units - at all. It is noted that there may be some problems with choice of - unique RDNs when using a flat DIT structure. Multi-component RDNs can - alleviate this problem: see section 3.1. The standard X.521 - recommends that an organizationalUnitName attribute can also be used - as a naming attribute to disambiguate entries [2]. Further - disambiguation may be achieved by the use of a personalTitle or - userId attribute in the RDN. - - - - - - - - -RARE Working Group on Network Applications Support (WG-NAP) [Page 6] - -RFC 1617 Naming and Structuring Guidelines for X.500 May 1994 - - -2.4.3 Real World Organisational Structure - - Another aspect on designing the DIT structure for an organisation is - the administrative structure within a company. Using the same - structure in the DIT might help in distributing maintenance authority - to the different units. Please note comments on the stability of the - DIT structure in section 2.4. - -2.5 Multi-National Organisations - - The standard says that only international organisations may be placed - under the root of the DIT. This implies that multi-national - organisations must be represented as a number of separate entries - underneath country or locality entries. This structure makes it more - awkward to use X.500 within a multi-national to provide an internal - organisational directory, as the data is now spread widely throughout - the DIT, rather than all being grouped within a single sub-tree. - - Many people have expressed the view that this restriction is a severe - limitation of X.500, and argue that the intentions of the standard - should be ignored in this respect. This note argues, though, that the - standard should be followed. - - No attempt to precisely define multinational organisation is essayed - here. Instead, the observation is made that the term is applied to a - variety of organisational structures, where an organisation operates - in more than one country. This suggests that a variety of DIT - structures may be appropriate to accommodate these different - organisational structures. This document suggests three approaches, - and notes some of the characteristics associated with each of these - approaches. - - Before considering the approaches, it is worth bearing in mind again - that a major aim in the choice of a DIT structure is to facilitate - querying, and that approaches which militate against this should be - avoided wherever possible. - -2.5.1 The Multi-National as a Single Entity - - In many cases, a multi-national organisation will operate with a - highly centralised structure. While the organisation may have large - operations in a number of countries, the organisation is strongly - controlled from the centre and the disparate parts of the - organisation exist only as limbs of the main organisation. In such a - situation, the model shown in figure 1 may be the best choice. - - - - - - -RARE Working Group on Network Applications Support (WG-NAP) [Page 7] - -RFC 1617 Naming and Structuring Guidelines for X.500 May 1994 - - - ROOT - - / | \ - / | \ - - C=GB C=FR C=US - - / | \ - / | \ - - O=MultiNat---->O=MultiNat<----O=MultiNat - - / | \ - / | \ - / | \ - - l=abc ou=def l=fgi - - ---> means "alias to" - - Figure 1: The multi-national as a single entity - - The organisation's entries all exist under a single sub-tree. The - organisational structure beneath the organisation entry should - reflect the perceived structure of the organisation, and so no - recommendations on this matter can be made here. To assist the person - querying the directory, alias entries should be created under all - countries where the organisation operates. - -2.5.2 The Multi-National as a Loose Confederation - - Another common model of organisational structure is that where a - multi-national consists of a number of national entities, which are - in large part independent of both sibling national entities, and of - any central entity. In such cases, the model shown in Figure 2 may be - a better choice. Organisational entries exist within each country, - and only that country's localities and organisational units appear - directly beneath the appropriate organisational entry. - - - - - - - - - - - - - -RARE Working Group on Network Applications Support (WG-NAP) [Page 8] - -RFC 1617 Naming and Structuring Guidelines for X.500 May 1994 - - - ROOT - - / | \ - / | \ - C=GB C=FR C=US - - / | \ - / | \ - O=MultiNat O=MultiNat O=MultiNat - - / | / | \ | \ - / | / | \ | \ - - L=FR L=GB<---L=GB | L=US--->L=US L=FR - \ | / - ------------------->L=FR<---------------- - - ---> means "alias to" - - Figure 2: The multi-national as a loose confederation - - Some binding together of the various parts of the organisation can be - achieved by the use of aliases for localities and organisational - units, and this can be done in a highly flexible fashion. In some - cases, the national view might not contain all branches of the - company, as illustrated in Figure 2. - -2.5.3 Loosely Linked DIT Sub-Trees - - A third approach is to avoid aliasing altogether, and to use the - looser binding provided by an attribute such as seeAlso. This - approach treats all parts of an organisation as essentially separate. - - A unified view of the organisation can only be achieved by user - interfaces choosing to follow the seeAlso links. This is a key - difference with aliasing, where decisions to follow links may be - specified within the protocol. (Note that it may be better to specify - another attribute for this purpose, as seeAlso is likely to be used - for a wide variety of purposes.) - -2.5.4 Summary of Advantages and Disadvantages of the Above Approaches - - Providing an internal directory - - All the above methods can be used to provide an internal - directory. In the first two cases, the linkage to other parts of - the organisation can be followed by the protocol and thus - organisation-wide searches can be achieved by single X.500 - - - -RARE Working Group on Network Applications Support (WG-NAP) [Page 9] - -RFC 1617 Naming and Structuring Guidelines for X.500 May 1994 - - - operations. In the last case, interfaces would have to "know" to - follow the soft links indicated by the seeAlso attribute. - - Impact on naming - - In the single-entity model, all DNs within the organisation will - be under one country. It could be argued that this will often - result in rather "unnatural" naming. In the loose- confederation - model, DNs are more natural, although the need to disambiguate - between organisational units and localities on an international, - rather than just a national, basis may have some impact on the - choice of names. For example, it may be necessary to add in an - extra level of organisational unit or locality information. In the - loosely-linked model, there is no impact on naming at all. - - Views of the organisation - - The first method provides a unique view of the organisation. The - loose confederacy allows for a variety of views of the - organisation. The view from the centre of the organisation may - well be that all constituent organisations should be seen as part - of the main organisation, whereas other parts of the organisation - may only be interested in the organisation's centre and a few of - its sibling organisations. The third model gives an equally - flexible view of organisational structures. - - Lookup performance - - All methods should perform reasonably well, providing information - is either held within a single DSA or it is replicated to the - other DSAs. - -3. Naming Style - - The first goal of naming is to provide unique identifiers for - entries. Once this is achieved, the next major goal in naming entries - should be to facilitate querying of the Directory. In particular, - support for a naming structure which facilitates use of user friendly - naming [5] is desirable. Other considerations, such as accurately - reflecting the organisational structure of an organisation, should be - disregarded if this has an adverse effect on normal querying. Early - experience in the pilot has shown that a consistent approach to - structure and naming is an aid to querying using a wide range of user - interfaces, as interfaces are often optimised for DIT structures - which appear prevalent. In addition, the X.501 standard notes that - "RDNs are intended to be long-lived so that the users of the - Directory can store the distinguished names of objects..." and "It is - preferable that distinguished names of objects which humans have to - - - -RARE Working Group on Network Applications Support (WG-NAP) [Page 10] - -RFC 1617 Naming and Structuring Guidelines for X.500 May 1994 - - - deal with be user-friendly." [2] - - Naming is dependent on a number of factors and these are now - considered in turn. - -3.1 Multi-Component Relative Distinguished Names - - According to the standard, relative distinguished names may have more - than one component selected from the set of the attributes of the - entry to be named. This is useful when there are, for example, two - "John Smiths" in one department. The use of multi-component relative - distinguished names allows one to avoid artificial naming values such - as "John Smith 1" or "John Smith-2". Attributes which could be used - as the additional naming attribute include: personalTitle, - roomNumber, telephoneNumber, and userId. - -3.2 National Guidelines for Naming - - Where naming is being done in a country which has established - guidelines for naming, these guidelines should in general be - followed. These guidelines might be based on an established - registration authority, or may make use of an existing registration - mechanism (e.g., company name registration). - - Where an organisation has a name which is nationally registered in an - existing registry, this name is likely to be appropriate for use in - the Directory, even in cases where there are no national guidelines. - -3.3 Naming Organisation and Organisational Unit Names - - The naming of organisations in the Directory will ultimately come - under the jurisdiction of official naming authorities. In the - interim, it is recommended that pilots and organisations follow these - guidelines. An organisation's RDN should usually be the full name of - the organisation, rather than just a set of initials. This means that - University College London should be preferred over UCL. An example - of the problems which a short name might cause is given by the - proposed registration of AA for the Automobile Association. This - seems reasonable at first glance, as the Automobile Association is - well known by this acronym. However, it seems less reasonable in a - broader perspective when you consider that organisations such as - Alcoholics Anonymous and American Airlines use the same acronym. - - Just as initials should usually be avoided for organisational RDNs, - so should formal names which, for example, exist only on official - charters and are not generally well known. There are two reasons for - this approach: - - - - -RARE Working Group on Network Applications Support (WG-NAP) [Page 11] - -RFC 1617 Naming and Structuring Guidelines for X.500 May 1994 - - - 1. The names should be meaningful. - - 2. The names should uniquely identify the organisation, and be - a name which is unlikely to be challenged in an open - registration process. For example, UCL might well be - challenged by United Carriers Ltd. - - The same arguments on naming style can be applied with even greater - force to the choice of RDNs for organisational units. While - abbreviated names will be in common parlance within an organisation, - they will almost always be meaningless outside of that organisation. - While many people in academic computing habitually refer to CS when - thinking of Computer Science, CS may be given several different - interpretations. It could equally be interpreted as Computing - Services, Cognitive Science, Clinical Science or even Counselling - Services. - - For both organisations and organisational units, extra naming - information should be stored in the directory as alternative values - of the naming attribute. Thus, for University College London, UCL - should be stored as an alternative organizationName attribute value. - Similarly CS could be stored as an alternative organizationalUnitName - value for Computer Science and any of the other departments cited - earlier. In general, entries will be located by searching, and so it - is not essential to have RDNs which are either the most memorable or - guessable, although names should be recognisable. The need for users - not to type long names may be achieved by use of carefully selected - alternative values. - -3.4 Naming Human Users - - A reasonably consistent approach to naming people is particularly - critical as a large percentage of directory usage will be looking up - information about people. User interfaces will be better able to - assist users if entries have names conforming to a common format, or - small group of formats. It is suggested that the RDN should follow - such a format. Alternative values of the common name attribute should - be used to store extra naming information. It seems sensible to try - to ensure that the RDN commonName value is genuinely the most common - name for a person as it is likely that user interfaces may choose to - place greater weight on matches on the RDN than on matches on one of - the alternative names. - - The choice of RDN for humans will be influenced by cultural - considerations. In many countries the best choice will be of the form - familiar-first-name surname. Thus, Steve Kille is preferred as the - RDN choice for one of this document's co-authors, while Stephen E. - Kille is stored as an alternative commonName value. Pragmatic choices - - - -RARE Working Group on Network Applications Support (WG-NAP) [Page 12] - -RFC 1617 Naming and Structuring Guidelines for X.500 May 1994 - - - will have to be made for other cultures. The common name attribute - should not be used to hold other attribute information such as - telephone numbers, room numbers, or local codes. Such information - should be stored within the appropriate attributes as defined in the - COSINE and Internet X.500 Schema. Section 3.1 on multi-component RDNs - shows how clashing names can be made unique. - - The choice of a naming strategy should not be made on the basis of - the possibilities of the currently available user interface - implementations. For example, it is inappropriate to use common names - of the form 'surname firstname' merely because a user interface - presents results in a more satisfactory order by so doing. Use the - best structure for human names, and fix the user interface! - - More details on the use of commonName in section 4.4.1. - -3.5 Application Entities - - The guidelines of X.521 should be followed, in that the application - entity should always be named relative to an Organisation or - Organisational Unit. The application process will often correspond to - a system or host. In this case, the application entities should be - named by Common Names which identify the service (e.g., "FTAM - Service"). In cases where there is no useful distinction between - application process and application entity, the application process - may be omitted (This is often done for DSAs in the current pilot). - -4. Attribute Values - - In general the attribute values should be used as documented in the - standards. Sometimes the standard is not very precise about which - attribute to use and how to represent a value. - - The following sections give recommendations how to use them in X.500 - pilot projects. - -4.1 Basic Attribute Syntaxes - - Every attribute type has a definition of the attribute syntaxes its - values may be use. Most attribute types make use the basic attribute - syntaxes only. - - - - - - - - - - -RARE Working Group on Network Applications Support (WG-NAP) [Page 13] - -RFC 1617 Naming and Structuring Guidelines for X.500 May 1994 - - -4.1.1 Printable String - - This most simple syntax uses a subset of characters from ISO 646 IRV. - - A-Z a-z 0-9 ' ( ) + - - , - . / : ? space - - Tab 1: Characters in PrintableString - -4.1.2 IA5 String - T.50 - - The International Alphabet No. 5 (IA5) is known from the X.400 - message handling service. It covers a wider range of characters than - the printable string. The international reference version of IA5 - offers the same set of characters as ISO 646 IRV. - -4.1.3 Teletex String - T.61 - - The Teletex character set is a very unusual one in the computing - environment because it uses mixed one and two octet character codes - which are more difficult to handle than single octet codes. Most of - the characters can be mapped to the more often supported 8-bit - character set standard ISO 8859-1 (ISO Latin-1). - -4.1.4 Case Ignore String - - Many attributes use this case insensitive syntax. It allows attribute - values to be represented using a mixture of upper and lower case - letters, as appropriate. Matching of attribute values, however, is - performed such that no significance is given to case. - -4.1.5 Distinguished Name - - A Distinguished Name should currently never contain a value in T.61 - string syntax because most users would not be able to view or type it - correctly by lack of appropriate hardware/software configuration. - Therefore, only the characters defined in printable string syntax - should be used as part of a RDN. The correct representation of the - name should be added as additional attribute value to match for - search operations. - -4.2 Languages & Transliteration - - The standard as available has no support at all for the use of - different languages in the Directory. It is e.g., not possible to add - a language qualifier to a description attribute nor is it possible to - use characters beyond the Teletex character set. - - - -RARE Working Group on Network Applications Support (WG-NAP) [Page 14] - -RFC 1617 Naming and Structuring Guidelines for X.500 May 1994 - - -4.2.1 Languages other than English - - Many countries have more than one national language and a world-wide - Directory must be able to support non-English-speaking users. - - Until the standard provides a solution for this problem it is - possible to make use of multi-valued attributes to specify a value - not only in the local languages but also in English. - - In particular the friendlyCountryName, stateOrProvinceName and - localityName attributes should use the most often used translations - of its original value to increase the chance for successful searches - also for users with a foreign language. Other attributes like - description, organizationName and organizationalUnitName attributes - should provide multi-lingual values where appropriate. - - The drawback of this solution is, that the user interfaces present - much redundant information because they are not able to know the - language of the values and make an automatic selection. - - Note: The sequence of multi-valued attribute values in an entry - cannot be defined. It is always up to the DSA to decide on - which order to store them and return them as results, and - to the DUA to decide on which order to display them. - -4.2.2 Transliteration - - What measures can be taken to make sure all users are able to read an - attribute, when a value uses one of the special characters from the - T.61 character set? An interim solution is transliteration as used in - earlier days with the typewriters, where e.g., the German 'a' with - umlaut is written as 'ae'. Transliteration is not necessarily unique - since it is dependent on the language, English speakers transliterate - the 'a' with umlaut just to an 'a'. However, it is an improvement - over just using the T.61 value since it may not be possible to - display such a value at all. Whenever an attribute needs a character - not in PrintableString and the attribute syntax allows the use of the - T.61 character set, it is recommended that the attribute should be - supplied as multi-valued attribute both in T.61 string and in a - transliterated PrintableString notation. - -4.3 Access control - - An entry's object class attribute, and any attribute(s) used for - naming an entry are of special significance and may be considered to - be "structural". Any inability to access these attributes will often - militate against successful querying of the Directory. For example, - user interfaces typically limit the scope of their searches by - - - -RARE Working Group on Network Applications Support (WG-NAP) [Page 15] - -RFC 1617 Naming and Structuring Guidelines for X.500 May 1994 - - - searching for entries of a particular type, where the type of entry - is indicated by its object class. Thus, unless the intention is to - bar public access to an entry or set of entries, the object class and - naming attributes should be publicly readable. - -4.4 Selected Attributes - - The section lists attributes together with a short description what - they should be used for and some examples. [6] The source of the - attributes is given in brackets. - - Note that due to national legal restrictions on privacy issues it - might be forbidden to use certain attributes or that the search on - them is restricted. [7] - -4.4.1 Personal Attributes - - commonName [X.520] - - It is proposed that pilots should ignore the standard's - recommendations on storing personal titles, and letters indicating - academic and professional qualifications within the commonName - attribute, as this overloads the commonName attribute. A - personalTitle attribute has already been specified in the COSINE - and Internet Schema, and another attribute could be specified for - information about qualifications. - - The choice of a name depends on the culture as discussed in - section 3.4. When a commonName is selected as (part of) a RDN the - most often used form of the name should be selected. A firstname - should never be supplied only as an initial (unless, of course, - the source data does not include forenames). It is very important - to have its full value in order to be able to distinguish between - two similar entries. Sets of initials should not be concatenated - into a single "word", but be separated by spaces and/or "." - characters. - - - Format: Firstname [Initials] Lastname - - Example: Steve Kille - - Stephen E. Kille - - S.E. Kille - - - - - - -RARE Working Group on Network Applications Support (WG-NAP) [Page 16] - -RFC 1617 Naming and Structuring Guidelines for X.500 May 1994 - - - The use of 'Lastname Firstname' is deprecated as explained in - section 3.4. - - favouriteDrink [RFC 1274] - - The intention of this attribute is that it provides at least one - benign attribute which any user can create or modify, given a - suitable user interface, without having the unfortunate impact on - the directory service that follows from modifying an attribute - such as an e-mail address or telephone number. - - Example: Pure Crystal Water - - organizationalStatus [RFC 1274] - - The Organisational Status attribute type specifies a category by - which a person is often referred to in an organisation. Examples - of usage in academia might include undergraduate student, - researcher, lecturer, etc. - - A Directory administrator should consider carefully the - distinctions between this and the title and description - attributes. - - Example: undergraduate student - - personalTitle [RFC 1274] - - The usually used titles, especially academic ones. Excessive use - should be avoided. - - Example: Prof. Dr. - - roomNumber [RFC 1274] - - The room where the person works, it will mostly be locally defined - how to write the room number, e.g., Building Floor Room. - - Example: HLW B12 - - secretary [RFC 1274] - - The secretary of the person. This is the Distinguished Name (DN) - of the secretary. - - Example: CN=Beverly Pyke, O=ISODE Consortium, C=GB - - - - - -RARE Working Group on Network Applications Support (WG-NAP) [Page 17] - -RFC 1617 Naming and Structuring Guidelines for X.500 May 1994 - - - surname [X.520] - - Like with commonName it is a matter of culture what to use for - surname in case of a noble name, e.g., de Stefani, von Gunten. - - Example: Kille - - title [X.520] - - Title describing the position, job title or function of an - organisational person. - - Example: Manager - International Sales - - userId [RFC 1274] - - When an organisation has centrally managed user ids, it might make - sense to include it into the entry. It might also be used to form - a unique RDN for the person. - - Example: skille - - userPassword [X.520] - - The password of the entry which allows the modification of the - entry, provided that the access control permits it. The password - should not be the same as any system password, unless it is sure - that nobody can read it. With the current implementations this is - mostly not guaranteed. - - Example: 8kiu8z7e - -4.4.2 Organisational Attributes - - associatedDomain [RFC 1274] - - The Internet domain name for an organisation or one of its units. - - Example: isode.com - - businessCategory [X.520] - - Type of business an organisation, an organisational unit or - organisational person is involved in. The values could be chosen - from a thesaurus. - - Example: Software Development - - - - -RARE Working Group on Network Applications Support (WG-NAP) [Page 18] - -RFC 1617 Naming and Structuring Guidelines for X.500 May 1994 - - - organizationName [X.520] - - The name of the organisation. The value for the RDN should be - chosen according to section 3.3. Additional names like - abbreviations should be used for better search results. - - Example: Uni Lausanne - Universite de Lausanne - Universit\c2e Lausanne (with a T.61 encoded umlaut) - University of Lausanne - unil - - organizationalUnitName [X.520] - - The name of a part of the organisation. The value for the RDN - should be chosen according to section 3.3. Additional names like - abbreviations should be provided for better search results. - - Example: Institut fuer Angewandte Mathematik - Mathematik - iam - - roleOccupant [X.520] - - The person(s) in that role. This is the Distinguished Name of the - entry of the person(s). - - Example: CN=Beverly Pyke, O=ISODE Consortium, C=GB - - searchGuide [X.520] - - The currently available DUAs make no use this attribute. It seems - that it is not powerful enough for real usage. Experience is - needed before being able to give recommendations on how to - configure it. - -4.4.3 Local Attributes - - localityName [X.520] - - Name of the place, village or town with values in local and other - languages as useful. - - Example: Bale - B\c3ale (with a T.61 encoded accented character) Basel - Basilea - Basle - - - - -RARE Working Group on Network Applications Support (WG-NAP) [Page 19] - -RFC 1617 Naming and Structuring Guidelines for X.500 May 1994 - - - stateOrProvinceName [X.520] - - Name of the canton, county, department, province or state with - values in local and other languages as useful. If official and - commonly used abbreviations exist for the states, they should be - supplied as additional values - - Example: Ticino - Tessin - TI - -4.4.4 Miscellaneous Attributes - - audio [RFC 1274] - - The audio attribute uses a u-law encoded sound file as used by the - "play" utility on a Sun 4. According to RFC 1274 it is an interim - format. It may be useful to listen to the pronunciation of a name - which is otherwise unknown. - - description [X.520] - - A short informal explanation of special interests of a person or - organisation. Overlap with businessCategory, organizationalStatus - and title should be avoided. - - Example: Networking, distributed systems, OSI, implementation. - - friendlyCountryName [RFC 1274] - - The friendlyCountryName attribute type specifies names of - countries in human readable format. Especially the country name as - used in the major languages should be included as additional - values to help foreign users. - - jpegPhoto [RFC 1488] [8] - - A colour or grayscale picture encoded according to JPEG File - Interchange Format (JFIF). Thanks to compression the size of the - pictures is moderate. For persons it may show a portrait, for - organisations the company logo or a map on how to get there. - - photo [RFC 1274] - - The photo attribute is a b/w G3 fax encoded picture of an object. - The size of the photo should be in a sensible relation to the - informational value of it. This attribute will be replaced by - jpegPhoto. - - - -RARE Working Group on Network Applications Support (WG-NAP) [Page 20] - -RFC 1617 Naming and Structuring Guidelines for X.500 May 1994 - - - seeAlso [X.520] - - Reference to another closely related entry in the DIT, e.g., from - a room to the person using that room. It is the Distinguished Name - of the entry. - - Example: CN=Beverly Pyke, O=ISODE Consortium, C=GB - -4.4.5 MHS Attributes - - mhsORAddresses [X.411] - - The attribute uses internally an ASN.1 structure. The string - notation used for display purposes is implementation dependent. - This attribute is especially useful for an integrated X.400 user - agent since it gets the address in a directly usable format. - - rfc822mailbox [RFC 1274] - - E-Mail address in RFC 822 notation - - Example: s.kille@isode.com - - textEncodedORAddress [RFC 1274] - - X.400 e-mail address in string notation. The F.401 notation should - be used. This attribute shall disappear once the majority of the - DUAs support the mhsORAddresses attribute. The advantage of the - latter attribute is, that a configurable DUA could adjust the - syntax to the one needed by the local mailer, where - textencodedORAddress is just a string which will mostly have a - different syntax than the mailer expects. - - Example: G=thomas; S=lenggenhager; OU1=gate; O=switch; \ - P=switch; A=arcom; C=ch; - -4.4.6 Postal Attributes - - postalAddress [X.520] - - The full postal address (but not including the name) in - international notation, with up to 6 lines with 30 characters - each. - - Example: SWITCH - Limmatquai 13 - CH-8001 Zurich - - - - -RARE Working Group on Network Applications Support (WG-NAP) [Page 21] - -RFC 1617 Naming and Structuring Guidelines for X.500 May 1994 - - - postalCode [X.520] - - The postalCode will be the same as used in the postalAddress (in - international notation). - - Example: CH-8001 - - streetAddress [X.520] - - It shall be the street where the person has its office. Mostly, it - will be the street part of the postalAddress. - - Example: Limmatquai 138 - -4.4.7 Telecom Attributes - - telephoneNumber, facsimileTelephoneNumber & iSDNAddress [X.520] - - The phone number in the international notation according to CCITT - E.123. The separator '-' instead of space may be used according to - the local habit, it should be used consistently within a country. - - Format: "+" ["x" ] - Example: +41 1 268 1540 - - telexNumber [X.520] - - The telex number in the international notation - - Example: 817379, ch, ehhg - -5. Miscellany - - This section draws attention to two areas which frequently provoke - questions, and where it is felt that a consistent approach will be - useful. - -5.1 Schema consistency of aliases - - According to the letter of the standard, an alias may point at any - entry. It is beneficial for aliases to be 'schema consistent'. - - The following two checks should be made: - - 1. The Relative Distinguished Name of the alias should use an - attribute type normally used for naming entries of the - object class of the main entry. - - - - -RARE Working Group on Network Applications Support (WG-NAP) [Page 22] - -RFC 1617 Naming and Structuring Guidelines for X.500 May 1994 - - - 2. If the entry (aliased object) were placed where the alias - is, there should be no schema violation. - -5.2 Organisational Units - - There is a problem that many organisations can be either - organisations or organisational units, dependent on the location in - the DIT (with aliases giving the alternate names). For example, an - organisation may be an independent national organisation and also an - organisational unit of a parent organisation. To achieve this, it is - important to allow an entry to be of both object class organisation - and of object class organisational unit. - -6. References - - [1] Barker, P., and S. Hardcastle-Kille, "The COSINE and Internet - X.500 schema", RFC 1274, Department of Computer Science, - University College London, November 1991. - - [2] "The Directory --- Overview of concepts, models and services", - CCITT X.500 Series Recommendations, December 1988. - - [3] The North American Directory Forum. "A Naming Scheme for C=US", - RFC 1255, NADF-175, NADF, September 1991. - - [4] Michaelson, G., and M. Prior, "Naming Guidelines for the AARNet - X.500 Directory Service", RFC 1562, AEN-001, The University of - Queensland, The University of Adelaide, December 1993. - - [5] Hardcastle-Kille, S., "Using the OSI Directory to achieve user - friendly naming", RFC 1484, Department of Computer Science, - University College London, July 1993. - - [6] Barker, P., "Preparing data for inclusion in an X.500 Directory", - Research Note RN/92/41, Department of Computer Science, - University College London, May 1992. - - [7] Jeunink, E., and E. Huizer, "Directory Services and Privacy - Issues", RARE WG-DATMAN, TF-LEGAL, Work in Progress, May 1993. - - [8] Howes, T., Kille, S., Yeong, W., and C. Robbins, "The X.500 - String Representation of Standard Attribute Syntaxes", RFC 1488, - University of Michigan, ISODE Consortium, Performance Systems - International, NeXor Ltd., July 1993. - -7. Security Considerations - - Security issues are not substantially discussed in this memo. - - - -RARE Working Group on Network Applications Support (WG-NAP) [Page 23] - -RFC 1617 Naming and Structuring Guidelines for X.500 May 1994 - - -8. Authors' Addresses - - Paul Barker - Department of Computer Science - University College London - Gower Street - London WC1E 6BT - England - - Phone: +44 71 380 7366 - EMail: p.barker@cs.ucl.ac.uk - - DN: CN=Paul Barker, OU=Computer Science, O=University College - London, C=GB - - UFN: Paul Barker, Computer Science, UCL, GB - - - Steve Kille - ISODE Consortium - The Dome - The Square - Richmond TW9 1DT - England - - Phone: +44 81 332 9091 - EMail: s.kille@isode.com - - DN: CN=Steve Kille, O=ISODE Consortium, C=GB - - UFN: S. Kille, ISODE Consortium, GB - - - Thomas Lenggenhager - SWITCH - Limmatquai 138 - CH-8001 Zurich - Switzerland - - Phone: +41 1 268 1540 - EMail: lenggenhager@switch.ch - - DN: CN=Thomas Lenggenhager, O=SWITCH, C=CH - - UFN: Thomas Lenggenhager, SWITCH, CH - - - - - - -RARE Working Group on Network Applications Support (WG-NAP) [Page 24] - -RFC 1617 Naming and Structuring Guidelines for X.500 May 1994 - - -9. Appendix - Example Entries - -9.1 Country - - DN: C=CH - - objectClass=top & country & domainRelatedObject & friendlyCountry - country=CH - associatedDomain=ch - friendlyCountryName=CH - friendlyCountryName=Confoederatio Helvetica - friendlyCountryName=Schweiz - friendlyCountryName=Suisse - friendlyCountryName=Svizzera - friendlyCountryName=Switzerland - -9.2 Organisation - - DN: O=SWITCH, C=CH - - objectClass=top & organization & mhsUser & domainRelatedObject - description=Swiss Academic and Research Network - organizationName=SWIss TeleCommunication system for Higher - education\and research - organizationName=Swiss Academic and Research Network - organizationName=SWITCH - localityName=Zuerich - localityName=Zurich - localityName={T.61}Z\c8urich - stateOrProvinceName=ZH - stateOrProvinceName=Zuerich - stateOrProvinceName=Zurich - stateOrProvinceName={T.61}Z\c8urich - postalAddress=SWITCH - Limmatquai 138 - CH-8001 Zurich - postalCode=CH-8001 - streetAddress=Limmatquai 138 - telephoneNumber=+41 1 268 1515 - facsimileTelephoneNumber=+41 1 268 1568 - seeAlso=CN=Postmaster, O=SWITCH, C=CH - mhsORAddresses=S=postmaster, O=switch; P=switch; A=arcom; C=ch; - associatedDomain=switch.ch - - - - - - - - -RARE Working Group on Network Applications Support (WG-NAP) [Page 25] - -RFC 1617 Naming and Structuring Guidelines for X.500 May 1994 - - -9.3 Organisation Unit - - DN: OU=SWITCHdirectory, O=SWITCH, C=CH - - objectClass=top & organizationalUnit - description=The SWITCH X.500 pilot project - organizationalUnitName=SWITCHdirectory - localityName=Zurich - localityName=Zuerich - localityName={T.61}Z\c8urich - stateOrProvinceName=Zurich - stateOrProvinceName=Zuerich - stateOrProvinceName=ZH - stateOrProvinceName={T.61}Z\c8urich - postalAddress=SWITCHdirectory - SWITCH - Limmatquai 138 - CH-8001 Zurich - postalCode=CH-8001 - streetAddress=Limmatquai 138 - telephoneNumber=+41 1 268 1540 - facsimileTelephoneNumber=+41 1 268 1568 - -9.4 Organizational Role - - DN: CN=Directory Manager, O=SWITCH, C=CH - - objectClass=top & organizationalRole & mhsUser - commonName=Directory Manager - description=SWITCH Directory Managers - roleOccupant=CN=Martin Berli, O=SWITCH, C=CH - roleOccupant=CN=Thomas Lenggenhager, O=SWITCH, C=CH - localityName=Zuerich - localityName=Zurich - localityName={T.61}Z\c8urich - stateOrProvinceName=Zurich - stateOrProvinceName=Zuerich - stateOrProvinceName=ZH - stateOrProvinceName={T.61}Z\c8urich - postalAddress=SWITCHdirectory - SWITCH - Limmatquai 138 - CH-8001 Zurich - postalCode=CH-8001 - streetAddress=Limmatquai 138 - telephoneNumber=+41 1 268 1540 - facsimileTelephoneNumber=+41 1 268 1568 - mhsORAddresses=S=switchinfo; O=switch; P=switch; A=arcom; C=ch; - - - -RARE Working Group on Network Applications Support (WG-NAP) [Page 26] - -RFC 1617 Naming and Structuring Guidelines for X.500 May 1994 - - - DN: CN=Postmaster, O=SWITCH, C=CH - - objectClass=top & organizationalRole & mhsUser - commonName=Postmaster - commonName=Helpdesk - roleOccupant=CN=Christoph Graf, O=SWITCH, C=CH - roleOccupant=CN=Felix Kugler, O=SWITCH, C=CH - roleOccupant=CN=Marcel Parodi, O=SWITCH, C=CH - roleOccupant=CN=Marcel Schneider, O=SWITCH, C=CH - telephoneNumber=+41 1 268 1520 - facsimileTelephoneNumber=+41 1 268 1568 - mhsORAddresses=S=postmaster; O=switch; P=switch; A=arcom; C=ch; - - DN: CN=Secretary, O=SWITCH, C=CH - - objectClass=top & organizationalRole & quipuObject - commonName=Secretary - roleOccupant=CN=Franziska Remund, O=SWITCH, C=CH - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -RARE Working Group on Network Applications Support (WG-NAP) [Page 27] - -RFC 1617 Naming and Structuring Guidelines for X.500 May 1994 - - -9.5 Person - - DN: CN=Thomas Lenggenhager, O=SWITCH, C=CH - - objectClass=top & person & organizationalPerson & mhsUser & - pilotObject & newPilotPerson - commonName=Thomas Lenggenhager - commonName=T. Lenggenhager - surname=Lenggenhager - description=SWITCHinfo, Project Leader - localityName=Zuerich - localityName=Zurich - localityName={T.61}Z\c8urich - stateOrProvinceName=ZH - stateOrProvinceName=Zuerich - stateOrProvinceName=Zurich - stateOrProvinceName={T.61}Z\c8urich - postalAddress=SWITCH - Limmatquai 138 - CH-8001 Zurich - postalCode=CH-8001 - streetAddress=Limmatquai 138 - telephoneNumber=+41 1 268 1540 - facsimileTelephoneNumber=+41 1 268 1568 - mhsORAddresses=S=lenggenhager; O=switch; P=switch; A=arcom; C=ch; - userPassword=secret - textEncodedORaddress={T.61}S=lenggenhager; O=switch; P=switch; \ - A=arcom; C=ch; - rfc822mailbox=lenggenhager@switch.ch - secretary=CN=Franziska Remund, O=SWITCH, C=CH - - - - - - - - - - - - - - - - - - - - - -RARE Working Group on Network Applications Support (WG-NAP) [Page 28] - diff --git a/doc/rfc/rfc1798.txt b/doc/rfc/rfc1798.txt deleted file mode 100644 index 96d477c75a..0000000000 --- a/doc/rfc/rfc1798.txt +++ /dev/null @@ -1,507 +0,0 @@ - - - - - - -Network Working Group A. Young -Request for Comments: 1798 ISODE Consortium -Category: Standards Track June 1995 - - - Connection-less Lightweight Directory Access Protocol - -Status of this Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -X.500 - - The protocol described in this document is designed to provide access - to the Directory while not incurring the resource requirements of the - Directory Access Protocol (DAP) [3]. In particular, it is aimed at - avoiding the elapsed time that is associated with connection-oriented - communication and it facilitates use of the Directory in a manner - analagous to the DNS [5,6]. It is specifically targeted at simple - lookup applications that require to read a small number of attribute - values from a single entry. It is intended to be a complement to DAP - and LDAP [4]. The protocol specification draws heavily on that of - LDAP. - -1. Background - - The Directory can be used as a repository for many kinds of - information. The full power of DAP is unnecessary for applications - that require simple read access to a few attribute values. - Applications addressing is a good example of this type of use where - an application entity needs to determine the Presentation Address - (PA) of a peer entity given that peer's Application Entity Title - (AET). If the AET is a Directory Name (DN) then the required result - can be obtained from the PA attribute of the Directory entry - identified by the AET. This is very similar to DNS. - - - - - - - - - - - - -Young Standards Track [Page 1] - -RFC 1798 CLDAP June 1995 - - - Use of DAP to achieve this functionality involves a significant - number of network exchanges: - - ___________________________________________________________ - |_#_|______Client_(DUA)________DAP________Server_(DSA)_____| - | 1| N-Connect.request -> | - | 2| <- N-Connect.response | - | 3| T-Connect.request -> | - | 4| <- T-Connect.response | - | | S-Connect.request, | - | | P-Connect.request, | - | | A-Associate.request, | - | 5| DAP-Bind.request -> | - | | S-Connect.response, | - | | P-Connect.response, | - | | A-Associate.response, | - | 6| <- DAP-Bind.response | - | 7| DAP-Read.request -> | - | 8| <- DAP-Read.response | - | | S-Release.request, | - | | P-Release.request, | - | | A-Release.request, | - | 9| DAP-Unbind.request -> | - | | S-Release.response, | - | | P-Release.response, | - | | A-Release.response, | - | 10| <- DAP-Unbind.response | - | | T-Disconnect.request, | - | 11| N-Disconnect.request -> | - | | T-Disconnect.response,| - | 12| <- N-Disconnect.response | - |___|______________________________________________________| - - - - - - - - - - - - - - - - - - - -Young Standards Track [Page 2] - -RFC 1798 CLDAP June 1995 - - - This is 10 packets before the application can continue, given that it - can probably do so after issuing the T-Disconnect.request. (Some - minor variations arise depending upon the class of Network and - Transport service that is being used; for example use of TP4 over - CLNS reduces the packet count by two.) LDAP is no better in the case - where the LDAP server uses full DAP to communicate with the - Directory: - - ____________________________________________________________________ - |__#_|___Client_____LDAP_____LDAP_server______DAP_________DSA_______| - | 1 | TCP SYN -> | - | 2 | <- TCP SYN ACK | - | 3 | BindReq -> | - | 4 | N-Connect.req -> | - | 5 | <- N-Connect.res | - | 6 | T-Connect.req -> | - | 7 | <- T-Connect.res | - | 8 | DAP-Bind.req -> | - | 9 | <- DAP-Bind.res | - | 10 | <- BindRes | - | 11 | SearchReq -> | - | 12 | DAP-Search.req -> | - | 13 | <- DAP-Search.res | - | 14 | <- SearchRes | - | 15 | TCP FIN -> | - | 16 | DAP-Unbind.req -> | - | 17 | <- DAP-Unbind.res | - | 18 | N-Disconnect.req -> | - | 19 | <- N-Disconnect.res| - |____|______________________________________________________________| - - - - - - - - - - - - - - - - - - - - - -Young Standards Track [Page 3] - -RFC 1798 CLDAP June 1995 - - - Here there are 14 packets before the application can continue. Even - if the LDAP server is on the same host as the DSA (so packet delay is - negligible), or if the DSA supports LDAP directly, then there are - still 6 packets. - - ____________________________________ - | #| Client LDAP LDAP server| - |__|________________________________| - | 1| TCP SYN -> | - | 2| <- TCP SYN ACK| - | 3| BindReq -> | - | 4| <- BindRes | - | 5| SearchReq -> | - |_6|_______________<-____SearchRes__| - - - This protocol provides for simple access to the Directory where the - delays inherent in the above exchanges are unacceptable and where the - additional functionality provided by connection-mode operation is not - required. - -2. Protocol Model - - CLDAP is based directly on LDAP [4] and inherits many of the key - aspects of the LDAP protocol: - - - - Many protocol data elements are encoding as ordinary strings - (e.g., Distinguished Names). - - - - A lightweight BER encoding is used to encode all protocol - elements. - - It is different to LDAP in that: - - - - Protocol elements are carried directly over UDP or other - connection-less transport, bypassing much of the - session/presentation overhead and that of connections (LDAP uses - a connection-mode transport service). - - - - A restricted set of operations is available. - - The definitions of most protocol elements are inherited from LDAP. - - The general model adopted by this protocol is one of clients - performing protocol operations against servers. In this model, this - is accomplished by a client transmitting a protocol request - describing the operation to be performed to a server, which is then - responsible for performing the necessary operations on the Directory. - - - -Young Standards Track [Page 4] - -RFC 1798 CLDAP June 1995 - - - Upon completion of the necessary operations, the server returns a - response containing any results or errors to the requesting client. - - Note that, although servers are required to return responses whenever - such responses are defined in the protocol, there is no requirement - for synchronous behaviour on the part of either client or server - implementations: requests and responses for multiple operations may - be exchanged by client and servers in any order, as long as servers - eventually send a response for every request that requires one. - - Also, because the protocol is implemented over a connection-less - transport service clients must be prepared for either requests or - responses to be lost. Clients should use a retry mechanism with - timeouts in order to achieve the desired level of reliability. For - example, a client might send off a request and wait for two seconds. - If no reply is forthcoming, the request is sent again and the client - waits four seconds. If there is still no reply, the client sends it - again and waits eight seconds, and so on, until some maximun time. - Such algorithms are widely used in other datagram-based protocol - implementations, such as the DNS. It is not appropriate to mandate a - specific algorithm as this will depend upon the requirments and - operational environment of individual CLDAP client implementations. - - It is not required that a client abandon any requests to which no - response has been received and for which a reply is no longer - required (because the request has been timed out), but they may do - so. - - Consistent with the model of servers performing protocol operations - on behalf of clients, it is also to be noted that protocol servers - are expected to handle referrals without resorting to the return of - such referrals to the client. This protocol makes no provisions for - the return of referrals to clients, as the model is one of servers - ensuring the performance of all necessary operations in the - Directory, with only final results or errors being returned by - servers to clients. - - Note that this protocol can be mapped to a strict subset of the - Directory abstract service, so it can be cleanly provided by the DAP. - -3. Mapping Onto Transport Services - - This protocol is designed to run over connection-less transports, - with all 8 bits in an octet being significant in the data stream. - Specifications for two underlying services are defined here, though - others are also possible. - - - - - -Young Standards Track [Page 5] - -RFC 1798 CLDAP June 1995 - - -3.1. User Datagram Protocol (UDP) - - The CLDAPMessage PDUs are mapped directly onto UDP datagrams. Only - one request may be sent in a single datagram. Only one response may - be sent in a single datagram. Server implementations running over - the UDP should provide a protocol listener on port 389. - -3.2. Connection-less Transport Service (CLTS) - - Each LDAPMessage PDU is mapped directly onto T-Unit-Data. - -4. Elements of Protocol - - CLDAP messages are defined by the following ASN.1: - - CLDAPMessage ::= SEQUENCE { - messageID MessageID, - user LDAPDN, -- on request only -- - protocolOp CHOICE { - searchRequest SearchRequest, - searchResponse SEQUENCE OF - SearchResponse, - abandonRequest AbandonRequest - } - } - - where MessageID, LDAPDN, SearchRequest, SearchResponse and - AbandonRequest are defined in the LDAP protocol. - - The 'user' element is supplied only on requests (it should be zero - length and is ignored in responses). It may be used for logging - purposes but it is not required that a CLDAP server implementation - apply any particular semantics to this field. - - Editorial note: - There has been some discussion about the desirability of - authentication with CLDAP requests and the addition of the fields - necessary to support this. This might take the form of a clear - text password (which would go against the current IAB drive to - remove such things from protocols) or some arbitrary credentials. - Such a field is not included. It is felt that, in general, - authentication would incur sufficient overhead to negate the - advantages of the connectionless basis of CLDAP. If an - application requires authenticated access to the Directory then - CLDAP is not an appropriate protocol. - - - - - - -Young Standards Track [Page 6] - -RFC 1798 CLDAP June 1995 - - - Within a searchResponse all but the last SearchResponse has choice - 'entry' and the last SearchResponse has choice 'resultCode'. Within - a searchResponse, as an encoding optimisation, the value of the - objectName LDAP DN may use a trailing '*' character to refer to the - baseObject of the corresponding searchRequest. For example, if the - baseObject is specified as "o=UofM, c=US", then the following - objectName LDAPDNs in a response would have the indicated meanings - - objectName returned actual LDAPDN denoted - ____________________________________________________ - "*" "o=UofM, c=US" - "cn=Babs Jensen, *" "cn=Babs Jensen, o=UofM, c=US" - -4.1. Errors - -The following error code is added to the LDAPResult.resultCode -enumeration of [4]: - - resultsTooLarge (70), - - This error is returned when the LDAPMessage PDU containing the - results of an operation are too large to be sent in a single - datagram. - -4.2. Example - - A simple lookup can be performed in 4 packets. This is reduced to 2 - if either the DSA implements the CLDAP protocol, the CLDAP server has - a cache of the desired results, or the CLDAP server and DSA are co- - located such that there is insignificant delay between them. - - _______________________________________________________________ - |_#|___Client_____CLDAP____CLDAP_server____DAP________DSA______| - | 1| SearchReq -> | - | 2| DAP-Search.req -> | - | 3| <- DAP-Search.res| - | 4| <- SearchRes | - |__|___________________________________________________________| - -5. Implementation Considerations - - The following subsections provide guidance on the implementation of - clients and servers using the CLDAP protocol. - - - - - - - - -Young Standards Track [Page 7] - -RFC 1798 CLDAP June 1995 - - -5.1. Server Implementations - - Given that the goal of this protocol is to minimise the elapsed time - between making a Directory request and receiving the response, a - server which uses DAP to access the directory should use techniques - that assist in this. - - - - A server should remain bound to the Directory during reasonably - long idle periods or should remain bound permanently. - - - - Cacheing of results is highly desirable but this must be - tempered by the need to provide up-to-date results given the - lack of a cache invalidation protocol in DAP (either implicit - via timers or explicit) and the lack of a dontUseCopy service - control in the protocol. - - Of course these issues are irrelevant if the CLDAP protocol is - directly supported by a DSA. - -5.2. Client Implementations - - For simple lookup applications, use of a retry algorithm with - multiple servers similar to that commonly used in DNS stub resolver - implementations is recommended. The location of a CLDAP server or - servers may be better specified using IP addresses (simple or - broadcast) rather than names that must first be looked up in another - directory such as DNS. - -6. Security Considerations - - This protocol provides no facilities for authentication. It is - expected that servers will bind to the Directory either anonymously - or using simple authentication without a password. - -7. Bibliography - - [1] The Directory: Overview of Concepts, Models and Service. CCITT - Recommendation X.500, 1988. - - [2] The Directory: Models. CCITT Recommendation X.501 ISO/IEC JTC - 1/SC21; International Standard 9594-2, 1988. - - [3] The Directory: Abstract Service Definition. CCITT Recommendation - X.511, ISO/IEC JTC 1/SC21; International Standard 9594-3, 1988. - - [4] Yeong, W., Howes, T., and S. Kille, "X.500 Lightweight Directory - Access Protocol", RFC 1487, Performance Systems International, - University of Michigan, ISODE Consortium, July 1993. - - - -Young Standards Track [Page 8] - -RFC 1798 CLDAP June 1995 - - - [5] Mockapetris, P., "Domain Names - Implementation and - Specification", STD 13, RFC 1035, USC/Information Sciences - Institute, November 1987. - - [6] Mockapetris, P., "Domain Names - Concepts and Facilities", STD - 13, RFC 1034, USC/Information Sciences Institute, November 1987. - -8. Acknowledgements - - Many thanks to Tim Howes and Steve Kille for their detailed comments - and to other members of the working group. - - This work was initiated by the Union Bank of Switzerland. - -9. Author's Address - - Alan Young - ISODE Consortium - The Dome, The Square - RICHMOND - GB - TW9 1DT - - Phone: +44 81 332 9091 - EMail: A.Young@isode.com - X.400: i=A; s=Young; o=ISODE Consortium; p=ISODE; a=MAILNET; c=FI - - - - - - - - - - - - - - - - - - - - - - - - - - -Young Standards Track [Page 9] - diff --git a/doc/rfc/rfc1823.txt b/doc/rfc/rfc1823.txt deleted file mode 100644 index 835f1ef477..0000000000 --- a/doc/rfc/rfc1823.txt +++ /dev/null @@ -1,1235 +0,0 @@ - - - - - - -Network Working Group T. Howes -Request for Comments: 1823 M. Smith -Category: Informational University of Michigan - August 1995 - - - The LDAP Application Program Interface - -Status of this Memo - - This memo provides information for the Internet community. This memo - does not specify an Internet standard of any kind. Distribution of - this memo is unlimited. - -1. Introduction - - This document defines a C language application program interface to - the lightweight directory access protocol (LDAP). The LDAP API is - designed to be powerful, yet simple to use. It defines compatible - synchronous and asynchronous interfaces to LDAP to suit a wide - variety of applications. This document gives a brief overview of the - LDAP model, then an overview of how the API is used by an application - program to obtain LDAP information. The API calls are described in - detail, followed by an appendix that provides some example code - demonstrating the use of the API. - -2. Overview of the LDAP Model - - LDAP is the lightweight directory access protocol, described in [2] - and [7]. It can provide a lightweight frontend to the X.500 directory - [1], or a stand-alone service. In either mode, LDAP is based on a - client-server model in which a client makes a TCP connection to an - LDAP server, over which it sends requests and receives responses. - - The LDAP information model is based on the entry, which contains - information about some object (e.g., a person). Entries are composed - of attributes, which have a type and one or more values. Each - attribute has a syntax that determines what kinds of values are - allowed in the attribute (e.g., ASCII characters, a jpeg photograph, - etc.) and how those values behave during directory operations (e.g., - is case significant during comparisons). - - Entries are organized in a tree structure, usually based on - political, geographical, and organizational boundaries. Each entry is - uniquely named relative to its sibling entries by its relative - distinguished name (RDN) consisting of one or more distinguished - attribute values from the entry. At most one value from each - attribute may be used in the RDN. For example, the entry for the - - - -Howes & Smith Informational [Page 1] - -RFC 1823 LDAP API August 1995 - - - person Babs Jensen might be named with the "Barbara Jensen" value - from the commonName attribute. A globally unique name for an entry, - called a distinguished name or DN, is constructed by concatenating - the sequence of RDNs from the root of the tree down to the entry. For - example, if Babs worked for the University of Michigan, the DN of her - U-M entry might be "cn=Barbara Jensen, o=University of Michigan, - c=US". The DN format used by LDAP is defined in [4]. - - Operations are provided to authenticate, search for and retrieve - information, modify information, and add and delete entries from the - tree. The next sections give an overview of how the API is used and - detailed descriptions of the LDAP API calls that implement all of - these functions. - -3. Overview of LDAP API Use - - An application generally uses the LDAP API in four simple steps. - - o Open a connection to an LDAP server. The ldap_open() call - returns a handle to the connection, allowing multiple - connections to be open at once. - - o Authenticate to the LDAP server and/or the X.500 DSA. The - ldap_bind() call and friends support a variety of - authentication methods. - - o Perform some LDAP operations and obtain some results. - ldap_search() and friends return results which can be parsed - by ldap_result2error(), ldap_first_entry(), ldap_next_entry(), - etc. - - o Close the connection. The ldap_unbind() call closes the - connection. - - Operations can be performed either synchronously or asynchronously. - Synchronous calls end in _s. For example, a synchronous search can be - completed by calling ldap_search_s(). An asynchronous search can be - initiated by calling ldap_search(). All synchronous routines return - an indication of the outcome of the operation (e.g, the constant - LDAP_SUCCESS or some other error code). The asynchronous routines - return the message id of the operation initiated. This id can be used - in subsequent calls to ldap_result() to obtain the result(s) of the - operation. An asynchronous operation can be abandoned by calling - ldap_abandon(). - - - - - - - -Howes & Smith Informational [Page 2] - -RFC 1823 LDAP API August 1995 - - - Results and errors are returned in an opaque structure called - LDAPMessage. Routines are provided to parse this structure, step - through entries and attributes returned, etc. Routines are also - provided to interpret errors. The next sections describe these - routines in more detail. - -4. Calls for performing LDAP operations - - This section describes each LDAP operation API call in detail. All - calls take a "connection handle", a pointer to an LDAP structure - containing per-connection information. Many routines return results - in an LDAPMessage structure. These structures and others are - described as needed below. - -4.1. Opening a connection - - ldap_open() opens a connection to the LDAP server. - - typedef struct ldap { - /* ... opaque parameters ... */ - int ld_deref; - int ld_timelimit; - int ld_sizelimit; - int ld_errno; - char *ld_matched; - char *ld_error; - /* ... opaque parameters ... */ - } LDAP; - - LDAP *ldap_open( char *hostname, int portno ); - - Parameters are: - - hostname Contains a space-separated list of hostnames or dotted - strings representing the IP address of hosts running an - LDAP server to connect to. The hosts are tried in the - order listed, stopping with the first one to which a - successful connection is made; - - portno contains the TCP port number to which to connect. The - default LDAP port can be obtained by supplying the - constant LDAP_PORT. - - ldap_open() returns a "connection handle", a pointer to an LDAP - structure that should be passed to subsequent calls pertaining to the - connection. It returns NULL if the connection cannot be opened. One - of the ldap_bind calls described below must be completed before other - operations can be performed on the connection. - - - -Howes & Smith Informational [Page 3] - -RFC 1823 LDAP API August 1995 - - - The calling program should assume nothing about the order of the - fields in the LDAP structure. There may be other fields in the - structure for internal library use. The fields shown above are - described as needed in the description of other calls below. - -4.2. Authenticating to the directory - - ldap_bind() and friends are used to authenticate to the directory. - - int ldap_bind( LDAP *ld, char *dn, char *cred, int method ); - - int ldap_bind_s( LDAP *ld, char *dn, char *cred, int method ); - - int ldap_simple_bind( LDAP *ld, char *dn, char *passwd ); - - int ldap_simple_bind_s( LDAP *ld, char *dn, char *passwd ); - - int ldap_kerberos_bind( LDAP *ld, char *dn ); - - int ldap_kerberos_bind_s( LDAP *ld, char *dn ); - - Parameters are: - - ld The connection handle; - - dn The name of the entry to bind as; - - cred The credentials with which to authenticate; - - method One of LDAP_AUTH_SIMPLE, LDAP_AUTH_KRBV41, or - LDAP_AUTH_KRBV42, indicating the authentication method to use; - - passwd For ldap_simple_bind(), the password to compare to the entry's - userPassword attribute; - - There are three types of bind calls, providing simple authentication, - kerberos authentication, and general routines to do either one. In - the case of Kerberos version 4 authentication using the general - ldap_bind() routines, the credentials are ignored, as the routines - assume a valid ticket granting ticket already exists which can be - used to retrieve the appropriate service tickets. - - Synchronous versions of the routines have names that end in _s. - These routines return the result of the bind operation, either the - constant LDAP_SUCCESS if the operation was successful, or another - LDAP error code if it was not. See the section below on error - handling for more information about possible errors and how to - interpret them. - - - -Howes & Smith Informational [Page 4] - -RFC 1823 LDAP API August 1995 - - - Asynchronous versions of these routines return the message id of the - bind operation initiated. A subsequent call to ldap_result(), - described below, can be used to obtain the result of the bind. In - case of error, these routines will return -1, setting the ld_errno - field in the LDAP structure appropriately. - - Note that no other operations over the connection should be attempted - before a bind call has successfully completed. Subsequent bind calls - can be used to re-authenticate over the same connection. - -4.3. Closing the connection - - ldap_unbind() is used to unbind from the directory and close the - connection. - - int ldap_unbind( LDAP *ld ); - - Parameters are: - - ld The connection handle. - - ldap_unbind() works synchronously, unbinding from the directory, - closing the connection, and freeing up the ld structure before - returning. ldap_unbind() returns LDAP_SUCCESS (or another LDAP error - code if the request cannot be sent to the LDAP server). After a call - to ldap_unbind(), the ld connection handle is invalid. - -4.4. Searching - - ldap_search() and friends are used to search the LDAP directory, - returning a requested set of attributes for each entry matched. - There are three variations. - - struct timeval { - long tv_sec; - long tv_usec; - }; - int ldap_search( - LDAP *ld, - char *base, - int scope, - char *filter, - char *attrs[], - int attrsonly - ); - int ldap_search_s( - LDAP *ld, - char *base, - - - -Howes & Smith Informational [Page 5] - -RFC 1823 LDAP API August 1995 - - - int scope, - char *filter, - char *attrs[], - int attrsonly, - LDAPMessage **res - ); - int ldap_search_st( - LDAP *ld, - char *base, - int scope, - char *filter, - char *attrs[], - int attrsonly, - struct timeval *timeout, - LDAPMessage **res - ); - - Parameters are: - - ld The connection handle; - - base The dn of the entry at which to start the search; - - scope One of LDAP_SCOPE_BASE, LDAP_SCOPE_ONELEVEL, or - LDAP_SCOPE_SUBTREE, indicating the scope of the search; - - filter A character string as described in RFC 1558 [3], - representing the search filter; - - attrs A NULL-terminated array of strings indicating which - attributes to return for each matching entry. Passing - NULL for this parameter causes all available attributes - to be retrieved; - - attrsonly A boolean value that should be zero if both attribute - types and values are to be returned, non-zero if only - types are wanted; - - timeout For the ldap_search_st() call, this specifies the local - search timeout value; - - res For the synchronous calls, this is a result parameter - which will contain the results of the search upon - completion of the call. - - There are three fields in the ld connection handle which control how - the search is performed. They are: - - - - -Howes & Smith Informational [Page 6] - -RFC 1823 LDAP API August 1995 - - - ld_sizelimit A limit on the number of entries to return from the - search. A value of zero means no limit; - - ld_timelimit A limit on the number of seconds to spend on the search. - A value of zero means no limit; - - ld_deref One of LDAP_DEREF_NEVER, LDAP_DEREF_SEARCHING, - LDAP_DEREF_FINDING, or LDAP_DEREF_ALWAYS, specifying - how aliases should be handled during the search. The - LDAP_DEREF_SEARCHING value means aliases should be - dereferenced during the search but not when locating - the base object of the search. The LDAP_DEREF_FINDING - value means aliases should be dereferenced when - locating the base object but not during the search. - - An asynchronous search is initiated by calling ldap_search(). It - returns the message id of the initiated search. The results of the - search can be obtained by a subsequent call to ldap_result(). The - results can be parsed by the result parsing routines described in - detail later. In case of error, -1 is returned and the ld_errno - field in the LDAP structure is set appropriately. - - A synchronous search is performed by calling ldap_search_s() or - ldap_search_st(). The routines are identical, except that - ldap_search_st() takes an additional parameter specifying a timeout - for the search. Both routines return an indication of the result of - the search, either LDAP_SUCCESS or some error indication (see Error - Handling below). The entries returned from the search (if any) are - contained in the res parameter. This parameter is opaque to the - caller. Entries, attributes, values, etc., should be extracted by - calling the parsing routines described below. The results contained - in res should be freed when no longer in use by calling - ldap_msgfree(), described later. - -4.5. Reading an entry - - LDAP does not support a read operation directly. Instead, this - operation is emulated by a search with base set to the DN of the - entry to read, scope set to LDAP_SCOPE_BASE, and filter set to - "(objectclass=*)". attrs contains the list of attributes to return. - -4.6. Listing the children of an entry - - LDAP does not support a list operation directly. Instead, this - operation is emulated by a search with base set to the DN of the - entry to list, scope set to LDAP_SCOPE_ONELEVEL, and filter set to - "(objectclass=*)". attrs contains the list of attributes to return - for each child entry. - - - -Howes & Smith Informational [Page 7] - -RFC 1823 LDAP API August 1995 - - -4.7. Modifying an entry - - The ldap_modify() and ldap_modify_s() routines are used to modify an - existing LDAP entry. - - typedef struct ldapmod { - int mod_op; - char *mod_type; - union { - char **modv_strvals; - struct berval **modv_bvals; - } mod_vals; - } LDAPMod; - #define mod_values mod_vals.modv_strvals - #define mod_bvalues mod_vals.modv_bvals - - int ldap_modify( LDAP *ld, char *dn, LDAPMod *mods[] ); - - int ldap_modify_s( LDAP *ld, char *dn, LDAPMod *mods[] ); - - Parameters are: - - ld The connection handle; - - dn The name of the entry to modify; - - mods A NULL-terminated array of modifications to make to the - entry. - - The fields in the LDAPMod structure have the following meanings: - - mod_op The modification operation to perform. It should be one of - LDAP_MOD_ADD, LDAP_MOD_DELETE, or LDAP_MOD_REPLACE. This - field also indicates the type of values included in the - mod_vals union. It is ORed with LDAP_MOD_BVALUES to select - the mod_bvalues form. Otherwise, the mod_values form is - used; - - mod_type The type of the attribute to modify; - - mod_vals The values (if any) to add, delete, or replace. Only one of - the mod_values or mod_bvalues variants should be used, - selected by ORing the mod_op field with the constant - LDAP_MOD_BVALUES. mod_values is a NULL-terminated array of - zero-terminated strings and mod_bvalues is a NULL-terminated - array of berval structures that can be used to pass binary - values such as images. - - - - -Howes & Smith Informational [Page 8] - -RFC 1823 LDAP API August 1995 - - - For LDAP_MOD_ADD modifications, the given values are added to the - entry, creating the attribute if necessary. For LDAP_MOD_DELETE - modifications, the given values are deleted from the entry, removing - the attribute if no values remain. If the entire attribute is to be - deleted, the mod_vals field should be set to NULL. For - LDAP_MOD_REPLACE modifications, the attribute will have the listed - values after the modification, having been created if necessary. All - modifications are performed in the order in which they are listed. - - ldap_modify_s() returns the LDAP error code resulting from the - modify operation. This code can be interpreted by ldap_perror() - and friends. - - ldap_modify() returns the message id of the request it initiates, or - -1 on error. The result of the operation can be obtained by calling - ldap_result(). - -4.8. Modifying the RDN of an entry - - The ldap_modrdn() and ldap_modrdn_s() routines are used to change the - name of an LDAP entry. - - int ldap_modrdn( - LDAP *ld, - char *dn, - char *newrdn, - int deleteoldrdn - ); - int ldap_modrdn_s( - LDAP *ld, - char *dn, - char *newrdn, - int deleteoldrdn - ); - - Parameters are: - - ld The connection handle; - - dn The name of the entry whose RDN is to be changed; - - newrdn The new RDN to give the entry; - - deleteoldrdn A boolean value, if non-zero indicating that the old - RDN value(s) should be removed, if zero indicating that - the old RDN value(s) should be retained as non- - distinguished values of the entry. - - - - -Howes & Smith Informational [Page 9] - -RFC 1823 LDAP API August 1995 - - - The ldap_modrdn_s() routine is synchronous, returning the LDAP error - code indicating the outcome of the operation. - - The ldap_modrdn() routine is asynchronous, returning the message id - of the operation it initiates, or -1 in case of trouble. The result - of the operation can be obtained by calling ldap_result(). - -4.9. Adding an entry - - ldap_add() and ldap_add_s() are used to add entries to the LDAP - directory. - - int ldap_add( LDAP *ld, char *dn, LDAPMod *attrs[] ); - - int ldap_add_s( LDAP *ld, char *dn, LDAPMod *attrs[] ); - - Parameters are: - - ld The connection handle; - - dn The name of the entry to add; - - attrs The entry's attributes, specified using the LDAPMod structure - defined for ldap_modify(). The mod_type and mod_vals fields - should be filled in. The mod_op field is ignored unless ORed - with the constant LDAP_MOD_BVALUES, used to select the - mod_bvalues case of the mod_vals union. - - Note that the parent of the entry must already exist. - - ldap_add_s() is synchronous, returning the LDAP error code indicating - the outcome of the operation. - - ldap_add() is asynchronous, returning the message id of the operation - it initiates, or -1 in case of trouble. The result of the operation - can be obtained by calling ldap_result(). - -4.10. Deleting an entry - - ldap_delete() and ldap_delete_s() are used to delete entries from the - LDAP directory. - - int ldap_delete( LDAP *ld, char *dn ); - - int ldap_delete_s( LDAP *ld, char *dn ); - - - - - - -Howes & Smith Informational [Page 10] - -RFC 1823 LDAP API August 1995 - - - Parameters are: - - ld The connection handle; - - dn The name of the entry to delete. - - Note that the entry to delete must be a leaf entry (i.e., it must - have no children). Deletion of entire subtrees is not supported by - LDAP. - - ldap_delete_s() is synchronous, returning the LDAP error code - indicating the outcome of the operation. - - ldap_delete() is asynchronous, returning the message id of the - operation it initiates, or -1 in case of trouble. The result of the - operation can be obtained by calling ldap_result(). - -5. Calls for abandoning an operation - - ldap_abandon() is used to abandon an operation in progress. - - int ldap_abandon( LDAP *ld, int msgid ); - - ldap_abandon() abandons the operation with message id msgid. It - returns zero if the abandon was successful, -1 otherwise. After a - successful call to ldap_abandon(), results with the given message id - are never returned from a call to ldap_result(). - -6. Calls for obtaining results - - ldap_result() is used to obtain the result of a previous - asynchronously initiated operation. ldap_msgfree() frees the results - obtained from a previous call to ldap_result(), or a synchronous - search routine. - - int ldap_result( - LDAP *ld, - int msgid, - int all, - struct timeval *timeout, - LDAPMessage **res - ); - - int ldap_msgfree( LDAPMessage *res ); - - - - - - - -Howes & Smith Informational [Page 11] - -RFC 1823 LDAP API August 1995 - - - Parameters are: - - ld The connection handle; - - msgid The message id of the operation whose results are to be - returned, or the constant LDAP_RES_ANY if any result is - desired; - - all A boolean parameter that only has meaning for search - results. If non-zero it indicates that all results of a - search should be retrieved before any are returned. If zero, - search results (entries) will be returned one at a time as - they arrive; - - timeout A timeout specifying how long to wait for results to be - returned. A NULL value causes ldap_result() to block until - results are available. A timeout value of zero second - specifies a polling behavior; - - res For ldap_result(), a result parameter that will contain the - result(s) of the operation. For ldap_msgfree(), the result - chain to be freed, obtained from a previous call to - ldap_result() or ldap_search_s() or ldap_search_st(). - - Upon successful completion, ldap_result() returns the type of the - result returned in the res parameter. This will be one of the - following constants. - - LDAP_RES_BIND - LDAP_RES_SEARCH_ENTRY - LDAP_RES_SEARCH_RESULT - LDAP_RES_MODIFY - LDAP_RES_ADD - LDAP_RES_DELETE - LDAP_RES_MODRDN - LDAP_RES_COMPARE - - ldap_result() returns 0 if the timeout expired and -1 if an error - occurs, in which case the ld_errno field of the ld structure will be - set accordingly. - - ldap_msgfree() frees the result structure pointed to be res and - returns the type of the message it freed. - - - - - - - - -Howes & Smith Informational [Page 12] - -RFC 1823 LDAP API August 1995 - - -7. Calls for error handling - - The following calls are used to interpret errors returned by other - LDAP API routines. - - int ldap_result2error( - LDAP *ld, - LDAPMessage *res, - int freeit - ); - - char *ldap_err2string( int err ); - - void ldap_perror( LDAP *ld, char *msg ); - - Parameters are: - - ld The connection handle; - - res The result of an LDAP operation as returned by ldap_result() - or one of the synchronous API operation calls; - - freeit A boolean parameter indicating whether the res parameter - should be freed (non-zero) or not (zero); - - err An LDAP error code, as returned by ldap_result2error() or - one of the synchronous API operation calls; - - msg A message to be displayed before the LDAP error message. - - ldap_result2error() is used to convert the LDAP result message - obtained from ldap_result(), or the res parameter returned by one of - the synchronous API operation calls, into a numeric LDAP error code. - It also parses the ld_matched and ld_error portions of the result - message and puts them into the connection handle information. All the - synchronous operation routines call ldap_result2error() before - returning, ensuring that these fields are set correctly. The relevant - fields in the connection structue are: - - ld_matched In the event of an LDAP_NO_SUCH_OBJECT error return, this - parameter contains the extent of the DN matched; - - ld_error This parameter contains the error message sent in the - result by the LDAP server. - - ld_errno The LDAP error code indicating the outcome of the - operation. It is one of the following constants: - - - - -Howes & Smith Informational [Page 13] - -RFC 1823 LDAP API August 1995 - - - LDAP_SUCCESS - LDAP_OPERATIONS_ERROR - LDAP_PROTOCOL_ERROR - LDAP_TIMELIMIT_EXCEEDED - LDAP_SIZELIMIT_EXCEEDED - LDAP_COMPARE_FALSE - LDAP_COMPARE_TRUE - LDAP_STRONG_AUTH_NOT_SUPPORTED - LDAP_STRONG_AUTH_REQUIRED - LDAP_NO_SUCH_ATTRIBUTE - LDAP_UNDEFINED_TYPE - LDAP_INAPPROPRIATE_MATCHING - LDAP_CONSTRAINT_VIOLATION - LDAP_TYPE_OR_VALUE_EXISTS - LDAP_INVALID_SYNTAX - LDAP_NO_SUCH_OBJECT - LDAP_ALIAS_PROBLEM - LDAP_INVALID_DN_SYNTAX - LDAP_IS_LEAF - LDAP_ALIAS_DEREF_PROBLEM - LDAP_INAPPROPRIATE_AUTH - LDAP_INVALID_CREDENTIALS - LDAP_INSUFFICIENT_ACCESS - LDAP_BUSY - LDAP_UNAVAILABLE - LDAP_UNWILLING_TO_PERFORM - LDAP_LOOP_DETECT - LDAP_NAMING_VIOLATION - LDAP_OBJECT_CLASS_VIOLATION - LDAP_NOT_ALLOWED_ON_NONLEAF - LDAP_NOT_ALLOWED_ON_RDN - LDAP_ALREADY_EXISTS - LDAP_NO_OBJECT_CLASS_MODS - LDAP_RESULTS_TOO_LARGE - LDAP_OTHER - LDAP_SERVER_DOWN - LDAP_LOCAL_ERROR - LDAP_ENCODING_ERROR - LDAP_DECODING_ERROR - LDAP_TIMEOUT - LDAP_AUTH_UNKNOWN - LDAP_FILTER_ERROR - LDAP_USER_CANCELLED - LDAP_PARAM_ERROR - LDAP_NO_MEMORY - - - - - - -Howes & Smith Informational [Page 14] - -RFC 1823 LDAP API August 1995 - - - ldap_err2string() is used to convert a numeric LDAP error code, as - returned by ldap_result2error() or one of the synchronous API - operation calls, into an informative NULL-terminated character string - message describing the error. It returns a pointer to static data. - - ldap_perror() is used to print the message supplied in msg, followed - by an indication of the error contained in the ld_errno field of the - ld connection handle, to standard error. - -8. Calls for parsing search entries - - The following calls are used to parse the entries returned by - ldap_search() and friends. These entries are returned in an opaque - structure that should only be accessed by calling the routines - described below. Routines are provided to step through the entries - returned, step through the attributes of an entry, retrieve the name - of an entry, and retrieve the values associated with a given - attribute in an entry. - -8.1. Stepping through a set of entries - - The ldap_first_entry() and ldap_next_entry() routines are used to - step through a set of entries in a search result. - ldap_count_entries() is used to count the number of entries returned. - - LDAPMesage *ldap_first_entry( LDAP *ld, LDAPMessage *res ); - - LDAPMesage *ldap_next_entry( LDAP *ld, LDAPMessage *entry ); - - int ldap_count_entries( LDAP *ld, LDAPMessage *res ); - - Parameters are: - - ld The connection handle; - - res The search result, as obtained by a call to one of the syn- - chronous search routines or ldap_result(); - - entry The entry returned by a previous call to ldap_first_entry() or - ldap_next_entry(). - - ldap_first_entry() and ldap_next_entry() will return NULL when no - more entries exist to be returned. NULL is also returned if an error - occurs while stepping through the entries, in which case the ld_errno - field of the ld connection handle will be set to indicate the error. - - ldap_count_entries() returns the number of entries contained in a - chain of entries. It can also be used to count the number of entries - - - -Howes & Smith Informational [Page 15] - -RFC 1823 LDAP API August 1995 - - - that remain in a chain if called with an entry returned by - ldap_first_entry() or ldap_next_entry(). - -8.2. Stepping through the attributes of an entry - - The ldap_first_attribute() and ldap_next_attribute() calls are used - to step through the list of attribute types returned with an entry. - - char *ldap_first_attribute( - LDAP *ld, - LDAPMessage *entry, - void **ptr - ); - char *ldap_next_attribute( - LDAP *ld, - LDAPMessage *entry, - void *ptr - ); - - Parameters are: - - ld The connection handle; - - entry The entry whose attributes are to be stepped through, as - returned by ldap_first_entry() or ldap_next_entry(); - - ptr In ldap_first_attribute(), the address of a pointer used - internally to keep track of the current position in the entry. - In ldap_next_attribute(), the pointer returned by a previous - call to ldap_first_attribute(). - - ldap_first_attribute() and ldap_next_attribute() will return NULL - when the end of the attributes is reached, or if there is an error, - in which case the ld_errno field in the ld connection handle will be - set to indicate the error. - - Both routines return a pointer to a per-connection buffer containing - the current attribute name. This should be treated like static data. - ldap_first_attribute() will allocate and return in ptr a pointer to a - BerElement used to keep track of the current position. This pointer - should be passed in subsequent calls to ldap_next_attribute() to step - through the entry's attributes. - - The attribute names returned are suitable for passing in a call to - ldap_get_values() and friends to retrieve the associated values. - - - - - - -Howes & Smith Informational [Page 16] - -RFC 1823 LDAP API August 1995 - - -8.3. Retrieving the values of an attribute - - ldap_get_values() and ldap_get_values_len() are used to retrieve the - values of a given attribute from an entry. ldap_count_values() and - ldap_count_values_len() are used to count the returned values. - ldap_value_free() and ldap_value_free_len() are used to free the - values. - - typedef struct berval { - unsigned long bv_len; - char *bv_val; - }; - - char **ldap_get_values( - LDAP *ld, - LDAPMessage *entry, - char *attr - ); - - struct berval **ldap_get_values_len( - LDAP *ld, - LDAPMessage *entry, - char *attr - ); - - int ldap_count_values( char **vals ); - - int ldap_count_values_len( struct berval **vals ); - - int ldap_value_free( char **vals ); - - int ldap_value_free_len( struct berval **vals ); - - Parameters are: - - ld The connection handle; - - entry The entry from which to retrieve values, as returned by - ldap_first_entry() or ldap_next_entry(); - - attr The attribute whose values are to be retrieved, as returned by - ldap_first_attribute() or ldap_next_attribute(), or a caller- - supplied string (e.g., "mail"); - - vals The values returned by a previous call to ldap_get_values() or - ldap_get_values_len(). - - - - - -Howes & Smith Informational [Page 17] - -RFC 1823 LDAP API August 1995 - - - Two forms of the various calls are provided. The first form is only - suitable for use with non-binary character string data only. The - second _len form is used with any kind of data. - - Note that the values returned are malloc'ed and should be freed by - calling either ldap_value_free() or ldap_value_free_len() when no - longer in use. - -8.4. Retrieving the name of an entry - - ldap_get_dn() is used to retrieve the name of an entry. - ldap_explode_dn() is used to break up the name into its component - parts. ldap_dn2ufn() is used to convert the name into a more "user - friendly" format. - - char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ); - - char **ldap_explode_dn( char *dn, int notypes ); - - char *ldap_dn2ufn( char *dn ); - - Parameters are: - - ld The connection handle; - - entry The entry whose name is to be retrieved, as returned by - ldap_first_entry() or ldap_next_entry(); - - dn The dn to explode, as returned by ldap_get_dn(); - - notypes A boolean parameter, if non-zero indicating that the dn com- - ponents should have their type information stripped off - (i.e., "cn=Babs" would become "Babs"). - - ldap_get_dn() will return NULL if there is some error parsing the dn, - setting ld_errno in the ld connection handle to indicate the error. - It returns a pointer to malloc'ed space that the caller should free - by calling free() when it is no longer in use. Note the format of - the DNs returned is given by [4]. - - ldap_explode_dn() returns a char * array containing the RDN - components of the DN supplied, with or without types as indicated by - the notypes parameter. The array returned should be freed when it is - no longer in use by calling ldap_value_free(). - - ldap_dn2ufn() converts the DN into the user friendly format described - in [5]. The UFN returned is malloc'ed space that should be freed by a - call to free() when no longer in use. - - - -Howes & Smith Informational [Page 18] - -RFC 1823 LDAP API August 1995 - - -9. Security Considerations - - LDAP supports minimal security during connection authentication. - -10. Acknowledgements - - This material is based upon work supported by the National Science - Foundation under Grant No. NCR-9416667. - -11. Bibliography - - [1] The Directory: Selected Attribute Syntaxes. CCITT, - Recommendation X.520. - - [2] Howes, T., Kille, S., Yeong, W., and C. Robbins, "The String - Representation of Standard Attribute Syntaxes", University of - Michigan, ISODE Consortium, Performance Systems International, - NeXor Ltd., RFC 1778, March 1995. - - [3] Howes, T., "A String Representation of LDAP Search Filters", RFC - 1558, University of Michigan, December 1993. - - [4] Kille, S., "A String Representation of Distinguished Names", RFC - 1779, ISODE Consortium, March 1995. - - [5] Kille, S., "Using the OSI Directory to Achieve User Friendly - Naming", RFC 1781, ISODE Consortium, March 1995. - - [6] S.P. Miller, B.C. Neuman, J.I. Schiller, J.H. Saltzer, "Kerberos - Authentication and Authorization System", MIT Project Athena - Documentation Section E.2.1, December 1987 - - [7] Yeong, W., Howes, T., and S. Kille, "Lightweight Directory Access - Protocol," RFC 1777, Performance Systems International, - University of Michigan, ISODE Consortium, March 1995. - - - - - - - - - - - - - - - - -Howes & Smith Informational [Page 19] - -RFC 1823 LDAP API August 1995 - - -12. Authors' Addresses - - Tim Howes - University of Michigan - ITD Research Systems - 535 W William St. - Ann Arbor, MI 48103-4943 - USA - - Phone: +1 313 747-4454 - EMail: tim@umich.edu - - - Mark Smith - University of Michigan - ITD Research Systems - 535 W William St. - Ann Arbor, MI 48103-4943 - USA - - Phone: +1 313 764-2277 - EMail: mcs@umich.edu - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Howes & Smith Informational [Page 20] - -RFC 1823 LDAP API August 1995 - - -13. Appendix A - Sample LDAP API Code - - #include - - main() - { - LDAP *ld; - LDAPMessage *res, *e; - int i; - char *a, *dn; - void *ptr; - char **vals; - - /* open a connection */ - if ( (ld = ldap_open( "dotted.host.name", LDAP_PORT )) - == NULL ) - exit( 1 ); - - /* authenticate as nobody */ - if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) { - ldap_perror( ld, "ldap_simple_bind_s" ); - exit( 1 ); - } - - /* search for entries with cn of "Babs Jensen", - return all attrs */ - if ( ldap_search_s( ld, "o=University of Michigan, c=US", - LDAP_SCOPE_SUBTREE, "(cn=Babs Jensen)", NULL, 0, &res ) - != LDAP_SUCCESS ) { - ldap_perror( ld, "ldap_search_s" ); - exit( 1 ); - } - - /* step through each entry returned */ - for ( e = ldap_first_entry( ld, res ); e != NULL; - e = ldap_next_entry( ld, e ) ) { - /* print its name */ - dn = ldap_get_dn( ld, e ); - printf( "dn: %s0, dn ); - free( dn ); - - /* print each attribute */ - for ( a = ldap_first_attribute( ld, e, &ptr ); - a != NULL; - a = ldap_next_attribute( ld, e, ptr ) ) { - printf( "attribute: %s0, a ); - - /* print each value */ - - - -Howes & Smith Informational [Page 21] - -RFC 1823 LDAP API August 1995 - - - vals = ldap_get_values( ld, e, a ); - for ( i = 0; vals[i] != NULL; i++ ) { - printf( "value: %s0, vals[i] ); - } - ldap_value_free( vals ); - } - } - /* free the search results */ - ldap_msgfree( res ); - - /* close and free connection resources */ - ldap_unbind( ld ); - } - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Howes & Smith Informational [Page 22] - diff --git a/doc/rfc/rfc2218.txt b/doc/rfc/rfc2218.txt deleted file mode 100644 index 8fa67a9d5d..0000000000 --- a/doc/rfc/rfc2218.txt +++ /dev/null @@ -1,451 +0,0 @@ - - - - - - -Network Working Group T. Genovese -Request for Comments: 2218 Microsoft -Category: Standards Track B. Jennings - Sandia National Laboratory - October 1997 - - - A Common Schema for the Internet White Pages Service - - -Status of this Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Abstract - - This work is the result of the IETF Integrated Directory Services - (IDS) Working Group. The IDS Working Group proposes a standard - specification for a simple Internet White Pages service by defining a - common schema for use by the various White Pages servers. This - schema is independent of specific implementations of the White Pages - service. - - This document specifies the minimum set of core attributes of a White - Pages entry for an individual and describes how new objects with - those attributes can be defined and published. It does not describe - how to represent other objects in the White Pages service. Further, - it does not address the search sort expectations within a particular - service. - -1.0 Introduction to IWPS - - The Internet community has stated a need for the development and - deployment of a White Pages service for use in locating information - about people in the Internet [PA94]. To facilitate interoperability - and to provide a common user experience, the Internet White Pages - Service (IWPS) must have a common set of information about each - person. - - A common user object would allow a user to go between implementations - of the service and to expect consistency in the types of information - provided. A common user object would also provide developers with an - unambigious method of representing the information managed by the - service. - - - -Genovese & Jennings Standards Track [Page 1] - -RFC 2218 Common Schema for IWPS October 1997 - - - This document will focus only on common information modeling issues - to which all IWPS providers must conform. - -2.0 Scope - - This document establishes the set of attributes that specify the - Common User Information Object for the IWPS. It does not attempt to - be an exhaustive specification of all objects that may be stored in - the IWPS. The process used by this document to define the user object - is recommended to be used to define other information objects used in - the IWPS. - - All conforming implementations must support at the minimum, the core - attributes listed in Section 5.0. Implementations may include local - attributes in addition to the core set and still be considered "in - conformance". - - This document will not specify rules with respect to information - privacy. Each country has its own set of laws and practices. - Previous work covering this area has been done by the North American - Directory Forum (NADF), whose publication [NADF92] contain - recommendations for registrants' rights in both the USA and Canada. - - This document does not specify a Directory access protocol (i.e. - whois++, LDAP, DAP, etc.). - -3.0 IWPS Schema Considerations - - The description of the IWPS information object consists of the - following requirements: - - 1. Syntax for definition/representation of information - object templates. - 2. Publication of information object templates, etc. - 3. Database structure or schema. - - Items 1 and 2 will be covered in this document. Because database - structure can potentially restrict implementations (i.e. X.500 schema - based versus DNS schema based) it will be treated as a separate - research topic and will not be defined in this paper. - -4.0 Syntax for Definition/Representation of Information Object - Templates - - A clear, precise, and consistent method must be used when discussing - information object templates and their associated attributes. - Therefore, this document makes uses of the previously defined syntax - used by LDAP. To avoid restrictions on implementations of the IWPS, - - - -Genovese & Jennings Standards Track [Page 2] - -RFC 2218 Common Schema for IWPS October 1997 - - - some syntax are listed as requirements vs specific encodings. The - general IWPS syntax is included in section 6.0 for reference. - - The IWPS Person Object specifies a limited set of recommended - attributes that a White Pages Service must include. Storage of user - attributes are a local issue, therefore, this memo suggests storage - sizes but not storage types. - - This document lists the syntax with the attributes for developers of - user interface (UIs) to use as a reference, but it does not specify - how the UI should display these attributes. - - Attributes that contain multiple-line text (i.e. Address) must use - the procedure defined in RFC 822 in section 3.1.1 on "folding" long - header lines [RFC-822]. - -5.0 Information Object Template Definitions - - This section describes the IWPS Person Information Object Template - and its associated attributes. The Person Object is a simple list of - attributes, no structure nor object inheritance is implied. - - IWPS client applications should use the following size - recommendations as the maximum sizes of the attributes. However, - applications should be able to handle attributes of arbitrary size, - returned by a server which may not comply with these recommendation. - All size recommendations are in characters. - - Note: Because many characters in many encodings require more than one - byte, the size recommendations cannot be interpreted as sizes in - bytes. - - This set of attributes describes information types, and are not - defined attributes in a particular schema. Any technology deploying - a White Page service (WHOIS ++, LDAP, vCard, etc.) will need to - publish as a companion document, their specific schema detailing how - the general attributes of the White Pages schema are expressed. - - SPECIAL CONSIDERATIONS - - Phone number: The full international form is recommended; - i.e. +1 206 703 0852. The field may contain - additional information following the phone - number. For example: - - +1 800 759 7243 #123456 - +1 505 882 8080 ext. 30852 - - - - -Genovese & Jennings Standards Track [Page 3] - -RFC 2218 Common Schema for IWPS October 1997 - - - Email address: Is multivalued. - - Certificate: Is multivalued. - - Common Name: Is multivalued. - - Language Spoken: Is multivalued. - - THE INFORMATION OBJECT TEMPLATE FOR THE IWPS PERSON - - --General Attributes -- - - Field Name Size Syntax - - Email 360 Mailbox - Cert 4000 Certificate - Home Page 128 URI - Common Name 64 WhitepageString - Given Name 48 WhitepageString - Surname 48 WhitepageString - Organization 64 WhitepageString - Locality 20 WhitepageString - Country 2 WhitepageString (ISO 3166) - Language Spoken 128 WhitepageString (RFC 1766) - - --Personal Attributes - - Personal Phone 30 PrintableString - Personal Fax 30 PrintableString - Personal Mobile Phone 30 PrintableString - Personal Pager Number 30 PrintableString - Personal Postal Address 255 Address - Description 255 WhitepageString - - --Organizational Attributes - - Title 64 WhitepageString - Office Phone 30 PrintableString - Office Fax 30 PrintableString - Office Mobile Phone 30 PrintableString - Office Pager 30 PrintableString - Office Postal Address 255 Address - - --Ancillary - - Creation Date 24 GeneralizedTime - Creator Name 255 URI - Modified Date 24 GeneralizedTime - - - -Genovese & Jennings Standards Track [Page 4] - -RFC 2218 Common Schema for IWPS October 1997 - - - Modifier Name 255 URI - -6.0 IWPS Person Information Object Template Syntax - - This section defines the syntax used by the IWPS person information - object template. It is copied in whole from the LDAP attribute - working document with some modification for completeness. - - Certificate: - - The certificate field is intended to hold any kind of certificate; - X.509 certificates are one example. A specific implementation will - specify how to indicate the type of certificate when describing - the mapping of the IWPS schema onto the implementation schema. - - WhitepageString: - - This syntax must be able to encode arbitrary ISO 10646 characters. - One such encoding is the UTF-8 encoding [UTF-8]. - - GeneralizedTime: - - Values of this syntax are encoded as printable strings, - represented as specified in X.208. Note that the time zone must - be specified. It is strongly recommended that Zulu time zone be - used. For example: - - 199412161032Z - - Mailbox: - - here are many kinds of mailbox addresses, including X.400 and - Internet mailbox addresses. The implementation must clearly - distinguish between different types of mailbox address, for - instance by using a textual refix or a set of attribute types. - There must be a way to represent any mailbox type. - - Address: - - According to Universal Postal Union standards, this field must be - able to represent at least 6 lines of 40 characters. - - PrintableString: - - The encoding of a value with PrintableString syntax is the string - value itself. PrintableString is limited to the characters in - production

. Where production

is described by the - following: - - - -Genovese & Jennings Standards Track [Page 5] - -RFC 2218 Common Schema for IWPS October 1997 - - - ::= 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | - 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | - 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z' | 'A' | - 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | - 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | - 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z' - - ::= '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' - - -

::= | | ''' | '(' | ')' | '+' | ',' | '-' | '.' | - '/' | ':' | '?' | ' ' - -7.0 Publication of IWPS Information Object Templates. - - The Working Group recommends that all information object templates - used for the IWPS be published. - - Individual organizations may define information object templates that - are local in scope as required to meet local organizational needs. - All information that the organization wishes to be part of the IWPS - must use a published IWPS information object template. - -8.0 Data Privacy - - Each country, and each state within the US, has legislation defining - information privacy. The suggested attributes in Section 5.0 may be - considered private and the directory administrator is strongly - advised to verify the privacy legislation for his domain. - - As suggested in "Privacy and Accuracy in NIC Databases" [RFC-1355], - each directory provider should provide a clear statement of the - purpose of the directory, the information that should be contained in - it, and a privacy policy associated with that information. This - policy should include restrictions for data dissemination. - - This policy is strongly recommended for the US and Canada and - required by many countries in the European Community for data - sharing. - -9.0 Data Integrity - - Data Integrity was first addressed in RFC 1107 [KS89], which states - "a White Pages service will not be used, if the information it - provides is out of date or incorrect." Therefore, any production - IWPS provider must insure that all data is reasonably correct and - up-to-date. - - - - -Genovese & Jennings Standards Track [Page 6] - -RFC 2218 Common Schema for IWPS October 1997 - - - The Ancillary Attributes of the IWPS person template denote the - information's source and date of origin, and the source and date of - its latest modification. They provide the user with some measurement - of the quality of data making it easy to determine the owner and - freshness of the data retrieved. - - The IWPS User Agent must be able to retrieve and display Ancillary - Attributes. Retrieval and display may be done as separate - operations. - - The Ancillary Attributes are recommended as the minimum set of - attributes for any new information object template. Each IWPS server - may individually decide whether to support the storage and retrieval - of this data. - - The Ancillary Attributes (also defined in Section 5.0) provide the - following information about its associated information object: - - 1. The date and time the entry was created; Creation Date. - - 2. Owner or individual responsible for the data creation; - Creator Name. - - 3. The date and time of the last modification; - Modified Date. - - 4. Individual responsible for the last modification; - Modifier Name. - -10.0 Security Considerations - - Security is implementation and deployment specific and as such is not - addressed in this memo. Security must ensure that the constraints - mentioned in the Data Privacy Section 8.0 are complied with. - -11.0 References - - [KS89] Sollins, K., "A Plan for Internet Directory Services", RFC - 1107, Laboratory for Computer Science, MIT, July 1989. - - [NADF92] North American Directory Forum, "User Bill of Rights for - entries and listings in the Public Directory', RFC 1295, - North American Directory Forum, January 1992. - - - - - - - - -Genovese & Jennings Standards Track [Page 7] - -RFC 2218 Common Schema for IWPS October 1997 - - - [PA94] Postel, J., and C. Anderson, "WHITE PAGES MEETING REPORT", - RFC 1588, University of Southern California, February 1994. - - [RFC-822] Crocker, D., "Standard for the Format of ARPA Internet - Text Messages", STD 11, RFC 822, August 1982. - - [RFC-1355] Curran, J., and A. Marine, "Privacy and Accuracy Issues - in Network Information Center Databases", FYI 15, RFC 1355, August - 1992. - - [UCS] Universal Multiple-Octet Coded Character Set (UCS) - - Architecture and Basic Multilingual Plane, ISO/IEC 10646-1, 1993. - - [RFC-1766] Alvestrand, H., "Tags for the Identification of - Languages", RFC 1766, March 1995. - - [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO 10646", - Work in Progress. - -11.0 Authors' Addresses - - Tony Genovese - The Microsoft Corporation - One Microsoft Way - Redmond, Washington 98007 - USA - - Phone: (206) 703-0852 - EMail: TonyG@Microsoft.com - - - Barbara Jennings - Sandia National Laboratories - Albuquerque, New Mexico 87106 - USA - - Phone: (505) 845-8554 - EMail: jennings@sandia.gov - - - - - - - - - - - - - -Genovese & Jennings Standards Track [Page 8] - diff --git a/doc/rfc/rfc2657.txt b/doc/rfc/rfc2657.txt deleted file mode 100644 index d23a877081..0000000000 --- a/doc/rfc/rfc2657.txt +++ /dev/null @@ -1,675 +0,0 @@ - - - - - - -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] - diff --git a/doc/rfc/rfc2831.txt b/doc/rfc/rfc2831.txt deleted file mode 100644 index c1a54c4944..0000000000 --- a/doc/rfc/rfc2831.txt +++ /dev/null @@ -1,1515 +0,0 @@ - - - - - - -Network Working Group P. Leach -Request for Comments: 2831 Microsoft -Category: Standards Track C. Newman - Innosoft - May 2000 - - - Using Digest Authentication as a SASL Mechanism - -Status of this Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2000). All Rights Reserved. - -Abstract - - This specification defines how HTTP Digest Authentication [Digest] - can be used as a SASL [RFC 2222] mechanism for any protocol that has - a SASL profile. It is intended both as an improvement over CRAM-MD5 - [RFC 2195] and as a convenient way to support a single authentication - mechanism for web, mail, LDAP, and other protocols. - -Table of Contents - - 1 INTRODUCTION.....................................................2 - 1.1 CONVENTIONS AND NOTATION......................................2 - 1.2 REQUIREMENTS..................................................3 - 2 AUTHENTICATION...................................................3 - 2.1 INITIAL AUTHENTICATION........................................3 - 2.1.1 Step One...................................................3 - 2.1.2 Step Two...................................................6 - 2.1.3 Step Three................................................12 - 2.2 SUBSEQUENT AUTHENTICATION....................................12 - 2.2.1 Step one..................................................13 - 2.2.2 Step Two..................................................13 - 2.3 INTEGRITY PROTECTION.........................................13 - 2.4 CONFIDENTIALITY PROTECTION...................................14 - 3 SECURITY CONSIDERATIONS.........................................15 - 3.1 AUTHENTICATION OF CLIENTS USING DIGEST AUTHENTICATION........15 - 3.2 COMPARISON OF DIGEST WITH PLAINTEXT PASSWORDS................16 - 3.3 REPLAY ATTACKS...............................................16 - - - -Leach & Newman Standards Track [Page 1] - -RFC 2831 Digest SASL Mechanism May 2000 - - - 3.4 ONLINE DICTIONARY ATTACKS....................................16 - 3.5 OFFLINE DICTIONARY ATTACKS...................................16 - 3.6 MAN IN THE MIDDLE............................................17 - 3.7 CHOSEN PLAINTEXT ATTACKS.....................................17 - 3.8 SPOOFING BY COUNTERFEIT SERVERS..............................17 - 3.9 STORING PASSWORDS............................................17 - 3.10 MULTIPLE REALMS.............................................18 - 3.11 SUMMARY.....................................................18 - 4 EXAMPLE.........................................................18 - 5 REFERENCES......................................................20 - 6 AUTHORS' ADDRESSES..............................................21 - 7 ABNF............................................................21 - 7.1 AUGMENTED BNF................................................21 - 7.2 BASIC RULES..................................................23 - 8 SAMPLE CODE.....................................................25 - 9 FULL COPYRIGHT STATEMENT........................................27 - -1 Introduction - - This specification describes the use of HTTP Digest Access - Authentication as a SASL mechanism. The authentication type - associated with the Digest SASL mechanism is "DIGEST-MD5". - - This specification is intended to be upward compatible with the - "md5-sess" algorithm of HTTP/1.1 Digest Access Authentication - specified in [Digest]. The only difference in the "md5-sess" - algorithm is that some directives not needed in a SASL mechanism have - had their values defaulted. - - There is one new feature for use as a SASL mechanism: integrity - protection on application protocol messages after an authentication - exchange. - - Also, compared to CRAM-MD5, DIGEST-MD5 prevents chosen plaintext - attacks, and permits the use of third party authentication servers, - mutual authentication, and optimized reauthentication if a client has - recently authenticated to a server. - -1.1 Conventions and Notation - - This specification uses the same ABNF notation and lexical - conventions as HTTP/1.1 specification; see appendix A. - - Let { a, b, ... } be the concatenation of the octet strings a, b, ... - - Let H(s) be the 16 octet MD5 hash [RFC 1321] of the octet string s. - - - - - -Leach & Newman Standards Track [Page 2] - -RFC 2831 Digest SASL Mechanism May 2000 - - - Let KD(k, s) be H({k, ":", s}), i.e., the 16 octet hash of the string - k, a colon and the string s. - - Let HEX(n) be the representation of the 16 octet MD5 hash n as a - string of 32 hex digits (with alphabetic characters always in lower - case, since MD5 is case sensitive). - - Let HMAC(k, s) be the 16 octet HMAC-MD5 [RFC 2104] of the octet - string s using the octet string k as a key. - - The value of a quoted string constant as an octet string does not - include any terminating null character. - -1.2 Requirements - - 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 RFC 2119 [RFC 2119]. - - An implementation is not compliant if it fails to satisfy one or more - of the MUST level requirements for the protocols it implements. An - implementation that satisfies all the MUST level and all the SHOULD - level requirements for its protocols is said to be "unconditionally - compliant"; one that satisfies all the MUST level requirements but - not all the SHOULD level requirements for its protocols is said to be - "conditionally compliant." - -2 Authentication - - The following sections describe how to use Digest as a SASL - authentication mechanism. - -2.1 Initial Authentication - - If the client has not recently authenticated to the server, then it - must perform "initial authentication", as defined in this section. If - it has recently authenticated, then a more efficient form is - available, defined in the next section. - -2.1.1 Step One - - The server starts by sending a challenge. The data encoded in the - challenge contains a string formatted according to the rules for a - "digest-challenge" defined as follows: - - - - - - - -Leach & Newman Standards Track [Page 3] - -RFC 2831 Digest SASL Mechanism May 2000 - - - digest-challenge = - 1#( realm | nonce | qop-options | stale | maxbuf | charset - algorithm | cipher-opts | auth-param ) - - realm = "realm" "=" <"> realm-value <"> - realm-value = qdstr-val - nonce = "nonce" "=" <"> nonce-value <"> - nonce-value = qdstr-val - qop-options = "qop" "=" <"> qop-list <"> - qop-list = 1#qop-value - qop-value = "auth" | "auth-int" | "auth-conf" | - token - stale = "stale" "=" "true" - maxbuf = "maxbuf" "=" maxbuf-value - maxbuf-value = 1*DIGIT - charset = "charset" "=" "utf-8" - algorithm = "algorithm" "=" "md5-sess" - cipher-opts = "cipher" "=" <"> 1#cipher-value <"> - cipher-value = "3des" | "des" | "rc4-40" | "rc4" | - "rc4-56" | token - auth-param = token "=" ( token | quoted-string ) - - The meanings of the values of the directives used above are as - follows: - - realm - Mechanistically, a string which can enable users to know which - username and password to use, in case they might have different - ones for different servers. Conceptually, it is the name of a - collection of accounts that might include the user's account. This - string should contain at least the name of the host performing the - authentication and might additionally indicate the collection of - users who might have access. An example might be - "registered_users@gotham.news.example.com". This directive is - optional; if not present, the client SHOULD solicit it from the - user or be able to compute a default; a plausible default might be - the realm supplied by the user when they logged in to the client - system. Multiple realm directives are allowed, in which case the - user or client must choose one as the realm for which to supply to - username and password. - - nonce - A server-specified data string which MUST be different each time a - digest-challenge is sent as part of initial authentication. It is - recommended that this string be base64 or hexadecimal data. Note - that since the string is passed as a quoted string, the - double-quote character is not allowed unless escaped (see section - 7.2). The contents of the nonce are implementation dependent. The - - - -Leach & Newman Standards Track [Page 4] - -RFC 2831 Digest SASL Mechanism May 2000 - - - security of the implementation depends on a good choice. It is - RECOMMENDED that it contain at least 64 bits of entropy. The nonce - is opaque to the client. This directive is required and MUST - appear exactly once; if not present, or if multiple instances are - present, the client should abort the authentication exchange. - - qop-options - A quoted string of one or more tokens indicating the "quality of - protection" values supported by the server. The value "auth" - indicates authentication; the value "auth-int" indicates - authentication with integrity protection; the value "auth-conf" - indicates authentication with integrity protection and encryption. - This directive is optional; if not present it defaults to "auth". - The client MUST ignore unrecognized options; if the client - recognizes no option, it should abort the authentication exchange. - - stale - The "stale" directive is not used in initial authentication. See - the next section for its use in subsequent authentications. This - directive may appear at most once; if multiple instances are - present, the client should abort the authentication exchange. - - maxbuf - A number indicating the size of the largest buffer the server is - able to receive when using "auth-int" or "auth-conf". If this - directive is missing, the default value is 65536. This directive - may appear at most once; if multiple instances are present, the - client should abort the authentication exchange. - - charset - This directive, if present, specifies that the server supports - UTF-8 encoding for the username and password. If not present, the - username and password must be encoded in ISO 8859-1 (of which - US-ASCII is a subset). The directive is needed for backwards - compatibility with HTTP Digest, which only supports ISO 8859-1. - This directive may appear at most once; if multiple instances are - present, the client should abort the authentication exchange. - - algorithm - This directive is required for backwards compatibility with HTTP - Digest., which supports other algorithms. . This directive is - required and MUST appear exactly once; if not present, or if - multiple instances are present, the client should abort the - authentication exchange. - - - - - - - -Leach & Newman Standards Track [Page 5] - -RFC 2831 Digest SASL Mechanism May 2000 - - - cipher-opts - A list of ciphers that the server supports. This directive must be - present exactly once if "auth-conf" is offered in the - "qop-options" directive, in which case the "3des" and "des" modes - are mandatory-to-implement. The client MUST ignore unrecognized - options; if the client recognizes no option, it should abort the - authentication exchange. - - des - the Data Encryption Standard (DES) cipher [FIPS] in cipher - block chaining (CBC) mode with a 56 bit key. - - 3des - the "triple DES" cipher in CBC mode with EDE with the same key - for each E stage (aka "two keys mode") for a total key length - of 112 bits. - - rc4, rc4-40, rc4-56 - the RC4 cipher with a 128 bit, 40 bit, and 56 bit key, - respectively. - - auth-param This construct allows for future extensions; it may appear - more than once. The client MUST ignore any unrecognized - directives. - - For use as a SASL mechanism, note that the following changes are made - to "digest-challenge" from HTTP: the following Digest options (called - "directives" in HTTP terminology) are unused (i.e., MUST NOT be sent, - and MUST be ignored if received): - - opaque - domain - - The size of a digest-challenge MUST be less than 2048 bytes. - -2.1.2 Step Two - - The client makes note of the "digest-challenge" and then responds - with a string formatted and computed according to the rules for a - "digest-response" defined as follows: - - - - - - - - - - - -Leach & Newman Standards Track [Page 6] - -RFC 2831 Digest SASL Mechanism May 2000 - - - digest-response = 1#( username | realm | nonce | cnonce | - nonce-count | qop | digest-uri | response | - maxbuf | charset | cipher | authzid | - auth-param ) - - username = "username" "=" <"> username-value <"> - username-value = qdstr-val - cnonce = "cnonce" "=" <"> cnonce-value <"> - cnonce-value = qdstr-val - nonce-count = "nc" "=" nc-value - nc-value = 8LHEX - qop = "qop" "=" qop-value - digest-uri = "digest-uri" "=" <"> digest-uri-value <"> - digest-uri-value = serv-type "/" host [ "/" serv-name ] - serv-type = 1*ALPHA - host = 1*( ALPHA | DIGIT | "-" | "." ) - serv-name = host - response = "response" "=" response-value - response-value = 32LHEX - LHEX = "0" | "1" | "2" | "3" | - "4" | "5" | "6" | "7" | - "8" | "9" | "a" | "b" | - "c" | "d" | "e" | "f" - cipher = "cipher" "=" cipher-value - authzid = "authzid" "=" <"> authzid-value <"> - authzid-value = qdstr-val - - - username - The user's name in the specified realm, encoded according to the - value of the "charset" directive. This directive is required and - MUST be present exactly once; otherwise, authentication fails. - - realm - The realm containing the user's account. This directive is - required if the server provided any realms in the - "digest-challenge", in which case it may appear exactly once and - its value SHOULD be one of those realms. If the directive is - missing, "realm-value" will set to the empty string when computing - A1 (see below for details). - - nonce - The server-specified data string received in the preceding - digest-challenge. This directive is required and MUST be present - exactly once; otherwise, authentication fails. - - - - - - -Leach & Newman Standards Track [Page 7] - -RFC 2831 Digest SASL Mechanism May 2000 - - - cnonce - A client-specified data string which MUST be different each time a - digest-response is sent as part of initial authentication. The - cnonce-value is an opaque quoted string value provided by the - client and used by both client and server to avoid chosen - plaintext attacks, and to provide mutual authentication. The - security of the implementation depends on a good choice. It is - RECOMMENDED that it contain at least 64 bits of entropy. This - directive is required and MUST be present exactly once; otherwise, - authentication fails. - - nonce-count - The nc-value is the hexadecimal count of the number of requests - (including the current request) that the client has sent with the - nonce value in this request. For example, in the first request - sent in response to a given nonce value, the client sends - "nc=00000001". The purpose of this directive is to allow the - server to detect request replays by maintaining its own copy of - this count - if the same nc-value is seen twice, then the request - is a replay. See the description below of the construction of - the response value. This directive may appear at most once; if - multiple instances are present, the client should abort the - authentication exchange. - - qop - Indicates what "quality of protection" the client accepted. If - present, it may appear exactly once and its value MUST be one of - the alternatives in qop-options. If not present, it defaults to - "auth". These values affect the computation of the response. Note - that this is a single token, not a quoted list of alternatives. - - serv-type - Indicates the type of service, such as "www" for web service, - "ftp" for FTP service, "smtp" for mail delivery service, etc. The - service name as defined in the SASL profile for the protocol see - section 4 of [RFC 2222], registered in the IANA registry of - "service" elements for the GSSAPI host-based service name form - [RFC 2078]. - - host - The DNS host name or IP address for the service requested. The - DNS host name must be the fully-qualified canonical name of the - host. The DNS host name is the preferred form; see notes on server - processing of the digest-uri. - - - - - - - -Leach & Newman Standards Track [Page 8] - -RFC 2831 Digest SASL Mechanism May 2000 - - - serv-name - Indicates the name of the service if it is replicated. The service - is considered to be replicated if the client's service-location - process involves resolution using standard DNS lookup operations, - and if these operations involve DNS records (such as SRV, or MX) - which resolve one DNS name into a set of other DNS names. In this - case, the initial name used by the client is the "serv-name", and - the final name is the "host" component. For example, the incoming - mail service for "example.com" may be replicated through the use - of MX records stored in the DNS, one of which points at an SMTP - server called "mail3.example.com"; it's "serv-name" would be - "example.com", it's "host" would be "mail3.example.com". If the - service is not replicated, or the serv-name is identical to the - host, then the serv-name component MUST be omitted. - - digest-uri - Indicates the principal name of the service with which the client - wishes to connect, formed from the serv-type, host, and serv-name. - For example, the FTP service on "ftp.example.com" would have a - "digest-uri" value of "ftp/ftp.example.com"; the SMTP server from - the example above would have a "digest-uri" value of - "smtp/mail3.example.com/example.com". - - Servers SHOULD check that the supplied value is correct. This will - detect accidental connection to the incorrect server. It is also so - that clients will be trained to provide values that will work with - implementations that use a shared back-end authentication service - that can provide server authentication. - - The serv-type component should match the service being offered. The - host component should match one of the host names of the host on - which the service is running, or it's IP address. Servers SHOULD NOT - normally support the IP address form, because server authentication - by IP address is not very useful; they should only do so if the DNS - is unavailable or unreliable. The serv-name component should match - one of the service's configured service names. - - This directive may appear at most once; if multiple instances are - present, the client should abort the authentication exchange. - - Note: In the HTTP use of Digest authentication, the digest-uri is the - URI (usually a URL) of the resource requested -- hence the name of - the directive. - - response - A string of 32 hex digits computed as defined below, which proves - that the user knows a password. This directive is required and - MUST be present exactly once; otherwise, authentication fails. - - - -Leach & Newman Standards Track [Page 9] - -RFC 2831 Digest SASL Mechanism May 2000 - - - maxbuf - A number indicating the size of the largest buffer the client is - able to receive. If this directive is missing, the default value - is 65536. This directive may appear at most once; if multiple - instances are present, the server should abort the authentication - exchange. - - charset - This directive, if present, specifies that the client has used - UTF-8 encoding for the username and password. If not present, the - username and password must be encoded in ISO 8859-1 (of which - US-ASCII is a subset). The client should send this directive only - if the server has indicated it supports UTF-8. The directive is - needed for backwards compatibility with HTTP Digest, which only - supports ISO 8859-1. - - LHEX - 32 hex digits, where the alphabetic characters MUST be lower case, - because MD5 is not case insensitive. - - cipher - The cipher chosen by the client. This directive MUST appear - exactly once if "auth-conf" is negotiated; if required and not - present, authentication fails. - - authzid - The "authorization ID" as per RFC 2222, encoded in UTF-8. This - directive is optional. If present, and the authenticating user has - sufficient privilege, and the server supports it, then after - authentication the server will use this identity for making all - accesses and access checks. If the client specifies it, and the - server does not support it, then the response-value will be - incorrect, and authentication will fail. - - The size of a digest-response MUST be less than 4096 bytes. - -2.1.2.1 Response-value - - The definition of "response-value" above indicates the encoding for - its value -- 32 lower case hex characters. The following definitions - show how the value is computed. - - Although qop-value and components of digest-uri-value may be - case-insensitive, the case which the client supplies in step two is - preserved for the purpose of computing and verifying the - response-value. - - response-value = - - - -Leach & Newman Standards Track [Page 10] - -RFC 2831 Digest SASL Mechanism May 2000 - - - HEX( KD ( HEX(H(A1)), - { nonce-value, ":" nc-value, ":", - cnonce-value, ":", qop-value, ":", HEX(H(A2)) })) - - If authzid is specified, then A1 is - - - A1 = { H( { username-value, ":", realm-value, ":", passwd } ), - ":", nonce-value, ":", cnonce-value, ":", authzid-value } - - If authzid is not specified, then A1 is - - - A1 = { H( { username-value, ":", realm-value, ":", passwd } ), - ":", nonce-value, ":", cnonce-value } - - where - - passwd = *OCTET - - The "username-value", "realm-value" and "passwd" are encoded - according to the value of the "charset" directive. If "charset=UTF-8" - is present, and all the characters of either "username-value" or - "passwd" are in the ISO 8859-1 character set, then it must be - converted to ISO 8859-1 before being hashed. This is so that - authentication databases that store the hashed username, realm and - password (which is common) can be shared compatibly with HTTP, which - specifies ISO 8859-1. A sample implementation of this conversion is - in section 8. - - If the "qop" directive's value is "auth", then A2 is: - - A2 = { "AUTHENTICATE:", digest-uri-value } - - If the "qop" value is "auth-int" or "auth-conf" then A2 is: - - A2 = { "AUTHENTICATE:", digest-uri-value, - ":00000000000000000000000000000000" } - - Note that "AUTHENTICATE:" must be in upper case, and the second - string constant is a string with a colon followed by 32 zeros. - - These apparently strange values of A2 are for compatibility with - HTTP; they were arrived at by setting "Method" to "AUTHENTICATE" and - the hash of the entity body to zero in the HTTP digest calculation of - A2. - - Also, in the HTTP usage of Digest, several directives in the - - - -Leach & Newman Standards Track [Page 11] - -RFC 2831 Digest SASL Mechanism May 2000 - - - "digest-challenge" sent by the server have to be returned by the - client in the "digest-response". These are: - - opaque - algorithm - - These directives are not needed when Digest is used as a SASL - mechanism (i.e., MUST NOT be sent, and MUST be ignored if received). - -2.1.3 Step Three - - The server receives and validates the "digest-response". The server - checks that the nonce-count is "00000001". If it supports subsequent - authentication (see section 2.2), it saves the value of the nonce and - the nonce-count. It sends a message formatted as follows: - - response-auth = "rspauth" "=" response-value - - where response-value is calculated as above, using the values sent in - step two, except that if qop is "auth", then A2 is - - A2 = { ":", digest-uri-value } - - And if qop is "auth-int" or "auth-conf" then A2 is - - A2 = { ":", digest-uri-value, ":00000000000000000000000000000000" } - - Compared to its use in HTTP, the following Digest directives in the - "digest-response" are unused: - - nextnonce - qop - cnonce - nonce-count - -2.2 Subsequent Authentication - - If the client has previously authenticated to the server, and - remembers the values of username, realm, nonce, nonce-count, cnonce, - and qop that it used in that authentication, and the SASL profile for - a protocol permits an initial client response, then it MAY perform - "subsequent authentication", as defined in this section. - - - - - - - - - -Leach & Newman Standards Track [Page 12] - -RFC 2831 Digest SASL Mechanism May 2000 - - -2.2.1 Step one - - The client uses the values from the previous authentication and sends - an initial response with a string formatted and computed according to - the rules for a "digest-response", as defined above, but with a - nonce-count one greater than used in the last "digest-response". - -2.2.2 Step Two - - The server receives the "digest-response". If the server does not - support subsequent authentication, then it sends a - "digest-challenge", and authentication proceeds as in initial - authentication. If the server has no saved nonce and nonce-count from - a previous authentication, then it sends a "digest-challenge", and - authentication proceeds as in initial authentication. Otherwise, the - server validates the "digest-response", checks that the nonce-count - is one greater than that used in the previous authentication using - that nonce, and saves the new value of nonce-count. - - If the response is invalid, then the server sends a - "digest-challenge", and authentication proceeds as in initial - authentication (and should be configurable to log an authentication - failure in some sort of security audit log, since the failure may be - a symptom of an attack). The nonce-count MUST NOT be incremented in - this case: to do so would allow a denial of service attack by sending - an out-of-order nonce-count. - - If the response is valid, the server MAY choose to deem that - authentication has succeeded. However, if it has been too long since - the previous authentication, or for any other reason, the server MAY - send a new "digest-challenge" with a new value for nonce. The - challenge MAY contain a "stale" directive with value "true", which - says that the client may respond to the challenge using the password - it used in the previous response; otherwise, the client must solicit - the password anew from the user. This permits the server to make sure - that the user has presented their password recently. (The directive - name refers to the previous nonce being stale, not to the last use of - the password.) Except for the handling of "stale", after sending the - "digest-challenge" authentication proceeds as in the case of initial - authentication. - -2.3 Integrity Protection - - If the server offered "qop=auth-int" and the client responded - "qop=auth-int", then subsequent messages, up to but not including the - next subsequent authentication, between the client and the server - - - - - -Leach & Newman Standards Track [Page 13] - -RFC 2831 Digest SASL Mechanism May 2000 - - - MUST be integrity protected. Using as a base session key the value of - H(A1) as defined above the client and server calculate a pair of - message integrity keys as follows. - - The key for integrity protecting messages from client to server is: - - Kic = MD5({H(A1), - "Digest session key to client-to-server signing key magic constant"}) - - The key for integrity protecting messages from server to client is: - - Kis = MD5({H(A1), - "Digest session key to server-to-client signing key magic constant"}) - - where MD5 is as specified in [RFC 1321]. If message integrity is - negotiated, a MAC block for each message is appended to the message. - The MAC block is 16 bytes: the first 10 bytes of the HMAC-MD5 [RFC - 2104] of the message, a 2-byte message type number in network byte - order with value 1, and the 4-byte sequence number in network byte - order. The message type is to allow for future extensions such as - rekeying. - - MAC(Ki, SeqNum, msg) = (HMAC(Ki, {SeqNum, msg})[0..9], 0x0001, - SeqNum) - - where Ki is Kic for messages sent by the client and Kis for those - sent by the server. The sequence number is initialized to zero, and - incremented by one for each message sent. - - Upon receipt, MAC(Ki, SeqNum, msg) is computed and compared with the - received value; the message is discarded if they differ. - -2.4 Confidentiality Protection - - If the server sent a "cipher-opts" directive and the client responded - with a "cipher" directive, then subsequent messages between the - client and the server MUST be confidentiality protected. Using as a - base session key the value of H(A1) as defined above the client and - server calculate a pair of message integrity keys as follows. - - The key for confidentiality protecting messages from client to server - is: - - Kcc = MD5({H(A1)[0..n], - "Digest H(A1) to client-to-server sealing key magic constant"}) - - The key for confidentiality protecting messages from server to client - is: - - - -Leach & Newman Standards Track [Page 14] - -RFC 2831 Digest SASL Mechanism May 2000 - - - Kcs = MD5({H(A1)[0..n], - "Digest H(A1) to server-to-client sealing key magic constant"}) - - where MD5 is as specified in [RFC 1321]. For cipher "rc4-40" n is 5; - for "rc4-56" n is 7; for the rest n is 16. The key for the "rc-*" - ciphers is all 16 bytes of Kcc or Kcs; the key for "des" is the first - 7 bytes; the key for "3des" is the first 14 bytes. The IV for "des" - and "3des" is the last 8 bytes of Kcc or Kcs. - - If message confidentiality is negotiated, each message is encrypted - with the chosen cipher and a MAC block is appended to the message. - - The MAC block is a variable length padding prefix followed by 16 - bytes formatted as follows: the first 10 bytes of the HMAC-MD5 [RFC - 2104] of the message, a 2-byte message type number in network byte - order with value 1, and the 4-byte sequence number in network byte - order. If the blocksize of the chosen cipher is not 1 byte, the - padding prefix is one or more octets each containing the number of - padding bytes, such that total length of the encrypted part of the - message is a multiple of the blocksize. The padding and first 10 - bytes of the MAC block are encrypted along with the message. - - SEAL(Ki, Kc, SeqNum, msg) = - {CIPHER(Kc, {msg, pad, HMAC(Ki, {SeqNum, msg})[0..9])}), 0x0001, - SeqNum} - - where CIPHER is the chosen cipher, Ki and Kc are Kic and Kcc for - messages sent by the client and Kis and Kcs for those sent by the - server. The sequence number is initialized to zero, and incremented - by one for each message sent. - - Upon receipt, the message is decrypted, HMAC(Ki, {SeqNum, msg}) is - computed and compared with the received value; the message is - discarded if they differ. - -3 Security Considerations - -3.1 Authentication of Clients using Digest Authentication - - Digest Authentication does not provide a strong authentication - mechanism, when compared to public key based mechanisms, for example. - However, since it prevents chosen plaintext attacks, it is stronger - than (e.g.) CRAM-MD5, which has been proposed for use with LDAP [10], - POP and IMAP (see RFC 2195 [9]). It is intended to replace the much - weaker and even more dangerous use of plaintext passwords; however, - since it is still a password based mechanism it avoids some of the - potential deployabilty issues with public-key, OTP or similar - mechanisms. - - - -Leach & Newman Standards Track [Page 15] - -RFC 2831 Digest SASL Mechanism May 2000 - - - Digest Authentication offers no confidentiality protection beyond - protecting the actual password. All of the rest of the challenge and - response are available to an eavesdropper, including the user's name - and authentication realm. - -3.2 Comparison of Digest with Plaintext Passwords - - The greatest threat to the type of transactions for which these - protocols are used is network snooping. This kind of transaction - might involve, for example, online access to a mail service whose use - is restricted to paying subscribers. With plaintext password - authentication an eavesdropper can obtain the password of the user. - This not only permits him to access anything in the database, but, - often worse, will permit access to anything else the user protects - with the same password. - -3.3 Replay Attacks - - Replay attacks are defeated if the client or the server chooses a - fresh nonce for each authentication, as this specification requires. - -3.4 Online dictionary attacks - - If the attacker can eavesdrop, then it can test any overheard - nonce/response pairs against a (potentially very large) list of - common words. Such a list is usually much smaller than the total - number of possible passwords. The cost of computing the response for - each password on the list is paid once for each challenge. - - The server can mitigate this attack by not allowing users to select - passwords that are in a dictionary. - -3.5 Offline dictionary attacks - - If the attacker can choose the challenge, then it can precompute the - possible responses to that challenge for a list of common words. Such - a list is usually much smaller than the total number of possible - passwords. The cost of computing the response for each password on - the list is paid just once. - - Offline dictionary attacks are defeated if the client chooses a fresh - nonce for each authentication, as this specification requires. - - - - - - - - - -Leach & Newman Standards Track [Page 16] - -RFC 2831 Digest SASL Mechanism May 2000 - - -3.6 Man in the Middle - - Digest authentication is vulnerable to "man in the middle" (MITM) - attacks. Clearly, a MITM would present all the problems of - eavesdropping. But it also offers some additional opportunities to - the attacker. - - A possible man-in-the-middle attack would be to substitute a weaker - qop scheme for the one(s) sent by the server; the server will not be - able to detect this attack. For this reason, the client should always - use the strongest scheme that it understands from the choices - offered, and should never choose a scheme that does not meet its - minimum requirements. - -3.7 Chosen plaintext attacks - - A chosen plaintext attack is where a MITM or a malicious server can - arbitrarily choose the challenge that the client will use to compute - the response. The ability to choose the challenge is known to make - cryptanalysis much easier [8]. - - However, Digest does not permit the attack to choose the challenge as - long as the client chooses a fresh nonce for each authentication, as - this specification requires. - -3.8 Spoofing by Counterfeit Servers - - If a user can be led to believe that she is connecting to a host - containing information protected by a password she knows, when in - fact she is connecting to a hostile server, then the hostile server - can obtain challenge/response pairs where it was able to partly - choose the challenge. There is no known way that this can be - exploited. - -3.9 Storing passwords - - Digest authentication requires that the authenticating agent (usually - the server) store some data derived from the user's name and password - in a "password file" associated with a given realm. Normally this - might contain pairs consisting of username and H({ username-value, - ":", realm-value, ":", passwd }), which is adequate to compute H(A1) - as described above without directly exposing the user's password. - - The security implications of this are that if this password file is - compromised, then an attacker gains immediate access to documents on - the server using this realm. Unlike, say a standard UNIX password - file, this information need not be decrypted in order to access - documents in the server realm associated with this file. On the other - - - -Leach & Newman Standards Track [Page 17] - -RFC 2831 Digest SASL Mechanism May 2000 - - - hand, decryption, or more likely a brute force attack, would be - necessary to obtain the user's password. This is the reason that the - realm is part of the digested data stored in the password file. It - means that if one Digest authentication password file is compromised, - it does not automatically compromise others with the same username - and password (though it does expose them to brute force attack). - - There are two important security consequences of this. First the - password file must be protected as if it contained plaintext - passwords, because for the purpose of accessing documents in its - realm, it effectively does. - - A second consequence of this is that the realm string should be - unique among all realms that any single user is likely to use. In - particular a realm string should include the name of the host doing - the authentication. - -3.10 Multiple realms - - Use of multiple realms may mean both that compromise of a the - security database for a single realm does not compromise all - security, and that there are more things to protect in order to keep - the whole system secure. - -3.11 Summary - - By modern cryptographic standards Digest Authentication is weak, - compared to (say) public key based mechanisms. But for a large range - of purposes it is valuable as a replacement for plaintext passwords. - Its strength may vary depending on the implementation. - -4 Example - - This example shows the use of the Digest SASL mechanism with the - IMAP4 AUTHENTICATE command [RFC 2060]. - - In this example, "C:" and "S:" represent a line sent by the client or - server respectively including a CRLF at the end. Linebreaks and - indentation within a "C:" or "S:" are editorial and not part of the - protocol. The password in this example was "secret". Note that the - base64 encoding of the challenges and responses is part of the IMAP4 - AUTHENTICATE command, not part of the Digest specification itself. - - S: * OK elwood.innosoft.com PMDF IMAP4rev1 V6.0-9 - C: c CAPABILITY - S: * CAPABILITY IMAP4 IMAP4rev1 ACL LITERAL+ NAMESPACE QUOTA - UIDPLUS AUTH=CRAM-MD5 AUTH=DIGEST-MD5 AUTH=PLAIN - S: c OK Completed - - - -Leach & Newman Standards Track [Page 18] - -RFC 2831 Digest SASL Mechanism May 2000 - - - C: a AUTHENTICATE DIGEST-MD5 - S: + cmVhbG09ImVsd29vZC5pbm5vc29mdC5jb20iLG5vbmNlPSJPQTZNRzl0 - RVFHbTJoaCIscW9wPSJhdXRoIixhbGdvcml0aG09bWQ1LXNlc3MsY2hh - cnNldD11dGYtOA== - C: Y2hhcnNldD11dGYtOCx1c2VybmFtZT0iY2hyaXMiLHJlYWxtPSJlbHdvb2 - QuaW5ub3NvZnQuY29tIixub25jZT0iT0E2TUc5dEVRR20yaGgiLG5jPTAw - MDAwMDAxLGNub25jZT0iT0E2TUhYaDZWcVRyUmsiLGRpZ2VzdC11cmk9Im - ltYXAvZWx3b29kLmlubm9zb2Z0LmNvbSIscmVzcG9uc2U9ZDM4OGRhZDkw - ZDRiYmQ3NjBhMTUyMzIxZjIxNDNhZjcscW9wPWF1dGg= - S: + cnNwYXV0aD1lYTQwZjYwMzM1YzQyN2I1NTI3Yjg0ZGJhYmNkZmZmZA== - C: - S: a OK User logged in - --- - - The base64-decoded version of the SASL exchange is: - - S: realm="elwood.innosoft.com",nonce="OA6MG9tEQGm2hh",qop="auth", - algorithm=md5-sess,charset=utf-8 - C: charset=utf-8,username="chris",realm="elwood.innosoft.com", - nonce="OA6MG9tEQGm2hh",nc=00000001,cnonce="OA6MHXh6VqTrRk", - digest-uri="imap/elwood.innosoft.com", - response=d388dad90d4bbd760a152321f2143af7,qop=auth - S: rspauth=ea40f60335c427b5527b84dbabcdfffd - - The password in this example was "secret". - - This example shows the use of the Digest SASL mechanism with the - ACAP, using the same notational conventions and password as in the - previous example. Note that ACAP does not base64 encode and uses - fewer round trips that IMAP4. - - S: * ACAP (IMPLEMENTATION "Test ACAP server") (SASL "CRAM-MD5" - "DIGEST-MD5" "PLAIN") - C: a AUTHENTICATE "DIGEST-MD5" - S: + {94} - S: realm="elwood.innosoft.com",nonce="OA9BSXrbuRhWay",qop="auth", - algorithm=md5-sess,charset=utf-8 - C: {206} - C: charset=utf-8,username="chris",realm="elwood.innosoft.com", - nonce="OA9BSXrbuRhWay",nc=00000001,cnonce="OA9BSuZWMSpW8m", - digest-uri="acap/elwood.innosoft.com", - response=6084c6db3fede7352c551284490fd0fc,qop=auth - S: a OK (SASL {40} - S: rspauth=2f0b3d7c3c2e486600ef710726aa2eae) "AUTHENTICATE - Completed" - --- - - - - - -Leach & Newman Standards Track [Page 19] - -RFC 2831 Digest SASL Mechanism May 2000 - - - The server uses the values of all the directives, plus knowledge of - the users password (or the hash of the user's name, server's realm - and the user's password) to verify the computations above. If they - check, then the user has authenticated. - -5 References - - [Digest] Franks, J., et al., "HTTP Authentication: Basic and Digest - Access Authentication", RFC 2617, June 1999. - - [ISO-8859] ISO-8859. International Standard--Information Processing-- - 8-bit Single-Byte Coded Graphic Character Sets -- - Part 1: Latin alphabet No. 1, ISO-8859-1:1987. - Part 2: Latin alphabet No. 2, ISO-8859-2, 1987. - Part 3: Latin alphabet No. 3, ISO-8859-3, 1988. - Part 4: Latin alphabet No. 4, ISO-8859-4, 1988. - Part 5: Latin/Cyrillic alphabet, ISO-8859-5, 1988. - Part 6: Latin/Arabic alphabet, ISO-8859-6, 1987. - Part 7: Latin/Greek alphabet, ISO-8859-7, 1987. - Part 8: Latin/Hebrew alphabet, ISO-8859-8, 1988. - Part 9: Latin alphabet No. 5, ISO-8859-9, 1990. - - [RFC 822] Crocker, D., "Standard for The Format of ARPA Internet - Text Messages," STD 11, RFC 822, August 1982. - - [RFC 1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, - April 1992. - - [RFC 2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) - Part Three: Message Header Extensions for Non-ASCII Text", - RFC 2047, November 1996. - - [RFC 2052] Gulbrandsen, A. and P. Vixie, "A DNS RR for specifying the - location of services (DNS SRV)", RFC 2052, October 1996. - - [RFC 2060] Crispin, M., "Internet Message Access Protocol - Version - 4rev1", RFC 2060, December 1996. - - [RFC 2104] Krawczyk, H., Bellare, M. and R. Canetti, "HMAC: Keyed- - Hashing for Message Authentication", RFC 2104, February - 1997. - - [RFC 2195] Klensin, J., Catoe, R. and P. Krumviede, "IMAP/POP - AUTHorize Extension for Simple Challenge/Response", RFC - 2195, September 1997. - - - - - - -Leach & Newman Standards Track [Page 20] - -RFC 2831 Digest SASL Mechanism May 2000 - - - [RFC 2119] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [RFC 2222] Myers, J., "Simple Authentication and Security Layer - (SASL)", RFC 2222, October 1997. - - [USASCII] US-ASCII. Coded Character Set - 7-Bit American Standard - Code for Information Interchange. Standard ANSI X3.4-1986, - ANSI, 1986. - -6 Authors' Addresses - - Paul Leach - Microsoft - 1 Microsoft Way - Redmond, WA 98052 - - EMail: paulle@microsoft.com - - - Chris Newman - Innosoft International, Inc. - 1050 Lakes Drive - West Covina, CA 91790 USA - - EMail: chris.newman@innosoft.com - -7 ABNF - - What follows is the definition of the notation as is used in the - HTTP/1.1 specification (RFC 2616) and the HTTP authentication - specification (RFC 2617); it is reproduced here for ease of - reference. Since it is intended that a single Digest implementation - can support both HTTP and SASL-based protocols, the same notation is - used in both to facilitate comparison and prevention of unwanted - differences. Since it is cut-and-paste from the HTTP specifications, - not all productions may be used in this specification. It is also not - quite legal ABNF; again, the errors were copied from the HTTP - specifications. - -7.1 Augmented BNF - - All of the mechanisms specified in this document are described in - both prose and an augmented Backus-Naur Form (BNF) similar to that - used by RFC 822 [RFC 822]. Implementers will need to be familiar with - the notation in order to understand this specification. - - - - - -Leach & Newman Standards Track [Page 21] - -RFC 2831 Digest SASL Mechanism May 2000 - - - The augmented BNF includes the following constructs: - - name = definition - The name of a rule is simply the name itself (without any - enclosing "<" and ">") and is separated from its definition by the - equal "=" character. White space is only significant in that - indentation of continuation lines is used to indicate a rule - definition that spans more than one line. Certain basic rules are - in uppercase, such as SP, LWS, HT, CRLF, DIGIT, ALPHA, etc. Angle - brackets are used within definitions whenever their presence will - facilitate discerning the use of rule names. - - "literal" - Quotation marks surround literal text. Unless stated otherwise, - the text is case-insensitive. - - rule1 | rule2 - Elements separated by a bar ("|") are alternatives, e.g., "yes | - no" will accept yes or no. - - (rule1 rule2) - Elements enclosed in parentheses are treated as a single element. - Thus, "(elem (foo | bar) elem)" allows the token sequences - "elem foo elem" and "elem bar elem". - - *rule - The character "*" preceding an element indicates repetition. The - full form is "*element" indicating at least and at most - occurrences of element. Default values are 0 and infinity so - that "*(element)" allows any number, including zero; "1*element" - requires at least one; and "1*2element" allows one or two. - - [rule] - Square brackets enclose optional elements; "[foo bar]" is - equivalent to "*1(foo bar)". - - N rule - Specific repetition: "(element)" is equivalent to - "*(element)"; that is, exactly occurrences of (element). - Thus 2DIGIT is a 2-digit number, and 3ALPHA is a string of three - alphabetic characters. - - #rule - A construct "#" is defined, similar to "*", for defining lists of - elements. The full form is "#element" indicating at least - and at most elements, each separated by one or more commas - (",") and OPTIONAL linear white space (LWS). This makes the usual - form of lists very easy; a rule such as - - - -Leach & Newman Standards Track [Page 22] - -RFC 2831 Digest SASL Mechanism May 2000 - - - ( *LWS element *( *LWS "," *LWS element )) - can be shown as - 1#element - Wherever this construct is used, null elements are allowed, but do - not contribute to the count of elements present. That is, - "(element), , (element) " is permitted, but counts as only two - elements. Therefore, where at least one element is required, at - least one non-null element MUST be present. Default values are 0 - and infinity so that "#element" allows any number, including zero; - "1#element" requires at least one; and "1#2element" allows one or - two. - - ; comment - A semi-colon, set off some distance to the right of rule text, - starts a comment that continues to the end of line. This is a - simple way of including useful notes in parallel with the - specifications. - - implied *LWS - The grammar described by this specification is word-based. Except - where noted otherwise, linear white space (LWS) can be included - between any two adjacent words (token or quoted-string), and - between adjacent words and separators, without changing the - interpretation of a field. At least one delimiter (LWS and/or - separators) MUST exist between any two tokens (for the definition - of "token" below), since they would otherwise be interpreted as a - single token. - -7.2 Basic Rules - - The following rules are used throughout this specification to - describe basic parsing constructs. The US-ASCII coded character set - is defined by ANSI X3.4-1986 [USASCII]. - - OCTET = - CHAR = - UPALPHA = - LOALPHA = - ALPHA = UPALPHA | LOALPHA - DIGIT = - CTL = - CR = - LF = - SP = - HT = - <"> = - CRLF = CR LF - - - -Leach & Newman Standards Track [Page 23] - -RFC 2831 Digest SASL Mechanism May 2000 - - - - All linear white space, including folding, has the same semantics as - SP. A recipient MAY replace any linear white space with a single SP - before interpreting the field value or forwarding the message - downstream. - - LWS = [CRLF] 1*( SP | HT ) - - The TEXT rule is only used for descriptive field contents and values - that are not intended to be interpreted by the message parser. Words - of *TEXT MAY contain characters from character sets other than - ISO-8859-1 [ISO 8859] only when encoded according to the rules of RFC - 2047 [RFC 2047]. - - TEXT = - - A CRLF is allowed in the definition of TEXT only as part of a header - field continuation. It is expected that the folding LWS will be - replaced with a single SP before interpretation of the TEXT value. - - Hexadecimal numeric characters are used in several protocol elements. - - HEX = "A" | "B" | "C" | "D" | "E" | "F" - | "a" | "b" | "c" | "d" | "e" | "f" | DIGIT - - Many HTTP/1.1 header field values consist of words separated by LWS - or special characters. These special characters MUST be in a quoted - string to be used within a parameter value. - - token = 1* - separators = "(" | ")" | "<" | ">" | "@" - | "," | ";" | ":" | "\" | <"> - | "/" | "[" | "]" | "?" | "=" - | "{" | "}" | SP | HT - - A string of text is parsed as a single word if it is quoted using - double-quote marks. - - quoted-string = ( <"> qdstr-val <"> ) - qdstr-val = *( qdtext | quoted-pair ) - qdtext = > - - Note that LWS is NOT implicit between the double-quote marks (<">) - surrounding a qdstr-val and the qdstr-val; any LWS will be considered - part of the qdstr-val. This is also the case for quotation marks - surrounding any other construct. - - - - -Leach & Newman Standards Track [Page 24] - -RFC 2831 Digest SASL Mechanism May 2000 - - - The backslash character ("\") MAY be used as a single-character - quoting mechanism only within qdstr-val and comment constructs. - - quoted-pair = "\" CHAR - - The value of this construct is CHAR. Note that an effect of this rule - is that backslash must be quoted. - -8 Sample Code - - The sample implementation in [Digest] also applies to DIGEST-MD5. - - The following code implements the conversion from UTF-8 to 8859-1 if - necessary. - - /* if the string is entirely in the 8859-1 subset of UTF-8, then - * translate to 8859-1 prior to MD5 - */ - void MD5_UTF8_8859_1(MD5_CTX *ctx, const unsigned char *base, - int len) - { - const unsigned char *scan, *end; - unsigned char cbuf; - - end = base + len; - for (scan = base; scan < end; ++scan) { - if (*scan > 0xC3) break; /* abort if outside 8859-1 */ - if (*scan >= 0xC0 && *scan <= 0xC3) { - if (++scan == end || *scan < 0x80 || *scan > 0xBF) - break; - } - } - /* if we found a character outside 8859-1, don't alter string - */ - if (scan < end) { - MD5Update(ctx, base, len); - return; - } - - /* convert to 8859-1 prior to applying hash - */ - do { - for (scan = base; scan < end && *scan < 0xC0; ++scan) - ; - if (scan != base) MD5Update(ctx, base, scan - base); - if (scan + 1 >= end) break; - cbuf = ((scan[0] & 0x3) << 6) | (scan[1] & 0x3f); - MD5Update(ctx, &cbuf, 1); - - - -Leach & Newman Standards Track [Page 25] - -RFC 2831 Digest SASL Mechanism May 2000 - - - base = scan + 2; - } while (base < end); - } - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Leach & Newman Standards Track [Page 26] - -RFC 2831 Digest SASL Mechanism May 2000 - - -9 Full Copyright Statement - - Copyright (C) The Internet Society (2000). 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. - - - - - - - - - - - - - - - - - - - -Leach & Newman Standards Track [Page 27] -