test

Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition

Part I Directory Server Reference

This part explains how Directory Server works. The information here is primarily descriptive. For instructions, try Part I, Directory Server Administration, in Oracle Fusion Middleware Administration Guide for Oracle Directory Server Enterprise Edition instead.

This part covers the following chapters.

For additional reference information, see Oracle Fusion Middleware Man Page Reference for Oracle Directory Server Enterprise Edition.

Chapter 2 Directory Server Overview

This chapter outlines the architecture of Directory Server. This chapter includes the following topics.

Introduction to Directory Server

Directory Server serves directory data to standards compliant LDAP and DSML applications. Directory Server stores the data in customized, binary tree databases, allowing quick searches even for large data sets.

Directories are object oriented databases. Directories organize their data objects, called entries, into a directory information tree, often called a DIT. Each entry is identified by a distinguished name, such as uid=bjensen,ou=people,dc=example,dc=com. The distinguished name identifies where the entry is located in the directory information tree. For example, uid=bjensen,ou=people,dc=example,dc=com is a user entry for Barbara Jensen on the ou=people branch of the dc=example,dc=com part of the tree.

Each directory entry has attributes. For entries that concern people, these attributes may reflect names, phone numbers, and email addresses, for example. An attribute has at least one type name, which is the name of the attribute. For example, people entries can have an attribute surname, which can also be called by the shorter name sn. Attributes can also have one or more values. For example, if Barbara Jensen marries Quentin Cubbins, and takes Quentin's surname, her entry could have sn: Jensen and sn: Cubbins.

Directories are designed to be fast when looking up entries based on the values of their attributes. An example query might be, “Find all the entries under dc=example,dc=com with surname Jensen.” This fast lookup capability makes directories well suited for applications where you store information that must be read often. Directories are therefore good data stores for telephone and email information. Directories are also good for handling authentication credentials, identity information, and application configuration data.

Directory Server is also designed to handle high update rates as the information in the directory changes. Today, the size of many directory deployments mean that handling updates well can be as important as handling lookups.

Directory Server supports many directory related standards and RFCs. Directory Server allows fast data replication across the network for high availability. Directory Server lets you configure servers comprehensively without restarting them. Furthermore, Directory Server gives you extensive control over access to directory data.

The list of Directory Server features is too long to cover in a short introduction. Oracle Fusion Middleware Evaluation Guide for Oracle Directory Server Enterprise Edition includes a more extensive list. The other chapters in this part of this Reference help you to understand many of the features in detail.

Directory Server Architecture

This section succinctly addresses key concepts of Directory Server from the point of view of someone who must install and manage Directory Server. This section touches on the following topics.

Comparison of Software Installation and Server Instances

For each installation of Directory Server software, you can create multiple server instances. Although you may create server instances in the place on the file system where you install the software, nothing requires you to put both the software and the instances side by side.

The Directory Server software you install includes the executable files, template data, and sample files needed to create, run, and manage actual servers. As the software is separate from the actual servers, you can apply patches or service packs to the software without changing the server data. You therefore do not need to patch each server instance, but instead only the software installation.

A Directory Server instance holds the configuration data and the directory data required to serve directory client applications. Although in production systems you carefully control the user identity of the server, you can typically create and run a Directory Server instance as any user on the system. The directory data belongs then to the user who created the instance.

In Chapter 1, Directory Server Enterprise Edition File Reference, you see that Software Layout for Directory Server Enterprise Edition is clearly separate from Directory Server Instance Default Layout. In particular, notice that the documentation mentions install-path when referring to the software installation, but instance-path when referring to a server instance.

Communication With Client Applications

Directory Server listens for LDAP and DSML client application traffic on the port numbers you configure. Directory Server listens for LDAP connections as soon as the server starts. Directory Server only listens for DSML connections over HTTP if you enable the DSML service.

By default, Directory Server listens for LDAP connections on port 389 if the instance was created by root, 1389 if the instance was created by non-root. By default, Directory Server listens for LDAP connections over SSL on port 636 if the instance was created by root, 1636 if the instance was created by non-root. The DSML/HTTP port number is not defined by default. Instead, you supply a port number when enabling the DSML service.

    In order to enable client applications to reach Directory Server, you create instances on hosts with static IP addresses. The hostname is also usually referenced in DNS. Client applications typically need at least two pieces of information to access the directory.

  1. The hostname, or at least the IP address, of the system on which Directory Server runs.

  2. The port number on which Directory Server listens for client connections.

LDAP clients and servers do not usually open a new connection for every request. In the LDAP model, a client connects to the server to authenticate before performing other operations. The connection and authentication process is referred to as binding. Client applications can bind with credentials, but they can also bind anonymously. Directory Server lets you configure access accordingly both for known and anonymous clients. Client applications can also keep a connection open, but bind again, thus changing the authentication identity. This technique can reduce the costs of creating a new connection.

Once the bind has been performed and the client is authenticated, the client can request the following operations.

add

Add a new directory entry.

compare

Checks whether an attribute value is the same as a given value.

delete

Delete a directory entry.

modify

Change one or more attributes of a directory entry.

modDN

Change the distinguished name of a directory entry.

This operation is for moving directory entries from one part of the directory information tree to another. For example, you could move uid=bjensen,ou=employees,dc=example,dc=com to uid=bjensen,ou=people,dc=example,dc=com.

When you move an parent entry, such as ou=people,dc=example,dc=com, the operation can take a very long time as Directory Server must move all child entries of the parent as well.

modRDN

Change the relative distinguished name of a directory entry.

The relative distinguished name is the attribute value used to distinguish a directory entry from the others at the same level of the directory information tree.

This operation is for renaming directory entries. For example, you could rename uid=bjensen,ou=employees,dc=example,dc=com to uid=bcubbins,ou=people,dc=example,dc=com.

This operation is a special case of modDN. The modRDN operation is always relatively fast, however, as it involves modifying only leaf entries.

search

Find all the directory entries under a specified point in the directory tree that have attribute values matching a filter.

A search filter can specify one or more attribute characteristics. For example, to find entries with the surname Jensen, you use the LDAP filter (sn=Jensen). To find entries with surname Jensen and user ID beginning with the letter B, you use the LDAP filter (&(sn=Jensen)(uid=b*)).

When finished performing operations, a client can unbind. After unbinding, the connection is dropped by the client and the server. Client applications can also abandon operations, such as a search that is taking too long.

Directory Server can handle many client connections simultaneously. To handle connections, Directory Server consumes free file descriptors, and manages a number of threads. You can limit the system resources available to Directory Server through the server configuration. See Chapter 6, Tuning System Characteristics and Hardware Sizing, in Oracle Fusion Middleware Deployment Planning Guide for Oracle Directory Server Enterprise Edition for details.

Directory Server Configuration

Directory Server stores server instance configuration data in files, but the configuration data is also accessible over LDAP.

The files are stored under instance-path as follows. Directory Server stores the LDAP schema, which define what directory entries can contain, under instance-path/config/schema/. See Oracle Fusion Middleware Man Page Reference for Oracle Directory Server Enterprise Edition for reference information about the schema, and Chapter 11, Directory Server Schema, in Oracle Fusion Middleware Administration Guide for Oracle Directory Server Enterprise Edition for instructions on managing schema. Directory Server stores other configuration information in the dse.ldif(4) file, instance-path/config/dse.ldif. Avoid updating this file by hand.

Over LDAP, the schema information is accessible under cn=schema. The other configuration information is accessible under cn=config. In practice, you do not generally update data under cn=config directly. Instead, you use either the web based Directory Service Control Center, or the dsconf command. Both Directory Service Control Center and the dsconf command change Directory Server over LDAP. Yet, both also spare you much of the complexity of making configuration adjustments with LDAP modify operations.

Almost all Directory Server product documentation is devoted to Directory Server configuration. In Oracle Fusion Middleware Administration Guide for Oracle Directory Server Enterprise Edition, you find extensive instructions for accomplishing a variety of tasks using command line configuration tools. The Directory Service Control Center online help can help get you back on track when the Directory Service Control Center interface does not seem intuitive enough.

Data Storage in Directory Server

Directory Server manages many binary-tree databases to hold directory data. By default, database files are stored under instance-path/db/. In general, do not change or move these files.

If you examine the content of the instance-path/db/ directory, you find database log files. You also find subdirectories for each database managed by the server. For instance, instance-path/db/example/ holds data for the directory entries under dc=example,dc=com. When you examine the files, you find a number of database indexes, such as example_sn.db3 for surname attribute values. You also find a example_id2entry.db3 file containing directory entry information. You can configure Directory Server to encrypt the information in these files if necessary.

From the point of view of client applications, Directory Server presents the directory data stored as directory entries arranged in the directory information tree. Directory Server uses the attribute value indexes to retrieve entries quickly. You can configure which indexes Directory Server maintains.

For instructions on backing up directory data, see Chapter 8, Directory Server Backup and Restore, in Oracle Fusion Middleware Administration Guide for Oracle Directory Server Enterprise Edition. For instructions on configuring indexes, see Chapter 12, Directory Server Indexing, in Oracle Fusion Middleware Administration Guide for Oracle Directory Server Enterprise Edition. You can also back up directory data and configure indexes using Directory Service Control Center.

Data Structuring With the Directory Information Tree

The directory information tree (DIT) provides a way to structure directory data so that the data can be referred to by client applications.

DIT Terminology

A well-designed DIT provides the following:

The DIT structure follows the hierarchical LDAP model. The DIT organizes data, for example, by group, by people, or by geographical location. It also determines how data is partitioned across multiple servers.

DIT design has an impact on replication configuration and on how you use Directory Proxy Server to distribute data. If you want to replicate or distribute certain portions of a DIT, consider replication and the requirements of Directory Proxy Server at design time. Also, decide at design time whether you require access controls on branch points.

A DIT is defined in terms of suffixes, subsuffixes, and chained suffixes. A suffix is a branch or subtree whose entire contents are treated as a unit for administrative tasks. Indexing is defined for an entire suffix, and an entire suffix can be initialized in a single operation. A suffix is also usually the unit of replication. Data that you want to access and manage in the same way should be located in the same suffix. A suffix can be located at the root of the directory tree, where it is called a root suffix.

Because data can only be partitioned at the suffix level, an appropriate directory tree structure is required to spread data across multiple servers.

The following figure shows a directory with two root suffixes. Each suffix represents a separate corporate entity.

Figure 2–1 Two Root Suffixes in a Single Directory Server

Directory information tree with two root suffixes

A suffix might also be a branch of another suffix, in which case it is called a subsuffix. The parent suffix does not include the contents of the subsuffix for administrative operations. The subsuffix is managed independently of its parent. Because LDAP operation results contain no information about suffixes, directory clients are unaware of whether entries are part of root suffixes or subsuffixes.

The following figure shows a directory with a single root suffix and multiple subsuffixes for a large corporate entity.

Figure 2–2 One Root Suffix With Multiple Subsuffixes

Directory information tree with a single root suffix and multiple subsuffixes

A suffix corresponds to an individual database within the server. However, databases and their files are managed internally by the server and database terminology is not used.

In the special case of cascading chaining, the chained suffix might reference another chained suffix on the remote server, and so on. Each server forwards the operation and eventually returns the result to the server that handles the client’s request.

Data Replication Between Server Instances

Directory Server allows you to replicate directory data among as many server instances as necessary. Directory Server replication works as an LDAP extended operation that replays update operations from one server to another. The protocol for Directory Server replication is optimized to work quickly over the network. The protocol is also optimized to resolve conflicts when the same data is modified simultaneously on two different server instances.

The unit of Directory Server replication is the suffix. A replication agreement between two servers handles all the directory entries under a base entry in the directory information tree, such as dc=example,dc=com. Each agreement to replicate is set up point to point. On one hand, point to point agreements prevent replication from single points of failure when the network becomes partitioned. On the other hand, point to point agreements can be complex to manage as the number of replicas increases. Luckily, Directory Service Control Center handles much of the complexity for you. Directory Service Control Center allows you to manage groups of replicas that provide a common directory service.

You can configure timing, priority, and which data is replicated. You can also configure some servers, called masters, to accepts both updates and lookups. You can configure other servers, called consumers, to accept only lookups. In addition, you can publish update information over LDAP for client applications that must follow updates as they happen. For further explanation of replication, see Chapter 7, Directory Server Replication. For instructions on configuring replication, see Chapter 10, Directory Server Replication, in Oracle Fusion Middleware Administration Guide for Oracle Directory Server Enterprise Edition.

Access Control in Directory Server

Directory Server offers an access control mechanism that works through aci attributes placed on directories entries. ACI stands for Access Control Instruction.

ACIs are evaluated based on a user's bind identity. ACIs can be evaluated therefore for all users who can bind to the directory. ACIs can also be applied for anonymous users who did not provide bind credentials. Rules about the bind identity can specify not only which users, but also which systems the users connect from, what time of day they connect, or what authentication method they use.

You configure an ACI to apply to the entries in its scope. Entries that can be in scope include entries on the branch of the directory information tree starting with the entry holding the ACI. Directory Server allows you to configure ACIs to be applied according to a number of different criteria. Directory Server also lets you configure ACIs not only to allow access, but also to deny access.

ACIs can specify which operations are allowed and denied. For example, you typically allow many users to read information, but only a few to update and add directory data.

For further explanation of access control in Directory Server, see How Directory Server Provides Access Control. For instructions on configuring access control, see Chapter 6, Directory Server Access Control, in Oracle Fusion Middleware Administration Guide for Oracle Directory Server Enterprise Edition.

Chapter 3 Directory Server LDAP URLs

One way to express an LDAP query is to use a URL to specify the Directory Server host machine and the DN or filter for the search. Directory Server responds to queries sent as LDAP URLs and returns an HTML page representing the results. In this way, if anonymous searching is permitted, web browsers can perform searches of the directory. You can also use LDAP URLs to specify target entries when you manage Directory Server referrals or when you access control instructions.

For information about LDAP URLs, see the following sections:

Components of an LDAP URL

LDAP URLs have the following syntax:

ldap[s]://hostname:port/base_dn?attributes?scope?filter

When ldap:// is specified, standard LDAP is used to connect to the LDAP servers. When ldaps:// is specified, LDAP over SSL is used to connect to the LDAP server.

Table 3–1 LDAP URL Components

Component 

Description 

hostname

Name (or IP address in dotted format) of the LDAP server. For example: 

ldap.example.com or 192.168.1.100

port

Port number of the LDAP server. 

If no port is specified, the standard LDAP port (389) or LDAPS port (636) is used. 

base_dn

Distinguished name (DN) of an entry in the directory. This DN identifies the entry that is the starting point of the search.  

If no base DN is specified, the search starts at the root of the directory tree. 

attributes

The attributes to be returned. To specify more than one attribute, use commas to separate the attributes. For example, "cn,mail,telephoneNumber".

If no attributes are specified in the URL, all attributes are returned. 

scope

The scope of the search. The scope can be one of these values: 

  • base retrieves information about the distinguished name (base_dn) specified in the URL only.

  • one retrieves information about entries one level below the distinguished name (base_dn) specified in the URL. The base entry is not included in this scope.

  • sub retrieves information about entries at all levels below the distinguished name (base_dn) specified in the URL. The base entry is included in this scope.

    If no scope is specified, the server performs a base search.

filter

Search filter to apply to entries within the specified scope of the search. 

If no filter is specified, the server uses the filter objectClass=*.

The following components are identified by their positions in the URL: attributes, scope, and filter are. If you do not want to specify a component, you must include a question mark to delimit the field. Two consecutive question marks, ??, indicate that no attributes have been specified.

For example, to specify a subtree search starting from "dc=example,dc=com" that returns all attributes for entries matching "(sn=Jensen)", use the following LDAP URL.

ldap://ldap.example.com/dc=example,dc=com??sub?(sn=Jensen)

Because no specific attributes are identified in the URL, all attributes are returned in the search.

Escaping Unsafe Characters

Unsafe characters in a URL must be represented by a special sequence of characters. The following table lists the characters that are unsafe within URLs, and provides the associated escape characters to use in place of the unsafe character.

Table 3–2 Characters That Are Unsafe Within URLs

Unsafe Character 

Escape Characters 

space 

%20 

< 

%3c 

\> 

%3e 

" 

%22 

# 

%23 

% 

%25 

{ 

%7b 

} 

%7d 

| 

%7c 

\\ 

%5c 

^ 

%5e 

~ 

%7e 

[ 

%5b 

] 

%5d 

” 

%60 

Examples of LDAP URLs

The syntax for LDAP URLs does not include any means for specifying credentials or passwords. Search request initiated through LDAP URLs are unauthenticated (anonymous), unless the LDAP client that supports LDAP URLs provides an authentication mechanism. This section gives examples of LDAP URLs.

Example 3–1 Base Search for an Entry

The following LDAP URL specifies a base search for the entry with the distinguished name dc=example,dc=com.

ldap://ldap.example.com/dc=example,dc=com
Example 3–2 Retrieving postalAddress Attribute of an Entry

The following LDAP URL retrieves the postalAddress attribute of the entry with the DN dc=example,dc=com:

ldap://ldap.example.com/dc=example,dc=com?postalAddress
Example 3–3 Retrieving cn and mail Attributes of an Entry

The following LDAP URL retrieves the cn, and mail attributes of the entry for Barbara Jensen.

ldap://ldap.example.com/cn=Barbara%20Jensen,dc=example, dc=com?cn,mail
Example 3–4 Retrieving the Surname Jensen Under dc=example,dc=com

The following LDAP URL specifies a search for entries that have the surname Jensen and are at any level under dc=example,dc=com:

ldap://ldap.example.com/dc=example,dc=com??sub?(sn=Jensen)
Example 3–5 Retrieving the Object Class for all Entries One Level Under dc=example,dc=com

The following LDAP URL specifies a search for the object class for all entries one level under dc=example,dc=com:

ldap://ldap.example.com/dc=example,dc=com?objectClass?one

Chapter 4 Directory Server LDIF and Search Filters

Directory Server uses the LDAP Data Interchange Format (LDIF) to describe a directory and its entries in text format. LDIF can be used to build the initial directory database or to add large numbers of entries to a directory. LDIF can also be used to describe changes to directory entries. Most command-line utilities rely on LDIF for input or output.

All directory data is stored by using the UTF-8 encoding of Unicode, and, therefore, LDIF files must also be UTF-8 encoded.

This chapter also provides information about searching the directory, and LDAP search filters.

For information about LDIF and searching the directory, see the following sections:

LDIF File Format

LDIF files consist of one or more directory entries separated by a blank line. Each LDIF entry consists of the following parts:

The LDIF format is defined in RFC 2849.

The following example shows a basic directory entry in LDIF.

Example 4–1 A Directory Entry in LDIF

dn: distinguished_name
objectClass: object_class
objectClass: object_class
...
attribute_type[;subtype]: attribute_value
attribute_type[;subtype]: attribute_value
...

All other attributes and object classes are optional. Object classes and attributes can be specified in any order. The space after the colon is optional.

The following table describes the fields in a LDIF file.

Table 4–1 LDIF Fields

Field  

Definition  

[id]

Optional. A positive decimal number representing the entry ID. The database creation tools generate this ID for you. Never add or edit this value yourself. 

dn: distinguished_name

The distinguished name for the entry. 

objectClass: object_class

An object class to use with this entry. The object class identifies the types of attributes or schema that are allowed and required for the entry.  

attribute_type

A descriptive attribute to use with the entry. The attribute should be defined in the schema. 

[subtype]

Optional. A subtype of one of the following types: 

  • Language (attribute;lang-subtype) identifies the language in which the corresponding attribute value is expressed

  • Binary (attribute;binary) identifies whether the attribute value is binary

  • Pronunciation (attribute;phonetic) identifies whether the attribute value is a pronunciation of an attribute value

attribute_value

The attribute value to be used with the attribute type. 

The LDIF syntax for representing a change to an entry in the directory is different from the syntax described above.

Continuing Lines in LDIF

When you specify LDIF, you can break and continue a line or fold a line by indenting the continued portion of the line by one space. For example, the following two statements are identical:

dn: cn=Babs Jensen,dc=example,dc=com

dn: cn=Babs J
 ensen,dc=exam
 ple,dc=com

You are not required to break and continue LDIF lines. However, doing so can improve the readability of an LDIF file.

Binary Data in LDIF

You can represent binary data in LDIF by using one of the following methods:

Representing Binary Data by Using Standard LDIF Notation

The following example gives the standard LDIF notation of binary data:

jpegphoto:< file:/path/to/photo

In the example, the path is relative to the client, not to the server. To use standard notation, you do not need to specify the ldapmodify -b parameter. However, you must add the following line to the beginning of your LDIF file or to your LDIF update statements:

version:1

For example, you could use the ldapmodify command, as follows:


$ ldapmodify -D userDN -w passwd
version: 1
dn: cn=Barbara Jensen,ou=People,dc=example,dc=com
changetype: modify
add: userCertificate
userCertificate;binary:< file:BabsCert

Representing Binary Data by Using the ldapmodify -b Command

For backward compatibility with earlier versions of Directory Server, binary data can be represented by using the ldapmodify -b command. However, when possible, use the standard LDIF notation to represent binary data.

Directory Server accepts the ldapmodify command with the -b parameter and the following LDIF notation:

jpegphoto: /path/to/photo

This notation indicates that the ldapmodify command should read the referenced file for binary values if the attribute value begins with a slash.

Representing Binary Data by Using Base 64 Encoding

Base 64 encoded data is represented by the :: symbol, as shown in this example:

jpegPhoto:: encoded_data

In addition to binary data, the following values must be base 64 encoded:

Use the ldif command with the -b parameter to convert binary data to LDIF format, as follows.


$ ldif -b attributeName

For more information about how to use the ldif command, see the ldif(1) man page.

In the above example, attributeName is the name of the attribute to which you are supplying the binary data. The binary data is read from standard input and the results are written to standard output. Use redirection operators to select input and output files.

The command takes any input and formats it with the correct line continuation and appropriate attribute information. The command also assesses whether the input requires base–64 encoding. The following example takes a binary file containing a JPEG image and converts it into LDIF format for the attribute named jpegPhoto. The output is saved to out.ldif:


$ ldif -b jpegPhoto < aphoto.jpg > out.ldif

The -b option specifies that the utility should interpret the entire input as a single binary value. If the -b option is not present, each line is considered as a separate input value.

You can edit the output file to add the LDIF statements required to create or modify the directory entry that will contain the binary value. For example, you can open the file out.ldif in a text editor and add the following lines at the top of the file.

dn: cn=Barbara Jensen,ou=People,dc=example,dc=com
changetype: modify
add: jpegPhoto
jpegPhoto:: encoded_data

In this example, encoded_data represents the contents of the out.ldif file produced by the command.

Directory Entries in LDIF

This section covers the following topics:

Organization Entries in LDIF

Directories often have at least one organization entry. Typically the organization entry is the first, or topmost entry in the directory. The organization entry often corresponds to the suffix set for the directory. For example, a directory defined to use a suffix of o=example.com will probably have an organization entry named o=example.com.

The LDIF that defines an organization entry should appear as follows:

dn: distinguished_name
objectClass: top 
objectClass: organization
o: organization_namelist_of_optional_attributes...

The following is an example organization entry in LDIF format:

dn: o=example.com
objectclass: top
objectclass: organization
o: example.com Corporation
description: Fictional company for example purposes
telephonenumber: 555-5555

The organization name in the following example uses a comma:

dn: o=example.com Chile\, S.A.
objectclass: top
objectclass: organization
o: example.com Chile\, S.A.
description: Fictional company for example purposes
telephonenumber: 555-5556

The following table describes each element of the organization entry.

Table 4–2 Organization Entries in LDIF

LDIF Element  

Description  

dn: distinguished_name

Required. Specifies the distinguished name for the entry.  

objectClass: top

Required. Specifies the top object class. 

objectClass: organization

Specifies the organization object class. This line defines the entry as an organization.  

o: organization_name

Specifies the organization’s name. If the organization name includes a comma, you must escape the comma by a single backslash or the entire organization argument must be enclosed in quotation marks. However, if you are working with a UNIX shell, you must also escape the backslash. Therefore, you must use two back slashes. For example, to set the suffix to example.com Bolivia, S.A. you would enter o: example.com Bolivia\, S.A..

list_of_attributes

Specifies the list of optional attributes that you want to maintain for the entry.  

Organizational Unit Entries in LDIF

In a directory tree, an organizational unit represents a major subdirectory. A directory tree usually contains more than one organizational unit. An LDIF file that defines an organizational unit entry must appear as follows:

dn: distinguished_name
objectClass: top
objectClass: organizationalUnit
ou: organizational_unit_namelist_of_optional_attributes...

The following example shows an organizational unit entry in LDIF format:

dn: ou=people, o=example.com
objectclass: top
objectclass: organizationalUnit
ou: people
description: Fictional organizational unit for example purposes

The following table defines each element of the organizational unit entry.

Table 4–3 Organizational Unit Entries in LDIF

LDIF Element  

Description  

dn: distinguished_name

Required. Specifies the distinguished name for the entry.  

If there is a comma in the DN, the comma must be escaped with a backslash (\). For example: 

dn: ou=people,o=example.com Bolivia\,S.A.

objectClass: top

Required. Specifies the top object class.

objectClass: organizationalUnit

Specifies the organizationalUnit object class. This line defines the entry as an organizationalUnit.

ou: organizational_unit_name

Specifies an attribute containing the name of the organizational unit. 

list_of_attributes

Specifies the list of optional attributes that maintain for the entry.  

Organizational Person Entries in LDIF

The majority of the entries in a directory represent organizational people. In LDIF, the definition of an organizational person is as follows:

dn: distinguished_name
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
cn: common_name 
sn: surname
list_of_optional_attributes

The following example shows an organizational person entry in LDIF format:

dn: uid=bjensen,ou=people,o=example.com
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: Babs Jensen
sn: Jensen
givenname: Babs
uid: bjensen
ou: Marketing
ou: people
description: Fictional person for example purposes
telephonenumber: 555-5557
userpassword: {sha}dkfljlk34r2kljdsfk9

The following table defines each element of the LDIF person entry.

Table 4–4 Organizational Person Entries in LDIF

LDIF Element  

Description  

dn: distinguished_name

Required. Specifies the distinguished name for the entry. 

If there is a comma in the DN, the comma must be escaped with a backslash (\). For example, dn:uid=bjensen,ou=people,o=example.com Bolivia\,S.A.

objectClass: top

Required. Specifies the top object class.

objectClass: person

Specifies the person object class. This object class specification should be included because many LDAP clients require it during search operations for a person or an organizational person.

objectClass: organizationalPerson

Specifies the organizationalPerson object class. This object class specification should be included because some LDAP clients require it during search operations for an organizational person.

objectClass: inetOrgPerson

