The Lightweight Directory Access Protocol (LDAP) provides access to the X.500 directory service without the overhead of the full Directory Access Protocol (DAP). The simplicity of LDAP, along with the powerful capabilities it inherits from DAP, has made it a defacto standard for Internet directory services.

DCE has relied on CDS to provide both intra-cell and inter-cell directory service. Inside a cell, the directory service is accessed mostly through the name service interface (NSI), implemented as part of the runtime library. Cross-cell directory service is controlled by a global directory agent (GDA), which looks up foreign cell information on behalf of the application in either the Domain Naming Service (DNS) or X.500 database. Once that information is obtained, the application contacts the foreign CDS in the same way as the local CDS.

DCE gains LDAP support for both NSI and GDA. From an application standpoint, any application within NSI can now reach the LDAP directory service. From a GDA standpoint, GDA can now look up foreign cell information by communicating through LDAP to either an LDAP-aware X.500 directory service or a standalone LDAP directory service, in addition to DNS and DAP.

This release provides LDAP as an optional directory service that is independent of CDS. From an application standpoint, it duplicates CDS functionality. LDAP does not replace CDS as the directory service for DCE nor does it coexist with CDS Version 3.0 of DCE for Compaq Tru64 UNIX . LDAP is provided as an option for customers looking for an alternative that offers TCP/IP and internet support.

Gradient DCE for Tru64 UNIX does not automatically install LDAP. Prior to installing DCE, a DCE administrator must obtain LDAP software and install it as an LDAP server in the environment. Next, a DCE administrator must choose LDAP during the DCE installation and configuration procedure and configure LDAP directory service for a cell. Once LDAP is configured, applications can request directory services from either CDS or LDAP, or both. Whether or not LDAP is configured, DCE system processes continue to rely on CDS to provide directory service.

6.2 How NSI Works

NSI stores and retrieves RPC binding, group, and profile information in either the CDS directory service or LDAP, or both.

NSI implements the name service switch (NSS), which selects among configured directory services when executing an NSI call.

Exactly which name service(s) are selected by NSS depends upon the name and syntax arguments to the NSI call, the NSI runtime configuration options, and the nature of the call itself, as shown in Figure 6-1

Figure 6-1: NSI Architecture

Table 6-1: LDAP NSI Configuration Options and Values
config_option_name	config_option_value
`RPC_NS_NAME_SERVICE`	`integer: l 100 CDS\|LDAP` An integer priority value followed by the name of a name service known to the NSI. Currently, the only known services are CDS and LDAP. Multiple name services may be configured and are tried in priority order subject to the service selection rules. Lower priority values indicate higher priority No default. At least one name service must be specified. Multiple name services may be speci-fied, if desired. If the same name service is specified more than once, the last priority value specified is used. If more than one name service has the same priority value, it is undefined which service has (effectively) the highest priority.
`RPC_NS_EXPORT_MODE`	`write_one\|write_all` Specifies whether export operations should write only to the first possible name service or all possi-ble name services. Services are tried in priority order. Default is `write_one`; in the case that the option is specified multiple times, only the last-specified value is used
`RPC_NS_LDAP_SERVER`	hostname_or_ip_addr[:port] The name or IP address of an LDAP server to which the NSI can connect. The appropriate port number may also be specified. The default port number (389) is used if another is not specified. Multiple LDAP servers can be specified, but only the first specified server will be used.
`RPC_NS_LDAP_CELLMAPPING`	dce_cell_name ldap_dn Associates the ldap_dn with the dce_cell_name so that names in the specified cell are searched for in the specified LDAP subtree. No default. Multiple options may be specified; if multiple mappings for the same cellname are specified, the last-specified mapping is used.
`RPC_NS_DNS_CONFIG_INFO`	domain_name A domain name the NSI can query to obtain configuration information. This domain name should possess TXT records formatted exactly like lines in the configuration file: each TXT record has an initial config_option_name followed by white space and a config_option_value. No default. Multiple options may be specified; the effect is to read each specified DNS name for configuration information.

6.2.4 NSI Call Categorization

Usually, an NSI call is either read or write. A read NSI call obtains information from the directory service but makes no changes. A write call creates, deletes, or updates a directory. An example of the read NSI call is rpc_ns_binding_lookup_next. The call rpc_ns_binding_export is an example of write NSI call.

NSI calls that are neither read nor write calls are miscellaneous calls, of which an example is rpc_ns_binding_select.

A read NSI call completes when the information is obtained from a configured directory service. NSI does not guarantee the consistency of information between different configured name services.

