Skip Headers

Oracle Internet Directory Application Developer's Guide
Release 9.2

Part Number A96577-01
Go To Documentation Library
Go To Product List
Book List
Go To Table Of Contents
Go To Index

Master Index


Go to previous page Go to next page


This chapter provides a brief overview of all of the major operations available in the C API and the PL/SQL API. It provides developers a general understanding of Lightweight Directory Access Protocol (LDAP) from a perspective independent of the API. The concepts acquired in this section make it easier to understand the API details.

This chapter contains these topics:

History of LDAP

LDAP began as a lightweight front end to the X.500 Directory Access Protocol. To simplify X.500 Directory Access Protocol, LDAP:

Overview of LDAP Models

LDAP defines four basic models to describe its operations. This section contains these topics:

LDAP Naming Model

The LDAP naming model allows directory information to be referenced and organized. Each entry in a directory is uniquely identified by a DN. The distinguished name tells you exactly where the entry resides in the directory's hierarchy. This hierarchy is represented by a directory information tree (DIT).

To understand the relation between a distinguished name and a directory information tree, look at the example in Figure 2-1.

Figure 2-1 A Directory Information Tree

Text description of oidag025.gif follows
Text description of the illustration oidag025.gif

The DIT in Figure 2-1 diagrammatically represents entries for two employees of Acme Corporation who are both named Anne Smith. It is structured along geographical and organizational lines. The Anne Smith represented by the left branch works in the Sales division in the United States, while the other works in the Server Development division in the United Kingdom.

The Anne Smith represented by the right branch has the common name (cn) Anne Smith. She works in an organizational unit (ou) named Server Development, in the country (c) of Great Britain (uk), in the organization (o) Acme.

The DN for this "Anne Smith" entry is:

cn=Anne Smith,ou=Server Development,c=uk,o=acme

Note that the conventional format of a distinguished name places the lowest DIT component at the left, then follows it with the next highest component, thus moving progressively up to the root.

Within a distinguished name, the lowest component is called the relative distinguished name (RDN). For example, in the above entry for Anne Smith, the RDN is cn=Anne Smith. Similarly, the RDN for the entry immediately above Anne Smith's RDN is ou=Server Development, the RDN for the entry immediately above ou=Server Development is c=uk, and so on. A DN is thus a sequence of RDNs separated by commas.

To locate a particular entry within the overall DIT, a client uniquely identifies that entry by using the full DN--not simply the RDN--of that entry. For example, within the global organization in Figure 2-1, to avoid confusion between the two Anne Smiths, you would use each one's full DN. (If there are potentially two employees with the same name in the same organizational unit, you could use additional mechanisms, such as identifying each employee with a unique identification number.)

LDAP Information Model

The LDAP information model determines the form and character of information in the directory. It is centered around entries, which are composed of attributes. In a directory, each collection of information about an object is called an entry. For example, a typical telephone directory includes entries for people, and a library card catalog contains entries for books. Similarly, an online directory might include entries for employees, conference rooms, e-commerce partners, or shared network resources such as printers.

In a typical telephone directory, an entry for a person contains such information items as an address and a phone number. In an online directory, such an information item is called an attribute. Attributes in a typical employee entry can include, for example, a job title, an e-mail address, or a phone number.

For example, in Figure 2-2, the entry for Anne Smith in Great Britain (uk) has several attributes, each providing specific information about her. These are listed in the balloon to the right of the tree, and they include emailaddrs, printername, jpegPhoto, and app preferences. Moreover, each bullet in Figure 2-2 is also an entry with attributes, although the attributes for each are not shown.

Figure 2-2 Attributes of the Entry for Anne Smith

Text description of concept6.gif follows
Text description of the illustration concept6.gif

Each attribute consists of an attribute type and one or more attribute values. The attribute type is the kind of information that the attribute contains--for example, jobTitle. The attribute value is the particular occurrence of information appearing in that entry. For example, the value for the jobTitle attribute could be manager.

LDAP Functional Model

The LDAP functional model determines what operations can be performed on the information. There are three types of functions:

Search and read

The read operation retrieves the attributes of an entry whose name is known. The list operation enumerates the children of a given entry. The search operation selects entries from a defined area of the tree based on some selection criteria known as a search filter. For each matching entry, a requested set of attributes (with or without values) is returned. The searched entries can span a single entry, an entry's children, or an entire subtree. Alias entries can be followed automatically during a search, even if they cross server boundaries. An abandon operation is also defined, allowing an operation in progress to be canceled.