Specifies the inetOrgPerson object class. The inetOrgPerson object class is recommended for the creation of an organizational person entry because this object class includes the widest range of attributes. The uid attribute is required by this object class, and entries that contain this object class are named based on the value of the uid attribute.

cn: common_name

Required. Specifies the person’s common name which is the full name commonly used by the person. For example, cn: Bill Anderson.

sn: surname

Required. Specifies the person’s surname, or last name. For example, sn: Anderson.

list_of_attributes

Specifies the list of optional attributes that you maintain for the entry.  

Guidelines for Defining Directories by Using LDIF

Follow these guidelines to create a directory by using LDIF.

The following example shows an LDIF file with one organization entry, two organizational unit entries, and three organizational person entries.

Example 4–2 Example LDIF File With Entries for Organization, Organizational Units, and Organizational Person

dn: o=example.com Corp
objectclass: top
objectclass: organization
o: example.com Corp
description: Fictional organization for example purposes
dn: ou=People,o=example.com Corp
objectclass: top
objectclass: organizationalUnit
ou: People
description: Fictional organizational unit for example purposes
tel: 555-5559

dn: cn=June Rossi,ou=People,o=example.com Corp
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
cn: June Rossi
sn: Rossi
givenName: June
mail: rossi@example.com
userPassword: {sha}KDIE3AL9DK
ou: Accounting
ou: people
telephoneNumber: 2616
roomNumber: 220

dn: cn=Marc Chambers,ou=People,o=example.com Corp
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
cn: Marc Chambers
sn: Chambers
givenName: Marc
mail: chambers@example.com
userPassword: {sha}jdl2alem87dlacz1
telephoneNumber: 2652
ou: Manufacturing
ou: People
roomNumber: 167

dn: cn=Robert Wong,ou=People,o=example.com Corp
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
cn: Robert Wong
cn: Bob Wong
sn: Wong
givenName: Robert
givenName: Bob
mail: bwong@example.com
userPassword: {sha}nn2msx761
telephoneNumber: 2881
roomNumber: 211
ou: Manufacturing
ou: people

dn: ou=Groups,o=example.com Corp
objectclass: top
objectclass: organizationalUnit
ou: groups
description: Fictional organizational unit for example purposes

Storing Information in Multiple Languages

For directories that contains a single language, it is not necessary to do anything special to add a new entry to the directory. However, for multinational organizations, it can be necessary to store information in multiple languages so that users in different locales can view directory information in their own language.

When information is represented in multiple languages, the server associates language tags with attribute values. When a new entry is added, attribute values used in the RDN (Relative Distinguished Name) must be added without any language codes.

Multiple languages can be stored within a single attribute. The attribute type is the same, but each attribute value has a different language code. The language tag has no effect on how the string is stored within the directory. All object class and attribute strings are stored using UTF-8.

For a list of the languages supported by Directory Server and their associated language tags, refer to Identifying Supported Locales.

For example, the example.com Corporation has offices in the United States and France. The company wants employees to be able to view directory information in their native language. When a directory entry is added for a new employee, Babs Jensen, the administrator creates the entry in LDIF. The administrator creates values for the personalTitle attribute in English and French, as follows:

dn: uid=bjensen,ou=people, o=example.com Corp
objectclass: top
objectclass: person
objectclass: organizationalPerson
name: Babs Jensen
cn: Babs Jensen
sn: Jensen
uid: bjensen
personalTitle: Miss
personalTitle;lang-en: Miss
personalTitle;lang-fr: Mlle
preferredLanguage: fr

Users accessing this directory entry with an LDAP client with the preferred language set to English will see the personal title Miss. Users accessing the directory with an LDAP client with the preferred language set to French will see the title Mlle.

Guidelines for Providing LDIF Input

All directory data is stored using the UTF-8 encoding of Unicode. Therefore, any LDIF input you provide must also be UTF-8 encoded. The LDIF format is described in detail in “LDAP Data Interchange Format Reference” in the Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

Consider the following points when you provide LDIF input:

Terminating LDIF Input on the Command Line

The ldapmodify and ldapdelete utilities read the LDIF statements that you enter after the command in exactly the same way as if they were read from a file. When you finish providing input, enter the character that your shell recognizes as the end of file (EOF) escape sequence.

Typically, the EOF escape sequence is Control-D (^D).

The following example shows how to terminate input to the ldapmodify command:

prompt\> ldapmodify -h host -p port -D cn=admin,cn=Administrators,cn=config -w -
 dn: cn=Barry Nixon,ou=People,dc=example,dc=com
changetype: modify
delete: telephonenumber
^D
prompt\>

For simplicity and portability, examples in this document do not show prompts or EOF sequences.

Using Special Characters

When entering command options on the command line, you may need to escape characters that have special meaning to the command-line interpreter, such as space ( ), asterisk (*), backslash (\\), and so forth. For example, many DNs contain spaces, and you must enclose the value in double quotation marks ("") for most UNIX shells:

Depending on your command-line interpreter, you should use either single or double quotation marks for this purpose. Refer to your operating system documentation for more information.

Note that LDIF statements after the ldapmodify command are being interpreted by the command, not by the shell, and therefore do not need special consideration.

Using Attribute OIDs

Attribute OIDs are by default not supported in attribute names. This was not the case in some previous versions of Directory Server. If you used attribute OIDs as attribute names in a previous version of Directory Server, you must set the attribute nsslapd-attribute-name-exceptions to on for the attribute OIDs to be accepted.

Schema Checking

When adding or modifying an entry, the attributes you use must be required or allowed by the object classes in your entry, and your attributes must contain values that match their defined syntax.

When modifying an entry, Directory Server performs schema checking on the entire entry, not only the attributes being modified. Therefore, the operation may fail if any object class or attribute in the entry does not conform to the schema.

Ordering of LDIF Entries

In any sequence of LDIF text for adding entries, either on the command line or in a file, parent entries must be listed before their children. This way, when the server process the LDIF text, it will create the parent entries before the children entries.

For example, if you want to create entries in a People subtree that does not exist in your directory, then list an entry representing the People container before the entries within the subtree: 

dn: dc=example,dc=com
dn: ou=People,dc=example,dc=com
...
People subtree entries...
dn: ou=Group,dc=example,dc=com
...
Group subtree entries...

You can use the ldapmodify command-line utility to create any entry in the directory, however, the root of a suffix or subsuffix is a special entry that must be associated with the necessary configuration entries.

Managing Large Entries

Before adding or modifying entries with very large attribute values, you may need to configure the server to accept them. To protect against overloading the server, clients are limited to sending data no larger than 2 MB by default.

If you add an entry larger than this, or modify an attribute to a value which is larger, the server will refuse to perform the operation and immediately close the connection. For example, binary data such as multimedia contents in one or more attributes of an entry may exceed this limit.

Also, the entry defining a large static group may contain so many members that their representation exceeds the limit. However, such groups are not recommended for performance reasons, and you should consider redesigning your directory structure.

Error Handling

The command-line tools process all entries or modifications in the LDIF input sequentially. The default behavior is to stop processing when the first error occurs. Use the -c option to continue processing all input regardless of any errors. You will see the error condition in the output of the tool.

In addition to the considerations listed above, common errors are:

Searching the Directory

You can locate entries in a directory using any LDAP client. Most clients provide some form of search interface that enables you to search the directory and retrieve entry information.

The access control that has been set in your directory determines the results of your searches. Common users typically do not “see” much of the directory, and directory administrators have full access to all data, including configuration.

Searching the Directory With ldapsearch

You can use the ldapsearch command-line utility to locate and retrieve directory entries. Note that the ldapsearch utility described in this section is not the utility provided with the Solaris platform, but is part of the Directory Server Resource Kit.

This utility opens a connection to the server with a specified a user identity (usually a distinguished name) and password, and locates entries based on a search filter. Search scopes can include a single entry, an entry’s immediate subentries, or an entire tree or subtree.

Search results are returned in LDIF format.

ldapsearch Command-Line Format

When you use ldapsearch, you must enter the command using the following format:

ldapsearch [optional_options] [search_filter] [optional_list_of_attributes]

where

Note –

If you want operational attributes returned as a result of a search operation, you must explicitly specify them in the search command. To retrieve regular attributes in addition to explicitly specified operational attributes, use an asterisk (*) in the list of attributes in the ldapsearch command.

Using Special Characters

When using the ldapsearch command-line utility, you may need to specify values that contain characters that have special meaning to the command-line interpreter (such as space [ ], asterisk [*], backslash [\\], and so forth). When you specify special characters, enclose the value in quotation marks (“”). For example:

-D "cn=Charlene Daniels,ou=People,dc=example,dc=com"

Depending on your command-line interpreter, use either single or double quotation marks for this purpose. Refer to your shell documentation for more information.

ldapsearch Examples

In the next set of examples, the following assumptions are made:

Returning All Entries

Given the previous information, the following call will return all entries in the directory:

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config
 -b "dc=example,dc=com" -s sub "(objectclass=*)"

"(objectclass=*)" is a search filter that matches any entry in the directory.

Specifying Search Filters on the Command Line

You can specify a search filter directly on the command line. If you do this, be sure to enclose your filter in quotation marks (“filter”). Also, do not specify the -f option.

For example:

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 -b "dc=example,dc=com" "(cn=Charlene Daniels)"

Searching the Root DSE Entry

The root DSE is a special entry that contains information related to the current server instance, such as a list of supported suffixes, available authentication mechanisms, and so forth. You can search this entry by supplying a search base of “”. You must also specify a search scope of base and a filter of "(objectclass=*)".

For example:

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 -b "" -s base "(objectclass=*)"

Searching the Schema Entry

Directory Server stores all directory server schema in the special cn=schema entry. This entry contains information on every object class and attribute defined for your directory server.

You can examine the contents of this entry as follows:

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config
 -b "cn=schema" -s base "(objectclass=*)"
Note –

For strict compliance, the location of the schema subentry for a given entry is specified by the subschemaSubentry operational attribute. In this version of Directory Server, the value of this attribute is always cn=schema.

Using LDAP_BASEDN

To make searching easier, you can set your search base using the LDAP_BASEDN environment variable. Doing this allows you to skip specifying the search base with the -b option (for information on how to set environment variables, see the documentation for your operating system).

Typically, you set LDAP_BASEDN to your directory’s suffix value. Since your directory suffix is equal to the root, or topmost, entry in your directory, this causes all searches to begin from your directory’s root entry.

For example, if you have set LDAP_BASEDN to dc=example,dc=com, you can search for (cn=Charlene Daniels) in your directory using the following command-line call:

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 "(cn=Charlene Daniels)"

In this example, the default scope of sub is used because the -s option was not used to specify the scope.

Displaying Subsets of Attributes

The ldapsearch command returns all search results in LDIF format. By default, ldapsearch returns the entry’s distinguished name and all of the attributes that you are allowed to read. You can set up the directory access control such that you are allowed to read only a subset of the attributes on any given directory entry.) Only operational attributes are not returned. If you want operational attributes returned as a result of a search operation, you must explicitly specify them in the search command. For more information on operational attributes, refer to the TODO: No more AdminServerAdminGuide.

Suppose you do not want to see all of the attributes returned in the search results. You can limit the returned attributes to just a few specific attributes by specifying the ones you want on the command line immediately after the search filter. For example, to show the cn and sn attributes for every entry in the directory, use the following command:

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 "(objectclass=*)" sn cn

This example assumes you set your search base with LDAP_BASEDN.

Searching Multi-Valued Attributes

During a search, Directory Server does not necessarily return multi-valued attributes in sorted order. For example, suppose you want to search for configuration attributes on cn=config requiring that the server be restarted before changes take effect.

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 -b cn=config "(objectclass=*)" nsslapd-requiresrestart

The following result is returned:

dn: cn=config
nsslapd-requiresrestart: cn=config:nsslapd-port
nsslapd-requiresrestart: cn=config:nsslapd-secureport
nsslapd-requiresrestart: cn=config:nsslapd-plugin
nsslapd-requiresrestart: cn=config:nsslapd-changelogdir
nsslapd-requiresrestart: cn=config:nsslapd-changelogsuffix
nsslapd-requiresrestart: cn=config:nsslapd-changelogmaxentries
nsslapd-requiresrestart: cn=config:nsslapd-changelogmaxage
nsslapd-requiresrestart: cn=config:nsslapd-db-locks
nsslapd-requiresrestart: cn=config:nsslapd-return-exact-case
nsslapd-requiresrestart: cn=config,cn=ldbm database,cn=plugins,
  cn=config:nsslapd-allidsthreshold
nsslapd-requiresrestart: cn=config,cn=ldbm database,cn=plugins,
  cn=config:nsslapd-dbcachesize
nsslapd-requiresrestart: cn=config,cn=ldbm database,cn=plugins,
  cn=config:nsslapd-dbncache
nsslapd-requiresrestart: cn=config,cn=ldbm database,cn=plugins,
  cn=config:nsslapd-directory
nsslapd-requiresrestart: cn=encryption,cn=config:nssslsessiontimeout
nsslapd-requiresrestart: cn=encryption,cn=config:nssslclientauth
nsslapd-requiresrestart: cn=encryption,cn=config:nssslserverauth
nsslapd-requiresrestart: cn=encryption,cn=config:nsssl2
nsslapd-requiresrestart: cn=encryption,cn=config:nsssl3
...

As shown here, the nsslapd-requiresrestart attribute takes multiple values. These values are not, however, in sorted order. If you develop an application that requires multi-valued attributes in sorted order, make sure that your application performs the sort.

Using Client Authentication When Searching

This example shows user cdaniels searching the directory using client authentication:

ldapsearch -h myServer -p 636 -b "dc=example,dc=com"
  -N  "cdanielsscertname" -Z -W certdbpassword
  -P /home/cdaniels/certdb/cert.db "(givenname=Richard)"

LDAP Search Filters

Search filters select the entries to be returned for a search operation. They are most commonly used with the ldapsearch command-line utility. When you use ldapsearch, you can place multiple search filters in a file, with each filter on a separate line in the file, or you can specify a search filter directly on the command line.

For example, the following filter specifies a search for the common name Lucie Du Bois:

(cn=Lucie Du Bois)

This search filter returns all entries that contain the common name Lucie Du Bois. Searches for common name values are not case sensitive.

When the common name attribute has values associated with a language tag, all of the values are returned. Thus, the following two attribute values both match this filter:

cn: Lucie Du Bois
cn;lang-fr: Lucie Du Bois

Search Filter Syntax

The basic syntax of a search filter is:

(attribute operator value)

For example:

(buildingname\>=alpha)

In this example, buildingname is the attribute, \>= is the operator, and alpha is the value. You can also define filters that use different attributes combined together with Boolean operators.

Using Attributes in Search Filters

When searching for an entry, you can specify attributes associated with that type of entry. For example, when you search for people entries, you can use the cn attribute to search for people with a specific common name.

Examples of attributes that people entries might include:

Using Operators in Search Filters

The operators that you can use in search filters are listed in Table 4–5:

Table 4–5 Search Filter Operators

Search Type

Operator  

Description  

Equality

= 

Returns entries containing attribute values that exactly match the specified value. For example, cn=Bob Johnson

Substring

=string*string

Returns entries containing attributes containing the specified substring. For example, 

cn=Bob*cn=*Johnsoncn=*John*cn=B*John

(The asterisk (*) indicates zero (0) or more characters.) 

Greater than or equal to

\>= 

Returns entries containing attributes that are greater than or equal to the specified value. For example, 

buildingname \>= alpha

Less than or equal to

<= 

Returns entries containing attributes that are less than or equal to the specified value. For example, 

buildingname <= alpha

Presence

=* 

Returns entries containing one or more values for the specified attribute. For example, 

cn=*

telephonenumber=*

manager=*

Approximate

~= 

Returns entries containing the specified attribute with a value that is approximately equal to the value specified in the search filter. For example, 

cn~=suret

l~=san fransico

could return 

cn=sarette

l=san francisco

The Approximate operator is experimental and works only with English language strings. It does not work with non-ASCII based strings, such as Ja or Zn. 

Extended operators exist that extend searches to dn attributes (cn:dn:=John, for example) and provide support for internationalized searches.

Using OIDs in Search Filters

LDAPv3 enables you to build match operators and rules for a particular attribute. Matching rules define how to compare attribute values with a particular syntax. In other words, a matching rule defines how potentially matching attributes are compared. For example, a matching rule can define whether or not to take text case into account when comparing attributes.

When the rules are created, they can be referred to in a search filter.

For example, the following search filter compares entries containing the surname “Jensen” by using the matching rule designated by OID 2.5.13.5:

(sn:2.5.13.5:=Jensen)

The following example illustrates the use of the ":dn" notation to indicate that OID 2.5.13.5 should be used when making comparisons, and that the attributes of an entry\qs distinguished name should be considered part of the entry when evaluating the match:

(sn:dn:2.5.13.5:=Jensen)

Using Compound Search Filters

Multiple search filter components can be combined using Boolean operators expressed in prefix notation as follows:

(Boolean-operator(filter)(filter)(filter)...)

where Boolean-operator is any one of the Boolean operators listed in Table 4–6.

Boolean operators can be combined and nested together to form complex expressions, such as:

(Boolean-operator(filter)(Boolean-operator(filter)(filter)))

The Boolean operators available for use with search filters include the following:

Table 4–6 Search Filter Boolean Operators

Operator  

Symbol  

Description  

AND 

& 

All specified filters must be true for the statement to be true. For example, 

(&(filter)(filter)(filter)...)

OR 

| 

At least one specified filter must be true for the statement to be true. For example, 

(|(filter)(filter)(filter)...)

NOT 

! 

The specified statement must not be true for the statement to be true. Only one filter is affected by the NOT operator. For example, 

(!(filter))

The use of the NOT operator results in an unindexed search. 

Boolean expressions are evaluated in the following order:

Specifying Search Filters Using a File

You can enter search filters into a file instead of entering them on the command line. When you do this, specify each search filter on a separate line in the file. The ldapsearch command runs each search in the order in which it appears in the file.

For example, if the file contains:

(sn=Daniels)
(givenname=Charlene)

then ldapsearch first finds all the entries with the surname Daniels, and then all the entries with the given name Charlene. If an entry is found that matches both search criteria, the entry is returned twice.

For example, suppose you specified the previous search filters in a file named searchdb, and you set your search base using LDAP_BASEDN. The following returns all the entries that match either search filter:

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 -f searchdb

You can limit the set of attributes returned here by specifying the attribute names that you want at the end of the search line. For example, the following ldapsearch command performs both searches, but returns only the DN and the givenname and sn attributes of each entry:

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 -f searchdb sn givenname

Specifying Non 7-Bit ASCII Characters in Search Filters

Non 7-bit ASCII characters in search filters must be replaced with a representation of the character, where each byte of the UTF-8 encoding is preceded by a backslash. In UTF-8, characters are represented by a hexadecimal code for each byte.

For example, the character é has UTF-8 representation c3a9. Thus, in a search filter, you represent é as \\c3\\a9. So, to search for cn=Véronique Martin:

ldapsearch -h myServer -b "dc=example,dc=com" "(cn=V\\c3\\a9ronique Martin)"

The special characters listed in Table 4–7 must also be represented in this fashion when used in search filters.

Table 4–7 Special Characters in Search Filters

Special character  

Value With Special Character  

Example Filter  

* 

Five*Star

(cn=Five\\2aStar)

\\ 

c:\\File

(cn=\\5cFile)

() 

John (2nd)

(cn=John \\282nd\\29)

null 

0004

(bin=\\00\\00\\00\\04)

Escaped Characters in Distinguished Names within Search Filters

When using a DN in any part of Directory Server, you must escape commas and certain other special characters with a backslash (\\). If you are using a DN in a search filter, the backslash used for escaping special characters in DNs must be represented by \\5c. For example:

DN: cn=Julie Fulmer,ou=Marketing\\,Bolivia,dc=example,dc=com

DN in a search filter: ldapsearch -h myServer -b "dc=example,dc=com" "(manager=cn=Julie Fulmer,ou=Marketing\\5c,Bolivia,dc=example,dc=com)"

Search Filter Examples

The following filter searches for entries containing one or more values for the manager attribute. This is also known as a presence search:

(manager=*)

The following filter searches for entries containing the common name Ray Kultgen. This is also known as an equality search:

(cn=Ray Kultgen)

The following filter returns all entries that contain a description attribute that contains the substring X.500:

(description=*X.500*)

The following filter returns all entries whose organizational unit is Marketing and whose description field does not contain the substring X.500:

(&(ou=Marketing)(!(description=*X.500*)))

The following filter returns all entries whose organizational unit is Marketing and that have Julie Fulmer or Cindy Zwaska as a manager:

(&(ou=Marketing)(|(manager=cn=Julie Fulmer,ou=Marketing,
 dc=example,dc=com)(manager=cn=Cindy Zwaska,ou=Marketing,
 dc=example,dc=com)))

The following filter returns all entries that do not represent a person:

(!(objectClass=person))

Note that the previous filter will have a negative performance impact and should be used as part of a complex search. The following filter returns all entries that do not represent a person and whose common name is similar to printer3b:

(&(cn~=printer3b)(!(objectClass=person)))

Searching for Operational Attributes

If you want operational attributes returned as a result of a search operation, you must explicitly specify them in the search command.

$ ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 "(objectclass=*)" aci

To retrieve regular attributes in addition to explicitly specified operational attributes, specify “*” in addition to the operational attributes. For example:

$ ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 "(objectclass=*)" aci *

Chapter 5 Directory Server Security

For information about the security in Directory Server, see the following sections:

How Directory Server Provides Security

Directory Server provides security through a combination of the following methods:

How Directory Server Provides Access Control

Directory Server uses access control instructions (ACIs) to define what rights to grant or deny to requests from LDAP clients. When a directory server receives a request, it uses the ACIs defined in the server, and any authentication information provided by the user to allow or deny access to directory information. The server can allow or deny permissions such as read, write, search, or compare.

For information about ACIs in Directory Server, see the following sections:

Introduction to ACIs

ACIs are stored in the aci operational attribute. The aci attribute is available for use on every entry in the directory, regardless of whether the aci attribute is defined for the object class of the entry. The aci attribute is multi-valued, therefore multiple ACIs can be defined for the same portion of a directory.

ACIs can be used to control access to the following portions of a directory:

ACIs can be used to define access for the following users:

Scope and Hierarchy in ACIs

ACIs can be created at any node in a directory tree, including the root DSE.

The scope of an ACI can be the target entry, the target entry and its immediate children, or the target entry and all of its children. When no scope is specified, the ACI applies to the target entry and all of its children.

When a server evaluates access permissions to an entry, it verifies the ACIs for the entry and the ACIs for the parent entries back up to the base of the entry’s root suffix.

Access to an entry in a server must be explicitly granted by an ACI. By default, ACIs define anonymous read access and allow users to modify their own entries, except for attributes needed for security. If no ACI applies to an entry, access is denied to all users except the Directory Manager.

Access granted by an ACI is allowed unless any other ACI in the hierarchy denies it. ACIs that deny access, no matter where they appear in the hierarchy, take precedence over ACIs that allow access to the same resource.

The Directory Manager is the only privileged user to whom access control does not apply. When a client is bound to the directory as the Directory Manager, the server does not evaluate any ACIs before performing operations.

In previous versions of Directory Server, ACIs could not be added or deleted directly under the root DSE. Now this limitation has been removed in Directory Server.

ACI Limitations

The following restrictions apply to ACIs

Default ACIs

The following default ACIs are defined on the root DSE:

ACIs and Replication

ACIs are stored as attributes of entries. Therefore, if an entry that contains ACIs is part of a replicated suffix, the ACIs are replicated like any other attribute.

ACIs are always evaluated locally, on the directory server that services the incoming LDAP requests.

When a consumer server receives an update request, the consumer server returns a referral to the master server for evaluation of whether the request can be serviced on the master.

Effective Rights

The effective rights feature can be used to obtain the following information:

To use the effective rights feature, you must have the access control rights to use the effective rights control and read access to the aclRights attribute.

If a proxy control is attached to an effective rights control-based search operation, the effective rights operation is authorized as the proxy user. Therefore the proxy user needs to have the right to use the effective rights control. The entries that the proxy user has the right to search and view are returned. For more information, see Chapter 6, Directory Server Access Control, in Oracle Fusion Middleware Administration Guide for Oracle Directory Server Enterprise Edition.

Tuning Access Control Instructions

Directory Server offers performance and scalability improvements for Access Control Instructions. The improvements include better memory management. The improvements also include support for macro ACIs. Improvements notwithstanding, Directory Server uses significant system resources to evaluate complex ACIs. Extensive use of complex ACIs can therefore negatively impact performance.

Macro ACIs help you limit the number of ACIs used. By limiting the number of ACIs, you render access control easier to manage and reduce the load on the system. Macros are placeholders that represent a DN, or a portion of a DN, in an ACI. A macro can be used in an ACI target, in an ACI bind rule, or in both. When Directory Server receives a request, it checks which ACI macros match against the resource targeted for the resulting operation. If a macro matches, Directory Server replaces it with the value of the actual DN. Directory Server then evaluates the ACI normally.

Testing has demonstrated that a Directory Server instance can support more than 50,000 ACIs. Nevertheless, keep the number of ACIs as small as possible. Keeping the number of ACIs small limits negative impact on performance. Keeping the number small also reduces the complexity of managing access controls. For deployments involving complex ACI environments, consider using Directory Proxy Server to provide some access control features.

How Directory Server Provides Authentication

Authentication is the process of confirming an identity. In network interactions, authentication involves the confident identification of one party by another party. Network interactions typically take place between a client, such as browser software running on a personal computer, and a server, such as the software and hardware used to host a Web site. Client authentication refers to the confident identification of a client by a server; server authentication refers to the confident identification of a server by a client.

For information about authentication, see the following sections:

Anonymous Access

Anonymous access lets a user bind to the directory without providing authentication credentials. With access control, you can give anonymous users whatever privileges you choose. Often, anonymous users are allowed to read non-sensitive data from the directory, such as names, telephone numbers, and email addresses.

You can also restrict the privileges of anonymous access, or limit anonymous access to a subset of attributes that contain address book information. Anonymous access should not be allowed for sensitive data.

In cases where anonymous users have access to something, you may want to prevent users who fail to bind properly nevertheless being granted access as anonymous. See the require-bind-pwd-enabled in server(5dsconf) for more information.

Password-Based Authentication

Simple password authentication offers an easy way of authenticating users. In password authentication, the user must supply a password for each server, and the administrator must keep track of the name and password for each user, typically on separate servers.

Steps in Password-Based Authentication

Figure 5–1 shows the steps involved in authenticating a client by using a name and password. The figure assumes the following points.

Figure 5–1 Password-Based Authentication

