4. GDS API: Concepts and Overview

The attributes that constitute a single entry can be of various types. For example, an entry for a person may contain that person's name, address, and phone number. If the person has a second telephone number, the attribute of type telephone number may have two values, one for each telephone number.

Object entries are composed of mandatory and optional attributes. Mandatory and optional attributes are discussed in Section 4.4.3.

4.2.2. Attribute Types

"directory" All attributes in a particular entry must be of different attribute types. Each attribute type is assigned a unique object identifier value. The Directory standard assigns object identifiers for several commonly used attribute types, including surname, country name, telephone number, and presentation address. Other international standards may define additional attribute types. For example, the X.400 Message Handling standard defines mail-specific attributes like O/R address. It is expected that various national and private organizations will also define attribute types of their own. The CDS attributes (defined in the xdscds.h header file) and the Global Directory Service Package attributes (defined in the xdsgds.h header file) are examples of additional attribute definitions.

4.2.3. Object Identifiers

Objects in a network environment, such as DCE, require unique names to distinguish them from one another. To provide these names, object identifiers are allocated by an administrative organization, such as a standards body. An object identifier is a hierarchical sequence of numbers uniquely identifying an object. Associated with each object identifier is a character string to make it easier to document.

The possible values of object identifiers are defined in a tree. Part of this tree is shown in Figure 4-3. It begins with three numbered branches coming from the root: branch 0 (assigned to CCITT), branch (assigned to ISO), and branch 2 (a joint ISO-CCITT branch). Below each of these branches are other numbered branches assigned to various standards such as the Directory Service (ds(5)) and Electronic Mail Service (mhs-motis(6)) with each ending in a named object. Thus, the name of any of these objects is a series of integers describing a path down this tree to the leaf node.

The object identifier associated with the XDS Directory Service Package is defined as follows:

{iso(1) identified-organization(3) icd-ecma(12) member-company(2) dec(1011) xopen(28) dsp(0)}.

All object classes and object attributes in the Directory Service Package have these numbered branches associated with them. The classes and attributes, in turn, have their own unique numbers. These object identifiers are defined in header files included as part of the XDS and XOM API software. For example, the attribute type Common-Name is identified by the object identifier

Table 4-1 contains a sample list of object identifiers for selected attributes. The complete list is provided in Chapter 12.

Note: The object identifiers in Table 4-1 stem from the root {joint-iso-ccitt(2) ds(5) attributeType(4)}.

4.2.4. Object Entries

Entries are grouped into generic object classes based on the type of object they represent. Examples of object classes are Country, Organizational-Person, and Application-Entity. All entries contain a special attribute, the object class attribute, indicating to which object class (or classes) they belong.

Entries that model a certain object and contain information about the object in terms of attributes are called object entries. The Directory contains a second type of entry, which is a pointer to an object entry, called an alias entry. Alias entries are discussed in Section 4.3.4.

In summary (as shown previously in Figure 4-2), the DIB is made up of entries, each of which contains information about objects. Entries consist of attributes; each attribute has a type and one or more values.

Section 4.3 describes how objects are organized in the DIB, by using the Directory Information Tree (DIT). Figure 4-4 shows an example of an entry describing Organizational-Person.

4.3. X.500 Naming Concepts

Large amounts of information need to be organized in some way to make efficient retrieval possible and ensure that names are unique. Information in the DIB is organized into a hierarchical structure known as the Directory Information Tree (DIT). The structure and naming of the nodes in the DIT are specified by registration authorities for a standardized set of X.500 names and by implementors of the Directory Service (such as OSF) for implementation-specific names. The DIT hierarchy is described by a schema. Schemas are described in more detail in Section 4.4.

Although the X.500 standard does not mandate a specific schema, it does make general recommendations. For example, countries and organizations should be named close to the root of the DIT; people, applications, and devices should be named further down in the hierarchy. GDS supplies a default schema that complies with these recommendations.

4.3.1. Distinguished Names

A hierarchical path exists from the root of the DIT to any entry in the DIB. To access information stored in an entry, a name that uniquely describes that entry must be given. An RDN distinguishes an entry from other entries with the same superior node in the DIT. A sequence of RDNs, starting from the root of the tree, can identify a unique path down the tree, and thus a unique entry. This sequence of RDNs, each of which indentifies a particular entry, is the distinguished name of that entry. Each entry in the DIB can be referenced by giving its distinguished name.

Figure 4-5 shows an example of a distinguished name. The shaded boxes in the DIT represent the entries that are named in the column labeled "RDN" (Relative Distinguished Name). The schema dictates that countries are named directly below the root, followed by organizations, organization units, and people.

Every entry in the DIB has a distinguished name, not just the leaf nodes. For example, the entry for the organization, Acme Enterprises (shown in Figure 4-5) is represented by the shaded box in the Organizations subtree. Its distinguished name is the concatenation of the distinguished name of the entry above with its relative distinguished name. The entry for People, Alfred Schmidt, is represented by the shaded box in the People subtree.

4.3.2. Relative Distinguished Names and Attribute Value Assertions

