--- /dev/null
+
+Network Working Group M. Wahl
+INTERNET-DRAFT Critical Angle Inc.
+Obsoletes: RFC 1778 A. Coulbeck
+ ISODE Consortium
+ T. Howes
+ Netscape Communications Corp.
+ S. Kille
+ ISODE Consortium
+Intended Category: Standards Track October 22, 1996
+
+
+ Lightweight Directory Access Protocol:
+ Standard and Pilot Attribute Definitions
+ <draft-ietf-asid-ldapv3-attributes-03.txt>
+
+1. Status of this Memo
+
+ This document is an Internet-Draft. Internet-Drafts are working
+ documents of the Internet Engineering Task Force (IETF), its areas, and
+ its working groups. Note that other groups may also distribute working
+ documents as Internet-Drafts.
+
+ Internet-Drafts are draft documents valid for a maximum of six months
+ and may be updated, replaced, or obsoleted by other documents at any
+ time. It is inappropriate to use Internet-Drafts as reference material
+ or to cite them other than as "work in progress."
+
+ To learn the current status of any Internet-Draft, please check the
+ "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow
+ Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe),
+ ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim).
+
+2. Abstract
+
+ The Lightweight Directory Access Protocol (LDAP) [1] requires that the
+ contents of AttributeValue fields in protocol elements be octet
+ strings. This document defines the requirements that must be
+ satisfied by encoding rules used to render directory attribute
+ syntaxes into a form suitable for use in the LDAP, then goes on to
+ define the encoding rules for the standard set of attribute syntaxes
+ of [2],[3] and [4]. It also identifies all the attribute types, object
+ classes and matching rules for LDAP version 3.
+
+3. Overview
+
+ Section 4 states the general requirements and notations for attribute
+ types, object classes, syntax and matching rule definitions.
+
+ The core definitions are given in section 5, those which are based on
+ X.500(1993) in section 6, and other optional definitions in section 7.
+
+
+
+
+
+Wahl, Coulbeck, Howes & Kille [Page 1]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+4. General Issues
+
+4.1. Attribute Types
+
+ The attribute types are described by sample values for the subschema
+ "attributeTypes" attribute, which is written in the
+ AttributeTypeDescription syntax. While lines have been folded for
+ readability, the values transferred in protocol would not contain
+ newlines.
+
+ The AttributeTypeDescription is encoded according to the following BNF,
+ and the productions for <oid>, <DirectoryStrings> and <DirectoryString>
+ are given in sections 4.2.1.
+
+ <AttributeTypeDescription> ::= "("
+ <oid> -- AttributeType identifier
+ [ "NAME" <DirectoryStrings> ] -- name used in AttributeType
+ [ "DESC" <DirectoryString> ]
+ [ "OBSOLETE" ]
+ [ "SUP" <oid> ] -- derived from this other AttributeType
+ [ "EQUALITY" <oid> ] -- Matching Rule name
+ [ "ORDERING" <oid> ] -- Matching Rule name
+ [ "SUBSTR" <oid> ] -- Matching Rule name
+ [ "SYNTAX" <DirectoryString> ] -- see section 4.2
+ [ "SINGLE-VALUE" ] -- default multi-valued
+ [ "COLLECTIVE" ] -- default not collective
+ [ "NO-USER-MODIFICATION" ] -- default user modifiable
+ [ "USAGE" <AttributeUsage> ] -- default user applications
+ ")"
+
+ <AttributeUsage> ::=
+ "userApplications"
+ | "directoryOperation"
+ | "distributedOperation" -- DSA-shared
+ | "dSAOperation" -- DSA-specific, value depends on server
+
+ Servers are not required to provide the same or any text
+ in the description part of the subschema values they maintain.
+
+ Servers must implement all the attribute types in section 5.1, and
+ may also implement the types listed in sections 6.1 and 7.1. Servers must
+ be able to perform equality matching of values, but need not perform
+ any additional validity checks on attribute values.
+
+ Servers may recognize additional names and attributes not listed in this
+ document. Later documents may define additional types.
+
+ Servers may implement additional attribute types not listed in this
+ document, and if they do so, must publish the definitions of the types
+ in the attributeTypes attribute of their subschema subentries.
+
+ AttributeDescriptions may be used as the value in a NAME part of an
+ AttributeTypeDescription. Note that these are case insensitive.
+
+Wahl, Coulbeck, Howes & Kille [Page 2]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+4.2. Syntaxes
+
+ This section defines general requirements for LDAP attribute value
+ syntax encodings. All documents defining attribute syntax encodings for
+ use with LDAP are expected to conform to these requirements.
+
+ The encoding rules defined for a given attribute syntax must produce
+ octet strings. To the greatest extent possible, encoded octet
+ strings should be usable in their native encoded form for display
+ purposes. In particular, encoding rules for attribute syntaxes
+ defining non-binary values should produce strings that can be
+ displayed with little or no translation by clients implementing
+ LDAP. There are a few cases (e.g. Audio) however, when it is not sensible
+ to produce a printable representation, and clients must not assume that
+ an unrecognized syntax is a string representation.
+
+4.2.1. Common Encoding Aspects
+
+ In these encodings where an arbitrary string is used as part of a larger
+ production (other than a Distinguished Name), a backslash quoting mechanism
+ is used to encode the following separator symbol character (such as ''',
+ '$' or '#') if it should occur in that string. The backslash is followed
+ by a pair of hexadecimal digits representing the next character. A
+ backslash itself in the string which forms part of a larger syntax is
+ always transmitted as '\5C' or '\5c'.
+
+ For the purposes of defining the encoding rules for attribute syntaxes,
+ the following auxiliary BNF definitions will be used:
+
+ <a> ::= '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'
+
+ <d> ::= '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'
+
+ <hex-digit> ::= <d> | 'a' | 'b' | 'c' | 'd' | 'e' | 'f' |
+ 'A' | 'B' | 'C' | 'D' | 'E' | 'F'
+
+ <k> ::= <a> | <d> | '-'
+
+ <p> ::= <a> | <d> | ''' | '(' | ')' | '+' | ',' | '-' | '.' |
+ '/' | ':' | '?' | ' '
+
+ <letterstring> ::= <a> | <a> <letterstring>
+
+ <numericstring> ::= <d> | <d> <numericstring>
+
+ <keystring> ::= <a> | <a> <anhstring>
+
+ <anhstring> ::= <k> | <k> <anhstring>
+
+Wahl, Coulbeck, Howes & Kille [Page 3]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+ <printablestring> ::= <p> | <p> <printablestring>
+
+ <space> ::= ' ' | ' ' <space>
+
+ <whsp> ::= <space> | empty
+
+ <utf8> ::= any sequence of octets formed from the UTF-8 [11]
+ transformation of a character from ISO 10646 [12]
+
+ <dstring> ::= <utf8> | <utf8> <dstring>
+
+ <DirectoryStrings> ::= <DirectoryString> | '(' <DirectoryStringList> ')'
+
+ <DirectoryStringList> ::= <DirectoryStringList> <DirectoryString> | ""
+
+ <DirectoryString> ::= ''' <dstring> '''
+
+ <oids> ::= <oid> | '(' <oidlist> ')'
+
+ <oidlist> ::= <oidlist> '$' <oid> | <oid>
+
+ -- <oid> is defined in 5.2.1.15
+
+4.2.2 Binary Transfer of Values
+
+ This encoding format is used if the binary encoding is requested by the
+ client for an attribute, or if the attribute syntax name is 'Binary'. The
+ value, an instance of the ASN.1 AttributeValue type, is BER-encoded,
+ subject to the restrictions of section 5.1 of [1], and this sequence of
+ octets is used as the value.
+
+ All servers must implement this form for both generating Search responses
+ and parsing Add, Compare and Modify requests. Clients must be prepared
+ receiving values in binary (e.g. userCertificate or audio), and must not
+ simply display binary or unrecognized values to users.
+
+4.2.3. Syntax Namees
+
+ Names of syntaxes for use with LDAP are ASCII strings which either
+ begin with a letter and contain only letters or digits. The names are
+ case insensitive. Historically since syntaxes correspond to ASN.1 types,
+ they have been named starting with a capital letter. A suggested upper
+ bound on the number of characters in value with a DirectoryString or
+ IA5String syntax or the number of bytes in a value for all other syntaxes
+ may be indicated by appending this bound count inside of curly braces, e.g.
+ "DirectoryString{64}". Note that a single character of the DirectoryString
+ may be encoded in more than one byte since UTF-8 is a variable-length
+ encoding.
+
+ Syntax names do not have global scope: two clients or servers may
+ know of different syntaxes with the same name.
+
+
+
+Wahl, Coulbeck, Howes & Kille [Page 4]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+ The definition of additional arbitrary syntaxes is strongly depreciated
+ since it will hinder interoperability: today's client and server
+ implementations generally do not have the ability to dynamically recognize
+ new syntaxes. In most cases attributes will be defined with the
+ DirectoryString syntax.
+
+ The following syntax names are used for attributes in this document.
+ Servers are only required to implement the syntaxes in section 5.2.
+
+ AccessPoint ACIItem
+ AttributeTypeDescription Audio
+ Binary BitString
+ Certificate CertificateList
+ CertificatePair DataQualitySyntax
+ DeliveryMethod DirectoryString
+ DITContentRuleDescription DN
+ DSAQualitySyntax DSEType
+ EnhancedGuide FacsimileTelephoneNumber
+ Fax GeneralizedTime
+ Guide IA5String
+ INTEGER JPEG
+ MailPreference MasterAndShadowAccessPoints
+ MatchingRuleDescription MatchingRuleUseDescription
+ ModifyRight NameAndOptionalUID
+ NameFormDescription NumericString
+ ObjectClassDescription OID
+ OtherMailbox Password
+ PostalAddress PresentationAddress
+ PrintableString ProtocolInformation
+ SubtreeSpecification SupplierAndConsumers
+ SupplierInformation SupplierOrConsumer
+ TelephoneNumber TeletexTerminalIdentifier
+ TelexNumber UTCTime
+
+4.3. Object Classes
+
+ These are described as sample values for the subschema "objectClasses"
+ attribute for a server which implements the LDAP schema.
+ While lines have been folded for readability, the values transferred in
+ protocol would not contain newlines.
+
+ Object class descriptions are written according to the following BNF:
+
+ <ObjectClassDescription> ::= "("
+ <oid> -- ObjectClass identifier
+ [ "NAME" <DirectoryStrings> ]
+ [ "DESC" <DirectoryString> ]
+ [ "OBSOLETE" ]
+ [ "SUP" <oids> ] -- Superior ObjectClasses
+ [ ( "ABSTRACT" | "STRUCTURAL" | "AUXILIARY" ) ] -- default structural
+ [ "MUST" <oids> ] -- AttributeTypes
+ [ "MAY" <oids> ] -- AttributeTypes
+ ")"
+
+Wahl, Coulbeck, Howes & Kille [Page 5]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+ Servers must implement all the object classes in section 5.3:
+ account alias
+ applicationEntity applicationProcess
+ certificationAuthority country
+ dNSDomain dSA
+ device document
+ documentSeries domain
+ domainRelatedObject friendlyCountry
+ groupOfNames groupOfUniqueNames
+ locality newPilotPerson
+ organization organizationalPerson
+ organizationalRole organizationalUnit
+ person pilotDSA
+ pilotObject pilotOrganization
+ qualityLabelledData rFC822localPart
+ residentialPerson room
+ simpleSecurityObject strongAuthenticationUser
+ top
+
+ and may also implement the object classes of 6.3 and 7.3.
+
+ Servers may implement additional object classes not listed in this
+ document, and if they do so, must publish the definitions of the classes
+ in the objectClasses attribute of their subschema subentries. Later
+ documents may define additional object classes.
+
+4.4. Matching Rules
+
+ Matching rules are used by servers to compare attribute values against
+ assertion values when performing Search and Compare operations.
+
+ Most of the attributes given in this document will have an equality
+ matching rule defined.
+
+ Matching rule descriptions are written according to the following BNF:
+
+ <MatchingRuleDescription> ::= "("
+ <oid> -- MatchingRule identifier
+ [ "NAME" <DirectoryStrings> ]
+ [ "DESC" <DirectoryString> ]
+ [ "OBSOLETE" ]
+ "SYNTAX" <DirectoryString>
+ ")"
+
+ Servers must implement all the matching rules in section 5.4:
+ bitStringMatch caseExactIA5Match
+ caseIgnoreIA5Match caseIgnoreListMatch
+ caseIgnoreMatch distinguishedNameMatch
+ generalizedTimeMatch integerMatch
+ numericStringMatch objectIdentifierMatch
+ octetStringMatch telephoneNumberMatch
+
+ and may also implement the matching rules of 6.4 and 7.4.
+
+Wahl, Coulbeck, Howes & Kille [Page 6]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+ Servers may implement additional matching rules not listed in this
+ document, and if they do so, must publish the definitions of the
+ matching rules in the matchingRules attribute of their
+ subschema subentries.
+
+5. Mandatory Definitions
+
+ Section 5 contains definitions which must be implemented by all servers.
+
+
+5.1. Attribute Types
+
+ Servers must recognize all the attributes of this section (5.1.1 - 5.1.5).
+
+5.1.1. Standard User Attributes
+
+ The attributes listed in this section are those defined in X.520(1993),
+ likely to be present in user entries. Servers must recognize all the
+ attributes of this section. The semantics of attributes 2.5.4.0 through
+ 2.5.4.40 are summarized in RFC 1274.
+
+ ( 2.5.4.0 NAME 'objectClass' EQUALITY objectIdentifierMatch SYNTAX 'OID' )
+
+ ( 2.5.4.1 NAME 'aliasedObjectName' EQUALITY distinguishedNameMatch
+ SYNTAX 'DN' SINGLE-VALUE )
+
+ ( 2.5.4.2 NAME 'knowledgeInformation' EQUALITY caseIgnoreMatch
+ SYNTAX 'DirectoryString{32768}' )
+
+ ( 2.5.4.3 NAME 'cn' SUP name )
+
+ ( 2.5.4.4 NAME 'sn' SUP name )
+
+ ( 2.5.4.5 NAME 'serialNumber' EQUALITY caseIgnoreMatch
+ SUBSTRINGS caseIgnoreSubstringsMatch SYNTAX 'PrintableString{64}' )
+
+ ( 2.5.4.6 NAME 'c' SUP name SINGLE-VALUE )
+
+ ( 2.5.4.7 NAME 'l' SUP name )
+
+ ( 2.5.4.8 NAME 'st' SUP name )
+
+ ( 2.5.4.9 NAME 'street' EQUALITY caseIgnoreMatch
+ SUBSTRINGS caseIgnoreSubstringsMatch SYNTAX 'DirectoryString{128}' )
+
+ ( 2.5.4.10 NAME 'o' SUP name )
+
+ ( 2.5.4.11 NAME 'ou' SUP name )
+
+ ( 2.5.4.12 NAME 'title' SUP name )
+
+ ( 2.5.4.13 NAME 'description' EQUALITY caseIgnoreMatch
+ SUBSTRINGS caseIgnoreSubstringsMatch SYNTAX 'DirectoryString{1024}' )
+
+Wahl, Coulbeck, Howes & Kille [Page 7]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+ ( 2.5.4.14 NAME 'searchGuide' SYNTAX 'Guide' )
+
+ ( 2.5.4.15 NAME 'businessCategory' EQUALITY caseIgnoreMatch
+ SUBSTRINGS caseIgnoreSubstringsMatch SYNTAX 'DirectoryString{128}' )
+
+ ( 2.5.4.16 NAME 'postalAddress' EQUALITY caseIgnoreListMatch
+ SUBSTRINGS caseIgnoreListSubstringsMatch SYNTAX 'PostalAddress' )
+
+ ( 2.5.4.17 NAME 'postalCode' EQUALITY caseIgnoreMatch
+ SUBSTRINGS caseIgnoreSubstringsMatch SYNTAX 'DirectoryString{40}' )
+
+ ( 2.5.4.18 NAME 'postOfficeBox' EQUALITY caseIgnoreMatch
+ SUBSTRINGS caseIgnoreSubstringsMatch SYNTAX 'DirectoryString{40}' )
+
+ ( 2.5.4.19 NAME 'physicalDeliveryOfficeName' EQUALITY caseIgnoreMatch
+ SUBSTRINGS caseIgnoreSubstringsMatch SYNTAX 'DirectoryString{128}' )
+
+ ( 2.5.4.20 NAME 'telephoneNumber' EQUALITY telephoneNumberMatch
+ SUBSTRINGS telephoneNumberSubstringsMatch SYNTAX 'TelephoneNumber{32}' )
+
+ ( 2.5.4.21 NAME 'telexNumber' SYNTAX 'TelexNumber' )
+
+ ( 2.5.4.22 NAME 'teletexTerminalIdentifier'
+ SYNTAX 'TeletexTerminalIdentifier' )
+
+ ( 2.5.4.23 NAME 'facsimileTelephoneNumber'
+ SYNTAX 'FacsimileTelephoneNumber' )
+
+ ( 2.5.4.24 NAME 'x121Address' EQUALITY numericStringMatch
+ SUBSTRINGS numericStringSubstringsMatch SYNTAX 'NumericString{15}' )
+
+ ( 2.5.4.25 NAME 'internationaliSDNNumber' EQUALITY numericStringMatch
+ SUBSTRINGS numericStringSubstringsMatch SYNTAX 'NumericString{16}' )
+
+ ( 2.5.4.26 NAME 'registeredAddress' SUP postalAddress
+ SYNTAX 'PostalAddress' )
+
+ ( 2.5.4.27 NAME 'destinationIndicator' EQUALITY caseIgnoreMatch
+ SUBSTRINGS caseIgnoreSubstringsMatch SYNTAX 'PrintableString{128}' )
+
+ ( 2.5.4.28 NAME 'preferredDeliveryMethod' SYNTAX 'DeliveryMethod'
+ SINGLE-VALUE )
+
+ ( 2.5.4.29 NAME 'presentationAddress' EQUALITY presentationAddressMatch
+ SYNTAX 'PresentationAddress' SINGLE-VALUE )
+
+ ( 2.5.4.30 NAME 'supportedApplicationContext'
+ EQUALITY objectIdentifierMatch SYNTAX 'OID' )
+
+ ( 2.5.4.31 NAME 'member' SUP distinguishedName )
+
+ ( 2.5.4.32 NAME 'owner' SUP distinguishedName )
+
+
+Wahl, Coulbeck, Howes & Kille [Page 8]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+ ( 2.5.4.33 NAME 'roleOccupant' SUP distinguishedName )
+
+ ( 2.5.4.34 NAME 'seeAlso' SUP distinguishedName )
+
+ ( 2.5.4.35 NAME 'userPassword' EQUALITY octetStringMatch
+ SYNTAX 'Password{128}' )
+
+ ( 2.5.4.36 NAME 'userCertificate' SYNTAX 'Certificate' )
+
+ ( 2.5.4.37 NAME 'cACertificate' SYNTAX 'Certificate' )
+
+ ( 2.5.4.38 NAME 'authorityRevocationList' SYNTAX 'CertificateList' )
+
+ ( 2.5.4.39 NAME 'certificateRevocationList' SYNTAX 'CertificateList' )
+
+ ( 2.5.4.40 NAME 'crossCertificatePair' SYNTAX 'CertificatePair' )
+
+ ( 2.5.4.41 NAME 'name'
+ DESC 'The name attribute type is the attribute supertype from which
+ string attribute types typically used for naming may be formed.'
+ EQUALITY caseIgnoreMatch
+ SUBSTRINGS caseIgnoreSubstringsMatch SYNTAX 'DirectoryString{32768}' )
+
+ ( 2.5.4.42 NAME 'givenName' SUP name )
+
+ ( 2.5.4.43 NAME 'initials'
+ DESC 'The initials attribute type contains the initials of some or all
+ of an individuals names, but not the surname(s).'
+ SUP name )
+
+ ( 2.5.4.44 NAME 'generationQualifier'
+ DESC 'e.g. Jr or II.'
+ SUP name )
+
+ ( 2.5.4.45 NAME 'x500UniqueIdentifier'
+ DESC 'used to distinguish between objects when a distinguished name has
+ been reused.'
+ EQUALITY bitStringMatch SYNTAX 'BitString' )
+
+ ( 2.5.4.46 NAME 'dnQualifier'
+ DESC 'The dnQualifier attribute type specifies disambiguating
+ information to add to the relative distinguished name of an
+ entry. It is intended to be used for entries held in multiple
+ DSAs which would otherwise have the same name, and that its
+ value be the same in a given DSA for all entries to which this
+ information has been added.'
+ EQUALITY caseIgnoreMatch
+ ORDERING caseIgnoreOrderingMatch SUBSTRINGS caseIgnoreSubstringsMatch
+ SYNTAX 'PrintableString' )
+
+ ( 2.5.4.47 NAME 'enhancedSearchGuide' SYNTAX 'EnhancedGuide' )
+
+
+
+Wahl, Coulbeck, Howes & Kille [Page 9]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+ ( 2.5.4.48 NAME 'protocolInformation' EQUALITY protocolInformationMatch
+ SYNTAX 'ProtocolInformation' )
+
+ ( 2.5.4.49 NAME 'distinguishedName'
+ DESC 'This is not the name of the object itself, but a base type
+ from which attributes with DN syntax inherit.'
+ EQUALITY distinguishedNameMatch
+ SYNTAX 'DN' )
+
+ ( 2.5.4.50 NAME 'uniqueMember' EQUALITY uniqueMemberMatch
+ SYNTAX 'NameAndOptionalUID' )
+
+ ( 2.5.4.51 NAME 'houseIdentifier' EQUALITY caseIgnoreMatch
+ SUBSTRINGS caseIgnoreSubstringsMatch SYNTAX 'DirectoryString{32768}' )
+
+5.1.2. Pilot User Attributes
+
+ These attributes are defined in RFC 1274. Servers must recognize all the
+ attributes of this section.
+
+ ( 0.9.2342.19200300.100.1.1 NAME 'uid' EQUALITY caseIgnoreMatch
+ SUBSTRINGS caseIgnoreSubstringsMatch SYNTAX 'DirectoryString{256}' )
+
+ ( 0.9.2342.19200300.100.1.2 NAME 'textEncodedORaddress'
+ EQUALITY caseIgnoreMatch SUBSTRINGS caseIgnoreSubstringsMatch
+ SYNTAX 'DirectoryString{256}' )
+
+ ( 0.9.2342.19200300.100.1.3 NAME 'mail' EQUALITY caseIgnoreIA5Match
+ SUBSTRINGS caseIgnoreIA5SubstringsMatch SYNTAX 'IA5String{256}' )
+
+ ( 0.9.2342.19200300.100.1.4 NAME 'info' EQUALITY caseIgnoreMatch
+ SUBSTRINGS caseIgnoreSubstringsMatch SYNTAX 'DirectoryString{2048}' )
+
+ ( 0.9.2342.19200300.100.1.5 NAME 'drink' EQUALITY caseIgnoreMatch
+ SUBSTRINGS caseIgnoreSubstringsMatch SYNTAX 'DirectoryString{256}' )
+
+ ( 0.9.2342.19200300.100.1.6 NAME 'roomNumber' EQUALITY caseIgnoreMatch
+ SUBSTRINGS caseIgnoreSubstringsMatch SYNTAX 'DirectoryString{256}' )
+
+ ( 0.9.2342.19200300.100.1.7 NAME 'photo' SYNTAX 'Fax{250000}' )
+
+ ( 0.9.2342.19200300.100.1.8 NAME 'userClass' EQUALITY caseIgnoreMatch
+ SUBSTRINGS caseIgnoreSubstringsMatch SYNTAX 'DirectoryString{256}' )
+
+ ( 0.9.2342.19200300.100.1.9 NAME 'host' EQUALITY caseIgnoreMatch
+ SUBSTRINGS caseIgnoreSubstringsMatch SYNTAX 'DirectoryString{256}' )
+
+ ( 0.9.2342.19200300.100.1.10 NAME 'manager'
+ EQUALITY distinguishedNameMatch SYNTAX 'DN' )
+
+ ( 0.9.2342.19200300.100.1.11 NAME 'documentIdentifier'
+ EQUALITY caseIgnoreMatch SUBSTRINGS caseIgnoreSubstringsMatch
+ SYNTAX 'DirectoryString{256}' )
+
+Wahl, Coulbeck, Howes & Kille [Page 10]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+ ( 0.9.2342.19200300.100.1.12 NAME 'documentTitle' EQUALITY caseIgnoreMatch
+ SUBSTRINGS caseIgnoreSubstringsMatch SYNTAX 'DirectoryString{256}' )
+
+ ( 0.9.2342.19200300.100.1.13 NAME 'documentVersion'
+ EQUALITY caseIgnoreMatch SUBSTRINGS caseIgnoreSubstringsMatch
+ SYNTAX 'DirectoryString{256}' )
+
+ ( 0.9.2342.19200300.100.1.14 NAME 'documentAuthor'
+ EQUALITY distinguishedNameMatch SYNTAX 'DN' )
+
+ ( 0.9.2342.19200300.100.1.15 NAME 'documentLocation'
+ EQUALITY caseIgnoreMatch SUBSTRINGS caseIgnoreSubstringsMatch
+ SYNTAX 'DirectoryString{256}' )
+
+ ( 0.9.2342.19200300.100.1.20 NAME 'homePhone' EQUALITY telephoneNumberMatch
+ SUBSTRINGS telephoneNumberSubstringsMatch SYNTAX 'TelephoneNumber{32}' )
+
+ ( 0.9.2342.19200300.100.1.21 NAME 'secretary'
+ EQUALITY distinguishedNameMatch SYNTAX 'DN' )
+
+ ( 0.9.2342.19200300.100.1.22 NAME 'otherMailbox' SYNTAX 'OtherMailbox' )
+
+ ( 0.9.2342.19200300.100.1.25 NAME 'dc' EQUALITY caseIgnoreIA5Match
+ SUBSTRINGS caseIgnoreIA5SubstringsMatch SYNTAX 'IA5String' )
+
+ ( 0.9.2342.19200300.100.1.26 NAME 'dNSRecord'
+ EQUALITY caseExactIA5Match SYNTAX 'IA5String' )
+
+ ( 0.9.2342.19200300.100.1.37 NAME 'associatedDomain'
+ EQUALITY caseIgnoreIA5Match SUBSTRINGS caseIgnoreIA5SubstringsMatch
+ SYNTAX 'IA5String' )
+
+ ( 0.9.2342.19200300.100.1.38 NAME 'associatedName'
+ EQUALITY distinguishedNameMatch SYNTAX 'DN' )
+
+ ( 0.9.2342.19200300.100.1.39 NAME 'homePostalAddress'
+ EQUALITY caseIgnoreListMatch
+ SUBSTRINGS caseIgnoreListSubstringsMatch SYNTAX 'PostalAddress' )
+
+ ( 0.9.2342.19200300.100.1.40 NAME 'personalTitle'
+ EQUALITY caseIgnoreMatch SUBSTRINGS caseIgnoreSubstringsMatch
+ SYNTAX 'DirectoryString' )
+
+ ( 0.9.2342.19200300.100.1.41 NAME 'mobile' EQUALITY telephoneNumberMatch
+ SUBSTRINGS telephoneNumberSubstringsMatch SYNTAX 'TelephoneNumber{32}' )
+
+ ( 0.9.2342.19200300.100.1.42 NAME 'pager' EQUALITY telephoneNumberMatch
+ SUBSTRINGS telephoneNumberSubstringsMatch SYNTAX 'TelephoneNumber{32}' )
+
+ ( 0.9.2342.19200300.100.1.43 NAME 'co' EQUALITY caseIgnoreMatch
+ SUBSTRINGS caseIgnoreSubstringsMatch SYNTAX 'DirectoryString' )
+
+
+
+Wahl, Coulbeck, Howes & Kille [Page 11]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+ ( 0.9.2342.19200300.100.1.44 NAME 'uniqueIdentifier'
+ EQUALITY caseIgnoreMatch SUBSTRINGS caseIgnoreSubstringsMatch
+ SYNTAX 'DirectoryString' )
+
+ ( 0.9.2342.19200300.100.1.45 NAME 'organizationalStatus'
+ EQUALITY caseIgnoreMatch SUBSTRINGS caseIgnoreSubstringsMatch
+ SYNTAX 'DirectoryString{256}' )
+
+ ( 0.9.2342.19200300.100.1.46 NAME 'janetMailbox'
+ EQUALITY caseIgnoreIA5Match SUBSTRINGS caseIgnoreIA5SubstringsMatch
+ SYNTAX 'IA5String{256}' )
+
+ ( 0.9.2342.19200300.100.1.47 NAME 'mailPreferenceOption'
+ SYNTAX 'INTEGER' SINGLE-VALUE }
+
+ ( 0.9.2342.19200300.100.1.48 NAME 'buildingName'
+ EQUALITY caseIgnoreMatch SUBSTRINGS caseIgnoreSubstringsMatch
+ SYNTAX 'DirectoryString{256}' )
+
+ ( 0.9.2342.19200300.100.1.49 NAME 'dSAQuality'
+ SYNTAX 'DSAQualitySyntax' SINGLE-VALUE )
+
+ ( 0.9.2342.19200300.100.1.50 NAME 'singleLevelQuality'
+ SYNTAX 'DataQualitySyntax' SINGLE-VALUE )
+
+ ( 0.9.2342.19200300.100.1.51 NAME 'subtreeMinimumQuality'
+ SYNTAX 'DataQualitySyntax' SINGLE-VALUE )
+
+ ( 0.9.2342.19200300.100.1.52 NAME 'subtreeMaximumQuality'
+ SYNTAX 'DataQualitySyntax' SINGLE-VALUE )
+
+ ( 0.9.2342.19200300.100.1.53 NAME 'personalSignature'
+ SYNTAX 'Fax{50000}' )
+
+ ( 0.9.2342.19200300.100.1.54 NAME 'dITRedirect'
+ EQUALITY distinguishedNameMatch SYNTAX 'DN' )
+
+ ( 0.9.2342.19200300.100.1.55 NAME 'audio' SYNTAX 'Audio{250000}' )
+
+ ( 0.9.2342.19200300.100.1.56 NAME 'documentPublisher'
+ EQUALITY caseIgnoreMatch SUBSTRINGS caseIgnoreSubstringsMatch
+ SYNTAX 'DirectoryString' )
+
+ ( 0.9.2342.19200300.100.1.60 NAME 'jpegPhoto' SYNTAX 'JPEG' )
+
+
+
+
+
+
+
+
+
+
+Wahl, Coulbeck, Howes & Kille [Page 12]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+5.1.3. Standard Operational Attributes
+
+ All servers must recognize the attribute types defined in this
+ section.
+
+ ( 2.5.18.1 NAME 'createTimestamp' EQUALITY generalizedTimeMatch
+ ORDERING generalizedTimeOrderingMatch SYNTAX 'GeneralizedTime'
+ SINGLE-VALUE NO-USER-MODIFICATION USAGE directoryOperation )
+
+ ( 2.5.18.2 NAME 'modifyTimestamp' EQUALITY generalizedTimeMatch
+ ORDERING generalizedTimeOrderingMatch SYNTAX 'GeneralizedTime'
+ SINGLE-VALUE NO-USER-MODIFICATION USAGE directoryOperation )
+
+ ( 2.5.18.3 NAME 'creatorsName' EQUALITY distinguishedNameMatch SYNTAX 'DN'
+ SINGLE-VALUE NO-USER-MODIFICATION USAGE directoryOperation )
+
+ ( 2.5.18.4 NAME 'modifiersName' EQUALITY distinguishedNameMatch SYNTAX 'DN'
+ SINGLE-VALUE NO-USER-MODIFICATION USAGE directoryOperation )
+
+ ( 2.5.18.10 NAME 'subschemaSubentry'
+ DESC 'The value of this attribute is the name of a subschema subentry,
+ an entry in which the server makes available attributes specifying
+ the schema.'
+ EQUALITY distinguishedNameMatch SYNTAX 'DN' NO-USER-MODIFICATION
+ SINGLE-VALUE USAGE directoryOperation )
+
+ ( 2.5.21.5 NAME 'attributeTypes'
+ EQUALITY objectIdentifierFirstComponentMatch
+ SYNTAX 'AttributeTypeDescription' USAGE directoryOperation )
+
+ ( 2.5.21.6 NAME 'objectClasses'
+ EQUALITY objectIdentifierFirstComponentMatch
+ SYNTAX 'ObjectClassDescription' USAGE directoryOperation )
+
+5.1.4. LDAP Operational Attributes
+
+ All servers must recognize the attribute types defined in this section.
+ (Of course, it is not required that the server provide values for these
+ attributes, when the attribute corresponds to a feature which the server
+ does not implement.)
+
+ ( 1.3.6.1.4.1.1466.101.120.1 NAME 'administratorsAddress'
+ DESC 'This attribute\27s values are string containing the addresses of
+ the LDAP server\27s human administrator. This information may
+ be of use when tracking down problems in an Internet distributed
+ directory. For simplicity the syntax of the values are limited to
+ being URLs of the mailto form with an RFC 822 address:
+ "mailto:user@domain". Future versions of this protocol may permit
+ other forms of addresses.'
+ SYNTAX 'IA5String' USAGE dSAOperation )
+
+
+
+
+Wahl, Coulbeck, Howes & Kille [Page 13]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+ ( 1.3.6.1.4.1.1466.101.120.2 NAME 'currentTime'
+ DESC 'This attribute has a single value, a string containing a
+ GeneralizedTime character string. This attribute need only
+ be present if the server supports LDAP strong or protected
+ simple authentication. Otherwise if the server does not know
+ the current time, or does not choose to present it to clients,
+ this attribute need not be present. The client may wish to
+ use this value to detect whether a strong or protected bind
+ is failing because the client and server clocks are not
+ sufficiently synchronized. Clients must not use this time
+ field for setting their own system clock.'
+ SYNTAX 'GeneralizedTime' SINGLE-VALUE USAGE dSAOperation )
+
+ ( 1.3.6.1.4.1.1466.101.120.3 NAME 'serverName'
+ DESC 'This attribute\27s value is the server\27s Distinguished Name.
+ If the server does not have a Distinguished Name it will not
+ be able to accept X.509-style strong authentication, and this
+ attribute must be absent. However the presence of this
+ attribute does not guarantee that the server will be able to
+ perform strong authentication. If the server acts as a
+ gateway to more than one X.500 DSA capable of strong
+ authentication, there may be multiple values of this
+ attribute, one per DSA. (Note: this attribute is distinct
+ from myAccessPoint, for it is not required that a server
+ have a presentation address in order to perform strong
+ authentication.) (Note: it is likely that clients will
+ retrieve this attribute in binary.)'
+ SYNTAX 'DN' USAGE dSAOperation )
+
+ ( 1.3.6.1.4.1.1466.101.120.4 NAME 'certificationPath'
+ DESC 'This attribute contains a binary DER encoding of an
+ AF.CertificatePath data type, which is the certificate
+ path for a server. If the server does not have a certificate
+ path this attribute must be absent. (Note: this attribute
+ may only be retrieved in binary.)'
+ SYNTAX 'CertificatePath' USAGE dSAOperation )
+
+ ( 1.3.6.1.4.1.1466.101.120.5 NAME 'namingContexts'
+ DESC 'The values of this attribute correspond to naming contexts
+ which this server masters or shadows. If the server does
+ not master any information (e.g. it is an LDAP gateway to a
+ public X.500 directory) this attribute must be absent. If
+ the server believes it contains the entire directory, the
+ attribute must have a single value, and that value must
+ be the empty string (indicating the null DN of the root).
+ This attribute will allow clients to choose suitable base
+ objects for searching when it has contacted a server.'
+ SYNTAX 'DN' USAGE dSAOperation )
+
+
+
+
+
+
+Wahl, Coulbeck, Howes & Kille [Page 14]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+ ( 1.3.6.1.4.1.1466.101.120.6 NAME 'altServer'
+ DESC 'The values of this attribute are URLs of other servers which
+ may be contacted when this server becomes unavailable. If
+ the server does not know of any other servers which could be
+ used this attribute must be absent. Clients may cache this
+ information in case their preferred LDAP server later becomes
+ unavailable.'
+ SYNTAX 'IA5String' USAGE dSAOperation )
+
+ ( 1.3.6.1.4.1.1466.101.120.7 NAME 'supportedExtension'
+ DESC 'The values of this attribute are OBJECT IDENTIFIERs,
+ the names of supported extended operations
+ which the server supports. If the server does not support
+ any extensions this attribute must be absent.'
+ SYNTAX 'OID' USAGE dSAOperation )
+
+ ( 1.3.6.1.4.1.1466.101.120.13 NAME 'supportedControl'
+ DESC 'The values of this attribute are the names of supported session
+ controls which the server supports. If the server does not
+ support any controls this attribute must be absent.'
+ SYNTAX 'LDAPString' USAGE dSAOperation )
+
+ ( 1.3.6.1.4.1.1466.101.120.14 NAME 'supportedSASLMechanisms'
+ DESC 'The values of this attribute are the names of supported SASL
+ mechanisms which the server supports. If the server does not
+ support any mechanisms this attribute must be absent.'
+ SYNTAX 'LDAPString' USAGE dSAOperation )
+
+ ( 1.3.6.1.4.1.1466.101.120.8 NAME 'entryName'
+ SYNTAX 'DN' SINGLE-VALUE NO-USER-MODIFICATION USAGE directoryOperation )
+
+ ( 1.3.6.1.4.1.1466.101.120.9 NAME 'modifyRights'
+ SYNTAX 'ModifyRight' NO-USER-MODIFICATION USAGE dSAOperation )
+
+ ( 1.3.6.1.4.1.1466.101.120.10 NAME 'incompleteEntry'
+ SYNTAX 'BOOLEAN' NO-USER-MODIFICATION USAGE dSAOperation )
+
+ ( 1.3.6.1.4.1.1466.101.120.11 NAME 'fromEntry'
+ SYNTAX 'BOOLEAN' NO-USER-MODIFICATION USAGE dSAOperation )
+
+5.1.5. LDAP User Attributes
+
+ The following attributes may be of use in naming entries, or as
+ descriptive attributes in entries.
+
+ ( 1.3.6.1.4.1.1466.101.121.1 NAME 'url'
+ DESC 'Uniform Resource Locator'
+ EQUALITY caseExactIA5Match SYNTAX 'IA5String' )
+
+ Note that the associatedDomain attribute may be used to hold a DNS name.
+
+
+
+
+Wahl, Coulbeck, Howes & Kille [Page 15]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+5.2. Syntaxes
+
+5.2.1. Standard User Syntaxes
+
+ Servers must recognize all the syntaxes described in this section.
+
+5.2.1.1. BitString
+
+ The encoding of a value with BitString syntax is according to the
+ following BNF:
+
+ <bitstring> ::= ''' <binary-digits> ''B'
+
+ <binary-digits> ::= '0' <binary-digits> | '1' <binary-digits> |
+ empty
+
+
+5.2.1.2. PrintableString
+
+ The encoding of a value with PrintableString syntax is the string
+ value itself. PrintableString is limited to the characters in
+ production <p> of section 4.1.
+
+5.2.1.3. DirectoryString
+
+ A string with DirectoryString syntax is encoded in the UTF-8 form of
+ ISO 10646 (a superset of Unicode). Servers and clients must be prepared to
+ receive arbitrary Unicode characters in values.
+
+ For characters in the PrintableString form, the value is encoded as the
+ string value itself.
+
+ If it is of the TeletexString form, then the characters are transliterated
+ to their equivalents in UniversalString, and encoded in UTF-8 [11].
+
+ If it is of the UniversalString or BMPString forms [12], UTF-8 is used to
+ encode them.
+
+ Note: the form of DirectoryString is not indicated in protocol unless the
+ attribute value is carried in binary. Servers which convert to DAP must
+ choose an appropriate form. Servers must not reject values merely because
+ they contain legal Unicode characters outside of the range of printable
+ ASCII.
+
+5.2.1.4. Certificate
+
+ Because of the changes from X.509(1988) and X.509(1993) and additional
+ changes to the ASN.1 definition to support certificate extensions, no
+ string representation is defined, and values with Certificate syntax
+ must only be transferred using the binary encoding, by requesting or
+ returning the attributes with descriptions "userCertificate;binary" or
+ "caCertificate;binary". The BNF notation in RFC 1778 for
+ "User Certificate" is not recommended to be used.
+
+Wahl, Coulbeck, Howes & Kille [Page 16]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+5.2.1.5. CertificateList
+
+ Because of the incompatibility of the X.509(1988) and X.509(1993)
+ definitions of revocation lists, values with CertificateList syntax
+ must only be transferred using a binary encoding, by requesting or
+ returning the attributes with descriptions
+ "certificateRevocationList;binary" or "authorityRevocationList;binary".
+ The BNF notation in RFC 1778 for "Authority Revocation List" is not
+ recommended to be used.
+
+5.2.1.6. CertificatePair
+
+ Because the Certificate is being carried in binary, values with
+ CertificatePair syntax must only be transferred using a binary encoding,
+ by requesting or returning the attribute description
+ "crossCertificatePair;binary". The BNF notation in RFC 1778 for
+ "Certificate Pair" is not recommended to be used.
+
+5.2.1.7. CountryString
+
+ A value of CountryString syntax is encoded the same as a value of
+ DirectoryString syntax. Note that this syntax is limited to values of
+ exactly two printable string characters.
+
+ <CountryString> ::= <p> <p>
+
+5.2.1.8. DN
+
+ Values with DN (Distinguished Name) syntax are encoded to have the
+ representation defined in [5]. Note that this representation is not
+ reversible to the original ASN.1 encoding as the CHOICE of any
+ DirectoryString element in an RDN is no longer known.
+
+5.2.1.9. DeliveryMethod
+
+ Values with DeliveryMethod syntax are encoded according to the
+ following BNF:
+
+ <delivery-value> ::= <pdm> | <pdm> '$' <delivery-value>
+
+ <pdm> ::= 'any' | 'mhs' | 'physical' | 'telex' | 'teletex' |
+ 'g3fax' | 'g4fax' | 'ia5' | 'videotex' | 'telephone'
+
+5.2.1.10. EnhancedGuide
+
+ Values with the EnhancedGuide syntax are encoded according to the
+ following BNF:
+
+ <EnhancedGuide> ::= <objectclass> '#' <criteria> '#' <subset>
+
+ <subset> ::= "baseobject" | "oneLevel" | "wholeSubtree"
+
+
+
+Wahl, Coulbeck, Howes & Kille [Page 17]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+ The <criteria> production is defined in the Guide syntax below.
+ This syntax has been added subsequent to RFC 1778.
+
+5.2.1.11. FacsimileTelephoneNumber
+
+ Values with the FacsimileTelephoneNumber syntax are encoded according
+ to the following BNF:
+
+ <fax-number> ::= <printablestring> [ '$' <faxparameters> ]
+
+ <faxparameters> ::= <faxparm> | <faxparm> '$' <faxparameters>
+
+ <faxparm> ::= 'twoDimensional' | 'fineResolution' | 'unlimitedLength' |
+ 'b4Length' | 'a3Width' | 'b4Width' | 'uncompressed'
+
+ In the above, the first <printablestring> is the actual fax number,
+ and the <faxparm> tokens represent fax parameters.
+
+5.2.1.12. Guide
+
+ Values with the Guide syntax are encoded according to the following
+ BNF:
+
+ <guide-value> ::= [ <object-class> '#' ] <criteria>
+
+ <object-class> ::= an encoded value with OID syntax
+
+ <criteria> ::= <criteria-item> | <criteria-set> | '!' <criteria>
+
+ <criteria-set> ::= [ '(' ] <criteria> '&' <criteria-set> [ ')' ] |
+ [ '(' ] <criteria> '|' <criteria-set> [ ')' ]
+
+ <criteria-item> ::= [ '(' ] <attributetype> '$' <match-type> [ ')' ]
+
+ <match-type> ::= "EQ" | "SUBSTR" | "GE" | "LE" | "APPROX"
+
+5.2.1.13. NameAndOptionalUID
+
+ The encoding of a value with the NameAndOptionalUID syntax is according
+ to the following BNF:
+
+ <NameAndOptionalUID> ::=
+ <DistinguishedName> [ '#' <BitString> ]
+
+ Although the '#' character may occur in a string representation of a
+ distinguished name, no additional special quoting is done in the
+ distinguished name other than that of [5].
+
+ This syntax has been added subsequent to RFC 1778.
+
+
+
+
+
+Wahl, Coulbeck, Howes & Kille [Page 18]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+5.2.1.14. NumericString
+
+ The encoding of a string with the NumericString syntax is the string
+ value itself.
+
+5.2.1.15. OID
+
+ Values with OID (Object Identifier) syntax are encoded according to the
+ following BNF:
+
+ <oid> ::= <descr> | <numericoid>
+
+ <descr> ::= <keystring>
+
+ <numericoid> ::= <numericstring> | <numericstring> '.' <numericoid>
+
+ In the above BNF, <descr> is the syntactic representation of an
+ object descriptor, which must consist of letters and digits, starting
+ with a letter. When encoding values with OID syntax, the first encoding
+ option must be used in preference to the second. That is, in encoding
+ object identifiers, object descriptors (where assigned and known by
+ the implementation) must be used in preference to numeric oids to
+ the greatest extent possible. All permitted object descriptors for use
+ in LDAP are given in this document. No other object descriptors may be
+ used. (Note that clients must expect that LDAPv2 implementations
+ will return object descriptors other than those listed.)
+
+5.2.1.16. Password
+
+ Values with Password syntax are encoded as octet strings.
+
+5.2.1.17. PostalAddress
+
+ Values with the PostalAddress syntax are encoded according to the
+ following BNF:
+
+ <postal-address> ::= <dstring> | <dstring> '$' <postal-address>
+
+ In the above, each <dstring> component of a postal address value is
+ encoded as a value of type DirectoryString syntax. Backslashes and
+ dollar characters, if they occur in the component, are quoted as
+ described in section 4.2.
+
+5.2.1.18. PresentationAddress
+
+ Values with the PresentationAddress syntax are encoded to have the
+ representation described in [6].
+
+5.2.1.20. TelephoneNumber
+
+ Values with the TelephoneNumber syntax are encoded as if they were
+ Printable String types. Telephone numbers are recommended in X.520 to
+ be in international form, e.g. "+1 512 305 0280".
+
+Wahl, Coulbeck, Howes & Kille [Page 19]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+5.2.1.21. TeletexTerminalIdentifier
+
+ Values with the TeletexTerminalIdentifier syntax are encoded according
+ to the following BNF:
+
+ <teletex-id> ::= <ttx-term> 0*('$' <ttx-param>)
+
+ <ttx-term> ::= <printablestring>
+
+ <ttx-param> ::= <ttx-key> ':' <ttx-value>
+
+ <ttx-key> ::= 'graphic' | 'control' | 'misc' | 'page' | 'private'
+
+ <ttx-value> ::= <octetstring>
+
+ In the above, the first <printablestring> is the encoding of the
+ first portion of the teletex terminal identifier to be encoded, and
+ the subsequent 0 or more <octetstrings> are subsequent portions
+ of the teletex terminal identifier.
+
+5.2.1.22. TelexNumber
+
+ Values with the TelexNumber syntax are encoded according to the
+ following BNF:
+
+ <telex-number> ::= <actual-number> '$' <country> '$' <answerback>
+
+ <actual-number> ::= <printablestring>
+
+ <country> ::= <printablestring>
+
+ <answerback> ::= <printablestring>
+
+ In the above, <actual-number> is the syntactic representation of the
+ number portion of the TELEX number being encoded, <country> is the
+ TELEX country code, and <answerback> is the answerback code of a
+ TELEX terminal.
+
+5.2.1.23. UTCTime
+
+ Values with UTCTime syntax are encoded as if they were printable
+ strings with the strings containing a UTCTime value. This is historical;
+ new attribute definitions must use GeneralizedTime instead.
+
+5.2.1.24. Boolean
+
+ Values with Boolean syntax are encoded according to the following
+ BNF:
+
+ <boolean> ::= "TRUE" | "FALSE"
+
+ Boolean values have an encoding of "TRUE" if they are logically true,
+ and have an encoding of "FALSE" otherwise.
+
+Wahl, Coulbeck, Howes & Kille [Page 20]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+5.2.2. Pilot Syntaxes
+
+ Servers must recognize all the syntaxes described in this section.
+
+5.2.2.1. Audio
+
+ The encoding of a value with Audio syntax is the octets of the value
+ itself, an 8KHz uncompressed encoding compatible with the SunOS
+ 4.1.3 'play' utility.
+
+5.2.2.2. DSAQualitySyntax
+
+ Values with this syntax are encoded according to the following BNF:
+
+ <DsaQualitySyntax> ::= <DSAKeyword> [ '#' <description> ]
+
+ <DSAKeyword> ::= 'DEFUNCT' | 'EXPERIMENTAL' | 'BEST-EFFORT' |
+ 'PILOT-SERVICE' | 'FULL-SERVICE'
+
+ <description> ::= encoded as a PrintableString
+
+5.2.2.3. DataQualitySyntax
+
+ Values with this syntax are encoded according to the following BNF:
+
+ <DataQualitySyntax> ::= <compKeyword> '#' <attrQuality> '#'
+ <listQuality> [ '#' <description> ]
+
+ <attrQuality> ::= <levelKeyword> '+' <compKeyword>
+
+ <listQuality> ::= <list> '$' <list><listQuality>
+
+ <list> ::= <attribute> '+' <attrQuality>
+
+ <compKeyword> ::= 'NONE' | 'SAMPLE' | 'SELECTED' |
+ 'SUBSTANTIAL' | 'FULL'
+
+ <levelKeyword> ::= 'UNKNOWN' | 'EXTERNAL' | 'SYSTEM-MAINTAINED' |
+ 'USER-SUPPLIED'
+
+5.2.2.4. IA5String
+
+ The encoding of a value with IA5String syntax is the string value
+ itself.
+
+5.2.2.5. JPEG
+
+ Values with JPEG syntax are encoded as if they were octet strings
+ containing JPEG images in the JPEG File Interchange Format (JFIF), as
+ described in [8].
+
+
+
+
+Wahl, Coulbeck, Howes & Kille [Page 21]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+5.2.2.6. MailPreference
+
+ Values with MailPreference syntax are encoded according to the
+ following BNF:
+
+ <mail-preference> ::= "NO-LISTS" | "ANY-LIST" | "PROFESSIONAL-LISTS"
+
+5.2.2.7. OtherMailbox
+
+ Values of the OtherMailbox syntax are encoded according to the
+ following BNF:
+
+ <otherMailbox> ::= <mailbox-type> '$' <mailbox>
+
+ <mailbox-type> ::= an encoded Printable String
+
+ <mailbox> ::= an encoded IA5 String
+
+ In the above, <mailbox-type> represents the type of mail system in
+ which the mailbox resides, for example "MCIMail"; and <mailbox> is the
+ actual mailbox in the mail system defined by <mailbox-type>.
+
+5.2.2.8. Fax
+
+ Values with Fax syntax are encoded as if they were octet strings
+ containing Group 3 Fax images as defined in [7].
+
+5.2.3. Operational Syntaxes
+
+ Servers must recognize all the syntaxes described in this section.
+
+5.2.3.1. AttributeTypeDescription
+
+ Values with this syntax are encoded according to the BNF given at the
+ start of section 4.1. For example,
+
+ ( 2.5.4.0 NAME 'objectClass' SYNTAX 'OID' )
+
+5.2.3.2. 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
+
+5.2.3.3. INTEGER
+
+ Values with INTEGER syntax are encoded as the decimal representation
+ of their values, with each decimal digit represented by the its
+ character equivalent. So the number 1321 is represented by the character
+ string "1321".
+
+
+Wahl, Coulbeck, Howes & Kille [Page 22]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+5.2.3.4. ObjectClassDescription
+
+ Values of this syntax are encoded according to the BNF in section 4.3.
+
+5.3. Object Classes
+
+5.3.1. Standard Classes
+
+ Servers must recognize the object classes listed here as values of
+ the objectClass attribute. With the exception of groupOfUniqueNames,
+ they are described in RFC 1274.
+
+ ( 2.5.6.0 NAME 'top' ABSTRACT MUST objectClass )
+
+ ( 2.5.6.1 NAME 'alias' SUP top STRUCTURAL MUST aliasedObjectName )
+
+ ( 2.5.6.2 NAME 'country' SUP top STRUCTURAL MUST c
+ MAY ( searchGuide $ description ) )
+
+ ( 2.5.6.3 NAME 'locality' SUP top STRUCTURAL
+ MAY ( street $ seeAlso $ searchGuide $ st $ l $ description ) )
+
+ ( 2.5.6.4 NAME 'organization' SUP top STRUCTURAL MUST o
+ MAY ( userPassword $ searchGuide $ seeAlso $ businessCategory $
+ x121Address $ registeredAddress $ destinationIndicator $
+ preferredDeliveryMethod $ telexNumber $ teletexTerminalIdentifier $
+ telephoneNumber $ internationaliSDNNumber $ facsimileTelephoneNumber $
+ street $ postOfficeBox $ postalCode $ postalAddress $
+ physicalDeliveryOfficeName $ st $ l $ description ) )
+
+ ( 2.5.6.5 NAME 'organizationalUnit' SUP top STRUCTURAL MUST ou
+ MAY ( userPassword $ searchGuide $ seeAlso $ businessCategory $
+ x121Address $ registeredAddress $ destinationIndicator $
+ preferredDeliveryMethod $ telexNumber $ teletexTerminalIdentifier $
+ telephoneNumber $ internationaliSDNNumber $ facsimileTelephoneNumber $
+ street $ postOfficeBox $ postalCode $ postalAddress $
+ physicalDeliveryOfficeName $ st $ l $ description ) )
+
+ ( 2.5.6.6 NAME 'person' SUP top STRUCTURAL MUST ( sn $ cn )
+ MAY ( userPassword $ telephoneNumber $ seeAlso $ description ) )
+
+ ( 2.5.6.7 NAME 'organizationalPerson' SUP person STRUCTURAL
+ MAY ( title $ x121Address $ registeredAddress $ destinationIndicator $
+ preferredDeliveryMethod $ telexNumber $ teletexTerminalIdentifier $
+ telephoneNumber $ internationaliSDNNumber $ facsimileTelephoneNumber $
+ street $ postOfficeBox $ postalCode $ postalAddress $
+ physicalDeliveryOfficeName $ ou $ st $ l ) )
+
+
+
+
+
+
+
+Wahl, Coulbeck, Howes & Kille [Page 23]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+ ( 2.5.6.8 NAME 'organizationalRole' SUP top STRUCTURAL MUST cn
+ MAY ( x121Address $ registeredAddress $ destinationIndicator $
+ preferredDeliveryMethod $ telexNumber $ teletexTerminalIdentifier $
+ telephoneNumber $ internationaliSDNNumber $ facsimileTelephoneNumber $
+ seeAlso $ roleOccupant $ preferredDeliveryMethod $ street $
+ postOfficeBox $ postalCode $ postalAddress $
+ physicalDeliveryOfficeName $ ou $ st $ l $ description ) )
+
+ ( 2.5.6.9 NAME 'groupOfNames' SUP top STRUCTURAL MUST ( member $ cn )
+ MAY ( businessCategory $ seeAlso $ owner $ ou $ o $ description ) )
+
+ ( 2.5.6.10 NAME 'residentialPerson' SUP person STRUCTURAL MUST l
+ MAY ( businessCategory $ x121Address $ registeredAddress $
+ destinationIndicator $ preferredDeliveryMethod $ telexNumber $
+ teletexTerminalIdentifier $ telephoneNumber $ internationaliSDNNumber $
+ facsimileTelephoneNumber $ preferredDeliveryMethod $ street $
+ postOfficeBox $ postalCode $ postalAddress $
+ physicalDeliveryOfficeName $ st $ l ) )
+
+ ( 2.5.6.11 NAME 'applicationProcess' SUP top STRUCTURAL MUST cn
+ MAY ( seeAlso $ ou $ l $ description ) )
+
+ ( 2.5.6.12 NAME 'applicationEntity' SUP top STRUCTURAL
+ MUST ( presentationAddress $ cn )
+ MAY ( supportedApplicationContext $ seeAlso $ ou $ o $ l $
+ description ) )
+
+ ( 2.5.6.13 NAME 'dSA' SUP applicationEntity STRUCTURAL
+ MAY knowledgeInformation )
+
+ ( 2.5.6.14 NAME 'device' SUP top STRUCTURAL MUST cn
+ MAY ( serialNumber $ seeAlso $ owner $ ou $ o $ l $ description ) )
+
+ ( 2.5.6.15 NAME 'strongAuthenticationUser' SUP top STRUCTURAL
+ MUST userCertificate )
+
+ ( 2.5.6.16 NAME 'certificationAuthority' SUP top STRUCTURAL
+ MUST ( authorityRevocationList $ certificateRevocationList $
+ cACertificate ) MAY crossCertificatePair )
+
+ ( 2.5.6.17 NAME 'groupOfUniqueNames' SUP top STRUCTURAL
+ MUST ( uniqueMember $ cn )
+ MAY ( businessCategory $ seeAlso $ owner $ ou $ o $ description ) )
+
+5.3.2. Pilot Classes
+
+ These object classes are defined in RFC 1274. All servers must recognize
+ these object class names.
+
+ ( 0.9.2342.19200300.100.4.3 NAME 'pilotObject' SUP top STRUCTURAL
+ MAY ( jpegPhoto $ audio $ dITRedirect $ lastModifiedBy $
+ lastModifiedTime $ uniqueIdentifier $ manager $ photo $ info ) )
+
+
+Wahl, Coulbeck, Howes & Kille [Page 24]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+ ( 0.9.2342.19200300.100.4.4 NAME 'newPilotPerson' SUP person
+ STRUCTURAL MAY ( personalSignature $ mailPreferenceOption $
+ organizationalStatus $ pagerTelephoneNumber $ mobileTelephoneNumber $
+ otherMailbox $ janetMailbox $ businessCategory $
+ preferredDeliveryMethod $ personalTitle $ secretary $
+ homePostalAddress $ homePhone $ userClass $ roomNumber $
+ favouriteDrink $ rfc822Mailbox $ textEncodedORaddress $ userid ) )
+
+ ( 0.9.2342.19200300.100.4.5 NAME 'account' SUP top STRUCTURAL
+ MUST userid MAY ( host $ ou $ o $ l $ seeAlso $ description ) )
+
+ ( 0.9.2342.19200300.100.4.6 NAME 'document' SUP ( top $ pilotObject )
+ STRUCTURAL MUST documentIdentifier
+ MAY ( documentPublisher $ documentStore $ documentAuthorSurName $
+ documentAuthorCommonName $ abstract $ subject $ keywords $
+ updatedByDocument $ updatesDocument $ obsoletedByDocument $
+ obsoletesDocument $ documentLocation $ documentAuthor $
+ documentVersion $ documentTitle $ ou $ o $ l $ seeAlso $ description $
+ cn ) )
+
+ ( 0.9.2342.19200300.100.4.7 NAME 'room' SUP top STRUCTURAL MUST cn
+ MAY ( telephoneNumber $ seeAlso $ description $ roomNumber ) )
+
+ ( 0.9.2342.19200300.100.4.9 NAME 'documentSeries' SUP top STRUCTURAL
+ MUST cn MAY ( ou $ o $ l $ telephoneNumber $ seeAlso $ description ) )
+
+ ( 0.9.2342.19200300.100.4.13 NAME 'domain' SUP top STRUCTURAL
+ MUST dc
+ MAY ( userPassword $ searchGuide $ seeAlso $ businessCategory $
+ x121Address $ registeredAddress $ destinationIndicator $
+ preferredDeliveryMethod $ telexNumber $ teletexTerminalIdentifier $
+ telephoneNumber $ internationaliSDNNumber $ facsimileTelephoneNumber $
+ street $ postOfficeBox $ postalCode $ postalAddress $
+ physicalDeliveryOfficeName $ st $ l $ description $ o $
+ associatedName ) )
+
+ ( 0.9.2342.19200300.100.4.14 NAME 'rFC822localPart' SUP domain
+ STRUCTURAL
+ MAY ( x121Address $ registeredAddress $ destinationIndicator $
+ preferredDeliveryMethod $ telexNumber $ teletexTerminalIdentifier $
+ telephoneNumber $ internationaliSDNNumber $ facsimileTelephoneNumber $
+ streetAddress $ postOfficeBox $ postalCode $ postalAddress $
+ physicalDeliveryOfficeName $ telephoneNumber $ seeAlso $ description $
+ sn $ cn ) )
+
+ ( 0.9.2342.19200300.100.4.15 NAME 'dNSDomain' SUP domain STRUCTURAL
+ MAY dNSRecord )
+
+ ( 0.9.2342.19200300.100.4.17 NAME 'domainRelatedObject' SUP top
+ STRUCTURAL MUST associatedDomain )
+
+ ( 0.9.2342.19200300.100.4.18 NAME 'friendlyCountry' SUP country
+ STRUCTURAL MUST co )
+
+Wahl, Coulbeck, Howes & Kille [Page 25]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+ ( 0.9.2342.19200300.100.4.19 NAME 'simpleSecurityObject' SUP top
+ STRUCTURAL MUST userPassword )
+
+ ( 0.9.2342.19200300.100.4.20 NAME 'pilotOrganization'
+ SUP ( organization $ organizationalUnit ) STRUCTURAL
+ MAY buildingName )
+
+ ( 0.9.2342.19200300.100.4.21 NAME 'pilotDSA' SUP dSA STRUCTURAL
+ MUST dSAQuality )
+
+ ( 0.9.2342.19200300.100.4.23 NAME 'qualityLabelledData' SUP top
+ STRUCTURAL MUST singleLevelQuality
+ MAY ( subtreeMaximumQuality $ subtreeMinimumQuality ) )
+
+5.4. Matching Rules
+
+ Servers must recognize the following matching rules, used for equality
+ matching, and must be capable of performing the matching rules.
+ For all these rules, the assertion syntax is the same as the value syntax.
+
+ ( 2.5.13.0 NAME 'objectIdentifierMatch' SYNTAX 'OID' )
+ ( 2.5.13.1 NAME 'distinguishedNameMatch' SYNTAX 'DN' )
+ ( 2.5.13.2 NAME 'caseIgnoreMatch' SYNTAX 'DirectoryString' )
+ ( 2.5.13.8 NAME 'numericStringMatch' SYNTAX 'NumericString' )
+ ( 2.5.13.11 NAME 'caseIgnoreListMatch' SYNTAX 'PostalAddress' )
+ ( 2.5.13.14 NAME 'integerMatch' SYNTAX 'INTEGER' )
+ ( 2.5.13.16 NAME 'bitStringMatch' SYNTAX 'BitString' )
+ ( 2.5.13.17 NAME 'octetStringMatch' SYNTAX 'Password' )
+ ( 2.5.13.20 NAME 'telephoneNumberMatch' SYNTAX 'TelephoneNumber' )
+ ( 2.5.13.27 NAME 'generalizedTimeMatch' SYNTAX 'GeneralizedTime' )
+ ( 1.3.6.1.4.1.1466.109.114.1 NAME 'caseExactIA5Match' SYNTAX 'IA5String' )
+ ( 1.3.6.1.4.1.1466.109.114.2 NAME 'caseIgnoreIA5Match' SYNTAX 'IA5String' )
+
+ When performing the caseIgnoreMatch, caseIgnoreListMatch,
+ telephoneNumberMatch, caseExactIA5Match and caseIgnoreIA5Match,
+ multiple adjoining whitespace characters are treated the same as
+ an individual space, and leading and trailing whitespace is ignored.
+
+6. X.500 Definitions
+
+ Servers which implement the X.500(1993) protocols are required to recognize
+ these attributes types, syntaxes, object classes and matching rules, where
+ they correspond to X.500 features implemented by that server. No other
+ servers are required to implement any definitions in section 6, although
+ they may do so.
+
+ Clients must not assume these definitions are recognized by all servers.
+
+6.1. Attribute Types
+
+6.1.1. User Attributes
+
+ All user attributes of X.500 are listed in section 5.1.1.
+
+Wahl, Coulbeck, Howes & Kille [Page 26]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+6.1.2. Collective Attributes
+
+ These attributes are stored in collective attribute subentries, but may
+ be visible in user entries if requested.
+
+ Each of these collective attributes is a subtype of the attribute which
+ has the OID without the final ".1", e.g. "collectivePostalCode" is a
+ subtype of "postalCode".
+
+ ( 2.5.4.7.1 NAME 'collectiveLocalityName' SUP l COLLECTIVE )
+
+ ( 2.5.4.8.1 NAME 'collectiveStateOrProvinceName' SUP st COLLECTIVE )
+
+ ( 2.5.4.9.1 NAME 'collectiveStreetAddress' SUP street COLLECTIVE )
+
+ ( 2.5.4.10.1 NAME 'collectiveOrganizationName' SUP o COLLECTIVE )
+
+ ( 2.5.4.11.1 NAME 'collectiveOrganizationalUnitName' SUP ou COLLECTIVE )
+
+ ( 2.5.4.16.1 NAME 'collectivePostalAddress' SUP postalAddress COLLECTIVE )
+
+ ( 2.5.4.17.1 NAME 'collectivePostalCode' SUP postalCode COLLECTIVE )
+
+ ( 2.5.4.18.1 NAME 'collectivePostOfficeBox' SUP postOfficeBox COLLECTIVE )
+
+ ( 2.5.4.19.1 NAME 'collectivePhysicalDeliveryOfficeName'
+ SUP physicalDeliveryOfficeName COLLECTIVE )
+
+ ( 2.5.4.20.1 NAME 'collectiveTelephoneNumber' SUP telephoneNumber
+ COLLECTIVE )
+
+ ( 2.5.4.21.1 NAME 'collectiveTelexNumber' SUP 'TelexNumber' COLLECTIVE )
+
+ ( 2.5.4.22.1 NAME 'collectiveTeletexTerminalIdentifier'
+ SUP teletexTerminalIdentifier COLLECTIVE )
+
+ ( 2.5.4.23.1 NAME 'collectiveFacsimileTelephoneNumber'
+ SUP facsimileTelephoneNumber COLLECTIVE )
+
+ ( 2.5.4.25.1 NAME 'collectiveInternationaliSDNNumber'
+ SUP internationaliSDNNumber COLLECTIVE )
+
+6.1.3. Standard Operational Attributes
+
+ These attributes are defined in X.501(1993) Annexes B through E.
+
+ ( 2.5.18.5 NAME 'administrativeRole' EQUALITY objectIdentifierMatch
+ SYNTAX 'OID' USAGE directoryOperation )
+
+ ( 2.5.18.6 NAME 'subtreeSpecification' SYNTAX 'SubtreeSpecification'
+ SINGLE-VALUE USAGE directoryOperation )
+
+
+
+Wahl, Coulbeck, Howes & Kille [Page 27]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+ ( 2.5.18.7 NAME 'collectiveExclusions' EQUALITY objectIdentifierMatch
+ SYNTAX 'OID' USAGE directoryOperation )
+
+ ( 2.5.21.1 NAME 'dITStructureRules' EQUALITY integerFirstComponentMatch
+ SYNTAX 'DITStructureRuleDescription' USAGE directoryOperation )
+
+ ( 2.5.21.2 NAME 'dITContentRules'
+ EQUALITY objectIdentifierFirstComponentMatch
+ SYNTAX 'DITContentRuleDescription' USAGE directoryOperation )
+
+ ( 2.5.21.4 NAME 'matchingRules'
+ EQUALITY objectIdentifierFirstComponentMatch
+ SYNTAX 'MatchingRuleDescription' USAGE directoryOperation )
+
+ ( 2.5.21.7 NAME 'nameForms'
+ EQUALITY objectIdentifierFirstComponentMatch
+ SYNTAX 'NameFormDescription' USAGE directoryOperation )
+
+ ( 2.5.21.8 NAME 'matchingRuleUse'
+ EQUALITY objectIdentifierFirstComponentMatch
+ SYNTAX 'MatchingRuleUseDescription' USAGE directoryOperation )
+
+ ( 2.5.21.9 NAME 'structuralObjectClass' EQUALITY objectIdentifierMatch
+ SYNTAX 'OID' SINGLE-VALUE NO-USER-MODIFICATION
+ USAGE directoryOperation )
+
+ ( 2.5.21.10 NAME 'governingStructuralRule' EQUALITY integerMatch
+ SYNTAX 'INTEGER' SINGLE-VALUE NO-USER-MODIFICATION
+ USAGE directoryOperation )
+
+ ( 2.5.24.1 NAME 'accessControlScheme' EQUALITY objectIdentifierMatch
+ SYNTAX 'OID' SINGLE-VALUE USAGE directoryOperation )
+
+ ( 2.5.24.4 NAME 'prescriptiveACI'
+ EQUALITY directoryStringFirstComponentMatch SYNTAX 'ACIItem'
+ USAGE directoryOperation )
+
+ ( 2.5.24.5 NAME 'entryACI'
+ EQUALITY directoryStringFirstComponentMatch SYNTAX 'ACIItem'
+ USAGE directoryOperation )
+
+ ( 2.5.24.6 NAME 'subentryACI'
+ EQUALITY directoryStringFirstComponentMatch SYNTAX 'ACIItem'
+ USAGE directoryOperation )
+
+ ( 2.5.12.0 NAME 'dseType' EQUALITY bitStringMatch SYNTAX 'DSEType'
+ SINGLE-VALUE NO-USER-MODIFICATION USAGE dSAOperation )
+
+ ( 2.5.12.1 NAME 'myAccessPoint' EQUALITY accessPointMatch
+ SYNTAX 'AccessPoint' SINGLE-VALUE NO-USER-MODIFICATION
+ USAGE dSAOperation )
+
+
+
+Wahl, Coulbeck, Howes & Kille [Page 28]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+ ( 2.5.12.2 NAME 'superiorKnowledge' EQUALITY accessPointMatch
+ SYNTAX 'AccessPoint' SINGLE-VALUE NO-USER-MODIFICATION
+ USAGE dSAOperation )
+
+ ( 2.5.12.3 NAME 'specificKnowledge'
+ EQUALITY masterAndShadowAccessPointsMatch
+ SYNTAX 'MasterAndShadowAccessPoints'
+ SINGLE-VALUE NO-USER-MODIFICATION USAGE distributedOperation )
+
+ ( 2.5.12.4 NAME 'nonSpecificKnowledge'
+ EQUALITY masterAndShadowAccessPointsMatch
+ SYNTAX 'MasterAndShadowAccessPoints' NO-USER-MODIFICATION
+ USAGE distributedOperation )
+
+ ( 2.5.12.5 NAME 'supplierKnowledge'
+ EQUALITY supplierOrConsumerInformationMatch
+ SYNTAX 'SupplierInformation'
+ NO-USER-MODIFICATION USAGE dSAOperation )
+
+ ( 2.5.12.6 NAME 'consumerKnowledge'
+ EQUALITY supplierOrConsumerInformationMatch
+ SYNTAX 'SupplierOrConsumer'
+ NO-USER-MODIFICATION USAGE dSAOperation )
+
+ ( 2.5.12.7 NAME 'secondaryShadows'
+ EQUALITY supplierAndConsumersMatch
+ SYNTAX 'SupplierAndConsumers'
+ NO-USER-MODIFICATION USAGE dSAOperation )
+
+6.1.4. LDAP-defined Operational Attributes
+
+6.1.4.1. targetSystem
+
+ ( 1.3.6.1.4.1.1466.101.120.12 NAME 'targetSystem'
+ SYNTAX 'AccessPoint' SINGLE-VALUE NO-USER-MODIFICATION
+ USAGE distributedOperation )
+
+ The value of this attribute may be supplied in an AddEntry operation
+ to inform the Directory of the target server on which the entry is to
+ be held. This is used to create a new naming context in the directory
+ tree. A server which does not permit the use of this attribute must
+ return an appropriate error code if it is present in the attribute list.
+ This attribute will generally not be present in the entry after the add
+ is completed.
+
+
+
+
+
+
+
+
+
+
+Wahl, Coulbeck, Howes & Kille [Page 29]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+6.2. Syntaxes
+
+6.2.1. Standard Syntaxes
+
+6.2.1.1. ACIItem
+
+ This syntax appears too complicated for a compact string representation
+ to be useful. Clients must only request and servers must only return
+ values which use the the binary encoding of the value, e.g.
+ "entryACI;binary".
+
+ It is recommended that clients that wish to only determine whether they
+ have been granted permission to modify an entry use the "modifyRights"
+ attribute rather than attempt to parse this syntax.
+
+6.2.1.2. AccessPoint
+
+ Values with AccessPoint syntax are encoded according to the
+ following BNF:
+
+ <AccessPoint> ::= ( '(' <DistinguishedName> '#'
+ <PresentationAddress> ')' ) |
+ -- Optional protocol info absent, parenthesis required
+ ( '(' <DistinguishedName> '#'
+ <PresentationAddress> '#'
+ <SetOfProtocolInformation ')' )
+
+ <SetOfProtocolInformation> ::= <ProtocolInformation> |
+ '(' <ProtocolInformationList> ')'
+
+ <ProtocolInformationList> ::= <ProtocolInformation> |
+ <ProtocolInformation> '$'
+ <ProtocolInformationList>
+
+6.2.1.3. DITContentRuleDescription
+
+ Values with this syntax are encoded according to the following BNF:
+
+ <DITContentRuleDescription> ::= "("
+ <oid> -- Structural ObjectClass identifier
+ [ "NAME" <DirectoryStrings> ]
+ [ "DESC" <DirectoryString> ]
+ [ "OBSOLETE" ]
+ [ "AUX" <oids> ] -- Auxiliary ObjectClasses
+ [ "MUST" <oids> ] -- AttributeType identifiers
+ [ "MAY" <oids> ] -- AttributeType identifiers
+ [ "NOT" <oids> ] -- AttributeType identifiers
+ ")"
+
+
+
+
+
+
+Wahl, Coulbeck, Howes & Kille [Page 30]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+6.2.1.4. DITStructureRuleDescription
+
+ Values with this syntax are encoded according to the following BNF:
+
+ <DITStructureRuleDescription> ::= "("
+ <RuleIdentifier> -- DITStructureRule identifier
+ [ "NAME" <DirectoryStrings> ]
+ [ "DESC" <DirectoryString> ]
+ [ "OBSOLETE" ]
+ "FORM" <oid> -- NameForm
+ [ "SUP" <RuleIdentifiers> ] -- superior DITStructureRules
+ ")"
+
+ <RuleIdentifier> ::= <integer>
+
+ <RuleIdentifiers> ::=
+ <RuleIdentifier> |
+ "(" <RuleIdentifierList> ")"
+
+ <RuleIdentifierList> ::=
+ <RuleIdentifierList> <RuleIdentifier>
+ |
+ -- empty list
+
+6.2.1.5. DSEType
+
+ Values with DSEType syntax are encoded according to the following BNF:
+
+ <DSEType> ::= '(' <DSEBitList> ')'
+
+ <DSEBitList> ::= <DSEBit> | <DSEBit> '$' <DSEBitList>
+
+ <DSEBit> ::= 'root' | 'glue' | 'cp' | 'entry' | 'alias' | 'subr' |
+ 'nssr' | 'supr' | 'xr' | 'admPoint' | 'subentry' |
+ 'shadow' | 'zombie' | 'immSupr' | 'rhob' | 'sa'
+
+6.2.1.6. MasterAndShadowAccessPoints
+
+ Values of this syntax are encoded according to the following BNF:
+
+ <MasterAndShadowAccessPoints> ::= <MasterOrShadowAccessPoint> |
+ '(' <MasterAndShadowAccessPointList ')'
+
+ <MasterAndShadowAccessPointList> ::= <MasterOrShadowAccessPoint> |
+ <MasterOrShadowAccessPoint> '$' <MasterAndShadowAccessPointList>
+
+ <MasterOrShadowAccessPoint> ::= <category> '#' <AccessPoint>
+
+ <category> ::= 'master' | 'shadow'
+
+6.2.1.7. MatchingRuleDescription
+
+ Values of this syntax are encoded according to the BNF of section 4.4.
+
+Wahl, Coulbeck, Howes & Kille [Page 31]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+6.2.1.8. MatchingRuleUseDescription
+
+ Values of this syntax are encoded according to the following BNF:
+
+ <MatchingRuleUseDescription> ::= "("
+ <oid> -- MatchingRule identifier
+ [ "NAME" <DirectoryStrings> ]
+ [ "DESC" <DirectoryString> ]
+ [ "OBSOLETE" ]
+ "APPLIES" <oids> -- AttributeType identifiers
+ ")"
+
+6.2.1.9. NameFormDescription
+
+ Values of this syntax are encoded according to the following BNF:
+
+ <NameFormDescription> ::= "("
+ <oid> -- NameForm identifier
+ [ "NAME" <DirectoryStrings> ]
+ [ "DESC" <DirectoryString> ]
+ [ "OBSOLETE" ]
+ "OC" <oid> -- Structural ObjectClass
+ "MUST" <oids> -- AttributeTypes
+ [ "MAY" <oids> ] -- AttributeTypes
+ ")"
+
+6.2.1.10. SubtreeSpecification
+
+ Values of this syntax are encoded according to the following BNF:
+
+ <SubtreeSpecification> ::= '(' [<localname>] '#'
+ [<exclusionlist>] '#'
+ [<minimum>] '#' [<maximum>] '#'
+ [<refinement>] ')'
+
+ <localname> ::= <DistinguishedName>
+
+ <exclusionlist> ::= '(' <exclusions> ')'
+
+ <exclusions> ::= <exclusion> | <exclusion> '$' <exclusionlist>
+
+ <exclusion> ::= ( 'before ' <DistinguishedName> ) |
+ ( 'after ' <DistinguishedName> )
+
+ <minimum> ::= <numericstring>
+
+ <maximum> ::= <numericstring>
+
+ <refinement> ::= <oid> | '!' <refinement> |
+ '( &' <refinements> ')' |
+ '( |' <refinements> ')'
+
+ <refinements> ::= <refinement> | <refinement> '$' <refinements>
+
+Wahl, Coulbeck, Howes & Kille [Page 32]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+6.2.1.11. SupplierInformation
+
+ Values of this syntax are encoded according to the following BNF:
+
+ <SupplierInformation> ::=
+ -- supplier is master --
+ '(' 'master' '#' <SupplierOrConsumer> ')' |
+
+ -- supplier is not master, master unspecified --
+ '(' 'shadow' '#' <SupplierOrConsumer> ')' |
+
+ -- supplier not master, master specified --
+ ['('] 'shadow' '#' <SupplierOrConsumer> '#' <AccessPoint> [')']
+
+6.2.1.12. SupplierOrConsumer
+
+ Values of this syntax are encoded according to the following BNF:
+
+ <SupplierOrConsumer> ::= <Agreement> '#' <AccessPoint>
+
+ <Agreement> ::= <bindingid> '.' <bindingversion>
+
+ <bindingid> ::= <numericstring>
+
+ <bindingversion> ::= <numericstring>
+
+6.2.1.13. SupplierAndConsumers
+
+ Values of this syntax are encoded according to the following BNF:
+
+ <SupplierAndConsumers> ::= <Supplier> '#' <Consumers>
+
+ <Suppliers> ::= <AccessPoint>
+
+ <Consumers> ::= <AccessPoint> | '(' <AccessPointList> ')'
+
+ <AccessPointList> ::= <AccessPoint> |
+ <AccessPoint> '$' <AccessPointList>
+
+6.2.1.14. ProtocolInformation
+
+ A value with the ProtocolInformation syntax is encoded according to the
+ following BNF:
+
+ <ProtocolInformation> ::= <NetworkAddress> <space> '#'
+ <SetOfProtocolIdentifier>
+
+ <NetworkAddress> ::= As appears in PresentationAddress
+
+ <SetOfProtocolIdentifiers> ::= <ProtocolIdentifier> |
+ '(' <ProtocolIdentifiers> ')'
+
+
+
+Wahl, Coulbeck, Howes & Kille [Page 33]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+ <ProtocolIdentifiers> ::= <ProtocolIdentifier> |
+ <ProtocolIdentifier> '$' <ProtocolIdentifiers>
+
+ <ProtocolIdentifier> ::= <oid>
+
+ For example,
+
+ NS+12345678 # 1.2.3.4.5
+
+6.2.2. LDAP-defined Syntaxes
+
+ There is currently one syntax defined here.
+
+6.2.2.1 ModifyRight
+
+ This syntax is a printable encoding of the following ASN.1 data type:
+
+ ModifyRight ::= SEQUENCE {
+ item CHOICE {
+ entry [0] NULL,
+ attribute [1] AttributeType,
+ value [2] AttributeValueAssertion },
+ permission [3] BIT STRING { add(0), remove(1), rename(2), move(3) } }
+
+ The syntax is encoded according to the following BNF:
+
+ <ModifyRight> ::= [<perm-list>] <octo> <item>
+ -- perm list is absent when none of the bits set in permission
+
+ <item> ::= <entry> | <attribute> | <value>
+
+ <entry> ::= 'entry'
+
+ <attribute> ::= 'attribute' <dollar> <attributetype>
+
+ <value> ::= 'value' <dollar> <attributetype> <dollar> <strvalue>
+
+ -- <strvalue> is the string encoding of the value
+
+ <perm-list> ::= <perm> | <perm> <dollar> <perm-list>
+ -- one or more of the bits in permission, if set
+
+ <perm> ::= 'add' | 'remove' | 'rename' | 'move'
+
+ <octo> ::= [ <whsp> ] '#' [ <whsp> ]
+
+ <dollar> ::= [ <whsp> ] '$' [ <whsp> ]
+
+
+
+
+
+
+
+Wahl, Coulbeck, Howes & Kille [Page 34]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+ For example,
+
+ # entry
+ add $ remove # attribute $ cn
+ add $ remove # attribute $ sn
+ remove # value $ memberName $ CN=Babs, O=Michigan, C=US
+
+6.3. Object Classes
+
+ The following object classes may be recognized.
+
+ ( 2.5.17.0 NAME 'subentry' SUP top STRUCTURAL
+ MUST ( cn $ subtreeSpecification ) )
+
+ ( 2.5.17.1 NAME 'accessControlSubentry' AUXILIARY )
+
+ ( 2.5.17.2 NAME 'collectiveAttributeSubentry' AUXILIARY )
+
+ ( 2.5.20.1 NAME 'subschema' AUXILIARY
+ MAY ( dITStructureRules $ nameForms $ ditContentRules $
+ objectClasses $ attributeTypes $ matchingRules $ matchingRuleUse ) )
+
+6.4. Matching Rules
+
+ Only servers which implement the attribute types which reference these
+ matching rules in their definition are required to implement these rules.
+
+ The definitions of the rules can be found in [2] and [3].
+
+ Name OID
+ ===================================== ===========
+ caseIgnoreOrderingMatch 2.5.13.3
+ caseIgnoreSubstringsMatch 2.5.13.4
+ caseExactMatch 2.5.13.5
+ caseExactOrderingMatch 2.5.13.6
+ caseExactSubstringsMatch 2.5.13.7
+ numericStringOrderingMatch 2.5.13.9
+ numericStringSubstringsMatch 2.5.13.10
+ caseIgnoreListSubstringsMatch 2.5.13.12
+ booleanMatch 2.5.13.13
+ integerOrderingMatch 2.5.13.15
+ octetStringOrderingMatch 2.5.13.18
+ octetStringSubstringsMatch 2.5.13.19
+ telephoneNumberSubstringsMatch 2.5.13.21
+ presentationAddressMatch 2.5.13.22
+ uniqueMemberMatch 2.5.13.23
+ protocolInformationMatch 2.5.13.24
+ uTCTimeMatch 2.5.13.25
+ uTCTimeOrderingMatch 2.5.13.26
+ generalizedTimeOrderingMatch 2.5.13.28
+ integerFirstComponentMatch 2.5.13.29
+ objectIdentifierFirstComponentMatch 2.5.13.30
+ directoryStringFirstComponentMatch 2.5.13.31
+
+Wahl, Coulbeck, Howes & Kille [Page 35]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+ wordMatch 2.5.13.32
+ keywordMatch 2.5.13.33
+ accessPointMatch 2.5.14.0
+ masterAndShadowAccessPointsMatch 2.5.14.1
+ supplierOrConsumerInformationMatch 2.5.14.2
+ supplierAndConsumersMatch 2.5.14.3
+
+6.5. Other
+
+ The string 'excludeAllCollectiveAttributes' is defined as a synonym
+ for the OID 2.5.18.0. It would typically be used as a value of the
+ collectiveExclusions attribute.
+
+7. Other Optional Definitions
+
+7.1. Attribute Types
+
+7.1.1. Obsolete Attributes
+
+ Implementors must use modifyTimestamp and modifiersName instead.
+
+ ( 0.9.2342.19200300.100.1.23 NAME 'lastModifiedTime' OBSOLETE
+ SYNTAX 'UTCTime' )
+
+ ( 0.9.2342.19200300.100.1.24 NAME 'lastModifiedBy' OBSOLETE
+ EQUALITY distinguishedNameMatch SYNTAX 'DN' )
+
+7.2. Syntaxes
+
+7.2.1 MHSORAddress
+
+ Values of type MHSORAddress are encoded as strings, according to
+ the format defined in [10].
+
+7.2.2 DLSubmitPermission
+
+ Values of type DLSubmitPermission are encoded as strings, according
+ to the following BNF:
+
+ <dlsubmit-perm> ::= <dlgroup_label> ':' <dlgroup-value>
+ | <dl-label> ':' <dl-value>
+
+ <dlgroup-label> ::= 'group_member'
+
+ <dlgroup-value> ::= <name>
+
+ <name> ::= an encoded Distinguished Name
+
+ <dl-label> ::= 'individual' | 'dl_member' | 'pattern'
+
+ <dl-value> ::= <orname>
+
+
+
+Wahl, Coulbeck, Howes & Kille [Page 36]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+ <orname> ::= <address> '#' <dn>
+ | <address>
+
+ <address> ::= <add-label> ':' <oraddress>
+
+ <dn> ::= <dn-label> ':' <name>
+
+ <add-label> = 'X400'
+
+ <dn-label> = 'X500'
+
+ where <oraddress> is as defined in RFC 1327.
+
+7.3. Object Classes
+
+7.3.1. Obsolete Classes
+
+ ( 0.9.2342.19200300.100.4.22 NAME 'oldQualityLabelledData' SUP top
+ STRUCTURAL MUST dSAQuality
+ MAY ( subtreeMaximumQuality $ subtreeMinimumQuality ) )
+
+ The oldQualityLabelledData object class is historical and must not be
+ used for defining new objects.
+
+7.3.2. extensibleObject
+
+ ( 1.3.6.1.4.1.1466.101.120.111 NAME 'extensibleObject'
+ SUP top AUXILIARY )
+
+ This class, if present in an entry, permits that entry to optionally
+ hold any attribute. The MAY attribute list of this class is implicitly
+ the set of all attributes known to the server. The mandatory attributes
+ of the other object classes of this entry are still required to be
+ present.
+
+ Note that not all servers will implement this object class, and those
+ which do not will reject requests to add entries which contain this
+ object class, or modify an entry to add this object class.
+
+7.4. Matching Rules
+
+7.4.1. caseIgnoreIA5SubstringsMatch
+
+ ( 1.3.6.1.4.1.1466.109.114.3
+ NAME 'caseIgnoreIA5SubstringsMatch' SYNTAX 'IA5String' )
+
+ This matching rule may be used to compare components of an IA5 string
+ against an attribute whose values have IA5 string syntax.
+
+8. Security Considerations
+
+ Security issues are not discussed in this memo.
+
+
+Wahl, Coulbeck, Howes & Kille [Page 37]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+9. Acknowledgements
+
+ This document is based substantially on RFC 1778, written by Tim Howes,
+ Steve Kille, Wengyik Yeong and Colin Robbins.
+
+ Many of the attribute syntax encodings defined in this document are
+ adapted from those used in the QUIPU and the IC R3 X.500
+ implementations. The contributions of the authors of both these
+ implementations in the specification of syntaxes in this document are
+ gratefully acknowledged.
+
+10. Authors Addresses
+
+ Mark Wahl
+ Critical Angle Inc.
+ 4815 West Braker Lane #502-385
+ Austin, TX 78759
+ USA
+
+ EMail: M.Wahl@critical-angle.com
+
+
+ Andy Coulbeck
+ ISODE Consortium
+ The Dome, The Square
+ Richmond TW9 1DT
+ United Kingdom
+
+ Phone: +44 181-332-9091
+ EMail: A.Coulbeck@isode.com
+
+
+
+
+ Tim Howes
+ Netscape Communications Corp.
+ 501 E. Middlefield Rd
+ Mountain View, CA 94043
+ USA
+
+ Phone: +1 415 254-1900
+ EMail: howes@netscape.com
+
+
+ Steve Kille
+ ISODE Consortium
+ The Dome, The Square
+ Richmond
+ TW9 1DT
+ UK
+
+ Phone: +44-181-332-9091
+ EMail: S.Kille@isode.com
+
+Wahl, Coulbeck, Howes & Kille [Page 38]
+\f
+INTERNET-DRAFT LDAP Standard and Pilot Attributes October 1996
+
+11. Bibliography
+
+ [1] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol
+ (Version 3)", INTERNET-DRAFT <draft-ietf-asid-ldapv3-protocol-03.txt>,
+ October 1996.
+
+ [2] The Directory: Selected Attribute Types. ITU-T Recommendation
+ X.520, 1993.
+
+ [3] The Directory: Models. ITU-T Recommendation X.501, 1993.
+
+ [4] P. Barker, S. Kille, "The COSINE and Internet X.500 Schema", RFC
+ 1274, November 1991.
+
+ [5] M. Wahl, S. Kille, "A UTF-8 String Representation of Distinguished
+ Names", INTERNET-DRAFT <draft-ietf-asid-ldapv3-dn-00.txt>, August 1996.
+
+ [6] S. Kille, "A String Representation for Presentation Addresses",
+ RFC 1278, University College London, November 1991.
+
+ [7] Terminal Equipment and Protocols for Telematic Services -
+ Standardization of Group 3 facsimile apparatus for document
+ transmission. CCITT, Recommendation T.4.
+
+ [8] JPEG File Interchange Format (Version 1.02). Eric Hamilton,
+ C-Cube Microsystems, Milpitas, CA, September 1, 1992.
+
+ [9] The Directory: Selected Object Classes. ITU-T Recommendation
+ X.521, 1993.
+
+ [10] H. Alvestrand, S. Kille, R. Miles, M. Rose, S. Thompson,
+ "Mapping between X.400 and RFC-822 Message Bodies", RFC 1495,
+ August 1993.
+
+ [11] M. Davis, UTF-8, (WG2 N1036) DAM for ISO/IEC 10646-1.
+
+ [12] Universal Multiple-Octet Coded Character Set (UCS) - Architecture
+ and Basic Multilingual Plane, ISO/IEC 10646-1 : 1993.
+
+ [13] The Directory: Authentication Framework. ITU-T Recommendation
+ X.509 (1993).
+
+ [14] Abstract Syntax Notation One (ASN.1) - Specification of Basic
+ Notation. ITU-T Recommendation X.680, 1994.
+
+
+
+
+
+
+
+
+<draft-ietf-asid-ldapv3-attributes-03.txt>
+Expires: April 1997
+Wahl, Coulbeck, Howes & Kille [Page 39]
--- /dev/null
+
+INTERNET-DRAFT David Boreham, Netscape
+ Jim Sermersheim, Novell
+ Anoop Anantha, Microsoft
+ Michael Armijo, Microsoft
+ldapext Working Group 6 April, 2000
+
+
+ LDAP Extensions for Scrolling View Browsing of Search Results
+
+ draft-ietf-ldapext-ldapv3-vlv-04.txt
+ This document expires on 5 October 2000
+
+1. Status of this Memo
+
+This document is an Internet-Draft and is in full conformance with all
+provisions of Section 10 of RFC2026. Internet-Drafts are working docu-
+ments of the Internet Engineering Task Force (IETF), its areas, and its
+working groups. Note that other groups may also distribute working
+documents as Internet-Drafts.
+
+Internet-Drafts are draft documents valid for a maximum of six months
+and may be updated, replaced, or obsoleted by other documents at any
+time. It is inappropriate to use Internet- Drafts as reference material
+or to cite them other than as "work in progress."
+
+The list of current Internet-Drafts can be accessed at
+http://www.ietf.org/ietf/1id-abstracts.txt
+
+The list of Internet-Draft Shadow Directories can be accessed at
+http://www.ietf.org/shadow.html.
+
+2. Abstract
+
+This document describes a Virtual List View control extension for the
+LDAP Search operation. This control is designed to allow the "virtual
+list box" feature, common in existing commercial e-mail address book
+applications, to be supported efficiently by LDAP servers. LDAP servers'
+inability to support this client feature is a significant impediment to
+LDAP replacing proprietary protocols in commercial e-mail systems.
+
+The control allows a client to specify that the server return, for a
+given LDAP search with associated sort keys, a contiguous subset of the
+search result set. This subset is specified in terms of offsets into the
+ordered list, or in terms of a greater than or equal comparison value.
+
+3. Background
+
+A Virtual List is a graphical user interface technique employed where
+
+
+
+Boreham et al [Page 1]
+
+
+
+
+
+RFC DRAFT April 2000
+
+
+ordered lists containing a large number of entries need to be displayed.
+A window containing a small number of visible list entries is drawn. The
+visible portion of the list may be relocated to different points within
+the list by means of user input. This input can be to a scroll bar
+slider; from cursor keys; from page up/down keys; from alphanumeric keys
+for "typedown". The user is given the impression that they may browse
+the complete list at will, even though it may contain millions of
+entries. It is the fact that the complete list contents are never
+required at any one time that characterizes Virtual List View. Rather
+than fetch the complete list from wherever it is stored (typically from
+disk or a remote server), only that information which is required to
+display the part of the list currently in view is fetched. The subject
+of this document is the interaction between client and server required
+to implement this functionality in the context of the results from a
+sorted LDAP search request.
+
+For example, suppose an e-mail address book application displays a list
+view onto the list containing the names of all the holders of e-mail
+accounts at a large university. The list is sorted alphabetically.
+While there may be tens of thousands of entries in this list, the
+address book list view displays only 20 such accounts at any one time.
+The list has an accompanying scroll bar and text input window for type-
+down. When first displayed, the list view shows the first 20 entries in
+the list, and the scroll bar slider is positioned at the top of its
+range. Should the user drag the slider to the bottom of its range, the
+displayed contents of the list view should be updated to show the last
+20 entries in the list. Similarly, if the slider is positioned somewhere
+in the middle of its travel, the displayed contents of the list view
+should be updated to contain the 20 entries located at that relative
+position within the complete list. Starting from any display point, if
+the user uses the cursor keys or clicks on the scroll bar to request
+that the list be scrolled up or down by one entry, the displayed con-
+tents should be updated to reflect this. Similarly the list should be
+displayed correctly when the user requests a page scroll up or down.
+Finally, when the user types characters in the type-down window, the
+displayed contents of the list should "jump" or "seek" to the appropri-
+ate point within the list. For example, if the user types "B", the
+displayed list could center around the first user with a name beginning
+with the letter "B". When this happens, the scroll bar slider should
+also be updated to reflect the new relative location within the list.
+
+This document defines a request control which extends the LDAP search
+operation. Always used in conjunction with the server side sorting
+control[SSS], this allows a client to retrieve selected portions of
+large search result set in a fashion suitable for the implementation of
+a virtual list view.
+
+The key words "MUST", "SHOULD", and "MAY" used in this document are to
+
+
+
+Boreham et al [Page 2]
+
+
+
+
+
+RFC DRAFT April 2000
+
+
+be interpreted as described in [Bradner97].
+
+4. Client-Server Interaction
+
+The Virtual List View control extends a regular LDAP Search operation
+which must also include a server-side sorting control[SSS]. Rather than
+returning the complete set of appropriate SearchResultEntry messages,
+the server is instructed to return a contiguous subset of those entries,
+taken from the sorted result set, centered around a particular target
+entry. Henceforth, in the interests of brevity, the sorted search result
+set will be referred to as "the list".
+
+The sort control MAY contain any sort specification valid for the
+server. The attributeType field in the first SortKeyList sequence ele-
+ment has special significance for "typedown".
+
+The desired target entry, and the number of entries to be returned both
+before, and after, that target entry in the list, are determined by the
+client's VirtualListViewRequest control.
+
+When the server returns the set of entries to the client, it attaches a
+VirtualListViewResponse control to the SearchResultDone message. The
+server returns in this control: its current estimate for the list con-
+tent count, the location within the list corresponding to the target
+entry, and any error codes.
+
+The target entry is specified in the VirtualListViewRequest control by
+one of two methods. The first method is for the client to indicate the
+target entry's offset within the list. The second way is for the client
+to supply an attribute assertion value. The value is compared against
+the values of the attribute specified as the primary sort key in the
+sort control attached to the search operation. The first sort key in
+the SortKeyList is the primary sort key. The target entry is the first
+entry in the list with value greater than or equal to (in the primary
+sort order), the presented value. The order is determined by rules
+defined in [SSS]. Selection of the target entry by this means is
+designed to implement "typedown". Note that it is possible that no
+entry satisfies these conditions, in which case there is no target
+entry. This condition is indicated by the server returning the special
+value contentCount + 1 in the target position field.
+
+Because the server may not have an accurate estimate of the number of
+entries in the list, and to take account of cases where the list size is
+changing during the time the user browses the list, and because the
+client needs a way to indicate specific list targets "beginning" and
+"end", offsets within the list are transmitted between client and server
+as ratios---offset to content count. The server sends its latest esti-
+mate as to the number of entries in the list (content count) to the
+
+
+
+Boreham et al [Page 3]
+
+
+
+
+
+RFC DRAFT April 2000
+
+
+client in every response control. The client sends its assumed value
+for the content count in every request control. The server examines the
+content count and offsets presented by the client and computes the
+corresponding offsets within the list, based on its own idea of the con-
+tent count.
+
+ Si = Sc * (Ci / Cc)
+
+ Where:
+ Si is the actual list offset used by the server
+ Sc is the server's estimate for content count
+ Ci is the client's submitted offset
+ Cc is the client's submitted content count
+ The result is rounded to the nearest integer.
+
+If the content count is stable, and the client returns to the server the
+content count most recently received, Cc = Sc and the offsets transmit-
+ted become the actual server list offsets.
+
+The following special cases are allowed: a client sending a content
+count of zero (Cc = 0) means "client has no idea what the content count
+is, server MUST use its own content count estimate in place of the
+client's". An offset value of one (Ci = 1) always means that the target
+is the first entry in the list. Client specifying an offset which equals
+the content count specified in the same request control (Ci = Cc) means
+that the target is the last entry in the list. Ci may only equal zero
+when Cc is also zero. This signifies the last entry in the list.
+
+Because the server always returns contentCount and targetPosition, the
+client can always determine which of the returned entries is the target
+entry. Where the number of entries returned is the same as the number
+requested, the client is able to identify the target by simple arith-
+metic. Where the number of entries returned is not the same as the
+number requested (because the requested range crosses the beginning or
+end of the list, or both), the client must use the target position and
+content count values returned by the server to identify the target
+entry. For example, suppose that 10 entries before and 10 after the tar-
+get were requested, but the server returns 13 entries, a content count
+of 100 and a target position of 3. The client can determine that the
+first entry must be entry number 1 in the list, therefore the 13 entries
+returned are the first 13 entries in the list, and the target is the
+third one.
+
+A server-generated context identifier MAY be returned to clients. A
+client receiving a context identifier SHOULD return it unchanged in a
+subsequent request which relates to the same list. The purpose of this
+interaction is to enhance the performance and effectiveness of servers
+which employ approximate positioning.
+
+
+
+Boreham et al [Page 4]
+
+
+
+
+
+RFC DRAFT April 2000
+
+
+5. The Controls
+
+Support for the virtual list view control extension is indicated by the
+presence of the OID "2.16.840.1.113730.3.4.9" in the supportedControl
+attribute of a server's root DSE.
+
+5.1. Request Control
+
+This control is included in the SearchRequest message as part of the
+controls field of the LDAPMessage, as defined in Section 4.1.12 of
+[LDAPv3]. The controlType is set to "2.16.840.1.113730.3.4.9". The cri-
+ticality SHOULD be set to TRUE. If this control is included in a Sear-
+chRequest message, a Server Side Sorting request control [SSS] MUST also
+be present in the message. The controlValue is an OCTET STRING whose
+value is the BER-encoding of the following SEQUENCE:
+
+ VirtualListViewRequest ::= SEQUENCE {
+ beforeCount INTEGER (0..maxInt),
+ afterCount INTEGER (0..maxInt),
+ CHOICE {
+ byoffset [0] SEQUENCE {
+ offset INTEGER (0 .. maxInt),
+ contentCount INTEGER (0 .. maxInt) },
+ greaterThanOrEqual [1] AssertionValue },
+ contextID OCTET STRING OPTIONAL }
+
+beforeCount indicates how many entries before the target entry the
+client wants the server to send. afterCount indicates the number of
+entries after the target entry the client wants the server to send.
+offset and contentCount identify the target entry as detailed in section
+4. greaterThanOrEqual is an attribute assertion value defined in
+[LDAPv3]. If present, the value supplied in greaterThanOrEqual is used
+to determine the target entry by comparison with the values of the
+attribute specified as the primary sort key. The first list entry who's
+value is no less than (less than or equal to when the sort order is
+reversed) the supplied value is the target entry. If present, the con-
+textID field contains the value of the most recently received contextID
+field from a VirtualListViewResponse control. The type AssertionValue
+and value maxInt are defined in [LDAPv3]. contextID values have no
+validity outwith the connection on which they were received. That is, a
+client should not submit a contextID which it received from another con-
+nection, a connection now closed, or a different server.
+
+
+5.2. Response Control
+
+This control is included in the SearchResultDone message as part of the
+controls field of the LDAPMessage, as defined in Section 4.1.12 of
+
+
+
+Boreham et al [Page 5]
+
+
+
+
+
+RFC DRAFT April 2000
+
+
+[LDAPv3].
+
+The controlType is set to "2.16.840.1.113730.3.4.10". The criticality is
+FALSE (MAY be absent). The controlValue is an OCTET STRING, whose value
+is the BER encoding of a value of the following SEQUENCE:
+
+ VirtualListViewResponse ::= SEQUENCE {
+ targetPosition INTEGER (0 .. maxInt),
+ contentCount INTEGER (0 .. maxInt),
+ virtualListViewResult ENUMERATED {
+ success (0),
+ operationsError (1),
+ unwillingToPerform (53),
+ insufficientAccessRights (50),
+ busy (51),
+ timeLimitExceeded (3),
+ adminLimitExceeded (11),
+ sortControlMissing (60),
+ offsetRangeError (61),
+ other (80) },
+ contextID OCTET STRING OPTIONAL }
+
+targetPosition gives the list offset for the target entry. contentCount
+gives the server's estimate of the current number of entries in the
+list. Together these give sufficient information for the client to
+update a list box slider position to match the newly retrieved entries
+and identify the target entry. The contentCount value returned SHOULD be
+used in a subsequent VirtualListViewRequest control. contextID is a
+server-defined octet string. If present, the contents of the contextID
+field SHOULD be returned to the server by a client in a subsequent Vir-
+tualListViewRequest control.
+
+The virtualListViewResult codes which are common to the LDAP sear-
+chResponse (adminLimitExceeded, timeLimitExceeded, busy, operationsEr-
+ror, unwillingToPerform, insufficientAccessRights) have the same mean-
+ings as defined in [LDAPv3], but they pertain specifically to the VLV
+operation. For example, the server could exceed an administration limit
+processing a SearchRequest with a VirtualListViewRequest control. How-
+ever, the same administration limit would not be exceeded should the
+same SearchRequest be submitted by the client without the VirtualList-
+ViewRequest control. In this case, the client can determine that an
+administration limit has been exceeded in servicing the VLV request, and
+can if it chooses resubmit the SearchRequest without the VirtualList-
+ViewRequest control.
+
+insufficientAccessRights means that the server denied the client permis-
+sion to perform the VLV operation.
+
+
+
+
+Boreham et al [Page 6]
+
+
+
+
+
+RFC DRAFT April 2000
+
+
+If the server determines that the results of the search presented exceed
+the range provided by the 32-bit offset values, it MUST return
+offsetRangeError.
+
+6. Protocol Example
+
+Here we walk through the client-server interaction for a specific vir-
+tual list view example: The task is to display a list of all 78564 peo-
+ple in the US company "Ace Industry". This will be done by creating a
+graphical user interface object to display the list contents, and by
+repeatedly sending different versions of the same virtual list view
+search request to the server. The list view displays 20 entries on the
+screen at a time.
+
+We form a search with baseDN "o=Ace Industry, c=us"; search scope sub-
+tree; filter "objectClass=inetOrgPerson". We attach a server sort order
+control to the search, specifying ascending sort on attribute "cn". To
+this base search, we attach a virtual list view request control with
+contents determined by the user activity and send the search to the
+server. We display the results from each search in the list window and
+update the slider position.
+
+When the list view is first displayed, we want to initialize the con-
+tents showing the beginning of the list. Therefore, we set beforeCount =
+0, afterCount = 19, contentCount = 0, offset = 1 and send the request to
+the server. The server duly returns the first 20 entries in the list,
+plus the content count = 78564 and targetPosition = 1. We therefore
+leave the scroll bar slider at its current location (the top of its
+range).
+
+Say that next the user drags the scroll bar slider down to the bottom of
+its range. We now wish to display the last 20 entries in the list, so
+we set beforeCount = 19, afterCount = 0, contentCount = 78564, offset =
+78564 and send the request to the server. The server returns the last 20
+entries in the list, plus the content count = 78564 and targetPosition =
+78564.
+
+Next the user presses a page up key. Our page size is 20, so we set
+beforeCount = 0, afterCount = 19, contentCount = 78564, offset =
+78564-19-20 and send the request to the server. The server returns the
+preceding 20 entries in the list, plus the content count = 78564 and
+targetPosition = 78525.
+
+Now the user grabs the scroll bar slider and drags it to 68% of the way
+down its travel. 68% of 78564 is 53424 so we set beforeCount = 9, after-
+Count = 10, contentCount = 78564, offset = 53424 and send the request to
+the server. The server returns the preceding 20 entries in the list,
+plus the content count = 78564 and targetPosition = 53424.
+
+
+
+Boreham et al [Page 7]
+
+
+
+
+
+RFC DRAFT April 2000
+
+
+Lastly, the user types the letter "B". We set beforeCount = 9, after-
+Count = 10 and greaterThanOrEqual = "B". The server finds the first
+entry in the list not less than "B", let's say "Babs Jensen", and
+returns the nine preceding entries, the target entry, and the proceeding
+10 entries. The server returns content count = 78564 and targetPosition
+= 5234 and so the client updates its scroll bar slider to 6.7% of full
+scale.
+
+7. Notes for Implementers
+
+While the feature is expected to be generally useful for arbitrary
+search and sort specifications, it is specifically designed for those
+cases where the result set is very large. The intention is that this
+feature be implemented efficiently by means of pre-computed indices per-
+taining to a set of specific cases. For example, an offset relating to
+"all the employees in the local organization, sorted by surname" would
+be a common case.
+
+The intention for client software is that the feature should fit easily
+with the host platform's graphical user interface facilities for the
+display of scrolling lists. Thus the task of the client implementers
+should be one of reformatting up the requests for information received
+from the list view code to match the format of the virtual list view
+request and response controls.
+
+Client implementers should note that any offset value returned by the
+server may be approximate. Do not design clients > which only operate
+correctly when offsets are exact.
+
+Server implementers using indexing technology which features approximate
+positioning should consider returning context identifiers to clients.
+The use of a context identifier will allow the server to distinguish
+between client requests which relate to different displayed lists on the
+client. Consequently the server can decide more intelligently whether to
+reposition an existing database cursor accurately to within a short dis-
+tance of its current position, or to reposition to an approximate posi-
+tion. Thus the client will see precise offsets for "short" repositioning
+(e.g. paging up or down), but approximate offsets for a "long" reposi-
+tion (e.g. a slider movement).
+
+Server implementers are free to return status code unwillingToPerform
+should their server be unable to service any particular VLV search.
+This might be because the resolution of the search is computationally
+infeasible, or because excessive server resources would be required to
+service the search.
+
+Client implementers should note that this control is only defined on a
+client interaction with a single server. If a server returns referrals
+
+
+
+Boreham et al [Page 8]
+
+
+
+
+
+RFC DRAFT April 2000
+
+
+as a part of its response to the search request, the client is responsi-
+ble for deciding when and how to apply this control to the referred-to
+servers, and how to collate the results from multiple servers.
+
+
+8. Relationship to "Simple Paged Results"
+
+These controls are designed to support the virtual list view, which has
+proved hard to implement with the Simple Paged Results mechanism
+[SPaged]. However, the controls described here support any operation
+possible with the Simple Paged Results mechanism. The two mechanisms are
+not complementary, rather one has a superset of the other's features.
+One area where the mechanism presented here is not a strict superset of
+the Simple Paged Results scheme is that here we require a sort order to
+be specified. No such requirement is made for paged results.
+
+
+9. Security Considerations
+
+Server implementers may wish to consider whether clients are able to
+consume excessive server resources in requesting virtual list opera-
+tions. Access control to the feature itself; configuration options lim-
+iting the feature's use to certain predetermined search base DNs and
+filters; throttling mechanisms designed to limit the ability for one
+client to soak up server resources, may be appropriate.
+
+Consideration should be given as to whether a client will be able to
+retrieve the complete contents, or a significant subset of the complete
+contents of the directory using this feature. This may be undesirable in
+some circumstances and consequently it may be necessary to enforce some
+access control.
+
+Clients can, using this control, determine how many entries are con-
+tained within a portion of the DIT. This may constitute a security
+hazard. Again, access controls may be appropriate.
+
+Server implementers SHOULD exercise caution concerning the content of
+the contextID. Should the contextID contain internal server state, it
+may be possible for a malicious client to use that information to gain
+unauthorized access to information.
+
+10. Acknowledgements
+
+Chris Weider of Microsoft co-authored a previous version of this docu-
+ment.
+
+
+
+
+
+
+Boreham et al [Page 9]
+
+
+
+
+
+RFC DRAFT April 2000
+
+
+11. References
+
+[LDAPv3]
+ Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access Pro-
+ tocol (v3)", Internet Standard, December, 1997. RFC2251.
+
+[SPaged]
+ Weider, C, A. Herron, A. Anantha, and T. Howes, "LDAP Control
+ Extension for Simple Paged Results Manipulation", September
+ 1999. RFC2696
+
+[SSS]Wahl, M, A. Herron and T. Howes, "LDAP Control Extension for Server
+ Side Sorting of Search Results", Internet Draft, April, 1999.
+ Available as draft-ietf-asid-ldapv3-sorting-02.txt.
+
+[Bradner97]
+ Bradner, S., "Key Words for use in RFCs to Indicate Requirement
+ Levels", BCP 14, RFC 2119, March 1997.
+
+12. Authors' Addresses
+
+ David Boreham
+ iPlanet e-commerce solutions
+ 501 E. Middlefield Road
+ Mountain View, CA 94043, USA
+ +1 650 937-5206
+ dboreham@netscape.com
+
+ Jim Sermersheim
+ Novell
+ 122 East 1700 South
+ Provo, Utah 84606, USA
+ jimse@novell.com
+
+ Anoop Anantha
+ Microsoft Corp.
+ 1 Microsoft Way
+ Redmond, WA 98052, USA
+ +1 425 882-8080
+ anoopa@microsoft.com
+
+ Michael Armijo
+ Microsoft Corp.
+ 1 Microsoft Way
+ Redmond, WA 98052, USA
+ +1 425 882-8080
+ micharm@microsoft.com
+ This document expires on 5 October 2000
+
+
+
+Boreham et al [Page 10]
+
+
+
+
+
+RFC DRAFT April 2000
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Boreham et al [Page 11]
+
+
--- /dev/null
+
+Network Working Group A. Herron, Microsoft
+INTERNET DRAFT T. Howes, Netscape
+Expire in six months M. Wahl, Critical Angle Inc
+ A. Anantha, Microsoft
+ April 5, 1999
+
+ LDAP Control Extension for Server Side Sorting of Search Results
+ draft-ietf-ldapext-sorting-02.txt
+
+
+1. Status of this Memo
+
+This document is an Internet-Draft. Internet-Drafts are working docu-
+ments of the Internet Engineering Task Force (IETF), its areas, and its
+working groups. Note that other groups may also distribute working
+documents as Internet-Drafts.
+
+Internet-Drafts are draft documents valid for a maximum of six months
+and may be updated, replaced, or obsoleted by other documents at any
+time. It is inappropriate to use Internet- Drafts as reference material
+or to cite them other than as ``work in progress.''
+
+To learn the current status of any Internet-Draft, please check the
+``1id-abstracts.txt'' listing contained in the Internet- Drafts Shadow
+Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe),
+ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim).
+
+This document expires on October 5, 1999.
+
+2. Abstract
+
+This document describes two LDAPv3 control extensions for server side
+sorting of search results. These controls allows a client to specify the
+attribute types and matching rules a server should use when returning
+the results to an LDAP search request. The controls may be useful when
+the LDAP client has limited functionality or for some other reason
+cannot sort the results but still needs them sorted. Other permissible
+controls on search operations are not defined in this extension.
+
+The sort controls allow a server to return a result code for the sorting
+of the results that is independent of the result code returned for the
+search operation.
+
+The key words "MUST", "SHOULD", and "MAY" used in this document are to
+be interpreted as described in [bradner97].
+
+3. The Controls
+
+3.1 Request Control
+
+This control is included in the searchRequest message as part of the
+controls field of the LDAPMessage, as defined in Section 4.1.12 of
+[LDAPv3].
+
+The controlType is set to "1.2.840.113556.1.4.473". The criticality
+MAY be either TRUE or FALSE (where absent is also equivalent to
+FALSE) at the client's option. The controlValue is an OCTET STRING,
+whose value is the BER encoding of a value of the following SEQUENCE:
+
+ SortKeyList ::= SEQUENCE OF SEQUENCE {
+ attributeType AttributeDescription,
+ orderingRule [0] MatchingRuleId OPTIONAL,
+ reverseOrder [1] BOOLEAN DEFAULT FALSE }
+
+The SortKeyList sequence is in order of highest to lowest sort key
+precedence.
+
+The MatchingRuleID SHOULD be one that is valid for the attribute type
+it applies to. If it is not, the server MUST return unwillingToPerform.
+
+Each attributeType should only occur in the SortKeyList once. If an
+attributeType is included in the sort key list multiple times, the
+server should return an error in the sortResult of unwillingToPerform.
+
+If the orderingRule is omitted, the ordering MatchingRule defined for use
+with this attribute MUST be used.
+
+Any conformant implementation of this control MUST allow a sort key
+list with at least one key.
+
+3.2 Response Control
+
+This control is included in the searchResultDone message as part of the
+controls field of the LDAPMessage, as defined in Section 4.1.12 of
+[LDAPv3].
+
+The controlType is set to "1.2.840.113556.1.4.474". The criticality is
+FALSE (MAY be absent). The controlValue is an OCTET STRING, whose
+value is the BER encoding of a value of the following SEQUENCE:
+
+ SortResult ::= SEQUENCE {
+ sortResult ENUMERATED {
+ success (0), -- results are sorted
+ operationsError (1), -- server internal failure
+ timeLimitExceeded (3), -- timelimit reached before
+ -- sorting was completed
+ strongAuthRequired (8), -- refused to return sorted
+ -- results via insecure
+ -- protocol
+ adminLimitExceeded (11), -- too many matching entries
+ -- for the server to sort
+ noSuchAttribute (16), -- unrecognized attribute
+ -- type in sort key
+ inappropriateMatching (18), -- unrecognized or inappro-
+ -- priate matching rule in
+ -- sort key
+ insufficientAccessRights (50), -- refused to return sorted
+ -- results to this client
+ busy (51), -- too busy to process
+ unwillingToPerform (53), -- unable to sort
+ other (80)
+ },
+ attributeType [0] AttributeDescription OPTIONAL }
+
+4. Client-Server Interaction
+
+The sortKeyRequestControl specifies one or more attribute types and
+matching rules for the results returned by a search request. The server
+SHOULD return all results for the search request in the order specified
+by the sort keys. If the reverseOrder field is set to TRUE, then the
+entries will be presented in reverse sorted order for the specified
+key.
+
+There are six possible scenarios that may occur as a result of the sort
+control being included on the search request :
+
+1 - If the server does not support this sorting control and the client
+specified TRUE for the control's criticality field, then the server
+MUST return unavailableCriticalExtension as a return code in the
+searchResultDone message and not send back any other results. This
+behavior is specified in section 4.1.12 of [LDAPv3].
+
+2 - If the server does not support this sorting control and the client
+specified FALSE for the control's criticality field, then the server
+MUST ignore the sort control and process the search request as if it
+were not present. This behavior is specified in section 4.1.12 of
+[LDAPv3].
+
+3 - If the server supports this sorting control but for some reason
+cannot sort the search results using the specified sort keys and the
+client specified TRUE for the control's criticality field, then the
+server SHOULD do the following: return unavailableCriticalExtension as
+a return code in the searchResultDone message; include the
+sortKeyResponseControl in the searchResultDone message, and not send
+back any search result entries.
+
+4 - If the server supports this sorting control but for some reason
+cannot sort the search results using the specified sort keys and the
+client specified FALSE for the control's criticality field, then the
+server should return all search results unsorted and include the
+sortKeyResponseControl in the searchResultDone message.
+
+5 - If the server supports this sorting control and can sort the search
+results using the specified sort keys, then it should include the
+sortKeyResponseControl in the searchResultDone message with a
+sortResult of success.
+
+6 - If the search request failed for any reason and/or there are no
+searchResultEntry messages returned for the search response, then the
+server SHOULD omit the sortKeyResponseControl from the
+searchResultDone message.
+
+The client application is assured that the results are sorted in the
+specified key order if and only if the result code in the
+sortKeyResponseControl is success. If the server omits the
+sortKeyResponseControl from the searchResultDone message, the client
+SHOULD assume that the sort control was ignored by the server.
+
+The sortKeyResponseControl, if included by the server in the
+searchResultDone message, should have the sortResult set to either
+success if the results were sorted in accordance with the keys
+specified in the sortKeyRequestControl or set to the appropriate error
+code as to why it could not sort the data (such as noSuchAttribute or
+inappropriateMatching). Optionally, the server MAY set the
+attributeType to the first attribute type specified in the SortKeyList
+that was in error. The client SHOULD ignore the attributeType field if
+the sortResult is success.
+
+The server may not be able to sort the results using the specified sort
+keys because it may not recognize one of the attribute types, the
+matching rule associated with an attribute type is not applicable, or
+none of the attributes in the search response are of these types.
+Servers may also restrict the number of keys allowed in the control,
+such as only supporting a single key.
+
+Servers that chain requests to other LDAP servers should ensure that
+the server satisfying the client's request sort the entire result set
+prior to sending back the results.
+
+4.1 Behavior in a chained environment
+
+If a server receives a sort request, the client expects to receive a
+set of sorted results. If a client submits a sort request to a server
+which chains the request and gets entries from multiple servers, and
+the client has set the criticality of the sort extension to TRUE, the
+server MUST merge sort the results before returning them to the client
+or MUST return unwillingToPerform.
+
+4.2 Other sort issues
+
+An entry that meets the search criteria may be missing one or more of
+the sort keys. In that case, the entry is considered to have a value of
+NULL for that key. This standard considers NULL to be a larger value
+than all other valid values for that key. For example, if only one key
+is specified, entries which meet the search criteria but do not have
+that key collate after all the entries which do have that key. If the
+reverseOrder flag is set, and only one key is specified, entries which
+meet the search criteria but do not have that key collate BEFORE all
+the entries which do have that key.
+
+If a sort key is a multi-valued attribute, and an entry happens to have
+multiple values for that attribute and no other controls are present that
+affect the sorting order, then the server SHOULD use the least value
+(according to the ORDERING rule for that attribute).
+
+5. Interaction with other search controls
+
+When the sortKeyRequestControl control is included with the
+pagedResultsControl control as specified in [LdapPaged], then the
+server should send the searchResultEntry messages sorted according to
+the sort keys applied to the entire result set. The server should not
+simply sort each page, as this will give erroneous results to the
+client.
+
+The sortKeyList must be present on each searchRequest message for the
+paged result. It also must not change between searchRequests for the
+same result set. If the server has sorted the data, then it SHOULD
+send back a sortKeyResponseControl control on every searchResultDone
+message for each page. This will allow clients to quickly determine
+if the result set is sorted, rather than waiting to receive the entire
+result set.
+
+
+6. Security Considerations
+
+Implementors and administrators should be aware that allowing sorting
+of results could enable the retrieval of a large number of records from
+a given directory service, irregardless of administrative limits set on
+the maximum number of records to return.
+
+A client that desired to pull all records out of a directory service
+could use a combination of sorting and updating of search filters to
+retrieve all records in a database in small result sets, thus
+circumventing administrative limits.
+
+This behavior can be overcome by the judicious use of permissions on
+the directory entries by the administrator and by intelligent
+implementations of administrative limits on the number of records
+retrieved by a client.
+
+
+7. References
+
+[LDAPv3]
+ Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access
+Pro-
+ tocol (v3)", RFC 2251, December, 1997.
+
+[Bradner97]
+ Bradner, Scott, "Key Words for use in RFCs to Indicate
+Requirement
+ Levels", RFC 2119, March, 1997.
+
+[LdapPaged]
+ C. Weider, A. Herron, and T. Howes, "LDAP Control Extension for
+ Simple Paged Results Manipulation", Internet Draft, February, 1997.
+ Available as draft-ietf-asid-ldapv3-simplepaged-00.txt.
+
+
+8. Author's Address
+
+ Anoop Anantha
+ Microsoft Corp.
+ 1 Microsoft Way
+ Redmond, WA 98052
+ USA
+ Anoopa@microsoft.com
+ +1 425 882-8080
+
+ Andy Herron
+ Microsoft Corp.
+ 1 Microsoft Way
+ Redmond, WA 98052
+ USA
+ andyhe@microsoft.com
+ +1 425 882-8080
+
+ Tim Howes
+ Netscape Communications Corp.
+ 501 E. Middlefield Road
+ Mountain View, CA 94043
+ USA
+ howes@netscape.com
+ +1 415 937-2600
+
+ Mark Wahl
+ Critical Angle Inc.
+ 4815 W Braker Lane #502-385
+ Austin, TX 78759
+ USA
+ M.Wahl@critical-angle.com
+
--- /dev/null
+
+
+
+
+
+
+Network Working Group Paul J. Leach, Microsoft
+INTERNET-DRAFT Rich Salz, Certco
+<draft-leach-uuids-guids-01.txt>
+Category: Standards Track
+Expires August 4, 1998 February 4, 1998
+
+
+
+ UUIDs and GUIDs
+
+STATUS OF THIS MEMO
+
+ This document is an Internet-Draft. Internet-Drafts are working
+ documents of the Internet Engineering Task Force (IETF), its areas,
+ and its working groups. Note that other groups may also distribute
+ working documents as Internet-Drafts.
+
+ Internet-Drafts are draft documents valid for a maximum of six months
+ and may be updated, replaced, or obsoleted by other documents at any
+ time. It is inappropriate to use Internet-Drafts as reference
+ material or to cite them other than as "work in progress".
+
+ To learn the current status of any Internet-Draft, please check the
+ "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow
+ Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe),
+ munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or
+ ftp.isi.edu (US West Coast).
+
+ Distribution of this document is unlimited. Please send comments to
+ the authors or the CIFS mailing list at <cifs@discuss.microsoft.com>.
+ Discussions of the mailing list are archived at
+ <URL:http://discuss.microsoft.com/archives/index.
+
+
+ABSTRACT
+
+ This specification defines the format of UUIDs (Universally Unique
+ IDentifier), also known as GUIDs (Globally Unique IDentifier). A UUID
+ is 128 bits long, and if generated according to the one of the
+ mechanisms in this document, is either guaranteed to be different
+ from all other UUIDs/GUIDs generated until 3400 A.D. or extremely
+ likely to be different (depending on the mechanism chosen). UUIDs
+ were originally used in the Network Computing System (NCS) [1] and
+ later in the Open Software Foundation's (OSF) Distributed Computing
+ Environment [2].
+
+ This specification is derived from the latter specification with the
+ kind permission of the OSF.
+
+
+Table of Contents
+
+1. Introduction .......................................................3
+
+
+[Page 1]\f
+
+
+ Internet-Draft UUIDs and GUIDs (DRAFT) 02/04/98
+
+
+2. Motivation .........................................................3
+
+3. Specification ......................................................3
+
+ 3.1 Format............................................................4
+
+ 3.1.1 Variant......................................................4
+
+ 3.1.2 UUID layout..................................................5
+
+ 3.1.3 Version......................................................5
+
+ 3.1.4 Timestamp....................................................6
+
+ 3.1.5 Clock sequence...............................................6
+
+ 3.1.6 Node.........................................................7
+
+ 3.1.7 Nil UUID.....................................................7
+
+ 3.2 Algorithms for creating a time-based UUID.........................7
+
+ 3.2.1 Basic algorithm..............................................7
+
+ 3.2.2 Reading stable storage.......................................8
+
+ 3.2.3 System clock resolution......................................8
+
+ 3.2.4 Writing stable storage.......................................9
+
+ 3.2.5 Sharing state across processes...............................9
+
+ 3.2.6 UUID Generation details......................................9
+
+ 3.3 Algorithm for creating a name-based UUID.........................10
+
+ 3.4 Algorithms for creating a UUID from truly random or pseudo-random
+ numbers .............................................................11
+
+ 3.5 String Representation of UUIDs...................................12
+
+ 3.6 Comparing UUIDs for equality.....................................12
+
+ 3.7 Comparing UUIDs for relative order...............................13
+
+ 3.8 Byte order of UUIDs..............................................13
+
+4. Node IDs when no IEEE 802 network card is available ...............14
+
+5. Obtaining IEEE 802 addresses ......................................15
+
+6. Security Considerations ...........................................15
+
+7. Acknowledgements ..................................................15
+
+ Leach, Salz expires Aug 1998 [Page 2]\f
+
+
+ Internet-Draft UUIDs and GUIDs (DRAFT) 02/04/98
+
+
+8. References ........................................................15
+
+9. Authors' addresses ................................................16
+
+10.Notice ............................................................16
+
+11.Full Copyright Statement ..........................................16
+
+Appendix A _ UUID Sample Implementation...............................17
+
+Appendix B _ Sample output of utest...................................27
+
+Appendix C _ Some name space IDs......................................27
+
+
+
+
+1. Introduction
+
+ This specification defines the format of UUIDs (Universally Unique
+ IDentifiers), also known as GUIDs (Globally Unique IDentifiers). A
+ UUID is 128 bits long, and if generated according to the one of the
+ mechanisms in this document, is either guaranteed to be different
+ from all other UUIDs/GUIDs generated until 3400 A.D. or extremely
+ likely to be different (depending on the mechanism chosen).
+
+
+2. Motivation
+
+ One of the main reasons for using UUIDs is that no centralized
+ authority is required to administer them (beyond the one that
+ allocates IEEE 802.1 node identifiers). As a result, generation on
+ demand can be completely automated, and they can be used for a wide
+ variety of purposes. The UUID generation algorithm described here
+ supports very high allocation rates: 10 million per second per
+ machine if you need it, so that they could even be used as
+ transaction IDs.
+
+ UUIDs are fixed-size (128-bits) which is reasonably small relative to
+ other alternatives. This fixed, relatively small size lends itself
+ well to sorting, ordering, and hashing of all sorts, storing in
+ databases, simple allocation, and ease of programming in general.
+
+
+3. Specification
+
+ A UUID is an identifier that is unique across both space and time,
+ with respect to the space of all UUIDs. To be precise, the UUID
+ consists of a finite bit space. Thus the time value used for
+ constructing a UUID is limited and will roll over in the future
+ (approximately at A.D. 3400, based on the specified algorithm). A
+ UUID can be used for multiple purposes, from tagging objects with an
+ extremely short lifetime, to reliably identifying very persistent
+ objects across a network.
+
+ Leach, Salz expires Aug 1998 [Page 3]\f
+
+
+ Internet-Draft UUIDs and GUIDs (DRAFT) 02/04/98
+
+
+ The generation of UUIDs does not require that a registration
+ authority be contacted for each identifier. Instead, it requires a
+ unique value over space for each UUID generator. This spatially
+ unique value is specified as an IEEE 802 address, which is usually
+ already available to network-connected systems. This 48-bit address
+ can be assigned based on an address block obtained through the IEEE
+ registration authority. This section of the UUID specification
+ assumes the availability of an IEEE 802 address to a system desiring
+ to generate a UUID, but if one is not available section 4 specifies a
+ way to generate a probabilistically unique one that can not conflict
+ with any properly assigned IEEE 802 address.
+
+
+3.1 Format
+
+ In its most general form, all that can be said of the UUID format is
+ that a UUID is 16 octets, and that some bits of octet 8 of the UUID
+ called the variant field (specified in the next section) determine
+ finer structure.
+
+
+3.1.1 Variant
+ The variant field determines the layout of the UUID. That is, the
+ interpretation of all other bits in the UUID depends on the setting
+ of the bits in the variant field. The variant field consists of a
+ variable number of the msbs of octet 8 of the UUID.
+
+ The following table lists the contents of the variant field.
+
+ Msb0 Msb1 Msb2 Description
+
+ 0 - - Reserved, NCS backward compatibility.
+
+ 1 0 - The variant specified in this document.
+
+ 1 1 0 Reserved, Microsoft Corporation backward
+ compatibility
+
+ 1 1 1 Reserved for future definition.
+
+
+
+ Other UUID variants may not interoperate with the UUID variant
+ specified in this document, where interoperability is defined as the
+ applicability of operations such as string conversion and lexical
+ ordering across different systems. However, UUIDs allocated according
+ to the stricture of different variants, though they may define
+ different interpretations of the bits outside the variant field, will
+ not result in duplicate UUID allocation, because of the differing
+ values of the variant field itself.
+
+ The remaining fields described below (version, timestamp, etc.) are
+ defined only for the UUID variant noted above.
+
+
+ Leach, Salz expires Aug 1998 [Page 4]\f
+
+
+ Internet-Draft UUIDs and GUIDs (DRAFT) 02/04/98
+
+
+3.1.2 UUID layout
+ The following table gives the format of a UUID for the variant
+ specified herein. The UUID consists of a record of 16 octets. To
+ minimize confusion about bit assignments within octets, the UUID
+ record definition is defined only in terms of fields that are
+ integral numbers of octets. The fields are in order of significance
+ for comparison purposes, with "time_low" the most significant, and
+ "node" the least significant.
+
+ Field Data Type Octet Note
+ #
+
+ time_low unsigned 32 0-3 The low field of the
+ bit integer timestamp.
+
+ time_mid unsigned 16 4-5 The middle field of the
+ bit integer timestamp.
+
+ time_hi_and_version unsigned 16 6-7 The high field of the
+ bit integer timestamp multiplexed
+ with the version number.
+
+ clock_seq_hi_and_rese unsigned 8 8 The high field of the
+ rved bit integer clock sequence
+ multiplexed with the
+ variant.
+
+ clock_seq_low unsigned 8 9 The low field of the
+ bit integer clock sequence.
+
+ node unsigned 48 10-15 The spatially unique
+ bit integer node identifier.
+
+
+
+
+3.1.3 Version
+ The version number is in the most significant 4 bits of the time
+ stamp (time_hi_and_version).
+
+ The following table lists currently defined versions of the UUID.
+
+ Msb0 Msb1 Msb2 Msb3 Version Description
+
+ 0 0 0 1 1 The time-based version
+ specified in this
+ document.
+
+ 0 0 1 0 2 Reserved for DCE
+ Security version, with
+ embedded POSIX UIDs.
+
+ 0 0 1 1 3 The name-based version
+ specified in this
+
+ Leach, Salz expires Aug 1998 [Page 5]\f
+
+
+ Internet-Draft UUIDs and GUIDs (DRAFT) 02/04/98
+
+
+ document
+
+ 0 1 0 0 4 The randomly or pseudo-
+ randomly generated
+ version specified in
+ this document
+
+
+3.1.4 Timestamp
+ The timestamp is a 60 bit value. For UUID version 1, this is
+ represented by Coordinated Universal Time (UTC) as a count of 100-
+ nanosecond intervals since 00:00:00.00, 15 October 1582 (the date of
+ Gregorian reform to the Christian calendar).
+
+ For systems that do not have UTC available, but do have local time,
+ they MAY use local time instead of UTC, as long as they do so
+ consistently throughout the system. This is NOT RECOMMENDED, however,
+ and it should be noted that all that is needed to generate UTC, given
+ local time, is a time zone offset.
+
+ For UUID version 3, it is a 60 bit value constructed from a name.
+
+ For UUID version 4, it is a randomly or pseudo-randomly generated 60
+ bit value.
+
+
+3.1.5 Clock sequence
+ For UUID version 1, the clock sequence is used to help avoid
+ duplicates that could arise when the clock is set backwards in time
+ or if the node ID changes.
+
+ If the clock is set backwards, or even might have been set backwards
+ (e.g., while the system was powered off), and the UUID generator can
+ not be sure that no UUIDs were generated with timestamps larger than
+ the value to which the clock was set, then the clock sequence has to
+ be changed. If the previous value of the clock sequence is known, it
+ can be just incremented; otherwise it should be set to a random or
+ high-quality pseudo random value.
+
+ Similarly, if the node ID changes (e.g. because a network card has
+ been moved between machines), setting the clock sequence to a random
+ number minimizes the probability of a duplicate due to slight
+ differences in the clock settings of the machines. (If the value of
+ clock sequence associated with the changed node ID were known, then
+ the clock sequence could just be incremented, but that is unlikely.)
+
+ The clock sequence MUST be originally (i.e., once in the lifetime of
+ a system) initialized to a random number to minimize the correlation
+ across systems. This provides maximum protection against node
+ identifiers that may move or switch from system to system rapidly.
+ The initial value MUST NOT be correlated to the node identifier.
+
+ For UUID version 3, it is a 14 bit value constructed from a name.
+
+
+ Leach, Salz expires Aug 1998 [Page 6]\f
+
+
+ Internet-Draft UUIDs and GUIDs (DRAFT) 02/04/98
+
+
+ For UUID version 4, it is a randomly or pseudo-randomly generated 14
+ bit value.
+
+
+3.1.6 Node
+ For UUID version 1, the node field consists of the IEEE address,
+ usually the host address. For systems with multiple IEEE 802
+ addresses, any available address can be used. The lowest addressed
+ octet (octet number 10) contains the global/local bit and the
+ unicast/multicast bit, and is the first octet of the address
+ transmitted on an 802.3 LAN.
+
+ For systems with no IEEE address, a randomly or pseudo-randomly
+ generated value may be used (see section 4). The multicast bit must
+ be set in such addresses, in order that they will never conflict with
+ addresses obtained from network cards.
+
+ For UUID version 3, the node field is a 48 bit value constructed from
+ a name.
+
+ For UUID version 4, the node field is a randomly or pseudo-randomly
+ generated 48 bit value.
+
+
+3.1.7 Nil UUID
+ The nil UUID is special form of UUID that is specified to have all
+ 128 bits set to 0 (zero).
+
+
+3.2 Algorithms for creating a time-based UUID
+
+ Various aspects of the algorithm for creating a version 1 UUID are
+ discussed in the following sections. UUID generation requires a
+ guarantee of uniqueness within the node ID for a given variant and
+ version. Interoperability is provided by complying with the specified
+ data structure.
+
+
+3.2.1 Basic algorithm
+ The following algorithm is simple, correct, and inefficient:
+
+ . Obtain a system wide global lock
+
+ . From a system wide shared stable store (e.g., a file), read the
+ UUID generator state: the values of the time stamp, clock sequence,
+ and node ID used to generate the last UUID.
+
+ . Get the current time as a 60 bit count of 100-nanosecond intervals
+ since 00:00:00.00, 15 October 1582
+
+ . Get the current node ID
+
+
+
+
+ Leach, Salz expires Aug 1998 [Page 7]\f
+
+
+ Internet-Draft UUIDs and GUIDs (DRAFT) 02/04/98
+
+
+ . If the state was unavailable (non-existent or corrupted), or the
+ saved node ID is different than the current node ID, generate a
+ random clock sequence value
+
+ . If the state was available, but the saved time stamp is later than
+ the current time stamp, increment the clock sequence value
+
+ . Format a UUID from the current time stamp, clock sequence, and node
+ ID values according to the structure in section 3.1 (see section
+ 3.2.6 for more details)
+
+ . Save the state (current time stamp, clock sequence, and node ID)
+ back to the stable store
+
+ . Release the system wide global lock
+
+ If UUIDs do not need to be frequently generated, the above algorithm
+ may be perfectly adequate. For higher performance requirements,
+ however, issues with the basic algorithm include:
+
+ . Reading the state from stable storage each time is inefficient
+
+ . The resolution of the system clock may not be 100-nanoseconds
+
+ . Writing the state to stable storage each time is inefficient
+
+ . Sharing the state across process boundaries may be inefficient
+
+ Each of these issues can be addressed in a modular fashion by local
+ improvements in the functions that read and write the state and read
+ the clock. We address each of them in turn in the following sections.
+
+
+3.2.2 Reading stable storage
+ The state only needs to be read from stable storage once at boot
+ time, if it is read into a system wide shared volatile store (and
+ updated whenever the stable store is updated).
+
+ If an implementation does not have any stable store available, then
+ it can always say that the values were unavailable. This is the least
+ desirable implementation, because it will increase the frequency of
+ creation of new clock sequence numbers, which increases the
+ probability of duplicates.
+
+ If the node ID can never change (e.g., the net card is inseparable
+ from the system), or if any change also reinitializes the clock
+ sequence to a random value, then instead of keeping it in stable
+ store, the current node ID may be returned.
+
+
+3.2.3 System clock resolution
+ The time stamp is generated from the system time, whose resolution
+ may be less than the resolution of the UUID time stamp.
+
+
+ Leach, Salz expires Aug 1998 [Page 8]\f
+
+
+ Internet-Draft UUIDs and GUIDs (DRAFT) 02/04/98
+
+
+ If UUIDs do not need to be frequently generated, the time stamp can
+ simply be the system time multiplied by the number of 100-nanosecond
+ intervals per system time interval.
+
+ If a system overruns the generator by requesting too many UUIDs
+ within a single system time interval, the UUID service MUST either:
+ return an error, or stall the UUID generator until the system clock
+ catches up.
+
+ A high resolution time stamp can be simulated by keeping a count of
+ how many UUIDs have been generated with the same value of the system
+ time, and using it to construction the low-order bits of the time
+ stamp. The count will range between zero and the number of 100-
+ nanosecond intervals per system time interval.
+
+ Note: if the processors overrun the UUID generation frequently,
+ additional node identifiers can be allocated to the system, which
+ will permit higher speed allocation by making multiple UUIDs
+ potentially available for each time stamp value.
+
+
+3.2.4 Writing stable storage
+ The state does not always need to be written to stable store every
+ time a UUID is generated. The timestamp in the stable store can be
+ periodically set to a value larger than any yet used in a UUID; as
+ long as the generated UUIDs have time stamps less than that value,
+ and the clock sequence and node ID remain unchanged, only the shared
+ volatile copy of the state needs to be updated. Furthermore, if the
+ time stamp value in stable store is in the future by less than the
+ typical time it takes the system to reboot, a crash will not cause a
+ reinitialization of the clock sequence.
+
+
+3.2.5 Sharing state across processes
+ If it is too expensive to access shared state each time a UUID is
+ generated, then the system wide generator can be implemented to
+ allocate a block of time stamps each time it is called, and a per-
+ process generator can allocate from that block until it is exhausted.
+
+
+3.2.6 UUID Generation details
+ UUIDs are generated according to the following algorithm:
+
+ - Determine the values for the UTC-based timestamp and clock sequence
+ to be used in the UUID, as described above.
+
+ - For the purposes of this algorithm, consider the timestamp to be a
+ 60-bit unsigned integer and the clock sequence to be a 14-bit
+ unsigned integer. Sequentially number the bits in a field, starting
+ from 0 (zero) for the least significant bit.
+
+ - Set the time_low field equal to the least significant 32-bits (bits
+ numbered 0 to 31 inclusive) of the time stamp in the same order of
+ significance.
+
+ Leach, Salz expires Aug 1998 [Page 9]\f
+
+
+ Internet-Draft UUIDs and GUIDs (DRAFT) 02/04/98
+
+
+ - Set the time_mid field equal to the bits numbered 32 to 47
+ inclusive of the time stamp in the same order of significance.
+
+ - Set the 12 least significant bits (bits numbered 0 to 11 inclusive)
+ of the time_hi_and_version field equal to the bits numbered 48 to 59
+ inclusive of the time stamp in the same order of significance.
+
+ - Set the 4 most significant bits (bits numbered 12 to 15 inclusive)
+ of the time_hi_and_version field to the 4-bit version number
+ corresponding to the UUID version being created, as shown in the
+ table in section 3.1.3.
+
+ - Set the clock_seq_low field to the 8 least significant bits (bits
+ numbered 0 to 7 inclusive) of the clock sequence in the same order of
+ significance.
+
+ - Set the 6 least significant bits (bits numbered 0 to 5 inclusive)
+ of the clock_seq_hi_and_reserved field to the 6 most significant bits
+ (bits numbered 8 to 13 inclusive) of the clock sequence in the same
+ order of significance.
+
+ - Set the 2 most significant bits (bits numbered 6 and 7) of the
+ clock_seq_hi_and_reserved to 0 and 1, respectively.
+
+ - Set the node field to the 48-bit IEEE address in the same order of
+ significance as the address.
+
+
+3.3 Algorithm for creating a name-based UUID
+
+ The version 3 UUID is meant for generating UUIDs from "names" that
+ are drawn from, and unique within, some "name space". Some examples
+ of names (and, implicitly, name spaces) might be DNS names, URLs, ISO
+ Object IDs (OIDs), reserved words in a programming language, or X.500
+ Distinguished Names (DNs); thus, the concept of name and name space
+ should be broadly construed, and not limited to textual names. The
+ mechanisms or conventions for allocating names from, and ensuring
+ their uniqueness within, their name spaces are beyond the scope of
+ this specification.
+
+ The requirements for such UUIDs are as follows:
+
+ . The UUIDs generated at different times from the same name in the
+ same namespace MUST be equal
+
+ . The UUIDs generated from two different names in the same namespace
+ should be different (with very high probability)
+
+ . The UUIDs generated from the same name in two different namespaces
+ should be different with (very high probability)
+
+ . If two UUIDs that were generated from names are equal, then they
+ were generated from the same name in the same namespace (with very
+ high probability).
+
+ Leach, Salz expires Aug 1998 [Page 10]\f
+
+
+ Internet-Draft UUIDs and GUIDs (DRAFT) 02/04/98
+
+
+ The algorithm for generating the a UUID from a name and a name space
+ are as follows:
+
+ . Allocate a UUID to use as a "name space ID" for all UUIDs generated
+ from names in that name space
+
+ . Convert the name to a canonical sequence of octets (as defined by
+ the standards or conventions of its name space); put the name space
+ ID in network byte order
+
+ . Compute the MD5 [3] hash of the name space ID concatenated with the
+ name
+
+ . Set octets 0-3 of time_low field to octets 0-3 of the MD5 hash
+
+ . Set octets 0-1 of time_mid field to octets 4-5 of the MD5 hash
+
+ . Set octets 0-1 of time_hi_and_version field to octets 6-7 of the
+ MD5 hash
+
+ . Set the clock_seq_hi_and_reserved field to octet 8 of the MD5 hash
+
+ . Set the clock_seq_low field to octet 9 of the MD5 hash
+
+ . Set octets 0-5 of the node field to octets 10-15 of the MD5 hash
+
+ . Set the 2 most significant bits (bits numbered 6 and 7) of the
+ clock_seq_hi_and_reserved to 0 and 1, respectively.
+
+ . Set the 4 most significant bits (bits numbered 12 to 15 inclusive)
+ of the time_hi_and_version field to the 4-bit version number
+ corresponding to the UUID version being created, as shown in the
+ table above.
+
+ . Convert the resulting UUID to local byte order.
+
+
+3.4 Algorithms for creating a UUID from truly random or pseudo-random
+numbers
+
+ The version 4 UUID is meant for generating UUIDs from truly-random or
+ pseudo-random numbers.
+
+ The algorithm is as follows:
+
+ . Set the 2 most significant bits (bits numbered 6 and 7) of the
+ clock_seq_hi_and_reserved to 0 and 1, respectively.
+
+ . Set the 4 most significant bits (bits numbered 12 to 15 inclusive)
+ of the time_hi_and_version field to the 4-bit version number
+ corresponding to the UUID version being created, as shown in the
+ table above.
+
+
+
+ Leach, Salz expires Aug 1998 [Page 11]\f
+
+
+ Internet-Draft UUIDs and GUIDs (DRAFT) 02/04/98
+
+
+ . Set all the other bits to randomly (or pseudo-randomly) chosen
+ values.
+
+ Here are several possible ways to generate the random values:
+
+ . Use a physical source of randomness: for example, a white noise
+ generator, radioactive decay, or a lava lamp.
+
+ . Use a cryptographic strength random number generator.
+
+
+3.5 String Representation of UUIDs
+
+ For use in human readable text, a UUID string representation is
+ specified as a sequence of fields, some of which are separated by
+ single dashes.
+
+ Each field is treated as an integer and has its value printed as a
+ zero-filled hexadecimal digit string with the most significant digit
+ first. The hexadecimal values a to f inclusive are output as lower
+ case characters, and are case insensitive on input. The sequence is
+ the same as the UUID constructed type.
+
+ The formal definition of the UUID string representation is provided
+ by the following extended BNF:
+
+ UUID = <time_low> "-" <time_mid> "-"
+ <time_high_and_version> "-"
+ <clock_seq_and_reserved>
+ <clock_seq_low> "-" <node>
+ time_low = 4*<hexOctet>
+ time_mid = 2*<hexOctet>
+ time_high_and_version = 2*<hexOctet>
+ clock_seq_and_reserved = <hexOctet>
+ clock_seq_low = <hexOctet>
+ node = 6*<hexOctet
+ hexOctet = <hexDigit> <hexDigit>
+ hexDigit =
+ "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
+ | "a" | "b" | "c" | "d" | "e" | "f"
+ | "A" | "B" | "C" | "D" | "E" | "F"
+
+ The following is an example of the string representation of a UUID:
+
+ f81d4fae-7dec-11d0-a765-00a0c91e6bf6
+
+3.6 Comparing UUIDs for equality
+
+ Consider each field of the UUID to be an unsigned integer as shown in
+ the table in section 3.1. Then, to compare a pair of UUIDs,
+ arithmetically compare the corresponding fields from each UUID in
+ order of significance and according to their data type. Two UUIDs are
+ equal if and only if all the corresponding fields are equal.
+
+
+ Leach, Salz expires Aug 1998 [Page 12]\f
+
+
+ Internet-Draft UUIDs and GUIDs (DRAFT) 02/04/98
+
+
+ Note: as a practical matter, on many systems comparison of two UUIDs
+ for equality can be performed simply by comparing the 128 bits of
+ their in-memory representation considered as a 128 bit unsigned
+ integer. Here, it is presumed that by the time the in-memory
+ representation is obtained the appropriate byte-order
+ canonicalizations have been carried out.
+
+
+3.7 Comparing UUIDs for relative order
+
+ Two UUIDs allocated according to the same variant can also be ordered
+ lexicographically. For the UUID variant herein defined, the first of
+ two UUIDs follows the second if the most significant field in which
+ the UUIDs differ is greater for the first UUID. The first of a pair
+ of UUIDs precedes the second if the most significant field in which
+ the UUIDs differ is greater for the second UUID.
+
+
+3.8 Byte order of UUIDs
+
+ UUIDs may be transmitted in many different forms, some of which may
+ be dependent on the presentation or application protocol where the
+ UUID may be used. In such cases, the order, sizes and byte orders of
+ the UUIDs fields on the wire will depend on the relevant presentation
+ or application protocol. However, it is strongly RECOMMENDED that
+ the order of the fields conform with ordering set out in section 3.1
+ above. Furthermore, the payload size of each field in the application
+ or presentation protocol MUST be large enough that no information
+ lost in the process of encoding them for transmission.
+
+ In the absence of explicit application or presentation protocol
+ specification to the contrary, a UUID is encoded as a 128-bit object,
+ as follows: the fields are encoded as 16 octets, with the sizes and
+ order of the fields defined in section 3.1, and with each field
+ encoded with the Most Significant Byte first (also known as network
+ byte order).
+
+ 0 1 2 3
+ 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | time_low |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | time_mid | time_hi_and_version |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ |clk_seq_hi_res | clk_seq_low | node (0-1) |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | node (2-5) |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+
+
+
+
+
+
+
+ Leach, Salz expires Aug 1998 [Page 13]\f
+
+
+ Internet-Draft UUIDs and GUIDs (DRAFT) 02/04/98
+
+
+4. Node IDs when no IEEE 802 network card is available
+
+ If a system wants to generate UUIDs but has no IEE 802 compliant
+ network card or other source of IEEE 802 addresses, then this section
+ describes how to generate one.
+
+ The ideal solution is to obtain a 47 bit cryptographic quality random
+ number, and use it as the low 47 bits of the node ID, with the most
+ significant bit of the first octet of the node ID set to 1. This bit
+ is the unicast/multicast bit, which will never be set in IEEE 802
+ addresses obtained from network cards; hence, there can never be a
+ conflict between UUIDs generated by machines with and without network
+ cards.
+
+ If a system does not have a primitive to generate cryptographic
+ quality random numbers, then in most systems there are usually a
+ fairly large number of sources of randomness available from which one
+ can be generated. Such sources are system specific, but often
+ include:
+
+ - the percent of memory in use
+ - the size of main memory in bytes
+ - the amount of free main memory in bytes
+ - the size of the paging or swap file in bytes
+ - free bytes of paging or swap file
+ - the total size of user virtual address space in bytes
+ - the total available user address space bytes
+ - the size of boot disk drive in bytes
+ - the free disk space on boot drive in bytes
+ - the current time
+ - the amount of time since the system booted
+ - the individual sizes of files in various system directories
+ - the creation, last read, and modification times of files in various
+ system directories
+ - the utilization factors of various system resources (heap, etc.)
+ - current mouse cursor position
+ - current caret position
+ - current number of running processes, threads
+ - handles or IDs of the desktop window and the active window
+ - the value of stack pointer of the caller
+ - the process and thread ID of caller
+ - various processor architecture specific performance counters
+ (instructions executed, cache misses, TLB misses)
+
+ (Note that it precisely the above kinds of sources of randomness that
+ are used to seed cryptographic quality random number generators on
+ systems without special hardware for their construction.)
+
+ In addition, items such as the computer's name and the name of the
+ operating system, while not strictly speaking random, will help
+ differentiate the results from those obtained by other systems.
+
+ The exact algorithm to generate a node ID using these data is system
+ specific, because both the data available and the functions to obtain
+
+ Leach, Salz expires Aug 1998 [Page 14]\f
+
+
+ Internet-Draft UUIDs and GUIDs (DRAFT) 02/04/98
+
+
+ them are often very system specific. However, assuming that one can
+ concatenate all the values from the randomness sources into a buffer,
+ and that a cryptographic hash function such as MD5 [3] is available,
+ then any 6 bytes of the MD5 hash of the buffer, with the multicast
+ bit (the high bit of the first byte) set will be an appropriately
+ random node ID.
+
+ Other hash functions, such as SHA-1 [4], can also be used. The only
+ requirement is that the result be suitably random _ in the sense that
+ the outputs from a set uniformly distributed inputs are themselves
+ uniformly distributed, and that a single bit change in the input can
+ be expected to cause half of the output bits to change.
+
+
+5. Obtaining IEEE 802 addresses
+
+ At the time of writing, the following URL
+
+ http://standards.ieee.org/db/oui/forms/
+
+ contains information on how to obtain an IEEE 802 address block. At
+ the time of writing, the cost is $1250 US.
+
+
+6. Security Considerations
+
+ It should not be assumed that UUIDs are hard to guess; they should
+ not be used as capabilities.
+
+
+7. Acknowledgements
+
+ This document draws heavily on the OSF DCE specification for UUIDs.
+ Ted Ts'o provided helpful comments, especially on the byte ordering
+ section which we mostly plagiarized from a proposed wording he
+ supplied (all errors in that section are our responsibility,
+ however).
+
+
+8. References
+
+ [1] Lisa Zahn, et. al., Network Computing Architecture, Prentice
+ Hall, Englewood Cliffs, NJ, 1990
+
+ [2] DCE: Remote Procedure Call, Open Group CAE Specification C309
+ ISBN 1-85912-041-5 28cm. 674p. pbk. 1,655g. 8/94
+
+ [3] R. Rivest, RFC 1321, "The MD5 Message-Digest Algorithm",
+ 04/16/1992.
+
+ [4] NIST FIPS PUB 180-1, "Secure Hash Standard," National Institute
+ of Standards and Technology, U.S. Department of Commerce, DRAFT, May
+ 31, 1994.
+
+
+ Leach, Salz expires Aug 1998 [Page 15]\f
+
+
+ Internet-Draft UUIDs and GUIDs (DRAFT) 02/04/98
+
+
+9. Authors' addresses
+
+ Paul J. Leach
+ Microsoft
+ 1 Microsoft Way
+ Redmond, WA, 98052, U.S.A.
+ paulle@microsoft.com
+ Tel. 425 882 8080
+ Fax. 425 936 7329
+
+ Rich Salz
+ 100 Cambridge Park Drive
+ Cambridge MA 02140
+ salzr@certco.com
+ Tel. 617 499 4075
+ Fax. 617 576 0019
+
+
+10. Notice
+
+ The IETF takes no position regarding the validity or scope of any
+ intellectual property or other rights that might be claimed to
+ pertain to the implementation or use of the technology described in
+ this document or the extent to which any license under such rights
+ might or might not be available; neither does it represent that it
+ has made any effort to identify any such rights. Information on the
+ IETF's procedures with respect to rights in standards-track and
+ standards-related documentation can be found in BCP-11. Copies of
+ claims of rights made available for publication and any assurances of
+ licenses to be made available, or the result of an attempt made to
+ obtain a general license or permission for the use of such
+ proprietary rights by implementors or users of this specification can
+ be obtained from the IETF Secretariat.
+
+ The IETF invites any interested party to bring to its attention any
+ copyrights, patents or patent applications, or other proprietary
+ rights which may cover technology that may be required to practice
+ this standard. Please address the information to the IETF Executive
+ Director.
+
+
+11. Full Copyright Statement
+
+ Copyright (C) The Internet Society 1997. 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
+
+ Leach, Salz expires Aug 1998 [Page 16]\f
+
+
+ Internet-Draft UUIDs and GUIDs (DRAFT) 02/04/98
+
+
+ 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.
+
+
+ Appendix A _ UUID Sample Implementation
+
+ This implementation consists of 5 files: uuid.h, uuid.c, sysdep.h,
+ sysdep.c and utest.c. The uuid.* files are the system independent
+ implementation of the UUID generation algorithms described above,
+ with all the optimizations described above except efficient state
+ sharing across processes included. The code has been tested on Linux
+ (Red Hat 4.0) with GCC (2.7.2), and Windows NT 4.0 with VC++ 5.0. The
+ code assumes 64 bit integer support, which makes it a lot clearer.
+
+ All the following source files should be considered to have the
+ following copyright notice included:
+
+ copyrt.h
+
+ /*
+ ** Copyright (c) 1990- 1993, 1996 Open Software Foundation, Inc.
+ ** Copyright (c) 1989 by Hewlett-Packard Company, Palo Alto, Ca. &
+ ** Digital Equipment Corporation, Maynard, Mass.
+ ** Copyright (c) 1998 Microsoft.
+ ** To anyone who acknowledges that this file is provided "AS IS"
+ ** without any express or implied warranty: permission to use, copy,
+ ** modify, and distribute this file for any purpose is hereby
+ ** granted without fee, provided that the above copyright notices and
+ ** this notice appears in all source code copies, and that none of
+ ** the names of Open Software Foundation, Inc., Hewlett-Packard
+ ** Company, or Digital Equipment Corporation be used in advertising
+ ** or publicity pertaining to distribution of the software without
+ ** specific, written prior permission. Neither Open Software
+ ** Foundation, Inc., Hewlett-Packard Company, Microsoft, nor Digital
+ Equipment
+ ** Corporation makes any representations about the suitability of
+ ** this software for any purpose.
+ */
+
+
+ uuid.h
+
+
+ Leach, Salz expires Aug 1998 [Page 17]\f
+
+
+ Internet-Draft UUIDs and GUIDs (DRAFT) 02/04/98
+
+
+ #include "copyrt.h"
+ #undef uuid_t
+ typedef struct _uuid_t {
+ unsigned32 time_low;
+ unsigned16 time_mid;
+ unsigned16 time_hi_and_version;
+ unsigned8 clock_seq_hi_and_reserved;
+ unsigned8 clock_seq_low;
+ byte node[6];
+ } uuid_t;
+
+ /* uuid_create -- generate a UUID */
+ int uuid_create(uuid_t * uuid);
+
+ /* uuid_create_from_name -- create a UUID using a "name"
+ from a "name space" */
+ void uuid_create_from_name(
+ uuid_t * uuid, /* resulting UUID */
+ uuid_t nsid, /* UUID to serve as context, so identical
+ names from different name spaces generate
+ different UUIDs */
+ void * name, /* the name from which to generate a UUID */
+ int namelen /* the length of the name */
+ );
+
+ /* uuid_compare -- Compare two UUID's "lexically" and return
+ -1 u1 is lexically before u2
+ 0 u1 is equal to u2
+ 1 u1 is lexically after u2
+ Note: lexical ordering is not temporal ordering!
+ */
+ int uuid_compare(uuid_t *u1, uuid_t *u2);
+
+ uuid.c
+
+ #include "copyrt.h"
+ #include <string.h>
+ #include <stdio.h>
+ #include <stdlib.h>
+ #include <time.h>
+ #include "sysdep.h"
+ #include "uuid.h"
+
+ /* various forward declarations */
+ static int read_state(unsigned16 *clockseq, uuid_time_t *timestamp,
+ uuid_node_t * node);
+ static void write_state(unsigned16 clockseq, uuid_time_t timestamp,
+ uuid_node_t node);
+ static void format_uuid_v1(uuid_t * uuid, unsigned16 clockseq,
+ uuid_time_t timestamp, uuid_node_t node);
+ static void format_uuid_v3(uuid_t * uuid, unsigned char hash[16]);
+ static void get_current_time(uuid_time_t * timestamp);
+ static unsigned16 true_random(void);
+
+
+ Leach, Salz expires Aug 1998 [Page 18]\f
+
+
+ Internet-Draft UUIDs and GUIDs (DRAFT) 02/04/98
+
+
+ /* uuid_create -- generator a UUID */
+ int uuid_create(uuid_t * uuid) {
+ uuid_time_t timestamp, last_time;
+ unsigned16 clockseq;
+ uuid_node_t node;
+ uuid_node_t last_node;
+ int f;
+
+ /* acquire system wide lock so we're alone */
+ LOCK;
+
+ /* get current time */
+ get_current_time(×tamp);
+
+ /* get node ID */
+ get_ieee_node_identifier(&node);
+
+ /* get saved state from NV storage */
+ f = read_state(&clockseq, &last_time, &last_node);
+
+ /* if no NV state, or if clock went backwards, or node ID changed
+ (e.g., net card swap) change clockseq */
+ if (!f || memcmp(&node, &last_node, sizeof(uuid_node_t)))
+ clockseq = true_random();
+ else if (timestamp < last_time)
+ clockseq++;
+
+ /* stuff fields into the UUID */
+ format_uuid_v1(uuid, clockseq, timestamp, node);
+
+ /* save the state for next time */
+ write_state(clockseq, timestamp, node);
+
+ UNLOCK;
+ return(1);
+ };
+
+ /* format_uuid_v1 -- make a UUID from the timestamp, clockseq,
+ and node ID */
+ void format_uuid_v1(uuid_t * uuid, unsigned16 clock_seq, uuid_time_t
+ timestamp, uuid_node_t node) {
+ /* Construct a version 1 uuid with the information we've gathered
+ * plus a few constants. */
+ uuid->time_low = (unsigned long)(timestamp & 0xFFFFFFFF);
+ uuid->time_mid = (unsigned short)((timestamp >> 32) & 0xFFFF);
+ uuid->time_hi_and_version = (unsigned short)((timestamp >> 48) &
+ 0x0FFF);
+ uuid->time_hi_and_version |= (1 << 12);
+ uuid->clock_seq_low = clock_seq & 0xFF;
+ uuid->clock_seq_hi_and_reserved = (clock_seq & 0x3F00) >> 8;
+ uuid->clock_seq_hi_and_reserved |= 0x80;
+ memcpy(&uuid->node, &node, sizeof uuid->node);
+ };
+
+
+ Leach, Salz expires Aug 1998 [Page 19]\f
+
+
+ Internet-Draft UUIDs and GUIDs (DRAFT) 02/04/98
+
+
+ /* data type for UUID generator persistent state */
+ typedef struct {
+ uuid_time_t ts; /* saved timestamp */
+ uuid_node_t node; /* saved node ID */
+ unsigned16 cs; /* saved clock sequence */
+ } uuid_state;
+
+ static uuid_state st;
+
+ /* read_state -- read UUID generator state from non-volatile store */
+ int read_state(unsigned16 *clockseq, uuid_time_t *timestamp,
+ uuid_node_t *node) {
+ FILE * fd;
+ static int inited = 0;
+
+ /* only need to read state once per boot */
+ if (!inited) {
+ fd = fopen("state", "rb");
+ if (!fd)
+ return (0);
+ fread(&st, sizeof(uuid_state), 1, fd);
+ fclose(fd);
+ inited = 1;
+ };
+ *clockseq = st.cs;
+ *timestamp = st.ts;
+ *node = st.node;
+ return(1);
+ };
+
+ /* write_state -- save UUID generator state back to non-volatile
+ storage */
+ void write_state(unsigned16 clockseq, uuid_time_t timestamp,
+ uuid_node_t node) {
+ FILE * fd;
+ static int inited = 0;
+ static uuid_time_t next_save;
+
+ if (!inited) {
+ next_save = timestamp;
+ inited = 1;
+ };
+ /* always save state to volatile shared state */
+ st.cs = clockseq;
+ st.ts = timestamp;
+ st.node = node;
+ if (timestamp >= next_save) {
+ fd = fopen("state", "wb");
+ fwrite(&st, sizeof(uuid_state), 1, fd);
+ fclose(fd);
+ /* schedule next save for 10 seconds from now */
+ next_save = timestamp + (10 * 10 * 1000 * 1000);
+ };
+ };
+
+ Leach, Salz expires Aug 1998 [Page 20]\f
+
+
+ Internet-Draft UUIDs and GUIDs (DRAFT) 02/04/98
+
+
+
+ /* get-current_time -- get time as 60 bit 100ns ticks since whenever.
+ Compensate for the fact that real clock resolution is
+ less than 100ns. */
+ void get_current_time(uuid_time_t * timestamp) {
+ uuid_time_t time_now;
+ static uuid_time_t time_last;
+ static unsigned16 uuids_this_tick;
+ static int inited = 0;
+
+ if (!inited) {
+ get_system_time(&time_now);
+ uuids_this_tick = UUIDS_PER_TICK;
+ inited = 1;
+ };
+
+ while (1) {
+ get_system_time(&time_now);
+
+ /* if clock reading changed since last UUID generated... */
+ if (time_last != time_now) {
+ /* reset count of uuids gen'd with this clock reading */
+ uuids_this_tick = 0;
+ break;
+ };
+ if (uuids_this_tick < UUIDS_PER_TICK) {
+ uuids_this_tick++;
+ break;
+ };
+ /* going too fast for our clock; spin */
+ };
+ /* add the count of uuids to low order bits of the clock reading */
+ *timestamp = time_now + uuids_this_tick;
+ };
+
+ /* true_random -- generate a crypto-quality random number.
+ This sample doesn't do that. */
+ static unsigned16
+ true_random(void)
+ {
+ static int inited = 0;
+ uuid_time_t time_now;
+
+ if (!inited) {
+ get_system_time(&time_now);
+ time_now = time_now/UUIDS_PER_TICK;
+ srand((unsigned int)(((time_now >> 32) ^ time_now)&0xffffffff));
+ inited = 1;
+ };
+
+ return (rand());
+ }
+
+
+
+ Leach, Salz expires Aug 1998 [Page 21]\f
+
+
+ Internet-Draft UUIDs and GUIDs (DRAFT) 02/04/98
+
+
+ /* uuid_create_from_name -- create a UUID using a "name" from a "name
+ space" */
+ void uuid_create_from_name(
+ uuid_t * uuid, /* resulting UUID */
+ uuid_t nsid, /* UUID to serve as context, so identical
+ names from different name spaces generate
+ different UUIDs */
+ void * name, /* the name from which to generate a UUID */
+ int namelen /* the length of the name */
+ ) {
+ MD5_CTX c;
+ unsigned char hash[16];
+ uuid_t net_nsid; /* context UUID in network byte order */
+
+ /* put name space ID in network byte order so it hashes the same
+ no matter what endian machine we're on */
+ net_nsid = nsid;
+ htonl(net_nsid.time_low);
+ htons(net_nsid.time_mid);
+ htons(net_nsid.time_hi_and_version);
+
+ MD5Init(&c);
+ MD5Update(&c, &net_nsid, sizeof(uuid_t));
+ MD5Update(&c, name, namelen);
+ MD5Final(hash, &c);
+
+ /* the hash is in network byte order at this point */
+ format_uuid_v3(uuid, hash);
+ };
+
+ /* format_uuid_v3 -- make a UUID from a (pseudo)random 128 bit number
+ */
+ void format_uuid_v3(uuid_t * uuid, unsigned char hash[16]) {
+ /* Construct a version 3 uuid with the (pseudo-)random number
+ * plus a few constants. */
+
+ memcpy(uuid, hash, sizeof(uuid_t));
+
+ /* convert UUID to local byte order */
+ ntohl(uuid->time_low);
+ ntohs(uuid->time_mid);
+ ntohs(uuid->time_hi_and_version);
+
+ /* put in the variant and version bits */
+ uuid->time_hi_and_version &= 0x0FFF;
+ uuid->time_hi_and_version |= (3 << 12);
+ uuid->clock_seq_hi_and_reserved &= 0x3F;
+ uuid->clock_seq_hi_and_reserved |= 0x80;
+ };
+
+ /* uuid_compare -- Compare two UUID's "lexically" and return
+ -1 u1 is lexically before u2
+ 0 u1 is equal to u2
+ 1 u1 is lexically after u2
+
+ Leach, Salz expires Aug 1998 [Page 22]\f
+
+
+ Internet-Draft UUIDs and GUIDs (DRAFT) 02/04/98
+
+
+ Note: lexical ordering is not temporal ordering!
+ */
+ int uuid_compare(uuid_t *u1, uuid_t *u2)
+ {
+ int i;
+
+ #define CHECK(f1, f2) if (f1 != f2) return f1 < f2 ? -1 : 1;
+ CHECK(u1->time_low, u2->time_low);
+ CHECK(u1->time_mid, u2->time_mid);
+ CHECK(u1->time_hi_and_version, u2->time_hi_and_version);
+ CHECK(u1->clock_seq_hi_and_reserved, u2->clock_seq_hi_and_reserved);
+ CHECK(u1->clock_seq_low, u2->clock_seq_low)
+ for (i = 0; i < 6; i++) {
+ if (u1->node[i] < u2->node[i])
+ return -1;
+ if (u1->node[i] > u2->node[i])
+ return 1;
+ }
+ return 0;
+ };
+
+ sysdep.h
+
+ #include "copyrt.h"
+ /* remove the following define if you aren't running WIN32 */
+ #define WININC 0
+
+ #ifdef WININC
+ #include <windows.h>
+ #else
+ #include <sys/types.h>
+ #include <sys/time.h>
+ #include <sys/sysinfo.h>
+ #endif
+
+ /* change to point to where MD5 .h's live */
+ /* get MD5 sample implementation from RFC 1321 */
+ #include "global.h"
+ #include "md5.h"
+
+ /* set the following to the number of 100ns ticks of the actual
+ resolution of
+ your system's clock */
+ #define UUIDS_PER_TICK 1024
+
+ /* Set the following to a call to acquire a system wide global lock
+ */
+ #define LOCK
+ #define UNLOCK
+
+ typedef unsigned long unsigned32;
+ typedef unsigned short unsigned16;
+ typedef unsigned char unsigned8;
+ typedef unsigned char byte;
+
+ Leach, Salz expires Aug 1998 [Page 23]\f
+
+
+ Internet-Draft UUIDs and GUIDs (DRAFT) 02/04/98
+
+
+
+ /* Set this to what your compiler uses for 64 bit data type */
+ #ifdef WININC
+ #define unsigned64_t unsigned __int64
+ #define I64(C) C
+ #else
+ #define unsigned64_t unsigned long long
+ #define I64(C) C##LL
+ #endif
+
+
+ typedef unsigned64_t uuid_time_t;
+ typedef struct {
+ char nodeID[6];
+ } uuid_node_t;
+
+ void get_ieee_node_identifier(uuid_node_t *node);
+ void get_system_time(uuid_time_t *uuid_time);
+ void get_random_info(char seed[16]);
+
+
+ sysdep.c
+
+ #include "copyrt.h"
+ #include <stdio.h>
+ #include "sysdep.h"
+
+ /* system dependent call to get IEEE node ID.
+ This sample implementation generates a random node ID
+ */
+ void get_ieee_node_identifier(uuid_node_t *node) {
+ char seed[16];
+ FILE * fd;
+ static inited = 0;
+ static uuid_node_t saved_node;
+
+ if (!inited) {
+ fd = fopen("nodeid", "rb");
+ if (fd) {
+ fread(&saved_node, sizeof(uuid_node_t), 1, fd);
+ fclose(fd);
+ }
+ else {
+ get_random_info(seed);
+ seed[0] |= 0x80;
+ memcpy(&saved_node, seed, sizeof(uuid_node_t));
+ fd = fopen("nodeid", "wb");
+ if (fd) {
+ fwrite(&saved_node, sizeof(uuid_node_t), 1, fd);
+ fclose(fd);
+ };
+ };
+ inited = 1;
+ };
+
+ Leach, Salz expires Aug 1998 [Page 24]\f
+
+
+ Internet-Draft UUIDs and GUIDs (DRAFT) 02/04/98
+
+
+ *node = saved_node;
+ };
+
+ /* system dependent call to get the current system time.
+ Returned as 100ns ticks since Oct 15, 1582, but resolution may be
+ less than 100ns.
+ */
+ #ifdef _WINDOWS_
+
+ void get_system_time(uuid_time_t *uuid_time) {
+ ULARGE_INTEGER time;
+
+ GetSystemTimeAsFileTime((FILETIME *)&time);
+
+ /* NT keeps time in FILETIME format which is 100ns ticks since
+ Jan 1, 1601. UUIDs use time in 100ns ticks since Oct 15, 1582.
+ The difference is 17 Days in Oct + 30 (Nov) + 31 (Dec)
+ + 18 years and 5 leap days.
+ */
+
+ time.QuadPart +=
+ (unsigned __int64) (1000*1000*10) // seconds
+ * (unsigned __int64) (60 * 60 * 24) // days
+ * (unsigned __int64) (17+30+31+365*18+5); // # of days
+
+ *uuid_time = time.QuadPart;
+
+ };
+
+ void get_random_info(char seed[16]) {
+ MD5_CTX c;
+ typedef struct {
+ MEMORYSTATUS m;
+ SYSTEM_INFO s;
+ FILETIME t;
+ LARGE_INTEGER pc;
+ DWORD tc;
+ DWORD l;
+ char hostname[MAX_COMPUTERNAME_LENGTH + 1];
+ } randomness;
+ randomness r;
+
+ MD5Init(&c);
+ /* memory usage stats */
+ GlobalMemoryStatus(&r.m);
+ /* random system stats */
+ GetSystemInfo(&r.s);
+ /* 100ns resolution (nominally) time of day */
+ GetSystemTimeAsFileTime(&r.t);
+ /* high resolution performance counter */
+ QueryPerformanceCounter(&r.pc);
+ /* milliseconds since last boot */
+ r.tc = GetTickCount();
+ r.l = MAX_COMPUTERNAME_LENGTH + 1;
+
+ Leach, Salz expires Aug 1998 [Page 25]\f
+
+
+ Internet-Draft UUIDs and GUIDs (DRAFT) 02/04/98
+
+
+ GetComputerName(r.hostname, &r.l );
+ MD5Update(&c, &r, sizeof(randomness));
+ MD5Final(seed, &c);
+ };
+ #else
+
+ void get_system_time(uuid_time_t *uuid_time)
+ {
+ struct timeval tp;
+
+ gettimeofday(&tp, (struct timezone *)0);
+
+ /* Offset between UUID formatted times and Unix formatted times.
+ UUID UTC base time is October 15, 1582.
+ Unix base time is January 1, 1970.
+ */
+ *uuid_time = (tp.tv_sec * 10000000) + (tp.tv_usec * 10) +
+ I64(0x01B21DD213814000);
+ };
+
+ void get_random_info(char seed[16]) {
+ MD5_CTX c;
+ typedef struct {
+ struct sysinfo s;
+ struct timeval t;
+ char hostname[257];
+ } randomness;
+ randomness r;
+
+ MD5Init(&c);
+ sysinfo(&r.s);
+ gettimeofday(&r.t, (struct timezone *)0);
+ gethostname(r.hostname, 256);
+ MD5Update(&c, &r, sizeof(randomness));
+ MD5Final(seed, &c);
+ };
+
+ #endif
+
+ utest.c
+
+ #include "copyrt.h"
+ #include "sysdep.h"
+ #include <stdio.h>
+ #include "uuid.h"
+
+ uuid_t NameSpace_DNS = { /* 6ba7b810-9dad-11d1-80b4-00c04fd430c8 */
+ 0x6ba7b810,
+ 0x9dad,
+ 0x11d1,
+ 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8
+ };
+
+
+
+ Leach, Salz expires Aug 1998 [Page 26]\f
+
+
+ Internet-Draft UUIDs and GUIDs (DRAFT) 02/04/98
+
+
+ /* puid -- print a UUID */
+ void puid(uuid_t u);
+
+ /* Simple driver for UUID generator */
+ void main(int argc, char **argv) {
+ uuid_t u;
+ int f;
+
+ uuid_create(&u);
+ printf("uuid_create() -> "); puid(u);
+
+ f = uuid_compare(&u, &u);
+ printf("uuid_compare(u,u): %d\n", f); /* should be 0 */
+ f = uuid_compare(&u, &NameSpace_DNS);
+ printf("uuid_compare(u, NameSpace_DNS): %d\n", f); /* s.b. 1 */
+ f = uuid_compare(&NameSpace_DNS, &u);
+ printf("uuid_compare(NameSpace_DNS, u): %d\n", f); /* s.b. -1 */
+
+ uuid_create_from_name(&u, NameSpace_DNS, "www.widgets.com", 15);
+ printf("uuid_create_from_name() -> "); puid(u);
+ };
+
+ void puid(uuid_t u) {
+ int i;
+
+ printf("%8.8x-%4.4x-%4.4x-%2.2x%2.2x-", u.time_low, u.time_mid,
+ u.time_hi_and_version, u.clock_seq_hi_and_reserved,
+ u.clock_seq_low);
+ for (i = 0; i < 6; i++)
+ printf("%2.2x", u.node[i]);
+ printf("\n");
+ };
+
+Appendix B _ Sample output of utest
+
+ uuid_create() -> 7d444840-9dc0-11d1-b245-5ffdce74fad2
+ uuid_compare(u,u): 0
+ uuid_compare(u, NameSpace_DNS): 1
+ uuid_compare(NameSpace_DNS, u): -1
+ uuid_create_from_name() -> e902893a-9d22-3c7e-a7b8-d6e313b71d9f
+
+Appendix C _ Some name space IDs
+
+ This appendix lists the name space IDs for some potentially
+ interesting name spaces, as initialized C structures and in the
+ string representation defined in section 3.5
+
+ uuid_t NameSpace_DNS = { /* 6ba7b810-9dad-11d1-80b4-00c04fd430c8 */
+ 0x6ba7b810,
+ 0x9dad,
+ 0x11d1,
+ 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8
+ };
+
+
+ Leach, Salz expires Aug 1998 [Page 27]\f
+
+
+ Internet-Draft UUIDs and GUIDs (DRAFT) 02/04/98
+
+
+ uuid_t NameSpace_URL = { /* 6ba7b811-9dad-11d1-80b4-00c04fd430c8 */
+ 0x6ba7b811,
+ 0x9dad,
+ 0x11d1,
+ 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8
+ };
+
+ uuid_t NameSpace_OID = { /* 6ba7b812-9dad-11d1-80b4-00c04fd430c8 */
+ 0x6ba7b812,
+ 0x9dad,
+ 0x11d1,
+ 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8
+ };
+
+ uuid_t NameSpace_X500 = { /* 6ba7b814-9dad-11d1-80b4-00c04fd430c8 */
+ 0x6ba7b814,
+ 0x9dad,
+ 0x11d1,
+ 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8
+ };
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
--- /dev/null
+Network Working Group M. Smith
+INTERNET-DRAFT Netscape Communications Corp.
+Intended Category: Standards Track
+Expires: 18 April 2000
+
+ 18 October 1999
+
+ LDAP C API Virtual List View Extension
+ <draft-smith-ldap-c-api-ext-vlv-00.txt>
+
+1. Status of this Memo
+
+This document is an Internet-Draft and is in full conformance with all
+provisions of Section 10 of RFC2026. Internet-Drafts are working docu-
+ments of the Internet Engineering Task Force (IETF), its areas, and its
+working groups. Note that other groups may also distribute working
+documents as Internet-Drafts.
+
+Internet-Drafts are draft documents valid for a maximum of six months
+and may be updated, replaced, or obsoleted by other documents at any
+time. It is inappropriate to use Internet-Drafts as reference material
+or to cite them other than as "work in progress."
+
+The list of current Internet-Drafts can be accessed at
+http://www.ietf.org/ietf/1id-abstracts.txt.
+
+The list of Internet-Draft Shadow Directories can be accessed at
+http://www.ietf.org/shadow.html.
+
+This draft document will be submitted to the RFC Editor as a Standards
+Track document. Distribution of this memo is unlimited. Technical dis-
+cussion of this document will take place on the IETF LDAP Extension
+Working Group mailing list <ietf-ldapext@netscape.com>. Please send
+editorial comments directly to the author <mcs@netscape.com>.
+
+Copyright (C) The Internet Society (1998-1999). All Rights Reserved.
+
+Please see the Copyright section near the end of this document for more
+information.
+
+Expires: 18 April 2000 [Page 1]
+
+INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
+
+2. Introduction
+
+This document defines a virtual list view extension for the LDAP C API
+to support the LDAP protocol extensions for scrolling view browsing of
+search results. More specifically, this document defines functions to
+create virtual list view request controls and to parse virtual list view
+response controls.
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+"SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are
+to be interpreted as described in RFC 2119 [KEYWORDS].
+
+3. Table of Contents
+
+1. Status of this Memo............................................1
+2. Introduction...................................................2
+3. Table of Contents..............................................2
+4. Background and Intended Usage..................................2
+5. Advertising the Virtual List View C LDAP API Extension.........3
+6. Creating a Virtual List View Request Control...................3
+7. Parsing a Virtual List View Response Control...................6
+8. Example Code...................................................8
+9. Security Considerations........................................8
+10. Copyright......................................................8
+11. Bibliography...................................................9
+12. Author's Address...............................................9
+13. Appendix A - Summary of Additions to the C LDAP API............9
+
+4. Background and Intended Usage
+
+The LDAP C API [CAPI] defines a C language application programming
+interface (API) to the Lightweight Directory Access Protocol [LDAP].
+This document defines an extension to that API to support an optional
+LDAP protocol extension for scrolling view browsing of search results,
+also known as Virtual List View [VLV].
+
+The scrolling view browsing LDAP extension itself is designed to allow a
+"virtual list box" feature to be supported efficiently by LDAP servers
+and clients. The protocol extension consists of two LDAP controls: a
+Virtual List View (VLV) Request control which is sent by a client to a
+server along with an LDAP search request and a Virtual List View
+Response control which is returned by the server to send back status
+information about the VLV request.
+
+LDAP clients that wish to use the "virtual list box" feature SHOULD
+first check the supportedControls attribute in a server's rootDSE to
+
+Expires: 18 April 2000 [Page 2]
+
+INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
+
+determine if a value identical to the Virtual List View Request
+control's OID is present. If the OID is present and the client chooses
+to use the VLV feature, it MUST construct a Virtual List View Request
+control and a Server Side Sorting Control [SSS] and send both controls
+to the server within an LDAP searchRequest message. Both controls
+SHOULD be marked critical. Client applications MAY use the
+ldap_create_vlv_control() function described in this document to create
+a Virtual List View Request control.
+
+At the end of the search request processing, the server SHOULD return a
+Virtual List View Response control in the LDAP searchResultDone message.
+A Virtual List View Response control MAY be parsed to extract its con-
+tents by using the ldap_parse_vlv_control() function described in this
+document.
+
+5. Advertising the Virtual List View C LDAP API Extension
+
+To conform with the requirements defined in the C LDAP API specification
+[CAPI], implementations that support this extension SHOULD advertise the
+existence of this extension as follows:
+
+ Define the macro LDAP_API_FEATURE_VIRTUAL_LIST_VIEW as a value that
+ corresponds to the "level" or revision of this specification. When
+ this document is published as an RFC, the value to use for
+ LDAP_API_FEATURE_VIRTUAL_LIST_VIEW is the RFC number itself. While
+ this document is an Internet Draft, the value to use is 1000 plus the
+ revision number of this draft, i.e., 1000 for the -00 revision of
+ this draft, 1001 for the -01 version, and so on.
+
+ Return the text string VIRTUAL_LIST_VIEW in the ldapai_extensions
+ array of the LDAPAPIInfo structure following a successful call to
+ ldap_get_option() with an option parameter value of
+ LDAP_OPT_API_INFO.
+
+ Return information about the extension when the ldapaif_name field in
+ the LDAPAPIFeatureInfo structure is set to the text string
+ VIRTUAL_LIST_VIEW and a call to ldap_get_option() with an option
+ parameter value of LDAP_OPT_API_FEATURE_INFO is made.
+
+6. Creating a Virtual List View Request Control
+
+The LDAPVLVInfo structure describes a Virtual List View Request control
+and is passed to the ldap_create_vlv_control() function to create a Vir-
+tualListViewRequest control. The resulting control SHOULD be passed to
+
+Expires: 18 April 2000 [Page 3]
+
+INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
+
+the ldap_search_ext() or ldap_search_ext_s() functions described in
+[CAPI] to send them to the server. The ldap_create_sort_control() func-
+tion described in [SSSAPI] MAY be used to create a Sort control that is
+be passed to the server along with the VirtualListViewRequest control.
+
+The LDAPVLVInfo structure MAY also be used by applications to manage the
+state information associated with a series of virtual list view
+client/server interactions.
+
+ /* LDAPVLVInfo structure: */
+ typedef struct ldapvlvinfo {
+ int ldvlv_version; /* version of this struct (1) */
+ unsigned long ldvlv_before_count;
+ unsigned long ldvlv_after_count;
+ unsigned long ldvlv_offset; /* used if ldvlv_attrvalue is NULL
+*/
+ unsigned long ldvlv_count; /* used if ldvlv_attrvalue is NULL
+*
+ struct berval *ldvlv_attrvalue;
+ struct berval *ldvlv_context;
+ void *ldvlv_extradata; /* for use by application */
+ } LDAPVLVInfo;
+
+ /* value for the ldvlv_version field of the LDAPVLVInfo structure: */
+ #define LDAP_VLVINFO_VERSION 1
+
+ /* function used to create a VirtualListViewRequest control: */
+ int ldap_create_vlv_control(
+ LDAP *ld,
+ LDAPVLVInfo *vlvinfop,
+ LDAPControl **ctrlp
+ );
+
+ /* OID of the VirtualListViewRequest control: */
+ #define LDAP_CONTROL_VLVREQUEST "2.16.840.1.113730.3.4.9"
+
+The parameters to the ldap_create_vlv_control() function are:
+
+ld An LDAP session handle, as obtained from a call to
+ ldap_init().
+
+vlvinfop The address of an LDAPVLVInfo structure whose con-
+ tents are used to construct the value of the control
+ that is created.
+
+ctrlp A result parameter that will be assigned the address
+ of an LDAPControl structure that contains the Virtu-
+ alListViewRequest control created by this function.
+ The memory occupied by the LDAPControl structure
+ SHOULD be freed when it is no longer in use by
+
+Expires: 18 April 2000 [Page 4]
+
+INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
+
+ calling ldap_control_free().
+
+The ldap_create_vlv_control() function returns a C LDAP API error code
+to indicate success or failure (LDAP_SUCCESS if all goes well).
+
+The members of the LDAPVLVInfo structure are:
+
+ldvlv_version A number that identifies the version of the
+ LDAPVLVInfo structure. This SHOULD always be set to
+ the value LDAP_VLVINFO_VERSION (1).
+
+ldvlv_before_count A count of the number of entries before the target
+ entry the client wants the server to send back.
+ This field corresponds to the beforeCount element of
+ the BER-encoded VirtualListViewRequest control value
+ itself.
+
+ldvlv_after_count A count of the number of entries after the target
+ entry the client wants the server to send back.
+ This field corresponds to the afterCount element of
+ the BER-encoded VirtualListViewRequest control value
+ itself.
+
+ldvlv_offset This field is only used if ldvlv_attrvalue is NULL,
+ i.e, if the byoffset choice within the VirtualList-
+ ViewRequest control is to be used. ldvlv_offset is
+ used along with the ldvlv_count value by the server
+ to determine the target entry. This field
+ corresponds to the offset element within the BER-
+ encoded VirtualListViewRequest control value itself.
+
+ldvlv_count This field is only used if ldvlv_attrvalue is NULL,
+ i.e., if the byIndex choice within the VirtualList-
+ ViewRequest control is to be used. ldvlv_count is
+ used along with the ldvlv_offset value by the server
+ to determine the target entry. This field
+ corresponds to the contentCount element within the
+ BER-encoded VirtualListViewRequest control value
+ itself.
+
+ldvlv_attrvalue If this is not NULL, it indicates that the
+ greaterThanOrEqual choice within the VirtualList-
+ ViewRequest is to be used. ldvlv_attrvalue
+ corresponds to the assertionValue element of the
+ BER-encoded VirtualListViewRequest control value
+ itself. This value is compared by the server with
+ the values of the attribute specified by the primary
+ sort key to determine the target entry.
+
+Expires: 18 April 2000 [Page 5]
+
+INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
+
+ldvlv_context If this is not NULL, it is included as the context
+ identifier in the VirtualListViewRequest control;
+ ldvlv_context corresponds to the contextID element
+ within the BER-encoded VirtualListViewRequest con-
+ trol value itself. If ldvlv_context is NULL, no
+ context identifier is included in the VirtualList-
+ ViewRequest control.
+
+ldvlv_extradata This field is reserved for application-specific use
+ and is not used by the ldap_create_vlv_control()
+ function; it has no effect on the control that is
+ created.
+
+7. Parsing a Virtual List View Response Control
+
+When an application receives the result from a VLV search, it SHOULD use
+the ldap_parse_vlv_control() function to look for and parse the Virtual
+List View Response control returned by the server.
+
+ /* function used to look for and parse a VirtualListViewResponse
+control: */
+ int ldap_parse_vlv_control(
+ LDAP *ld,
+ LDAPControl **ctrls,
+ unsigned long *target_posp,
+ unsigned long *list_countp,
+ struct berval **contextp,
+ int *errcodep
+ );
+
+ /* OID of the VirtualListViewResponse control: */
+ #define LDAP_CONTROL_VLVRESPONSE "2.16.840.1.113730.3.4.10"
+
+ /* new error codes: */
+ #define LDAP_SORT_CONTROL_MISSING 0x3C /* 60 */
+ #define LDAP_INDEX_RANGE_ERROR 0x3D /* 61 */
+
+The parameters to the ldap_parse_vlv_control() function are:
+
+ld An LDAP session handle.
+
+ctrls The address of a NULL-terminated array of LDAPCon-
+ trol structures, typically obtained by a call to
+ ldap_parse_result().
+
+target_posp This result parameter is filled in with the list
+ index of the target entry. If this parameter is
+ NULL, the target position is not returned. The
+
+Expires: 18 April 2000 [Page 6]
+
+INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
+
+ value for this result parameter is pulled from the
+ targetPosition element of the BER-encoded Virtual-
+ ListViewResponse control value itself.
+
+list_countp This result parameter is filled in with the server's
+ estimate of the size of the list. If this parameter
+ is NULL, the size is not returned. The value for
+ this result parameter is pulled from the con-
+ tentCount element of the BER-encoded VirtualList-
+ ViewResponse control value itself.
+
+contextp This result parameter is filled in with the address
+ of a struct berval that contains the server-
+ generated context identifier if one was returned by
+ the server. If the server did not return a context
+ identifier, this parameter will be set to NULL. The
+ struct berval returned SHOULD be disposed of by cal-
+ ling ber_bvfree() when it is no longer needed. If
+ NULL is passed for contextp, the context identifier
+ is not returned.
+
+errcodep This result parameter is filled in with the VLV
+ result code. If this parameter is NULL, the result
+ code is not returned. The value for this result
+ parameter is pulled from the virtualListViewResult
+ element of the BER-encoded VirtualListViewResponse
+ control value itself. As specified in the VLV pro-
+ tocol extension [VLV], it will have one of the fol-
+ lowing values:
+
+ LDAP_SUCCESS (0); defined in [CAPI]
+ LDAP_OPERATIONS_ERROR (1); defined in [CAPI]
+ LDAP_UNWILLING_TO_PERFORM (53); defined in [CAPI]
+ LDAP_INSUFFICIENT_ACCESS (50); defined in [CAPI]
+ LDAP_BUSY (51); defined in [CAPI]
+ LDAP_TIMELIMIT_EXCEEDED (3); defined in [CAPI]
+ LDAP_ADMINLIMIT_EXCEEDED (11); defined in [CAPI]
+ LDAP_SORT_CONTROL_MISSING (60); defined above
+ LDAP_INDEX_RANGE_ERROR (61); defined above
+ LDAP_OTHER (80); defined in [CAPI]
+
+The ldap_parse_vlv_control() function returns an LDAP error code that
+indicates whether a VLV Result control was found and whether the parsing
+was successful. LDAP_SUCCESS is returned if all goes well,
+LDAP_CONTROL_NOT_FOUND is returned if the ctrls array does not include a
+VirtualListViewResponse control, and another LDAP error code that is
+defined in [CAPI] is returned if a parsing error or other problem
+occurs.
+
+Expires: 18 April 2000 [Page 7]
+
+INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
+
+8. Example Code
+
+To be provided.
+
+9. Security Considerations
+
+Most servers will be configured to restrict access to the Virtual List
+View feature since poorly-behaved or malicious clients may cause many
+resources to be consumed on the server, or allow users to retrieve too
+many entries, or allow users to get an accurate count of the number of
+entries present in a portion of the DIT. Clients should take care to
+not abuse the VLV feature and should be prepared for servers to refuse
+to service a particular VLV request due to access control or other
+site-defined policies.
+
+Please see the protocol extension document [VLV] for a discussion of
+related security considerations.
+
+10. Copyright
+
+Copyright (C) The Internet Society (1998-1999). All Rights Reserved.
+
+This document and translations of it may be copied and furnished to oth-
+ers, and derivative works that comment on or otherwise explain it or
+assist in its implementation may be prepared, copied, published and dis-
+tributed, 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 Stan-
+dards 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 FIT-
+NESS FOR A PARTICULAR PURPOSE.
+
+Expires: 18 April 2000 [Page 8]
+
+INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
+
+11. Bibliography
+
+[CAPI] M. Smith, T. Howes, A. Herron, M. Wahl, A. Anantha, "The C
+ LDAP Application Program Interface", INTERNET-DRAFT,
+ <draft-ietf-ldapext-ldap-c-api-04.txt>, 8 October 1999.
+
+[KEYWORDS] S. Bradner, "Key words for use in RFCs to Indicate Require-
+ ment Levels", RFC 2119, March 1997.
+
+[LDAP] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access
+ Protocol (v3)", RFC 2251, December 1997.
+
+[SSS] A. Herron, T. Howes, M. Wahl, A. Anantha, "LDAP Control
+ Extension for Server Side Sorting of Search Results",
+ INTERNET-DRAFT, April 1999.
+
+[SSSAPI] C. Weider, A. Herron, T. Howes, M. Smith, M. Wahl, "LDAP API
+ Extensions for Sort and Simple Paged Results", INTERNET-
+ DRAFT, <draft-ietf-asid-ldapv3-api-ext-00.txt>, July 1997.
+
+[VLV] D. Boreham, J. Sermersheim, A. Anantha, M. Armijo, "LDAP
+ Extensions for Scrolling View Browsing of Search Results",
+ INTERNET-DRAFT <draft-ietf-ldapext-ldapv3-vlv-03.txt>, 11
+ June 1999.
+
+12. Author's Address
+
+ Mark Smith
+ Netscape Communications Corp.
+ 501 E. Middlefield Rd., Mailstop MV068
+ Mountain View, CA 94043
+ USA
+ +1 650 937-3477
+ mcs@netscape.com
+
+13. Appendix A - Summary of Additions to the C LDAP API
+
+This extension introduces the following macros:
+
+ LDAP_API_FEATURE_VIRTUAL_LIST_VIEW
+ LDAP_VLVINFO_VERSION
+ LDAP_CONTROL_VLVREQUEST
+ LDAP_CONTROL_VLVRESPONSE
+ LDAP_SORT_CONTROL_MISSING
+ LDAP_INDEX_RANGE_ERROR
+
+Expires: 18 April 2000 [Page 9]
+
+INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
+
+This extension introduces the following structures and typedefs:
+
+ ldapvlvinfo
+ LDAPVLVInfo
+
+This extension introduces the following functions:
+
+ ldap_create_vlv_control()
+ ldap_parse_vlv_control()
+
+Expires: 18 April 2000 [Page 10]
/* Experimental Controls */
+#define LDAP_CONTROL_SORTREQUEST "1.2.840.113556.1.4.473"
+#define LDAP_CONTROL_SORTRESPONSE "1.2.840.113556.1.4.474"
+#define LDAP_CONTROL_VLVREQUEST "2.16.840.1.113730.3.4.9"
+#define LDAP_CONTROL_VLVRESPONSE "2.16.840.1.113730.3.4.10"
+
/* LDAP Unsolicited Notifications */
#define LDAP_NOTICE_OF_DISCONNECTION "1.3.6.1.4.1.1466.20036"
#define LDAP_NOTICE_DISCONNECT LDAP_NOTICE_OF_DISCONNECTION
LDAP_END_DECL
+/*
+ * in sortctrl.c
+ */
+/*
+ * structure for a sort-key
+ */
+typedef struct ldapsortkey {
+ char * attributeType;
+ char * orderingRule;
+ int reverseOrder;
+} LDAPSortKey;
+
+LIBLDAP_F( int )
+ldap_create_sort_keylist LDAP_P((
+ LDAPSortKey ***sortKeyList,
+ char *keyString));
+
+
+LIBLDAP_F( void )
+ldap_free_sort_keylist LDAP_P((
+ LDAPSortKey **sortkeylist));
+
+
+LIBLDAP_F( int )
+ldap_create_sort_control LDAP_P((
+ LDAP *ld,
+ LDAPSortKey **keyList,
+ int ctl_iscritical,
+ LDAPControl **ctrlp));
+
+LIBLDAP_F( int )
+ldap_parse_sort_control LDAP_P((
+ LDAP *ld,
+ LDAPControl **ctrlp,
+ unsigned long *result,
+ char **attribute));
+
+
+/*
+ * in vlvctrl.c
+ */
+
+/*
+ * structure for virtul list.
+ */
+typedef struct ldapvlvinfo {
+ int ldvlv_version;
+ unsigned long ldvlv_before_count;
+ unsigned long ldvlv_after_count;
+ unsigned long ldvlv_offset;
+ unsigned long ldvlv_count;
+ struct berval *ldvlv_attrvalue;
+ struct berval *ldvlv_context;
+ void *ldvlv_extradata;
+} LDAPVLVInfo;
+
+LIBLDAP_F( int )
+ldap_create_vlv_control LDAP_P((
+ LDAP *ld,
+ LDAPVLVInfo *ldvlistp,
+ LDAPControl **ctrlp));
+
+LIBLDAP_F( int )
+ldap_parse_vlv_control LDAP_P((
+ LDAP *ld,
+ LDAPControl **ctrls,
+ unsigned long *target_posp,
+ unsigned long *list_countp,
+ struct berval **contextp,
+ int *errcodep));
+
#endif /* _LDAP_H */
/* LDAP v2 Referrals */
#undef LDAP_API_FEATURE_X_OPENLDAP_V2_REFERRALS
+/* LDAP Server Side Sort. */
+#define LDAP_API_FEATURE_SERVER_SIDE_SORT 1000
+
+/* LDAP Virtual List View. */
+#define LDAP_API_FEATURE_VIRTUAL_LIST_VIEW 1000
+
#endif /* LDAP_FEATURES */
/* LDAP v2 Referrals */
#define LDAP_API_FEATURE_X_OPENLDAP_V2_REFERRALS LDAP_VENDOR_VERSION
+/* LDAP Server Side Sort. */
+#define LDAP_API_FEATURE_SERVER_SIDE_SORT 1000
+
+/* LDAP Virtual List View. Version = 1000 + draft revision.
+ * VLV requires Server Side Sort control.
+ */
+#define LDAP_API_FEATURE_VIRTUAL_LIST_VIEW 1000
+
#endif /* LDAP_FEATURES */
getfilter.c sasl.c sbind.c kbind.c unbind.c friendly.c cldap.c \
free.c disptmpl.c srchpref.c dsparse.c tmplout.c sort.c \
getdn.c getentry.c getattr.c getvalues.c addentry.c \
- request.c os-ip.c url.c \
+ request.c os-ip.c url.c sortctrl.c vlvctrl.c \
init.c options.c print.c string.c util-int.c schema.c \
charray.c tls.c dn.c os-local.c dnssrv.c \
utf-8.c
getfilter.lo sasl.lo sbind.lo kbind.lo unbind.lo friendly.lo cldap.lo \
free.lo disptmpl.lo srchpref.lo dsparse.lo tmplout.lo sort.lo \
getdn.lo getentry.lo getattr.lo getvalues.lo addentry.lo \
- request.lo os-ip.lo url.lo \
+ request.lo os-ip.lo url.lo sortctrl.lo vlvctrl.lo \
init.lo options.lo print.lo string.lo util-int.lo schema.lo \
charray.lo tls.lo dn.lo os-local.lo dnssrv.lo \
utf-8.lo
new->ldctl_iscritical = c->ldctl_iscritical;
return new;
}
+
+/*
+ * Copyright 1998-2000 The OpenLDAP Foundation, All Rights Reserved.
+ * COPYING RESTRICTIONS APPLY, see COPYRIGHT file
+ */
+/* Adapted for inclusion into OpenLDAP by Kurt D. Zeilenga */
+/*---
+ * This notice applies to changes, created by or for Novell, Inc.,
+ * to preexisting works for which notices appear elsewhere in this file.
+ *
+ * Copyright (C) 1999, 2000 Novell, Inc. All Rights Reserved.
+ *
+ * THIS WORK IS SUBJECT TO U.S. AND INTERNATIONAL COPYRIGHT LAWS AND TREATIES.
+ * USE, MODIFICATION, AND REDISTRIBUTION OF THIS WORK IS SUBJECT TO VERSION
+ * 2.0.1 OF THE OPENLDAP PUBLIC LICENSE, A COPY OF WHICH IS AVAILABLE AT
+ * HTTP://WWW.OPENLDAP.ORG/LICENSE.HTML OR IN THE FILE "LICENSE" IN THE
+ * TOP-LEVEL DIRECTORY OF THE DISTRIBUTION. ANY USE OR EXPLOITATION OF THIS
+ * WORK OTHER THAN AS AUTHORIZED IN VERSION 2.0.1 OF THE OPENLDAP PUBLIC
+ * LICENSE, OR OTHER PRIOR WRITTEN CONSENT FROM NOVELL, COULD SUBJECT THE
+ * PERPETRATOR TO CRIMINAL AND CIVIL LIABILITY.
+ *---
+ * Modification to OpenLDAP source by Novell, Inc.
+ * June 2000 sfs Added control utilities
+ */
+/*---
+ ldap_int_create_control
+
+ Internal function to create an LDAP control from the encoded BerElement.
+
+ requestOID (IN) The OID to use in creating the control.
+
+ ber (IN) The encoded BerElement to use in creating the control.
+
+ iscritical (IN) 0 - Indicates the control is not critical to the operation.
+ non-zero - The control is critical to the operation.
+
+ ctrlp (OUT) Returns a pointer to the LDAPControl created. This control
+ SHOULD be freed by calling ldap_control_free() when done.
+---*/
+
+LIBLDAP_F( int )
+ldap_int_create_control(
+ const char *requestOID,
+ BerElement *ber,
+ int iscritical,
+ LDAPControl **ctrlp )
+{
+ LDAPControl *ctrl;
+ struct berval *bvalp;
+
+ if ( requestOID == NULL || ber == NULL || ctrlp == NULL ) {
+ return LDAP_PARAM_ERROR;
+ }
+
+ if ( ber_flatten( ber, &bvalp ) == LBER_ERROR ) {
+ return LDAP_NO_MEMORY;
+ }
+
+ ctrl = (LDAPControl *) LBER_MALLOC( sizeof(LDAPControl) );
+ if ( ctrl == NULL ) {
+ ber_bvfree( bvalp );
+ return LDAP_NO_MEMORY;
+ }
+
+ ctrl->ldctl_value = *bvalp;
+ LDAP_FREE( bvalp );
+
+ ctrl->ldctl_oid = LDAP_STRDUP( requestOID );
+ ctrl->ldctl_iscritical = iscritical;
+
+ if ( ctrl->ldctl_oid == NULL ) {
+ LBER_FREE( ctrl );
+ return LDAP_NO_MEMORY;
+ }
+
+ *ctrlp = ctrl;
+ return LDAP_SUCCESS;
+}
LDAPControl *const *ctrls,
BerElement *ber ));
+LIBLDAP_F( int )
+ldap_int_create_control LDAP_P((
+ const char *requestOID,
+ BerElement *ber,
+ int iscritical,
+ LDAPControl **ctrlp ));
+
/*
* in dsparse.c
*/
getfilter.c sasl.c sbind.c kbind.c unbind.c friendly.c cldap.c \
free.c disptmpl.c srchpref.c dsparse.c tmplout.c sort.c \
getdn.c getentry.c getattr.c getvalues.c addentry.c \
- request.c os-ip.c url.c \
+ request.c os-ip.c url.c sortctrl.c vlvctrl.c \
init.c options.c print.c string.c util-int.c schema.c \
charray.c tls.c dn.c os-local.c dnssrv.c \
utf-8.c
getfilter.lo sasl.lo sbind.lo kbind.lo unbind.lo friendly.lo cldap.lo \
free.lo disptmpl.lo srchpref.lo dsparse.lo tmplout.lo sort.lo \
getdn.lo getentry.lo getattr.lo getvalues.lo addentry.lo \
- request.lo os-ip.lo url.lo \
+ request.lo os-ip.lo url.lo sortctrl.lo vlvctrl.lo \
init.lo options.lo print.lo string.lo util-int.lo schema.lo \
thr_posix.lo thr_cthreads.lo thr_thr.lo thr_lwp.lo thr_nt.lo \
thr_pth.lo thr_sleep.lo thr_stub.lo rdwr.lo threads.lo \
projects / openldap / commitdiff