Figure shows password-based authentication.

    In Figure 5–1, password authentication is performed in the following steps.

  1. The user enters a name and password.

    For the LDAP bind to Directory Server, the client application must bind with a Distinguished Name. Therefore the client application may use the name entered by the user to retrieve the DN.

  2. The client sends the DN and password across the network.

  3. The server determines whether the password sent from the client matches the password stored for the entry with the DN sent from the client.

    If so, the server accepts the credentials as evidence authenticating the user identity.

  4. The server determines whether the identified user is permitted to access the requested resource.

    If so, the server allows the client to access the resource.

Password Policy

A password policy is a set of rules that govern how passwords are administered in a system. Directory Server supports multiple password policies. The password policy can be configured to suit the security requirements of your deployment.

Instances of Directory Server are created with a default password policy.

Types of Password Policy

Directory Server provides the following password policies.

Default password policy

The default password policy is defined in the configuration entry cn=PasswordPolicy,cn=config. The default password policy applies to all accounts in the directory except for the directory manager.

The parameters of the default policy can be modified to override the default settings. However, because the default password policy is part of the configuration for the instance, modifications to the default password policy cannot be replicated.

Specialized password policy

A password policy can be configured for an individual user or for set of users by using the CoS and roles features. However, specialized password policies can not be applied to static groups.

A specialized password policy is defined in a subentry in the directory tree. Like the default password policy, the specialized password policy uses the pwdPolicy object class. For example, the following entry defines a specialized password policy:


dn: cn=TempPolicy,dc=example,dc=com
objectClass: top
objectClass: pwdPolicy
objectClass: LDAPsubentry
cn: TempPolicy
pwdCheckQuality: 2
pwdLockout: on
pwdLockoutDuration: 300
pwdMaxFailure: 3
pwdMustChange: on

A specialized password policy can be assigned to a single user account or can be assigned to a set of users by using roles. For example, in the following entry the password policy defined in cn=TempPolicy,dc=example,dc=com is assigned to the pwdPolicySubentry attribute of the user entry:


dn: uid=dmiller,ou=people,dc=example,dc=com
objectClasaccess controls: person
objectClass: top
sn: miller
cn: david
userPassword: secret12
pwdPolicySubentry: cn=TempPolicy,dc=example,dc=com

When referenced by a user entry, a specialized password policy overrides the default password policy.

Because specialized password policies are defined the directory data, they can be replicated.

Configuration of Password Policy

For information about how to configure password policy, see Chapter 7, Directory Server Password Policy, in Oracle Fusion Middleware Administration Guide for Oracle Directory Server Enterprise Edition.

For information about the attributes used to configure password policies, see the pwpolicy(5dssd) man page.

Proxy Authorization

Proxy authorization allows requests from clients to be processed with a proxy identity instead of the identity of the client. A client, binding with its own identity is granted, through proxy authorization, the rights of a proxy user. The Access Control Instructions (ACIs) of the proxy user, not the ACIs of the client, are evaluated to allow or deny the operation.

Before performing an operation with proxy authorization, the account of the proxy user is validated. If the proxy user account is locked out, inactivated, if the password has been reset or has expired the client operation is aborted.

By using proxy authorization, an LDAP application can use a single bind to service multiple users who are making requests against Directory Server. Instead of having to bind and authenticate for each user, the client application binds to Directory Server and uses proxy rights.

The following conditions must be satisfied in order to use proxy authorization:

The following sample shows the user ClientApplication performing a search operation by using the Administrator proxy identity:


$ ldapsearch \
-D "uid=ClientApplication,ou=Applications,dc=example,dc=com" \
-w password \
-y "uid=Administrator,ou=Administrators,dc=example,dc=com" ...

Note that the client binds as itself, but is granted the privileges of the proxy entry. The client does not need the password of the proxy entry.

Proxy rights can be granted to any user except the Directory Manager.

For information about how to configure proxy authorization, see Proxy Authorization in Oracle Fusion Middleware Administration Guide for Oracle Directory Server Enterprise Edition.

Account Inactivation

A user account or a set of accounts can be inactivated temporarily or indefinitely by using the dsutil account-inactivate command. See dsutil(1M).

When the account is inactivated, the user cannot bind to Directory Server. This feature is called account inactivation.

User accounts and roles can be inactivated. When a role is inactivated, the members of the role are inactivated, not the role itself.

For information about how to configure account inactivation, see Manually Locking Accounts in Oracle Fusion Middleware Administration Guide for Oracle Directory Server Enterprise Edition.

Global Account Lockout

Depending on the password policy settings, a client account can be locked out of an account when the number of failed bind attempts exceeds the number of allowed bind attempts. In a replicated topology the client is locked out of all instances of Directory Server, not just the instance to which the client was attempting to bind. This feature is called global account lockout.

In versions of Directory Server prior to Directory Server 6, account lockout was based on integer counters. By default, these counters were not replicated.

In this version of the product, bind failures are recorded by using timestamps. By default, the timestamps are replicated, and prioritized replication is used to replicate updates to the lockout data that are caused by failed bind requests.

Global account lockout can be used in the following scenarios:

Certificate-based Authentication

For information about client authentication with certificates, see the following sections:

Introduction to Certificate-based Authentication

Figure 5–2 shows how certificates and the SSL protocol are used together for authentication. To authenticate a user to a server, a client digitally signs a randomly generated piece of data and sends both the certificate and the signed data across the network. For the purposes of this discussion, the digital signature associated with some data can be thought of as evidence provided by the client to the server. The server authenticates the user’s identity on the strength of this evidence.

Like for password-based authentication illustrated in Figure 5–1, Figure 5–2 assumes that the user has already decided to trust the server and has requested a resource. The server has requested client authentication in the process of evaluating whether to grant access to the requested resource.

Figure 5–2 Certificate-Based Authentication

Figure shows certificate-based authentication

Unlike for password-based authentication illustrated in Figure 5–1, Figure 5–2 requires the use of SSL. In Figure 5–2 it is assumed that the client has a valid certificate that can be used to identify the client to the server.

Certificate-based authentication is generally considered preferable to password-based authentication because it is based on what the user has, the private key, as well as what the user knows, the password that protects the private key. However, it’s important to note that these two assumptions are true only if unauthorized personnel have not gained access to the user’s machine or password, the password for the client software’s private key database has been set, and the software is set up to request the password at reasonably frequent intervals.

Note –

Neither password-based authentication nor certificate-based authentication address security issues related to physical access to individual machines or passwords. Public-key cryptography can only verify that a private key used to sign some data corresponds to the public key in a certificate. It is the user’s responsibility to protect a machine’s physical security and to keep the private-key password secret.

Certificates replace the authentication portion of the interaction between the client and the server. Instead of requiring a user to send passwords across the network throughout the day, single sign-on requires the user to enter the private-key database password just once, without sending it across the network. For the rest of the session, the client presents the user’s certificate to authenticate the user to each new server it encounters. Existing authorization mechanisms based on the authenticated user identity are not affected.

Certificates and Certificate Authorities (CA)

A certificate is an electronic document that identifies an individual, a server, a company, or some other entity. A certificate also associates that identity with a public key. Like a driver’s license, a passport, or other commonly used personal IDs, a certificate provides generally recognized proof of someone's or something's identity.

Certificate authorities, CAs, validate identities and issue certificates. CAs can be independent third parties or organizations that run their own certificate-issuing server software. The methods used to validate an identity vary depending on the policies of a given CA. In general, before issuing a certificate, the CA must use its published verification procedures for that type of certificate to ensure that an entity requesting a certificate is in fact who it claims to be.

A certificate issued by a CA binds a particular public key to the name of the entity the certificate identifies, such as the name of an employee or a server. Certificates help prevent the use of fake public keys for impersonation. Only the public key certified by the certificate works with the corresponding private key possessed by the entity identified by the certificate.

In addition to a public key, a certificate always includes the name of the entity it identifies, an expiration date, the name of the CA that issued the certificate, a serial number, and other information. Most importantly, a certificate always includes the digital signature of the issuing CA. The CA’s digital signature allows the certificate to function as a “letter of introduction” for users who know and trust the CA but don’t know the entity identified by the certificate.

Any client or server software that supports certificates maintains a collection of trusted CA certificates. These CA certificates determine which other certificates the software can validate, in other words, which issuers of certificates the software can trust. In the simplest case, the software can validate only certificates issued by one of the CAs for which it has a certificate. It’s also possible for a trusted CA certificate to be part of a chain of CA certificates, each issued by the CA above it in a certificate hierarchy.

For information about CAs, see the following sections:

CA Hierarchies

In large organizations, it may be appropriate to delegate the responsibility for issuing certificates to several different certificate authorities. For example, the number of certificates required may be too large for a single CA to maintain; different organizational units may have different policy requirements; or it may be important for a CA to be physically located in the same geographic area as the people to whom it is issuing certificates.

It’s possible to delegate certificate-issuing responsibilities to subordinate CAs. The X.509 standard includes a model for setting up a hierarchy of CAs.

Figure 5–3 Hierarchy of Certificate Authorities

Figure shows a hierarchy of certificate authorities

In this model, the root CA is at the top of the hierarchy. The root CA’s certificate is a self-signed certificate. That is, the certificate is digitally signed by the same entity, the root CA, that the certificate identifies. The CAs that are directly subordinate to the root CA have CA certificates signed by the root CA. CAs under the subordinate CAs in the hierarchy have their CA certificates signed by the higher-level subordinate CAs.

Organizations have a great deal of flexibility in terms of the way they set up their CA hierarchies. Figure 5–3 shows just one example; many other arrangements are possible.

Certificate Chains

CA hierarchies are reflected in certificate chains. A certificate chain is a series of certificates issued by successive CAs. Figure 5–4 shows a certificate chain leading from a certificate that identifies some entity through two subordinate CA certificates to the CA certificate for the root CA (based on the CA hierarchy shown in the following figure).

Figure 5–4 Certificate Chain

Figure shows a certificate chain.

A certificate chain traces a path of certificates from a branch in the hierarchy to the root of the hierarchy. In a certificate chain, the following occur:

In Figure 5–4, the public key in the certificate for the USA CA can be used to verify the USA CA’s digital signature on the certificate for the Engineering CA.

Verifying a Certificate Chain

Certificate chain verification is the process of making sure a given certificate chain is well-formed, valid, properly signed, and trustworthy. Directory Server software uses the following steps to form and verify a certificate chain, starting with the certificate being presented for authentication:

  1. The certificate validity period is checked against the current time provided by the verifier’s system clock.

  2. The issuer’s certificate is located. The source can be either the verifier’s local certificate database (on that client or server) or the certificate chain provided by the subject (for example, over an SSL connection).

  3. The certificate signature is verified using the public key in the issuer certificate.

  4. If the issuer’s certificate is trusted by the verifier in the verifier’s certificate database, verification stops successfully here. Otherwise, the issuer’s certificate is checked to make sure it contains the appropriate subordinate CA indication in the Directory Server certificate type extension, and chain verification returns to step 1 to start again, but with this new certificate.

Figure 5–5 Verifying A Certificate Chain

Figure shows verification of a certificate chain.

Figure 5–5 shows what happens when only Root CA is included in the verifier’s local database. If a certificate for one of the intermediate CAs shown in Figure 5–6, such as Engineering CA, is found in the verifier’s local database, verification stops with that certificate, as shown in the following figure.

Figure 5–6 Verifying A Certificate Chain to an Intermediate CA

Figure shows verification of a certificate chain to an intermediate CA.

Expired validity dates, an invalid signature, or the absence of a certificate for the issuing CA at any point in the certificate chain causes authentication to fail. For example, the following figure shows how verification fails if neither the Root CA certificate nor any of the intermediate CA certificates are included in the verifier’s local database.

Figure 5–7 Certificate Chain That Cannot Be Verified

Figure shows verification of a certificate chain that cannot be verified.

For general information about the way digital signatures work, see Digital Signatures.

Types of Certificates

Directory Server uses the following types of certificate:

Client SSL certificates

Client SSL certificates are used to identify clients to servers via SSL (client authentication). Typically, the identity of the client is assumed to be the same as the identity of a human being, such as an employee in an enterprise. Client SSL certificates can also be used for form signing and as part of a single sign-on solution.

For example, a bank gives a customer a client SSL certificate that allows the bank’s servers to identify that customer and authorize access to the customer’s accounts. A company might give a new employee a client SSL certificate that allows the company’s servers to identify that employee and authorize access to the company’s servers.

Server SSL certificates

Server SSL certificates are used to identify servers to clients via SSL (server authentication). Server authentication may be used with or without client authentication. Server authentication is a requirement for an encrypted SSL session.

For example, internet sites that engage in electronic commerce usually support certificate-based server authentication, at a minimum, to establish an encrypted SSL session and to assure customers that they are dealing with a web site identified with a particular company. The encrypted SSL session ensures that personal information sent over the network, such as credit card numbers, cannot easily be intercepted.

S/MIME certificates

S/MIME certificates are used for signed and encrypted email. As with client SSL certificates, the identity of the client is typically assumed to be the same as the identity of a human being, such as an employee in an enterprise. A single certificate may be used as both an S/MIME certificate and an SSL certificate. S/MIME certificates can also be used for form signing and as part of a single sign-on solution.

For example, a company deploys combined S/MIME and SSL certificates solely for the purpose of authenticating employee identities, thus permitting signed email and client SSL authentication but not encrypted email. Another company issues S/MIME certificates solely for the purpose of both signing and encrypting email that deals with sensitive financial or legal matters.

Object-signing certificates

Object-signing certificates are used to identify signers of Java code, JavaScript scripts, or other signed files.

For example, a software company signs software distributed over the Internet to provide users with some assurance that the software is a legitimate product of that company. Using certificates and digital signatures in this manner can also make it possible for users to identify and control the kind of access downloaded software has to their computers.

CA certificates

CA certificates are used to identify CAs. Client and server software use CA certificates to determine what other certificates can be trusted.

For example, the CA certificates stored in client software determine what other certificates that client can authenticate. An administrator can implement some aspects of corporate security policies by controlling the CA certificates stored in each user’s client.

Contents of a Certificate

The contents of certificates supported by Directory Server and many other software companies are organized according to the X.509 v3 certificate specification, which has been recommended by the International Telecommunications Union (ITU), an international standards body, since 1988. Examples in this section show samples of the data and signature sections of a certificate.

Every X.509 certificate consists of the following sections.

Example 5–1 Data and Signature Sections of a Certificate in Human-Readable Format

Certificate:
Data:
   Version: v3 (0x2)
   Serial Number: 3 (0x3)
   Signature Algorithm: PKCS #1 MD5 With RSA Encryption
   Issuer: OU=Certificate Authority, O=Example Industry, C=US
   Validity:
    Not Before: Fri Oct 17 18:36:25 2003
    Not  After: Sun Oct 17 18:36:25 2004
   Subject: CN=Jane Doe, OU=Finance, O=Example Industry, C=US
   Subject Public Key Info:
    Algorithm: PKCS #1 RSA Encryption
    Public Key:
       Modulus:
          00:ca:fa:79:98:8f:19:f8:d7:de:e4:49:80:48:e6:2a:2a:86:
          ed:27:40:4d:86:b3:05:c0:01:bb:50:15:c9:de:dc:85:19:22:
          43:7d:45:6d:71:4e:17:3d:f0:36:4b:5b:7f:a8:51:a3:a1:00:
          98:ce:7f:47:50:2c:93:36:7c:01:6e:cb:89:06:41:72:b5:e9:
          73:49:38:76:ef:b6:8f:ac:49:bb:63:0f:9b:ff:16:2a:e3:0e:
          9d:3b:af:ce:9a:3e:48:65:de:96:61:d5:0a:11:2a:a2:80:b0:
          7d:d8:99:cb:0c:99:34:c9:ab:25:06:a8:31:ad:8c:4b:aa:54:
          91:f4:15
       Public Exponent: 65537 (0x10001)
   Extensions:
    Identifier: Certificate Type
      Critical: no
      Certified Usage:
      SSL Client
    Identifier: Authority Key Identifier
      Critical: no
      Key Identifier:
        f2:f2:06:59:90:18:47:51:f5:89:33:5a:31:7a:e6:5c:fb:36:
        26:c9
   Signature:
    Algorithm: PKCS #1 MD5 With RSA Encryption
   Signature:
 6d:23:af:f3:d3:b6:7a:df:90:df:cd:7e:18:6c:01:69:8e:54:65:fc:06:
 30:43:34:d1:63:1f:06:7d:c3:40:a8:2a:82:c1:a4:83:2a:fb:2e:8f:fb:
 f0:6d:ff:75:a3:78:f7:52:47:46:62:97:1d:d9:c6:11:0a:02:a2:e0:cc:
 2a:75:6c:8b:b6:9b:87:00:7d:7c:84:76:79:ba:f8:b4:d2:62:58:c3:c5:
 b6:c1:43:ac:63:44:42:fd:af:c8:0f:2f:38:85:6d:d6:59:e8:41:42:a5:
 4a:e5:26:38:ff:32:78:a1:38:f1:ed:dc:0d:31:d1:b0:6d:67:e9:46:a8:
 d:c4
Example 5–2 Certificate In the 64-Byte Encoded Form Interpreted by Software

-----BEGIN CERTIFICATE-----
MIICKzCCAZSgAwIBAgIBAzANBgkqhkiG9w0BAQQFADA3MQswCQYDVQQGEwJVUzER
MA8GA1UEChMITmV0c2NhcGUxFTATBgNVBAsTDFN1cHJpeWEncyBDQTAeFw05NzEw
MTgwMTM2MjVaFw05OTEwMTgwMTM2MjVaMEgxCzAJBgNVBAYTAlVTMREwDwYDVQQK
EwhOZXRzY2FwZTENMAsGA1UECxMEUHViczEXMBUGA1UEAxMOU3Vwcml5YSBTaGV0
dHkwgZ8wDQYJKoZIhvcNAQEFBQADgY0AMIGJAoGBAMr6eZiPGfjX3uRJgEjmKiqG
7SdATYazBcABu1AVyd7chRkiQ31FbXFOGD3wNktbf6hRo6EAmM5/R1AskzZ8AW7L
iQZBcrXpc0k4du+2Q6xJu2MPm/8WKuMOnTuvzpo+SGXelmHVChEqooCwfdiZywyZ
NMmrJgaoMa2MS6pUkfQVAgMBAAGjNjA0MBEGCWCGSAGG+EIBAQQEAwIAgDAfBgNV
HSMEGDAWgBTy8gZZkBhHUfWJM1oxeuZc+zYmyTANBgkqhkiG9w0BAQQFAAOBgQBt
I6/z07Z635DfzX4XbAFpjlRl/AYwQzTSYx8GfcNAqCqCwaSDKvsuj/vwbf91o3j3
UkdGYpcd2cYRCgKi4MwqdWyLtpuHAH18hHZ5uvi00mJYw8W2wUOsY0RC/a/IDy84
hW3WWehBUqVK5SY4/zJ4oTjx7dwNMdGwbWfpRqjd1A==
-----END CERTIFICATE-----

Certificate Management

The set of standards and services that facilitate the use of public-key cryptography and X.509 v3 certificates in a network environment is called thepublic key infrastructure (PKI). For information about the certificate management issues addressed by Directory Server, see the following sections:

Issuing Certificates

The process for issuing a certificate depends on the certificate authority that issues it and the purpose for which it is used. The process for issuing non-digital forms of identification varies in similar ways. For example, if you want to get a generic ID card (not a driver’s license) from the Department of Motor Vehicles in California, the requirements are straightforward: you need to present some evidence of your identity, such as a utility bill with your address on it and a student identity card. If you want to get a regular driving license, you also need to take a test — a driving test when you first get the license, and a written test when you renew it. If you want to get a commercial license for an eighteen-wheeler, the requirements are much more stringent. If you live in some other state or country, the requirements for various kinds of licenses differ.

Similarly, different CAs have different procedures for issuing different kinds of certificates. In some cases the only requirement may be your mail address. In other cases, your UNIX login and password may be sufficient. At the other end of the scale, for certificates that identify people who can authorize large expenditures or make other sensitive decisions, the issuing process may require notarized documents, a background check, and a personal interview.

Depending on an organization’s policies, the process of issuing certificates can range from being completely transparent for the user to requiring significant user participation and complex procedures. In general, processes for issuing certificates should be highly flexible, so organizations can tailor them to their changing needs.

Issuing certificates is one of several management tasks that can be handled by separate Registration Authorities.

Certificates and the LDAP Directory

The Lightweight Directory Access Protocol (LDAP) for accessing directory services supports great flexibility in the management of certificates within an organization. System administrators can store much of the information required to manage certificates in an LDAP-compliant directory. For example, a CA can use information in a directory to pre-populate a certificate with a new employee’s legal name and other information. The CA can leverage directory information in other ways to issue certificates one at a time or in bulk, using a range of different identification techniques depending on the security policies of a given organization. Other routine management tasks, such as key management and renewing and revoking certificates, can be partially or fully automated with the aid of the directory.

Information stored in the directory can also be used with certificates to control access to various network resources by different users or groups. Issuing certificates and other certificate management tasks can thus be an integral part of user and group management.

Key Management

Before a certificate can be issued, the public key it contains and the corresponding private key must be generated. Sometimes it may be useful to issue a single person one certificate and key pair for signing operations, and another certificate and key pair for encryption operations. Separate signing and encryption certificates make it possible to keep the private signing key on the local machine only, thus providing maximum non-repudiation, and to back up the private encryption key in some central location where it can be retrieved in case the user loses the original key or leaves the company.

Keys can be generated by client software or generated centrally by the CA and distributed to users via an LDAP directory. There are trade-offs involved in choosing between local and centralized key generation. For example, local key generation provides maximum non-repudiation, but may involve more participation by the user in the issuing process. Flexible key management capabilities are essential for most organizations.

Key recovery, or the ability to retrieve backups of encryption keys under carefully defined conditions, can be a crucial part of certificate management (depending on how an organization uses certificates). Key recovery schemes usually involve an m of n mechanism: for example, m of n managers within an organization might have to agree, and each contribute a special code or key of their own, before a particular person’s encryption key can be recovered. This kind of mechanism ensures that several authorized personnel must agree before an encryption key can be recovered.

Renewal and Revocation of Certificates

Like a driver’s license, a certificate specifies a period of time during which it is valid. Attempts to use a certificate for authentication before or after its validity period fails. Therefore, mechanisms for managing certificate renewal are essential for any certificate management strategy. For example, an administrator may wish to be notified automatically when a certificate is about to expire, so that an appropriate renewal process can be completed in plenty of time without causing the certificate’s subject any inconvenience. The renewal process may involve reusing the same public-private key pair or issuing a new one.

A driver’s license can be suspended even if it has not expired—for example, as punishment for a serious driving offense. Similarly, it’s sometimes necessary to revoke a certificate before it has expired—for example, if an employee leaves a company or moves to a new job within the company.

Certificate revocation can be handled in several different ways. For some organizations, it may be sufficient to set up servers so that the authentication process includes checking the directory for the presence of the certificate being presented. When an administrator revokes a certificate, the certificate can be automatically removed from the directory, and subsequent authentication attempts with that certificate fails even though the certificate remains valid in every other respect. Another approach involves publishing a certificate revocation list (CRL)—that is, a list of revoked certificates—to the directory at regular intervals and checking the list as part of the authentication process. For some organizations, it may be preferable to check directly with the issuing CA each time a certificate is presented for authentication. This procedure is sometimes called real-time status checking.

Registration Authorities

Interactions between entities identified by certificates (sometimes called end entities) and CAs are an essential part of certificate management. These interactions include operations such as registration for certification, certificate retrieval, certificate renewal, certificate revocation, and key backup and recovery. In general, a CA must be able to authenticate the identities of end entities before responding to the requests. In addition, some requests need to be approved by authorized administrators or managers before being serviced.

As previously discussed, the means used by different CAs to verify an identity before issuing a certificate can vary widely, depending on the organization and the purpose for which the certificate is used. To provide maximum operational flexibility, interactions with end entities can be separated from the other functions of a CA and handled by a separate service called a Registration Authority RA.

An RA acts as a front end to a CA by receiving end entity requests, authenticating them, and forwarding them to the CA. After receiving a response from the CA, the RA notifies the end entity of the results. RAs can be helpful in scaling a PKI across different departments, geographical areas, or other operational units with varying policies and authentication requirements.

SASL-based Authentication

Client authentication during an SSL or TLS connection can also use the Simple Authentication and Security Layer (SASL). Directory Server supports the following SASL mechanisms.

DIGEST-MD5

The DIGEST-MD5 mechanism authenticates clients by comparing a hashed value sent by the client with a hash of the user's password. However, because the mechanism must read user passwords, all users wishing to be authenticated through DIGEST-MD5 must have clear text passwords in the directory.

GSSAPI

GSSAPI is available on the Solaris Operating System only. The General Security Services API (GSSAPI) allows Directory Server to interact with the Kerberos V5 security system to identify a user. The client application must present its credentials to the Kerberos system, which in turn validates the user's identity to Directory Server.

For information about how to configure SASL-based authentication, see Configuring Credential Levels and Authentication Methods in Oracle Fusion Middleware Administration Guide for Oracle Directory Server Enterprise Edition.

How Directory Server Provides Encryption

For information about how Directory Server encrypts data, see the following sections:

Secure Sockets Layer (SSL)

SSL provides encrypted communications and optional authentication between a Directory Server and its clients. SSL can be used over LDAP or DSML over HTTP. SSL is enabled by default over LDAP and can be enabled for DSML over HTTP.

Replication can be configured to use SSL for secure communications between servers. When replication is configured to use SSL, data sent to and from the server is encrypted by using SSL.

By default, Directory Server allows simultaneous unsecured and secure communications, suing different port numbers. Unsecured LDAP communications are handled on one port, conventionally port number 389. Secure LDAP communications are handled on another port, conventionally port number 636.

For security reasons, you can also restrict all communications to the secure port. Client authentication is also configurable. You can set client authentication to required or allowed. This setting determines the level of security you enforce.

SSL enables support for the Start TLS extended operation that provides security on a regular LDAP connection. Clients can bind to the non-SSL port and then use the Transport Layer Security protocol to initiate an SSL connection. The Start TLS operation allows more flexibility for clients, and can help simplify port allocation.

For information about SSL, see the following sections:

Overview of SSL

TCP/IP governs the transport and routing of data over the Internet. Other protocols, such as the HTTP, LDAP, or IMAP use TCP/IP to support typical application tasks such as displaying web pages or running mail servers.

Figure 5–8 Where SSL Runs

Figure shows that SSL runs above the TCP/IP layer but below other protocols

The SSL protocol runs above TCP/IP and below higher-level protocols such as HTTP or IMAP. It uses TCP/IP on behalf of the higher-level protocols, and in the process allows an SSL-enabled server to authenticate itself to an SSL-enabled client, allows the client to authenticate itself to the server, and allows both machines to establish an encrypted connection.

SSL addresses the following concerns about communication over the Internet and other TCP/IP networks:

SSL server authentication allows a user to confirm a server’s identity.