Each entry has a unique Relative Distinguished Name (RDN), which distinguishes it from all other entries with a particular immediate superior in the DIT.

"assertion" An RDN consists of one or more assertions of the type and value of an attribute. A pair consisting of an attribute type and a value of that type is known as an Attribute Value Assertion (AVA). All attribute types in an RDN must be different. The attribute value of an attribute in an RDN's AVA is called the distinguished value of that attribute, as opposed to the other possible values of that attribute.

The assertion is TRUE if the entry contains an attribute of the specified type, and if one of that attribute's values matches the AVA's distinguished attribute value. An entry commonly has an RDN that consists of a single AVA. In some cases, however, more than one AVA may be required to distinguish an entry. (Multiple AVAs are discussed in Section 4.3.3.)

The entry shown in Figure 4-4 contains the RDN Common-Name = Alfred Schmidt. The attribute consists of two values: Alfred Schmidt and Al Schmidt. The AVA Common-Name = Alfred Schmidt contains the value Alfred Schmidt, which has been designated as the distinguished value in the AVA.

4.3.3. Multiple AVAs

Frequently, as shown in the previous section, an entry contains a single distinguished value; therefore, the RDN comprises a single AVA. However, under certain circumstances, additional values (and hence multiple AVAs) can be used.

Figure 4-4 shows the contents of an entry describing Organizational-Person. The RDN of an Organizational-Person entry is usually composed of a single AVA, such as the Common-Name attribute type with a distinguished value (in Figure 4-5, the AVA CN = Alfred Schmidt). Depending on the schema, the RDN of an Organizational-Person entry may contain more than one AVA. For example, the RDN in Figure 4-5 could contain the AVAs CN = Alfred Schmidt and OU = New York Sales, with Alfred Schmidt and New York Sales as distinguished values.

In summary:

• A DIT consists of a collection of distinguished names.
• Distinguished names result from a concatenation of RDNs.
• RDNs consist of an unordered collection of attribute type and value pairs (AVAs).

4.3.4. Aliases

An alternative name or alias is supported in the DIT by the use of special pointer entries called alias entries. Alias entries do not contain any other attributes beyond their distinguished attributes, the object class attribute, and the aliased object name attribute; that is, the distinguished name of the aliased object entry. Furthermore, an alias entry has no subordinate entries, making it, by definition, a leaf entry of the DIT as shown in Figure 4-6. Alias entries point to object entries and provide the basis for alternative names for the corresponding objects.

Aliases are used to do such things as provide more user-friendly names, direct the search for a particular entry, reduce the scope of a search, provide for common alternate abbreviations and spellings, or provide continuity after a name change.

Figure 4-6 demonstrates how an alias name provides continuity after a name change. The ABC company's branch office located originally in Osaka has moved to Tokyo. To make the transition easier for Directory Service users and to guarantee that a search based on the old information finds its target, an alias for O=ABC has been added to the directory beneath L=Osaka. This alias entry points to the object entry O=ABC. A search for ABC under L=Osaka in the DIT finds the entry /C=Japan/L=Tokyo/O=ABC.

Another use of alias entries is as an alternative to filtering; that is, by using assertions about particular attributes to search through the DIT. Although this approach does not require any special information to be set up in the DIT, it can be expensive to search where there is a large population of entries and attributes. An alternative approach is to set up special subtrees whose naming structures are designed for ``Yellow Pages'' type searching. Figure 4-7 shows an example of such a subtree populated by alias entries only. In reality, the entries within these subtrees can be a mixture of object and alias entries, as long as there exists only one object entry for each object stored in the directory.

An object with an entry in the DIT can have zero or more aliases. Several alias entries can point to the same object entry. An alias entry can point to an object that is not a leaf entry. Only object entries can have aliases. Thus, aliases of aliases are not permitted.

4.3.5. Name Verification

A Directory user identifies an entry by supplying an ordered set of RDNs (each of which consists of an unordered set of AVAs) that form a purported name. The purported name is mapped onto the desired entry by the process of name verification, which performs a distributed tree walk through the DIT. When a purported name is a valid name, a distinguished name exists with the same number of RDNs and matching AVAs within the RDNs.

4.4. Schemas

The structure of directory information is governed by a set of rules called a schema. Schemas specify rules for the following:

• The structure of the DIT
• The contents of entries in terms of attributes
• The syntax of attribute values and rules for comparing and matching them

4.4.1. The GDS Standard Schema

When the DCE software package is shipped to a customer, it includes a default or standard schema for GDS. This is the GDS proprietary interpretation of the X.500 schema.

Each attribute in the schema is assigned a unique object identifier and the syntax of its value. In addition, the schema specifies the mechanism by which attributes of this type are compared with one another. Each entry in the DIT belongs to an object class governed by the schema. Object class definitions can be used to derive subclasses, supporting the inheritance and refinement of the attribute types defined for the super-class.

Included with the GDS standard schema are the following tables that define the structure of the Directory.

• Structure Rule Table (SRT)
• Object Class Table (OCT)
• Attribute Table (AT)

4.4.2. The Structure Rule Table

The SRT specifies the relationship of object classes in the structure of the Directory. The SRT supplied with the GDS standard schema contains the entries shown in Table 4-2.

