6 — LDAP Capabilities

[Previous] [Next] [Contents] [Index]

6.1 Overview of LDAP

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

6.2.1 LDAP Syntax

In addition to the CDS syntax, rpc_c_ns_syntax_dce (previously supported by NSI), the LDAP-enabled NSI supports a new name syntax, rpc_c_ns_syntax_ldap.

If this new syntax is specified in an NSI call, the corresponding name must be an LDAP Distinguished Name (DN), which NSI uses to obtain information from the LDAP directory service.

If the CDS syntax is used in an NSI call, it is not apparent from the syntax which directory service, LDAP or CDS, is to be contacted. The run-time NSI configuration options and the nature of the call join in the decision. If LDAP is selected, NSS translates the name from CDS syntax to LDAP syntax. The purpose of the syntax translator is to make LDAP accessible from applications using a CDS syntax.

6.2.2 NSI Configuration

A one-time initialization executes when an application accesses NSI for the first time. The initialization determines which name services the application wants to use and the priority of each name service. The easiest way to provide the required information is with a configuration file.

If the LDAP name service is specified, the initialization must be able to find the address of the host where the LDAP server is running, the port it is listening on, and the cell name mapping from DNS or X.500 syntax to LDAP syntax. If more than one name service is configured, the export mode that determines if updates need to be sent to all name services has to be specified.

The environment variable RPC_CONFIG_FILE can be used to specify a configuration file. A configuration file can specify a DNS name to query for configuration information, allowing central control of client configuration. Storing LDAP configuration information in the TXT records of a DNS name is the recommended way of configuring the LDAP NSI.

Here is the recommended way to use a configuration file for LDAP:

  1. Choose a DNS name. (Consult with the DNS administrator.)

  2. Store the configuration information in the TXT records of a DNS name for use before the first process that uses RPC is executed.

  3. Create a file using the LDAP NSI configuration file syntax, and include all the options and values appropriate to your site, as explained in the next section.

  4. Ask the DNS administrator to create a TXT record for each line in this file and to add these TXT records to the set of records belonging to the domain name you chose.

  5. Use the RPC_CONFIG_FILE environment variable to specify the location of the file you want to be the configuration file. This file contains only a single line, specifying the target DNS name you chose previously:

    RPC_NS_DNS_CONFIG_INFO domain_name

The syntax of the LDAP NSI configuration file maps easily to a set of attribute type/value pairs. The pairs are described in the next section.

6.2.3 Configuration File Format and Syntax

The configuration file contains values for various configuration options used by the NSI runtime library. Each line of the file is of the following form:

config_option_name config_option_value

If multiple values are specified for a particular configuration option separated by a tab or a space character. Each value must be specified as a separate option name/option value pair on a separate line.

The following table describes the possible values for the config_option_name and config_option_value fields in the LDAP configuration file.

Table 6-1: LDAP NSI Configuration Options and Values

config_option_name config_option_value

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.



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



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.


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.



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 {
			   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 
		for each configured name service in the specified priority {
			if the name is in the native syntax of the name service {
			   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:

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

6.3.3 NSI Known Limitations 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. Schema

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

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. 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:

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:

A schema also defines nine attribute types:

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)

rpcGroup holds a set of references to other rpcEntry objects


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


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. 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> ]
[ ·"SUP" <oids> ] - ObjectClass[es] from which this class is derived
[ ·"PARENT" <oids> ] - Permissible parents of this object class
[ ·"MUST" <oids> ] -- AttributeTypes
[ ·"MAY" <oids> ] -- AttributeTypes
")" Object Naming

All objects have cn (common name) as their naming attribute; this attribute provides the RDN for the object. 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:

These object classes are included in the Lightweight Directory Access Protocol: Standard and Pilot Attribute Definitions, an ETF standard document, still in progress. 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)
					MUST cn

NOTE: The implementation treats rpcEntry as a structural, rather than an abstract, object class. 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)
					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. 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)

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
			MUST ( rpcNsPriorlty $ rpcNsProfileEnt an $ rpcNsInterfacQId )
			MAY rpcNsAnnotation
       ) 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)
					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
			HOST ( rpcNsInterfaceID $ rpcNsBindings $ rpcNsTransferSyntax )
       ) 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: 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 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
					D8AGE userApplications
					) 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
					USAGE userApplicationa
					) 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
					USAGE userApplications
					) 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:


The BNF description of this item is:

 ( 1 2 840 113556 1 4 115
					NAME 'rpcNsInterfaceID'
					EQUALITY caseIgnoreMatch
					SYNTAX directoryString
					USAGE userApplications
					) 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
					USAGE userApplications
					) 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
					) The rpcNsBindings

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


The BNF description of this item is:

( 1 2 840 113556 1 4 113
					NAME 'rpcNsBindings'
					EQUALITY caseIgnoreMatch
					SYNTAX dlrectoryString
					USAGE userApplications
					) 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

6.3.5 Usage Model

Instantiating an rpcGroup, rpcProfile, or rpcServer object and any necessary child objects (e.g., rpcServerElement or rpcProfileElement)can create any RPC entry type. Searching is simplified because there is a well-known set of object classes and attributes for each entry type.

A group entry contains the rpcNsGroup attribute listing the entries in the group. Each group is a single object and can be retrieved in a single operation. An rpcGroup object can have rpcNsObjectID present-----the list of object IDs, if present, is explicitly stored and retrieved by applications and not used by the NSI provider in locating rpcNsGroup objects.

A profile entry consists of an rpcProfile container with one or more rpcProfileEntry objects as children, one for each priority level defined. The complete profile is retrieved in a single operation by performing a single-level LDAP search for objects of class rpcProfileElement rooted at the rpcProfile entry.

A server entry consists of an rpcServer container with one or more rpcServerElement objects as children. The complete entry is retrieved in a single operation by performing a single--level LDAP search for objects of class rpcServerElement rooted at the rpcProfile entry. The NSI provider creates a new rpcServerElement entry when the interface and transfer syntax provided by the caller do not match an existing rpcServerElement in the named server entry. If a matching rpcServerElement exists, the NSI provider updates it with the string bindings provided by the caller.

This schema allows many discrete rpcServerElement objects to be stored in a given entry. This avoids a number of problems in trying to store multiple interfaces with their versions and transfer syntax in a single entry while providing convenient access and searching with LDAP. Indexing the Interface ID and Object UUIDs reduces the performance cost for retrieving multiple objects. Relative Names

On the surface, CDS can be said to support cell-relative names; LDAP does not. DCE RPC allows names presented to the RPC NSI to be absolute or relative. An absolute name contains the full DN of the entry in question. A relative name is relative to the DCE cell where the name is stored. The full DN is the DN of the cell with the relative name appended. When using an LDAP directory to store RPC entries as defined by this schema, the implementation of relative names is implementation dependent, but should be consistent. A suggested approach is the creation of a container at the root of the namespace; for example, directly below the first instantiated object, such as Organization or organizational Unit, which forms the root for cell-relative names.

6.4 How GDA Works

LDAP support at the GDA level is achieved by adding an LDAP path for cross-cell information. Depending on the syntax of the cell name and if a specific path is enabled via command line options, GDA is now able to look up foreign cell information in either DNS, or LDAP, or X.500.

In cases when both LDAP and X.500 are enabled and the cell name is typed, GDA first resolves the name using LDAP, only if the typed name cannot be resolved, the X.500 path is invoked. Figure 6-2 shows the various elements at work in the gdad environment.

Figure 6-2: Operation at gdad Level

6.4.1 Cell Naming

Cell names remain either as untyped names in DNS format or typed names in X.500 format. LDAP cell names are not supported.

If LDAP is enabled, GDA converts an X.500 typed cell name into LDAP syntax when sending a request to an LDAP directory service. The conversion routine can return unexpected results if special characters defined by either X.500 or LDAP are used in the cell name.

6.4.2 Security

GDA supports the minimum level of authentication. Authentication information may be supplied on the command line when gdad is started. However, these command line arguments can be viewed by most users and therefore a security problem can exist.

6.4.3 Registration Utility

The utility ldap_addcell is provided to register cell information in the LDAP directory service. The utility obtains and dynamically adds DCE cell information to the LDAP directory service. Authentication information must be provided on the command line.

[Previous] [Next] [Contents] [Index]

To make comments or ask for help, contact support@entegrity.com.

Copyright © 2001 Entegrity Solutions Corporation & its subsidiaries.

Copyright © 1998-2001 Compaq Computer Corporation.

All rights reserved.