This category defines four operations for modifying the directory:


This category defines a bind operation, allowing a client to initiate a session and prove its identity to the directory. Several authentication methods are supported, from simple clear-text password to public key-based authentication. The unbind operation is used to terminate a directory session.

LDAP Security Model

The LDAP security model allows information in the directory to be secured.

This section contains these topics:


Authentication is the process by which the directory server establishes the true identity of the user connecting to the directory. It occurs when an LDAP session is established by means of the ldap-bind operation. Every session has an associated user identity, also referred to as an authorization ID.

To ensure that the identities of users, hosts, and clients are correctly known, Oracle Internet Directory provides three authentication options: anonymous, simple, and SSL.

Anonymous Authentication

If your directory is available to everyone, then you can allow users to log in to the directory anonymously. When using anonymous authentication, users simply leave blank the user name and password fields when they log in. Each anonymous user then exercises whatever privileges are specified for anonymous users.

Simple Authentication

In this case, the client identifies itself to the server by means of a DN and a password which are not encrypted when sent over the network. In the simple authentication option, the server verifies that the DN and password sent by the client match the DN and password stored in the directory.

Authentication Using Secure Sockets Layer (SSL)

Secure Socket Layer (SSL) is an industry standard protocol for securing network connections. It provides authentication through the exchange of certificates that are verified by trusted certificate authorities. A certificate ensures that an entity's identity information is correct. An entity can be an end user, a database, an administrator, a client, or a server. A certificate authority (CA) is an application that creates public key certificates that are given a high level of trust by all the parties involved.

You can use SSL in one of three authentication modes:

SSL Mode Description

No authentication

Neither the client nor the server authenticates itself to the other. No certificates are sent or exchanged. In this case, only SSL encryption/decryption is used.

One-way authentication

Only the directory server authenticates itself to the client. The directory server sends the client a certificate verifying that the server is authentic.

Two-way authentication

Both client and server authenticate themselves to each other. Both the client and server send certificates to each other.

In an Oracle Internet Directory environment, SSL authentication between a client and a directory server involves three basic steps:

  1. The user initiates an LDAP connection to the directory server by using SSL on the SSL port. (The default SSL port is 636.)
  2. SSL performs the handshake between client and directory server.
  3. If the handshake is successful, the directory server verifies that the user has the appropriate authorization to access the directory.

    See Also:

    Oracle Advanced Security Administrator's Guide for more information about SSL

Access Control and Authorization

Authorization is the process of ensuring that a user reads or updates only the information for which that user has privileges. When directory operations are attempted within a directory session, the directory server ensures that the user-- identified by the authorization ID associated with the session--has the requisite permissions to perform those operations. Otherwise, the operation is disallowed. Through this mechanism, the directory server protects directory data from unauthorized operations by directory users. This mechanism is called access control.

Access control information is the directory metadata that captures the administrative policies relating to access control.

ACI is stored in Oracle Internet Directory as user-modifiable operational attributes. Typically, a list of these ACI attribute values, called an Access Control List (ACL), is associated with directory objects. The attribute values on that list govern the access policies for those directory objects.

ACIs are represented and stored as text strings in the directory. These strings must conform to a well defined format. Each valid value of an ACI attribute represents a distinct access control policy. These individual policy components are referred to as ACI Directives or ACIs and their format is called the ACI Directive format.

Access control policies can be prescriptive, that is, their security directives can be set to apply downward to all entries at lower positions in the directory information tree (DIT). The point from which an access control policy applies is called an access control policy point (ACP).

Data Integrity

Oracle Internet Directory ensures that data has not been modified, deleted, or replayed during transmission by using SSL. This SSL feature generates a cryptographically secure message digest--through cryptographic checksums using either the MD5 algorithm or the Secure Hash Algorithm (SHA)--and includes it with each packet sent across the network.

Data Privacy

Oracle Internet Directory ensures that data is not disclosed during transmission by using public-key encryption available with Secure Sockets Layer (SSL). In public-key encryption, the sender of a message encrypts the message with the public key of the recipient. Upon delivery, the recipient decrypts the message using the recipient's private key. Specifically, Oracle Internet Directory supports two levels of encryption available through SSL:

Password Protection

During installation, the protection scheme for passwords was set. You can change that initial configuration by using either Oracle Directory Manager or ldapmodify. You must be a superuser to change the type of password encryption.