The SRT determines how the object classes are laid out in the DIT by assigning rule numbers to each object class. An object class's Superior Rule Number specifies the object class directly above it in the DIT.

For example, the object class Organization (abbreviated with the acronym ORG in the SRT) has a superior rule number of 2, indicating that it is located in the DIT beneath the object class Country (C), which has a rule number of Organization Unit (OU) is located beneath Organization because it has a superior rule number of 3 and so forth.

The SRT only contains structured object classes; that is, classes that form branches in the DIT. Other object classes, such as abstract and alias classes, are not included.

"naming attributes" The SRT specifies the attribute(s) used to name entries belonging to each object class. These attributes, called naming attributes, are used to define the RDN and therefore the distinguished name of directory entries.

Figure 4-8 shows the structure of the DIT as defined by the SRT of the GDS standard schema.

4.4.3. The Object Class Table

The object classes that make up the GDS standard schema are defined in the OCT. Table 4-3 contains a partial listing of the OCT (refer to the OSF DCE GDS Administration Guide and Reference for a complete listing of the OCT for the GDS standard schema). Each column in Table 4-3 contains information about an object class entry in the schema.

Note: The object identifiers in Table 4-3 stem from the root {joint-iso-ccitt(2) ds(5) objectClass(6)}.

Column 4, Superclass acronyms, provides the class from which an object class inherits its attributes. Using the information in Column 4, it is possible to derive a graphical representation of the inheritance properties of object classes in the DIT as shown in Figure 4-9.

In the figure, the object class Top is the root of the tree, with Alias and GDS-Top as the main branches. Top contains the attribute type object class, which is inherited by all the other object classes.

Do not confuse the information in the OCT with that presented in the SRT. There is no direct relationship between the relative location of branches and leaves in the DIT structure and the inheritance properties of classes with their superclasses and subclasses. For example, when a Directory Service request is made by a directory user, such as a read operation, the SRT is used by the Directory Service to indicate its position in the DIT. The Directory Service uses the information defined in the SRT for tree traversal so that the requested object can be located in the Directory. Figure 4-8 shows the object class Organization located beneath Country in the DIT.

On the other hand, the OCT defines, among other things, the attributes of an object class along with its inherited attributes from its superclass. The superclass, in turn, inherits the attributes from its superclass, and so on until the root, Top, is reached (from which all classes derive their attributes). Figure 4-9 shows the object class Organization as a subclass of GDS-Top. As such, it inherits its attributes from GDS-Top, which in turn inherits from its superclass, Top.

"Object Class Table" The OCT also contains the unique object identifier of each class in the DIT. These numbers are defined by various standards authorities and in the X.500 standards documents mentioned previously. The AT also contains the predefined object identifiers for each attribute in the Directory. These object identifiers are defined in the header files that are included as part of the GDS API. Table 4-4 shows some examples of object identifiers for directory classes as defined in the X.500 standard.

Note: The object identifiers in Table 4-4 stem from the root {joint-iso-ccitt(2) ds(5) objectClass(6)}.

Another important feature of the OCT is the distinction made between mandatory and optional attributes for each object class. This distinction is based on recommendations from X.500 standards documents. These documents (Recommendations X.520 and X.521) define selected object classes and associated attribute types by using ASN.1 notation. Most object classes have one or more mandatory attributes associated with them for use by implementors who want to comply with the X.500 standards recommendations. In addition, optional attributes are defined.

The following example provides a flavor of ASN.1 notation; it shows how the object class country is described in Recommendation X.520 (The Directory: Selected Object Classes).

country OBJECT-CLASS
     SUBCLASS of top
     MUST CONTAIN {
         countryName}
     MAY CONTAIN {
         description,
         searchGuide}
     ::= {objectClass 2}

This ASN.1 definition defines Country as a subclass of superclass Top. The class, Country, must contain the mandatory attribute countryName (or Country-Name as defined in the GDS standard schema) and can contain the optional attributes Description and Search-Guide. In addition, the DCE implementation adds two more attributes, CDS-Cell and CDS-Replica, to incorporate other aspects of the DCE environment that are implementation specific.

Country is assigned the object identifier 2.5.6.2. This number distingushes it from the other object classes defined by the standard. The Top superclass is designated as 2.5.6.0. The first three numbers, 2.5.6, identify the object class as a member of a discrete set of object classes defined by X.500. The last number in the object identifier distinguishes objects within that discrete set. Alias, a subclass of Top, is assigned the number 2.5.6.1. Country is assigned the number 2.5.6.2, and so on. GDS-Top has no object identifier because it is implementation specific and thus not identified by the standard.

4.4.4. The Attribute Table

"Attribute Table" The attributes that make up the entries in the GDS standard schema are defined in the AT. (Refer to the OSF DCE GDS Administration Guide and Reference for a complete listing of the AT.) The object identifiers are in the range from 85.4.0 through 85.4.35 as defined by the X.500 standard, 86.5.2.0 through 86.5.2.10 as defined by the X.400 standard, and there are additional object identifiers for GDS specific attributes.