SSL-enabled client software can use standard techniques of public-key cryptography to check that a server’s certificate and public ID are valid and have been issued by a certificate authority (CA) listed in the client’s list of trusted CAs. This confirmation might be important if the user, for example, is sending a credit card number over the network and wants to check the receiving server’s identity.

SSL client authentication allows a server to confirm a user’s identity.

Using the same techniques as those used for server authentication, SSL-enabled server software can check that a client’s certificate and public ID are valid and have been issued by a certificate authority (CA) listed in the server’s list of trusted CAs. This confirmation might be important if the server, for example, is a bank sending confidential financial information to a customer and wants to check the recipient’s identity.

An encrypted SSL connection requires all information sent between a client and a server to be encrypted by the sending software and decrypted by the receiving software, thus providing a high degree of confidentiality.

Confidentiality is important for both parties to any private transaction. In addition, all data sent over an encrypted SSL connection is protected with a mechanism for detecting tampering—that is, for automatically determining whether the data has been altered in transit.

The SSL protocol includes two sub-protocols: the SSL record protocol and the SSL handshake protocol.

The SSL record protocol defines the format used to transmit data. The SSL handshake protocol involves using the SSL record protocol to exchange a series of messages between an SSL-enabled server and an SSL-enabled client when they first establish an SSL connection. This exchange of messages is designed to facilitate the following actions:

  • Authenticate the server to the client.

  • Allow the client and server to select the cryptographic algorithms, or ciphers, that they both support.

  • Optionally authenticate the client to the server.

  • Use public-key encryption techniques to generate shared secrets.

  • Establish an encrypted SSL connection.

For more information about the handshake process, see SSL Handshake.

Cryptographic Algorithms Used With SSL

Cipher suites define the following aspects of SSL communication:

The SSL protocol supports many ciphers. Clients and servers can support different cipher suites, depending on factors such as the version of SSL they support, and company policies regarding acceptable encryption strength. The SSL handshake protocol determines how the server and client negotiate which cipher suites they use to authenticate each other, to transmit certificates, and to establish session keys.

SSL 2.0 and SSL 3.0 protocols support overlapping sets of cipher suites. Administrators can enable or disable any of the supported cipher suites for both clients and servers. When a client and server exchange information during the SSL handshake, they identify the strongest enabled cipher suites they have in common and use those for the SSL session. Decisions about which cipher suites to enable depend on the sensitivity of the data involved, the speed of the cipher, and the applicability of export rules.

Key-exchange algorithms like KEA and RSA govern the way in which a server and client determine the symmetric keys they use during an SSL session. The most commonly used SSL cipher suites use the RSA key exchange.

The list of ciphers enabled for Directory Server, and also the list of ciphers supported by Directory Server can be obtained with the dsconf command. For information about using the dsconf command to list available ciphers and manage ciphers, see Choosing Encryption Ciphers in Oracle Fusion Middleware Administration Guide for Oracle Directory Server Enterprise Edition.

Support for ciphers is provided by the Network Security Services, NSS, component. For details about NSS, see theNSS project site.

SSL Handshake

The SSL protocol uses a combination of public-key and symmetric key encryption. Symmetric key encryption is much faster than public-key encryption, but public-key encryption provides better authentication techniques. An SSL session always begins with an exchange of messages called the SSL handshake. The handshake allows the server to authenticate itself to the client by using public-key techniques, and then allows the client and the server to cooperate in the creation of symmetric keys used for rapid encryption, decryption, and tamper detection. Optionally, the handshake also allows the client to authenticate itself to the server.

For information about the SSL handshake, see the following sections:

Messages Exchanged During SSL Handshake

The following steps describes the sequence of messages exchanged during an SSL handshake. These step describe the programmatic details of the messages exchanged during the SSL handshake.

  1. The client sends the server the client’s SSL version number, cipher settings, randomly generated data, and other information the server needs to communicate with the client using SSL.

  2. The server sends the client the server’s SSL version number, cipher settings, randomly generated data, and other information the client needs to communicate with the server over SSL. The server also sends its own certificate and, if the client is requesting a server resource that requires client authentication, requests the client’s certificate.

  3. The client can use some of the information sent by the server to authenticate the server. For details, see Server Authentication During SSL Handshake. If the server cannot be authenticated, the user is warned of the problem and informed that an encrypted and authenticated connection cannot be established. If the server can be successfully authenticated, the client goes on to Step 4.

  4. Using all data generated in the handshake so far, the client, with the cooperation of the server, depending on the cipher being used, creates the pre-master secret for the session, encrypts it with the server’s public key, obtained from the server’s certificate, sent in Step 2, and sends the encrypted pre-master secret to the server.

  5. If the server has requested client authentication (an optional step in the handshake), the client also signs another piece of data that is unique to this handshake and known by both the client and server. In this case the client sends both the signed data and the client’s own certificate to the server along with the encrypted pre-master secret.

  6. If the server has requested client authentication, the server attempts to authenticate the client. For details, see Server Authentication During SSL Handshake. If the client cannot be authenticated, the session is terminated. If the client can be successfully authenticated, the server uses its private key to decrypt the pre-master secret, then performs a series of steps (which the client also performs, starting from the same pre-master secret) to generate the master secret.

  7. Both the client and the server use the master secret to generate the session keys, which are symmetric keys used to encrypt and decrypt information exchanged during the SSL session and to verify its integrity—that is, to detect changes in the data between the time it was sent and the time it is received over the SSL connection.

  8. The client sends a message to the server informing it that future messages from the client are encrypted with the session key. It then sends a separate (encrypted) message indicating that the client portion of the handshake is finished.

  9. The server sends a message to the client informing it that future messages from the server are encrypted with the session key. It then sends a separate (encrypted) message indicating that the server portion of the handshake is finished.

  10. The SSL handshake is now complete, and the SSL session has begun. The client and the server use the session keys to encrypt and decrypt the data they send to each other and to validate its integrity.

Before continuing with a session, directory servers can be configured to check that the client’s certificate is present in the user’s entry in an LDAP directory. This configuration option provides one way of ensuring that the client’s certificate has not been revoked.

Both client and server authentication involve encrypting some piece of data with one key of a public-private key pair and decrypting it with the other key:

Server Authentication During SSL Handshake

SSL-enabled client software always requires server authentication, or cryptographic validation by a client of the server’s identity. The server sends the client a certificate to authenticate itself. The client uses the certificate to authenticate the identity the certificate claims to represent.

To authenticate the binding between a public key and the server identified by the certificate that contains the public key, an SSL-enabled client must receive a yes answer to the four questions shown in the following figure.

Figure 5–9 Authenticating a Client Certificate During SSL Handshake

Figure shows authentication of a client certificate.

An SSL-enabled client goes through the following steps to authenticate a server’s identity:

  1. Is today’s date within the validity period?

    The client checks the server certificate’s validity period. If the current date and time are outside of that range, the authentication process won’t go any further. If the current date and time are within the certificate’s validity period, the client goes on to the next step.

  2. Is the issuing CA a trusted CA?

    Each SSL-enabled client maintains a list of trusted CA certificates, represented by the shaded area on the right—hand side of Figure 5–9. This list determines which server certificates the client accepts. If the distinguished name (DN) of the issuing CA matches the DN of a CA on the client’s list of trusted CAs, the answer to this question is yes, and the client goes on to the next step. If the issuing CA is not on the list, the server is not authenticated unless the client can verify a certificate chain ending in a CA that is on the list.

  3. Does the issuing CA’s public key validate the issuer’s digital signature?

    The client uses the public key from the CA’s certificate (which it found in its list of trusted CAs in step 2) to validate the CA’s digital signature on the server certificate being presented. If the information in the server certificate has changed since it was signed by the CA or if the CA certificate’s public key doesn’t correspond to the private key used by the CA to sign the server certificate, the client won’t authenticate the server’s identity. If the CA’s digital signature can be validated, the server treats the user’s certificate as a valid “letter of introduction” from that CA and proceeds. At this point, the client has determined that the server certificate is valid.

  4. Does the domain name in the server’s certificate match the domain name of the server itself?

    This step confirms that the server is actually located at the same network address specified by the domain name in the server certificate. Although step 4 is not technically part of the SSL protocol, it provides the only protection against a form of security attack known as man-in-the-middle. Clients must perform this step and must refuse to authenticate the server or establish a connection if the domain names don’t match. If the server’s actual domain name matches the domain name in the server certificate, the client goes on to the next step.

  5. The server is authenticated.

    The client proceeds with the SSL handshake. If the client doesn’t get to step 5 for any reason, the server identified by the certificate cannot be authenticated, and the user is warned of the problem and informed that an encrypted and authenticated connection cannot be established. If the server requires client authentication, the server performs the steps described in Client Authentication During SSL Handshake.

After the steps described here, the server must successfully use its private key to decrypt the pre-master secret sent by the client.

Man-In-the-Middle Attack

The man-in-the-middle is a rogue program that intercepts all communication between the client and a server with which the client is attempting to communicate via SSL. The rogue program intercepts the legitimate keys that are passed back and forth during the SSL handshake, substitutes its own, and makes it appear to the client that it is the server, and to the server that it is the client.

The encrypted information exchanged at the beginning of the SSL handshake is actually encrypted with the rogue program’s public key or private key, rather than the client’s or server’s real keys. The rogue program ends up establishing one set of session keys for use with the real server, and a different set of session keys for use with the client. This allows the rogue program not only to read all the data that flows between the client and the real server, but also to change the data without being deleted. Therefore, it is extremely important for the client to check that the domain name in the server certificate corresponds to the domain name of the server with which a client is attempting to communicate—in addition to checking the validity of the certificate by performing the other steps described in Server Authentication During SSL Handshake

Client Authentication During SSL Handshake

SSL-enabled servers can be configured to require client authentication, or cryptographic validation by the server of the client’s identity. When a server configured this way requests client authentication separate piece of digitally signed data to authenticate itself. The server uses the digitally signed data to validate the public key in the certificate and to authenticate the identity the certificate claims to represent.

The SSL protocol requires the client to create a digital signature by creating a one-way hash from data generated randomly during the handshake and known only to the client and server. The hash of the data is then encrypted with the private key that corresponds to the public key in the certificate being presented to the server.

To authenticate the binding between the public key and the person or other entity identified by the certificate that contains the public key, an SSL-enabled server must receive a yes answer to the first four questions shown in Figure 5–10. Although the fifth question is not part of the SSL protocol, directory servers can be configured to support this requirement to take advantage of the user entry in an LDAP directory as part of the authentication process.

Figure 5–10 Authentication and Verification During SSL Handshake

Figure shows authentication and verification.

An SSL-enabled server goes through the following steps to authenticate a user’s identity:

  1. Does the user’s public key validate the user’s digital signature?

    The server checks that the user’s digital signature can be validated with the public key in the certificate. If so, the server has established that the public key asserted to belong to John Doe matches the private key used to create the signature and that the data has not been tampered with since it was signed.

    At this point, however, the binding between the public key and the DN specified in the certificate has not yet been established. The certificate might have been created by someone attempting to impersonate the user. To validate the binding between the public key and the DN, the server must also complete steps 3 and 4 in this list.

  2. Is today’s date within the validity period?

    The server checks the certificate’s validity period. If the current date and time are outside of that range, the authentication process won’t go any further. If the current date and time are within the certificate’s validity period, the server goes onto the next step.

  3. Is the issuing CA a trusted CA?

    Each SSL-enabled server maintains a list of trusted CA certificates, represented by the shaded area on the right—hand side of Figure 5–10. This list determines which certificates the server accepts. If the DN of the issuing CA matches the DN of a CA on the server’s list of trusted CAs, the answer to this question is yes, and the server goes on to the next step. If the issuing CA is not on the list, the client is not authenticated unless the server can verify a certificate chain ending in a CA that is trusted or not trusted within their organizations by controlling the lists of CA certificates maintained by clients and servers.

  4. Does the issuing CA’s public key validate the issuer’s digital signature?

    The server uses the public key from the CA’s certificate (which it found in its list of trusted CAs in the previous step) to validate the CA’s digital signature on the certificate being presented. If the information in the certificate has changed since it was signed by the CA or if the public key in the CA certificate doesn’t correspond to the private key used by the CA to sign the certificate, the server won’t authenticate the user’s identity. If the CA’s digital signature can be validated, the server treats the user’s certificate as a valid “letter of introduction” from that CA and proceeds. At this point, the SSL protocol allows the server to consider the client authenticated and proceed with the connection as described in step 6. The directory servers may optionally be configured to perform step 5 before step 6.

  5. Is the user’s certificate listed in the LDAP entry for the user?

    This optional step provides one way for a system administrator to revoke a user’s certificate even if it passes the tests in all the other steps. The Certificate Management System can automatically remove a revoked certificate from the user’s entry in the LDAP directory. All servers that are set up to perform this step then refuses to authenticate that certificate or establish a connection. If the user’s certificate in the directory is identical to the user’s certificate presented in the SSL handshake, the server goes on to the next step.

  6. Is the authenticated client authorized to access the requested resources?

    The server checks what resources the client is permitted to access according to the server’s access control lists (ACLs) and establishes a connection with appropriate access. If the server doesn’t get to step 6 for any reason, the user identified by the certificate cannot be authenticated, and the user is not allowed to access any server resources that require authentication.

Digital Signatures

Digital signatures can be used by Directory Server to maintain integrity of information. If encryption and message digests are applied to the information being sent, the recipient can determine that the information was not tampered with during transit.

Tamper detection and related authentication techniques rely on a mathematical function called a one-way hash. This function is also called a message digest. A one-way hash is a number of fixed length with the following characteristics:

It is possible to use a private key for encryption and a public key for decryption. Although this is not desirable when you are encrypting sensitive information, it is a crucial part of digitally signing any data. Instead of encrypting the data itself, the signing software creates a one-way hash of the data, then uses your private key to encrypt the hash. The encrypted hash, along with other information, such as the hashing algorithm, is known as a digital signature. Figure 5–11 shows two items transferred to the recipient of some signed data.

Figure 5–11 Digital Signatures

Figure shows digital signatures

In Figure 5–11, the original data and the digital signature, which is basically a one-way hash (of the original data) that has been encrypted with the signer's private key. To validate the integrity of the data, the receiving software first uses the signer’s public key to decrypt the hash. It then uses the same hashing algorithm that generated the original hash to generate a new one-way hash of the same data. (Information about the hashing algorithm used is sent with the digital signature, although this isn’t shown in the figure.) Finally, the receiving software compares the new hash against the original hash. If the two hashes match, the data has not changed since it was signed. If they don’t match, the data may have been tampered with since it was signed, or the signature may have been created with a private key that doesn’t correspond to the public key presented by the signer.

If the two hashes match, the recipient can be certain that the public key used to decrypt the digital signature corresponds to the private key used to create the digital signature. Confirming the identity of the signer, however, also requires some way of confirming that the public key really belongs to a particular person or other entity.

The significance of a digital signature is comparable to the significance of a handwritten signature. Once you have signed some data, it is difficult to deny doing so later — assuming that the private key has not been compromised or out of the owner’s control. This quality of digital signatures provides a high degree of non-repudiation — that is, digital signatures make it difficult for the signer to deny having signed the data. In some situations, a digital signature may be as legally binding as a handwritten signature.

Key Encryption

With most modern cryptography, the ability to keep encrypted information secret is based not on the cryptographic algorithm, which is widely known, but on a key. A key is a number that must be used with the algorithm to produce an encrypted result or to decrypt previously encrypted information. For information about encryption and decryption with keys, see the following sections:

Symmetric-Key Encryption

With symmetric-key encryption, the encryption key can be calculated from the decryption key, and vice versa. With most symmetric algorithms, the same key is used for both encryption and decryption. The following figure shows a symmetric-key encryption.

Figure 5–12 Symmetric-Key Encryption

Figure shows symmetric-key encryption.

Implementations of symmetric-key encryption can be highly efficient, so that users do not experience any significant time delay as a result of the encryption and decryption. Symmetric-key encryption also provides a degree of authentication, since information encrypted with one symmetric key cannot be decrypted with any other symmetric key. Thus, as long as the symmetric key is kept secret by the two parties using it to encrypt communications, each party can be sure that it is communicating with the other as long as the decrypted messages continue to make sense.

Symmetric-key encryption is effective only if the symmetric key is kept secret by the two parties involved. If anyone else discovers the key, it affects both confidentiality and authentication. A person with an unauthorized symmetric key not only can decrypt messages sent with that key, but can encrypt new messages and send them as if they came from one of the two parties who were originally using the key.

Symmetric-key encryption plays an important role in the SSL protocol, which is widely used for authentication, tamper detection, and encryption over TCP/IP networks. SSL also uses techniques of public-key encryption, which is described in the next section.

Public-Key Encryption

The most commonly used implementations of public-key encryption are based on algorithms patented by RSA Data Security. Therefore, this section describes the RSA approach to public-key encryption.

Public-key encryption (also called asymmetric encryption) involves a pair of keys—a public key and a private key—associated with an entity that needs to authenticate its identity electronically or to sign or encrypt data. Each public key is published, and the corresponding private key is kept secret. The following figure shows a simplified view of the way public-key encryption works.

Figure 5–13 Public-Key Encryption

Figure shows public-key encryption

Public—key encryption lets you distribute a public key, and only you can read data encrypted by this key. In general, to send encrypted data to someone, you encrypt the data with that person’s public key, and the person receiving the encrypted data decrypts it with the corresponding private key.

Compared with symmetric-key encryption, public-key encryption requires more computation and is therefore not always appropriate for large amounts of data. However, it’s possible to use public-key encryption to send a symmetric key, which can then be used to encrypt additional data. This is the approach used by the SSL protocol.

As it happens, the reverse of the scheme shown in Figure 5–13 also works: data encrypted with your private key can be decrypted with your public key only. This would not be a desirable way to encrypt sensitive data, however, because it means that anyone with your public key, which is by definition published, could decrypt the data. Nevertheless, private-key encryption is useful, because it means you can use your private key to sign data with your digital signature—an important requirement for electronic commerce and other commercial applications of cryptography. Client software can then use your public key to confirm that the message was signed with your private key and that it hasn’t been tampered with since being signed. Digital Signatures and subsequent sections describe how this confirmation process works.

Key Length and Encryption Strength

The strength of encryption is related to the difficulty of discovering the key, which in turn depends on both the cipher used and the length of the key. For example, the difficulty of discovering the key for the RSA cipher most commonly used for public-key encryption depends on the difficulty of factoring large numbers, a well-known mathematical problem.

Encryption strength is often described in terms of the size of the keys used to perform the encryption: in general, longer keys provide stronger encryption. Key length is measured in bits. For example, 128-bit keys for use with the RC4 symmetric-key cipher supported by SSL provide significantly better cryptographic protection than 40-bit keys for use with the same cipher. Roughly speaking, 128-bit RC4 encryption is 3 x 1026 times stronger than 40-bit RC4 encryption.

Different ciphers may require different key lengths to achieve the same level of encryption strength. The RSA cipher used for public-key encryption, for example, can use only a subset of all possible values for a key of a given length, due to the nature of the mathematical problem on which it is based. Other ciphers, such as those used for symmetric key encryption, can use all possible values for a key of a given length, rather than a subset of those values. Thus a 128-bit key for use with a symmetric-key encryption cipher would provide stronger encryption than a 128-bit key for use with the RSA public-key encryption cipher. This difference explains why the RSA public-key encryption cipher must use a 512-bit key (or longer) to be considered cryptographically strong, whereas symmetric key ciphers can achieve approximately the same level of strength with a 64-bit key. Even this level of strength may be vulnerable to attacks in the near future.

Attribute Encryption

Attribute encryption enables sensitive attributes of an entry to be stored in encrypted form. By encrypting sensitive attributes, you can prevent them from being read while the data is stored in database files, backup files, or exported LDIF files, or while the data is exported. Figure 5–14 shows a user entry being added to the database, where attribute encryption has been configured to encrypt the salary attribute.

Figure 5–14 Attribute Encryption

Figure shows attributes encrypted in the database.

The attribute encryption feature supports a wide range of encryption algorithms and different platforms. Attribute encryption uses the private key of the server’s SSL certificate to generate its own key. This key is then used to perform the encryption and decryption operations.

Attribute encryption is configured at the suffix level. This means that an attribute is encrypted for every entry in which it appears in a suffix. To encrypt an attribute in an entire directory, you must enable encryption for that attribute in every suffix.

If you choose to encrypt an attribute that some entries use as a naming attribute, values that appear in the DN will not be encrypted, but values stored in the entry will be encrypted.

Encrypting the userPassword attribute provides no security benefit unless the password needs to be stored in clear text, as is the for DIGEST-MD5 SASL authentication. If the password already has an encryption mechanism defined in the password policy, further encryption provides little additional security.

When encrypted attributes are stored, they are prefaced with a cipher tag that indicates what encryption algorithm has been used. An encrypted attribute using the DES encryption algorithm would appear as follows:


{CKM_DES_CBC}3hakc&jla+=snda%

While attribute encryption offers increased data security, the feature does impact performance. you should think carefully about which attributes require encryption and encrypt only those attributes that are particularly sensitive. Because sensitive data can be accessed directly through index files, it is necessary to encrypt the index keys corresponding to the encrypted attributes, to ensure that the attributes are fully protected.

For information about how to encrypt attributes, see Encrypting Attribute Values in Oracle Fusion Middleware Administration Guide for Oracle Directory Server Enterprise Edition.

Chapter 6 Directory Server Monitoring

For information about monitoring Directory Server, see the following sections.

Ways to Monitor Directory Server

Directory Server can be monitored in the following ways:

Directory Service Control Center

Directory Service Control Center, DSCC, can be used to monitor current activities of a Directory Server instance.

DSCC provides general server information, including a resource summary, current resource usage, connection status, and global database cache information. It also provides general database information, such as the database type, status, and entry cache statistics. Cache information and information relative to each index file within the database is also provided. In addition, DSCC provides information relative to the connections and the operations performed on each chained suffix.

Command line

The dsconf command can be used to configure logging and to monitor the replication status of Directory Server. For information about how to configure logging, see Configuring Logs for Directory Server in Oracle Fusion Middleware Administration Guide for Oracle Directory Server Enterprise Edition. For information about how to use the dsconf command for monitoring, see Getting Replication Status by Using the Command Line in Oracle Fusion Middleware Administration Guide for Oracle Directory Server Enterprise Edition.

The ldapsearch command can be used to search the cn=monitor entry for information about current activities of a Directory Server instance. For information about cn=monitor, see Directory Server Monitoring Attributes.

Log analyzer tool

The Directory Server Resource Kit provides a log analyzer tool called logconv(1).

The logconv tool extracts usage statistics and counts the occurrences of significant events in the access logs.

Java Management Extensions, JMX

Directory Server exposes management information through JMX according to the Common Monitoring Information and Data Model. See the Sun Java Enterprise System 5 Update 1 Monitoring Guide for details.

Java ES Monitoring Framework, Java ES MF, provides an JMX entry point to retrieve data. For information about the JMX entry points exposed for monitoring Directory Server, see Directory Server and SNMP.

Simple Network Management Protocol, SNMP

Directory Server exposes management information through SNMP. See the Sun Java Enterprise System 5 Update 1 Monitoring Guide for details.

Java ES MF provides an SNMP entry point to retrieve SNMP data. For information about the SNMP entry points exposed for monitoring Directory Server, see Directory Server and SNMP.

Simple Object Access Protocol, SOAP

Java ES MF provides a SOAP entry point to retrieve data. See the Sun Java Enterprise System 5 Update 1 Monitoring Guide for details.

Directory Server and SNMP

Directory Server implements the dsTable and the dsApplIfOpsTable of the Directory Server Monitoring MIB defined by RFC 2605. It does not implement the dsIntTable.

Directory Server also implements the Network Services Monitoring MIB defined by RFC 2788.

Directory Server support for SNMP has the following limitations.

This rest of this section explains how the information flows from the monitoring application to Directory Server and back, particularly in the case where you use SNMP.

The SNMP interface is exposed by Java ES MF. See the Sun Java Enterprise System 5 Update 1 Monitoring Guide for details.

The monitoring framework is contained within the Common Agent Container, cacao, which is installed alongside Directory Server. Figure 6–1 shows the monitoring framework.

Figure 6–1 Overall Monitoring Information Flow

Figure shows how information about Directory Server is monitored through a Common Agent Container.

SNMP support for monitoring Directory Server is managed by a Directory Server agent in the Common Agent Container. On Directory Server startup, the Monitoring server plug-in registers theDirectory Server instance with the Directory Server agent within the Common Agent Container.

Figure 6–2 shows how SNMP information about Directory Server flows through the Common Agent Container.

Figure 6–2 SNMP Information Flow

Figure shows how SNMP information about Directory Server flows through the Common Agent Container.

    SNMP information about Directory Server flows as follows.

  1. The network management station sends a GET message through the master SNMP agent, which by default uses standard port 161, to the SNMP mediation layer, which by default uses port 11161.

    For information about how to configure access to the SNMP mediation layer, see the Sun Java Enterprise System 5 Update 1 Monitoring Guide.

  2. The SNMP mediation layer forwards any requests destined for the Directory Server to the Directory Server agent.

  3. When the server state changes, Directory Server pushes SNMP information to the Directory Server agent.

  4. The Directory Server agent relays the response back to the SNMP client via the SNMP mediation layer and master SNMP agent to the network management station. The network management station then displays the data through its network management application.

Directory Server and CMM/JMX

Directory Server supports monitoring through JMX, which is exposed by Java ES MF. See the Sun Java Enterprise System 5 Update 1 Monitoring Guide for details on the interface itself.

The monitoring framework is contained within the Common Agent Container, cacao, which is installed alongside Directory Server. Figure 6–1 shows the monitoring framework. The information flow for JMX is similar to the flow shown for SNMP in Figure 6–2.

The monitoring information exposed through JMX is organized according to the Common Monitoring Information and Data Model, CMM. CMM allows applications exposing their monitoring information to associate human-readable descriptions with the individual counters and other information. CMM is therefore meant to be self-documenting. Directory Server implements the following CMM classes.

When examining the content of the monitoring information, notice that CMM_ServiceAccessURI is implemented not only for LDAP and for LDAPS, but also for DSML/HTTP or DSML/HTTPS if the DSML front end has been enabled.

Java ES Monitoring Console offers a browser-based user interface to examine the information exposed. See the Sun Java Enterprise System 5 Update 1 Monitoring Guide for instructions on preparing the Monitoring Console for use.

Directory Server Monitoring Attributes

Server status, replication status, resource usage, and other monitoring information is available through DSCC.

Alternatively, you can monitor the Directory Server’s current activities from any LDAP client by performing a search operation on the following entries:

cn=monitor

The cn=monitor entry is an instance of the extensibleObject object class. For cn=monitor configuration attributes to be taken into account by the server, this object class, in addition to the top object class, is present in the entry. The cn=monitor read-only attributes are presented in this section.

