Release 2 (9.0.2)
Part Number A95193-01
 Home |
 Solution Area |
 Contents |
 Index |
| Oracle Internet Directory Application Developer's Guide Release 2 (9.0.2) Part Number A95193-01 |
|
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:
LDAP began as a lightweight front end to the X.500 Directory Access Protocol. To simplify X.500 Directory Access Protocol, LDAP:
LDAP defines four basic models to describe its operations. This section contains these topics:
The LDAP naming model allows directory information to be referenced and organized. Each entry in a directory is uniquely identified by a distinguished name (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.
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.)
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.
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.
The LDAP functional model determines what operations can be performed on the information. There are three types of functions:
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.
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.
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.
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:
In an Oracle Internet Directory environment, SSL authentication between a client and a directory server involves three basic steps:
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).
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.
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:
The DES40 algorithm, available internationally, is a variant of DES in which the secret key is preprocessed to provide forty effective key bits. It is designed for use by customers outside the USA and Canada who want to use a DES-based encryption algorithm. This feature gives commercial customers a choice in the algorithm they use, regardless of their geographic location.
Oracle has obtained license to export the RC4 data encryption algorithm with a 40-bit key size to virtually all destinations where other Oracle products are available. This makes it possible for international corporations to safeguard their entire operations with fast cryptography.
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.
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:
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.
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:
Figure 2-4 illustrates these steps.
The following sections explain the important features of the API with respect to each of these steps.
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.
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) ;
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.
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 ) RETURN SESSION;
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:
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.
Before initiating any of the LDAP operations, an individual or application seeking to perform operations against an LDAP server must be authenticated.
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 [12]. 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.
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)RETURN PLS_INTEGER;
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)RETURN 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:
The appendix about Oracle Wallet Manager in Oracle Internet Directory Administrator's Guide |
The following PL/SQL code snippet shows a typical usage of the initialization, authentication, and cleanup functions that were just described.
DECLAREretval PLS_INTEGER; my_session DBMS_LDAP.session;BEGINretval := -1; -- Initialize the LDAP session my_session := DBMS_LDAP.init('yow.acme.com',389); --Bind to the directory retval :=DBMS_LDAP.simple_bind_s(my_session, 'cn=orcladmin',
'welcome');
In the previous example, an LDAP session is initialized to the LDAP server on the computer yow.acme.com 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.
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, attrs IN STRING_COLLECTION, attronly IN PLS_INTEGER, res OUT MESSAGE )RETURN PLS_INTEGER;
Both functions take these arguments:
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.
The programming work required to initiate a typical search operation and retrieve results can be broken down into the following steps:
DBMS_LDAP.STRING_COLLECTION data-type.
DBMS_LDAP.search_s or DBMS_LDAP.search_st).
DBMS_LDAP.first_entry or DBMS_LDAP.next_entry).
DBMS_LDAP.first_attribute or DBMS_LDAP.next_attribute).
DBMS_LDAP.get_values or DBMS_LDAP.get_values_len)
Figure 2-5 illustrates the above steps in more detail.
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.
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:
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:
The complex filters shown above can themselves be combined to create arbitrarily complex nested filters.
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:
FUNCTION unbind_s (ld IN SESSION ) RETURN PLS_INTEGER;
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.
|
 Copyright © 2002 Oracle Corporation. All Rights Reserved. |
|