Table 4-5 shows a partial listing of the AT for the GDS standard schema.

Note: The access class for every attribute listed in Table 4-5 is 0 (zero).

The columns with the headings Lower Bound and Upper Bound specify the range of the number of bytes (or octets) that the value of an attribute can contain. The schema puts constraints on the number of values that an attribute can contain in the Maximum Number of Values column.

The Syntax column describes how the data is represented and relates to ASN.1 syntax definitions for attributes. For example, a sample of ASN.1 notation for the Common-Name attribute follows:

commonName ATTRIBUTE
   WITH ATTRIBUTE-SYNTAX
       caseignoreStringSyntax
           (SIZE(1..ub-common-name))
   ::= (attributeType 3)

The Common-Name attribute is defined as case insensitive. The size of the string is from 1 to the upper bound defined by the schema for the Common-Name attribute in the Upper Bound column (in this case, bytes or octets).

Note also that the Common-Name attribute is assigned the number 3 by the standard. This corresponds to the 3 in the object identifier 85.4.3.

The other columns in the AT refer to the phonetic matching flag, security access classes, and index level.

As mentioned previously for object classes, object identifier values specified in the AT are defined as constants in the GDS header files.

4.4.5. Defining Subclasses

The ability to define subclasses is a powerful feature of the directory. Structure rules govern which object classes can be children of which others in the DIT and therefore determine possible name forms.

The directory standard defines a number of standard attribute types and object classes. For example, the attribute types Common-Name and Description, and the object classes Country and Organizational-Person are defined. Implementations of the directory standard, such as DCE, define their own schemas following rules stated in the standard with additional attribute types and object classes.

Figure 4-10 shows the relationship between schemas and the directory information model.

4.5. Abstract Syntax Notation 1

The need for Abstract Syntax Notation 1 (ASN.1) arises because different computer systems represent information in different ways. For example, one computer can use EBCDIC character representation while another can use ASCII. To transfer a file of characters from one system to another, common representation must be used during the transfer. This transfer can be one representation or the other, or some mutually agreed upon representation negotiated by the two systems. Similarly, floating-point values, integers, and other types of data can be stored internally in different ways. To exchange information, a common format must be agreed to before information can be exchanged.

The translation of EBCDIC to ASCII characters can seem like a trivial problem, but that leaves the larger issue of mapping between the many diverse representations that can exist within a network environment. To address this need, the ISO standards committee defined ASN.1 and Basic Encoding Rules (BER).

ASN.1 is based on the idea that the aspects of transferred information that are preserved are type, length, and value. Data types are collections of values distinguished for some reason, such as characters, integers, and floating-point values. Records and structure types become more complex when they combine several types into a single structure.

ASN.1 provides a way to group types into abstract syntaxes. An abstract syntax is a named group of types. The standard defines abstract syntax as the notation rules that are independent of the encoding technique used to represent them. Abstract syntax does not specify how to represent values of types, but merely defines the types that make up the group of types.

Abstract syntaxes are not enough to define how values of the data types in a specific abstract syntax are to be represented during communications. For this reason, ISO further defines a transfer syntax for each abstract syntax. A transfer syntax is a set of rules for encoding values of some specified group of types.

4.5.1. ASN.1 Types

ASN.1 is similar to a high-level programming language. Unlike other high-level languages, ASN.1 has no executable statements. It includes only language constructs required to define types and values.

ASN.1 defines a number of built-in types. Users of ASN.1 can then define their own types based on the built-in types provided by the language. The ASN.1 standard defines four categories of types that are commonly used in defining application interfaces such as XOM and XDS:

• ASN.1 Simple Types
• ASN.1 Useful Types
• ASN.1 Character String Types
• ASN.1 Type Constructors

ASN.1 simple types are Bit String, Boolean, Integer, Null, Object Identifier, Octet String, and Real. Table 4-6 shows the relationship of OM syntaxes (syntaxes defined in XOM API) to ASN.1 simple types. (Refer to Chapter 17 for the complete set of tables for the four categories of ASN.1 types.) As shown in the table, for every ASN.1 type except Real, there is an OM syntax that is functionally equivalent to it. The simple types are listed in the first column of the table; the corresponding syntaxes are listed in the second column.

^l

A future edition of XOM can define a syntax corresponding to this type.

An example will illustrate how OM syntaxes are used to define the syntax of values for various attributes. One of the simplest of the ASN.1 types is Boolean. There are only two possible values for a Boolean type: TRUE and FALSE. The DS_FROM_ENTRY OM attribute of the DS_C_ENTRY_INFO object class has a value syntax of OM_S_BOOLEAN. OM_S_BOOLEAN is the C language representation for the OM syntax that corresponds to the ASN.1 Boolean type. The value of the DS_FROM_ENTRY OM attribute indicates whether information from the directory was extracted from the specified object's entry (TRUE), or from a copy of the entry (FALSE). The actual C language definition for OM_S_BOOLEAN is made in the XOM API header file xom.h.

4.5.2. Basic Encoding Rules