Read-only monitoring information is stored under the cn=monitor entry.

backendMonitorDN

DN for each Directory Server backend.

For further database monitoring information, refer to dse.ldif(4).

bytesSent

Number of bytes sent by Directory Server.

cache-avail-bytes

The number of bytes available for caching.

connection

List of open connections given in the following format:

connection=31:20010201164808Z:45:45::cn=admin,cn=Administrators,cn=config:LDAP

connectionPeak

Maximum number of simultaneous connections since server startup.

currentConnections

Number of current Directory Server connections.

currentTime

Current time usually given in Greenwich Mean Time, indicated by GeneralizedTime syntax Z notation, for example 20010202131102Z.

dTableSize

Size of the Directory Server descriptor table.

entriesSent

Number of entries sent by Directory Server.

nbackEnds

Number of Directory Server backends.

opsCompleted

Number of Directory Server operations completed.

opsInitiated

Number of Directory Server operations initiated.

request-que-backlog

The number of requests waiting to be processed by a thread. Each request received by the server is accepted, then placed in a queue until a thread is available to process it. The queue backlog should always be small, 0 or close to 0. If the queue backlog is large, use the nsslapd-threadnumber attribute to increase the number of threads available in the server.

readWaiters

Number of connections where some requests are pending and not currently being serviced by a thread in Directory Server.

currentpsearches

Number of persistent searches currently running on the server. You can set a maximum number of persistent searches on the server by using the command dsconf set-server-prop max-psearch-count:number.

startTime

Directory Server start time.

threads

Number of operation threads Directory Server creates during startup. This attribute can be set using the nsslapd-threadnumber attribute under cn=config. The nsslapd-threadnumber attribute is not present in the configuration by default, but can be added.

totalConnections

Total number of Directory Server connections.

version

Directory Server version and build number.

cn=disk,cn=monitor

The cn=disk entry enables you to monitor disk conditions over LDAP. This entry is an instance of the extensibleObject object class. A cn=disknumber,cn=disk,cn=monitor entry exists for each disk. The following disk monitoring attributes appear under each of these individual disk entries.

disk-dir

Specifies the pathname of a directory used by the server on disk. Where several database instances reside on the same disk or an instance refers to several directories on the same disk, the short pathname is displayed. The disk numbering is arbitrary.

disk-free

Indicates the amount of free disk space available to the server, in MB.

Note –

The disk space available to the server process may be less than the total free disk space. For example, on some platforms a process that is not running as root may not have all the free disk space available to it.

disk-state

Indicates the state of the disk, based on the available free space and on the thresholds set for disk low and disk full with the configuration parameters nsslapd-disk-low-threshold and nsslapd-disk-full-threshold. Possible values are normal, low, and full.

cn=counters,cn=monitor

This entry holds counter information for the various subtree entry counter plug-ins, if they are enabled.

cn=monitor,cn=Class of Service,cn=plugins, cn=config

This entry holds counters related to the Class of Service plug-in. This entry is an instance of the extensibleObject object class.

classicHashAvgClashListLength

When the CoS plug-in uses the hash table for fast lookup, if more than one classic CoS template corresponds to the hash key used, the plug-in next checks for matches in what is called the clash list, a list of templates sharing an identical hash key. The value of this attribute provides the average length across all hash tables of classic CoS template clash lists, giving some indication of how much linear searching the plug-in must perform after using the hash table during fast lookup.

classicHashAvgClashPercentagePerHash

The average number of clashes per hash table. That is, the average percentage per hash of classic CoS templates sharing an identical hash key.

classicHashMemUsage

The memory overhead in bytes to hold hash tables for fast classic CoS template lookups.

classicHashValuesMemUsage

The memory in bytes used to hold hash values for fast classic CoS template lookups.

numClassicDefinitions

The number of classic CoS definition entries in use.

numClassicHashTables

The number of hash tables created for fast lookup where more than 10 classic CoS templates apply for a single CoS definition. Hash tables are not created for smaller lists of templates.

numClassicTemplates

The number of classic CoS template entries in use.

numCoSAttributeTypes

The number of distinct attributes with values calculated through CoS.

numIndirectDefinitions

The number of indirect CoS definition entries in use.

numPointerDefinitions

The number of pointer CoS definition entries in use.

numPointerTemplates

The number of pointer CoS template entries in use.

Chapter 7 Directory Server Replication

This chapter includes the following sections:

Introduction to Replication

Replication is a topology wide feature that always involves more than one participant.

Replication works as follows:

  1. A master receives a change. Once the change has been applied to the entry in the database, then because the server is a master, it stores the change in the change log database.

  2. The master updates its Replica Update Vector (RUV).

  3. The master notifies the replication threads that a new change has been recorded in the change log.

  4. These replication threads contact replication partners to propagate the information.

For example, Master 1 receives a change, applies it to the entry and updates its change log. When master 1 contacts the consumer, the consumer shows that master replica its RUV. The master looks at the RUV and compares it with its own RUV to see if it contains more recent changes than the consumer. If, for example, it sees that the consumer contains a higher RUV, it does not send changes. If it contains a more recent change, it sends another request to the consumer asking for a lock on replica ID 1 so that it can make updates. If the lock is unavailable, the update will be made later. If the lock is available, then the master can proceed to make the change.

This introduction to replication addresses the following topics:

Suppliers and Consumers

A Directory Server that replicates to other servers is called a supplier. A Directory Server that is updated by other servers is called a consumer. The supplier replays all updates on the consumer through specially designed LDAP v3 extended operations. In terms of performance, a supplier is therefore likely to be a demanding client application for the consumer.

A server can be both a supplier and a consumer, as in the following situations:

A server that plays the role of a consumer only is called a dedicated consumer.

For a master replica, the server must do the following:

The server that contains the master replica is responsible for recording any changes made to the master replica and for replicating these changes to consumers.

For a hub replica, the server must do the following:

For a consumer replica, the server must do the following:

Unit of Replication

The smallest logical unit of replication is a suffix, also known as a naming context. The term suffix arises from the way the base DN for the naming context is a suffix for all DNs in that context. For example, the suffix dc=example,dc=com contains all directory entries in the Example.com naming context.

The replication mechanism requires one suffix to correspond to one database. The unit of replication applies to both suppliers and consumers. Therefore, two suffixes on a master replica cannot be replicated to one suffix on a consumer replica, and vice versa.

Replica Identity

Master replicas require a unique replica identifier that is a 16-bit integer between 1 and 65534. Consumer and hub replicas all have the replica ID of 65535. The replica ID identifies the replica on which changes are made.

If multiple suffixes are configured on one master, you can use the same replica ID for each suffix on the master. In this way, when a change is made on that replica ID, it is possible to identify the server on which change was made.

Types of Replica

A suffix that participates in replication is called a replica. There are three kinds of replica:

A single instance of Directory Server can be configured to manage several replicas.

A replica can act as a supplier of updates, or a consumer of updates, or both.

A replica can be promoted or demoted to change its behavior with respect to other replicas. Dedicated consumers can be promoted to hubs, and hubs can be promoted to masters. Masters can be demoted to hubs, and hubs can be demoted to dedicated consumers.

A server that contains a consumer replica only is called a dedicated consumer.

Replication Agreements

Replication agreements define the relationships between a supplier and a consumer. The replication agreement is configured on the supplier. A replication agreement contains the following replication parameters:

Replication Authentication

Before a master can update a consumer, the consumer authenticates the master by using a special entry called the Replication Manager entry. The master uses the Replication Manager entry to bind to the consumer.

The Replication Manager entry has a special user profile that bypasses all access control rules defined on the consumer server. The special user profile is only valid in the context of replication.

The Replication Manager entry has the following characteristics.

The Replication Manager entry is created by default when you configure replication through the browser-based interfaceDirectory Service Control Center. You can also create your own Replication Manager entry. For information about how to create a Replication Manager entry, see Using a Non-Default Replication Manager in Oracle Fusion Middleware Administration Guide for Oracle Directory Server Enterprise Edition.

Authentication can be performed in the following ways for SSL with replication.

Replication Change Log

All modifications received by a master replica are recorded in a change log. A change log is maintained on all master replicas and hub replicas.

If your application needs to read the change log, use the retro change log plug-in for backward compatibility. For more information about the retro change log plug-in, see Replication and the Retro Change Log Plug-In.

Change Sequence Number

Each change to a master replica is identified by a change sequence number, CSN. The CSN is generated by the master server and is not visible to the client application. The CSN contains the timestamp, a sequence number, the replica ID, and a subsequence number. The change log is ordered by the CSN.

Replication is sequential, meaning that entries are replicated in an orderly way. Because replication is orderly, any change generated by a master is labeled by a change sequence number (CSN) that is unique for any change inside a multi-master topology. The CSN is a hexadecimal string that appears in the logs as follows:


41e6ee93000e00640000

The first 8 hexa-digits represent the time when the change was generated in the master. The time is represented in seconds since January 1, 1970.

The next four digits are the sequence number, or the order in the current second in which the change occurred. For example, multiple changes occur in second 41e6ee93. The sequence number tells us the progressive numbering of the change.

The next four digits specify the replica ID of the master that received the change in the first place.

The last four digits are reserved. Most of the time, they are 0000.

CSNs are generated only when local traffic introduces a new change to a replica. So only masters that receive updates generate CSNs. Consumers always refer to masters, because all the updates they receive are through replication.

Replica Update Vector

The replica update vector, RUV, identifies the state of each replica in a topology. Stored on the supplier and on the consumer, the RUV is used to establish which changes need to be replicated. The RUV stores the URL of the supplier, the ID of the supplier, the minimum CSN, and the maximum CSN.

Any replica in a replication topology stores its current replication state in a replica update vector (RUV). The RUV is stored in memory by a process that is running and provides the exact knowledge this replica has of itself and every other participant in the replication topology. The RUV entry on a given server contains a line for each master participating in a replication topology. Each line contains an identifier of one of the masters, the URL of the replica, and the CSN of the first and last changes made on the server. The CSN records only the first and last changes known by the server, not necessarily the most recent changes made by the master.

The RUV is mainly in memory and can be accessed using ldapsearch on the cn=replica,cn=suffix,cn=mapping tree,cn=config entry. For example, an ldapsearch for the ou=people suffix might yield the following results:


# ldapsearch -h host1 -p 1389 -D "cn=Directory Manager" -w secret \
-b "cn=replica,cn=ou=people,cn=mapping tree,cn=config" \
-s base objectclass=* nsds50ruv