To encrypt passwords, Oracle Internet Directory uses the MD4 algorithm as the default. MD4 is a one-way hash function that produces a 128-bit hash, or message digest. You can change this default to one of the following:

The value you specify is stored in the orclCryptoScheme attribute in the root DSE. This attribute is single-valued.

During authentication to a directory server, a user enters a password in clear text. The server then hashes the password by using the specified encryption algorithm, and verifies it against the hashed password in the userPassword attribute. If the hashed password values match, then the server authenticates the user. If the hashed password values do not match, then the server sends the user an Invalid Credentials error message.

Password Policies

A password policy is a set of rules that govern how passwords are used. When a user attempts to bind to the directory, the directory server uses the password policy to ensure that the password meets the various requirements set in that policy

When you establish a password policy, you set the following types of rules, to mention just a few:

About the Oracle Internet Directory API

The Oracle Internet Directory API is available as a C API and as a PL/SQL API.

The PL/SQL API is contained in a PL/SQL package called DBMS_LDAP. This package enables PL/SQL applications to access data located in enterprise-wide LDAP servers. The naming and syntax of the function calls are similar to those of the Oracle Internet Directory C API functions and comply with the current recommendations from the Internet Engineering Task Force (IETF) for the LDAP C-API. However, the PL/SQL API contains only a subset of the functions available in the C API. In particular, only synchronous calls to the LDAP server are available in the PL/SQL API.

Figure 2-3 illustrates the overall placement of the DBMS_LDAP API in the runtime environment of a client.

Figure 2-3 Applications Sharing LDAP Server Data

Text description of oiddg006.gif follows
Text description of the illustration oiddg006.gif

As Figure 2-3 shows, the API allows multiple different applications--in this example, Human Resources and Financials--to share employee address book information and user profiles by using an LDAP server.

Storing such information in an LDAP server enables other non-database applications that are LDAP-enabled to retrieve the same information. In Figure 2-3, the Email Clients application uses the same employee address book data to find the employee for a given email address. Because LDAP offers a centralized repository of user information, the same information can be used for Single Sign-On applications and other enterprise-wide user provisioning applications.

In summary, the Oracle Internet Directory API enables Oracle database applications to:

Typically, an application or trigger uses the functions in the API in four simple steps:

  1. Initialize the library and obtain an LDAP session handle.
  2. Authenticate to the LDAP server if necessary.
  3. Perform some LDAP operations and obtain results and errors if any.
  4. Close the session.

Figure 2-4 illustrates these steps.

Figure 2-4 Steps in Typical DBMS_LDAP Usage

Text description of oiddg003.gif follows
Text description of the illustration oiddg003.gif

The following sections explain the important features of the API with respect to each of these steps.

Initializing an LDAP Session

All LDAP operations require clients to establish an LDAP session with the LDAP server. To perform LDAP operations, a database session must first initialize and open an LDAP session.

Initializing the Session by Using the C API

ldap_init() initializes a session with an LDAP server. The server is not actually contacted until an operation is performed that requires it, allowing various options to be set after initialization.

LDAP *ldap_init

const char      *hostname,
int             portno
) ;
Table 2-1  Parameters for ldap_init()
Parameter Description


Contains a space-separated list of hostnames or dotted strings representing the IP address of hosts running an LDAP server to connect to. Each hostname in the list MAY include a port number which is separated from the host itself with a colon (:) character. The hosts will be tried in the order listed, stopping with the first one to which a successful connection is made.

Note: A suitable representation for including a literal IPv6[10] address in the hostname parameter is desired, but has not yet been determined or implemented in practice.


Contains the TCP port number to connect to. The default LDAP port of 389 can be obtained by supplying the constant LDAP_PORT. If a host includes a port number then this parameter is ignored.

ldap_init() and ldap_open() both return a session handle, that is, a pointer to an opaque structure that MUST be passed to subsequent calls pertaining to the session. These routines return NULL if the session cannot be initialized in which case the operating system error reporting mechanism can be checked to see why the call failed.

Note that if you connect to an LDAPv2 server, one of the LDAP bind calls described below SHOULD be completed before other operations can be per formed on the session. LDAPv3 does not require that a bind operation be completed before other operations can be performed.

The calling program can set various attributes of the session by calling the routines described in the next section.

Initializing the Session by Using DBMS_LDAP