It is possible to define a single transfer syntax that is powerful enough to encode values drawn from a number of abstract syntaxes. ISO defines a set of rules for encoding values of many different types for ASN.1. This set of encoding rules is called Basic Encoding Rules (BER). It is so powerful that values from any abstract syntax described by using ASN.1 can be encoded by using the transfer syntax defined by BER.

Although other transfer syntaxes could be used for representing values from ASN.1, BER is used most often.

4.6. GDS as a Distributed Service

When present in a DCE cell, GDS can serve two basic functions. First, it can provide a high-level, worldwide directory service by tying together independent DCE cells. Second, it can be used as an additional directory service to CDS for storing object names and attributes in a central place.

The GDS database contains information that can be distibuted over several GDS servers. In addition, copies of information can be stored in multiple GDS servers, and the information can also be cached locally. The unit of replication in GDS is the directory entry; whole subtrees can be also replicated.

The information belonging to the DIB is shared between several Directory Service Agents (DSAs). A DSA is a process that runs on a GDS server machine and manages the GDS database. DSAs cooperate to perform directory service operations, with each DSA knowing a fraction of the total directory information, as shown in Figure 4-11. DSAs are a combination of local database functions and a remote interface to the clients of users and other DSAs. DSAs can cooperate to execute operations. This cooperation often involves the navigation of operations through the network.

Users access the directory via Directory User Agents (DUAs). DUAs make requests of DSAs on behalf of users requesting directory service operations. The manner in which DUAs communicate with DSAs is defined by the X.500 standard. For communications between DUAs and DSAs, the Directory Access Protocol (DAP) is defined. For communications between DSAs in a distributed directory, the standard defines the Directory System Protocol (DSP).

4.6.1. The Directory Access Protocol

The directory standard defines directory functions in the Directory Access Protocol (DAP). The directory functions can be divided into three general categories: read, search, and modify.

Read operations involve the retrieval of information from specific named entries. This allows a general name-to-attributes mapping analogous to the ``White Pages'' phone directory.

Search operations involve the general browsing and relational searching of information. Search operations support human interaction with the Directory Service and is analogous to that of the ``Yellow Pages'' telephone directory.

Modify operations involve the modification of information in the directory.

4.6.2. The Directory System Protocol

The DSA can interact with other DSAs to provide services by using the DSP. DSP is a protocol defined by the directory standard to allow DSAs to communicate with one another. DSP provides two methods of distributed request resolution: referral and chaining.

4.6.3. Referral

In some cases, a DSA may not be able to provide service to a DUA because the required information is held elsewhere in the network. A DSA can simply choose to inform the DUA or the calling DSA where the information can be found. This is called referral and can occur because of the user's preference or the DSA's circumstances.

Referrals are possible because the distinguished name provided by the DUA identifies where in the DIT the requested entry is located. DSAs use their knowledge of the DIT to inform the DUA of the DSA that holds the requested information.

Figure 4-12 shows an example of a referral. DSA1 passes a referral to DSA2 back to the DUA. The DUA then makes a request to DSA2.

4.6.4. Chaining

If a request received from a DUA cannot be fulfilled by the receiving DSA, that DSA can send a referral back to the initiating DUA over DAP. Alternatively, the DSA can chain the request over DSP, asking another DSA to perform the requested function. That DSA can perform the function or can send back a referral of its own. In either case, the first DSA eventually responds to the originating DUA with either the results of the completed operation or a referral.

Chaining can go deeper than one level. To prevent lengthy searches, a user can request no chaining or specify a limit on the total elapsed time for an operation.

Figure 4-13 shows an example of chaining. The DUA makes a request of DSA1. DSA1 is unable to service the request and passes it to DSA2. DSA2 services the request, passes the result back to DSA1, and DSA1 passes the result back to the DUA.

4.6.5. The Directory User Agent Cache

The DUA Cache is a process that keeps a cache of information obtained from DSAs. One DUA cache runs on each client machine and is used by all the users on that machine. The DUA cache contains copies of recently accessed object entries and information about DSAs. The user specifies which information should be cached. It is also possible to bypass the DUA Cache to obtain information directly from a DSA. This is desirable, for example, when the user wants to make sure the information obtained is up-to-date.

The shadow update and cache update are processes that update replicated information in DSAs and DUA caches. These processes run as needed and then terminate. The shadow update process runs on the GDS server machine; the cache update process runs on GDS client machines.

When an application program makes a Directory Service call by using XDS API, the call is handed to the DUA library. The DUA first looks in the DUA cache (if requested by the user) to see if the requested information is already available on the local machine. If it is not, the DUA queries a DSA. If the DSA has the requested information, it returns the results to the DUA. If it does not, the query can proceed either by using chaining or a referral. In either case, different DSAs are queried until the information is found. It is cached (if requested by the user) in the DUA cache and the results are returned to the application program.

Figure 4-14 shows the interaction between an application program, via the XDS interface, and the GDS client and server. The GDS client and server use DAP to communicate. The GDS Servers use the DSP to communicate with one another. DAP and DSP perform functions similar to the functions that DCE RPC protocols perform in other DCE services.

4.6.5.1. Placing Entries in the Local DUA Cache