A write NSI call may or may not complete when the operation succeeds in one configured directory service, depending on the export mode run-time configuration option.

6.2.5 Name Service Selection

For a read NSI call, the following pseudocode describes the NSS selection algorithm:

		for each configured name service in the specified priority {
			if the name is in the native syntax of the name service {
			    or
			   a translation routine exists to the native syntax {
				append the name service to the trial list
			}
		}

		if there is no name services on the trial list {
			return rpc_s_name_service_unavailble
		}

		for each name service on the trial list {
			make the call
			if the call succeeds {
				return success
			} else if the call fails with other than rpc_s_entry_not_found {
				return the error
			} else if there is no more name services {
				return rpc_s_entry_not_found
			}
		}
For a write NSI call, the following pseudocode describes the NSS selection 
algorithm:
		for each configured name service in the specified priority {
			if the name is in the native syntax of the name service {
			    or
			   a translation routine exists to the native syntax {
				append the name service to the trial list
			}
		}

		if there is no name services on the trial list {
			return rpc_s_name_service_unavailble
		}

		for each name service on the trial list {
			make the call
			if the call succeeds {
				if export mode is to update one name service {
					return success
				}
			} else {
				return the error
			}
		}

Among the read NSI calls, contexts provide a way to maintain information across successive calls. An example of a read NSI call with context is rpc_ns_binding_lookup_next. The context is built in a previous rpc_ns_binding_lookup_begin and destroyed in rpc_ns_binding_lookup_done. NSS manages calls to assure that only the call to construct the context runs the selection algorithm. Successive calls bypass the algorithm and use the same selected name service.

6.2.6 Name Translation from CDS to LDAP

The NSI controls the CDS-syntax-to-LDAP-syntax translation of names. CDS-to-LDAP translation supports applications using the LDAP directory service with names based on CDS syntax. Another, larger purpose of name translation is to separate applications from dependence on particular directory services.

A configuration file controls NSI. A specific DCE cell name is associated with the DN of a subtree in the LDAP name space. The mapping of a DCE cell name in either DNS or X.500 style to the distinguished name (DN) must be provided in the NSI configuration file.

To translate a name in CDS syntax to LDAP syntax, the cell name part is translated using the mapping(s) specified in the NSI configuration file. The cell relative part is transformed with the order of the component names reversed. The component name is prefixed with cn=, commas are substituted for slash separators. Quoted special characters in CDS, and unquoted and unquoted special characters in LDAP, are quoted.

For example, if the mapping between /.../dce.mycompany.com and ou=dce,o=mycompany,c=us is defined, the name /.../dce.mycompany.com/foo/bar is translated as cn=bar,cn=foo,ou=dce,o=mycompany,c=us. The name /.../dce.mycompany.com/foo=bar is translated as cn=foo\=bar,ou=dce,o=mycompany,c=us. Note the handling of special characters in the second example.

6.3 Using NSI

This section describes NSI configuration issues and possible differences between CDS and LDAP.

6.3.1 Modifying Runtime Configuration Options

The NSI initialization process first checks if a value (file name) is set for the environment variable, RPC_CONFIG_FILE. If it finds the environment variable and the name of a file, the contents of the file is used to initialize the NSI. If no environment variable is present, the NSI initialization process looks for the default system runtime configuration file, /opt/dcelocal/etc/rpc.conf.

If neither the default configuration file nor the environment variable exists, NSI initialization fails with the error status rpc_s_file_not_found. If the file is not in the format as described earlier or is corrupted, NSI initialization fails with error status rpc_s_invalid_file_format.

Note that the default configuration file is very important. Modifying the default configuration file, /opt/dcelocal/etc/rpc.conf, affects configuration options for all DCE processes on the same host machine.

DCE installation configures CDS. DCE system processes rely on CDS to provide directory service security and reliability. Poorly-considered changes to the system defaults in the NSI configuration file can have particular consequences for the security daemon and CDS advertiser, and thereby compromise a DCE cell.

Please note that it is strongly recommended that you leave the default configuration file unchanged. Instead, use the environment variable RPC_CONFIG_FILE to alter runtime NSI configuration options. By providing a user-specified configuration file rather than altering the system default file, you safeguard an environment in which CDS and LDAP can continue to work properly.

6.3.2 Application Programming

For the sake of source and binary compatibility, the application programming interface (API) for the name service is unchanged. Note that an application might behave differently if LDAP is configured. A difference may result from LDAP itself or the availability of multiple name services.

A programmer must keep several things in mind:

CDS is a directory service that has no schema support. Any kind of data can be written to any kind of entry. Although users are advised to follow certain styles, they are not required to do so. LDAP mandates the use of schema, as X.500 does. It is likely that if a program does not follow the style and it succeeds in CDS, it might fail with LDAP configured.
Security is not supported in LDAP in Gradient DCE for Tru64 UNIX. All NSI calls are unauthenticated. The NSI call rpc_ns_set_authn has no effect on LDAP operations.
NSI calls for setting expiration ages have no effect on LDAP operations as LDAP does not support caching.
LDAP does not guarantee consistency among different directory services. Searching an entry in the LDAP directory service can return completely different results from the corresponding entry in CDS. Also, setting export mode to updating all configured directory services does not guarantee transactional behavior, which means the update procedure may succeed in one directory service and fail in another one and not try yet others.

To use multiple directory services, the understanding of NSS selection algorithms is essential.

6.3.3 NSI Known Limitations

6.3.3.1 Security

LDAP NSI offers no support for security. The lack of security makes an LDAP directory service vulnerable to spoofing or denial of service attacks.

6.3.3.2 Schema

Although CDS does not support schemas, it does support the following concepts:

Default Entry-----Stores bindings
UUID Entry-----Stores universal unique identifiers
Group Entry-----Stores members information
Profile Entry-----Stores profile elements

In LDAP, the object schema implements those same concepts and reinforces them.

As a result of the schema, certain kinds of data can only be exported to certain kinds of entries. For example, bindings cannot be exported to group entries and group members cannot be exported to profile entries. If an LDAP NSI operation is called for an incompatible kind of entry, the call fails with rpc_s_entry_not_found even if the entry indeed exists in the name space.

However, both CDS and LDAP support the notion of "upgrade." Namely, one can perform operations that are permissible to a server entry on a default entry, in which case the default entry is "upgraded" to a server entry. The same applies to group entry and profile entry.

There is one exception to the rule. In CDS, it is legal to export only UUIDs to a default entry, but this is not allowed in LDAP. Because the default entry does not allow UUIDs, LDAP would have to "upgrade" it. But both server entry and group entry allow UUIDs, there is no way of knowing which type of entry to "upgrade" to. This implementation of LDAP NSI chooses to return an error in an ambiguous case like this.

6.3.3.3 Schema for Storing RPC Entries in a Directory Service

This section defines a schema that conforms closely to the DCE conceptual model for RPC entries. This schema allows an RPC NSI implementation to use LDAP to store RPC entries and to use LDAP queries to implement the RPC NSI lookup APIs.

The implementation supports three kinds of RPC Name Service Entries:

Server Entries—Support the retrieval of a set of string bindings for any combination of Entry Name, Interface ID and version, Object ID, Transfer Syntax, and transfer syntax version.
Group Entries—A set of RPC entries identified by an Entry name.
Profile Entries—A profile establishes a priority-based search order through a set of entries. This is essentially a "list of sets" with the outer list ordered by priority and each inner set at the current priority.

DCE RPC defines the concept of a "mixed entry" in which a single entry serves multiple purposes—for example, entries that serve as both Group and Server entries. Mixed entries are not supported by this schema. This seldom-used DCE RPC feature leads to unnecessary complexity for both implementers and users of the RPC NSI.

To meet these requirements, a schema defines six object classes:

rpcEntry
rpcGroup
rpcServer
rpcServerElement
rpcProfile
rpcProfileElement

A schema also defines nine attribute types:

rpcNsObJectID
rpcNsGroup
rpcNsPriority
rpcNsProfileEntry
rpcNsInterfaceID
rpcNsAnnotation
rpcNsCodeset
rpcNsBindings
rpcNsTransferSyntax

Taken together, these object classes and attributes implement the DCE-RPC concept of an entry.

The rpcEntry object class is the class from which all other RPC objects derive, so that they may be easily located in a search.

An rpcGroup, rpcServer, or rpcProfile object forms the "root" of an entry. The type of entry is determined by the object class. Note that the types are mutually exclusive; an entry cannot serve multiple purposes. Separating the entry types into distinct object classes, as shown in Table 6-2, simplifies the task of the NSI provider in determining how to handle a given entry.

Table 6-2: Entry Types and Object Groups

Entry Type Object Class(es)
Group

rpcGroup holds a set of references to other rpcEntry objects

Profile

rpcProfile, a container holding a set of rpcProfileEntry objects, each holding a list of references to entries with a given priority

Server

rpcServer, a container holding a set of rpcServerElement objects, each holding the identification of one or more interfaces (and/or objects) offered by a given server

Table 6-2: Entry Types and Object Groups
Entry Type	Object Class(es)
Group	rpcGroup holds a set of references to other rpcEntry objects
Profile	rpcProfile, a container holding a set of rpcProfileEntry objects, each holding a list of references to entries with a given priority
Server	rpcServer, a container holding a set of rpcServerElement objects, each holding the identification of one or more interfaces (and/or objects) offered by a given server

6.3.4 Objects and Attributes

The following treats a number of items for programmers.

6.3.4.1 Notation

The notation used in this document is the same as that used in Lightweight Directory Access Protocol: Standard and Pilot Attribute Definitions, with the following difference: the referenced notation does not allow the expression of both permissible parentage and class inheritance. The BNF in the cited draft for defining object classes is therefore extended as follows:

<ObjectClassDescription> ::= "("
<oid> -- ObjectClass ldentifier
[ "NAME" <DirectoryStrings> ]
[ "DESC" <DirectoryStrings> ]
[ "OBSOLETE" ]
[ ·"SUP" <oids> ] - ObjectClass[es] from which this class is derived
[ ·"PARENT" <oids> ] - Permissible parents of this object class
[ ( ·"ABSTRACT" | ·"STRUCTURAL" | ·"AUXILIARY" ) ]
[ ·"MUST" <oids> ] -- AttributeTypes
[ ·"MAY" <oids> ] -- AttributeTypes
")"

6.3.4.2 Object Naming

All objects have cn (common name) as their naming attribute; this attribute provides the RDN for the object.

6.3.4.3 Object Definitions

In addition to the object classes listed in the sections below as allowed parents, there must be at least one other object class allowed as a parent to root the tree. Furthermore, we recommend that the following object classes also be allowed to parent RPC object classes:

country
organization
organizational Unit
locality
container

These object classes are included in the Lightweight Directory Access Protocol: Standard and Pilot Attribute Definitions, an ETF standard document, still in progress.

6.3.4.4 RPC Entry

The RPC Entry is the class from which all other RPC classes are derived.

( 1.2.840.113556.1.5.27
					NAME 'rpcEntry'
					SUP top
					PARENT (rpcEntry $ rpcGroup $ rpcProfile $ rpcServer)
					STRUCTURAL
					MUST cn
     )

NOTE: The implementation treats rpcEntry as a structural, rather than an abstract, object class.

6.3.4.5 RPC Group

The rpcGroup object defines an RPC Group. The cn is the RDN component of the entry name provided by the user in the NSI API call that creates the group. The rpcNsObjectID attribute contains string UUIDs of objects added to the group entry by applications. These object IDs are not used by the NSI provider during lookup operations.

( 1.2.840.113556.1.5.80
					NAME 'rpcGroup'
					SUP rpcEntry
					PARENT (rpcEntry $ rpcGroup $ rpcProfile $ rpcServer)
					STRUCTURAL
					MAY rpcNsGroup
					MAY rpcNsObjectID
   )

The next-to-last code line, MAY rpcNsGroup, is changed here from the Open Group specification, which uses MUST. To make the attribute rpcNsGroup mandatory not only disallows the notion of empty groups, but also makes deleting a last member of a group impossible. Because both those operations must be supported by DCE, it is best to make the rpcNsGroup attribute optional instead of mandatory.

6.3.4.6 RPC Profile

RPC Profile entries are implemented by two object classes. The rpcProfile object class is a container used to gather profile elements into a single profile instance. The cn is the RDN component of the entry name provided by the user in the NSI API call that creates the profile.

( 1. 2 . 840.113556.1.5.82
					NAME 'rpcProflle'
					SUP rpcEntry
					PARENT (rpcEntry $ rpcGroup $ rpcProflle $ rpcserver)
					STRUCTURAL
      )

The rpcProfileElement object describes a single element in the profile. The entire profile is retrieved with a single-level LDAP search rooted at the parent rpcProfile container. The cn is a string UUID generated by the NSI provider when the rpcProfileElement instance is created.

( 1.2.840.113556.1.5.26
			NAME 'rpcProfileElement'
			SUP rpcEntry
			PARENT rpcProfile
			STRUCTURAL
			MUST ( rpcNsPriorlty $ rpcNsProfileEnt an $ rpcNsInterfacQId )
			MAY rpcNsAnnotation
       )

6.3.4.7 RPC Server

RPC Server entries are implemented by two object classes. The rpcServer object class is a container. It is used to gather rpcServerElement entries into a single server instance. The cn is the user-provided RDN component of the entry name in the NSI API call that creates the server entry.

( 1.2.840.113556.1.5.81
					NAME 'rpcServer'
					SUP rpcEntry
					PARENT (rpcEntry $ rpcGroup $ rpcProfile $ rpcServer)
					STRUCTURAL
					MAY ( rpcNsObjectID $ rpcNsCodeSet )
         )

The rpcServerElement object describes a single interface in the server entry. The entire Server entry is retrieved with a single-level LDAP search rooted at the parent rpcServer container. The attributes of the rpcServerElement object allow for efficient searching using straightforward LDAP query expressions. The cn is a string UUID generated by the NSI provider when the rpcServerElement instance is created.

( 1.2.840.113556.1.5.73
			NAME 'rpcServerElement'
			SUP rpcEntry
			PARENT rpcServer
			STRUCTURAL
			HOST ( rpcNsInterfaceID $ rpcNsBindings $ rpcNsTransferSyntax )
       )

6.3.4.8 Attribute Definitions

RPC Name Service implementations search on a well-known set of attributes. Implementations of this schema are advised for performance reasons to index the following attributes:

rpcNsObjectID
rpcNsInterfaceID

6.3.4.9 The rpcNsObjectID

A set of string UUIDs for objects (in the DCE RPC sense of objects):

( 1.2.840.113556.1.4.312
					NAME 'rpcNsObjectID'
					EQUALITY caseIgnoreListMatch
					SYNTAX directoryString
					USAGE userApplications

6.3.4.10 The rpcNsGroup

A set of DNs for RPC entries that are members of a given RPC group:

( 1.2.840.113556.1.4.11d
					NAME 'rpcNsGroup'
					EQUALITY distinguishedNameMatch
					SUBSTRING distinguishedNameMatch
					SYNTAX DN
					D8AGE userApplications
					)

6.3.4.11 The rpcNsPriority

An integer value indicating the priority of a given RPC profile element:

( 1.2.840.113556.1.d.117
					NAME 'rpcNsPriority'
					EQUALITY integerMatch
					SYNTAX INTEGER
					USAGE userApplicationa
					)

6.3.4.12 The rpcNsProfileEntry

The DN of a single RPC entry that is a member of a given RPC profile:

( 1.2.840.113556.1.4.118
					NAME 'rpcNsGroup'
					EQUALITY distinguishedNameMatch
					SUBSTRING distinguishedNameMatch
					SYNTAX DN
					SINGLE-VALUE
					USAGE userApplications
					)

6.3.4.13 The rpcNsInterfaceID

A string composed of the UUID for an interface exported by an RPC server and the interface major and minor version numbers in the form:

 string-UUID'',''major''.''minor

The BNF description of this item is:

 ( 1 2 840 113556 1 4 115
					NAME 'rpcNsInterfaceID'
					EQUALITY caseIgnoreMatch
					SYNTAX directoryString
					SINGLE-VALUE
					USAGE userApplications
					)

6.3.4.14 The rpcNsAnnotation

A string describing a given RPC Profile element:

( 1 2 840 113556 1 4 366
					NAME 'rpcNsAnnotation'
					EQUALITY caseIgnoreMatch
					SUBSTRING caseIgnoreMatch
					SYNTAX directoryString
					SINGLE-VALUE
					USAGE userApplications
					)

6.3.4.15 The rpcNsCodeset

A set of strings identifying the character sets supported by a given RPC server:

( 1 2 840 113556 1 4 367
					NAME 'rpcNsCodeset'
					EQUALITY caseIgnoreListMatch
					SYNTAX directoryString
					USAGE userApplications
					)

6.3.4.16 The rpcNsBindings

A set of binding strings for a given interface and transfer syntax, in the form:

 ProtocolSequence'':''NetworkAddress''[]''

The BNF description of this item is:

( 1 2 840 113556 1 4 113
					NAME 'rpcNsBindings'
					EQUALITY caseIgnoreMatch
					SYNTAX dlrectoryString
					USAGE userApplications
					)

6.3.4.17 The rpcNsTransferSyntax

A set of strings composed of the string UUID for a transfer syntax supported by an RPC server, and the transfer syntax major and minor version numbers in the form:

 string-UUID'',''major'' ''minor

The BNF description of this item is:

( 1 2 840 113556 1 4 314
					NAME 'rpcNsTransferSyntax'
					EQUALITY caseIgnoreLletMatch
					SYNTAX directoryString
					USAGE userApplications
					)