nsds50ruv: {replicageneration} 45e8296c000000010000
nsds50ruv: {replica 1 ldap://server1:1389} 45ed8751000000010000 4600f252000000010000
nsds50ruv: {replica 2 ldap://server1:2389} 45eec0e1000000020000 45f03214000000020000

For clarity, we will simplify the RUV syntax to CSNchangenumber-replicaid. The change-number shows which change the RUV corresponds to in the successive changes that occurred on the master. For example, 45ed8751000000010000 can be written as CSN05-1. In the previous illustration, master 1 contains the following RUVs:


replica 1: CSN05-1 CSN43-1
replica 2: CSN05-2 CSN40-2

The first line provides information about the first change and the last change that this replica knows about from itself, master 1, as indicated by the replica ID 1. The second line provides information about the first change and the last change that it knows about from master 2. The information that is most interesting to us is the last change. In normal operations, master 1 should know more about the updates it received than master 2. We confirm this by looking at the RUV for master 2:


replica 2: CSN05-2 CSN50-2
replica 1: CSN01-1 CSN35-1

Looking at the last change, we see that master 2 knows more about the last change it received (CSN50-2) than master 1 (which shows the last change as having occurred at CSN40-2). By contrast, master 1 knows more about its last change (CSN43-1) than master 2 (CSN35-1).

When troubleshooting problems with replication, the CSNs can be useful in identifying the problem. Master 1 should always know at least as much about its own replica ID as any other participant in the replication topology because the change was first applied on master 1 and then replicated. So, CSN43-1 should be the highest value attributed to replica ID 1 in the topology.

A problem is identified if, for example, after 30 minutes the RUV on master 1 is still CSN40-2 but on master 2 the RUV has increased significantly to CSN67-2. This indicates that replication is not happening from master 2 to master 1.

If a failure occurs and you need to reinitialize the topology while saving as much data as possible, you can use the RUV picture to determine which machine contains the most recent changes. For example, in the replication topology described previously you have a hub that contains the following RUV:


2: CSN05-2 CSN50-2
1: CSN05-1 CSN43-1

In this case, server 1 seems like a good candidate for providing the most recent changes.

RUVs can be read through nsds50ruv(5dsconf) and ds6ruv(5dsconf) attributes.

Deleted Entries: Tombstones

Directory entries deleted on one replica are maintained by Directory Server until no longer needed for replication. Such deleted entries are called tombstones, as they have objectclass: nsTombstone. In rare cases, you might need to remove tombstones manually over LDAP.

Tombstones are visible only to Directory Manager. Furthermore, tombstones show up only in a search with filter (objectclass=nsTombstone). The following ldapsearch command returns tombstone entries under dc=example,dc=com.


$ ldapsearch -D "cn=Directory Manager" -b dc=example,dc=com "(objectclass=nsTombstone)"

Consumer Initialization and Incremental Updates

During consumer initialization, or total update, all data is physically copied from a master to a consumer. When you have created a replication agreement, the consumer defined by that agreement must be initialized. When a consumer has been initialized, the master can begin to replay, or replicate, update operations to the consumer. Under normal circumstances, the consumer should not require further initialization. However, if the data on a master is restored from a backup, it might be necessary to reinitialize the consumers that depend on that master.

In a multi-master replication topology, the default behavior of a read-write replica that has been re-initialized from a backup or from an LDIF file, is to refuse client update requests. By default, the replica remains in read-only mode until it is configured to accept updates again. You set the suffix property repl-accept-client-update-enabled to on using the dsconf set-suffix-prop command when the oldest updates are on the read-only replica.

When a consumer has been initialized, replication updates are sent to the consumer when the modifications are made on the supplier. These updates are called incremental updates. A consumer can be incrementally updated by several suppliers at once, provided that the updates originate from different replica IDs.

The binary copy feature can be used to clone master replicas or consumer replicas by using the binary backup files of one server to restore another server. For information about how to use binary copy for replication, see Initializing a Replicated Suffix by Using Binary Copy in Oracle Fusion Middleware Administration Guide for Oracle Directory Server Enterprise Edition.

Referrals and Replication

When a consumer receives a request to modify data, it does not forward the request to the server that contains the master replica. Instead, it returns to the client a list of the URLs of the masters that can satisfy the request. These URLs are called referrals.

The replication mechanism automatically configures consumers to return referrals for all known masters in the replication topology. However, you can also add your own referrals and overwrite the referrals set automatically by the server. The ability to control referrals helps enables you to perform the following tasks:

Directory Proxy Server is able to follow referrals.

Replication and the Retro Change Log Plug-In

The retro change log is a plug-in used by LDAP clients for maintaining application compatibility with earlier versions of Directory Server. The retro change log is stored in a separate database from the Directory Server change log, under the suffix cn=changelog.

A retro change log can be enabled on a standalone server or on each server in a replication topology. When the retro change log is enabled on a server, updates to all suffixes on that server are logged by default.

The retro changelog receives updates from all master replicas in the topology. The updates from each master replica are combined in the retro changelog. The retro changelog provides a way for applications to track changes so that they can be synchronized. Directory Server enables you to access a coherent version of the retro changelog on any master in a multi-master topology. You can also update your application to manage its state according to change numbers. This makes it possible to fail over between retro changelogs on different servers.

The global retro changelog contains all of the changes. If two changes occur on the same entry in two different locations, the retro changelog provides an ordered change description. If you query the retro changelog from any server, it will contain similar information.

For information about how to use the retro change log, see Using the Retro Change Log in Oracle Fusion Middleware Administration Guide for Oracle Directory Server Enterprise Edition.

Retro Change Log and Multi-Master Replication

The following figure illustrates the retro change log on two servers in a multi-master topology.

Figure 7–1 Retro Change Log and Multi-Master Replication

Figure shows the retro change log on two servers in a multi-master topology.

The retro change log uses the following attributes during replication:

changeNumber (cN)

Identifies the order in which an update is logged to the retro change log

replicationCSN (CSN)

Identifies the time when an update is made to a given replica

replicaIdentifier (RI)

Identifies the replica that is updating the retro change log

The diagram shows that the retro change logs, RCL1 and RCL2, contain the same list of updates, but that the updates do not have the same order. However, for a given replicaIdentifier, updates are logged in the same order on each retro change log. The order in which updates are logged to the retro change log is given by the changeNumber attribute.

Failover of the Retro Change Log

The following figure illustrates a simplified replication topology where a client reads a retro change log on a consumer server.

Figure 7–2 Simplified Topology for Replication of the Retro Change Log

Figure shows a simplified replication topology where a client reads a retro change log on a consumer server.

All of the updates made to each master replica in the topology are logged to each retro change log in the topology.

The client application reads the retro change log of Directory Server 3 and stores the last CSN for each replica identifier. The last CSN for each replica identifier is given by the replicationCSN attribute.

The following figure shows the client redirecting its reads to Directory Server 2 after the failure of Directory Server 3.

Figure 7–3 Failover of the Retro Change Log

Figure shows a client redirecting its reads to Directory Server 2 after the failure of Directory Server 3.

After failover, the client application must use the retro change log (RCL2) of Directory Server 2 to manage its updates. Because the order of the updates in RCL2 is not the same as the order in RCL3, the client must synchronize its updates with RCL2.

The client examines RCL2 to identify the cN that corresponds to its record of the last CSN for each replica identifier. In the example in Failover of the Retro Change Log, the client identifies the following correspondence between last CSN and cN:

The client identifies the update corresponding to the lowest cN in this list. In the example in Failover of the Retro Change Log, the lowest cN in the list is cN4. To ensure that the client processes all updates, it must process all updates logged to RCL2 after cN4. The client does not process updates logged to RCL2 before cN4 nor does it process the update corresponding to cN4.

Replication Conflicts and the Retro Change Log

When a replication conflict occurs, Directory Server performs operations to resolve the conflict. When the retro change log is running and the changeIsReplFixupOp attribute is set to true, the following information about the operations is logged in the changeHasReplFixupOp attribute:

For more information about these attributes, see the Oracle Fusion Middleware Man Page Reference for Oracle Directory Server Enterprise Edition.

Restrictions on Using the Retro Change Log

In a replicated topology, the retro change logs on replicated servers must be up-to-date with each other. This allows switchover of the retro change log. Using the example in Failover of the Retro Change Log, the last CSN for each replica ID on RCL3 must be present on RCL2.

Chapter 8 Directory Server Data Caching

For fast response time to client requests, Directory Server caches directory information in memory. If you must have top Directory Server performance, but cannot fit all directory data in available memory, you can tune cache settings to optimize performance.

This chapter covers what cache is.

Caches and How Directory Server Uses Them

This section describes the types of cache whose settings you can tune. It also describes how Directory Server uses those types of cache. This section covers the following topics:

Types of Cache

This section describes the types of cache used by Directory Server.

Figure 8–1 shows the caches for an instance of Directory Server with three suffixes, each with its own entry cache.

Directory Server also uses a file system cache. The file system cache is managed by the underlying operating system, and by I/O buffers in disk subsystems.

Figure 8–1 Entry and Database Caches in Context

Figure shows caches for an instance of Directory Server with three suffixes, each with its own entry cache.

Database Cache

Each instance of Directory Server has one database cache. The database cache holds pages from the databases that contain indexes and entries. Each page is not an entry, but a slice of memory that contains a portion of the database.

Directory Server moves pages between the database files and the database cache to maintain the maximum database cache size you specify. The amount of memory used by Directory Server for the database cache can be larger than the specified size. This is because Directory Server requires additional memory to manage the database cache.

The memory can be monitored by empirical testing and by the use of tools such as pmap(1) on Solaris systems. The ps(1) utility can also be used with the -p pid and -o format options to view current memory used by a particular process such as Directory Server ns-slapd. For more information, refer to the operating system documentation.

Entry Cache

The entry cache holds recently accessed entries that are formatted for delivery to client applications. The entry cache is allocated as required until it reaches a size larger than, but based on the maximum entry cache size you specify.

As entries stored in the entry cache are already formatted, Directory Server returns entries from an entry cache efficiently. Entries in the database must be formatted and stored in the entry cache before they are delivered to client applications.

The maximum size you specify indicates how much memory Directory Server requests from the underlying memory allocation library. Depending on how the memory allocation library handles requests for memory, the actual memory used may be much larger than the amount of memory available to Directory Server for the entry cache.

The memory used by the Directory Server process depends on the memory allocation library that is used, and depends on the entries cached. Entries with many small attribute values usually require more overhead than entries with few large attribute values.

Import Cache

The import cache is created and used when a suffix is initialized. If the deployment involves offline suffix initialization only, import cache and database cache are not used together. In this case, the import cache and database cache do not need to be added together when the cache size is aggregated. See Total Aggregate Cache Size. When the import cache size is changed, the change takes effect the next time the suffix is reset and initialized. The import cache is allocated for the initialization, then released after the initialization.

Directory Server handles import cache in the same way as it handles database cache. Sufficient physical memory must be available to prevent swapping. The benefits of having a larger import cache diminish for cache sizes larger than 2 GB.

File System Cache

The operating system allocates available memory not used by Directory Server caches and other applications to the file system cache. The file system cache holds data that was recently read from the disk, making it possible for subsequent requests to obtain data from cache rather than having to read it again from the disk. Because memory access is many times faster than disk access, leaving some physical memory available for the file system cache can boost performance.

The filesystem cache can be used as a replacement for some of the database cache. Database cache is more efficient for Directory Server use than file system cache, but file system cache is not directly associated with the Directory Server ns-slapd process. Potentially, a larger total cache can be made available to Directory Server than would be available by using database cache alone.

Refer to the operating system documentation for information about file system cache.

Total Aggregate Cache Size

The sum of all caches used simultaneously must remain smaller than the total size of available physical memory, minus the memory intended for file system cache, minus the memory intended for other processes such as Directory Server itself.

For 32-bit servers, the total aggregate cache size must be limited so that the total Directory Server ns-slapd process size is less than the maximum process size allowed by the operating system. In practice, this limit is generally in the 2-3 GB range.

If suffixes are initialized while Directory Server is online, the sum of the database cache, the entry cache, and the import cache sizes should remain smaller than the total size of available physical memory.

Table 8–1 Import Operations and Cache Use

Cache Type  

Offline Import  

Online Import  

Database 

no 

yes 

Entry 

yes 

yes 

Import 

yes 

yes 

If all suffixes are initialized while Directory Server is offline, the import cache does not coexist with the database cache, so the same memory can be allocated to the import cache for offline suffix initialization and to the database cache for online use. If you opt to implement this special case, however, ensure that no online bulk loads are performed on a production server. The sum of the caches used simultaneously must remain smaller than the total size of available physical memory.

For very large caches, it is important that the memory used by Directory Server does not exceed the size of available physical memory. If the available physical memory is exceeded, the system pages repeatedly and performance is degraded.

How Directory Server Performs Searches by Using Cache

In Figure 8–2, individual lines represent threads that access different levels of memory. Broken lines represent probable bottlenecks to minimize through effective tuning of Directory Server.

Figure 8–2 How Directory Server Performs Searches

Figure illustrates how Directory Server performs searches that specify a base DN and searches that use filters.

The following sections describe how Directory Server performs searches by using the cache. By processing subtree searches as described in the following sections, Directory Server returns results without loading the whole set of results into memory.

How Directory Server Performs Base Searches

    Base searches specify a base DN and are the simplest type of searches for Directory Server to manage. Directory Server processes base searches in the following stages.

  1. Directory Server attempts to retrieve the entry from the entry cache.

    If the entry is found in the entry cache, Directory Server checks whether the candidate entry matches the filter provided for the search.

    If the entry matches the filter provided for the search, Directory Server returns the formatted, cached entry to the client application.

  2. Directory Server attempts to retrieve the entry from the database cache.

    If the entry is found in the database cache, Directory Server copies the entry to the entry cache for the suffix. Directory Server proceeds as if the entry had been found in the entry cache.

  3. Directory Server attempts to retrieve the entry from the database itself.

    If the entry is found in the database, Directory Server copies the entry to the database cache . Directory Server proceeds as if the entry had been found in the database cache.

How Directory Server Performs Subtree and One-Level Searches

    Searches on a subtree or a level of a tree involve additional processing to handle multiple entries. Directory Server processes subtree searches and one-level search in the following stages.

  1. Directory Server attempts to define a set of candidate entries that match the filter from indexes in the database cache.

    If no appropriate index is present, the set of candidate entries must be found directly in the database itself.

  2. For each candidate entry, Directory Server performs the following tasks.

    1. Performs a base search to retrieve the entry.

    2. Checks whether the entry matches the filter provided for the search.

    3. Returns the entry to the client application if the entry matches the filter.

How Directory Server Performs Updates by Using the Cache

In Figure 8–3, individual lines represent threads that access different levels of memory. Broken lines represent probable bottlenecks to minimize through effective tuning of Directory Server.

Figure 8–3 How Directory Server Performs Updates

Figure illustrates how Directory Server manages updates.

The figure does not show the impact of the internal base search performed to get the entry for update.

    Directory Server processes updates in the following stages.

  1. Directory Server performs a base DN search to retrieve the entry, or to update or verify the entry in the case of an add operation that it does not already exist.

  2. Directory Server updates the database cache and any indexes affected.

    If data affected by the change have not been loaded into the database cache, this step can result in disk activity while the relevant data are loaded into the cache.

  3. Directory Server writes information about the changes to the transaction log and waits for the information to be flushed to disk, which happens periodically, at each checkpoint. Directory Server database files are thus updated during the checkpoint operation, not for each write.

  4. Directory Server formats and copies the updated entry to the entry cache for the suffix.

  5. Directory Server returns an acknowledgement of successful update to the client application.

How Directory Server Initializes a Suffix by Using the Cache

The following figure illustrates how Directory Server initializes a suffix by using the cache. Individual lines represent threads that access different levels of memory. Broken lines represent probable bottlenecks to minimize through effective tuning of Directory Server.

Figure 8–4 How Directory Server Initializes a Suffix

Figure illustrates how Directory Server initializes a suffix by using the cache.

Directory Server initializes a suffix in the following stages:

  1. Starts a thread to feed a buffer from LDIF.

  2. Starts a thread for each index affected and other working threads to update the indexes. These threads use the import cache.

  3. Reads from and writes to the database files when import cache runs out.

Directory Server also writes log messages during suffix initialization, but does not write to the transaction log.

Tools for suffix initialization delivered with Directory Server provide feedback on the cache hit rate and import throughput. If cache hit rate and import throughput drop together, it is possible that the import cache is too small.

Chapter 9 Directory Server Indexing

Like a book index, Directory Server indexes speed up searches by associating search strings with the contents of a directory. For information about indexes used by Directory Server, see following sections:

Overview of Indexes

Directory Server uses indexes to speed up search operations by associating lookup information with Directory Server entries. During a search operation, Directory Server uses the index to find entries that match the search key . Without an index, Directory Server must check every entry in a suffix to find matches for the search key.

Indexes are stored in database files, and are created and managed independently for each suffix in a directory. Each index file contains all of the indexes defined in the suffix for a given attribute. For example, all indexes maintained for the cn attribute are stored in the databaseName_cn.db3 file. When an indexed entry is modified, Directory Server updates the index files.

Directory Server supports the following types of indexes:

System Indexes and Default Indexes

This section addresses the following topics:

System Indexes

System indexes are required for Directory Server to function properly and efficiently. System indexes cannot be deleted or modified. Table 9–1 lists the system indexes created automatically in every suffix.

Table 9–1 System Indexes in Every Suffix

Attribute 

Equality Index 

Presence Index 

Description 

aci

 

X 

Allows the directory server to quickly obtain the access control information maintained in the directory 

ancestorid

X 

 

Enhances directory performance during subtree searches 

entrydn

X 

 

Speeds up entry retrieval based on DN searches 

id2entry

X 

 

Contains the actual database of directory entries. All other database files can be recreated from this one 

nsUniqueId

X 

 

Used to search for specific entries 

nscpEntryDN

X 

 

Used internally in Directory Server for replication 

nsds5ReplConflict

X 

X 

Helps to find replication conflicts 

numsubordinates

 

X 

Used by Directory Service Control Center to enhance display performance on the Directory tab 

objectClass

X 

 

Accelerate subtree searches 

parentID

X 

 

Enhances directory performance during one-level searches 

Default Indexes

When you create a new suffix in your directory, the server configures a set of default indexes in the corresponding database directory. The default indexes can be modified depending on your indexing needs, although you should ensure that no server plug-ins or other servers in your enterprise depend on an indexed attribute before you eliminate index.

Table 9–2 lists the default indexes that are configured in Directory Server.

Table 9–2 Default Indexes in Every New Suffix

Attribute 

Equality Index 

Presence Index 

Substring Index 

Description 

cn

X 

X 

X 

Improves the performance of the most common types of directory searches. 

givenName

X 

X 

X 

Improves the performance of the most common types of directory searches. 

mail

X 

X 

X 

Improves the performance of the most common types of directory searches. 

mailAlternateAddress

X 

   

Used by Messaging Server. 

mailHost

X 

   

Used by Messaging Server. 

member

X 

   

Improves server performance. This index is also used by the referential integrity plug-in.  

nsCalXItemId

X 

X 

X 

Used by Calendar Server. 

nsLIProfileName

X 

   

Used by roaming feature of Messaging Server. 

nsRoleDN

X 

   

Improves the performance of role-based operations. 

nswcalCALID

X 

   

Used by Calendar Server. 

owner

X 

   

Improves server performance. This index is also used by the referential integrity plug-in.  

pipstatus

X 

   

Used by other servers. 

pipuid

 

X 

 

Used by other servers. 

seeAlso

X 

   

Improves server performance. This index is used by the referential integrity plug-in.  

sn

X 

X 

X 

Improves the performance of the most common types of user directory searches. 

telephoneNumber

X 

X 

X 

Improves the performance of the most common types of user directory searches. 

uid

X 

   

Improves server performance. 

uniquemember

X 

   

Improves server performance. This index is also used by the referential integrity plug-in.  

Types of Index

With the exception of the approximate index, the indexes in this section are used by Directory Server to speed up basic matching rules. This section covers the following index types:

Presence Index

The presence index includes all entries in the database that have a value for a specified attribute, irrespective of that value. The following figure shows a presence index for the nsRoleDN attribute. For information about this attribute, see nsRoleDN(5dsat).

Figure 9–1 Presence Index

Illustration of a presence index for the nsRoleDN attribute.

Directory Server uses the value of the entryid attribute to store a reference to the entry. Directory Server retrieves the entry by using the instance-path/db/dbinstance/dbinstance_id2entry.db3 index file, where dbinstance depends on the database identifier.

When Directory Server receives a request to remove an attribute value indexed for presence, it must remove the entry from the presence index for that attribute before acknowledging the update to the client application.

The cost of presence indexes is generally low, although the list of entries maintained for a presence index may be long. When the index list length is small, presence indexes are useful for attributes in a relatively small percentage of directory entries.

Equality Index

The equality index includes all entries in the database that have a specified value for a given attribute. This index requires a value to be specified in the search filter. The following figure shows an equality index for the sn, surname, attribute. The index maintains a list of values for the sn attribute. For information about this attribute, see sn(5dsat).

Figure 9–2 Equality Index

Illustration of a equality index for the sn attribute.

When Directory Server receives a request to update an entry indexed for equality, it must do the following tasks before performing the update and acknowledging the update to the client:

The cost of equality indexes is generally lower than for substring indexes, but equality indexes require more space than presence indexes. Some client applications such as messaging servers might rely on equality indexes for search performance. Avoid using equality indexes for large binary attributes such as photos and hashed passwords.

Substring Index

Substring indexes are used for searches on three-character groups, for example, sn=*abc*. The three-character groups are stored in the index. Substring indexes cannot be applied to binary attributes such as photos. The following figure shows a substring index for the SN attribute.

Figure 9–3 Substring Index for the SN Attribute

Illustration of a substring index for the SN attribute.

The Directory Server search algorithm includes optimizations for the following searches, however, these searches are more likely to reach the index list threshold:

Directory Server builds an index of substrings according to its own built-in rules. Substring indexes cannot be configured by the system administrator.

When Directory Server receives a request to update an entry that has an attribute indexed for substrings, it must do the following tasks before performing the update and acknowledging the update to the client:

Maintaining substring indexes is relatively costly; the cost is a function of the length of the string indexed. To minimize cost, avoid unnecessary substring indexes, especially for attributes that have potentially long string values such as a description.

Browsing Index

Browsing indexes are also called virtual list view indexes. Browsing indexes are used for search operations that request server-side sorting or virtual list view, VLV, results. By using browsing indexes, you can improve the performance of searches that request server-side sorting of a large number of results. Depending on your directory configuration, the server may refuse to perform searches that request sorting when no browsing index is defined. This prevents large sorting operations from overloading server resources.

Browsing indexes are configured with the following parameters in the vlvSearch(5dsoc) object class, vlvBase(5dsat)vlvScope(5dsat), vlvScope(5dsat), and vlvFilter(5dsat). Browsing index are sorted by the following parameter in the vlvIndex(5dsoc) object class, vlvSort(5dsat).

    Browsing indexes are configured in two steps.

  1. The base of the search, the scope of the search, and a filter for the search are configured by the vlvBase, vlvScope, and vlvFilter attributes in the vlvSearch object class.

  2. The name of the attributes that sort the index are configured by the vlvSort attribute in the vlvIndex object class.

The following figure shows a browsing index.

Figure 9–4 Representation of a Browsing Index

Illustration of a browsing index.

When Directory Server receives a request to update an entry with a vlvFilter value, it must do the following tasks before performing the update and acknowledging the update to the client:

Approximate Index

Approximate indexes work with the English language only to provide efficient “sounds-like” searches. For example, the approximate index is useful for searching partial names or misspelled names. Directory Server uses a variation of the metaphone phonetic algorithm to perform searches on an approximate index. Because the algorithm is based loosely on syllables, it is not effective for attributes that contain numbers, such as telephone numbers.

International Index

International indexes are also called matching rule indexes. International indexes associate language-specific matching rules with attributes. This index type enables attributes to be sorted and searched for in accordance with the language rules. International indexes use matching rules for particular locales to maintain indexes.

Standard support for international and other types of indexing can be extended by using a custom matching rule server plug-in.

Chapter 10 Directory Server Logging

For information about the types of logs used in Directory Server and for a description of the server logs, see the following sections:

Introduction to Logs

The following table summarizes the different logs used by the Directory Server.

Table 10–1 Logs Used by Directory Server

Log 

Type 

Description 

Transaction log 

Database 

Ensuring data integrity by committing each update operation to the transaction log on disk before the result code for the update operation is returned to the client application. 

When Directory Server accepts an update operation, it writes a log message about the operation to the transaction log. If the system crashes, Directory Server uses the transaction log to recover the database. 

Access log 

Flat file 

Evaluating directory use patterns, verifying configuration settings, diagnosing access problems. For information about access logs, see Access Logs.

Error log 

Flat file 

Debugging directory deployments. For information about error logs, see Error Logs.

Audit log 

Flat file 

Providing audit trails for security and data integrity. For information about audit logs, see Audit Logs.

Transaction Log

The following server properties configure the transaction log.

db-checkpoint-interval

How often Directory Server checkpoints the transaction log, ensures the entire database system is synchronized to disk, and cleans up transaction logs

db-durable-transaction-enabled

Whether update operations are committed to the transaction log on disk before result codes are sent to clients

db-log-buf-size

The buffer size for log information stored in memory until the buffer fills or the transaction commit forces the buffer to be written to disk

db-log-path

The path of the transaction log

db-batched-transaction-count

How many updates are accumulated before being committed to the directory database

See server(5dsconf) for details.

Access, Error, and Audit Logs

Access logs, error logs and audit logs are flat files that contain information about operations. For information about how to view and configure logs, see Chapter 14, Directory Server Logging, in Oracle Fusion Middleware Administration Guide for Oracle Directory Server Enterprise Edition.

By default, the logs are stored in the directory instance-path/logs/.

Log files can be rotated on demand, or can be scheduled to be rotated on a specific day-of-the week and time of day, or when the log file exceeds a specified minimum size.

Old log files are stored in the same path with the same name and an extension that contains the date that the file was created, in the format filename.YYYYMMDD-hhmmss. The server also maintains a file with the same name and the .rotationinfo extension to record the creation dates of all log files.

For information about access logs, error logs and audit logs, see the following sections:

Access Logs

Access logs contain information about connections between an LDAP client and a directory server. A connection is a sequence of requests from the same client, and can contain the following components:

Error Logs

Error logs contain a unique identifier of the error, warning or information message, and a human readable message. Errors are defined according to the following severity.

Error

The error is severe. Immediate action should be taken to avoid the loss or corruption of directory data.

Warning

The error is important. Action should be taken at some stage to prevent a severe error occurring in the future.

Info

An informative message, usually describing server activity. No action is necessary.

Audit Logs

Audit logs contain records of all modifications to configuration or suffix entries. The modifications are written in LDIF format.

Audit logging is not enabled by default. To enable audit logging, use the procedure To Enable the Audit Log in Oracle Fusion Middleware Administration Guide for Oracle Directory Server Enterprise Edition.

Content of Access, Error, and Audit Logs

The remainder of this chapter describes each of the parts of the log files.

Time Stamp

Each line of an access log file begins with a timestamp of this format:[20/Dec/2006:11:39:51 -0700]. The time stamp, -0700 indicates the time difference in relation to GMT.

The format of the time stamp can vary according to your platform. The connection, closed, and abandon records appear individually. All other records appear in pairs, consisting of a request for service record followed by a result record. The record pairs usually, but not exclusively, appear on adjacent lines.

Connection Number

The connection number is represented by conn=value. Every external request is listed with an incremental connection number.

When conn=Internal the operation is an internal operation. To log internal access operations, specify an access logging level of acc-internal in the dsconf configuration attribute.

File Descriptor

The file descriptor is represented by fd=value.

Every connection from an external LDAP client to a directory server requires a file descriptor from the operating system. The file descriptor is taken from a pool of available file descriptors.

Slot Number

The slot number has the same meaning as file descriptor. Slot number is a legacy section of the access log and can be ignored.

Operation Number

The operation number is represented by op=value.

For a connection, all operation request and result pairs are given incremental operation numbers beginning with op=0. The operation number identifies the operation being performed.

When op=-1, the LDAP request for the connection was not issued by an external LDAP client, but was initiated internally.

Method Type

The method type is represented by method=value.

The method type indicates which bind method was used by the client. The method type can have one of the following values.

0

No authentication

128

Simple bind with user password

sasl

SASL bind using external authentication mechanism

LDAP Version

The LDAP version can be LDAPv2 or LDAPv3. The LDAP version gives the LDAP version number that the LDAP client used to communicate with the LDAP server.

Error Number

The error number is represented by err=number.

The error number provides the LDAP result code returned from the LDAP operation. The LDAP error number 0 means that the operation was successful. For a list of LDAP result codes refer to Result Codes in Log Files.

Tag Number

The tag number is represented by tag=value.

The tags are used internally for message decoding and are not intended for use outside. The following tags are used most often.

tag=97

A client bind operation

tag=100

The entry for which you were searching

tag=101

The result from a search operation

tag=103

The result from a modify operation

tag=105

The result from an add operation

tag=107

The result from a delete operation

tag=109

The result from a modify DN operation

tag=111

The result from a compare operation

tag=115

A search reference when the entry you perform your search on holds a referral to the entry you require. Search references are expressed in terms of a referral.

tag=120

A result from an extended operation

Number of Entries

The number of entries is represented by nentries=value.

The number of entries indicates the number of entries that matched an LDAP search request.

Elapsed Time

The elapsed time is represented by etime=value.

Elapsed time indicates the time that it took to perform the LDAP operation. An etime value of 0 means that the operation took milliseconds to perform.

To log the time in microseconds, specify an access logging level of acc-timing in the dsconf configuration attribute.

LDAP Request Type

The LDAP request type indicates the type of LDAP request made by the client. The following types of LDAP requests can be made:

SRCH

Search

MOD

Modify

DEL

Delete

ADD

Add

MODDN

Modify DN

EXT

Extended operation

ABANDON

Abandon operation

COMPARE

Compare operation

LDAP Response Type

The LDAP response type indicates the LDAP response being returned by the server. The following LDAP responses can be returned:

RESULT

Result

ENTRY

Entry

REFERRAL

Referral or search reference

Unindexed Search Indicator

The unindexed search indicator is represented by notes=U.

In an unindexed search, the database is searched instead of the index file. Unindexed searches occur for the following reasons:

An unindexed search indicator is often accompanied by a large etime value because unindexed searches are usually more time consuming than indexed searches.

Extended Operation OID

An extended operation OID is represented by EXT oid="OID number". See extended-operations(5dsconf) for a list of supported extended operations.

Change Sequence Number in Log Files

The replication change sequence number is represented in log files by csn=value.

The presence of a change sequence number indicates that replication is enabled for this naming context.

Abandon Message

The abandon message is represented by ABANDON.

The presence of the abandon message indicates that an operation has been aborted. If the message ID succeeds in locating the operation that has been aborted, the log message reads as follows:

conn=12 op=2 ABANDON targetop=1 msgid=2 nentries=0 etime=0

However, if the message ID does not succeed in locating the operation, or if the operation had already finished prior to the ABANDON request being sent, then the log message reads as follows:

conn=12 op=2 ABANDON targetop=NOTFOUND msgid=2

The abandon message uses the following parameters:

nentries

Gives the number of entries sent before the operation was aborted

etime

Gives the number of seconds that elapsed before the operation was aborted

targetop

Identifies the operation to be aborted. If the value is NOTFOUND, the operation to be aborted was either an unknown operation or already complete

Message ID

The message ID is represented by msgId=value.

The message ID is the LDAP operation identifier generated by the client. The message ID can have a different value to the operation number, but identifies the same operation. The message ID in an ABANDON operation specifies which client operation is being abandoned.

The operation number starts counting at 0. However, in many client implementations the message ID number starts counting at 1. This explains why the message ID is frequently equal to the operation number plus 1.

SASL Multi-Stage Bind Logging

Directory Server logs each stage in the multi stage bind process and, where appropriate, the progress statement SASL bind in progress is included.

The DN used for access control decisions is logged in the BIND result line and not in the bind request line.

conn=14 op=1 RESULT err=0 tag=97 nentries=0 etime=0 dn="uid=myname,dc=example,dc=com"

For SASL binds, the DN value displayed in the BIND request line is not used by the server and is, therefore, not relevant. However, for SASL binds, the authenticated DN must be used for audit purposes. Therefore, the authenticated DN must be clearly logged. Having the authenticated DN logged in the BIND result line avoids any confusion as to which DN is which.

Options Description

The options description, options=persistent, indicates that a persistent search is being performed. Persistent searches can be used as a form of monitoring and can be configured to return changes to given configurations. The access log distinguishes between persistent and regular searches.

Connection Codes in Log Files

A connection code is included in the closing message of a log file. The connection code provides additional information about why the connection was closed. The following table describes the common connection codes.

Table 10–2 Summary of Connection Codes

Connection Code 

Description 

A1 

The client has closed the connection without performing an UNBIND. 

B1 

This connection code can have one of the following causes: 

  • The client has closed the connection without performing an UNBIND.

  • The BER element was corrupt. If BER elements, which encapsulate data being sent over the wire, are corrupt when they are received, a B1 connection code is logged to the access log. BER elements can be corrupted by physical layer network problems or bad LDAP client operations, such as an LDAP client aborting before receiving all request results.

B2 

The BER element is longer than the nsslapd-maxbersize attribute value.

B3 

A corrupt BER tag was encountered. 

B4 

The server failed to flush data response back to client. This code can occur when the client closes the connection to the server, before the server finished sending data to the client. 

P1 

The client connection was closed by a custom plug-in. None of the plug-ins provided by Directory Server close a connection. 

P2 

A closed connection or corrupt connection has been detected. 

T1 

The server closed the client connection because it was idle for longer than the idle-timeout server property.

T2 

The server closed the client connection because it was stalled for longer than the nsslapd-ioblocktimeout attribute value. This code can occur for the following reasons:

  • There is a network problem.

  • The server sends a lot of data to the client but the client does not read the data. As a result, the server’s transmit buffer becomes full.

U1 

The server closed the client connection because client sent an UNBIND request. 

Result Codes in Log Files

The following tables summarizes the LDAP result codes generated by an LDAP server and an LDAP client.

Table 10–3 Summary of Result Codes for LDAP Servers

Result Code 

Description 

0 

Success 

1 

Operations error 

2 

Protocol error 

3 

Time limit exceeded 

4 

Size limit exceeded 

5 

Compare false 

6 

Compare true 

7 

Authentication method not supported 

8 

Strong authentication required 

9 

Partial results and referral received 

10 

Referral received 

11 

Administrative limit exceeded 

12 

Unavailable critical extension 

13 

Confidentiality required 

14 

SASL bind in progress 

16 

No such attribute 

17 

Undefined attribute type 

18 

Inappropriate matching 

19 

Constraint violation 

20 

Type or value exists 

21 

Invalid syntax 

32 

No such object 

33 

Alias problem 

34 

Invalid DN syntax 

35 

Object is a leaf 

36 

Alias de-referencing problem 

48 

Inappropriate authentication 

49 

Invalid credentials 

50 

Insufficient access 

51 

Server is busy 

52 

Server is unavailable 

53 

Server is unwilling to perform 

54 

Loop detected 

64 

Naming violation 

65 

Object class violation 

66 

Operation not permitted on a non-leaf entry 

67 

Operation not permitted on a RDN 

68 

Entry already exists 

69 

Cannot modify object class 

70 

Results too large 

71 

Affects multiple servers 

76 

Virtual list view error 

Table 10–4 Summary of Result Codes for LDAP Clients

Result Code 

Description 

80 

Unknown error 

81 

Cannot contact LDAP server 

82 

Local error 

83 

Encoding error 

84 

Decoding error 

85 

Timed out 

86 

Unknown authentication method 

87 

Bad search filter 

88 

User cancelled operation 

89 

Bad parameter to an LDAP routine 

90 

Out of memory 

91 

Cannot connect to the LDAP server 

92 

Not supported by this version of LDAP 

93 

Requested LDAP control not found 

94 

No results returned 

95 

Additional results to return 

96 

Client detected loop 

97 

Referral hop limit exceeded 

Chapter 11 Directory Server Groups and Roles

The directory information tree organizes entries hierarchically. This hierarchy is a type of grouping mechanism. The hierarchy is not well suited for associations between dispersed entries, for organizations that change frequently, or for data that is repeated in many entries. Directory Server groups and roles offer more flexible associations between entries.

This chapter describes how groups and roles are used by Directory Server to associate entries with each other. This chapter covers the following topics:

Directory Server Groups

A group is an entry that identifies the other entries that are in the group. The group mechanism makes it easy to retrieve a list of entries that are members of a given group.

Although groups may identify members anywhere in the directory, the group definitions themselves should be located under an appropriately named node such as ou=Groups. This makes them easy to find, for example, when defining access control instructions (ACIs) that grant or restrict access when the bind credentials are members of a group.

Static Groups

Static groups explicitly name their member entries. For example, a group of directory administrators would name the specific people who formed part of that group, as shown in the following illustration.

Figure shows logic of static group

The following LDIF extract shows how the members of this static group would be defined.

dn: cn=Directory Administrators, ou=Groups, dc=example,dc=com
...
member: uid=kvaughan, ou=People, dc=example,dc=com
member: uid=rdaugherty, ou=People, dc=example,dc=com
member: uid=hmiller, ou=People, dc=example,dc=com

Static groups specify the DN of each member of the group. Static groups use one of the following object class and attribute pairs:

The member attribute and uniqueMember attribute contain the DN for every entry that is a member of the group. The uniqueMember attribute value for the DN is optionally followed by a hash, #, and a unique identifier label to guarantee uniqueness.

Dynamic Groups

Dynamic groups specify a filter and all entries that match the filter are members of the group. These groups are dynamic because membership is defined each time the filter is evaluated.

Imagine, for example, that all management employees and their assistants were situated on the 3rd floor of your building, and that the room number of each employee commenced with the number of the floor. If you wanted to create a group containing just the employees on the third floor, you could use the room number to define just these employees, as shown in the following illustration.

Figure shows logic of dynamic group

The following LDIF extract shows how the members of this dynamic group would be defined.

dn: cn=3rd Floor, ou=Groups, dc=example,dc=com
...
memberURL: ldap:///dc=example,dc=com??sub?(roomnumber=3*)

Dynamic groups use one of the following object class and attribute pairs:

The group members are listed either by one or more filters represented as LDAP URL values of the memberURL attribute or by one or more DNs as values of the uniqueMember attribute.

Nested Groups

Static and dynamic groups can be nested by specifying the DN of another group as a value for the member attribute or uniqueMember attribute. The depth to which nested groups are supported by ACIs is controlled by the nsslapd-groupevalnestlevel configuration parameter. Directory Server also supports mixed groups, that is groups that reference individual entries, static groups, and dynamic groups.

Imagine for example that you wanted a group containing all directory administrators, and all management employees and their assistants. You could use a combination of the two groups defined earlier to create one nested group, as shown in the following illustration.

Figure shows logic of nested group

The following LDIF extract shows how the members of this nested group would be defined.

dn: cn=Admins and 3rd Floor, ou=Groups, dc=example,dc=com
...
member: cn=Directory Administrators, ou=Groups, dc=example,dc=com
member: cn=3rd Floor, ou=Groups, dc=example,dc=com
Caution – Caution –

Nested groups are not the most efficient grouping mechanism. Dynamic nested groups incur an even greater performance cost. To avoid these performance problems, consider using roles instead.

Directory Server Roles

Roles are similar to groups but work in the opposite way — where a group entry lists the DN of the member entries, the DN of a role entry is listed on each member entry. The role mechanism makes it is easy to retrieve a list of roles that are assigned to an entry.

Each role has members, or entries that possess the role. The role mechanism is managed by the nsRoleDN attribute and the nsRole attribute. The nsRoleDN attribute is used to add an entry to a role. The nsRole attribute is a read-only attribute, maintained by the directory server, that lists the roles to which an entry belongs. The nsRole attribute can be read or searched by clients to enumerate all roles to which an entry belongs. If you do not want to expose role membership, define access controls to read-protect the nsRole attribute.

By default, the scope of a role is limited to the subtree where it is defined. The scope of a role can be extended to other subtrees on the same server instance.

Managed Roles

Managed roles are functionally very similar to static groups. Managed roles explicitly assign a role to each member entry by adding the nsRoleDN attribute to the entry. The value of this attribute is the DN of the role definition entry.

The role definition entry only defines the scope of the role in the directory. Members of the role are entries that lie within the scope of the role definition, and that identify the role definition entry with their nsRoleDN attributes.

Filtered Roles

Filtered roles are equivalent to dynamic groups. Entries are assigned a role if they match a specified search filter. The value of the search filter is defined by the nsRoleFilter attribute. When the server returns an entry in the scope of a filtered role, that entry contains the generated nsRole attribute that identifies the role.

Nested Roles

Nested roles are equivalent to nested groups. Nested roles enable you to create roles that contain other roles and to extend the scope of existing roles. A nested role can itself contain another nested role. Up to 30 levels of nesting are supported

A nested role lists the definition entries of other roles and combines all the members of their roles. If an entry is a member of a role that is listed in a nested role, then the entry is also a member of the nested role.

Limitations on Using Roles

When you use roles to support your directory service, be aware of the following limitations.

Filtered Roles cannot use CoS generated attributes

The filter string of a filtered role cannot be based on the values of a CoS virtual attribute. However, the specifier attribute in a CoS definition may reference the nsRole attribute generated by a role definition. For information about CoS, see Chapter 12, Directory Server Class of Service.

Extending the scope of roles

You can extend the scope of roles to different subtrees but they must be on the same server instance. You cannot extend the scope of roles to other servers.

Searches on the nsRole attribute

The nsRole attribute can be used in any search filter with any of the comparison operators. When you search on nsRole attribute, consider the following points:

  • Searches on the nsRole attribute can take a long time because all roles must be evaluated before the entries can be filtered.

  • Directory Server is optimized for equality searches on membership in managed roles. For example, this search will be nearly as fast as a search on real attributes.

    (&(nsRole=cn=managersRole,ou=People,dc=example,dc=com)
 (objectclass=person)

  • The nsRoleDN attribute is indexed by default in all suffixes. Optimizations for searching the membership of managed roles are lost if indexing is disabled for the nsRoleDN attribute.

  • Searches for entries that contain a filtered role involve an internal search with the role filter. This internal operation will be fastest if all attributes that appear in the role filter are indexed in all suffixes in the scope of the role.

Deciding Between Groups and Roles

The functionality of the groups and roles mechanisms overlap somewhat. Both mechanisms have advantages and disadvantages. Generally, the roles mechanism is designed to provide frequently required functionality more efficiently. Because the choice of a grouping mechanism influences server complexity and determines how clients process membership information, you must plan your grouping mechanism carefully. To decide which mechanism is more suitable, you need to understand the typical membership queries and management operations that are performed.

Advantages of the Groups Mechanism

Groups have the following advantages:

Advantages of the Roles Mechanism

Roles have the following advantages:

Restricting Permissions on Roles

Be aware of the following issues when using roles:

Chapter 12 Directory Server Class of Service

The Class of Service (CoS) mechanism allows attributes to be shared between entries. CoS values are calculated dynamically when they are requested. For information about CoS, see the following sections:

About CoS

Imagine a directory containing thousands of entries that all have the same value for the facsimileTelephoneNumber attribute. Traditionally, to change the fax number, you would update each entry individually, a time consuming job for administrators. Using CoS, the fax number is stored in a single place, and the facsimileTelephoneNumber attribute is automatically generated on every entry as it is returned.

To client applications, a CoS attribute is generated in the same ways as any other attribute. However, directory administrators now have only a single fax value to manage. Also, because there are fewer values stored in the directory, the database uses less disk space. The CoS mechanism also allows entries to override a generated value or to generate multiple values for the same attribute.

Note –

Because CoS virtual attributes are not indexed, referencing them in an LDAP search filter may have an impact on performance.

Generated CoS attributes can be multivalued. Specifiers can designate several template entries, or there can be several CoS definitions for the same attribute. Alternatively, you can specify template priorities so that only one value is generated from all templates.

Roles and classic CoS can be used together to provide role-based attributes. These attributes appear on an entry because it possesses a particular role with an associated CoS template. You could use a role-based attribute to set the server look through limit on a role-by-role basis, for example.

CoS functionality can be used recursively; you can generate attributes through CoS that depend on other attributes generated through CoS. Complex CoS schemes can simplify client access to information and ease administration of repeated attributes, but they also increase management complexity and degrade server performance. Avoid overly complex CoS schemes; many indirect CoS schemes can be redefined as classic or pointer CoS, for example.

You should also avoid changing CoS definitions more often than necessary. Modifications to CoS definitions do not take effect immediately, because the server caches CoS information. Although caching accelerates read access to generated attributes, when changes to CoS information occur, the server must reconstruct the cache. This task can take some time, usually in the order of seconds. During cache reconstruction, read operations may still access the old cached information, rather than the newly modified information, which means that if you change CoS definitions too frequently, you are likely to be accessing outdated data.

CoS Definition Entries and CoS Template Entries

The CoS mechanism relies on two types of entries, the CoS definition entry and the CoS template entry. This section describes the CoS definition entry and the CoS template entry.

CoS Definition Entry

The CoS definition entry identifies the type of CoS and the names of the CoS attributes that will be generated. Like the role definition entry, the CoS definition entry inherits from the LDAPsubentry object class. Multiple definitions may exist for the same CoS attribute, which, as a result, may be multivalued.

The CoS definition entry is an instance of the cosSuperDefinition object class. The CoS definition entry also inherits from one of the following object classes to specify the type of CoS:

The CoS definition entry contains the attributes specific to each type of CoS for naming the virtual CoS attribute, the template DN, and the specifier attribute in target entries. By default, the CoS mechanism will not override the value of an existing attribute with the same name as the CoS attribute. However, the syntax of the CoS definition entry allows you to control this behavior.

When schema checking is turned on, the CoS attribute will be generated on all target entries that allow that attribute. When schema checking is turned off, the CoS attribute will be generated on all target entries.

The location of the definition entry determines the scope of the CoS, which is the entire subtree below the parent of the CoS definition entry. All entries in the branch of the definition entry’s parent are called target entries for the CoS definition.

The following figure shows a CoS definition entry at the root of the ou=people subtree. The scope of the CoS is only the two subtrees beneath the root. The CoS does not extend above this root, or to other subtrees in the DIT.

Figure 12–1 CoS Scope

Figure shows CoS scope beneath the CoS definition entry.

CoS Template Entry

The CoS template entry contains the value that is generated for the CoS attribute. All entries within the scope of the CoS use the values defined here. There may be several templates, each with a different value, in which case the generated attribute may be multivalued. The CoS mechanism selects one of these values based on the contents of both the definition entry and the target entry.

The CoS template entry is an instance of the cosTemplate object class. The CoS template entry contains the value or values of the attributes generated by the CoS mechanism. The template entries for a given CoS are stored in the directory tree at the same level as the CoS definition.

When possible, definition and template entries should be located in the same place, for easier management. You should also name them in a way that suggests the functionality they provide. For example, a definition entry DN such as "cn=classicCosGenEmployeeType,ou=People,dc=example,dc=com" is more descriptive than "cn=ClassicCos1,ou=People,dc=example,dc=com". For more information about the object classes and attributes associated with each type of CoS, see Class of Service in Oracle Fusion Middleware Administration Guide for Oracle Directory Server Enterprise Edition.

Pointer CoS, Indirect CoS, and Classic CoS

The following types of CoS differ in how the template, and therefore the generated value, is selected:

Pointer CoS

Pointer CoS is the simplest type of CoS. The pointer CoS definition entry provides the DN of a specific template entry of the cosTemplate object class. All target entries have the same CoS attribute value, as defined by this template.

The following figure shows a pointer CoS that defines a common postal code for all of the entries stored under dc=example,dc=com. The CoS definition entry, CoS template entry and target entry are indicated.

Figure 12–2 Example of a Pointer CoS Definition and Template

Example of a Pointer CoS Definition and Template

The template entry is identified by its DN, cn=exampleUS,cn=data, in the CoS definition entry. Each time the postalCode attribute is queried on entries under dc=example,dc=com, Directory Server returns the value available in the template entry cn=exampleUS,cn=data. Therefore, the postal code will appear with the entry uid=wholiday,ou=people,dc=example,dc=com, but it is not stored there.

In a scenario where several shared attributes are generated by CoS for thousands or millions of entries, instead of existing as real attributes in each entry, the storage space savings and performance gains provided by CoS are considerable.

Indirect CoS

Indirect CoS allows any entry in the directory to be a template and provide the CoS value. The indirect CoS definition entry identifies an attribute, called the indirect specifier, whose value in a target entry determines the template used for that entry. The indirect specifier attribute in the target entry must contain a DN. With indirect CoS, each target entry may use a different template and thus have a different value for the CoS attribute.

For example, an indirect CoS that generates the departmentNumber attribute may use an employee’s manager as the specifier. When retrieving a target entry, the CoS mechanism will use the DN value of the manager attribute as the template. It will then generate the departmentNumber attribute for the employee using the same value as the manager’s department number.

Note –

Because templates may be arbitrary entries anywhere in the directory tree, implementing access control for indirect CoS can become extremely complex. In deployments where performance is critical, you should also avoid overusing indirect CoS due to its resource intensive nature.

In many cases, results that are similar to those made possible by indirect CoS can be achieved by limiting the location of the target entries with classic CoS or using the less flexible pointer CoS mechanism.

The following figure shows an indirect CoS that uses the manager attribute of the target entry to identify the template entry. In this way, the CoS mechanism can generate the departmentNumber attribute of all employees to be the same as their manager’s, ensuring that it is always up to date.

Figure 12–3 Example of an Indirect CoS Definition and Template

Example of an Indirect CoS Definition and Template

The indirect CoS definition entry names the specifier attribute, which in this example, is the manager attribute. William Holiday’s entry is one of the target entries of this CoS, and his manager attribute contains the DN of uid=cfuentes,ou=people,dc=example,dc=com. Therefore, Carla Fuentes’s entry is the template, which in turn provides the departmentNumber attribute value of 318842.

Classic CoS

Classic CoS combines the pointer and indirect CoS behavior. The classic CoS definition entry identifies the base DN of the template and a specifier attribute. The value of the specifier attribute in the target entries is then used to construct the DN of the template entry as follows:

cn=specifierValue, baseDN

The template containing the CoS values is determined by the combination of the RDN (relative distinguished name) value of the specifier attribute in the target entry and the template’s base DN.

Classic CoS templates are entries of the cosTemplate object class to avoid the performance issue associated with arbitrary indirect CoS templates.

The classic CoS mechanism determines the DN of the template from the base DN given in the definition entry and the specifier attribute in the target entry. The value of the specifier attribute is taken as the cn value in the template DN. Template DNs for classic CoS must therefore have the following structure:

cn=specifierValue,baseDN

The following figure shows a classic CoS definition that generates a value for the postal code attribute.

Figure 12–4 Example of a Classic CoS Definition and Template

Example of a Classic CoS Definition and Template

In this example, the cosSpecifier attribute names the employeeType attribute. The combination of the cosSpecifier attribute and the template DN identifies the template entry as cn=sales,cn=exampleUS,cn=data. The template entry then provides the value of the postalCode attribute to the target entry.

Managing Attributes With Class of Service

The Class of Service (CoS) mechanism allows attributes to be shared between entries. Like the role mechanism, CoS generates virtual attributes on the entries as the entries are retrieved. CoS does not define membership, but it does allow related entries to share data for coherency and space considerations. CoS values are calculated dynamically when the values are requested. CoS functionality and the various types of CoS are described in detail in the Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

The following sections examine the ways in which you can use the CoS functionality as intended, while avoiding performance pitfalls:

Note –

CoS generation always impacts performance. Client applications that search for more attributes than they actually need can compound the problem.

If you can influence how client applications are written, remind developers that client applications perform much better when looking up only those attribute values that they actually need.

Using CoS When Many Entries Share the Same Value

CoS provides substantial benefits for relatively low cost when you need the same attribute value to appear on numerous entries in a subtree.

Imagine, for example, a directory for MyCompany, Inc. in which every user entry under ou=People has a companyName attribute. Contractors have real values for companyName attributes on their entries, but all regular employees have a single CoS-generated value, MyCompany, Inc., for companyName. The following figure demonstrates this example with pointer CoS. Notice that CoS generates companyName values for all permanent employees without overriding real, not CoS-generated, companyName values stored for contractor employees. The company name is generated only for those entries for which companyName is an allowed attribute.

Figure 12–5 Generating CompanyName With Pointer CoS

Figure shows the CompanyName attribute generated with Pointer CoS.

In cases where many entries share the same value, pointer CoS works particularly well. The ease of maintaining companyName for permanent employees offsets the additional processing cost of generating attribute values. Deep directory information trees (DITs) tend to bring together entries that share common characteristics. Pointer CoS can be used in deep DITs to generate common attribute values by placing CoS definitions at appropriate branches in the tree.

Using CoS When Entries Have Natural Relationships

CoS also provides substantial data administration benefits when directory data has natural relationships.

Consider an enterprise directory in which every employee has a manager. Every employee shares a mail stop and fax number with the nearest administrative assistant. Figure 12–6 demonstrates the use of indirect CoS to retrieve the department number from the manager entry. In Figure 12–7, the mail stop and fax number are retrieved from the administrative assistant entry.

Figure 12–6 Generating DepartmentNumber With Indirect CoS

Figure shows the DepartmentNumber attribute generated with Indirect CoS.

In this implementation, the manager’s entry has a real value for departmentNumber, and this real value overrides any generated value. Directory Server does not generate attribute values from CoS-generated attribute values. Thus, in the Figure 12–6 example, the department number attribute value needs to be managed only on the manager's entry. Likewise, for the example shown in Figure 12–7, mail stop and fax number attributes need to be managed only on the administrative assistant’s entry.

Figure 12–7 Generating Mail Stop and Fax Number With Indirect CoS

Figure shows Mail Stop and Fax Number attributes generated with Indirect CoS.

A single CoS definition entry can be used to exploit relationships such as these for many different entries in the directory.

Another natural relationship is service level. Consider an Internet service provider that offers customers standard, silver, gold, and platinum packages. A customer’s disk quota, number of mailboxes, and rights to prepaid support levels depend on the service level purchased. The following figure demonstrates how a classic CoS scheme enables this functionality.

Figure 12–8 Generating Service-Level Data With Classic CoS

Figure shows service level data generated with Classic CoS.

One CoS definition might be associated with multiple CoS template entries.

Avoiding Excessive CoS Definitions

Directory Server optimizes CoS when one classic CoS definition entry is associated with multiple CoS template entries. Directory Server does not optimize CoS if many CoS definitions potentially apply. Instead, Directory Server checks each CoS definition to determine whether the definition applies. This behavior leads to performance problems if you have thousands of CoS definitions.

This situation can arise in a modified version of the example shown in Figure 12–8. Consider an Internet service provider that offers customers delegated administration of their customers’ service level. Each customer provides definition entries for standard, silver, gold, and platinum service levels. Ramping up to 1000 customers means creating 1000 classic CoS definitions. Directory Server performance would be affected as it runs through the list of 1000 CoS definitions to determine which apply. If you must use CoS in this sort of situation, consider indirect CoS. In indirect CoS, customers’ entries identify the entries that define their class of service allotments.

When you start approaching the limit of having different CoS schemes for every target entry or two, you are better off updating the real values. You then achieve better performance by reading real, not CoS-generated values.

CoS Priorities

It is possible to create CoS schemes that compete with each other to provide an attribute value. For example, you might have a multivalued cosSpecifier in your CoS definition entry. In such a case, you can specify a template priority on each template entry to determine which template provides the attribute value. Set the template priority using the cosPriority attribute. This attribute represents the global priority of a particular template numerically. A priority of zero is the highest possible priority.

Templates that contain no cosPriority attribute are considered the lowest possible priority. In the case where two or more templates are considered to supply an attribute value and they have the same (or no) priority, a value is chosen arbitrarily. Directory Server can be configured to log messages when it is forced to choose a template arbitrarily.

CoS Limitations

The CoS functionality is a complex mechanism which, for performance and security reasons, is subject to the following limitations:

Chapter 13 Directory Server DSMLv2

For information about DSMLv2 in Directory Server, see the following sections:

Introduction to DSML

Directory Services Markup Language version 2, DSMLv2, is a markup language that describes directory operations in an eXtensible Markup Language (XML) document. For information about the DSMLv2 standard, see Directory Services Markup Language (DSML) v2.0 [OASIS 200201] at http://www.oasis-open.org/specs.

The complete DSMLv2 specification and supporting documentation can be found at the following locations:

Directory Server supports DSMLv2 SOAP over HTTP binding. DSML requests and responses are embedded in the body of SOAP v1.1, and transported in an HTTP/1.1 payload.

The Directory Server Resource Kit contains tools for searching and modifying directories using DSMLv2. See dsmlsearch(1) and dsmlmodify(1).

By using DSML, non-LDAP clients can perform directory operations. The following figure shows an example deployment where a non-LDAP client makes a requests to modify data on DSML-enabled directory servers.

Figure 13–1 Sample DSML-Enabled Directory Deployment

Figure shows an example deployment where a non-LDAP client makes modification requests to DSML-enabled directory servers.

In the example deployment, update requests in DSML arrive from non-LDAP client applications cross a firewall over HTTP port 80. The web proxy server enforces the use of secure HTTP over port 443 for the requests to cross a second firewall and enter the intranet domain. The requests are then processed by the two master replicas on Master A and Master B, before being replicated to the non-DSML enabled Consumers C and D.

Implementation of the DSMLv2 Standard

The Directory Server implementation of the DSMLv2 specification has the following restrictions:

Bindings

DSMLv2 defines two normative bindings: a SOAP request/response binding and a file binding that serves as the DSMLv2 analog of LDIF. Directory Server supports the SOAP request/response binding.

Modify DN

Directory Server supports the DSML modDNRequest and modDNResponse operations.

Abandon request

Directory Server does not support the abandonRequest operation, because this operation is of no use over HTTP.

Search operations

Some DSML clients incorrectly send an equality match with value * when a presence match is intended. Directory Server will return zero results from these badly formatted queries. You can detect these incorrect clients by searching for the characters =\2a in the access log.

DSML Security

The DSML front end constitutes a restricted HTTP server; it accepts only DSML post operations, it rejects requests that do not conform to the DSMLv2 SOAP binding specifications.

The security of DSML is configured by the following server properties dsml-client-auth-mode, dsml-port, dsml-secure-port, and dsml-relative-root-url. For information about these properties, see server(5dsconf).

For additional security, consider the following.

DSML Identity Mapping

Identity mapping is required for the following mechanisms: DSML over HTTP, DIGEST-MD5, and GSSAPI SASL. Identity mapping is used to determine a bind DN based on protocol specific credentials provided by the client.

Identity mapping uses the entries in the cn=identity mapping, cn=config configuration branch. This branch includes the following containers for the protocols that perform identity mapping:

cn=HTTP-BASIC, cn=identity mapping, cn=config

Contains the mappings for DSML-over-HTTP connections.

cn=DIGEST-MD5, cn=identity mapping, cn=config

Contains the mappings for client authentication using the DIGEST-MD5 SASL mechanism.

cn=GSSAPI, cn=identity mapping, cn=config

Must be created to contain the mappings for client authentication using the GSSAPI SASL mechanism.

A mapping entry defines how to extract credentials about the protocol to use them in a search operation. If a search returns a single user entry, the mapping has succeeded and the connection uses the mapping entry as the bind DN for all operations. If the search returns zero or more than one entry, the mapping fails and the connection does not use the mapping entry as the bind DN.

The protocols that perform identity mapping must have a default mapping. Additionally, The protocols can have any number of custom mappings. The default mapping has the RDN cn=default, and custom mappings may have any other RDN that uses cn as the naming attribute. All of the custom mappings are evaluated first, in a non deterministic order until one of them succeeds. If all custom mappings fail, the default mapping is applied. If the default mapping fails, authentication of the client fails.

A mapping entry must contain the object classes top, container, and dsIdentityMapping.

The entry can contain the following attributes.

dsMappedDN: DN

A literal string that defines a DN in the directory. This DN will be used for binding if it exists when the mapping is performed. You may also define the following attributes to perform a search in case this DN does not exist.

dsSearchBaseDN: DN

The base DN for a search. If omitted, the mapping will search all root suffixes in the entire directory tree, including all naming contexts, but excluding cn=config, cn=monitor, and cn=schema.

dsSearchScope: base|one|sub

The scope for a search, either the search base itself, one level of children below the base, or the entire subtree below the base. The default scope for mapping searches is the entire subtree when this attribute is omitted.

dsSearchFilter: filterString

A filter string to perform the mapping search. LDAP search filters are defined in RFC 4515 on http://www.ietf.org/rfc/rfc4515.txt.

Additionally, a mapping entry may also contain the dsPatternMatching object class which allows it to use the following attributes:

dsMatching-pattern: patternString

A string on which to perform pattern matching.

dsMatching-regexp: regularExpression

A regular expression to apply to the pattern string.

All of the attribute values above, except for dsSearchScope may contain placeholders of the format ${keyword}, where keyword is the name of an element in the protocol-specific credentials. During mapping, the placeholder is substituted for the actual value of the element provided by the client.

After all of the placeholders have been substituted, the pattern matching is performed. The matching pattern is compared to the regular expression, as follows.

For example, the following mapping could be defined for SASL.

dsMatching-pattern: ${Principal}
dsMatching-regexp: (.*)@(.*)\\.(.*)
dsMappedDN: uid=$1,ou=people,dc=$2,dc=$3

If a client authenticates with the Principal of bjensen@example.com, this mapping will define the following bind DN: uid=bjensen,ou=people,dc=example,dc=com. If this DN exists in the directory, the mapping will succeed, the client will be authenticated, and all operations performed during this connection will use this bind DN.

The dsMatching-pattern is compared to the dsMatching-regexp by using the POSIX regexec(3C) and regcomp(3C) function calls. Directory Server uses extended regular expressions and all comparisons are case insensitive. For more information, refer to the man pages for these functions.

The attribute values that can contain placeholders must encode any $, {, and } characters that are not part of a placeholder, even if no placeholder is used. You must encode these characters with the following values: $ as \\24, { as \\7B, and } as \\7D.

The use of placeholders and substitutions allows you to create mappings that extract a username or any other value from the protocol-specific credentials. The credential can be used to define a mapped DN or perform a search for a corresponding DN anywhere in the directory.

Caution – Caution –

Creating a poorly defined mapping is a security hole. For example, a mapping to a hard coded DN without pattern matching will always succeed, thereby authenticating clients who might not be directory users. It is safer to define several mappings to handle different client credential formats than to create a single, overly generic and permissive mapping. Always try to map client connections to specific users according to the client credentials.

Content of the HTTP Header

Directory Server supports the HTTP POST operation only. The following example shows the minimum fields required to send a DSML request to the server over HTTP:

POST /dsml HTTP/1.1
content-length: 450
HOST: hostname
SOAPAction: ""
Content-Type: text/xml
Connection: close

The Connection field is optional. In HTTP 1.0, the default value of this field is close. In HTTP 1.1, however, the default value is keep-alive. It is therefore recommended that you include this field with a value of close in your last request if you are using HTTP 1.1, to accelerate the dialog.

Additional fields may be included in the HTTP header. If they are supported by Directory Server, their values will override the defaults. If the fields are not supported, the request is not rejected by the server but the fields are ignored.

Accessing the Directory Using DSMLv2

The following examples indicate how to use DSML requests to access and search the directory.

Note that the content-length: header in these examples contains the exact length of the DSMLv2 request. For these examples to function correctly, ensure that the editor you use respects these content lengths, or that you modify them accordingly.

An Empty Anonymous DSML Ping Request

The DSML front end is disabled by default. For information on how to enable it, refer to Configuring DSML in Oracle Fusion Middleware Administration Guide for Oracle Directory Server Enterprise Edition. To check whether the DSML front end is enabled, send an empty DSML batch request, as shown in Example 13–1.

Example 13–1 Empty Anonymous DSML Request

POST /dsml HTTP/1.1
 content-length: 451
 HOST: hostname
 SOAPAction: ""
 Content-Type: text/xml
Connection: close
<?xml version=’1.0’ encoding=’UTF-8’?\>
 <soap-env:Envelope
    xmlns:xsd=’http://www.w3.org/2001/XMLSchema’
   xmlns:xsi=’http://www.w3.org/2001/XMLSchema-instance’
   xmlns:soap-env=’http://schemas.xmlsoap.org/soap/envelope/’\>
   <soap-env:Body\>
       <batchRequest
           xmlns=’urn:oasis:names:tc:DSML:2:0:core’           requestID=’Ping!’\>
           <!-- empty batch request --\>
      </batchRequest\>
    </soap-env:Body\>
 </soap-env:Envelope\>

The first section of this DSML request contains the HTTP method line, POST /dsml HTTP/1.1, followed by a number of HTTP headers. The HTTP method line specifies the HTTP method request and URL to be used by the DSML front end. POST is the only HTTP method request accepted by the DSML front end. The /dsml URL is the default URL for Directory Server, but can be configured with any other valid URL. The HTTP headers that follow, specify the remaining details of the DSML request.

Example 13–2 Empty Anonymous DSML Response

HTTP/1.1 200 OK
Cache-control: no-cache
Connection: close
Date: Mon, 11 Dec 2006 13:56:49 GMT
Accept-Ranges: none
Server: Directory Server Enterprise Edition/11g Release 1 (11.1.1)
Content-Type: text/xml; charset="utf-8"
Content-Length: 500
<?xml version=’1.0’ encoding=’UTF-8’ ?\>
<soap-env:Envelope
   xmlns:xsd=’http://www.w3.org/2001/XMLSchema’
   xmlns:xsi=’http://www.w3.org/2001/XMLSchema-instance’
   xmlns:soap-env=’http://schemas.xmlsoap.org/soap/envelope/’
   \>
<soap-env:Body\>
<batchResponse
   xmlns:xsd=’http://www.w3.org/2001/XMLSchema’
   xmlns:xsi=’http://www.w3.org/2001/XMLSchema-instance’
   xmlns=’urn:oasis:names:tc:DSML:2:0:core’
   requestID=’Ping!’
   \>
</batchResponse\>
</soap-env:Body\>
</soap-env:Envelope\>

If nothing is returned, you can conclude that the front end is disabled.

Maximum limits exist for the number of clients connecting simultaneously to the directory and for the size of the DSML requests. The limit for the number of clients is specified by the dsml-max-parser-count and dsml-min-parser-count server properties and the request size limit by the server property dsml-request-max-size. See server(5dsconf).

Issuing a DSML Request to Bind as a Particular User

To issue a DSML request you can bind to the directory as a specified user or anonymously. To bind as a specified user, the request must include an HTTP authorization header containing a UID and a password that are mapped to a DN, as shown in Example 13–3.

Example 13–3 DSML Extended Operation: Bind as a Particular User

POST /dsml HTTP/1.1
content-length: 578
content-Type: text/xml; charset="utf-8"
HOST: hostname
Authorization: Basic ZWFzdGVyOmVnZw==
SOAPAction: ""
Connection: close
<?xml version=’1.0’ encoding=’UTF-8’?\>
<soap-env:Envelope
   xmlns:xsd=’http://www.w3.org/2001/XMLSchema’
   xmlns:xsi=’http://www.w3.org/2001/XMLSchema-instance’
   xmlns:soap-env=’http://schemas.xmlsoap.org/soap/envelope/’\>
   <soap-env:Body\>
     <batchRequest
        xmlns=’urn:oasis:names:tc:DSML:2:0:core’\>
        <extendedRequest\>
          <requestName\>1.3.6.1.4.1.4203.1.11.3</requestName\>
        </extendedRequest\>
     </batchRequest\>
   </soap-env:Body\>
</soap-env:Envelope\>

In this example the HTTP authorization header transports the user ID easter and the password egg, which, in clear, appears as easter:egg, and encoded in base64 as Authorization: Basic ZWFzdGVyOmVnZw==.

The <extendedRequest\> tag is used to specify an LDAP Extended Operation. The <requestName\> tag is used to specify the OID of the extended operation. In this example, the OID 1.3.6.1.4.1.4203.1.11.3 identifies the whoami extended operation.

The response to the DSML extended operation shows the DN of the user that made the bind request. In Example 13–4, the whoami response, which contains the DN, is shown in the response line.

<response\>dn:uid=easter,ou=people,dc=example,dc=com</response\>
Example 13–4 Response to DSML Extended Operation

HTTP/1.1 200 OK
Cache-control: no-cache
Connection: close
Date: Fri, 15 Dec 2006 09:15:09 GMT
Accept-Ranges: none
Server: Directory Server Enterprise Edition/11g Release 1 (11.1.1)
Content-Type: text/xml; charset="utf-8"
Content-Length: 697

<?xml version=’1.0’ encoding=’UTF-8’ ?\>
<soap-env:Envelope
   xmlns:xsd=’http://www.w3.org/2001/XMLSchema’
   xmlns:xsi=’http://www.w3.org/2001/XMLSchema-instance’
   xmlns:soap-env=’http://schemas.xmlsoap.org/soap/envelope/’
   \>
<soap-env:Body\>
<batchResponse
   xmlns:xsd=’http://www.w3.org/2001/XMLSchema’
   xmlns:xsi=’http://www.w3.org/2001/XMLSchema-instance’
   xmlns=’urn:oasis:names:tc:DSML:2:0:core’
   \>
   <extendedResponse\>
      <resultCode code=’0’ descr=’success’/\>
   <responseName\>1.3.6.1.4.1.4203.1.11.3</responseName\>
   <response\>dn:uid=easter,ou=people,dc=example,dc=com</response\>
   </extendedResponse\>
</batchResponse\>
</soap-env:Body\>
</soap-env:Envelope\>

For anonymous access, no HTTP authorization header is required, although anonymous access is often subject to strict access controls, and possibly to data access restrictions. Similarly, you can issue DSML requests to perform LDAP operations by LDAP proxy.

Because DSML requests are managed on a batch basis, if you issue requests by LDAP proxy, the required DSML proxy authorization request must be the first in a given batch of requests.

A DSML Search Request

Example 13–5 shows a DSML base object search request on the root DSE entry.

Example 13–5 DSML Search Request

POST /dsml HTTP/1.1
HOST: hostname
Content-Length: 1081
Content-Type: text/xml
SOAPAction: ""
Connection: close
<?xml version=’1.0’ encoding=’UTF-8’?\>
<soap-env:Envelope
   xmlns:xsd=’http://www.w3.org/2001/XMLSchema’
   xmlns:xsi=’http://www.w3.org/2001/XMLSchema-instance’
   xmlns:soap-env=’http://schemas.xmlsoap.org/soap/envelope/’
   \>
   <soap-env:Body\>
      <batchRequest
        xmlns=’urn:oasis:names:tc:DSML:2:0:core’
        requestID=’Batch of search requests’
        \>
        <searchRequest
            dn=""
            requestID="search on Root DSE"
            scope="baseObject"
            derefAliases="neverDerefAliases"
            typesOnly="false"
            \>
            <filter\>
               <present name="objectClass"/\>
            </filter\>
            <attributes\>
               <attribute name="namingContexts"/\>
               <attribute name="supportedLDAPversion"/\>
               <attribute name="vendorName"/\>
               <attribute name="vendorVersion"/\>
               <attribute name="supportedSASLMechanisms"/\>
            </attributes\>
        </searchRequest\>
      </batchRequest\>
   </soap-env:Body\>
</soap-env:Envelope\>
Example 13–6 DSML Search Response

HTTP/1.1 200 OK
Cache-control: no-cache
Connection: close
Date: Fri, 15 Dec 2006 09:21:43 GMT
Accept-Ranges: none
Server: Directory Server Enterprise Edition/11g Release 1 (11.1.1)
Content-Type: text/xml; charset="utf-8"
Content-Length: 1287

<?xml version=’1.0’ encoding=’UTF-8’ ?\>
<soap-env:Envelope
   xmlns:xsd=’http://www.w3.org/2001/XMLSchema’
   xmlns:xsi=’http://www.w3.org/2001/XMLSchema-instance’
   xmlns:soap-env=’http://schemas.xmlsoap.org/soap/envelope/’
   \>
<soap-env:Body\>
<batchResponse
   xmlns:xsd=’http://www.w3.org/2001/XMLSchema’
   xmlns:xsi=’http://www.w3.org/2001/XMLSchema-instance’
   xmlns=’urn:oasis:names:tc:DSML:2:0:core’
   requestID=’Batch of search requests’
   \>
   <searchResponse requestID=’search on Root DSE’\>
   <searchResultEntry\>
      <attr name=’namingContexts’\>
      <value\>dc=example,dc=com</value\>
      </attr\>
      <attr name=’supportedLDAPVersion’\>
      <value\>2</value\>
      <value\>3</value\>
      </attr\>
      <attr name=’vendorName’\>
      <value\>Sun Microsystems, Inc.</value\>
      </attr\>
      <attr name=’vendorVersion’\>
      <value\>Directory Server Enterprise Edition/11g Release 1 (11.1.1)</value\>
      </attr\>
      <attr name=’supportedSASLMechanisms’\>
      <value\>EXTERNAL</value\>
      <value\>GSSAPI</value\>
      <value\>DIGEST-MD5</value\>
      </attr\>
   </searchResultEntry\>
   <searchResultDone\>
      <resultCode code=’0’ descr=’success’/\>
   </searchResultDone\>
   </searchResponse\>
</batchResponse\>
</soap-env:Body\>
</soap-env:Envelope\>

Chapter 14 Directory Server Internationalization Support

Directory Server provides support for storing, managing, and searching for entries and their associated attributes in different languages.

Data inside the internationalized directory is stored in UTF-8 format. Therefore, Directory Server supports all international characters by default. The internationalized directory can be used to specify matching rules and collation orders based on language preferences in search operations. For information about the internationalized directory, see the following sections:

About Locales

A locale identifies language-specific information about how users in a specific region, culture, or custom expect data to be presented. Locales define how data in different languages is interpreted, sorted, and collated.Directory Server supports multiple languages through the use of locales.

A locale specifies the following information.

Code page

The code page is an internal table used by an operating system to relate keyboard keys to character fonts displayed on a screen. A locale can indicate what code page an application should select for interaction with an end user.

Collation order

The collation order provides information about how the characters of a given language should be sorted. The collation order specifies the following information:

  • The sequence of the letters in the alphabet

  • How to compare letters with accents to letters without accents

  • Whether there are characters that can be ignored when comparing strings

  • The direction, left to right, right to left, or up and down, in which the language is read

Character type

The character type distinguishes alphabetic characters from numeric or other characters. It defines the mapping of uppercase letters to lowercase letters. For example, in some languages, the pipe character (|) is considered punctuation, while in other languages it is considered as alphabetic.

Monetary format

The monetary format specifies the following information: the monetary symbol used in a region, whether the symbol goes before or after its value, and how monetary units are represented.

Time and date formats

The time and date formats determine the appearance of times and dates in a region. The time format indicates whether the locale uses a 12–hour clock or 24-hour clock. The date format includes both the short date order and the long date format, and include the names of months and days of the week in each language.

Identifying Supported Locales

When you perform directory operations that require you to specify a locale, such as a search operation, you can use a language tag or a collation order object identifier, OID.

A language tag is a string that begins with the two-character lowercase language code that identifies the language, as defined in ISO standard 639. If necessary to distinguish regional differences in language, the language tag may also contain a country code, which is a two-character string, as defined in ISO standard 3166. The language code and country code are separated by a hyphen. For example, the language tag used to identify the American English locale is en-US.

An OID is a decimal number that uniquely identifies an object, such as an attribute or object class.

When you perform an international search in a directory, use either the language tag or the OID to identify the collation order you want to use. When you set up an international index, use the OIDs.

The following table lists the locales supported by Directory Server. It identifies the associated language tags and OIDs.

Table 14–1 Supported Locales

Locale 

Tag 

Collation Order OID 

Backward Compatible OID 

Afrikaans 

af 

1.3.6.1.4.1.42.2.27.9.4.1.1 

 

Amharic Ethiopia 

am 

1.3.6.1.4.1.42.2.27.9.4.2.1 

 

Arabic 

ar 

1.3.6.1.4.1.42.2.27.9.4.3.1 

2.16.840.1.113730.3.3.2.1.1 

Arabic United Arab Emirates 

ar-AE 

1.3.6.1.4.1.42.2.27.9.4.4.1 

 

Arabic Bahrain 

ar-BH 

1.3.6.1.4.1.42.2.27.9.4.5.1 

 

Arabic Algeria 

ar-DZ 

1.3.6.1.4.1.42.2.27.9.4.6.1 

 

Arabic Egypt 

ar-EG 

1.3.6.1.4.1.42.2.27.9.4.7.1 

 

Arabic India 

ar-IN 

1.3.6.1.4.1.42.2.27.9.4.8.1 

 

Arabic Iraq 

ar-IQ 

1.3.6.1.4.1.42.2.27.9.4.9.1 

 

Arabic Jordan 

ar-JO 

1.3.6.1.4.1.42.2.27.9.4.10.1 

 

Arabic Kuwait 

ar-KW 

1.3.6.1.4.1.42.2.27.9.4.11.1 

 

Arabic Lebanon 

ar-LB 

1.3.6.1.4.1.42.2.27.9.4.12.1 

 

Arabic Libya 

ar-LY 

1.3.6.1.4.1.42.2.27.9.4.13.1 

 

Arabic Morocco 

ar-MA 

1.3.6.1.4.1.42.2.27.9.4.14.1 

 

Arabic Oman 

ar-OM 

1.3.6.1.4.1.42.2.27.9.4.15.1 

 

Arabic Qatar 

ar-QA 

1.3.6.1.4.1.42.2.27.9.4.16.1 

 

Arabic Saudi Arabia 

ar-SA 

1.3.6.1.4.1.42.2.27.9.4.17.1 

 

Arabic Sudan 

ar-SD 

1.3.6.1.4.1.42.2.27.9.4.18.1 

 

Arabic Syria 

ar-SY 

1.3.6.1.4.1.42.2.27.9.4.19.1 

 

Arabic Tunisia 

ar-TN 

1.3.6.1.4.1.42.2.27.9.4.20.1 

 

Arabic Yemen 

ar-YE 

1.3.6.1.4.1.42.2.27.9.4.21.1 

 

Byelorussian 

be 

1.3.6.1.4.1.42.2.27.9.4.22.1 

2.16.840.1.113730.3.3.2.2.1 

Bulgarian 

bg 

1.3.6.1.4.1.42.2.27.9.4.23.1 

2.16.840.1.113730.3.3.2.3.1 

Bengali India 

bn 

1.3.6.1.4.1.42.2.27.9.4.24.1 

 

Catalan 

ca 

1.3.6.1.4.1.42.2.27.9.4.25.1 

2.16.840.1.113730.3.3.2.4.1 

Czech 

cs 

1.3.6.1.4.1.42.2.27.9.4.26.1 

2.16.840.1.113730.3.3.2.5.1 

Danish 

da 

1.3.6.1.4.1.42.2.27.9.4.27.1 

2.16.840.1.113730.3.3.2.6.1 

German 

de or de-DE 

1.3.6.1.4.1.42.2.27.9.4.28.1 

2.16.840.1.113730.3.3.2.7.1 

German Austria 

de-AT 

1.3.6.1.4.1.42.2.27.9.4.29.1 

2.16.840.1.113730.3.3.2.8.1 

German Belgium 

de-BE 

1.3.6.1.4.1.42.2.27.9.4.30.1 

 

German Swiss 

de-CH 

1.3.6.1.4.1.42.2.27.9.4.31.1 

2.16.840.1.113730.3.3.2.9.1 

German Luxembourg 

de-LU 

1.3.6.1.4.1.42.2.27.9.4.32.1 

 

Greek 

el 

1.3.6.1.4.1.42.2.27.9.4.33.1 

2.16.840.1.113730.3.3.2.10.1 

English (US) 

en-US 

1.3.6.1.4.1.42.2.27.9.4.34.1 

2.16.840.1.113730.3.3.2.11.1 

English Australian 

en-AU 

1.3.6.1.4.1.42.2.27.9.4.35.1 

 

English Canada 

en-CA 

1.3.6.1.4.1.42.2.27.9.4.36.1 

2.16.840.1.113730.3.3.2.12.1 

English Great Britain 

en-GB 

1.3.6.1.4.1.42.2.27.9.4.37.1 

2.16.840.1.113730.3.3.2.13.1 

English Hong Kong 

en-HK 

1.3.6.1.4.1.42.2.27.9.4.38.1 

 

English Ireland 

en-IE 

1.3.6.1.4.1.42.2.27.9.4.39.1 

2.16.840.1.113730.3.3.2.14.1 

English India 

en-IN 

1.3.6.1.4.1.42.2.27.9.4.40.1 

 

English Malta 

en-MT 

1.3.6.1.4.1.42.2.27.9.4.41.1 

 

English New Zealand 

en-NZ 

1.3.6.1.4.1.42.2.27.9.4.42.1 

 

English Philippines 

en-PH 

1.3.6.1.4.1.42.2.27.9.4.43.1 

 

English Singapore 

en-SG 

1.3.6.1.4.1.42.2.27.9.4.44.1 

 

English Virgin Island 

en-VI 

1.3.6.1.4.1.42.2.27.9.4.45.1 

 

English South Africa 

en-ZA 

1.3.6.1.4.1.42.2.27.9.4.46.1 

 

English Zimbabwe 

en-ZW 

1.3.6.1.4.1.42.2.27.9.4.47.1 

 

Esperanto 

eo 

1.3.6.1.4.1.42.2.27.9.4.48.1 

 

Spanish 

es or es-ES 

1.3.6.1.4.1.42.2.27.9.4.49.1 

2.16.840.1.113730.3.3.2.15.1 

Spanish Argentina 

es-AR 

1.3.6.1.4.1.42.2.27.9.4.50.1 

 

Spanish Bolivia 

es-BO 

1.3.6.1.4.1.42.2.27.9.4.51.1 

 

Spanish Chile 

es-CL 

1.3.6.1.4.1.42.2.27.9.4.52.1 

 

Spanish Colombia 

es-CO 

1.3.6.1.4.1.42.2.27.9.4.53.1 

 

Spanish Costa Rica 

es-CR 

1.3.6.1.4.1.42.2.27.9.4.54.1 

 

Spanish Dominican Rep. 

es-DO 

1.3.6.1.4.1.42.2.27.9.4.55.1 

 

Spanish Ecuador 

es-EC 

1.3.6.1.4.1.42.2.27.9.4.56.1 

 

Spanish Guatemala 

es-GT 

1.3.6.1.4.1.42.2.27.9.4.57.1 

 

Spanish Honduras 

es-HN 

1.3.6.1.4.1.42.2.27.9.4.58.1 

 

Spanish Mexico 

es-MX 

1.3.6.1.4.1.42.2.27.9.4.59.1 

 

Spanish Nicaragua 

es-NI 

1.3.6.1.4.1.42.2.27.9.4.60.1 

 

Spanish Panama 

es-PA 

1.3.6.1.4.1.42.2.27.9.4.61.1 

 

Spanish Peru 

es-PE 

1.3.6.1.4.1.42.2.27.9.4.62.1 

 

Spanish Puerto Rico 

es-PR 

1.3.6.1.4.1.42.2.27.9.4.63.1 

 

Spanish Paraguay 

es-PY 

1.3.6.1.4.1.42.2.27.9.4.64.1 

 

Spanish El Salvador 

es-SV 

1.3.6.1.4.1.42.2.27.9.4.65.1 

 

Spanish US 

es-US 

1.3.6.1.4.1.42.2.27.9.4.66.1 

 

Spanish Uruguay 

es-UY 

1.3.6.1.4.1.42.2.27.9.4.67.1 

 

Spanish Venezuela 

es-VE 

1.3.6.1.4.1.42.2.27.9.4.68.1 

 

Estonian 

et 

1.3.6.1.4.1.42.2.27.9.4.69.1 

2.16.840.1.113730.3.3.2.16.1 

Basque 

eu 

1.3.6.1.4.1.42.2.27.9.4.70.1 

 

Persian 

fa 

1.3.6.1.4.1.42.2.27.9.4.71.1 

 

Persian India 

fa-IN 

1.3.6.1.4.1.42.2.27.9.4.72.1 

 

Persian Iran 

fa-IR 

1.3.6.1.4.1.42.2.27.9.4.73.1 

 

Finnish 

fi 

1.3.6.1.4.1.42.2.27.9.4.74.1 

2.16.840.1.113730.3.3.2.17.1 

Faeroese 

fo 

1.3.6.1.4.1.42.2.27.9.4.75.1 

 

French 

fr or fr-FR 

1.3.6.1.4.1.42.2.27.9.4.76.1 

2.16.840.1.113730.3.3.2.18.1 

French Belgium 

fr-BE 

1.3.6.1.4.1.42.2.27.9.4.77.1 

2.16.840.1.113730.3.3.2.19.1 

French Canada 

fr-CA 

1.3.6.1.4.1.42.2.27.9.4.78.1 

2.16.840.1.113730.3.3.2.20.1 

French Swiss 

fr-CH 

1.3.6.1.4.1.42.2.27.9.4.79.1 

2.16.840.1.113730.3.3.2.21.1 

French Luxembourg 

fr-LU 

1.3.6.1.4.1.42.2.27.9.4.80.1 

 

Irish 

ga 

1.3.6.1.4.1.42.2.27.9.4.81.1 

 

Galician 

gl 

1.3.6.1.4.1.42.2.27.9.4.82.1 

 

Gujarati 

gu 

1.3.6.1.4.1.42.2.27.9.4.83.1 

 

Manx Gaelic (Isle of Man) 

gv 

1.3.6.1.4.1.42.2.27.9.4.84.1 

 

Hebrew 

he or iw 

1.3.6.1.4.1.42.2.27.9.4.85.1 

2.16.840.1.113730.3.3.2.27.1 

Hindi 

hi 

1.3.6.1.4.1.42.2.27.9.4.86.1 

 

Croatian 

hr 

1.3.6.1.4.1.42.2.27.9.4.87.1 

2.16.840.1.113730.3.3.2.22.1 

Hungarian 

hu 

1.3.6.1.4.1.42.2.27.9.4.88.1 

2.16.840.1.113730.3.3.2.23.1 

Armenian 

hy 

1.3.6.1.4.1.42.2.27.9.4.89.1 

 

Indonesian 

id 

1.3.6.1.4.1.42.2.27.9.4.90.1 

 

Icelandic 

is 

1.3.6.1.4.1.42.2.27.9.4.91.1 

2.16.840.1.113730.3.3.2.24.1 

Italian 

it 

1.3.6.1.4.1.42.2.27.9.4.92.1 

2.16.840.1.113730.3.3.2.25.1 

Italian Swiss 

it-CH 

1.3.6.1.4.1.42.2.27.9.4.93.1 

2.16.840.1.113730.3.3.2.26.1 

Japanese 

ja 

1.3.6.1.4.1.42.2.27.9.4.94.1 

2.16.840.1.113730.3.3.2.28.1 

Greenlandic 

kl 

1.3.6.1.4.1.42.2.27.9.4.95.1 

 

Kannada 

kn 

1.3.6.1.4.1.42.2.27.9.4.96.1 

 

Korean 

ko 

1.3.6.1.4.1.42.2.27.9.4.97.1 

2.16.840.1.113730.3.3.2.29.1 

Konkani 

kok 

1.3.6.1.4.1.42.2.27.9.4.98.1 

 

Cornish 

kw 

1.3.6.1.4.1.42.2.27.9.4.99.1 

 

Lithuanian 

lt 

1.3.6.1.4.1.42.2.27.9.4.100.1 

2.16.840.1.113730.3.3.2.30.1 

Latvian or Lettish 

lv 

1.3.6.1.4.1.42.2.27.9.4.101.1 

2.16.840.1.113730.3.3.2.31.1 

Macedonian 

mk 

1.3.6.1.4.1.42.2.27.9.4.102.1 

2.16.840.1.113730.3.3.2.32.1 

Marathi 

mr 

1.3.6.1.4.1.42.2.27.9.4.103.1 

 

Maltese 

mt 

1.3.6.1.4.1.42.2.27.9.4.104.1 

 

Dutch 

nl or nl-NL 

1.3.6.1.4.1.42.2.27.9.4.105.1 

2.16.840.1.113730.3.3.2.33.1 

Dutch Belgium 

nl-BE 

1.3.6.1.4.1.42.2.27.9.4.106.1 

2.16.840.1.113730.3.3.2.34.1 

Norwegian 

no or no-NO 

1.3.6.1.4.1.42.2.27.9.4.107.1 

2.16.840.1.113730.3.3.2.35.1 

Norwegian Nynorsk 

no-NO-NY 

1.3.6.1.4.1.42.2.27.9.4.108.1 

2.16.840.1.113730.3.3.2.37.1 

Norwegian Nynorsk 

nn 

1.3.6.1.4.1.42.2.27.9.4.109.1 

 

Norwegian Bokmål 

nb or no-NO-B 

1.3.6.1.4.1.42.2.27.9.4.110.1 

2.16.840.1.113730.3.3.2.36.1 

Oromo (Afan) 

om 

1.3.6.1.4.1.42.2.27.9.4.111.1 

 

Oromo Ethiopia 

om-ET 

1.3.6.1.4.1.42.2.27.9.4.112.1 

 

Oromo Kenya 

om-KE 

1.3.6.1.4.1.42.2.27.9.4.113.1 

 

Polish 

pl 

1.3.6.1.4.1.42.2.27.9.4.114.1 

2.16.840.1.113730.3.3.2.38.1 

Portuguese 

pt or pt-PT 

1.3.6.1.4.1.42.2.27.9.4.115.1 

 

Portuguese Brazil 

pt-BR 

1.3.6.1.4.1.42.2.27.9.4.116.1 

 

Romanian 

ro 

1.3.6.1.4.1.42.2.27.9.4.117.1 

2.16.840.1.113730.3.3.2.39.1 

Russian 

ru or ru-RU 

1.3.6.1.4.1.42.2.27.9.4.118.1 

2.16.840.1.113730.3.3.2.40.1 

Russian Ukraine 

ru-UA 

1.3.6.1.4.1.42.2.27.9.4.119.1 

 

Serbo-Croatian 

sh 

1.3.6.1.4.1.42.2.27.9.4.120.1 

2.16.840.1.113730.3.3.2.41.1 

Slovak 

sk 

1.3.6.1.4.1.42.2.27.9.4.121.1 

2.16.840.1.113730.3.3.2.42.1 

Slovenian 

sl 

1.3.6.1.4.1.42.2.27.9.4.122.1 

2.16.840.1.113730.3.3.2.43.1 

Somali 

so or so-SO 

1.3.6.1.4.1.42.2.27.9.4.123.1 

 

Somali Djibouti 

so-DJ 

1.3.6.1.4.1.42.2.27.9.4.124.1 

 

Somali Ethiopia 

so-ET 

1.3.6.1.4.1.42.2.27.9.4.125.1 

 

Somali Kenya 

so-KE 

1.3.6.1.4.1.42.2.27.9.4.126.1 

 

Albanian 

sq 

1.3.6.1.4.1.42.2.27.9.4.127.1 

2.16.840.1.113730.3.3.2.44.1 

Serbian 

sr 

1.3.6.1.4.1.42.2.27.9.4.128.1 

2.16.840.1.113730.3.3.2.45.1 

Swedish 

sv-SE 

1.3.6.1.4.1.42.2.27.9.4.129.1 

2.16.840.1.113730.3.3.2.46.1 

Swedish Finland 

sv-FI 

1.3.6.1.4.1.42.2.27.9.4.130.1 

 

Swahili 

sw 

1.3.6.1.4.1.42.2.27.9.4.131.1 

 

Swahili Kenya 

sw-KE 

1.3.6.1.4.1.42.2.27.9.4.132.1 

 

Swahili Tanzania 

sw-TZ 

1.3.6.1.4.1.42.2.27.9.4.133.1 

 

Tamil 

ta 

1.3.6.1.4.1.42.2.27.9.4.134.1 

 

Telugu 

te 

1.3.6.1.4.1.42.2.27.9.4.135.1 

 

Thai 

th 

1.3.6.1.4.1.42.2.27.9.4.136.1 

 

Tigrinya 

ti 

1.3.6.1.4.1.42.2.27.9.4.137.1 

 

Tigrinya Eritrea 

ti-ER 

1.3.6.1.4.1.42.2.27.9.4.138.1 

 

Tigrinya Ethiopia 

ti-ET 

1.3.6.1.4.1.42.2.27.9.4.139.1 

 

Turkish 

tr 

1.3.6.1.4.1.42.2.27.9.4.140.1 

2.16.840.1.113730.3.3.2.47.1 

Ukrainian 

uk 

1.3.6.1.4.1.42.2.27.9.4.141.1 

2.16.840.1.113730.3.3.2.48.1 

Vietnamese 

vi 

1.3.6.1.4.1.42.2.27.9.4.142.1 

 

Chinese 

zh 

1.3.6.1.4.1.42.2.27.9.4.143.1 

2.16.840.1.113730.3.3.2.49.1 

Chinese China 

zh-CN 

1.3.6.1.4.1.42.2.27.9.4.144.1 

 

Chinese Hong Kong 

zh-HK 

1.3.6.1.4.1.42.2.27.9.4.145.1 

 

Chinese Mongolia 

zh-MO 

1.3.6.1.4.1.42.2.27.9.4.146.1 

 

Chinese Singapore 

zh-SG 

1.3.6.1.4.1.42.2.27.9.4.147.1 

 

Chinese Taiwan 

zh-TW 

1.3.6.1.4.1.42.2.27.9.4.148.1 

2.16.840.1.113730.3.3.2.50.1 

Supported Language Subtypes

Language subtypes can be used by clients to indicate specific attributes in characters of a language other than the default language of a deployment. For example, German users may prefer to see addresses in German when possible. In this case, you can select German as a language subtype for the streetAddress attribute so that users can search for either the English or the German representation of the address. If you specify a language subtype for an attribute, the subtype is added to the attribute name as follows:attribute;lang-subtype.

The following listing shows an English language and German language subtype for the streetAddress attribute:

streetAddress;lang-en: 10 Schlossplatz, 76113, Karlsruhe, Germany
streetAddress;lang-de: Schloßplatz 10, 76113, Karlsruhe, Deutschland

The following table contains the list of supported language subtypes.

Table 14–2 Supported Language Subtypes

Language 

Language Tag 

Afrikaans 

af 

Albanian 

sq 

Amharic Ethiopia 

am 

Arabic 

ar 

Armenian 

hy 

Basque 

eu 

Bengali India 

bn 

Bulgarian 

bg 

Byelorussian 

be 

Catalan 

ca 

Chinese 

zh 

Cornish 

kw 

Croatian 

hr 

Czech 

cs 

Danish 

da 

Dutch 

nl 

English 

en 

Esperanto 

eo 

Estonian 

et 

Faeroese 

fo 

Finnish 

fi 

French 

fr 

Galician 

gl 

German 

de 

Greek 

el 

Greenlandic 

kl 

Gujarati 

gu 

Hebrew 

he or iw 

Hindi 

hi 

Hungarian 

hu 

Icelandic 

is 

Indonesian 

id 

Irish 

ga 

Italian 

it 

Japanese 

ja 

Kannada 

kn 

Konkani 

kok 

Korean 

ko 

Latvian or Lettish 

lv 

Lithuanian 

lt 

Macedonian 

mk 

Maltese 

mt 

Manx (Isle of Man) 

gv 

Marathi 

mr 

Norwegian 

no 

Oromo 

om 

Persian 

fa 

Polish 

pl 

Portuguese 

pt 

Romanian 

ro 

Russian 

ru 

Serbian 

sr 

Serbo-Croatian 

sh 

Slovak 

sk 

Slovenian 

sl 

Somali 

so 

Spanish 

es 

Swahili 

sw 

Swedish 

sv 

Tamil 

ta 

Telugu 

te 

Thai 

th 

Tigrinya 

ti 

Turkish 

tr 

Ukrainian 

uk 

Vietnamese 

vi