A special object OM class, DSX_C_GDS_CONTEXT, is provided in the GDS package to allow an application program to manage the placement of entries in the local DUA cache as a result of a directory request.

DSX_C_GDS_CONTEXT inherits the OM attributes of its superclasses OM_C_OBJECT and DS_C_CONTEXT. To enable caching entries, the DS_DONT_USE_COPY Om attribute of DS_C_CONTEXT must be set to a value of OM_FALSE, indicating that a directory request can access copies of directory entries maintained in other DSAs or copies cached locally.

DSX_C_GDS_CONTEXT has the following private extension OM attributes in addition to the OM attributes inherited from DS_C_CONTEXT:

• DSX_DUAFIRST
• DSX_DONT_STORE
• DSX_NORMAL_CLASS
• DSX_PRIV_CLASS
• DSX_RESIDENT_CLASS
• DSX_USEDSA
• DSX_DUA_CACHE

DSX_DUAFIRST determines where a query operation, such as a search or list, looks first for an entry. The default value is OM_FALSE, indicating that the DSA is searched first. If the entry is not found, then the DUA cache is searched.

DSX_DONT_STORE determines if information read from the DSAs by a query function also needs to be stored in the DUA cache. If this OM attribute is set to OM_TRUE, nothing is stored in the cache. If this OM attribute is set to OM_FALSE, the information read is stored in the DUA cache. The objects returned by ds_list() and ds_compare() are stored in the cache without their associated attribute information. The objects returned by ds_read() and ds_search() are stored in the cache with all their ``cachable'' attributes; these are all public attributes that do not exceed 4Kbytes in length.

The three different memory classes that the user can specify for a cached entry are DSX_NORMAL_CLASS, DSX_PRIV_CLASS, and DSX_RESIDENT_CLASS.

DSX_NORMAL_CLASS assigns the entry to the class of normal objects. If the number of entries in this class exceeds a maximum value, the entry that is not accessed for the longest period of time is removed from the DUA cache.

DSX_PRIV_CLASS assigns the entry to the class of privileged objects. Entries can be removed from the class in the same way as normal objects. However, by setting this area of memory aside to be used sparingly, the user can protect entries from deletion.

DSX_RESIDENT_CLASS assigns the entry to the class of resident objects. An entry in this class is never removed automatically. It must be explicitly removed by using an XDS ds_remove_entry() function applied directly to the cache; that is, DSX_DUA_CACHE and DSX_USEDSAOM_TRUE and OM_FALSE, respectively.

Tables 4-7 through 4-9 show the possible conditions that result when DSX_DUA_CACHE and DSX_USEDSA are set to OM_TRUE.

In the situation presented in Table 4-7, the cache is read first, then the other DSAs. The requested operation is permitted to use copies of entries.

In the situation presented in Table 4-8, the DSA is read first, then the cache. The requested operation is permitted to use copies of entries.

In the situation presented in Table 4-9, only the DSA is read. The requested operation is not permitted to use copies of entries.

Tables 4-10 through 4-12 show the possible situations when DSX_DUA_CACHE and DSX_USEDSA are not both set to OM_TRUE.

In the situation presented in Table 4-10, the DUA Cache is used exclusively.

In the situation presented in Table 4-11, the DSA is used excusively.

In the situation presented in Table 4-12, neither the DSA nor the DUA cache is used, and an error is returned.

4.6.5.2. Accessing the DUA Cache Without a GDS Server Present

An application program may need to access the local DUA cache without binding to a GDS server. This section describes the steps that should be included in the application program. Refer to the Chapters 5 and 6 for information on how to use the XDS and XOM API calls ds_initialize(), ds_version(), ds_bind(), ds_shutdown(), om_create(), and om_remove(), how to do static initialization of public objects, and how to create private objects.

The steps are as follows:

• Call ds_initialize() as normal.
• Negotiate the DSX_GDS_PKG by using ds_version(). This is necessary because a DSX_C_GDS_CONTEXT is required in order to set the DUA cache service controls.
• Supply a DSX_C_GDS_SESSION object to the ds_bind() call, which has no DS_DSA_NAME attribute and no DS_DSA_ADDRESS attribute present.

  There are two ways of achieving this:

  • Supply a public DSX_C_GDS_SESSION object (static initialization):

    OM_descriptor cache_session[] = {
        OM_OID_DESC(OM_CLASS, DSX_C_GDS_SESSION),
        OM_NULL_DESCRIPTOR
        };
    

    The other attributes of DSX_C_GDS_SESSION (DS_REQUESTOR, DSX_PASSWORD, DSX_DIR_ID, DSX_AUTH_MECHANISM and DSX_AUTH_INFO) can be included if required.

  • Supply a private DSX_C_GDS_SESSION object (using XOM API function calls):

    om_create(DSX_C_GDS_SESSION, OM_TRUE, workspace, &cache_session);
    om_remove(cache_session, DS_DSA_NAME, 0, OM_ALL_VALUES);
    om_remove(cache_session, DS_DSA_ADDRESS, 0, OM_ALL_VALUES);
    

    Note that an uninitialized session object may not be passed to ds_bind(). That means that OM_FALSE should not be used with the om_create() function call above.