Initialization occurs by means of a call to the function DBMS_LDAP.init(). The function `init' has the following syntax:

FUNCTION init (hostname IN VARCHAR2, portnum  IN PLS_INTEGER )


To establish an LDAP session, the function init requires a valid hostname and a port number. It allocates a data structure for the LDAP session and returns a handle of the type DBMS_LDAP.SESSION to the caller. The handle returned from the call to init should be used in all subsequent LDAP operations with the API. The DBMS_LDAP API uses the LDAP session handles to maintain state about open connections, outstanding requests, and other information.

A single database session can obtain as many LDAP sessions as required. Typically, multiple LDAP sessions within the same database session are opened if:

LDAP Session Handle Options in the C API

The LDAP session handle returned by ldap_init() is a pointer to an opaque data type representing an LDAP session. In RFC 1823 this data type was a structure exposed to the caller, and various fields in the structure could be set to control aspects of the session, such as size and time limits on searches.

In the interest of insulating callers from inevitable changes to this structure, these aspects of the session are now accessed through a pair of accessor functions, described below.

ldap_get_option() is used to access the current value of various session-wide parameters. ldap_set_option() is used to set the value of these parameters. Note that some options are READ-ONLY and cannot be set; it is an error to call ldap_set_option() and attempt to set a READ-ONLY option.

Note that if automatic referral following is enabled (the default), any connections created during the course of following referrals will inherit the options associated with the session that sent the original request that caused the referrals to be returned.

Enabling Authentication to a Directory Server

Before initiating any of the LDAP operations, an individual or application seeking to perform operations against an LDAP server must be authenticated.

Enabling Authentication to a Directory Server by Using the C API

The ldap_sasl_bind() and ldap_sasl_bind_s() functions can be used to do general and extensible authentication over LDAP through the use of the Simple Authentication Security Layer. The routines both take the dn to bind as, the method to use, as a dotted-string representation of an OID identifying the method, and a struct berval holding the credentials. The special constant value LDAP_SASL_SIMPLE (NULL) can be passed to request simple authentication, or the simplified routines ldap_simple_bind() or ldap_simple_bind_s() can be used.

Enabling Authentication to a Directory Server by Using DBMS_LDAP

The functions simple_bind_s and bind_s enable applications to authenticate to the directory server by using certain credentials. The function simple_bind_s has the following syntax:

FUNCTION simple_bind_s ( ld IN SESSION, dn IN VARCHAR2, passwd IN VARCHAR2)


The function simple_bind_s requires the LDAP session handle obtained from init as the first parameter. It also requires an LDAP distinguished name (DN) of an entry. This DN represents:

If the dn and passwd parameters are NULL, then the LDAP server assigns a special identity, called anonymous, to the application. Typically, the anonymous identity is associated with the least privileges in an LDAP directory.

When a bind operation is completed, the directory server remembers the new identity until either another bind is done or the LDAP session is terminated by using unbind_s. The identity is used by the LDAP server to enforce the security model specified by the enterprise administration. In particular, this identity helps the LDAP server determine whether the user or application has sufficient privileges to perform search, update, or compare operations in the directory.

Note that the password for the bind operation is sent in the clear over the network. If the network is not secure, then consider using SSL for authentication as well as secure data transport for all LDAP operations. The function that initiates SSL communications is called open_ssl and its syntax is:

FUNCTION open_ssl(ld IN SESSION, sslwrl IN VARCHAR2,

sslwalletpasswd IN VARCHAR2, sslauth IN PLS_INTEGER)

The open_sslfunction should be called immediately after the call to init to secure the LDAP TCP/IP connection from eavesdroppers. Authentication is done implicitly by using the credentials in the certificate stored in the wallet.

See Also:

Oracle Advanced Security Administrator's Guide for instructions on using the Oracle Wallet Manager

The following PL/SQL code snippet shows a typical usage of the initialization, authentication, and cleanup functions that were just described.


my_session DBMS_LDAP.session;
retval := -1;
-- Initialize the LDAP session
my_session := DBMS_LDAP.init('',389);
--Bind to the directory
retval :=DBMS_LDAP.simple_bind_s(my_session, 'cn=orcladmin',

In the previous example, an LDAP session is initialized to the LDAP server on the computer that is listening for requests at TCP/IP port number 389. Then an authentication is performed with the identity of cn=orcladmin whose password is welcome. This authenticates the LDAP session and paves the way for regular LDAP operations.

Searching by Using DBMS_LDAP

Searches are the most frequently used LDAP operations. The LDAP search operation allows applications to select and retrieve entries from the directory by using complex search criteria. This release of DBMS_LDAP API provides only synchronous search capability. This implies that the caller of the search functions is blocked until the LDAP server returns the entire result set.

There are two functions available for initiating searches in the DBMS_LDAP API:

The only difference between the two is that search_st() uses a client side timeout to stop the search if it exceeds a certain elapsed time limit. The syntax for DBMS_LDAP.search_s() is:

FUNCTION search_s

ld       IN  SESSION,
base     IN  VARCHAR2,
scope    IN  PLS_INTEGER,
filter   IN  VARCHAR2,
attronly IN  PLS_INTEGER,
res      OUT MESSAGE

Both functions take these arguments:

Argument Description


A valid session handle


The DN of the base entry in the LDAP server where search should start


The breadth and depth of the DIT that needs to be searched


The filter used to select entries of interest


The attributes of interest in the entries returned


If set to 1, only returns the attributes


An OUT parameter that returns the result set for further processing

In addition to search_s and search_st, several support functions in the API help in retrieving search results. These are highlighted in the following section.

Flow of Search-Related Operations

The programming work required to initiate a typical search operation and retrieve results can be broken down into the following steps:

  1. Decide the attributes that need to be returned, and compose them into the DBMS_LDAP.STRING_COLLECTION data-type.
  2. Initiate the search operation with the desired options and filters (using DBMS_LDAP.search_s or DBMS_LDAP.search_st).
  3. From the result set get an entry (using DBMS_LDAP.first_entry or DBMS_LDAP.next_entry).
  4. For the entry obtained in Step 3, get an attribute (using DBMS_LDAP.first_attribute or DBMS_LDAP.next_attribute).
  5. For the attribute obtained in Step 4, get all of the values and copy them into local variables (using DBMS_LDAP.get_values or DBMS_LDAP.get_values_len)
  6. Repeat Step 4 until all attributes of the entry are examined
  7. Repeat Step 3 until there are no more entries

Figure 2-5 illustrates the above steps.

Figure 2-5 Flow of Search-Related Operations

Text description of oiddg004.gif follows
Text description of the illustration oiddg004.gif

Search Scope

The scope of the search determines the number of entries relative to the base of the search that the directory server examines to see if they match the given filter condition. One of three options can be specified when invoking either search_s() or search_st() functions:

Figure 2-6 illustrates the difference between the three scope options.

Figure 2-6 The Three Scope Options

Text description of oiddg005.gif follows
Text description of the illustration oiddg005.gif

In Figure 2-6, the base of the search is the patterned circle. The shaded rectangle identifies the entries that are searched.


The search filter required by the search_s() and search_st() functions follows the string format defined in Internet Engineering Task Force (IETF) RFC 1960. This section provides a brief overview of the various options available for the filters.

There are six kinds of basic search filters that take an attribute operator value format. The following table summarizes the basic search filters:

Table 2-2  Search Filters
Filter Type Format Example Matches




Surnames exactly equal to Keaton.




Surnames approximately equal to Ketan.




Surnames containing the string "keaton".




Surnames starting with "keaton".




Surnames ending in "keaton".




Surnames starting with "ke", containing "at" and ending with "on".

Greater than or equal



Surnames lexicographically greater than or equal to Keaton.

Less than or equal



Surnames lexicographically less than or equal to Keaton.




All entries having the sn attribute.

The basic filters in Table 2-2 can be combined to form more complex filters using the Boolean operators and a prefix notation. The & character represents AND, the | character represents OR, and the ! character represents NOT.

Table 2-3 summarizes the fundamental Boolean operations:

Table 2-3  Boolean Operators
Filter Type Format Example Matches




Entries with surname of Keaton AND objectclass of InetOrgPerson.




Entries with surname approximately equal to ketan OR common name ending in keaton.




Entries without a mail attribute.

The complex filters shown above can themselves be combined to create arbitrarily complex nested filters.

Enabling Session Termination by Using DBMS_LDAP

Once an LDAP session handle is obtained and all of the desired LDAP-related work is complete, the LDAP session must be destroyed. This is accomplished through a call to DBMS_LDAP.unbind_s(). The function unbind_s has the following syntax:


A successful call to unbind_s closes the TCP/IP connection to the LDAP server, de-allocates all system resources consumed by the LDAP session, and returns the integer DBMS_LDAP.SUCCESS to its callers. Once the unbind_s function is invoked on a particular session, no other LDAP operations on that session can succeed unless the session is re-initialized with a call to init.

Go to previous page Go to next page
Copyright © 1999, 2002 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Go To Product List
Book List
Go To Table Of Contents
Go To Index

Master Index