+++ /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 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
+
+
+
+
+
+
+INTERNET-DRAFT S. Legg
+draft-legg-ldap-acm-admin-01.txt Adacel Technologies
+Intended Category: Standards Track September 18, 2002
+
+
+ Access Control Administration in LDAP
+
+ Copyright (C) The Internet Society (2002). All Rights Reserved.
+
+ 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 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".
+
+ 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.
+
+ Distribution of this document is unlimited. Comments should be sent
+ to the LDUP working group mailing list <ietf-ldup@imc.org> or to the
+ author.
+
+ This Internet-Draft expires on 18 March 2003.
+
+
+1. Abstract
+
+ This document adapts the X.500 directory administrative model, as it
+ pertains to access control administration, for use by the Lightweight
+ Directory Access Protocol. The administrative model partitions the
+ Directory Information Tree for various aspects of directory data
+ administration, e.g. subschema, access control and collective
+ attributes. This document provides the particular definitions that
+ support access control administration, but does not define a
+ particular access control scheme.
+
+
+
+Legg Expires 18 March 2003 [Page 1]
+\f
+INTERNET-DRAFT Access Control Administration September 18, 2002
+
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in RFC 2119 [RFC2119].
+
+
+2. Table of Contents
+
+ 1. Abstract .................................................... 1
+ 2. Table of Contents ........................................... 2
+ 3. Introduction ................................................ 2
+ 4. Access Control Administrative Areas ......................... 3
+ 5. Access Control Scheme Indication ............................ 3
+ 6. Access Control Information .................................. 4
+ 7. Access Control Subentries ................................... 4
+ 8. Applicable Access Control Information ....................... 5
+ 9. Security Considerations ..................................... 5
+ 10. Acknowledgements ........................................... 6
+ 11. Normative References ....................................... 6
+ 12. Informative References ..................................... 6
+ 13. Copyright Notice ........................................... 7
+ 14. Author's Address ........................................... 7
+
+
+3. Introduction
+
+ This document adapts the X.500 directory administrative model [X501],
+ as it pertains to access control administration, for use by the
+ Lightweight Directory Access Protocol (LDAP) [RFC2251].
+
+ The administrative model [ADMIN] partitions the Directory Information
+ Tree (DIT) for various aspects of directory data administration, e.g.
+ subschema, access control and collective attributes. The parts of
+ the administrative model that apply to every aspect of directory data
+ administration are described in [ADMIN]. This document describes the
+ administrative framework for access control.
+
+ An access control scheme describes the means by which access to
+ directory information, and potentially to access rights themselves,
+ may be controlled. This document describes the framework for
+ employing access control schemes but does not define a particular
+ access control scheme. Two access control schemes known as Basic
+ Access Control and Simplified Access Control are defined by [BAC].
+ Other access control schemes MAY be defined by other documents.
+
+ Schema definitions are provided using LDAP description formats
+ [RFC2252]. Note that the LDAP descriptions have been rendered with
+ additional white-space and line breaks for the sake of readability.
+
+
+
+
+Legg Expires 18 March 2003 [Page 2]
+\f
+INTERNET-DRAFT Access Control Administration September 18, 2002
+
+
+ This document is derived from, and duplicates substantial portions
+ of, Sections 4 and 8 of [X501].
+
+
+4. Access Control Administrative Areas
+
+ The specific administrative area [ADMIN] for access control is termed
+ an Access Control Specific Area (ACSA). The root of the ACSA is
+ termed an Access Control Specific Point (ACSP) and is represented in
+ the DIT by an administrative entry [ADMIN] which includes
+ accessControlSpecificArea as a value of its administrativeRole
+ operational attribute [SUBENTRY].
+
+ An ACSA MAY be partitioned into subtrees termed inner administrative
+ areas [ADMIN]. Each such inner area is termed an Access Control
+ Inner Area (ACIA). The root of the ACIA is termed an Access Control
+ Inner Point (ACIP) and is represented in the DIT by an administrative
+ entry which includes accessControlInnerArea as a value of its
+ administrativeRole operational attribute.
+
+ An administrative entry can never be both an ACSP and an ACIP. The
+ corresponding values can therefore never be present simultaneously in
+ the administrativeRole attribute.
+
+ Each entry necessarily falls within one and only one ACSA. Each such
+ entry may also fall within one or more ACIAs nested inside the ACSA
+ containing the entry.
+
+ An ACSP or ACIP has zero, one or more subentries that contain Access
+ Control Information (ACI).
+
+
+5. Access Control Scheme Indication
+
+ The access control scheme (e.g. Basic Access Control [BAC]) in force
+ in an ACSA is indicated by the accessControlScheme operational
+ attribute contained in the administrative entry for the relevant
+ ACSP.
+
+ The LDAP description [RFC2252] for the accessControlScheme
+ operational attribute is:
+
+ ( 2.5.24.1 NAME 'accessControlScheme'
+ EQUALITY objectIdentifierMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.38
+ SINGLE-VALUE USAGE directoryOperation )
+
+ An access control scheme conforming to the access control framework
+
+
+
+Legg Expires 18 March 2003 [Page 3]
+\f
+INTERNET-DRAFT Access Control Administration September 18, 2002
+
+
+ described in this document MUST define a distinct OBJECT IDENTIFIER
+ value to identify it through the accessControlScheme attribute.
+
+ Only administrative entries for ACSPs are permitted to contain an
+ accessControlScheme attribute. If the accessControlScheme attribute
+ is absent from a given ACSP, the access control scheme in force in
+ the corresponding ACSA, and its effect on operations, results and
+ errors, is implementation defined.
+
+ Any entry or subentry in an ACSA is permitted to contain ACI if and
+ only if such ACI is permitted by, and consistent with, the access
+ control scheme identified by the value of the accessControlScheme
+ attribute of the ACSP.
+
+
+6. Access Control Information
+
+ There are three categories of Access Control Information (ACI):
+ entry, subentry and prescriptive.
+
+ Entry ACI applies to only the entry or subentry in which it appears,
+ and the contents thereof. Subject to the access control scheme, any
+ entry or subentry MAY hold entry ACI.
+
+ Subentry ACI applies to only the subentries of the administrative
+ entry in which it appears. Subject to the access control scheme, any
+ administrative entry, for any aspect of administration, MAY hold
+ subentry ACI.
+
+ Prescriptive ACI applies to all the entries within a subtree or
+ subtree refinement of an administrative area (either an ACSA or an
+ ACIA), as defined by the subtreeSpecification attribute of the
+ subentry in which it appears. Prescriptive ACI is only permitted in
+ subentries of an ACSP or ACIP. Prescriptive ACI in the subentries of
+ a particular administrative point never applies to the same or any
+ other subentry of that administrative point, but does apply to the
+ subentries of subordinate administrative points, where those
+ subentries are within the subtree or subtree refinement.
+
+
+7. Access Control Subentries
+
+ Each subentry which contains prescriptive ACI MUST have
+ accessControlSubentry as a value of its objectClass attribute. Such
+ a subentry is called an access control subentry.
+
+ The LDAP description [RFC2252] for the accessControlSubentry
+ auxiliary object class is:
+
+
+
+Legg Expires 18 March 2003 [Page 4]
+\f
+INTERNET-DRAFT Access Control Administration September 18, 2002
+
+
+ ( 2.5.17.1 NAME 'accessControlSubentry' AUXILIARY )
+
+ A subentry of this object class MUST contain at least one
+ prescriptive ACI attribute of a type consistent with the value of the
+ accessControlScheme attribute of the corresponding ACSP.
+
+ The subtree or subtree refinement for an access control subentry is
+ termed a Directory Access Control Domain (DACD). A DACD can contain
+ zero entries, and can encompass entries that have not yet been added
+ to the DIT, but does not extend beyond the scope of the ACSA or ACIA
+ with which it is associated.
+
+ Since a subtreeSpecification may define a subtree refinement, DACDs
+ within a given ACSA may arbitrarily overlap.
+
+
+8. Applicable Access Control Information
+
+ Although particular items of ACI may specify attributes or values as
+ the protected items, ACI is logically associated with entries.
+
+ The ACI that is considered in access control decisions regarding an
+ entry includes:
+
+ (1) Entry ACI from that particular entry.
+
+ (2) Prescriptive ACI from access control subentries whose DACDs
+ contain the entry. Each of these access control subentries is
+ necessarily either a subordinate of the ACSP for the ACSA
+ containing the entry, or a subordinate of the ACIP for an ACIA
+ that contains the entry.
+
+ The ACI that is considered in access control decisions regarding a
+ subentry includes:
+
+ (1) Entry ACI from that particular subentry.
+
+ (2) Prescriptive ACI from access control subentries whose DACDs
+ contain the subentry, excluding those belonging to the same
+ administrative point as the subentry for which the decision is
+ being made.
+
+ (3) Subentry ACI from the administrative point associated with the
+ subentry.
+
+
+9. Security Considerations
+
+
+
+
+Legg Expires 18 March 2003 [Page 5]
+\f
+INTERNET-DRAFT Access Control Administration September 18, 2002
+
+
+ This document defines a framework for employing an access control
+ scheme, i.e. the means by which access to directory information and
+ potentially to access rights themselves may be controlled, but does
+ not itself define any particular access control scheme. The degree
+ of protection provided, and any security risks, are determined by the
+ provisions of the access control schemes (defined elsewhere) making
+ use of this framework.
+
+ Security considerations that apply to directory administration in
+ general [ADMIN] also apply to access control administration.
+
+
+10. Acknowledgements
+
+ This document is derived from, and duplicates substantial portions
+ of, Sections 4 and 8 of [X501].
+
+
+11. Normative References
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [RFC2251] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory
+ Access Protocol (v3)", RFC 2251, December 1997.
+
+ [RFC2252] Wahl, M., Coulbeck, A., Howes, T. and S. Kille,
+ "Lightweight Directory Access Protocol (v3): Attribute
+ Syntax Definitions", RFC 2252, December 1997.
+
+ [ADMIN] Legg, S., "Directory Administrative Model in LDAP",
+ draft-legg-ldap-admin-xx.txt, a work in progress,
+ September 2002.
+
+ [SUBENTRY] Zeilenga, K. and S. Legg, "Subentries in LDAP",
+ draft-zeilenga-ldap-subentry-xx.txt, a work in progress,
+ August 2002.
+
+
+12. Informative References
+
+ [BAC] Legg, S., "Basic and Simplified Access Control in LDAP",
+ draft-legg-ldap-acm-bac-xx.txt, a work in progress,
+ September 2002.
+
+ [COLLECT] Zeilenga, K., "Collective Attributes in LDAP",
+ draft-zeilenga-ldap-collective-xx.txt, a work in progress,
+ August 2002.
+
+
+
+Legg Expires 18 March 2003 [Page 6]
+\f
+INTERNET-DRAFT Access Control Administration September 18, 2002
+
+
+ [X501] ITU-T Recommendation X.501 (02/2001), Information
+ technology - Open Systems Interconnection - The Directory:
+ Models
+
+
+13. Copyright Notice
+
+ Copyright (C) The Internet Society (2002). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+
+14. Author's Address
+
+ Steven Legg
+ Adacel Technologies Ltd.
+ 405-409 Ferntree Gully Road
+ Mount Waverley, Victoria 3149
+ AUSTRALIA
+
+ Phone: +61 3 9451 2107
+ Fax: +61 3 9541 2121
+ EMail: steven.legg@adacel.com.au
+
+
+15. Appendix A - Changes From Previous Drafts
+
+
+
+Legg Expires 18 March 2003 [Page 7]
+\f
+INTERNET-DRAFT Access Control Administration September 18, 2002
+
+
+15.1 Changes in Draft 01
+
+ Section 4 has been extracted to become a separate Internet draft,
+ draft-legg-ldap-admin-00.txt. The subsections of Section 5 have
+ become the new Sections 4 to 8. Editorial changes have been made to
+ accommodate this split. No technical changes have been introduced.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Legg Expires 18 March 2003 [Page 8]
+\f
--- /dev/null
+
+
+
+
+
+
+INTERNET-DRAFT S. Legg
+draft-legg-ldap-admin-00.txt Adacel Technologies
+Intended Category: Standards Track September 18, 2002
+
+
+ Directory Administrative Model in LDAP
+
+ Copyright (C) The Internet Society (2002). All Rights Reserved.
+
+ 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 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".
+
+ 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.
+
+ Distribution of this document is unlimited. Comments should be sent
+ to the LDUP working group mailing list <ietf-ldup@imc.org> or to the
+ author.
+
+ This Internet-Draft expires on 18 March 2003.
+
+
+1. Abstract
+
+ This document adapts the X.500 directory administrative model for use
+ by the Lightweight Directory Access Protocol. The administrative
+ model partitions the Directory Information Tree for various aspects
+ of directory data administration, e.g. subschema, access control and
+ collective attributes. The generic framework that applies to every
+ aspect of administration is described in this document. The
+ definitions that apply for a specific aspect of administration, e.g.
+ access control administration, are described in other documents.
+
+
+
+Legg Expires 18 March 2003 [Page 1]
+\f
+INTERNET-DRAFT Directory Administrative Model September 18, 2002
+
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in RFC 2119 [RFC2119].
+
+
+2. Table of Contents
+
+ 1. Abstract .................................................... 1
+ 2. Table of Contents ........................................... 2
+ 3. Introduction ................................................ 2
+ 4. Administrative Areas ........................................ 2
+ 5. Autonomous Administrative Areas ............................. 3
+ 6. Specific Administrative Areas ............................... 3
+ 7. Inner Administrative Areas .................................. 4
+ 8. Administrative Entries ...................................... 5
+ 9. Security Considerations ..................................... 5
+ 10. Acknowledgements ........................................... 5
+ 11. Normative References ....................................... 5
+ 12. Informative References ..................................... 6
+ 13. Copyright Notice ........................................... 6
+ 14. Author's Address ........................................... 6
+
+
+3. Introduction
+
+ This document adapts the X.500 directory administrative model [X501]
+ for use by the Lightweight Directory Access Protocol (LDAP)
+ [RFC2251]. The administrative model partitions the Directory
+ Information Tree (DIT) for various aspects of directory data
+ administration, e.g. subschema, access control and collective
+ attributes. This document provides the definitions for the generic
+ parts of the administrative model that apply to every aspect of
+ directory data administration.
+
+ Sections 4 to 8, in conjunction with [SUBENTRY], describe the means
+ by which administrative authority is aportioned and exercised in the
+ DIT.
+
+ Aspects of administration that conform to the administrative model
+ described in this document are detailed elsewhere, e.g. access
+ control administration is described in [ACA] and collective attribute
+ administration is described in [COLLECT].
+
+ This document is derived from, and duplicates substantial portions
+ of, Sections 4 and 8 of [X501].
+
+
+4. Administrative Areas
+
+
+
+Legg Expires 18 March 2003 [Page 2]
+\f
+INTERNET-DRAFT Directory Administrative Model September 18, 2002
+
+
+ An administrative area is a subtree of the DIT considered from the
+ perspective of administration. The root entry of the subtree is an
+ administrative point. An administrative point is represented by an
+ entry holding an administrativeRole attribute [SUBENTRY]. The values
+ of this attribute identify the kind of administrative point.
+
+
+5. Autonomous Administrative Areas
+
+ The DIT may be partitioned into one or more non-overlapping subtrees
+ termed autonomous administrative areas. It is expected that the
+ entries in an autonomous administrative area are all administered by
+ the same administrative authority.
+
+ An administrative authority may be responsible for several autonomous
+ administrative areas in separated parts of the DIT but it SHOULD NOT
+ arbitrarily partition the collection of entries under its control
+ into autonomous administrative areas (thus creating adjacent
+ autonomous areas administered by the same authority).
+
+ The root entry of an autonomous administrative area's subtree is
+ called an autonomous administrative point. An autonomous
+ administrative area extends from its autonomous administrative point
+ downwards until another autonomous administrative point is
+ encountered, at which point another autonomous administrative area
+ begins.
+
+
+6. Specific Administrative Areas
+
+ Entries in an administrative area may be considered in terms of a
+ specific administrative function. When viewed in this context, an
+ administrative area is termed a specific administrative area.
+
+ Examples of specific administrative areas are subschema specific
+ administrative areas, access control specific areas and collective
+ attribute specific areas.
+
+ An autonomous administrative area may be considered as implicitly
+ defining a single specific administrative area for each specific
+ aspect of administration. In this case, there is a precise
+ correspondence between each such specific administrative area and the
+ autonomous administrative area.
+
+ Alternatively, for each specific aspect of administration, the
+ autonomous administrative area may be partitioned into
+ non-overlapping specific administrative areas.
+
+
+
+
+Legg Expires 18 March 2003 [Page 3]
+\f
+INTERNET-DRAFT Directory Administrative Model September 18, 2002
+
+
+ If so partitioned for a particular aspect of administration, each
+ entry of the autonomous administrative area is contained in one and
+ only one specific administrative area for that aspect, i.e. specific
+ administrative areas do not overlap.
+
+ The root entry of a specific administrative area's subtree is called
+ a specific administrative point. A specific administrative area
+ extends from its specific administrative point downwards until
+ another specific administrative point of the same administrative
+ aspect is encountered, at which point another specific administrative
+ area begins. Specific administrative areas are always bounded by the
+ autonomous administrative area they partition.
+
+ Where an autonomous administrative area is not partitioned for a
+ specific aspect of administration, the specific administrative area
+ for that aspect coincides with the autonomous administrative area.
+ In this case, the autonomous administrative point is also the
+ specific administrative point for this aspect of administration. A
+ particular administrative point may be the root of an autonomous
+ administrative area and may be the root of one or more specific
+ administrative areas for different aspects of administration.
+
+ It is not necessary for an administrative point to represent each
+ specific aspect of administrative authority. For example, there
+ might be an administrative point, subordinate to the root of the
+ autonomous administrative area, which is used for access control
+ purposes only.
+
+
+7. Inner Administrative Areas
+
+ For some aspects of administration, e.g. access control or collective
+ attributes, inner administrative areas may be defined within the
+ specific administrative areas, to allow a limited form of delegation,
+ or for administrative or operational convenience.
+
+ An inner administrative area may be nested within another inner
+ administrative area. The rules for nested inner areas are defined as
+ part of the definition of the specific administrative aspect for
+ which they are allowed.
+
+ The root entry of an inner administrative area's subtree is called an
+ inner administrative point. An inner administrative area (within a
+ specific administrative area) extends from its inner administrative
+ point downwards until a specific administrative point of the same
+ administrative aspect is encountered. An inner administrative area
+ is bounded by the specific administrative area within which it is
+ defined.
+
+
+
+Legg Expires 18 March 2003 [Page 4]
+\f
+INTERNET-DRAFT Directory Administrative Model September 18, 2002
+
+
+8. Administrative Entries
+
+ An entry located at an administrative point is an administrative
+ entry. Administrative entries MAY have subentries [SUBENTRY] as
+ immediate subordinates. The administrative entry and its associated
+ subentries are used to control the entries encompassed by the
+ associated administrative area. Where inner administrative areas are
+ used, the scopes of these areas may overlap. Therefore, for each
+ specific aspect of administrative authority, a definition is required
+ of the method of combination of administrative information when it is
+ possible for entries to be included in more than one subtree or
+ subtree refinement associated with an inner area defined for that
+ aspect.
+
+
+9. Security Considerations
+
+ This document defines a generic framework for employing policy of
+ various kinds, e.g. access controls, to entries in the DIT. Such
+ policy can only be correctly enforced at a directory server holding a
+ replica of a portion of the DIT if the administrative entries for
+ administrative areas that overlap the portion of the DIT being
+ replicated, and the subentries of those administrative entries
+ relevant to any aspect of policy that is required to be enforced at
+ the replica, are included in the replicated information.
+
+ Administrative entries and subentries SHOULD be protected from
+ unauthorized examination or changes by appropriate access controls.
+
+
+10. Acknowledgements
+
+ This document is derived from, and duplicates substantial portions
+ of, Sections 4 and 8 of [X501].
+
+
+11. Normative References
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [RFC2251] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory
+ Access Protocol (v3)", RFC 2251, December 1997.
+
+ [SUBENTRY] Zeilenga, K. and S. Legg, "Subentries in LDAP",
+ draft-zeilenga-ldap-subentry-xx.txt, a work in progress,
+ August 2002.
+
+
+
+
+Legg Expires 18 March 2003 [Page 5]
+\f
+INTERNET-DRAFT Directory Administrative Model September 18, 2002
+
+
+12. Informative References
+
+ [ACA] Legg, S., "Access Control Administration in LDAP",
+ draft-legg-ldap-acm-admin-xx.txt, a work in progress,
+ September 2002.
+
+ [COLLECT] Zeilenga, K., "Collective Attributes in LDAP",
+ draft-zeilenga-ldap-collective-xx.txt, a work in progress,
+ August 2002.
+
+ [X501] ITU-T Recommendation X.501 (02/2001), Information
+ technology - Open Systems Interconnection - The Directory:
+ Models
+
+
+13. Copyright Notice
+
+ Copyright (C) The Internet Society (2002). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+
+14. Author's Address
+
+ Steven Legg
+ Adacel Technologies Ltd.
+
+
+
+Legg Expires 18 March 2003 [Page 6]
+\f
+INTERNET-DRAFT Directory Administrative Model September 18, 2002
+
+
+ 405-409 Ferntree Gully Road
+ Mount Waverley, Victoria 3149
+ AUSTRALIA
+
+ Phone: +61 3 9451 2107
+ Fax: +61 3 9541 2121
+ EMail: steven.legg@adacel.com.au
+
+
+15. Appendix A - Changes From Previous Drafts
+
+ This document reproduces Section 4 from
+ draft-legg-ldap-acm-admin-00.txt as a standalone document. All
+ changes made are purely editorial. No technical changes have been
+ introduced.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Legg Expires 18 March 2003 [Page 7]
+\f
--- /dev/null
+
+
+
+
+
+
+INTERNET-DRAFT S. Legg
+draft-legg-ldap-gser-abnf-04.txt Adacel Technologies
+Intended Category: Informational August 19, 2002
+
+
+ Common Elements of GSER Encodings
+
+ Copyright (C) The Internet Society (2002). All Rights Reserved.
+
+ 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 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".
+
+ 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.
+
+ Distribution of this document is unlimited. Comments should be sent
+ to the LDAPEXT working group mailing list <ietf-ldapext@netscape.com>
+ or to the author.
+
+ This Internet-Draft expires on 19 February 2002.
+
+
+1. Abstract
+
+ The Generic String Encoding Rules (GSER) describe a human readable
+ text encoding for an ASN.1 value of any ASN.1 type. Specifications
+ making use of GSER may wish to provide an equivalent ABNF description
+ of the GSER encoding for a particular ASN.1 type as a convenience for
+ implementors. This document supports such specifications by
+ providing equivalent ABNF for the GSER encodings for ASN.1 types
+ commonly occuring in Lightweight Directory Access Protocol (LDAP)
+ syntaxes.
+
+
+
+Legg Expires 19 February 2002 [Page 1]
+\f
+INTERNET-DRAFT Common Elements of GSER Encodings August 19, 2002
+
+
+2. Table of Contents
+
+ 1. Abstract .................................................... 1
+ 2. Table of Contents ........................................... 2
+ 3. Introduction ................................................ 2
+ 4. Conventions ................................................. 2
+ 5. Separators .................................................. 2
+ 6. ASN.1 Built-in Types ........................................ 3
+ 7. ASN.1 Restricted String Types ............................... 7
+ 8. Directory ASN.1 Types ....................................... 8
+ 9. Security Considerations ..................................... 9
+ 10. Normative References ....................................... 10
+ 11. Informative References ..................................... 10
+ 12. Copyright Notice ........................................... 10
+ 13. Author's Address ........................................... 11
+
+
+3. Introduction
+
+ The Generic String Encoding Rules (GSER) defined in [9] define a
+ human readable text encoding, based on ASN.1 [7] value notation, for
+ an ASN.1 value of any ASN.1 type. Specifications making use of GSER
+ may wish to provide a non-normative equivalent ABNF [3] description
+ of the GSER encoding for a particular ASN.1 type as a convenience for
+ implementors unfamiliar with ASN.1. This document supports such
+ specifications by providing equivalent ABNF for the GSER encodings
+ for ASN.1 types commonly occuring in LDAP [8] or X.500 [10] attribute
+ and assertion syntaxes, as well as equivalent ABNF for the GSER
+ encodings for the ASN.1 built-in types.
+
+ The ABNF given in this document does not replace or alter GSER in any
+ way. If there is a discrepancy between the ABNF specified here and
+ the encoding defined by GSER in [9] then [9] is to be taken as
+ definitive.
+
+
+4. Conventions
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in RFC 2119 [1].
+
+
+5. Separators
+
+ Certain separators are commonly used in constructing equivalent ABNF
+ for SET and SEQUENCE types.
+
+
+
+
+Legg Expires 19 February 2002 [Page 2]
+\f
+INTERNET-DRAFT Common Elements of GSER Encodings August 19, 2002
+
+
+ sp = *%x20 ; zero, one or more space characters
+ msp = 1*%x20 ; one or more space characters
+
+ sep = [ "," ]
+
+ The <sep> rule is used in the ABNF description of the encoding for
+ ASN.1 SET or SEQUENCE types where all the components are either
+ OPTIONAL or DEFAULT. It encodes to an empty string if and only if
+ the immediately preceding character in the encoding is "{", i.e. it
+ is only empty for the first optional component actually present in
+ the SET or SEQUENCE value being encoded.
+
+
+6. ASN.1 Built-in Types
+
+ This section describes the GSER encoding of values of the ASN.1
+ built-in types, except for the restricted character string types.
+
+ The <BIT-STRING> rule describes the GSER encoding of values of the
+ BIT STRING type without a named bit list.
+
+ BIT-STRING = bstring / hstring
+
+ If the number of bits in a BIT STRING value is a multiple of four the
+ <hstring> form of <BIT-STRING> MAY be used. The <bstring> form of
+ <BIT-STRING> is used otherwise. The <bstring> rule encodes each bit
+ as the character "0" or "1" in order from the first bit to the last
+ bit. The <hstring> rule encodes each group of four bits as a
+ hexadecimal number where the first bit is the most significant. An
+ odd number of hexadecimal digits is permitted.
+
+ hstring = squote *hexadecimal-digit squote %x48 ; '...'H
+ hexadecimal-digit = %x30-39 / ; "0" to "9"
+ %x41-46 ; "A" to "F"
+
+ bstring = squote *binary-digit squote %x42 ; '...'B
+ binary-digit = "0" / "1"
+
+ squote = %x27 ; ' (single quote)
+
+ The <BOOLEAN> rule describes the GSER encoding of values of the
+ BOOLEAN type.
+
+ BOOLEAN = %x54.52.55.45 / ; "TRUE"
+ %x46.41.4C.53.45 ; "FALSE"
+
+ The <CHARACTER-STRING> rule describes the GSER encoding of values of
+ the associated type for the unrestricted CHARACTER STRING type.
+
+
+
+Legg Expires 19 February 2002 [Page 3]
+\f
+INTERNET-DRAFT Common Elements of GSER Encodings August 19, 2002
+
+
+ CHARACTER-STRING = "{" sp id-identification msp Identification ","
+ sp id-data-value msp OCTET-STRING
+ sp "}"
+
+ id-identification = %x69.64.65.6E.74.69.66.69.63.61.74.69.6F.6E
+ ; "identification"
+ id-data-value = %x64.61.74.61.2D.76.61.6C.75.65 ; "data-value"
+
+ Identification = ( id-syntaxes ":" Syntaxes ) /
+ ( id-syntax ":" OBJECT-IDENTIFIER ) /
+ ( id-presentation-context-id ":" INTEGER ) /
+ ( id-context-negotiation ":"
+ ContextNegotiation ) /
+ ( id-transfer-syntax ":" OBJECT-IDENTIFIER ) /
+ ( id-fixed ":" NULL )
+
+ id-syntaxes = %x73.79.6E.74.61.78.65.73
+ ; "syntaxes"
+ id-syntax = %x73.79.6E.74.61.78 ; "syntax"
+ id-presentation-context-id = %x70.72.65.73.65.6E.74.61.74.69.6F.6E
+ %x2D.63.6F.6E.74.65.78.74.2D.69.64
+ ; "presentation-context-id"
+ id-context-negotiation = %x63.6F.6E.74.65.78.74.2D.6E.65.67.6F
+ %x74.69.61.74.69.6F.6E
+ ; "context-negotiation"
+ id-transfer-syntax = %x74.72.61.6E.73.66.65.72.2D.73.79.6E
+ %x74.61.78 ; "transfer-syntax"
+ id-fixed = %x66.69.78.65.64 ; "fixed"
+
+ Syntaxes = "{" sp id-abstract msp OBJECT-IDENTIFIER ","
+ sp id-transfer msp OBJECT-IDENTIFIER
+ sp "}"
+ id-abstract = %x61.62.73.74.72.61.63.74 ; "abstract"
+ id-transfer = %x74.72.61.6E.73.66.65.72 ; "transfer"
+
+ ContextNegotiation = "{" sp id-presentation-context-id msp
+ INTEGER ","
+ sp id-transfer-syntax msp
+ OBJECT-IDENTIFIER
+ sp "}"
+
+ The <INTEGER> rule describes the GSER encoding of values of the
+ INTEGER type without a named number list. The <INTEGER-0-MAX> rule
+ describes the GSER encoding of values of the constrained type INTEGER
+ (0..MAX). The <INTEGER-1-MAX> rule describes the GSER encoding of
+ values of the constrained type INTEGER (1..MAX).
+
+ INTEGER = "0" / positive-number / ("-" positive-number)
+
+
+
+Legg Expires 19 February 2002 [Page 4]
+\f
+INTERNET-DRAFT Common Elements of GSER Encodings August 19, 2002
+
+
+ INTEGER-0-MAX = "0" / positive-number
+ INTEGER-1-MAX = positive-number
+ positive-number = non-zero-digit *decimal-digit
+ decimal-digit = %x30-39 ; "0" to "9"
+ non-zero-digit = %x31-39 ; "1" to "9"
+
+ The <EMBEDDED-PDV> rule describes the GSER encoding of values of the
+ associated type for the EMBEDDED PDV type.
+
+ EMBEDDED-PDV = "{" sp id-identification msp Identification
+ [ "," sp id-data-value-descriptor msp
+ ObjectDescriptor ]
+ "," sp id-data-value msp OCTET-STRING
+ sp "}"
+
+ id-data-value-descriptor = %x64.61.74.61.2D.76.61.6C.75.65.2D.64
+ %x65.73.63.72.69.70.74.6F.72
+ ; "data-value-descriptor"
+
+ The <EXTERNAL> rule describes the GSER encoding of values of the
+ associated type for the EXTERNAL type.
+
+ EXTERNAL = "{" sp id-identification msp E-Identification
+ [ "," sp id-data-value-descriptor msp
+ ObjectDescriptor ]
+ "," sp id-data-value msp OCTET-STRING
+ sp "}"
+
+ E-Identification = ( id-syntax ":" OBJECT-IDENTIFIER ) /
+ ( id-presentation-context-id ":" INTEGER ) /
+ ( id-context-negotiation ":"
+ ContextNegotiation )
+
+ The <NULL> rule describes the GSER encoding of values of the NULL
+ type.
+
+ NULL = %x4E.55.4C.4C ; "NULL"
+
+ The <OBJECT-IDENTIFIER> rule describes the GSER encoding of values of
+ the OBJECT IDENTIFIER type.
+
+ OBJECT-IDENTIFIER = numeric-oid / descr
+ numeric-oid = oid-component 1*( "." oid-component )
+ oid-component = "0" / positive-number
+
+ An OBJECT IDENTIFIER value is encoded using either the dotted decimal
+ representation or an object descriptor name, i.e. <descr>. The
+ <descr> rule is described in [4]. An object descriptor name is
+
+
+
+Legg Expires 19 February 2002 [Page 5]
+\f
+INTERNET-DRAFT Common Elements of GSER Encodings August 19, 2002
+
+
+ potentially ambiguous and should be used with care.
+
+ The <OCTET-STRING> rule describes the GSER encoding of values of the
+ OCTET STRING type.
+
+ OCTET-STRING = hstring
+
+ The octets are encoded in order from the first octet to the last
+ octet. Each octet is encoded as a pair of hexadecimal digits where
+ the first digit corresponds to the four most significant bits of the
+ octet. If the hexadecimal string does not have an even number of
+ digits the four least significant bits in the last octet are assumed
+ to be zero.
+
+ The <REAL> rule describes the GSER encoding of values of the REAL
+ type.
+
+ REAL = "0" ; zero
+ / PLUS-INFINITY ; positive infinity
+ / MINUS-INFINITY ; negative infinity
+ / realnumber ; positive base 10 REAL value
+ / ( "-" realnumber ) ; negative base 10 REAL value
+ / real-sequence-value ; non-zero base 2 or 10 REAL value
+
+ PLUS-INFINITY = %x50.4C.55.53.2D.49.4E.46.49.4E.49.54.59
+ ; "PLUS-INFINITY"
+ MINUS-INFINITY = %x4D.49.4E.55.53.2D.49.4E.46.49.4E.49.54.59
+ ; "MINUS-INFINITY"
+
+ realnumber = mantissa exponent
+ mantissa = (positive-number [ "." *decimal-digit ])
+ / ( "0." *("0") positive-number )
+ exponent = "E" ( "0" / ([ "-" ] positive-number))
+
+ real-sequence-value = "{" sp id-mantissa msp INTEGER ","
+ sp id-base msp ( "2" / "10" ) ","
+ sp id-exponent msp INTEGER sp "}"
+ id-mantissa = %x6D.61.6E.74.69.73.73.61 ; "mantissa"
+ id-base = %x62.61.73.65 ; "base"
+ id-exponent = %x65.78.70.6F.6E.65.6E.74 ; "exponent"
+
+ A value of the REAL type MUST be encoded as "0" if it is zero.
+
+ The <RELATIVE-OID> rule describes the GSER encoding of values of the
+ RELATIVE-OID type.
+
+ RELATIVE-OID = oid-component *( "." oid-component )
+
+
+
+
+Legg Expires 19 February 2002 [Page 6]
+\f
+INTERNET-DRAFT Common Elements of GSER Encodings August 19, 2002
+
+
+7. ASN.1 Restricted String Types
+
+ This section describes the GSER encoding of values of the ASN.1
+ restricted character string types. The characters of a value of a
+ restricted character string type are always encoded as a UTF8
+ character string between double quotes. For some of the ASN.1 string
+ types this requires a translation to or form the UTF8 encoding. Some
+ of the ASN.1 string types permit only a subset of the characters
+ representable in UTF8. Any double quote characters in the character
+ string, where allowed by the character set, are escaped by being
+ repeated.
+
+ The <UTF8String> rule describes the GSER encoding of values of the
+ UTF8String type. The characters of this string type do not require
+ any translation before being encoded.
+
+ UTF8String = StringValue
+ StringValue = dquote *SafeUTF8Character dquote
+
+ dquote = %x22 ; " (double quote)
+
+ SafeUTF8Character = %x00-21 / %x23-7F / ; ASCII minus dquote
+ dquote dquote / ; escaped double quote
+ %xC0-DF %x80-BF / ; 2 byte UTF8 character
+ %xE0-EF 2(%x80-BF) / ; 3 byte UTF8 character
+ %xF0-F7 3(%x80-BF) / ; 4 byte UTF8 character
+ %xF8-FB 4(%x80-BF) / ; 5 byte UTF8 character
+ %xFC-FD 5(%x80-BF) ; 6 byte UTF8 character
+
+ The <NumericString>, <PrintableString>, <VisibleString>,
+ <ISO646String>, <IA5String>, <GeneralizedTime> and <UTCTime> rules
+ describe the GSER encoding of values of the correspondingly named
+ ASN.1 types. The characters of these string types are compatible
+ with UTF8 and do not require any translation before being encoded.
+ The GeneralizedTime and UTCTime types use the VisibleString character
+ set, but have a strictly defined format.
+
+ NumericString = dquote *(decimal-digit / space) dquote
+ space = %x20
+
+ PrintableString = dquote *PrintableCharacter dquote
+ PrintableCharacter = decimal-digit / space
+ / %x41-5A ; A to Z
+ / %x61-7A ; a to z
+ / %x27-29 ; ' ( )
+ / %x2B-2F ; + , - . /
+ / %x3A ; :
+ / %x3D ; =
+
+
+
+Legg Expires 19 February 2002 [Page 7]
+\f
+INTERNET-DRAFT Common Elements of GSER Encodings August 19, 2002
+
+
+ / %x3F ; ?
+
+ ISO646String = VisibleString
+ VisibleString = dquote *SafeVisibleCharacter dquote
+ SafeVisibleCharacter = %x20-21
+ / %x23-7E ; printable ASCII minus dquote
+ / dquote dquote ; escaped double quote
+
+ IA5String = dquote *SafeIA5Character dquote
+ SafeIA5Character = %x00-21 / %x23-7F ; ASCII minus dquote
+ / dquote dquote ; escaped double quote
+
+ UTCTime = dquote 10(decimal-digit) [2(decimal-digit)]
+ [ "Z" / u-differential ] dquote
+ u-differential = ( "-" / "+" ) 4(decimal-digit)
+ GeneralizedTime = dquote 10(decimal-digit)
+ *2(2(decimal-digit))
+ fraction [ "Z" / g-differential ] dquote
+ fraction = ( "." / "," ) 1*decimal-digit
+ g-differential = ( "-" / "+" ) 1*2(2(decimal-digit))
+
+ The <BMPString> and <UniversalString> rules describe the GSER
+ encoding of values of the BMPString and UniversalString types
+ respectively. BMPString (UCS-2) and UniversalString (UCS-4) values
+ are translated into UTF8 [6] character strings before being encoded
+ according to <StringValue>.
+
+ BMPString = StringValue
+ UniversalString = StringValue
+
+ The <TeletexString>, <T61String>, <VideotexString>, <GraphicString>,
+ <GeneralString> and <ObjectDescriptor> rules describe the GSER
+ encoding of values of the correspondingly named ASN.1 types. Values
+ of these string types are translated into UTF8 character strings
+ before being encoded according to <StringValue>. The
+ ObjectDescriptor type uses the GraphicString character set.
+
+ TeletexString = StringValue
+ T61String = StringValue
+ VideotexString = StringValue
+ GraphicString = StringValue
+ GeneralString = StringValue
+ ObjectDescriptor = GraphicString
+
+
+8. Directory ASN.1 Types
+
+ This section describes the GSER encoding of values of selected ASN.1
+
+
+
+Legg Expires 19 February 2002 [Page 8]
+\f
+INTERNET-DRAFT Common Elements of GSER Encodings August 19, 2002
+
+
+ types defined for LDAP and X.500. The ABNF rule names beginning with
+ uppercase letters describe the GSER encoding of values of the ASN.1
+ type with the same name.
+
+ AttributeType = OBJECT-IDENTIFIER
+
+ The characters of a DirectoryString are translated into UTF8
+ characters as required before being encoded between double quotes
+ with any embedded double quotes escaped by being repeated.
+
+ DirectoryString = dquote *SafeUTF8Character dquote
+
+ The <RDNSequence> rule describes the GSER encoding of values of the
+ RDNSequence type, which is syntactically equivalent to the
+ DistinguishedName and LocalName types. The <RDNSequence> rule
+ encodes a name as an LDAPDN character string between double quotes.
+ The character string is first derived according to the
+ <distinguishedName> rule in Section 3 of [5], and then it is encoded
+ between double quotes with any embedded double quotes escaped by
+ being repeated.
+
+ DistinguishedName = RDNSequence
+ LocalName = RDNSequence
+ RDNSequence = dquote *SafeUTF8Character dquote
+
+ The <RelativeDistinguishedName> rule describes the GSER encoding of
+ values of the RelativeDistinguishedName type that are not part of an
+ RDNSequence value. The <RelativeDistinguishedName> rule encodes an
+ RDN as a double quoted string containing the RDN as it would appear
+ in an LDAPDN character string. The character string is first derived
+ according to the <name-component> rule in Section 3 of [6], and then
+ any embedded double quote characters are escaped by being repeated.
+ This resulting string is output between double quotes.
+
+ RelativeDistinguishedName = dquote *SafeUTF8Character dquote
+
+ The <ORAddress> rule encodes an X.400 address as an IA5 character
+ string between double quotes. The character string is first derived
+ according to Section 4.1 of [2], and then any embedded double quotes
+ are escaped by being repeated. This resulting string is output
+ between double quotes.
+
+ ORAddress = dquote *SafeIA5Character dquote
+
+
+9. Security Considerations
+
+ GSER, and therefore the ABNF encodings described in this document, do
+
+
+
+Legg Expires 19 February 2002 [Page 9]
+\f
+INTERNET-DRAFT Common Elements of GSER Encodings August 19, 2002
+
+
+ not necessarily enable the exact octet encoding of values of the
+ TeletexString, VideotexString, GraphicString or GeneralString types
+ to be reconstructed, so a transformation from DER to GSER and back to
+ DER may not reproduce the original DER encoding. This has
+ consequences for the verification of digital signatures.
+
+
+10. Normative References
+
+ [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement
+ Levels", BCP 14, RFC 2119, March 1997.
+
+ [2] Kille, S., "MIXER (Mime Internet X.400 Enhanced Relay): Mapping
+ between X.400 and RFC 822/MIME", RFC 2156, January 1998.
+
+ [3] Crocker, D. and P. Overell, "Augmented BNF for Syntax
+ Specifications: ABNF", RFC 2234, November 1997.
+
+ [4] Wahl, M., Coulbeck, A., Howes, T. and S. Kille, "Lightweight
+ Directory Access Protocol (v3): Attribute Syntax Definitions",
+ RFC 2252, December 1997.
+
+ [5] Wahl, M., Kille, S. and T. Howes, "Lightweight Directory Access
+ Protocol (v3): UTF-8 String Representation of Distinguished
+ Names", RFC 2253, December 1997.
+
+ [6] Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC
+ 2279, January 1998.
+
+ [7] ITU-T Recommendation X.680 (1997) | ISO/IEC 8824-1:1998
+ Information Technology - Abstract Syntax Notation One (ASN.1):
+ Specification of basic notation
+
+
+11. Informative References
+
+ [8] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access
+ Protocol (v3)", RFC 2251, December 1997.
+
+ [9] Legg, S., "Generic String Encoding Rules for ASN.1 Types",
+ draft-legg-ldap-gser-xx.txt, a work in progress, August 2002.
+
+ [10] ITU-T Recommendation X.500 (1993) | ISO/IEC 9594-1:1994,
+ Information Technology - Open Systems Interconnection - The
+ Directory: Overview of concepts, models and services
+
+
+12. Copyright Notice
+
+
+
+Legg Expires 19 February 2002 [Page 10]
+\f
+INTERNET-DRAFT Common Elements of GSER Encodings August 19, 2002
+
+
+ Copyright (C) The Internet Society (2002). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+
+13. Author's Address
+
+ Steven Legg
+ Adacel Technologies Ltd.
+ 405-409 Ferntree Gully Road
+ Mount Waverley, Victoria 3149
+ AUSTRALIA
+
+ Phone: +61 3 9451 2107
+ Fax: +61 3 9541 2121
+ EMail: steven.legg@adacel.com.au
+
+
+
+
+
+
+
+
+
+
+
+
+
+Legg Expires 19 February 2002 [Page 11]
+\f
--- /dev/null
+
+
+
+
+
+
+INTERNET-DRAFT S. Legg
+draft-legg-ldap-gser-01.txt Adacel Technologies
+Intended Category: Standard Track August 19, 2002
+
+
+ Generic String Encoding Rules for ASN.1 Types
+
+ Copyright (C) The Internet Society (2002). All Rights Reserved.
+
+ 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 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".
+
+ 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.
+
+ Distribution of this document is unlimited. Comments should be sent
+ to the LDAPEXT working group mailing list <ietf-ldapext@netscape.com>
+ or to the author.
+
+ This Internet-Draft expires on 19 February 2002.
+
+
+1. Abstract
+
+ This document defines a set of Abstract Syntax Notation One (ASN.1)
+ encoding rules, called the Generic String Encoding Rules, that
+ produce a human readable text encoding for values of any given ASN.1
+ data type.
+
+
+
+
+
+
+
+Legg Expires 19 February 2002 [Page 1]
+\f
+INTERNET-DRAFT Generic String Encoding Rules August 19, 2002
+
+
+2. Table of Contents
+
+ 1. Abstract ...................................................... 1
+ 2. Table of Contents ............................................. 2
+ 3. Introduction .................................................. 2
+ 4. Conventions ................................................... 3
+ 5. Generic String Encoding Rules ................................. 3
+ 5.1 Type Referencing Notations ................................ 4
+ 5.2 Restricted Character String Types ......................... 4
+ 5.3 ChoiceOfStrings Types ..................................... 5
+ 5.4 Identifiers ............................................... 7
+ 5.5 BIT STRING ................................................ 7
+ 5.6 BOOLEAN ................................................... 8
+ 5.7 ENUMERATED ................................................ 8
+ 5.8 INTEGER ................................................... 8
+ 5.9 NULL ...................................................... 8
+ 5.10 OBJECT IDENTIFIER and RELATIVE-OID ....................... 9
+ 5.11 OCTET STRING ............................................. 9
+ 5.12 CHOICE ................................................... 9
+ 5.13 SEQUENCE and SET ......................................... 10
+ 5.14 SEQUENCE OF and SET OF ................................... 11
+ 5.15 CHARACTER STRING ......................................... 11
+ 5.16 EMBEDDED PDV ............................................. 11
+ 5.17 EXTERNAL ................................................. 11
+ 5.18 INSTANCE OF .............................................. 12
+ 5.19 REAL ..................................................... 12
+ 5.20 Variant Encodings ........................................ 12
+ 6. GSER Transfer Syntax .......................................... 13
+ 7. Security Considerations ....................................... 13
+ 8. Normative References .......................................... 13
+ 9. Informative References ........................................ 14
+ 10. Copyright Notice ............................................. 15
+ 11. Author's Address ............................................. 15
+
+
+3. Introduction
+
+ This document defines a set of ASN.1 [8] encoding rules, called the
+ Generic String Encoding Rules or GSER, that produce a human readable
+ UTF8 [6] character string encoding of ASN.1 values of any given
+ arbitrary ASN.1 type.
+
+ Note that "ASN.1 value" does not mean a BER [17] encoded value. The
+ ASN.1 value is an abstract concept that is independent of any
+ particular encoding. BER is just one possible encoding of an ASN.1
+ value.
+
+ GSER is based on ASN.1 value notation [8], with changes to
+
+
+
+Legg Expires 19 February 2002 [Page 2]
+\f
+INTERNET-DRAFT Generic String Encoding Rules August 19, 2002
+
+
+ accommodate the notation's use as a transfer syntax, and to support
+ well established ad-hoc string encodings for LDAP [13] directory data
+ types.
+
+ Though primarily intended for defining the LDAP-specific encoding of
+ new LDAP attribute syntaxes and assertion syntaxes, these encoding
+ rules could also be used in other domains where human readable
+ renderings of ASN.1 values would be useful.
+
+ Referencing the Generic String Encoding Rules (GSER) is sufficient to
+ define a human readable text encoding for values of a specific ASN.1
+ type, however other specifications may wish to provide a customized
+ ABNF [3] description, independent of the ASN.1, as a convenience for
+ the implementor (equivalent ABNF for the GSER encodings for ASN.1
+ types commonly occuring in LDAP syntaxes is provided in [14]). Such
+ a specification SHOULD state that if there is a discrepancy between
+ the customized ABNF and the GSER encoding defined by this document,
+ that the GSER encoding takes precedence.
+
+
+4. Conventions
+
+ Throughout this document "type" shall be taken to mean an ASN.1 type,
+ and "value" shall be taken to mean an ASN.1 value.
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in RFC 2119 [1].
+
+
+5. Generic String Encoding Rules
+
+ The GSER encoding of a value of any ASN.1 type is described by the
+ following ABNF [3]:
+
+ Value = BitStringValue /
+ BooleanValue /
+ CharacterStringValue /
+ ChoiceValue /
+ EmbeddedPDVValue /
+ EnumeratedValue /
+ ExternalValue /
+ GeneralizedTimeValue /
+ IntegerValue /
+ InstanceOfValue /
+ NullValue /
+ ObjectDescriptorValue /
+ ObjectIdentifierValue /
+
+
+
+Legg Expires 19 February 2002 [Page 3]
+\f
+INTERNET-DRAFT Generic String Encoding Rules August 19, 2002
+
+
+ OctetStringValue /
+ RealValue /
+ RelativeOIDValue /
+ SequenceOfValue /
+ SequenceValue /
+ SetOfValue /
+ SetValue /
+ StringValue /
+ UTCTimeValue /
+ VariantEncoding
+
+ The ABNF for each of the above rules is given in the following
+ sections.
+
+
+5.1 Type Referencing Notations
+
+ A value of a type with a defined type name is encoded according to
+ the type definition on the right hand side of the type assignment for
+ the type name.
+
+ A value of a type denoted by the use of a parameterized type with
+ actual parameters is encoded according to the parameterized type with
+ the DummyReferences [12] substituted with the actual parameters.
+
+ A value of a tagged or constrained type is encoded as a value of the
+ type without the tag or constraint, respectively. Tags do not appear
+ in the string encodings defined by this document. See [8] and [11]
+ for the details of ASN.1 constraint notation.
+
+ A value of an open type denoted by an ObjectClassFieldType (Clause 14
+ of [10]) is encoded according to the specific type of the value.
+
+ A value of a fixed type denoted by an ObjectClassFieldType is encoded
+ according to that fixed type.
+
+ A value of a selection type is encoded according to the type
+ referenced by the selection type.
+
+ A value of a type described by TypeFromObject notation (Clause 15 of
+ [10]) is encoded according to the denoted type.
+
+ A value of a type described by ValueSetFromObjects notation (Clause
+ 15 of [10]) is encoded according to the governing type.
+
+
+5.2 Restricted Character String Types
+
+
+
+
+Legg Expires 19 February 2002 [Page 4]
+\f
+INTERNET-DRAFT Generic String Encoding Rules August 19, 2002
+
+
+ The contents of a string value are encoded as a UTF8 character string
+ between double quotes, regardless of the ASN.1 string type.
+ Depending on the ASN.1 string type, and an application's internal
+ representation of that string type, a translation to or from the UTF8
+ character encoding may be required. NumericString, PrintableString,
+ IA5String, VisibleString (ISO646String) are compatible with UTF8 and
+ do not require any translation. BMPString (UCS-2) and
+ UniversalString (UCS-4) have a direct mapping to and from UTF8 [6].
+ For the remaining string types see [8]. Any embedded double quotes
+ in the resulting UTF8 character string are escaped by repeating the
+ double quote characters.
+
+ A value of the NumericString, PrintableString, TeletexString
+ (T61String), VideotexString, IA5String, GraphicString, VisibleString
+ (ISO646String), GeneralString, BMPString, UniversalString or
+ UTF8String type is encoded according to the <StringValue> rule.
+
+ StringValue = dquote *SafeUTF8Character dquote
+
+ dquote = %x22 ; " (double quote)
+
+ SafeUTF8Character = %x00-21 / %x23-7F / ; ASCII minus dquote
+ dquote dquote / ; escaped double quote
+ %xC0-DF %x80-BF / ; 2 byte UTF8 character
+ %xE0-EF 2(%x80-BF) / ; 3 byte UTF8 character
+ %xF0-F7 3(%x80-BF) / ; 4 byte UTF8 character
+ %xF8-FB 4(%x80-BF) / ; 5 byte UTF8 character
+ %xFC-FD 5(%x80-BF) ; 6 byte UTF8 character
+
+ A value of the GeneralizedTime type, UTCTime type or ObjectDescriptor
+ type is encoded as a string value. GeneralizedTime and UTCTime use
+ the VisibleString character set so the conversion to UTF8 is trivial.
+ ObjectDescriptor uses the GraphicString type.
+
+ GeneralizedTimeValue = StringValue
+ UTCTimeValue = StringValue
+ ObjectDescriptorValue = StringValue
+
+
+5.3 ChoiceOfStrings Types
+
+ It is not uncommon for ASN.1 specifications to define types that are
+ a CHOICE between two or more alternative ASN.1 string types, where
+ the particular alternative chosen carries no semantic significance
+ (DirectoryString [7] being a prime example). Such types are defined
+ to avoid having to use a complicated character encoding for all
+ values when most values could use a simpler string type, or to deal
+ with evolving requirements that compel the use of a broader character
+
+
+
+Legg Expires 19 February 2002 [Page 5]
+\f
+INTERNET-DRAFT Generic String Encoding Rules August 19, 2002
+
+
+ set while still maintaining backward compatibility.
+
+ GSER encodes values of all the ASN.1 string types as UTF8 character
+ strings so the alternative chosen in a purely syntactic CHOICE of
+ string types makes no material difference to the final encoding of
+ the string value.
+
+ While there are certain ASN.1 constructs that betray the semantic
+ significance of the alternatives within a CHOICE type, the absence of
+ those constructs does not necessarily mean a CHOICE type is purely
+ syntactic. Therefore, it is necessary for specifications to declare
+ the purely syntactic CHOICE types so that they may be more compactly
+ encoded (see Section 5.12). These declared CHOICE types are referred
+ to as ChoiceOfStrings types.
+
+ To be eligible to be declared a ChoiceOfStrings type an ASN.1 type
+ MUST satisfy the following conditions.
+
+ a) The type is a CHOICE type.
+
+ b) The component type of each alternative is one of the following
+ ASN.1 restricted string types: NumericString, PrintableString,
+ TeletexString (T61String), VideotexString, IA5String,
+ GraphicString, VisibleString (ISO646String), GeneralString,
+ BMPString, UniversalString or UTF8String.
+
+ c) All the alternatives are of different restricted string types,
+ i.e. no two alternatives have the same ASN.1 restricted string
+ type.
+
+ d) Either none of the alternatives has a constraint, or all of the
+ alternatives have exactly the same constraint.
+
+ Tagging on the alternative types is ignored.
+
+ Consider the ASN.1 parameterized type definition of DirectoryString.
+
+ DirectoryString { INTEGER : maxSize } ::= CHOICE {
+ teletexString TeletexString (SIZE (1..maxSize)),
+ printableString PrintableString (SIZE (1..maxSize)),
+ bmpString BMPString (SIZE (1..maxSize)),
+ universalString UniversalString (SIZE (1..maxSize)),
+ uTF8String UTF8String (SIZE (1..maxSize)) }
+
+ Any use of the DirectoryString parameterized type with an actual
+ parameter defines a ASN.1 type that satisfies the above conditions.
+ Recognising that the alternative within a DirectoryString carries no
+ semantic significance, this document declares (each and every use of)
+
+
+
+Legg Expires 19 February 2002 [Page 6]
+\f
+INTERNET-DRAFT Generic String Encoding Rules August 19, 2002
+
+
+ DirectoryString{} to be a ChoiceOfStrings type.
+
+ Other specifications MAY declare other types satisfying the above
+ conditions to be ChoiceOfStrings types. The declaration SHOULD be
+ made at the point where the ASN.1 type is defined, otherwise it
+ SHOULD be made at the point where it is introduced as, or in, an LDAP
+ attribute or assertion syntax.
+
+
+5.4 Identifiers
+
+ An <identifier> conforms to the definition of an identifier in ASN.1
+ notation (Clause 11.3 of [8]). It begins with a lowercase letter and
+ is followed by zero or more letters, digits, and hyphens. A hyphen
+ is not permitted to be the last character and a hyphen is not
+ permitted to be followed by another hyphen. The case of letters in
+ an identifier is always significant.
+
+ identifier = lowercase *alphanumeric *(hyphen 1*alphanumeric)
+ alphanumeric = uppercase / lowercase / decimal-digit
+ uppercase = %x41-5A ; "A" to "Z"
+ lowercase = %x61-7A ; "a" to "z"
+ decimal-digit = %x30-39 ; "0" to "9"
+ hyphen = "-"
+
+
+5.5 BIT STRING
+
+ A value of the BIT STRING type is encoded according to the
+ <BitStringValue> rule. If the definition of the BIT STRING type
+ includes a named bit list, the <bit-list> form of <BitStringValue>
+ rule MAY be used. If the number of bits in a BIT STRING value is a
+ multiple of four the <hstring> form of <BitStringValue> MAY be used.
+ The <bstring> form of <BitStringValue> is used otherwise.
+
+ BitStringValue = bstring / hstring / bit-list
+
+ The <bit-list> rule encodes the one bits in the bit string value as a
+ comma separated list of identifiers. Each <identifier> MUST be one
+ of those in the named bit list. An <identifier> MUST NOT appear more
+ than once in the same <bit-list>. The <bstring> rule encodes each
+ bit as the character "0" or "1" in order from the first bit to the
+ last bit. The <hstring> rule encodes each group of four bits as a
+ hexadecimal number where the first bit is the most significant. An
+ odd number of hexadecimal digits is permitted.
+
+ bit-list = "{" [ sp identifier
+ *( "," sp identifier ) ] sp "}"
+
+
+
+Legg Expires 19 February 2002 [Page 7]
+\f
+INTERNET-DRAFT Generic String Encoding Rules August 19, 2002
+
+
+ hstring = squote *hexadecimal-digit squote %x48 ; '...'H
+ hexadecimal-digit = %x30-39 / ; "0" to "9"
+ %x41-46 ; "A" to "F"
+
+ bstring = squote *binary-digit squote %x42 ; '...'B
+ binary-digit = "0" / "1"
+
+ sp = *%x20 ; zero, one or more space characters
+ squote = %x27 ; ' (single quote)
+
+
+5.6 BOOLEAN
+
+ A value of the BOOLEAN type is encoded according to the
+ <BooleanValue> rule.
+
+ BooleanValue = %x54.52.55.45 / ; "TRUE"
+ %x46.41.4C.53.45 ; "FALSE"
+
+
+5.7 ENUMERATED
+
+ A value of the ENUMERATED type is encoded according to the
+ <EnumeratedValue> rule. The <identifier> MUST be one of those in the
+ list of enumerations in the definition of the ENUMERATED type.
+
+ EnumeratedValue = identifier
+
+
+5.8 INTEGER
+
+ A value of the INTEGER type is encoded according to the
+ <IntegerValue> rule. If the definition of the INTEGER type includes
+ a named number list, the <identifier> form of <IntegerValue> MAY be
+ used, in which case the <identifier> MUST be one of those in the
+ named number list.
+
+ IntegerValue = "0" /
+ positive-number /
+ ("-" positive-number) /
+ identifier
+
+ positive-number = non-zero-digit *decimal-digit
+ non-zero-digit = %x31-39 ; "1" to "9"
+
+
+5.9 NULL
+
+
+
+
+Legg Expires 19 February 2002 [Page 8]
+\f
+INTERNET-DRAFT Generic String Encoding Rules August 19, 2002
+
+
+ A value of the NULL type is encoded according to the <NullValue>
+ rule.
+
+ NullValue = %x4E.55.4C.4C ; "NULL"
+
+
+5.10 OBJECT IDENTIFIER and RELATIVE-OID
+
+ A value of the OBJECT IDENTIFIER type is encoded according to the
+ <ObjectIdentifierValue> rule. The <ObjectIdentifierValue> rule
+ allows either a dotted decimal representation of the OBJECT
+ IDENTIFIER value or an object descriptor name, i.e. <descr>. The
+ <descr> rule is described in [4]. An object descriptor name is
+ potentially ambiguous and should be used with care.
+
+ ObjectIdentifierValue = numeric-oid / descr
+ numeric-oid = oid-component 1*( "." oid-component )
+ oid-component = "0" / positive-number
+
+ A value of the RELATIVE-OID [9] type is encoded according to the
+ <RelativeOIDValue> rule.
+
+ RelativeOIDValue = oid-component *( "." oid-component )
+
+
+5.11 OCTET STRING
+
+ A value of the OCTET STRING type is encoded according to the
+ <OctetStringValue> rule. The octets are encoded in order from the
+ first octet to the last octet. Each octet is encoded as a pair of
+ hexadecimal digits where the first digit corresponds to the four most
+ significant bits of the octet. If the hexadecimal string does not
+ have an even number of digits the four least significant bits in the
+ last octet are assumed to be zero.
+
+ OctetStringValue = hstring
+
+
+5.12 CHOICE
+
+ A value of a CHOICE type is encoded according to the <ChoiceValue>
+ rule. The <ChoiceOfStringsValue> encoding MAY be used if the
+ corresponding CHOICE type has been declared a ChoiceOfStrings type.
+ This document declares DirectoryString to be a ChoiceOfStrings type
+ (see Section 5.3). The <IdentifiedChoiceValue> form of <ChoiceValue>
+ is used otherwise.
+
+ ChoiceValue = IdentifiedChoiceValue /
+
+
+
+Legg Expires 19 February 2002 [Page 9]
+\f
+INTERNET-DRAFT Generic String Encoding Rules August 19, 2002
+
+
+ ChoiceOfStringsValue
+
+ IdentifiedChoiceValue = identifier ":" Value
+ ChoiceOfStringsValue = StringValue
+
+ For implementations that recognise the internal structure of the
+ DirectoryString CHOICE type (e.g. X.500 directories [15]), if the
+ character string between the quotes in a <StringValue> contains only
+ characters that are permitted in a PrintableString the
+ DirectoryString is assumed to use the printableString alternative,
+ otherwise it is assumed to use the uTF8String alternative. The
+ <IdentifiedChoiceValue> rule MAY be used for a value of type
+ DirectoryString to indicate a different alternative to the one that
+ would otherwise be assumed from the string contents. No matter what
+ alternative is chosen, the <Value> will still be a UTF8 encoded
+ character string, however it is a syntax error if the characters in
+ the UTF8 string cannot be represented in the string type of the
+ chosen alternative.
+
+ Implementations that don't care about the internal structure of a
+ DirectoryString value MUST be able to parse the
+ <IdentifiedChoiceValue> form for a DirectoryString value, though the
+ particular identifier found will be of no interest.
+
+5.13 SEQUENCE and SET
+
+ A value of a SEQUENCE type is encoded according to the
+ <SequenceValue> rule. The <ComponentList> rule encodes a comma
+ separated list of the particular component values present in the
+ SEQUENCE value, where each component value is preceded by the
+ corresponding identifier from the SEQUENCE type definition. The
+ components are encoded in the order of their definition in the
+ SEQUENCE type.
+
+ SequenceValue = ComponentList
+
+ ComponentList = "{" [ sp NamedValue *( "," sp NamedValue) ] sp "}"
+ NamedValue = identifier msp Value
+ msp = 1*%x20 ; one or more space characters
+
+ A value of a SET type is encoded according to the <SetValue> rule.
+ The components are encoded in the order of their definition in
+ the SET type (i.e. just like a SEQUENCE value).
+ This is a deliberate departure from ASN.1 value notation where
+ the components of a SET can be written in any order.
+
+ SetValue = ComponentList
+
+
+
+
+Legg Expires 19 February 2002 [Page 10]
+\f
+INTERNET-DRAFT Generic String Encoding Rules August 19, 2002
+
+
+ SEQUENCE and SET type definitions are sometimes extended by the
+ inclusion of additional component types, so an implementation SHOULD
+ be capable of skipping over any <NamedValue> encoding with an
+ identifier that is not recognised, on the assumption that the sender
+ is using a more recent definition of the SEQUENCE or SET type.
+
+
+5.14 SEQUENCE OF and SET OF
+
+ A value of a SEQUENCE OF type is encoded according to the
+ <SequenceOfValue> rule, as a comma separated list of the instances in
+ the value. Each instance is encoded according to the component type
+ of the SEQUENCE OF type.
+
+ SequenceOfValue = "{" [ sp Value *( "," sp Value) ] sp "}"
+
+ A value of a SET OF type is encoded according to the <SetOfValue>
+ rule, as a list of the instances in the value. Each instance is
+ encoded according to the component type of the SET OF type.
+
+ SetOfValue = "{" [ sp Value *( "," sp Value) ] sp "}"
+
+
+5.15 CHARACTER STRING
+
+ A value of the unrestricted CHARACTER STRING type is encoded
+ according to the corresponding SEQUENCE type defined in Clause 39.5
+ of [8] (see [14] for equivalent ABNF).
+
+ CharacterStringValue = SequenceValue
+
+
+5.16 EMBEDDED PDV
+
+ A value of the EMBEDDED PDV type is encoded according to the
+ corresponding SEQUENCE type defined in Clause 32.5 of [8] (see [14]
+ for equivalent ABNF).
+
+ EmbeddedPDVValue = SequenceValue
+
+
+5.17 EXTERNAL
+
+ A value of the EXTERNAL type is encoded according to the
+ corresponding SEQUENCE type defined in Clause 33.5 of [8] (see [14]
+ for equivalent ABNF).
+
+ ExternalValue = SequenceValue
+
+
+
+Legg Expires 19 February 2002 [Page 11]
+\f
+INTERNET-DRAFT Generic String Encoding Rules August 19, 2002
+
+
+5.18 INSTANCE OF
+
+ A value of the INSTANCE OF type is encoded according to the
+ corresponding SEQUENCE type defined in Annex C of [10].
+
+ InstanceOfValue = SequenceValue
+
+
+5.19 REAL
+
+ A value of the REAL type MUST be encoded as "0" if it is zero,
+ otherwise it is encoded as either the special value <PLUS-INFINITY>,
+ the special value <MINUS-INFINITY>, an optionally signed <realnumber>
+ (based on the extended value notation for REAL from [16]) or as a
+ value of the corresponding SEQUENCE type for REAL defined in Clause
+ 20.5 of [8] (see [14] for equivalent ABNF).
+
+ RealValue = "0" ; zero REAL value
+ / PLUS-INFINITY ; positive infinity
+ / MINUS-INFINITY ; negative infinity
+ / realnumber ; positive base 10 REAL value
+ / "-" realnumber ; negative base 10 REAL value
+ / SequenceValue ; non-zero REAL value, base 2 or 10
+ realnumber = mantissa exponent
+ mantissa = (positive-number [ "." *decimal-digit ])
+ / ( "0." *("0") positive-number )
+ exponent = "E" ( "0" / ([ "-" ] positive-number))
+
+ PLUS-INFINITY = %x50.4C.55.53.2D.49.4E.46.49.4E.49.54.59
+ ; "PLUS-INFINITY"
+ MINUS-INFINITY = %x4D.49.4E.55.53.2D.49.4E.46.49.4E.49.54.59
+ ; "MINUS-INFINITY"
+
+
+5.20 Variant Encodings
+
+ The values of some named complex ASN.1 types have special string
+ encodings. These special encodings are always used instead of the
+ encoding that would otherwise apply based on the ASN.1 type
+ definition.
+
+ VariantEncoding = RDNSequenceValue /
+ RelativeDistinguishedNameValue /
+ ORAddressValue
+
+ A value of the RDNSequence type, i.e. a distinguished name, is
+ encoded according to the <RDNSequenceValue> rule, as a quoted LDAPDN
+ character string. The character string is first derived according to
+
+
+
+Legg Expires 19 February 2002 [Page 12]
+\f
+INTERNET-DRAFT Generic String Encoding Rules August 19, 2002
+
+
+ the <distinguishedName> rule in Section 3 of [5], and then it is
+ encoded as if it were a UTF8String value, i.e. between double quotes
+ with any embedded double quotes escaped by being repeated.
+
+ RDNSequenceValue = StringValue
+
+ A RelativeDistinguishedName value that is not part of an RDNSequence
+ value is encoded according to the <RelativeDistinguishedNameValue>
+ rule as a quoted character string. The character string is first
+ derived according to the <name-component> rule in Section 3 of [5],
+ and then it is encoded as if it were a UTF8String value.
+
+ RelativeDistinguishedNameValue = StringValue
+
+ A value of the ORAddress type is encoded according to the
+ <ORAddressValue> rule as a quoted character string. The character
+ string is first derived according to the textual representation of
+ MTS.ORAddress from [2], and then it is encoded as if it were an
+ IA5String value.
+
+ ORAddressValue = StringValue
+
+
+6. GSER Transfer Syntax
+
+ The following OBJECT IDENTIFIER has been assigned to identify the
+ Generic String Encoding Rules:
+
+ { 1 2 36 79672281 0 0 }
+
+ This OBJECT IDENTIFIER would be used, for example, to describe the
+ transfer syntax for a GSER encoded data-value in an EXTERNAL or
+ EMBEDDED PDV value.
+
+
+7. Security Considerations
+
+ The Generic String Encoding Rules do not necessarily enable the exact
+ octet encoding of values of the TeletexString, VideotexString,
+ GraphicString or GeneralString types to be reconstructed, so a
+ transformation from DER to GSER and back to DER may not reproduce the
+ original DER encoding. This has consequences for the verification of
+ digital signatures.
+
+
+8. Normative References
+
+ [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement
+
+
+
+Legg Expires 19 February 2002 [Page 13]
+\f
+INTERNET-DRAFT Generic String Encoding Rules August 19, 2002
+
+
+ Levels", BCP 14, RFC 2119, March 1997.
+
+ [2] Kille, S., "MIXER (Mime Internet X.400 Enhanced Relay): Mapping
+ between X.400 and RFC 822/MIME", RFC 2156, January 1998.
+
+ [3] Crocker, D. and P. Overell, "Augmented BNF for Syntax
+ Specifications: ABNF", RFC 2234, November 1997.
+
+ [4] Wahl, M., Coulbeck, A., Howes, T. and S. Kille, "Lightweight
+ Directory Access Protocol (v3): Attribute Syntax Definitions",
+ RFC 2252, December 1997.
+
+ [5] Wahl, M., Kille S. and T. Howes. "Lightweight Directory Access
+ Protocol (v3): UTF-8 String Representation of Distinguished
+ Names", RFC 2253, December 1997.
+
+ [6] Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC
+ 2279, January 1998.
+
+ [7] ITU-T Recommendation X.520 (1993) | ISO/IEC 9594-6:1994,
+ Information Technology - Open Systems Interconnection - The
+ Directory: Selected attribute types
+
+ [8] ITU-T Recommendation X.680 (1997) | ISO/IEC 8824-1:1998
+ Information Technology - Abstract Syntax Notation One (ASN.1):
+ Specification of basic notation
+
+ [9] ITU-T Recommendation X.680 - Amendment 1 (06/99) | ISO/IEC
+ 8824-1:1998/Amd 1:2000 Relative object identifiers
+
+ [10] ITU-T Recommendation X.681 (1997) | ISO/IEC 8824-2:1998
+ Information Technology - Abstract Syntax Notation One (ASN.1):
+ Information object specification
+
+ [11] ITU-T Recommendation X.682 (1997) | ISO/IEC 8824-3:1998
+ Information Technology - Abstract Syntax Notation One (ASN.1):
+ Constraint specification
+
+ [12] ITU-T Recommendation X.683 (1997) | ISO/IEC 8824-4:1998
+ Information Technology - Abstract Syntax Notation One (ASN.1):
+ Parameterization of ASN.1 specifications
+
+
+9. Informative References
+
+ [13] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access
+ Protocol (v3)", RFC 2251, December 1997.
+
+
+
+
+Legg Expires 19 February 2002 [Page 14]
+\f
+INTERNET-DRAFT Generic String Encoding Rules August 19, 2002
+
+
+ [14] Legg, S., "Common Elements of GSER Encodings",
+ draft-legg-ldap-gser-abnf-xx.txt, a work in progress, August
+ 2002.
+
+ [15] ITU-T Recommendation X.500 (1993) | ISO/IEC 9594-1:1994,
+ Information Technology - Open Systems Interconnection - The
+ Directory: Overview of concepts, models and services
+
+ [16] ITU-T Recommendation X.680 - Corrigendum 3 (02/2001)
+
+ [17] ITU-T Recommendation X.690 (1997) | ISO/IEC 8825-1:1998
+ Information Technology - ASN.1 encoding rules: Specification of
+ Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and
+ Distinguished Encoding Rules (DER)
+
+
+10. Copyright Notice
+
+ Copyright (C) The Internet Society (2002). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+
+11. Author's Address
+
+ Steven Legg
+
+
+
+Legg Expires 19 February 2002 [Page 15]
+\f
+INTERNET-DRAFT Generic String Encoding Rules August 19, 2002
+
+
+ Adacel Technologies Ltd.
+ 405-409 Ferntree Gully Road
+ Mount Waverley, Victoria 3149
+ AUSTRALIA
+
+ Phone: +61 3 9451 2107
+ Fax: +61 3 9541 2121
+ EMail: steven.legg@adacel.com.au
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Legg Expires 19 February 2002 [Page 16]
+\f
--- /dev/null
+
+
+
+
+
+
+INTERNET-DRAFT S. Legg
+draft-legg-ldapext-component-matching-08.txt Adacel Technologies
+Intended Category: Standard Track April 19, 2002
+
+
+ LDAP & X.500 Component Matching Rules
+
+ Copyright (C) The Internet Society (2002). All Rights Reserved.
+
+ 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 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".
+
+ 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.
+
+ Distribution of this document is unlimited. Comments should be sent
+ to the LDAPEXT working group mailing list <ietf-ldapext@netscape.com>
+ or to the author.
+
+ This Internet-Draft expires on 19 October 2002.
+
+
+1. Abstract
+
+ The syntaxes of attributes in a Lightweight Directory Access Protocol
+ or X.500 directory range from simple data types, such as text string,
+ integer, or boolean, to complex structured data types, such as the
+ syntaxes of the directory schema operational attributes. The
+ matching rules defined for the complex syntaxes, if any, usually only
+ provide the most immediately useful matching capability. This
+ document defines generic matching rules that can match any user
+ selected component parts in an attribute value of any arbitrarily
+
+
+
+Legg Expires 19 October 2002 [Page 1]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ complex attribute syntax.
+
+
+2. Table of Contents
+
+ 1. Abstract ...................................................... 1
+ 2. Table of Contents ............................................. 2
+ 3. Introduction .................................................. 2
+ 4. Conventions ................................................... 4
+ 5. ComponentAssertion ............................................ 5
+ 5.1 Component Reference ....................................... 5
+ 5.1.1 Component Type Substitutions ......................... 7
+ 5.1.2 Referencing SET, SEQUENCE and CHOICE Components ...... 8
+ 5.1.3 Referencing SET OF and SEQUENCE OF Components ........ 9
+ 5.1.4 Referencing Components of Parameterized Types ........ 10
+ 5.1.5 Component Referencing Example ........................ 10
+ 5.1.6 Referencing Components of Open Types ................. 11
+ 5.1.6.1 Open Type Referencing Example ................... 12
+ 5.1.7 Referencing Contained Types .......................... 13
+ 5.1.7.1 Contained Type Referencing Example .............. 14
+ 5.2 Matching of Components .................................... 15
+ 5.2.1 Applicability of Existing Matching Rules ............. 16
+ 5.2.1.1 String Matching ................................. 16
+ 5.2.1.2 Telephone Number Matching ....................... 17
+ 5.2.1.3 Distinguished Name Matching ..................... 17
+ 5.2.2 Additional Useful Matching Rules ..................... 17
+ 5.2.2.1 The rdnMatch Matching Rule ...................... 18
+ 5.2.2.2 The presentMatch Matching Rule .................. 18
+ 5.2.3 Summary of Useful Matching Rules ..................... 19
+ 6. ComponentFilter ............................................... 21
+ 7. The componentFilterMatch Matching Rule ........................ 22
+ 8. Equality Matching of Complex Components ....................... 23
+ 8.1 The OpenAssertionType Syntax .............................. 24
+ 8.2 The allComponentsMatch Matching Rule ...................... 25
+ 8.3 Deriving Component Equality Matching Rules ................ 27
+ 8.4 The directoryComponentsMatch Matching Rule ................ 28
+ 9. Component Matching Examples ................................... 29
+ 10. Security Considerations ...................................... 36
+ 11. Acknowledgements ............................................. 36
+ 12. Normative References ......................................... 36
+ 13. Informative References ....................................... 37
+ 14. Intellectual Property Notice ................................. 38
+ 15. Copyright Notice ............................................. 38
+ 16. Author's Address ............................................. 39
+
+
+3. Introduction
+
+
+
+
+Legg Expires 19 October 2002 [Page 2]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ The structure or data type of data held in an attribute of an LDAP
+ [3] or X.500 [18] directory is described by the attribute's syntax.
+ Attribute syntaxes range from simple data types, such as text string,
+ integer, or boolean, to complex data types, for example, the syntaxes
+ of the directory schema operational attributes.
+
+ In X.500, the attribute syntaxes are explicitly described by ASN.1
+ [11] type definitions. ASN.1 type notation has a number of simple
+ data types (e.g. PrintableString, INTEGER, BOOLEAN), and combining
+ types (i.e. SET, SEQUENCE, SET OF, SEQUENCE OF, and CHOICE) for
+ constructing arbitrarily complex data types from simpler component
+ types. In LDAP, the attribute syntaxes are usually described by ABNF
+ [2] though there is an implied association between the LDAP attribute
+ syntaxes and the X.500 ASN.1 types. To a large extent, the data
+ types of attribute values in either an LDAP or X.500 directory are
+ described by ASN.1 types. This formal description can be exploited
+ to identify component parts of an attribute value for a variety of
+ purposes. This document addresses attribute value matching.
+
+ With any complex attribute syntax there is normally a requirement to
+ partially match an attribute value of that syntax by matching only
+ selected components of the value. Typically, matching rules specific
+ to the attribute syntax are defined to fill this need. These highly
+ specific matching rules usually only provide the most immediately
+ useful matching capability. Some complex attribute syntaxes don't
+ even have an equality matching rule let alone any additional matching
+ rules for partial matching. This document defines a generic way of
+ matching user selected components in an attribute value of any
+ arbitrarily complex attribute syntax, where that syntax is described
+ using ASN.1 type notation. All of the type notations defined in [11]
+ are supported.
+
+ Section 5 describes the ComponentAssertion, a testable assertion
+ about the value of a component of an attribute value of any complex
+ syntax.
+
+ Section 6 introduces the ComponentFilter assertion, which is an
+ expression of ComponentAssertions. The ComponentFilter enables more
+ powerful filter matching of components in an attribute value.
+
+ Section 7 defines the componentFilterMatch matching rule, which
+ enables a ComponentFilter to be evaluated against attribute values.
+
+ Section 8 defines matching rules for component-wise equality matching
+ of attribute values of any syntax described by an ASN.1 type
+ definition.
+
+ Examples showing the usage of componentFilterMatch are in Section 9.
+
+
+
+Legg Expires 19 October 2002 [Page 3]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ For a new attribute syntax, the Generic String Encoding Rules [7] and
+ the specifications in sections 5 to 8 of this document make it
+ possible to fully and precisely define, the LDAP-specific encoding,
+ the LDAP and X.500 binary encoding (and possibly other encodings in
+ the future, e.g. XML via XER), a suitable equality matching rule, and
+ a comprehensive collection of component matching capabilities, by
+ simply writing down an ASN.1 type definition for the syntax. These
+ implicit definitions are also automatically extended if the ASN.1
+ type is later extended. The algorithmic relationship between the
+ ASN.1 type definition, the various encodings and the component
+ matching behaviour makes directory server implementation support for
+ the component matching rules amenable to automatic code generation
+ from ASN.1 type definitions.
+
+ Schema designers have the choice of storing related items of data as
+ a single attribute value of a complex syntax in some entry, or as a
+ subordinate entry where the related data items are stored as separate
+ attribute values of simpler syntaxes. The inability to search
+ component parts of a complex syntax has been used as an argument for
+ favouring the subordinate entries approach. The component matching
+ rules provide the analogous matching capability on an attribute value
+ of a complex syntax that a search filter has on a subordinate entry.
+
+ Most LDAP syntaxes have corresponding ASN.1 type definitions, though
+ they are usually not reproduced or referenced alongside the formal
+ definition of the LDAP syntax. Syntaxes defined with only a
+ character string encoding, i.e. without an explicit or implied
+ corresponding ASN.1 type definition, cannot use the component
+ matching capabilities described in this document unless and until a
+ semantically equivalent ASN.1 type definition is defined for them.
+
+
+4. Conventions
+
+ Throughout this document "type" shall be taken to mean an ASN.1 type
+ unless explicitly qualified as an attribute type, and "value" shall
+ be taken to mean an ASN.1 value unless explicitly qualified as an
+ attribute value.
+
+ Note that "ASN.1 value" does not mean a BER [19] encoded value. The
+ ASN.1 value is an abstract concept that is independent of any
+ particular encoding. BER is just one possible encoding of an ASN.1
+ value. The component matching rules operate at the abstract level
+ without regard for the possible encodings of a value.
+
+ Attribute type and matching rule definitions in this document are
+ provided in both the X.500 [8] and LDAP [4] description formats. Note
+ that the LDAP descriptions have been rendered with additional
+
+
+
+Legg Expires 19 October 2002 [Page 4]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ white-space and line breaks for the sake of readability.
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in RFC 2119 [1].
+
+
+5. ComponentAssertion
+
+ A ComponentAssertion is an assertion about the presence, or values
+ of, components within an ASN.1 value, i.e. an instance of an ASN.1
+ type. The ASN.1 value is typically an attribute value, where the
+ ASN.1 type is the syntax of the attribute. However a
+ ComponentAssertion may also be applied to a component part of an
+ attribute value. The assertion evaluates to either TRUE, FALSE or
+ undefined for each tested ASN.1 value.
+
+ A ComponentAssertion is described by the following ASN.1 type
+ (assumed to be defined with "EXPLICIT TAGS" in force):
+
+ ComponentAssertion ::= SEQUENCE {
+ component ComponentReference,
+ useDefaultValues BOOLEAN DEFAULT TRUE,
+ rule MATCHING-RULE.&id,
+ value MATCHING-RULE.&AssertionType }
+
+ ComponentReference ::= UTF8String
+
+ MATCHING-RULE.&id equates to the OBJECT IDENTIFIER of a matching
+ rule. MATCHING-RULE.&AssertionType is an open type (formally known
+ as the ANY type).
+
+ The "component" field of a ComponentAssertion identifies which
+ component part of a value of some ASN.1 type is to be tested, the
+ "useDefaultValues" field indicates whether DEFAULT values are to be
+ substituted for absent component values, the "rule" field indicates
+ how the component is to be tested, and the "value" field is an
+ asserted ASN.1 value against which the component is tested. The
+ ASN.1 type of the asserted value is determined by the chosen rule.
+
+ The fields of a ComponentAssertion are described in detail in the
+ following sections.
+
+
+5.1 Component Reference
+
+ The component field in a ComponentAssertion is a UTF8 character
+ string [6] whose textual content is a component reference,
+
+
+
+Legg Expires 19 October 2002 [Page 5]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ identifying a component part of some ASN.1 type or value. A
+ component reference conforms to the following ABNF [2], which extends
+ the notation defined in Clause 14 of [11]:
+
+ component-reference = ComponentId *( "." ComponentId )
+ ComponentId = identifier /
+ from-beginning /
+ count /
+ from-end / ; extends Clause 14
+ content / ; extends Clause 14
+ select / ; extends Clause 14
+ all
+
+ identifier = lowercase *alphanumeric
+ *(hyphen 1*alphanumeric)
+ alphanumeric = uppercase / lowercase / decimal-digit
+ uppercase = %x41-5A ; "A" to "Z"
+ lowercase = %x61-7A ; "a" to "z"
+ hyphen = "-"
+
+ from-beginning = positive-number
+ count = "0"
+ from-end = "-" positive-number
+ content = %x63.6F.6E.74.65.6E.74 ; "content"
+ select = "(" Value *( "," Value ) ")"
+ all = "*"
+
+
+ positive-number = non-zero-digit *decimal-digit
+
+ decimal-digit = %x30-39 ; "0" to "9"
+ non-zero-digit = %x31-39 ; "1" to "9"
+
+ An <identifier> conforms to the definition of an identifier in ASN.1
+ notation (Clause 11.3 of [11]). It begins with a lowercase letter
+ and is followed by zero or more letters, digits, and hyphens. A
+ hyphen is not permitted to be the last character and a hyphen is not
+ permitted to be followed by another hyphen.
+
+ The <Value> rule is described in [7].
+
+ A component reference is a sequence of one or more ComponentIds where
+ each successive ComponentId identifies either an inner component at
+ the next level of nesting of an ASN.1 combining type, i.e. SET,
+ SEQUENCE, SET OF, SEQUENCE OF, or CHOICE, or a specific type within
+ an ASN.1 open type.
+
+ A component reference is always considered in the context of a
+
+
+
+Legg Expires 19 October 2002 [Page 6]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ particular complex ASN.1 type. When applied to the ASN.1 type the
+ component reference identifies a specific component type. When
+ applied to a value of the ASN.1 type a component reference identifies
+ zero, one or more component values of that component type. The
+ component values are potentially in a DEFAULT value if
+ useDefaultValues is TRUE. The specific component type identified by
+ the component reference determines what matching rules are capable of
+ being used to match the component values.
+
+ An empty string for a component reference, which would identify the
+ whole ASN.1 value, is NOT supported since assertions about a whole
+ value are already possible by the direct application of a matching
+ rule to an attribute value.
+
+ A valid component reference for a particular complex ASN.1 type is
+ constructed by starting with the outermost combining type and
+ repeatedly selecting one of the permissible forms of ComponentId to
+ identify successively deeper nested components. A component
+ reference MAY identify a component with a complex ASN.1 type, i.e. it
+ is NOT required that the component type identified by a component
+ reference be a simple ASN.1 type.
+
+
+5.1.1 Component Type Substitutions
+
+ ASN.1 type notation has a number of constructs for referencing other
+ defined types, and constructs that are irrelevant for matching
+ purposes. These constructs are not represented in a component
+ reference in any way and substitutions of the component type are
+ performed to eliminate them from further consideration. These
+ substitutions automatically occur prior to each ComponentId, whether
+ constructing or interpreting a component reference, but do not occur
+ after the last ComponentId, except as allowed by Section 5.2.
+
+ If the ASN.1 type is an ASN.1 type reference then the component type
+ is taken to be the actual definition on the right hand side of the
+ type assignment for the referenced type.
+
+ If the ASN.1 type is a tagged type then the component type is taken
+ to be the type without the tag.
+
+ If the ASN.1 type is a constrained type (see [11] and [14] for the
+ details of ASN.1 constraint notation) then the component type is
+ taken to be the type without the constraint.
+
+ If the ASN.1 type is an ObjectClassFieldType (Clause 14 of [13]) that
+ denotes a specific ASN.1 type (e.g. MATCHING-RULE.&id denotes the
+ OBJECT IDENTIFIER type) then the component type is taken to be the
+
+
+
+Legg Expires 19 October 2002 [Page 7]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ denoted type. Section 5.1.6 describes the case where the
+ ObjectClassFieldType denotes an open type.
+
+ If the ASN.1 type is a selection type other than one used in the list
+ of components for a SET or SEQUENCE type then the component type is
+ taken to be the selected alternative type from the named CHOICE.
+
+ If the ASN.1 type is a TypeFromObject (Clause 15 of [13]) then the
+ component type is taken to be the denoted type.
+
+ If the ASN.1 type is a ValueSetFromObjects (Clause 15 of [13]) then
+ the component type is taken to be the governing type of the denoted
+ values.
+
+
+5.1.2 Referencing SET, SEQUENCE and CHOICE Components
+
+ If the ASN.1 type is a SET or SEQUENCE type then the <identifier>
+ form of ComponentId MAY be used to identify the component type within
+ that SET or SEQUENCE having that identifier. If <identifier>
+ references an OPTIONAL component type and that component is not
+ present in a particular value then there are no corresponding
+ component values. If <identifier> references a DEFAULT component
+ type and useDefaultValues is TRUE (the default setting for
+ useDefaultValues) and that component is not present in a particular
+ value then the component value is taken to be the default value. If
+ <identifier> references a DEFAULT component type and useDefaultValues
+ is FALSE and that component is not present in a particular value then
+ there are no corresponding component values.
+
+ If the ASN.1 type is a CHOICE type then the <identifier> form of
+ ComponentId MAY be used to identify the alternative type within that
+ CHOICE having that identifier. If <identifier> references an
+ alternative other than the one used in a particular value then there
+ are no corresponding component values.
+
+ The COMPONENTS OF notation in Clause 24 of [11] augments the defined
+ list of components in a SET or SEQUENCE type by including all the
+ components of another defined SET or SEQUENCE type respectively.
+ These included components are referenced directly by identifier as
+ though they were defined in-line in the SET or SEQUENCE type
+ containing the COMPONENTS OF notation.
+
+ The SelectionType (Clause 29 of [11]), when used in the list of
+ components for a SET or SEQUENCE type, includes a single component
+ from a defined CHOICE type. This included component is referenced
+ directly by identifier as though it was defined in-line in the SET or
+ SEQUENCE type.
+
+
+
+Legg Expires 19 October 2002 [Page 8]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ The REAL type is treated as though it is the SEQUENCE type defined in
+ Clause 20.5 of [11].
+
+ The EMBEDDED PDV type is treated as though it is the SEQUENCE type
+ defined in Clause 32.5 of [11].
+
+ The EXTERNAL type is treated as though it is the SEQUENCE type
+ defined in Clause 33.5 of [11].
+
+ The unrestricted CHARACTER STRING type is treated as though it is the
+ SEQUENCE type defined in Clause 39.5 of [11].
+
+ The INSTANCE OF type is treated as though it is the SEQUENCE type
+ defined in Annex C of [13].
+
+ The <identifier> form MUST NOT be used on any other ASN.1 type.
+
+
+5.1.3 Referencing SET OF and SEQUENCE OF Components
+
+ If the ASN.1 type is a SET OF or SEQUENCE OF type then the
+ <from-beginning>, <from-end>, <count> and <all> forms of ComponentId
+ can be used.
+
+ The <from-beginning> form of ComponentId MAY be used to identify one
+ instance (i.e. value) of the component type of the SET OF or SEQUENCE
+ OF type (e.g. if Foo ::= SET OF Bar, then Bar is the component type),
+ where the instances are numbered from one upwards. If
+ <from-beginning> references a higher numbered instance than the last
+ instance in a particular value of the SET OF or SEQUENCE OF type then
+ there is no corresponding component value.
+
+ The <from-end> form of ComponentId MAY be used to identify one
+ instance of the component type of the SET OF or SEQUENCE OF type,
+ where "-1" is the last instance, "-2" is the second last instance,
+ and so on. If <from-end> references a lower numbered instance than
+ the first instance in a particular value of the SET OF or SEQUENCE OF
+ type then there is no corresponding component value.
+
+ The <count> form of ComponentId identifies a notional count of the
+ number of instances of the component type in a value of the SET OF or
+ SEQUENCE OF type. This count is not explicitly represented but for
+ matching purposes it has an assumed ASN.1 type of INTEGER (0..MAX).
+ A ComponentId of the <count> form MUST be the last ComponentId in a
+ component reference.
+
+ The <all> form of ComponentId MAY be used to simultaneously identify
+ all instances of the component type of the SET OF or SEQUENCE OF
+
+
+
+Legg Expires 19 October 2002 [Page 9]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ type. It is through the <all> form that a component reference can
+ identify more than one component value. However, if a particular
+ value of the SET OF or SEQUENCE OF type is an empty list there are no
+ corresponding component values.
+
+ Where multiple component values are identified, the remaining
+ ComponentIds in the component reference, if any, can identify zero,
+ one or more subcomponent values for each of the higher level
+ component values.
+
+ The corresponding ASN.1 type for the <from-beginning>, <from-end>,
+ and <all> forms of ComponentId is the component type of the SET OF or
+ SEQUENCE OF type.
+
+ The <from-beginning>, <count>, <from-end> and <all> forms MUST NOT be
+ used on ASN.1 types other than SET OF or SEQUENCE OF.
+
+
+5.1.4 Referencing Components of Parameterized Types
+
+ A component reference cannot be formed for a parameterized type
+ unless the type has been used with actual parameters, in which case
+ the type is treated as though the DummyReferences [15] have been
+ substituted with the actual parameters.
+
+
+5.1.5 Component Referencing Example
+
+ Consider the following ASN.1 type definitions.
+
+ ExampleType ::= SEQUENCE {
+ part1 [0] INTEGER,
+ part2 [1] ExampleSet,
+ part3 [2] SET OF OBJECT IDENTIFIER,
+ part4 [3] ExampleChoice }
+
+ ExampleSet ::= SET {
+ option PrintableString,
+ setting BOOLEAN }
+
+ ExampleChoice ::= CHOICE {
+ eeny-meeny BIT STRING,
+ miney-mo OCTET STRING }
+
+ Following are component references constructed with respect to the
+ type ExampleType.
+
+ The component reference "part1" identifies a component of a value of
+
+
+
+Legg Expires 19 October 2002 [Page 10]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ ExampleType having the ASN.1 tagged type [0] INTEGER.
+
+ The component reference "part2" identifies a component of a value of
+ ExampleType having the ASN.1 type of [1] ExampleSet
+
+ The component reference "part2.option" identifies a component of a
+ value of ExampleType having the ASN.1 type of PrintableString. A
+ ComponentAssertion could also be applied to a value of ASN.1 type
+ ExampleSet, in which case the component reference "option" would
+ identify the same kind of information.
+
+ The component reference "part3" identifies a component of a value of
+ ExampleType having the ASN.1 type of [2] SET OF OBJECT IDENTIFIER.
+
+ The component reference "part3.2" identifies the second instance of
+ the part3 SET OF. The instance has the ASN.1 type of OBJECT
+ IDENTIFIER.
+
+ The component reference "part3.0" identifies the count of the number
+ of instances in the part3 SET OF. The count has the corresponding
+ ASN.1 type of INTEGER (0..MAX).
+
+ The component reference "part3.*" identifies all the instances in the
+ part3 SET OF. Each instance has the ASN.1 type of OBJECT IDENTIFIER.
+
+ The component reference "part4" identifies a component of a value of
+ ExampleType having the ASN.1 type of [3] ExampleChoice.
+
+ The component reference "part4.miney-mo" identifies a component of a
+ value of ExampleType having the ASN.1 type of OCTET STRING.
+
+
+5.1.6 Referencing Components of Open Types
+
+ If a sequence of ComponentIds identifies an ObjectClassFieldType
+ denoting an open type (e.g. ATTRIBUTE.&Type denotes an open type)
+ then the ASN.1 type of the component varies. An open type is
+ typically constrained by some other component(s) in an outer
+ enclosing type, either formally through the use of a component
+ relation constraint [14], or informally in the accompanying text, so
+ the actual ASN.1 type of a value of the open type will generally be
+ known. The constraint will also limit the range of permissible
+ types. The <select> form of ComponentId MAY be used to identify one
+ of these permissible types in an open type. Subcomponents of that
+ type can then be identified with further ComponentIds.
+
+ The other components constraining the open type are termed the
+ referenced components (using the terminology in [14]). The <select>
+
+
+
+Legg Expires 19 October 2002 [Page 11]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ form contains a list of one or more values which take the place of
+ the value(s) of the referenced component(s) to uniquely identify one
+ of the permissable types of the open type.
+
+ Where the open type is constrained by a component relation
+ constraint, there is a <Value> in the <select> form for each of the
+ referenced components in the component relation constraint, appearing
+ in the same order. The ASN.1 type of each of these values is the
+ same as the ASN.1 type of the corresponding referenced component.
+ The type of a referenced component is potentially any ASN.1 type
+ however it is typically an OBJECT IDENTIFIER or INTEGER, which means
+ that the <Value> in the <select> form of ComponentId will nearly
+ always be an <ObjectIdentifierValue> or <IntegerValue> (see [7]).
+ Furthermore, component relation constraints typically have only one
+ referenced component.
+
+ Where the open type is not constrained by a component relation
+ constraint, the specification introducing the syntax containing the
+ open type SHOULD explicitly nominate the referenced components and
+ their order, so that the <select> form can be used.
+
+ If an instance of <select> contains a value other than the value of
+ the referenced component used in a particular value of the outer
+ enclosing type then there are no corresponding component values for
+ the open type.
+
+
+5.1.6.1 Open Type Referencing Example
+
+ The ASN.1 type AttributeTypeAndValue from [8] describes a single
+ attribute value of a nominated attribute type.
+
+ AttributeTypeAndValue ::= SEQUENCE {
+ type ATTRIBUTE.&id ({SupportedAttributes}),
+ value ATTRIBUTE.&Type ({SupportedAttributes}{@type}) }
+
+ ATTRIBUTE.&id denotes an OBJECT IDENTIFIER and
+ ({SupportedAttributes}) constrains the OBJECT IDENTIFIER to be a
+ supported attribute type.
+
+ ATTRIBUTE.&Type denotes an open type, in this case an attribute
+ value, and ({SupportedAttributes}{@type}) is a component relation
+ constraint that constrains the open type to be of the attribute
+ syntax for the attribute type. The component relation constraint
+ references only the "type" component, which has the ASN.1 type of
+ OBJECT IDENTIFIER, thus if the <select> form of ComponentId is used
+ to identify attribute values of specific attribute types it will
+ contain a single OBJECT IDENTIFIER value.
+
+
+
+Legg Expires 19 October 2002 [Page 12]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ The component reference "value" on AttributeTypeAndValue refers to
+ the open type.
+
+ One of the X.500 standard attributes is facsimileTelephoneNumber
+ [10], which is identified with the OBJECT IDENTIFIER 2.5.4.23, and is
+ defined to have the following syntax.
+
+ FacsimileTelephoneNumber ::= SEQUENCE {
+ telephoneNumber PrintableString(SIZE(1..ub-telephone-number)),
+ parameters G3FacsimileNonBasicParameters OPTIONAL }
+
+ The component reference "value.(2.5.4.23)" on AttributeTypeAndValue
+ specifies an attribute value with the FacsimileTelephoneNumber
+ syntax.
+
+ The component reference "value.(2.5.4.23).telephoneNumber" on
+ AttributeTypeAndValue identifies the telephoneNumber component of a
+ facsimileTelephoneNumber attribute value. The component reference
+ "value.(facsimileTelephoneNumber)" is equivalent to
+ "value.(2.5.4.23)".
+
+ If the AttributeTypeAndValue ASN.1 value contains an attribute type
+ other than facsimileTelephoneNumber then there are no corresponding
+ component values for the component references "value.(2.5.4.23)" and
+ "value.(2.5.4.23).telephoneNumber".
+
+
+5.1.7 Referencing Contained Types
+
+ Sometimes the contents of a BIT STRING or OCTET STRING value are
+ required to be the encodings of other ASN.1 values of specific ASN.1
+ types. For example, the extnValue component of the Extension type
+ component in the Certificate type [9] is an OCTET STRING that is
+ required to contain a DER encoding of a certificate extension value.
+ It is useful to be able to refer to the embedded encoded value and
+ its components. An embedded encoded value is here referred to as a
+ contained value and its associated type as the contained type.
+
+ If the ASN.1 type is a BIT STRING or OCTET STRING type containing
+ encodings of other ASN.1 values then the <content> form of
+ ComponentId MAY be used to identify the contained type.
+ Subcomponents of that type can then be identified with further
+ ComponentIds.
+
+ The contained type may be (effectively) an open type, constrained by
+ some other component in an outer enclosing type (e.g. in a
+ certificate Extension, extnValue is constrained by the chosen
+ extnId). In these cases the next ComponentId, if any, MUST be of the
+
+
+
+Legg Expires 19 October 2002 [Page 13]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ <select> form.
+
+ For the purpose of building component references, the content of the
+ extnValue OCTET STRING in the Extension type is assumed to be an open
+ type having a notional component relation constraint with the extnId
+ component as the single referenced component, i.e.
+
+ EXTENSION.&ExtnType ({ExtensionSet}{@extnId})
+
+ The data-value component of the associated types for the EXTERNAL,
+ EMBEDDED PDV and CHARACTER STRING types is an OCTET STRING containing
+ the encoding of a data value described by the identification
+ component. For the purpose of building component references, the
+ content of the data-value OCTET STRING in these types is assumed to
+ be an open type having a notional component relation constraint with
+ the identification component as the single referenced component.
+
+
+5.1.7.1 Contained Type Referencing Example
+
+ The Extension ASN.1 type from [9] describes a single certificate
+ extension value of a nominated extension type.
+
+ Extension ::= SEQUENCE {
+ extnId EXTENSION.&id ({ExtensionSet}),
+ critical BOOLEAN DEFAULT FALSE,
+ extnValue OCTET STRING
+ -- contains a DER encoding of a value of type &ExtnType
+ -- for the extension object identified by extnId -- }
+
+ EXTENSION.&id denotes an OBJECT IDENTIFIER and ({ExtensionSet})
+ constrains the OBJECT IDENTIFIER to be the identifier of a supported
+ certificate extension.
+
+ The component reference "extnValue" on Extension refers to a
+ component type of OCTET STRING. The corresponding component values
+ will be OCTET STRING values. The component reference
+ "extnValue.content" on Extension refers to the type of the contained
+ type, which in this case is an open type.
+
+ One of the X.509 [X.509] standard extensions is basicConstraints,
+ which is identified with the OBJECT IDENTIFIER 2.5.29.19 and is
+ defined to have the following syntax.
+
+ BasicConstraintsSyntax ::= SEQUENCE {
+ cA BOOLEAN DEFAULT FALSE,
+ pathLenConstraint INTEGER (0..MAX) OPTIONAL }
+
+
+
+
+Legg Expires 19 October 2002 [Page 14]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ The component reference "extnValue.content.(2.5.29.19)" on Extension
+ specifies a BasicConstraintsSyntax extension value and the component
+ reference "extnValue.content.(2.5.29.19).cA" identifies the cA
+ component of a BasicConstraintsSyntax extension value.
+
+
+5.2 Matching of Components
+
+ The rule in a ComponentAssertion specifies how the zero, one or more
+ component values identified by the component reference are tested by
+ the assertion. Attribute matching rules are used to specify the
+ semantics of the test.
+
+ Each matching rule has a notional set of attribute syntaxes
+ (typically one), defined as ASN.1 types, to which it may be applied.
+ When used in a ComponentAssertion these matching rules apply to the
+ same ASN.1 types, only in this context the corresponding ASN.1 values
+ are not complete attribute values.
+
+ Note that the referenced component type may be a tagged and/or
+ constrained version of the expected attribute syntax (e.g. [0]
+ INTEGER, whereas integerMatch would expect simply INTEGER), or an
+ open type. Additional type substitutions of the kind described in
+ Section 5.1.1 are performed as required to reduce the component type
+ to the same type as the attribute syntax expected by the matching
+ rule. If an open type is encountered the actual ASN.1 type of the
+ component value is substituted before continuing.
+
+ If a matching rule applies to more than one attribute syntax (e.g.
+ objectIdentifierFirstComponentMatch [10]) then the minimum number of
+ substitutions required to conform to any one of those syntaxes are
+ performed. If a matching rule can apply to any attribute syntax
+ (e.g. the allComponentsMatch rule defined in Section 8.2) then the
+ referenced component type is used as is, with no additional
+ substitutions.
+
+ The value in a ComponentAssertion will be of the assertion syntax
+ (i.e. ASN.1 type) required by the chosen matching rule. Note that
+ the assertion syntax of a matching rule is not necessarily the same
+ as the attribute syntax(es) to which the rule may be applied.
+
+ Some matching rules do not have a fixed assertion syntax (e.g.
+ allComponentsMatch). The required assertion syntax is determined in
+ each instance of use by the syntax of the attribute type to which the
+ matching rule is applied. For these rules the ASN.1 type of the
+ referenced component is used in place of an attribute syntax to
+ decide the required assertion syntax.
+
+
+
+
+Legg Expires 19 October 2002 [Page 15]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ The ComponentAssertion is undefined if:
+
+ a) the matching rule in the ComponentAssertion is not known to the
+ evaluating procedure,
+
+ b) if no part of the component reference identifies an open type and
+ the matching rule is not applicable to the referenced component
+ type, even with the additional type substitutions,
+
+ c) the value in the ComponentAssertion does not conform to the
+ assertion syntax defined for the matching rule,
+
+ d) an open type in the tested value cannot be decoded, or
+
+ e) the implementation does not support the particular combination of
+ component reference and matching rule.
+
+ If the ComponentAssertion is not undefined then the
+ ComponentAssertion evaluates to TRUE if there is at least one
+ component value for which the matching rule applied to that component
+ value returns TRUE, and evaluates to FALSE otherwise (which includes
+ the case where there are no component values).
+
+ If some part of the component reference identifies an open type and
+ the matching rule is not applicable to the referenced component type
+ the ComponentAssertion evaluates to FALSE.
+
+
+5.2.1 Applicability of Existing Matching Rules
+
+5.2.1.1 String Matching
+
+ ASN.1 has a number of built in restricted character string types with
+ different character sets and/or different character encodings. A
+ directory user generally has little interest in the particular
+ character set or encoding used to represent a character string
+ component value, and some directory server implementations make no
+ distinction between the different string types in their internal
+ representation of values. So rather than define string matching
+ rules for each of the restricted character string types, the existing
+ case ignore and case exact string matching rules are extended to
+ apply to component values of any of the restricted character string
+ types and any ChoiceOfStrings type [7], in addition to component
+ values of the DirectoryString type. This extension is only for the
+ purposes of component matching described in this document.
+
+ The relevant string matching rules are: caseIgnoreMatch,
+ caseIgnoreOrderingMatch, caseIgnoreSubstringsMatch, caseExactMatch,
+
+
+
+Legg Expires 19 October 2002 [Page 16]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ caseExactOrderingMatch and caseExactSubstringsMatch. The relevant
+ restricted character string types are: NumericString,
+ PrintableString, VisibleString, IA5String, UTF8String, BMPString,
+ UniversalString, TeletexString, VideotexString, GraphicString and
+ GeneralString. A ChoiceOfStrings type is a purely syntactic CHOICE
+ of these ASN.1 string types. Note that [7] declares each and every
+ use of the DirectoryString{} parameterized type to be a
+ ChoiceOfStrings type.
+
+ The assertion syntax of the string matching rules is still
+ DirectoryString regardless of the string syntax of the component
+ being matched. Thus an implementation will be called upon to compare
+ a DirectoryString value to a value of one of the restricted character
+ string types, or a ChoiceOfStrings type. As is the case when
+ comparing two DirectoryStrings where the chosen alternatives are of
+ different string types, the comparison proceeds so long as the
+ corresponding characters are representable in both character sets.
+ Otherwise matching returns FALSE.
+
+
+5.2.1.2 Telephone Number Matching
+
+ Early editions of X.520 [10] gave the syntax of the telephoneNumber
+ attribute as a constrained PrintableString. The fourth edition of
+ X.520 equates the ASN.1 type name TelephoneNumber to the constrained
+ PrintableString and uses TelephoneNumber as the attribute and
+ assertion syntax. For the purposes of component matching,
+ telephoneNumberMatch and telephoneNumberSubstringsMatch are permitted
+ to be applied to any PrintableString value, as well as to
+ TelephoneNumber values.
+
+
+5.2.1.3 Distinguished Name Matching
+
+ The DistinguishedName type is defined by assignment to be the same as
+ the RDNSequence type, however RDNSequence is sometimes directly used
+ in other type definitions. For the purposes of component matching,
+ distinguishedNameMatch is also permitted to be applied to values of
+ the RDNSequence type.
+
+
+5.2.2 Additional Useful Matching Rules
+
+ This section defines additional matching rules that may prove useful
+ in ComponentAssertions. These rules MAY also be used in
+ extensibleMatch search filters [3].
+
+
+
+
+
+Legg Expires 19 October 2002 [Page 17]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+5.2.2.1 The rdnMatch Matching Rule
+
+ The distinguishedNameMatch matching rule can match whole
+ distinguished names but it is sometimes useful to be able to match
+ specific RDNs in a DN without regard for the other RDNs in the DN.
+ The rdnMatch matching rule allows component RDNs of a DN to be
+ tested.
+
+ The LDAP-style definitions for rdnMatch and its assertion syntax are:
+
+ ( 1.2.36.79672281.1.13.3 NAME 'rdnMatch'
+ SYNTAX 1.2.36.79672281.1.5.0 )
+
+ ( 1.2.36.79672281.1.5.0 DESC 'RDN' )
+
+ The LDAP-specific encoding for a value of the RDN syntax is given by
+ the <RelativeDistinguishedNameValue> rule in [7].
+
+ The X.500-style definition for rdnMatch is:
+
+ rdnMatch MATCHING-RULE ::= {
+ SYNTAX RelativeDistinguishedName
+ ID { 1 2 36 79672281 1 13 3 } }
+
+ The rdnMatch rule evaluates to true if the component value and
+ assertion value are the same RDN, using the same RDN comparison
+ method as distinguishedNameMatch.
+
+ When using rdnMatch to match components of DNs it is important to
+ note that the LDAP-specific encoding of a DN [5] reverses the order
+ of the RDNs. So for the DN represented in LDAP as "cn=Steven
+ Legg,o=Adacel,c=AU", the RDN "cn=Steven Legg" corresponds to the
+ component reference "3", or alternatively, "-1".
+
+
+5.2.2.2 The presentMatch Matching Rule
+
+ At times it would be useful to test not if a specific value of a
+ particular component is present, but whether any value of a
+ particular component is present. The presentMatch matching rule
+ allows the presence of a particular component value to be tested.
+
+ The LDAP-style definitions for presentMatch and its assertion syntax
+ are:
+
+ ( 1.2.36.79672281.1.13.5 NAME 'presentMatch'
+ SYNTAX 1.2.36.79672281.1.5.1 )
+
+
+
+
+Legg Expires 19 October 2002 [Page 18]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ ( 1.2.36.79672281.1.5.1 DESC 'NULL' )
+
+ The LDAP-specific encoding for a value of the NULL syntax is given by
+ the <NullValue> rule in [7].
+
+ The X.500-style definition for presentMatch is:
+
+ presentMatch MATCHING-RULE ::= {
+ SYNTAX NULL
+ ID { 1 2 36 79672281 1 13 5 } }
+
+ When used in a extensible match filter item, presentMatch behaves
+ like the "present" case of a regular search filter. In a
+ ComponentAssertion, presentMatch evaluates to TRUE if and only if the
+ component reference identifies one or more component values,
+ regardless of the actual component value contents. Note that if
+ useDefaultValues is TRUE then the identified component values may be
+ (part of) a DEFAULT value.
+
+ The notional count referenced by the <count> form of ComponentId is
+ taken to be present if the SET OF value is present, and absent
+ otherwise. Note that in ASN.1 notation an absent SET OF value is
+ distinctly different from a SET OF value that is present but empty.
+ It is up to the specification using the ASN.1 notation to decide
+ whether the distinction matters. Often an empty SET OF component and
+ an absent SET OF component are treated as semantically equivalent.
+ If a SET OF value is present, but empty, a presentMatch on the SET OF
+ component SHALL return TRUE and the notional count SHALL be regarded
+ as present and equal to zero.
+
+
+5.2.3 Summary of Useful Matching Rules
+
+ The following is a non-exhaustive list of useful matching rules and
+ the ASN.1 types to which they can be applied, taking account of all
+ the extensions described in Section 5.2.1, and the new matching rules
+ defined in Section 5.2.2.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Legg Expires 19 October 2002 [Page 19]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ +================================+==============================+
+ | Matching Rule | ASN.1 Type |
+ +================================+==============================+
+ | bitStringMatch | BIT STRING |
+ +--------------------------------+------------------------------+
+ | booleanMatch | BOOLEAN |
+ +--------------------------------+------------------------------+
+ | caseIgnoreMatch | NumericString |
+ | caseIgnoreOrderingMatch | PrintableString |
+ | caseIgnoreSubstringsMatch | VisibleString (ISO646String) |
+ | caseExactMatch | IA5String |
+ | caseExactOrderingMatch | UTF8String |
+ | caseExactSubstringsMatch | BMPString (UCS-2, UNICODE) |
+ | | UniversalString (UCS-4) |
+ | | TeletexString (T61String) |
+ | | VideotexString |
+ | | GraphicString |
+ | | GeneralString |
+ | | any ChoiceOfStrings type |
+ +--------------------------------+------------------------------+
+ | caseIgnoreIA5Match | IA5String |
+ | caseExactIA5Match | |
+ +--------------------------------+------------------------------+
+ | distinguishedNameMatch | DistinguishedName |
+ | | RDNSequence |
+ +--------------------------------+------------------------------+
+ | generalizedTimeMatch | GeneralizedTime |
+ | generalizedTimeOrderingMatch | |
+ +--------------------------------+------------------------------+
+ | integerMatch | INTEGER |
+ | integerOrderingMatch | |
+ +--------------------------------+------------------------------+
+ | numericStringMatch | NumericString |
+ | numericStringOrderingMatch | |
+ | numericStringSubstringsMatch | |
+ +--------------------------------+------------------------------+
+ | objectIdentifierMatch | OBJECT IDENTIFIER |
+ +--------------------------------+------------------------------+
+ | octetStringMatch | OCTET STRING |
+ | octetStringOrderingMatch | |
+ | octetStringSubstringsMatch | |
+ +--------------------------------+------------------------------+
+ | presentMatch | any ASN.1 type |
+ +--------------------------------+------------------------------+
+ | rdnMatch | RelativeDistinguishedName |
+ +--------------------------------+------------------------------+
+ | telephoneNumberMatch | PrintableString |
+ | telephoneNumberSubstringsMatch | TelephoneNumber |
+
+
+
+Legg Expires 19 October 2002 [Page 20]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ +--------------------------------+------------------------------+
+ | uTCTimeMatch | UTCTime |
+ | uTCTimeOrderingMatch | |
+ +--------------------------------+------------------------------+
+
+ Note that the allComponentsMatch matching rule defined in Section 8.2
+ can be used for equality matching of values of the ENUMERATED, NULL,
+ REAL and RELATIVE-OID ASN.1 types, among other things.
+
+
+6. ComponentFilter
+
+ The ComponentAssertion allows the value(s) of any one component type
+ in a complex ASN.1 type to be matched, but there is often a desire to
+ match the values of more than one component type. A ComponentFilter
+ is an assertion about the presence, or values of, multiple components
+ within an ASN.1 value.
+
+ The ComponentFilter assertion, an expression of ComponentAssertions,
+ evaluates to either TRUE, FALSE or undefined for each tested ASN.1
+ value.
+
+ A ComponentFilter is described by the following ASN.1 type (assumed
+ to be defined with "EXPLICIT TAGS" in force):
+
+ ComponentFilter ::= CHOICE {
+ item [0] ComponentAssertion,
+ and [1] SEQUENCE OF ComponentFilter,
+ or [2] SEQUENCE OF ComponentFilter,
+ not [3] ComponentFilter }
+
+ Note: despite the use of SEQUENCE OF instead of SET OF for the "and"
+ and "or" alternatives in ComponentFilter, the order of the component
+ filters is not significant.
+
+ A ComponentFilter that is a ComponentAssertion evaluates to TRUE if
+ the ComponentAssertion is TRUE, evaluates to FALSE if the
+ ComponentAssertion is FALSE, and evaluates to undefined otherwise.
+
+ The "and" of a sequence of component filters evaluates to TRUE if the
+ sequence is empty or if each component filter evaluates to TRUE,
+ evaluates to FALSE if at least one component filter is FALSE, and
+ evaluates to undefined otherwise.
+
+ The "or" of a sequence of component filters evaluates to FALSE if the
+ sequence is empty or if each component filter evaluates to FALSE,
+ evaluates to TRUE if at least one component filter is TRUE, and
+ evaluates to undefined otherwise.
+
+
+
+Legg Expires 19 October 2002 [Page 21]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ The "not" of a component filter evaluates to TRUE if the component
+ filter is FALSE, evaluates to FALSE if the component filter is TRUE,
+ and evaluates to undefined otherwise.
+
+
+7. The componentFilterMatch Matching Rule
+
+ The componentFilterMatch matching rule allows a ComponentFilter to be
+ applied to an attribute value. The result of the matching rule is
+ the result of applying the ComponentFilter to the attribute value.
+
+ The LDAP-style definitions for componentFilterMatch and its assertion
+ syntax are:
+
+ ( 1.2.36.79672281.1.13.2 NAME 'componentFilterMatch'
+ SYNTAX 1.2.36.79672281.1.5.2 )
+
+ ( 1.2.36.79672281.1.5.2 DESC 'ComponentFilter' )
+
+ The LDAP-specific encoding for the ComponentFilter assertion syntax
+ is specified by the Generic String Encoding Rules in [7].
+
+ As a convenience to implementors, an equivalent ABNF description of
+ the GSER encoding for ComponentFilter is provided here. In the event
+ that there is a discrepancy between this ABNF and the encoding
+ determined by [7], [7] is to be taken as definitive. The GSER
+ encoding of a ComponentFilter is described by the following
+ equivalent ABNF:
+
+ ComponentFilter = filter-item /
+ and-filter /
+ or-filter /
+ not-filter
+
+ filter-item = item-chosen ComponentAssertion
+ and-filter = and-chosen SequenceOfComponentFilter
+ or-filter = or-chosen SequenceOfComponentFilter
+ not-filter = not-chosen ComponentFilter
+
+ item-chosen = %x69.74.65.6D.3A ; "item:"
+ and-chosen = %x61.6E.64.3A ; "and:"
+ or-chosen = %x6F.72.3A ; "or:"
+ not-chosen = %x6E.6F.74.3A ; "not:"
+
+ SequenceOfComponentFilter = "{" [ sp ComponentFilter
+ *( "," sp ComponentFilter) ] sp "}"
+
+ ComponentAssertion = "{" sp component ","
+
+
+
+Legg Expires 19 October 2002 [Page 22]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ [ sp useDefaultValues "," ]
+ sp rule ","
+ sp assertion-value sp "}"
+ component = component-label msp
+ dquote component-reference dquote
+ useDefaultValues = use-defaults-label msp BooleanValue
+ rule = rule-label msp ObjectIdentifierValue
+ assertion-value = value-label msp Value
+
+ component-label = %x63.6F.6D.70.6F.6E.65.6E.74 ; "component"
+ use-defaults-label = %x75.73.65.44.65.66.61.75.6C.74.56.61.6C.75
+ %x65.73 ; "useDefaultValues"
+ rule-label = %x72.75.6C.65 ; "rule"
+ value-label = %x76.61.6C.75.65 ; "value"
+
+ sp = *%x20 ; zero, one or more space characters
+ msp = 1*%x20 ; one or more space characters
+ dquote = %x22 ; " (double quote)
+
+ The ABNF for <Value>, <ObjectIdentifierValue> and <BooleanValue> is
+ defined in [7].
+
+ The ABNF descriptions of LDAP-specific encodings for attribute
+ syntaxes typically do not clearly or consistently delineate the
+ component parts of an attribute value. A regular and uniform
+ character string encoding for arbitrary component data types is
+ needed to encode the assertion value in a ComponentAssertion. The
+ <Value> rule from [7] provides a human readable text encoding for a
+ component value of any arbitrary ASN.1 type.
+
+ The X.500-style definition [8] for componentFilterMatch is:
+
+ componentFilterMatch MATCHING-RULE ::= {
+ SYNTAX ComponentFilter
+ ID { 1 2 36 79672281 1 13 2 } }
+
+ A ComponentAssertion can potentially use any matching rule, including
+ componentFilterMatch, so componentFilterMatch MAY be nested. The
+ component references in a nested componentFilterMatch are relative to
+ the component corresponding to the containing ComponentAssertion. In
+ Section 9, an example search on the seeAlso attribute shows this
+ usage.
+
+
+8. Equality Matching of Complex Components
+
+ It is possible to test if an attribute value of a complex ASN.1
+ syntax is the same as some purported (i.e. assertion) value by using
+
+
+
+Legg Expires 19 October 2002 [Page 23]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ a complicated ComponentFilter that tests if corresponding components
+ are the same. However, it would be more convenient to be able to
+ present a whole assertion value to a matching rule that could do the
+ component-wise comparison of an attribute value with the assertion
+ value for any arbitrary attribute syntax. Similarly, the ability to
+ do a straightforward equality comparison of a component value that is
+ itself of a complex ASN.1 type would also be convenient.
+
+ It would be difficult to define a single matching rule that
+ simultaneously satisfies all notions of what the equality matching
+ semantics should be. For example, in some instances a case sensitive
+ comparison of string components may be preferable to a case
+ insensitive comparison. Therefore a basic equality matching rule,
+ allComponentsMatch, is defined in Section 8.2, and the means to
+ derive new matching rules from it with slightly different equality
+ matching semantics are described in Section 8.3.
+
+ The directoryComponentsMatch defined in Section 8.4 is a derivation
+ of allComponentsMatch that suits typical uses of the directory.
+ Other specifications are free to derive new rules from
+ allComponentsMatch or directoryComponentsMatch, that suit their usage
+ of the directory.
+
+ The allComponentsMatch rule, the directoryComponentsMatch rule and
+ any matching rules derived from them are collectively called
+ component equality matching rules.
+
+
+8.1 The OpenAssertionType Syntax
+
+ The component equality matching rules have a variable assertion
+ syntax. In X.500 this is indicated by omitting the optional SYNTAX
+ field in the MATCHING-RULE information object. The assertion syntax
+ then defaults to the target attribute's syntax in actual usage,
+ unless the description of the matching rule says otherwise. The
+ SYNTAX field in the LDAP-specific encoding of a
+ MatchingRuleDescription is mandatory, so the OpenAssertionType syntax
+ is defined to fill the same role. That is, the OpenAssertionType
+ syntax is semantically equivalent to an omitted SYNTAX field in an
+ X.500 MATCHING-RULE information object. OpenAssertionType MUST NOT
+ be used as the attribute syntax in an attribute type definition.
+
+ Unless explicitly varied by the description of a particular matching
+ rule, if an OpenAssertionType assertion value appears in a
+ ComponentAssertion its LDAP-specific encoding is described by the
+ <Value> rule in [7], otherwise its LDAP-specific encoding is the
+ encoding defined for the syntax of the attribute type to which the
+ matching rule with the OpenAssertionType assertion syntax is applied.
+
+
+
+Legg Expires 19 October 2002 [Page 24]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ The LDAP definition for the OpenAssertionType syntax is:
+
+ ( 1.2.36.79672281.1.5.3 DESC 'OpenAssertionType' )
+
+
+8.2 The allComponentsMatch Matching Rule
+
+ The LDAP-style definition for allComponentsMatch is:
+
+ ( 1.2.36.79672281.1.13.6 NAME 'allComponentsMatch'
+ SYNTAX 1.2.36.79672281.1.5.3 )
+
+ The X.500-style definition for allComponentsMatch is:
+
+ allComponentsMatch MATCHING-RULE ::= {
+ ID { 1 2 36 79672281 1 13 6 } }
+
+ When allComponentsMatch is used in a ComponentAssertion the assertion
+ syntax is the same as the ASN.1 type of the identified component.
+ Otherwise, the assertion syntax of allComponentsMatch is the same as
+ the attribute syntax of the attribute to which the matching rule is
+ applied.
+
+ Broadly speaking, this matching rule evaluates to true if and only if
+ corresponding components of the assertion value and the attribute or
+ component value are the same.
+
+ In detail, equality is determined by the following cases applied
+ recursively.
+
+ a) Two values of a SET or SEQUENCE type are the same if and only if,
+ for each component type, the corresponding component values are
+ either,
+
+ 1) both absent,
+
+ 2) both present and the same, or
+
+ 3) absent or the same as the DEFAULT value for the component, if a
+ DEFAULT value is defined.
+
+ Values of an EMBEDDED PDV, EXTERNAL, unrestricted CHARACTER
+ STRING, or INSTANCE OF type are compared according to their
+ respective SEQUENCE type (see Section 5.1.2).
+
+ b) Two values of a SEQUENCE OF type are the same if and only if, the
+ values have the same number of (possibly duplicated) instances and
+ corresponding instances are the same.
+
+
+
+Legg Expires 19 October 2002 [Page 25]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ c) Two values of a SET OF type are the same if and only if, the
+ values have the same number of instances and each distinct
+ instance occurs in both values the same number of times, i.e. both
+ values have the same instances, including duplicates, but in any
+ order.
+
+ d) Two values of a CHOICE type are the same if and only if, both
+ values are of the same chosen alternative and the component values
+ are the same.
+
+ e) Two BIT STRING values are the same if and only if the values have
+ the same number of bits and corresponding bits are the same. If
+ the BIT STRING type is defined with a named bit list then trailing
+ zero bits in the values are treated as absent for the purposes of
+ this comparison.
+
+ f) Two BOOLEAN values are the same if and only if both are TRUE or
+ both are FALSE.
+
+ g) Two values of a string type are the same if and only if the values
+ have the same number of characters and corresponding characters
+ are the same. Letter case is significant. For the purposes of
+ allComponentsMatch, the string types are NumericString,
+ PrintableString, TeletexString (T61String), VideotexString,
+ IA5String, GraphicString, VisibleString (ISO646String),
+ GeneralString, UniversalString, BMPString, UTF8String,
+ GeneralizedTime, UTCTime and ObjectDescriptor.
+
+ h) Two INTEGER values are the same if and only if the integers are
+ equal.
+
+ i) Two ENUMERATED values are the same if and only if the enumeration
+ item identifiers are the same (equivalently, if the integer values
+ associated with the identifiers are equal).
+
+ j) Two NULL values are always the same, unconditionally.
+
+ k) Two OBJECT IDENTIFIER values are the same if and only if the
+ values have the same number of arcs and corresponding arcs are the
+ same.
+
+ l) Two OCTET STRING values are the same if and only if the values
+ have the same number of octets and corresponding octets are the
+ same.
+
+ m) Two REAL values are the same if and only if they are both the same
+ special value, or neither is a special value and they have the
+ same base and represent the same real number. The special values
+
+
+
+Legg Expires 19 October 2002 [Page 26]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ for REAL are zero, PLUS-INFINITY and MINUS-INFINITY.
+
+ n) Two RELATIVE-OID [12] values are the same if and only if the
+ values have the same number of arcs and corresponding arcs are the
+ same. The respective starting nodes for the RELATIVE-OID values
+ are disregarded in the comparison, i.e. they are assumed to be the
+ same.
+
+ o) Two values of an open type are the same if and only if both are of
+ the same ASN.1 type and are the same according to that type.
+
+ Tags and constraints, being part of the type definition and not part
+ of the abstract values, are ignored for matching purposes.
+
+ The allComponentsMatch rule MAY be used as the defined equality
+ matching rule for an attribute.
+
+
+8.3 Deriving Component Equality Matching Rules
+
+ A new component equality matching rule with more refined matching
+ semantics MAY be derived from allComponentsMatch, or any other
+ component equality matching rule, using the convention described in
+ this section.
+
+ The matching behaviour of a derived component equality matching rule
+ is specified by nominating, for each of one or more identified
+ components, a commutative equality matching rule that will be used to
+ match values of that component. This overrides the matching that
+ would otherwise occur for values of that component using the base
+ rule for the derivation. These overrides can be conveniently
+ represented as rows in a table of the following form.
+
+ Component | Matching Rule
+ ============+===============
+ |
+ |
+
+ Usually, all component values of a particular ASN.1 type are to be
+ matched the same way. An ASN.1 type reference (e.g.
+ DistinguishedName) or an ASN.1 built-in type name (e.g. INTEGER) in
+ the Component column of the table specifies that the nominated
+ equality matching rule is to be applied to all values of the named
+ type, regardless of context.
+
+ An ASN.1 type reference with a component reference appended
+ (separated by a ".") specifies that the nominated matching rule
+ applies only to the identified components of values of the named
+
+
+
+Legg Expires 19 October 2002 [Page 27]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ type. Other component values that happen to be of the same ASN.1
+ type are not selected.
+
+ Additional type substitutions as described in Section 5.2 are assumed
+ to be performed to align the component type with the matching rule
+ assertion syntax.
+
+ Conceptually, the rows in a table for the base rule are appended to
+ the rows in the table for a derived rule for the purpose of deciding
+ the matching semantics of the derived rule. Notionally,
+ allComponentsMatch has an empty table.
+
+ A row specifying values of an outer containing type (e.g.
+ DistinguishedName) takes precedence over a row specifying values of
+ an inner component type (e.g. RelativeDistinguishedName), regardless
+ of their order in the table. Specifying a row for component values
+ of an inner type is only useful if a value of the type can also
+ appear on its own, or as a component of values of a different outer
+ type. For example, if there is a row for DistinguishedName then a
+ row for RelativeDistinguishedName can only ever apply to
+ RelativeDistinguishedName component values that are not part of a
+ DistinguishedName. A row for values of an outer type in the table
+ for the base rule takes precedence over a row for values of an inner
+ type in the table for the derived rule.
+
+ Where more than one row applies to a particular component value the
+ earlier row takes precedence over the later row. Thus rows in the
+ table for the derived rule take precedence over any rows for the same
+ component in the table for the base rule.
+
+
+8.4 The directoryComponentsMatch Matching Rule
+
+ The directoryComponentsMatch matching rule is derived from the
+ allComponentsMatch matching rule.
+
+ The LDAP-style definition for directoryComponentsMatch is:
+
+ ( 1.2.36.79672281.1.13.7 NAME 'directoryComponentsMatch'
+ SYNTAX 1.2.36.79672281.1.5.3 )
+
+ The X.500-style definition for directoryComponentsMatch is:
+
+ directoryComponentsMatch MATCHING-RULE ::= {
+ ID { 1 2 36 79672281 1 13 7 } }
+
+ The matching semantics of directoryComponentsMatch are described by
+ the following table, using the convention described in Section 8.3.
+
+
+
+Legg Expires 19 October 2002 [Page 28]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ ASN.1 Type | Matching Rule
+ =========================================+========================
+ RDNSequence | distinguishedNameMatch
+ RelativeDistinguishedName | rdnMatch
+ TelephoneNumber | telephoneNumberMatch
+ FacsimileTelephoneNumber.telephoneNumber | telephoneNumberMatch
+ NumericString | numericStringMatch
+ GeneralizedTime | generalizedTimeMatch
+ UTCTime | uTCTimeMatch
+ DirectoryString{} | caseIgnoreMatch
+ BMPString | caseIgnoreMatch
+ GeneralString | caseIgnoreMatch
+ GraphicString | caseIgnoreMatch
+ IA5String | caseIgnoreMatch
+ PrintableString | caseIgnoreMatch
+ TeletexString | caseIgnoreMatch
+ UniversalString | caseIgnoreMatch
+ UTF8String | caseIgnoreMatch
+ VideotexString | caseIgnoreMatch
+ VisibleString | caseIgnoreMatch
+
+ Notes.
+
+ 1) The DistinguishedName type is defined by assignment to be the same
+ as the RDNSequence type. Some types (e.g. Name and LocalName)
+ directly reference RDNSequence rather than DistinguishedName.
+ Specifying RDNSequence captures all these DN-like types.
+
+ 2) A RelativeDistinguishedName value is only matched by rdnMatch if
+ it is not part of an RDNSequence value.
+
+ 3) The telephone number component of the FacsimileTelephoneNumber
+ ASN.1 type [10] is defined as a constrained PrintableString.
+ PrintableString component values that are part of a
+ FacsimileTelephoneNumber value can be identified separately from
+ other components of PrintableString type by the specifier
+ FacsimileTelephoneNumber.telephoneNumber, so that
+ telephoneNumberMatch can be selectively applied. The fourth
+ edition of X.520 defines the telephoneNumber component of
+ FacsimileTelephoneNumber to be of the type TelephoneNumber, making
+ the row for FacsimileTelephoneNumber.telephoneNumber components
+ redundant.
+
+ The directoryComponentsMatch rule MAY be used as the defined equality
+ matching rule for an attribute.
+
+
+9. Component Matching Examples
+
+
+
+Legg Expires 19 October 2002 [Page 29]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ This section contains examples of search filters using the
+ componentFilterMatch matching rule. The filters are described using
+ the string representation of LDAP search filters from [17]. Note
+ that [17] requires asterisks to be escaped in assertion values (in
+ these examples the assertion values are all <ComponentAssertion>
+ encodings). The asterisks have not been escaped in these examples
+ for the sake of clarity, and to avoid confusing the LDAP protocol
+ representation of search filter assertion values, where such escaping
+ does not apply. Line breaks and indenting have been added only as an
+ aid to readability.
+
+ The example search filters are all single extensible match filter
+ items, though there is no reason why componentFilterMatch can't be
+ used in more complicated search filters.
+
+ The first examples describe searches over the objectClasses schema
+ operational attribute, which has an attribute syntax described by the
+ ASN.1 type ObjectClassDescription [8], and holds the definitions of
+ the object classes known to a directory server. The definition of
+ ObjectClassDescription is as follows:
+
+ ObjectClassDescription ::= SEQUENCE {
+ identifier OBJECT-CLASS.&id,
+ name SET OF DirectoryString {ub-schema} OPTIONAL,
+ description DirectoryString {ub-schema} OPTIONAL,
+ obsolete BOOLEAN DEFAULT FALSE,
+ information [0] ObjectClassInformation }
+
+ ObjectClassInformation ::= SEQUENCE {
+ subclassOf SET OF OBJECT-CLASS.&id OPTIONAL,
+ kind ObjectClassKind DEFAULT structural,
+ mandatories [3] SET OF ATTRIBUTE.&id OPTIONAL,
+ optionals [4] SET OF ATTRIBUTE.&id OPTIONAL }
+
+ ObjectClassKind ::= ENUMERATED {
+ abstract (0),
+ structural (1),
+ auxiliary (2) }
+
+ OBJECT-CLASS.&id and ATTRIBUTE.&id are equivalent to the OBJECT
+ IDENTIFIER ASN.1 type. A value of OBJECT-CLASS.&id is an OBJECT
+ IDENTIFIER for an object class. A value of ATTRIBUTE.&id is an
+ OBJECT IDENTIFIER for an attribute type.
+
+ The following search filter finds the object class definition for the
+ object class identified by the OBJECT IDENTIFIER 2.5.6.18:
+
+ (objectClasses:componentFilterMatch:=
+
+
+
+Legg Expires 19 October 2002 [Page 30]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ item:{ component "identifier",
+ rule objectIdentifierMatch, value 2.5.6.18 })
+
+ A match on the "identifier" component of objectClasses values is
+ equivalent to the objectIdentifierFirstComponentMatch matching rule
+ applied to attribute values of the objectClasses attribute type. The
+ componentFilterMatch matching rule subsumes the functionality of the
+ objectIdentifierFirstComponentMatch, integerFirstComponentMatch and
+ directoryStringFirstComponentMatch matching rules.
+
+ The following search filter finds the object class definition for the
+ object class called foobar:
+
+ (objectClasses:componentFilterMatch:=
+ item:{ component "name.*",
+ rule caseIgnoreMatch, value "foobar" })
+
+ An object class definition can have multiple names and the above
+ filter will match an objectClasses value if any one of the names is
+ "foobar".
+
+ The component reference "name.0" identifies the notional count of the
+ number of names in an object class definition. The following search
+ filter finds object class definitions with exactly one name:
+
+ (objectClasses:componentFilterMatch:=
+ item:{ component "name.0", rule integerMatch, value 1 })
+
+ The "description" component of an ObjectClassDescription is defined
+ to be an OPTIONAL DirectoryString. The following search filter finds
+ object class definitions that have descriptions, regardless of the
+ contents of the description string:
+
+ (objectClasses:componentFilterMatch:=
+ item:{ component "description",
+ rule presentMatch, value NULL })
+
+ The presentMatch returns TRUE if the description component is present
+ and FALSE otherwise.
+
+ The following search filter finds object class definitions that don't
+ have descriptions:
+
+ (objectClasses:componentFilterMatch:=
+ not:item:{ component "description",
+ rule presentMatch, value NULL })
+
+ The following search filter finds object class definitions with the
+
+
+
+Legg Expires 19 October 2002 [Page 31]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ word "bogus" in the description:
+
+ (objectClasses:componentFilterMatch:=
+ item:{ component "description",
+ rule caseIgnoreSubstringsMatch,
+ value { any:"bogus" } })
+
+ The assertion value is of the SubstringAssertion syntax, i.e.
+
+ SubstringAssertion ::= SEQUENCE OF CHOICE {
+ initial [0] DirectoryString {ub-match},
+ any [1] DirectoryString {ub-match},
+ final [2] DirectoryString {ub-match} }
+
+ The "obsolete" component of an ObjectClassDescription is defined to
+ be DEFAULT FALSE. An object class is obsolete if the "obsolete"
+ component is present and set to TRUE. The following search filter
+ finds all obsolete object classes:
+
+ (objectClasses:componentFilterMatch:=
+ item:{ component "obsolete", rule booleanMatch, value TRUE })
+
+ An object class is not obsolete if the "obsolete" component is not
+ present, in which case it defaults to FALSE, or is present but is
+ explicitly set to FALSE. The following search filter finds all non-
+ obsolete object classes:
+
+ (objectClasses:componentFilterMatch:=
+ item:{ component "obsolete", rule booleanMatch, value FALSE })
+
+ The useDefaultValues flag in the ComponentAssertion defaults to TRUE
+ so the componentFilterMatch rule treats an absent "obsolete"
+ component as being present and set to FALSE. The following search
+ filter finds only object class definitions where the "obsolete"
+ component has been explicitly set to FALSE, rather than implicitly
+ defaulting to FALSE:
+
+ (objectClasses:componentFilterMatch:=
+ item:{ component "obsolete", useDefaultValues FALSE,
+ rule booleanMatch, value FALSE })
+
+ With the useDefaultValues flag set to FALSE, if the "obsolete"
+ component is absent the component reference identifies no component
+ value and the matching rule will return FALSE. The matching rule can
+ only return TRUE if the component is present and set to FALSE.
+
+ The "information.kind" component of the ObjectClassDescription is an
+ ENUMERATED type. The allComponentsMatch matching rule can be used to
+
+
+
+Legg Expires 19 October 2002 [Page 32]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ match values of an ENUMERATED type. The following search filter
+ finds object class definitions for auxiliary object classes:
+
+ (objectClasses:componentFilterMatch:=
+ item:{ component "information.kind",
+ rule allComponentsMatch, value auxiliary })
+
+ The following search filter finds auxiliary object classes with
+ commonName (cn or 2.5.4.3) as a mandatory attribute:
+
+ (objectClasses:componentFilterMatch:=and:{
+ item:{ component "information.kind",
+ rule allComponentsMatch, value auxiliary },
+ item:{ component "information.mandatories.*",
+ rule objectIdentifierMatch, value cn } })
+
+ The following search filter finds auxiliary object classes with
+ commonName as a mandatory or optional attribute:
+
+ (objectClasses:componentFilterMatch:=and:{
+ item:{ component "information.kind",
+ rule allComponentsMatch, value auxiliary },
+ or:{
+ item:{ component "information.mandatories.*",
+ rule objectIdentifierMatch, value cn },
+ item:{ component "information.optionals.*",
+ rule objectIdentifierMatch, value cn } } })
+
+ Extra care is required when matching optional SEQUENCE OF or SET OF
+ components because of the distinction between an absent list of
+ instances and a present, but empty, list of instances. The following
+ search filter finds object class definitions with less than three
+ names, including object class definitions with a present but empty
+ list of names, but does not find object class definitions with an
+ absent list of names:
+
+ (objectClasses:componentFilterMatch:=
+ item:{ component "name.0",
+ rule integerOrderingMatch, value 3 })
+
+ If the "name" component is absent the "name.0" component is also
+ considered to be absent and the ComponentAssertion evaluates to
+ FALSE. If the "name" component is present, but empty, the "name.0"
+ component is also present and equal to zero, so the
+ ComponentAssertion evaluates to TRUE. To also find the object class
+ definitions with an absent list of names the following search filter
+ would be used:
+
+
+
+
+Legg Expires 19 October 2002 [Page 33]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ (objectClasses:componentFilterMatch:=or:{
+ not:item:{ component "name", rule presentMatch, value NULL },
+ item:{ component "name.0",
+ rule integerOrderingMatch, value 3 } })
+
+ Distinguished names embedded in other syntaxes can be matched with a
+ componentFilterMatch. The uniqueMember attribute type has an
+ attribute syntax described by the ASN.1 type NameAndOptionalUID.
+
+ NameAndOptionalUID ::= SEQUENCE {
+ dn DistinguishedName,
+ uid UniqueIdentifier OPTIONAL }
+
+ The following search filter finds values of the uniqueMember
+ attribute containing the author's DN:
+
+ (uniqueMember:componentFilterMatch:=
+ item:{ component "dn",
+ rule distinguishedNameMatch,
+ value "cn=Steven Legg,o=Adacel,c=AU" })
+
+ The DistinguishedName and RelativeDistinguishedName ASN.1 types are
+ also complex ASN.1 types so the component matching rules can be
+ applied to their inner components.
+
+ DistinguishedName ::= RDNSequence
+
+ RDNSequence ::= SEQUENCE OF RelativeDistinguishedName
+
+ RelativeDistinguishedName ::= SET SIZE (1..MAX) OF
+ AttributeTypeAndValue
+
+ AttributeTypeAndValue ::= SEQUENCE {
+ type AttributeType ({SupportedAttributes}),
+ value AttributeValue ({SupportedAttributes}{@type}) }
+
+ AttributeType ::= ATTRIBUTE.&id
+
+ AttributeValue ::= ATTRIBUTE.&Type
+
+ ATTRIBUTE.&Type is an open type. A value of ATTRIBUTE.&Type is
+ constrained by the type component of AttributeTypeAndValue to be of
+ the attribute syntax of the nominated attribute type. Note: the
+ fourth edition of X.500 extends and renames the AttributeTypeAndValue
+ SEQUENCE type.
+
+ The seeAlso attribute has the DistinguishedName syntax. The
+ following search filter finds seeAlso attribute values containing the
+
+
+
+Legg Expires 19 October 2002 [Page 34]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ RDN, "o=Adacel", anywhere in the DN:
+
+ (seeAlso:componentFilterMatch:=
+ item:{ component "*", rule rdnMatch, value "o=Adacel" })
+
+ The following search filter finds all seeAlso attribute values with
+ "cn=Steven Legg" as the RDN of the named entry (i.e. the "first" RDN
+ in an LDAPDN or the "last" RDN in an X.500 DN):
+
+ (seeAlso:componentFilterMatch:=
+ item:{ component "-1",
+ rule rdnMatch, value "cn=Steven Legg" })
+
+ The following search filter finds all seeAlso attribute values naming
+ entries in the DIT subtree of "o=Adacel,c=AU":
+
+ (seeAlso:componentFilterMatch:=and:{
+ item:{ component "1", rule rdnMatch, value "c=AU" },
+ item:{ component "2", rule rdnMatch, value "o=Adacel" } })
+
+ The following search filter finds all seeAlso attribute values
+ containing the naming attribute types commonName (cn) and
+ telephoneNumber in the same RDN:
+
+ (seeAlso:componentFilterMatch:=
+ item:{ component "*", rule componentFilterMatch,
+ value and:{
+ item:{ component "*.type",
+ rule objectIdentifierMatch, value cn },
+ item:{ component "*.type",
+ rule objectIdentifierMatch,
+ value telephoneNumber } } })
+
+ The following search filter would find all seeAlso attribute values
+ containing the attribute types commonName and telephoneNumber, but
+ not necessarily in the same RDN:
+
+ (seeAlso:componentFilterMatch:=and:{
+ item:{ component "*.*.type",
+ rule objectIdentifierMatch, value cn },
+ item:{ component "*.*.type",
+ rule objectIdentifierMatch, value telephoneNumber } })
+
+ The following search filter finds all seeAlso attribute values
+ containing the word "Adacel" in any organizationalUnitName (ou)
+ attribute value in any AttributeTypeAndValue of any RDN:
+
+ (seeAlso:componentFilterMatch:=
+
+
+
+Legg Expires 19 October 2002 [Page 35]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ item:{ component "*.*.value.(2.5.4.11)",
+ rule caseIgnoreSubstringsMatch,
+ value { any:"Adacel" } })
+
+ The component reference "*.*.value" identifies an open type, in this
+ case an attribute value. In a particular AttributeTypeAndValue, if
+ the attribute type is not organizationalUnitName then the
+ ComponentAssertion evaluates to FALSE. Otherwise the substring
+ assertion is evaluated against the attribute value.
+
+
+10. Security Considerations
+
+ The component matching rules described in this document allow for a
+ compact specification of matching capabilities that could otherwise
+ have been defined by a plethora of specific matching rules, i.e.
+ despite their expressiveness and flexibility the component matching
+ rules do not behave in a way uncharacteristic of other matching
+ rules, so the security issues for component matching rules are no
+ different than for any other matching rule. However, because the
+ component matching rules are applicable to any attribute syntax,
+ support for them in a directory server may allow searching of
+ attributes that were previously unsearchable by virtue of there not
+ being a suitable matching rule. Such attribute types ought to be
+ properly protected with appropriate access controls.
+
+
+11. Acknowledgements
+
+ The author would like to thank Tom Gindin for private email
+ discussions that clarified and refined the ideas presented in this
+ document.
+
+
+12. Normative References
+
+ [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement
+ Levels", BCP 14, RFC 2119, March 1997.
+
+ [2] Crocker, D. and P. Overell, "Augmented BNF for Syntax
+ Specifications: ABNF", RFC 2234, November 1997.
+
+ [3] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access
+ Protocol (v3)", RFC 2251, December 1997.
+
+ [4] Wahl, M., Coulbeck, A., Howes, T. and S. Kille, "Lightweight
+ Directory Access Protocol (v3): Attribute Syntax Definitions",
+ RFC 2252, December 1997.
+
+
+
+Legg Expires 19 October 2002 [Page 36]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ [5] Wahl, M., Kille S. and T. Howes. "Lightweight Directory Access
+ Protocol (v3): UTF-8 String Representation of Distinguished
+ Names", RFC 2253, December 1997.
+
+ [6] Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC
+ 2279, January 1998.
+
+ [7] Legg, S., "Generic String Encoding Rules for ASN.1 Types",
+ draft-legg-ldap-gser-xx.txt, a work in progress, March 2002.
+
+ [8] ITU-T Recommendation X.501 (1993) | ISO/IEC 9594-2:1994,
+ Information Technology - Open Systems Interconnection - The
+ Directory: Models
+
+ [9] ITU-T Recommendation X.509 (1997) | ISO/IEC 9594-8:1998,
+ Information Technology - Open Systems Interconnection - The
+ Directory: Authentication Framework
+
+ [10] ITU-T Recommendation X.520 (1993) | ISO/IEC 9594-6:1994,
+ Information Technology - Open Systems Interconnection - The
+ Directory: Selected attribute types
+
+ [11] ITU-T Recommendation X.680 (1997) | ISO/IEC 8824-1:1998
+ Information Technology - Abstract Syntax Notation One (ASN.1):
+ Specification of basic notation
+
+ [12] ITU-T Recommendation X.680 - Amendment 1 (06/99) | ISO/IEC
+ 8824-1:1998/Amd 1:2000 Relative object identifiers
+
+ [13] ITU-T Recommendation X.681 (1997) | ISO/IEC 8824-2:1998
+ Information Technology - Abstract Syntax Notation One (ASN.1):
+ Information object specification
+
+ [14] ITU-T Recommendation X.682 (1997) | ISO/IEC 8824-3:1998
+ Information Technology - Abstract Syntax Notation One (ASN.1):
+ Constraint specification
+
+ [15] ITU-T Recommendation X.683 (1997) | ISO/IEC 8824-4:1998
+ Information Technology - Abstract Syntax Notation One (ASN.1):
+ Parameterization of ASN.1 specifications
+
+
+13. Informative References
+
+ [16] Hovey, R. and S. Bradner, "The Organizations Involved in the
+ IETF Standards Process", BCP 11, RFC 2028, October 1996.
+
+ [17] Howes, T., "The String Representation of LDAP Search Filters",
+
+
+
+Legg Expires 19 October 2002 [Page 37]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ RFC 2254, December 1997.
+
+ [18] ITU-T Recommendation X.500 (1993) | ISO/IEC 9594-1:1994,
+ Information Technology - Open Systems Interconnection - The
+ Directory: Overview of concepts, models and services
+
+ [19] ITU-T Recommendation X.690 (1997) | ISO/IEC 8825-1:1998
+ Information Technology - ASN.1 encoding rules: Specification of
+ Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and
+ Distinguished Encoding Rules (DER)
+
+
+14. Intellectual Property 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. [16] 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.
+
+
+15. Copyright Notice
+
+ Copyright (C) The Internet Society (2002). 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
+
+
+
+Legg Expires 19 October 2002 [Page 38]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ 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.
+
+
+16. Author's Address
+
+ Steven Legg
+ Adacel Technologies Ltd.
+ 405-409 Ferntree Gully Road
+ Mount Waverley, Victoria 3149
+ AUSTRALIA
+
+ Phone: +61 3 9451 2107
+ Fax: +61 3 9541 2121
+ EMail: steven.legg@adacel.com.au
+
+
+17. Appendix A - Changes From Previous Drafts
+
+17.1 Changes in Draft 01
+
+ Section 4.1.7 (now 5.1.7) was added to enable component matching of
+ values embedded in encoded form into BIT STRINGs or OCTET STRINGs.
+ In particular, this is to allow component matching of values in
+ Certificate extensions. The <content> rule was added in Section 4.1
+ (now 5.1) to allow the OCTET STRING contents to be treated as either
+ raw octets or as an embedded value.
+
+ References to a companion document summarizing the ASN.1 types of
+ LDAP syntaxes were removed to avoid holding up this document.
+
+ The OpenType syntax was renamed to OpenAssertionType.
+
+ Object identifiers for the new syntax and matching rule definitions
+ have been allocated from an arc belonging to Adacel Technologies Ltd.
+
+
+
+
+Legg Expires 19 October 2002 [Page 39]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+17.2 Changes in Draft 02
+
+ The context specific tagging in the ComponentAssertion ASN.1 type was
+ unnecessary and has been removed.
+
+ The encoding of OpenAssertionType assertion values outside of
+ ComponentAssertions has been clarified, and the description of
+ OpenAssertionType has been promoted to its own section.
+
+17.3 Changes in Draft 03
+
+ The default matching by allComponentsMatch of component values of BIT
+ STRING types with named bit lists has been changed to ignore trailing
+ zero bits.
+
+ Typographical errors in the <SafeUTF8Character> rule have been fixed.
+
+17.4 Changes in Draft 04
+
+ When the matching rule in a ComponentAssertion has a variable
+ assertion syntax it is not possible to determine the syntax of the
+ value component from the ComponentAssertion alone when the associated
+ component reference has referenced through an open type. Deducing
+ what that syntax should be from inspection of the other
+ ComponentAssertions in a ComponentFilter is difficult to implement in
+ any comprehensive way. The <select> form of ComponentId has been
+ introduced so that the syntax can always be determined from the
+ contents of the ComponentAssertion alone. This not only simplifies
+ implementation but can lead to simpler ComponentFilters since there
+ is no longer a requirement to test that the components constraining
+ an open type have particular values. The open type referencing
+ example has been changed accordingly. The contained type referencing
+ example has also been changed because it is an example of a contained
+ open type.
+
+ The presentationAddressMatch rule is not commutative so it has been
+ removed from the table defining directoryComponentsMatch. The default
+ behaviour of allComponentsMatch is already a suitable commutative
+ substitute for matching PresentationAddress values.
+
+ The null character has been included in the range of legal characters
+ for <SafeUTF8Character>.
+
+ The ASN.1 type of the notional iteration count associated with SET OF
+ and SEQUENCE OF values has been refined to INTEGER (0..MAX).
+
+ The encoding rules in Section 8 (now draft-legg-ldap-gser-xx.txt)
+ have been formally named the Generic String Encoding Rules (GSER) and
+
+
+
+Legg Expires 19 October 2002 [Page 40]
+\f
+INTERNET-DRAFT LDAP & X.500 Component Matching Rules April 19, 2002
+
+
+ a transfer syntax object identifier has been assigned.
+
+ The term "LDAP string encoding" has been replaced by the term "native
+ LDAP-specific encoding" to align with terminology anticipated to be
+ used in the revision of RFC 2252.
+
+17.5 Changes in Draft 05
+
+ Reformatted the draft to conform to recent and proposed RFC editorial
+ policy.
+
+ The use of the <oid> rule from RFC 2252 has been replaced by a local
+ definition to specifically outlaw leading zero characters in OBJECT
+ IDENTIFIER components.
+
+ Provisions for the RELATIVE-OID ASN.1 type defined in Amendment 1 to
+ X.680 have been added.
+
+ The comparison of REAL values has been clarified and the GSER
+ encoding of REAL values has been extended.
+
+ Removed extraneous spaces from example DNs.
+
+17.6 Changes in Draft 06
+
+ An ABNF syntax error in the <exponent> rule was fixed.
+
+17.7 Changes in Draft 07
+
+ The term "native LDAP encoding" has been replaced by the term "LDAP-
+ specific encoding" to align with terminology anticipated to be used
+ in the revision of RFC 2252.
+
+ Section 8 has been extracted to become a separate Internet draft,
+ draft-legg-ldap-gser-00.txt. The specifications for ChoiceOfStrings
+ types have also been moved to this new Internet draft. Various
+ editorial changes have been made to this draft to accommodate this
+ split.
+
+17.8 Changes in Draft 08
+
+ The enumeratedMatch matching rule duplicates a subset of the
+ functionality of allComponentsMatch so it has been removed. The
+ enumeratedMatch rule has been replaced by allComponentsMatch in the
+ examples. The description of the OpenAssertionType syntax has been
+ moved into Section 8.
+
+
+
+
+
+Legg Expires 19 October 2002 [Page 41]
+\f
+++ /dev/null
-
-
-
-
-
-
-INTERNET-DRAFT Kurt D. Zeilenga
-Intended Category: Standard Track OpenLDAP Foundation
-Expires in six months 17 May 2002
-
-
-
- LDAP True/False Filters
- <draft-zeilenga-ldap-t-f-02.txt>
-
-
-Status of this Memo
-
- This document is an Internet-Draft and is in full conformance with all
- provisions of Section 10 of RFC2026.
-
- This document is intended to be, after appropriate review and
- revision, submitted to the RFC Editor as a Standard Track document.
- Distribution of this memo is unlimited. Technical discussion of this
- document will take place on the IETF LDAP Extensions Working Group
- mailing list <ietf-ldapext@netscape.com>. Please send editorial
- comments directly to the author <Kurt@OpenLDAP.org>.
-
- 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.''
-
- 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>.
-
- Copyright 2002, The Internet Society. All Rights Reserved.
-
- Please see the Copyright section near the end of this document for
- more information.
-
-
-Abstract
-
- This document extends the Lightweight Directory Access Protocol (LDAP)
- to support absolute True and False filters based upon similar
- capabilities found in X.500 directory systems. The document also
- extends the String Representation of LDAP Search Filters to support
- these filters.
-
-
-
-Zeilenga LDAP True/False Filters [Page 1]
-\f
-INTERNET-DRAFT draft-zeilenga-ldap-t-f-02.txt 17 May 2002
-
-
-1. Background and Intended Use
-
- The X.500 Directory Access Protocol (DAP) [X.511] supports absolute
- True and False assertions. An 'and' filter with zero elements always
- evaluates to True. An 'or' filter with zero elements always evaluates
- to False. These filters are commonly used when requesting DSA-
- specific Entries (DSEs) which do not necessarily have objectClass
- attributes. That is, where "(objectClass=*)" may evaluate to False.
-
- While LDAPv2 [RFC1777] placed no restriction on the number of elements
- in 'and' and 'or' filter sets, the LDAPv2 string representation
- [RFC1960] could not represent empty 'and' and 'or' filter sets. Due
- to this, LDAPv3 [RFC2251] required 'and' and 'or' filter sets to have
- at least one element. Hence, LDAPv3 does not provide absolute True or
- False filters.
-
- This documents extends LDAPv3 [RFC2251] to support absolute True and
- False matches by allowing empty 'and' and 'or' and extends the filter
- string representation [RFC2254] to allow empty filter lists.
-
- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
- document are to be interpreted as described in BCP 14 [RFC2119].
-
-
-2. Absolute True and False Filters
-
- Implementations of this extension SHALL allow 'and' and 'or' choices
- with zero filter elements.
-
- An 'and' Filter consisting of an empty set of filters SHALL evaluate
- to True. This filter is to represented by the string "(&)".
-
- An 'or' Filter consisting of an empty set of filters SHALL evaluate to
- False. This filter is to represented by the string "(|)".
-
- Servers supporting this feature SHOULD publish the Object Identifier
- 1.3.6.1.4.1.4203.1.5.3 as a value of the supportedFeatures [FEATURES]
- attribute in the root DSE.
-
- Clients supporting this feature SHOULD NOT use the feature unless they
- have knowledge the server supports it.
-
-
-3. Security Considerations
-
- The (re)introduction of absolute True and False filters does not raise
- any new security considerations.
-
-
-
-Zeilenga LDAP True/False Filters [Page 2]
-\f
-INTERNET-DRAFT draft-zeilenga-ldap-t-f-02.txt 17 May 2002
-
-
- Implementors of this (or any) LDAP extension should be familiar with
- general LDAP general security considerations [LDAPTS].
-
-
-4. IANA Considerations
-
- No IANA assignments are requested.
-
- This document uses the OID 1.3.6.1.4.1.4203.1.5.3 to identify the
- feature described above. This OID was assigned [ASSIGN] by OpenLDAP
- Foundation under its IANA assigned private enterprise allocation
- [PRIVATE] for use in this specification.
-
-
-5. Author's Address
-
- Kurt D. Zeilenga
- OpenLDAP Foundation
- <Kurt@OpenLDAP.org>
-
-
-6. Normative References
-
- [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14 (also RFC 2119), March 1997.
-
- [RFC2251] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access
- Protocol (v3)", RFC 2251, December 1997.
-
- [RFC2254] T. Howes, "A String Representation of LDAP Search Filters",
- RFC 2254, December 1997.
-
- [LDAPTS] J. Hodges, R. Morgan, "Lightweight Directory Access
- Protocol (v3): Technical Specification",
- draft-ietf-ldapbis-ldapv3-ts-xx.txt (a work in progress).
-
- [FEATURES] K. Zeilenga, "Feature Discovery in LDAP",
- draft-zeilenga-ldap-features-xx.txt (a work in progress).
-
-
-7. Informative References
-
- [RFC1777] Yeong, W., Howes, T., and S. Kille, "Lightweight Directory
- Access Protocol", RFC 1777, March 1995.
-
- [RFC1960] T. Howes, "A String Representation of LDAP Search Filters",
- RFC 1960, June 1996.
-
-
-
-
-Zeilenga LDAP True/False Filters [Page 3]
-\f
-INTERNET-DRAFT draft-zeilenga-ldap-t-f-02.txt 17 May 2002
-
-
- [X.500] ITU-T Rec. X.500, "The Directory: Overview of Concepts,
- Models and Service", 1993.
-
- [X.511] ITU-T Rec. X.511, "The Directory: Abstract Service
- Definition", 1993.
-
- [ASSIGN] OpenLDAP Foundation, "OpenLDAP OID Delegations",
- http://www.openldap.org/foundation/oid-delegate.txt.
-
- [PRIVATE] IANA, "Private Enterprise Numbers",
- http://www.iana.org/assignments/enterprise-numbers.
-
-
-
-Copyright 2002, The Internet Society. All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published and
- distributed, in whole or in part, without restriction of any kind,
- provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be followed,
- or as required to translate it into languages other than English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE AUTHORS, 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.
-
-
-
-
-
-
-
-
-
-
-
-
-
-Zeilenga LDAP True/False Filters [Page 4]
-\f
--- /dev/null
+
+
+
+
+
+
+INTERNET-DRAFT Kurt D. Zeilenga
+Intended Category: Standard Track OpenLDAP Foundation
+Expires in six months 17 May 2002
+
+
+
+ LDAP True/False Filters
+ <draft-zeilenga-ldap-t-f-02.txt>
+
+
+Status of this Memo
+
+ This document is an Internet-Draft and is in full conformance with all
+ provisions of Section 10 of RFC2026.
+
+ This document is intended to be, after appropriate review and
+ revision, submitted to the RFC Editor as a Standard Track document.
+ Distribution of this memo is unlimited. Technical discussion of this
+ document will take place on the IETF LDAP Extensions Working Group
+ mailing list <ietf-ldapext@netscape.com>. Please send editorial
+ comments directly to the author <Kurt@OpenLDAP.org>.
+
+ 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.''
+
+ 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>.
+
+ Copyright 2002, The Internet Society. All Rights Reserved.
+
+ Please see the Copyright section near the end of this document for
+ more information.
+
+
+Abstract
+
+ This document extends the Lightweight Directory Access Protocol (LDAP)
+ to support absolute True and False filters based upon similar
+ capabilities found in X.500 directory systems. The document also
+ extends the String Representation of LDAP Search Filters to support
+ these filters.
+
+
+
+Zeilenga LDAP True/False Filters [Page 1]
+\f
+INTERNET-DRAFT draft-zeilenga-ldap-t-f-02.txt 17 May 2002
+
+
+1. Background and Intended Use
+
+ The X.500 Directory Access Protocol (DAP) [X.511] supports absolute
+ True and False assertions. An 'and' filter with zero elements always
+ evaluates to True. An 'or' filter with zero elements always evaluates
+ to False. These filters are commonly used when requesting DSA-
+ specific Entries (DSEs) which do not necessarily have objectClass
+ attributes. That is, where "(objectClass=*)" may evaluate to False.
+
+ While LDAPv2 [RFC1777] placed no restriction on the number of elements
+ in 'and' and 'or' filter sets, the LDAPv2 string representation
+ [RFC1960] could not represent empty 'and' and 'or' filter sets. Due
+ to this, LDAPv3 [RFC2251] required 'and' and 'or' filter sets to have
+ at least one element. Hence, LDAPv3 does not provide absolute True or
+ False filters.
+
+ This documents extends LDAPv3 [RFC2251] to support absolute True and
+ False matches by allowing empty 'and' and 'or' and extends the filter
+ string representation [RFC2254] to allow empty filter lists.
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in BCP 14 [RFC2119].
+
+
+2. Absolute True and False Filters
+
+ Implementations of this extension SHALL allow 'and' and 'or' choices
+ with zero filter elements.
+
+ An 'and' Filter consisting of an empty set of filters SHALL evaluate
+ to True. This filter is to represented by the string "(&)".
+
+ An 'or' Filter consisting of an empty set of filters SHALL evaluate to
+ False. This filter is to represented by the string "(|)".
+
+ Servers supporting this feature SHOULD publish the Object Identifier
+ 1.3.6.1.4.1.4203.1.5.3 as a value of the supportedFeatures [FEATURES]
+ attribute in the root DSE.
+
+ Clients supporting this feature SHOULD NOT use the feature unless they
+ have knowledge the server supports it.
+
+
+3. Security Considerations
+
+ The (re)introduction of absolute True and False filters does not raise
+ any new security considerations.
+
+
+
+Zeilenga LDAP True/False Filters [Page 2]
+\f
+INTERNET-DRAFT draft-zeilenga-ldap-t-f-02.txt 17 May 2002
+
+
+ Implementors of this (or any) LDAP extension should be familiar with
+ general LDAP general security considerations [LDAPTS].
+
+
+4. IANA Considerations
+
+ No IANA assignments are requested.
+
+ This document uses the OID 1.3.6.1.4.1.4203.1.5.3 to identify the
+ feature described above. This OID was assigned [ASSIGN] by OpenLDAP
+ Foundation under its IANA assigned private enterprise allocation
+ [PRIVATE] for use in this specification.
+
+
+5. Author's Address
+
+ Kurt D. Zeilenga
+ OpenLDAP Foundation
+ <Kurt@OpenLDAP.org>
+
+
+6. Normative References
+
+ [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14 (also RFC 2119), March 1997.
+
+ [RFC2251] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access
+ Protocol (v3)", RFC 2251, December 1997.
+
+ [RFC2254] T. Howes, "A String Representation of LDAP Search Filters",
+ RFC 2254, December 1997.
+
+ [LDAPTS] J. Hodges, R. Morgan, "Lightweight Directory Access
+ Protocol (v3): Technical Specification",
+ draft-ietf-ldapbis-ldapv3-ts-xx.txt (a work in progress).
+
+ [FEATURES] K. Zeilenga, "Feature Discovery in LDAP",
+ draft-zeilenga-ldap-features-xx.txt (a work in progress).
+
+
+7. Informative References
+
+ [RFC1777] Yeong, W., Howes, T., and S. Kille, "Lightweight Directory
+ Access Protocol", RFC 1777, March 1995.
+
+ [RFC1960] T. Howes, "A String Representation of LDAP Search Filters",
+ RFC 1960, June 1996.
+
+
+
+
+Zeilenga LDAP True/False Filters [Page 3]
+\f
+INTERNET-DRAFT draft-zeilenga-ldap-t-f-02.txt 17 May 2002
+
+
+ [X.500] ITU-T Rec. X.500, "The Directory: Overview of Concepts,
+ Models and Service", 1993.
+
+ [X.511] ITU-T Rec. X.511, "The Directory: Abstract Service
+ Definition", 1993.
+
+ [ASSIGN] OpenLDAP Foundation, "OpenLDAP OID Delegations",
+ http://www.openldap.org/foundation/oid-delegate.txt.
+
+ [PRIVATE] IANA, "Private Enterprise Numbers",
+ http://www.iana.org/assignments/enterprise-numbers.
+
+
+
+Copyright 2002, The Internet Society. All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published and
+ distributed, in whole or in part, without restriction of any kind,
+ provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be followed,
+ or as required to translate it into languages other than English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE AUTHORS, 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+Zeilenga LDAP True/False Filters [Page 4]
+\f
projects / openldap / commitdiff