• Supply a DSX_C_GDS_CONTEXT object to the XDS calls that access the DUA cache. The following service controls must be set to ensure that access is restricted to the DUA cache alone:

  DSX_DUA_CACHE = OM_TRUE
  DSX_USEDSA    = OM_FALSE
  

  (Service controls that access the DSA will result in a DS_E_BAD_CONTEXT error.)

  There are two ways of achieving this:

  • Supply a public DSX_C_GDS_CONTEXT object (static initialization)
  • Supply a private DSX_C_GDS_CONTEXT object (using XOM API function calls)

• Supply the bound DSX_C_GDS_SESSION object to the ds_unbind() call.
• Call ds_shutdown() as normal.

4.6.6. GDS Configurations

A GDS machine can be configured in two ways:

• Client Only

  A node can contain only the client side of GDS. This node can access remote DSAs and cache information in the DUA cache.

• Client/Server

  A machine can be configured with both the GDS client and server. This is the typical configuration for a machine acting as a GDS server. This configuration can be useful even if a node acts mainly as a client because the DSA can be used as a larger, more permanent cache of information contained in remote DSAs.

Note: When a client and server reside on the same machine, access to the directory is optimized. Communications between the DUA and the DSA are by means of Interprocess Communications (IPC) via shared memory.

4.6.7. GDS Security

A number of authentication mechanisms are supported by GDS. XDS applications must indicate which method is to be used. Since authentication takes place at bind time, it is appropriate to pass the selected authentication mechanism as an argument to ds_bind().

A bind operation can be performed by the application program with or without user credentials. A bind with credentials is referred to as an authenticated bind and allows an application program to require a user to specify a distinguished name password as user credentials. A bind without user credentials only permits access to public information in the directory.

A special OM object class, DSX_C_GDS_SESSION, is provided in the GDS package to accommodate user credentials and authentication mechanisms. In addition to the OM attributes inherited from its superclass DS_C_SESSION, this OM class consists of the following OM attributes:

• DSX_PASSWORD

  This attribute contains the password for the user credentials.

• DSX_DIR_ID

  This attribute contains the identifier for distinguishing between several configurations of the Directory Service within a GDS installation. DSX_DIR_ID plays no role in user credentials.

• DSX_AUTH_MECHANISM

  If this attribute is present it identifies the selected authentication mechanism. If this attribute is absent then a bind without credentials (that is, anonymous bind) is attempted.

• DSX_AUTH_INFO

  This attribute is for future use.

The GDS package also provides the following special OM classes to support access rights to specific OM attributes by Directory Service users:

• DSX_C_GDS_ACL

  This attribute describes up to five categories of rights for one or more directory users.

• DSX_C_GDS_ACL_ITEM

  This attribute specifies the user, or subtree of users, to whom an access right applies.

The five categories of rights correspond to the access rights defined for the Directory Service as described in the OSF DCE GDS Administration Guide and Reference. The categories are as follows:

• Modify Public
• Read Standard
• Modify Standard
• Read Sensitive
• Modify Sensitive

Refer to Chapter 6 for more information on binding with credentials and setting access rights for users. The sample programs in Chapter 7 provide examples of how security features are used in application programs.

4.6.8. GDS API Logging

The GDS API logging facility displays informational and error messages for XDS functions. In addition, the input and output arguments to XDS function calls can also be displayed. For each XDS object, its OM types, syntaxes, and values are displayed recursively. A number of different display formats can be selected for the XDS objects. These are selected by setting the value of the environment variable XDS_LOG as shown in Table 4-13.

Logging can be activated dynamically at runtime by setting the environment variable XDS_LOG.

The bits shown in Table 4-13 can be combined. For example, the following command sequence sets XDS_LOG to 5 (00101 in binary):

XDS_LOG=5; export XDS_LOG

In this example, the logging facility is directed to display arguments, messages, results, and errors, to convert results and errors into public objects (for display purposes only), and to display object identifiers as hexadecimal bytes; and to display OM syntaxes and OM types as symbolic constants. Normally, XDS_LOG should be set to 0. If full tracing is required, then set XDS_LOG to

4.6.8.1. Logging Format

The following general display format is used by the logging facility:

identifier-name = {
{ type, syntax, value },
{ type, syntax, value },
:
:
etc.
}; /* identifier-name */

where:

• "type"

  The integer or symbolic constant for the specified type.

• "syntax"

  The integer or symbolic constant for the specified syntax. A +L is appended to the syntax label if the OM_S_LOCAL_STRING bit is set in the OM_syntax field.

• "value"
  • An integer (if syntax is OM_S_INTEGER or OM_S_ENUMERATION).
  • OM_FALSE or OM_TRUE (if syntax is OM_S_BOOLEAN).
  • Symbolic constant, dotted-decimal notation, or hexadecimal bytes (if syntax is OM_S_OBJECT_ID_STRING).
  • Quoted-string (if syntax is any other type of string).
  • Another object (if syntax is OM_S_OBJECT).

Note: The terminating NULL descriptor is expected but not displayed.

4.6.8.2. Examples

The following examples show how a selection of XDS objects are displayed by the logging facility.

The following filter selects entries that do not have the value secret for the DS_A_USER_PASSWORD attribute. The DS_FILTER_TYPE has the value DS_NOT. It contains a single DS_C_FILTER_ITEM attribute. DS_C_FILTER_ITEM tests for equality against the DS_A_USER_PASSWORD attribute.

my_filter = {
 { OM_CLASS, OM_S_OBJECT_ID_STRING, DS_C_FILTER },
 { DS_FILTER_ITEMS, OM_S_OBJECT, 
  {
   { OM_CLASS, OM_S_OBJECT_ID_STRING, DS_C_FILTER_ITEM },
   { DS_FILTER_ITEM_TYPE, OM_S_ENUMERATION, 0 },
   { DS_ATTRIBUTE_TYPE, OM_S_OBJECT_ID_STRING, DS_A_USER_PASSWORD },
   { DS_ATTRIBUTE_VALUES, OM_S_OCTET_STRING, "secret" },
  },
 },
 { DS_FILTER_TYPE, OM_S_ENUMERATION, 3 },
}; /* my_filter */

The following example shows logging output if the interface logger encounters a NULL pointer. The NULL pointer is flagged as follows:

my_session = {
 { OM_CLASS, OM_S_OBJECT_ID_STRING, DS_C_SESSION },
 { DS_DSA_NAME, OM_S_OBJECT, ---WARNING: NULL pointer encountered--- },
}; /* my_session */

The following example shows logging output if the interface logger encounters a private object. The private object is displayed as follows:

bound_session = {
  { OM_PRIVATE_OBJECT, OM_S_OBJECT_ID_STRING, DS_C_SESSION }
}; /* bound_session */

The following example shows how a 5-part DSA distinguished name is displayed (/C=de/O=sni/OU=ap/CN=dsa/CN=dsa-m1):

dsa_name = {
 { DS_DSA_NAME, OM_S_OBJECT, 
  {
   { OM_CLASS, OM_S_OBJECT_ID_STRING, DS_C_DS_DN },
   { DS_RDNS, OM_S_OBJECT, 
    {
     { OM_CLASS, OM_S_OBJECT_ID_STRING, DS_C_DS_RDN },
     { DS_AVAS, OM_S_OBJECT, 
      {
       { OM_CLASS, OM_S_OBJECT_ID_STRING, DS_C_AVA },
       { DS_ATTRIBUTE_TYPE, OM_S_OBJECT_ID_STRING, DS_A_COUNTRY_NAME },
       { DS_ATTRIBUTE_VALUES, OM_S_PRINTABLE_STRING, "de" },
      },
     },
    },
   },
   { DS_RDNS, OM_S_OBJECT, 
    {
     { OM_CLASS, OM_S_OBJECT_ID_STRING, DS_C_DS_RDN },
     { DS_AVAS, OM_S_OBJECT, 
      {
       { OM_CLASS, OM_S_OBJECT_ID_STRING, DS_C_AVA },
       { DS_ATTRIBUTE_TYPE, OM_S_OBJECT_ID_STRING, DS_A_ORG_NAME },
       { DS_ATTRIBUTE_VALUES, OM_S_TELETEX_STRING, "sni" },
      },
     },
    },
   },
   { DS_RDNS, OM_S_OBJECT, 
    {
     { OM_CLASS, OM_S_OBJECT_ID_STRING, DS_C_DS_RDN },
     { DS_AVAS, OM_S_OBJECT, 
      {
       { OM_CLASS, OM_S_OBJECT_ID_STRING, DS_C_AVA },
       { DS_ATTRIBUTE_TYPE, OM_S_OBJECT_ID_STRING, DS_A_ORG_UNIT_NAME },
       { DS_ATTRIBUTE_VALUES, OM_S_TELETEX_STRING, "ap" },
      },
     },
    },
   },
   { DS_RDNS, OM_S_OBJECT, 
    {
     { OM_CLASS, OM_S_OBJECT_ID_STRING, DS_C_DS_RDN },
     { DS_AVAS, OM_S_OBJECT, 
      {
       { OM_CLASS, OM_S_OBJECT_ID_STRING, DS_C_AVA },
       { DS_ATTRIBUTE_TYPE, OM_S_OBJECT_ID_STRING, DS_A_COMMON_NAME },
       { DS_ATTRIBUTE_VALUES, OM_S_TELETEX_STRING, "dsa" },
      },
     },
    },
   },
   { DS_RDNS, OM_S_OBJECT, 
    {
     { OM_CLASS, OM_S_OBJECT_ID_STRING, DS_C_DS_RDN },
     { DS_AVAS, OM_S_OBJECT, 
      {
       { OM_CLASS, OM_S_OBJECT_ID_STRING, DS_C_AVA },
       { DS_ATTRIBUTE_TYPE, OM_S_OBJECT_ID_STRING, DS_A_COMMON_NAME },
       { DS_ATTRIBUTE_VALUES, OM_S_TELETEX_STRING, "dsa-m1" },
      },
     },
    },
   },
  },
 },
}; /* dsa_name */