DCE 1.1: Directory Services - CDS Protocol Encodings

DCE 1.1: Directory Services
Copyright © 1997 The Open Group

CDS Protocol Encodings

This chapter specifies the encodings for both the CDS transaction protocol and the solicitation protocol. The messages transmitted between clerks and servers, and inter-server messages are specified as remote operations defined in RPC IDL (Interface Definition Language).

The transaction and solicitation protocols are defined in the RPC IDL files cds_clerkserver.idl and cds_solicit.idl respectively. The CDS protocol encodings are defined in the RPC IDL file cds_types.idl and the include file dns_records.h. The IDL definitions can be found in CDS IDL Definitions . The operations that are specified in IDL Notation of CDS Operations map to the definitions in this IDL specification. The ordering of the operation declarations in the IDL specification is relevant for determining the associated procedure numbers. For more information on the IDL notation refer to the DCE Remote Procedure Call specification.

The cds_types.idl file defines CDS-related data structures for use as argument types in the CDS RPC interfaces, so marshalling and unmarshalling issues take precedence and this is the only place they are used.

The dns_record.h file defines CDS-related data structures as they are represented on the local machine, so space and alignment issues take precedence. These are the usual data structures you will see throughout the CDS code.

This chapter specifies the relevant data types and constants for these IDL interface definitions. Unless noted otherwise, messages are encoded in DCE Transfer Syntax (NDR).

Architected Limits

There are two syntaxes for naming service names: the external ASCII name and the internal opaque name. The external name is the syntax used for the human-readable form of a name. The internal name is the syntax of the name as passed across the client interface with the naming service. The external name is designed for readability while the internal name is designed to be convenient to encode in programs, protocols, and databases.

The maximum lengths of internal, or opaque, names are specified as follows:

#define SIMPLENAMEMAX   255  /* Single component name max size */
#define FULLNAMEMAX     402  /* Internal fully-qualified  */
                             /* global name max size as represented
                             /* in an array of single component names */
#define ATTRIBNAMEMAX   31   /* Attribute name max size */
                             /* Same size limitation applies to */
                             /* class names */

The maximum length of external names is 1023 characters including the null terminator.

Encoding of Names

Opaque Names

Opaque names can be either simple or full. A simple opaque name is a single relative distinguished name (RDN). A full opaque name represents a complete list of RDNs relative to the global root.

The SimpleName_t structure defines an internal, opaque encoding of names of various kinds (entry, attribute, class) to be passed through the CDS protocol. This structure is defined in dns_record.h as follows:

typedef unsigned char byte_t;
typedef unsigned char byte_u[sizeof(byte_t)];
typedef unsigned char bytes_u;

typedef struct {
        byte_u          sn_flag;
        byte_u          sn_length;
        bytes_u         sn_name[SIMPLENAMEMAX];
} SimpleName_t;

The structure fields have the following definitions:

sn_flag

This type represents a single name component, and contains one of the following values:

 

SN_null             0
SN_typed            6
SN_objectid         7
SN_cds              8
SN_cdswildcard      9

The values 1, 2, 3, 4 and 5 are reserved.

SN_null

Signifies an empty atomic name.

Note that empty components of external atomic names are not allowed, but this value may be used for protocol internal purposes.

SN_typed

Signifies an atomic name representing a typed name (that is, an X.500 relative distinguished name (RDN)).

SN_objectid

Signifies an attribute name.

SN_cds

Signifies an atomic name representing an entity in the cell name space that does not contain wildcard metacharacters.

SN_cdswildcard

Signifies an atomic name representing an entity in the cell name space that contains at least one non-escaped (that is, with no preceding \ (backslash)) wildcard metacharacter (that is, * (asterisk) or ? (question mark)).

sn_length

Contains the length of the string contained in sn_name. If the value in sn_flag is SN_null (null opaque name), sn_length is zero.

sn_name

Contains the string representation of the opaque name in question (with no terminating NULL). If the string represents an atomic name (that is, consists of one / (slash) separated name component), its syntax and canonical form are as specified in Name Syntax .

If the value of sn_flag is SN_null (null opaque name), this field contains a null string.

The encoding of sn_name uses ISO 8859-1 code page (Latin-1) in ASCII.

The FullName_t structure defines an internal, opaque encoding of a complete global name to be passed through the CDS protocol. This structure is defined in dns_record.h as follows:

typedef uuid_t       ObjUID_t;
typedef bytes_u      ObjUID_u[sizeof(uuid_t)];

typedef struct {
   ObjUID_u   fn_root;
   word_u     fn_length;
   bytes_u    fn_name[FULLNAMEMAX - (sizeof(word_u) + sizeof(ObjUID_u))];
} FullName_t;

The structure fields have the following definitions:

fn_root: Contains the UUID of the parent node of the composite name stored in fn_name. If an invalid name was processed (that is, there is no name in fn_name), then this field contains a NIL UUID.
fn_length: Contains the total number of bytes in structures currently stored in fn_name.
fn_name: Contains an array of SimpleName_t structures forming a complete global name.

Single Name Components

The structure representing the internal format of single name components is defined as follows (this structure is also used to contain attribute identifiers and class values):

typedef struct {
        unsigned short int              nm_length;
        [length_is(nm_length)] byte     nm_name[257];
        } cds_Name_t;

The structure fields have the following definitions:

nm_length: Contains the length of the string in nm_name.
nm_name: Contains an internal opaque name.

Full Names

The structure containing the string representation of the fully qualified global name is defined as follows:

typedef struct {
        uuid_t                         fn_root;
        long int                       fn_length;
        [length_is(fn_length)] char    fn_name[1023];
} cds_FullName_t;

The structure fields have the following definitions:

fn_root: Contains the UUID of the parent node (name context) of the composite name stored in fn_name. If an invalid name was processed, this field contains a NIL UUID.
fn_length: The length of the fn_name string.
fn_name: The canonical string representation of the name in question, relative to the context defined in fn_root. This is generally the global root (that is, the name includes the /... prefix). The server-to-server operations may use a UUID in fn_root that defines a CDS directory. The string does not include a terminating null. Its syntax and canonical form are specified in DCE Composite Names .

Encoding of Time

CDS Timestamps

The CDS timestamp structure is defined as follows:

typedef struct {
        byte                  ts_node[6];
        unsigned hyper int    ts_time;
        } cds_Timestamp_t;

The structure fields have the following definitions:

ts_node

The node identifier, containing an IEEE 802 address.

ts_time

The amount of time, expressed in 100 nanosecond units, elapsed since 00:00:00.00, 17 November 1858 (Smithsonian calendar).

Note that the UTC base timestamps provided by the DCE Distributed Time Service are expressed as the amount of time elapsed since 15 October 1582 (Gregorian calendar).

Timeout Structure

The timeout structure used in operations for soft link entries is defined as follows:

typedef struct  {
        byte    to_expire[16];
        byte    to_extend[16];
        } cds_Timeout_t;

typedef [ptr]cds_Timeout_t *cds_TimeoutP_t;

The structure fields have the following definitions:

to_expire: The absolute time determining the expiration of a soft link, encoded as Coordinated Universal Time (UTC), as specified in the DCE Time Services specification.
to_extend: The relative time used as extension factor, encoded as UTC.

Encoding for Operations on Attributes

Atomic Attribute Values

All data types recognised by CDS are encoded in the discriminated union cds_AtomicValue_t, which is defined as follows:

typedef union switch (ValueType_t av_valuetype) av_val
  {
  case VT_none:            ;
  case VT_long:            long int                    av_long;
  case VT_short:           short int                   av_short;
  case VT_small:           small int                   av_small;
  case VT_uuid:            uuid_t                      av_uuid;
  case VT_Timestamp:       cds_Timestamp_t             av_timestamp;
  case VT_Timeout:         cds_Timeout_t               av_timeout;
  case VT_Version:         cds_Version_t               av_version;
  case VT_char:            [ptr]cds_OpenChar_t         *av_char_p;
  case VT_ASN1:
  case VT_byte:            [ptr]cds_OpenByte_t         *av_byte_p;

/* The remaining types are for internal CDS use only */

  case VT_ReplicaPointer:  [ptr]cds_ReplicaPointer_t   *av_rp_p;
  case VT_GroupMember:     [ptr]cds_GroupMember_t      *av_gm_p;
  case VT_ParentPointer:   [ptr]cds_ParentPointer_t    *av_pp_p;
  case VT_FullName:        [ptr]cds_FullName_t         *av_fullname_p;
  case VT_CHDirectory:     [ptr]cds_CHDirectory_t      *av_cp_p;
  case VT_DACL:            [ptr]sec_acl_t              *av_acl_p;
  case VT_gdaPointer:      [ptr]cds_gdaPointer_t       *av_gda_p;
  } cds_AtomicValue_t;

The structure fields have the following definitions:

VT_none: This indicates the absence of a value.
VT_long: This signifies a signed 32-bit integer.
VT_short: This signifies a signed 16-bit integer.
VT_small: This signifies a signed 8-bit integer.
VT_uuid: This signifies a universal unique identifier (UUID).
VT_Timestamp: This signifies a CDS timestamp (unique identifier); see above for encodings.
VT_Timeout: This signifies a timeout structure; see above for encodings.
VT_Version: This signifies class and replica version; see below for encodings.
VT_char: This signifies a counted string of 8-bit ASCII or EBCDIC characters (see CDS IDL Definitions for encodings).
VT_ASN1: This signifies the same encoding as VT_byte, but representing ASN.1.
VT_byte: This signifies a counted string of untranslated octets (see CDS IDL Definitions for encodings).
VT_ReplicaPointer: This signifies a replica pointer structure; see below for encodings.
VT_GroupMember: This signifies a group member structure (see CDS IDL Definitions for encodings).
VT_ParentPointer: This signifies a parent pointer structure (see CDS IDL Definitions for encodings).
VT_FullName: This signifies a full name structure; see above for encodings.
VT_CHDirectory: This signifies a clearinghouse directory structure (see CDS IDL Definitions for encodings).
VT_DACL: This signifies an Access Control List structure (see the DCE Security Services specification for encodings).
VT_gdaPointer: This signifies a GDA pointer structure (see CDS IDL Definitions for encodings).

The specified attribute type codes are as follows:

 

AT_none         1       /* no value */
AT_single       2       /* single-valued attribute */
AT_set          3       /* set-valued attribute */

Members of Set-Valued Attributes

The structure defining a member of a set-valued attribute or the contents of a single-valued attribute is defined as follows:

typedef struct {
        unsigned small int      sm_flag;
        cds_Timestamp_t         sm_ts;
        cds_AtomicValue_t       sm_value;
        } cds_SetMember_t;

The structure fields have the following definitions:

sm_flag

The value of this flag indicates whether an attribute value is present or absent. Valid values are as follows:

 

SM_present      1
SM_absent       0

sm_ts

Contains the member creation timestamp.

sm_value

Contains the actual value of this attribute member.

Single and Set-Valued Attributes

The structure describing single- or set-valued attributes is defined as follows:

typedef struct {
        unsigned small int                      set_type;
        unsigned short int                      set_length;
        [size_is(set_length)] cds_SetMember_t   set_members[];
} cds_Set_t;

typedef [ptr]cds_Set_t *cds_SetP_t;

The structure fields have the following definitions:

set_type

This flag describes the attribute type, and has one of the following values:

 

AT_none         1       /* no value */
AT_single       2       /* single-valued attribute */
AT_set          3       /* set-valued attribute */

set_length

Contains the number of elements in the array set_members.

set_members

An array containing the attribute's contents.

Values for Read Operations

The union that contains the value of the read attribute operation is defined as follows:

typedef union switch (unsigned small returningToClerk) {
    case RA_none:          ;
    case RA_single:        [ptr] cds_SetMember_t  *value_single_p;
    case RA_set:           [ptr] cds_Set_t        *value_set_p;
    case RA_wholeSet:      [ptr] cds_WholeEntry_t *wholeEntry_p;
} cds_RA_value_t;

Values for Modify Operations

The structure containing pertinent values for modify attribute operations is defined as follows:

typedef struct {
        small int               ud_operation;
        cds_Timestamp_t         ud_timestamp;
        unsigned small int      ud_type;
        byte                    ud_attribute[33];
        cds_AtomicValue_t       ud_value;
        } cds_Update_t;

The structure fields have the following definitions:

ud_operation

A flag indicating whether the attribute is present or absent; its value is one of the following:

 

UD_present      1
UD_absent       2

ud_timestamp

Contains the optional modification timestamp.

ud_type

A flag describing the attribute type; its value is one of the following:

 

AT_none      1    /* used to delete an object entry */
AT_single    2
AT_set       3

ud_attribute

A string representing the attribute identifier, encoded as a SimpleName_t structure with the value of its sn_flag being SN_objectid.

The attribute identifier represents the CCITT Object Identifier (OID) of the attribute, encoded in ASN.1/BER (ISO 8825). The directory version specified in this document supports only this format.

The attribute name to identifier mapping is specified in the CDS attributes table (in Object Identifiers for CDS Attributes ).

ud_value

Contains the attribute value.

Encoding of Progress Record

The structure specifying a progress record is defined as follows:

typedef struct {
        unsigned small int      pr_flags;
        [ptr]cds_Timeout_t      *pr_timeout;
        cds_FullName_t          pr_unresolved;
        cds_FullName_t          pr_resolved;
        [ptr]cds_Set_t          *pr_replicas_p;
        } cds_Progress_t;

The structure fields have the following definitions:

pr_flags

A flag whose valid values are subsets (logical OR) of the following:

 

PR_done         0x00000001
PR_up           0x00000010
PR_linked       0x00000100
PR_hitLink      0x00001000
PR_ignoreState  0x00010000
PR_directory    0x00100000

pr_timeout

A pointer to a value specifying the minimum timeout for all soft links followed in resolving a name.

pr_unresolved

Contains the unresolved portion of the name.

pr_resolved

Contains the resolved portion of the name.

pr_replicas_p

A pointer to a field containing a set of clearinghouses.

Encoding of Replica Pointer

The internal CDS structure that describes replicas is defined as follows:

typedef struct {
        unsigned small int              rp_type;
        uuid_t                          rp_chid;
        cds_FullName_t                  rp_chname;
        unsigned long int               rp_length;
        [size_is(rp_length)] byte       rp_towers[];
        } cds_ReplicaPointer_t;

typedef [ref]cds_ReplicaPointer_t *cds_ReplicaPointerP_t;

The structure fields have the following definitions:

rp_type

A flag specifying the type of replica; it can have one of the following values:

 

RT_master       1
RT_readOnly     3
RT_gda          4

The value 2 is reserved.

This document further specifies the usage only of RT_master (the Master Replica) and RT_gda (the Global Directory Agent).

rp_chid

Contains the UUID of this replica.

rp_chname

Contains the string representation of the name of this replica.

rp_length

Contains the number of elements of the rp_towers array.

rp_towers

An array containing the set of protocol towers for this replica (see the DCE Remote Procedure Call specification for encodings).

Miscellaneous Data Types and Constants

Boolean Values

Any integral or pointer type that is used to represent Boolean values is encoded as follows:

FALSE: equal to zero
TRUE: unequal to zero.

Entry Type

The structure that specifies entry type is defined as follows:

typedef struct {
        byte_u           et_value;
        } EntryType_t;

The structure fields have the following definitions:

et_value

A flag that specifies the entry type; it has one of the following values:

 

ET_directory            1
ET_object               2
ET_childPointer         3
ET_softlink             4
ET_clearinghouse        5
ET_anyDirectName        6
ET_firstLink            7
ET_dirOrObj             8

Clearinghouse List

The structure that specifies a list of clearinghouses is defined as follows:

typedef struct {
    unsigned short                               ch_length;
    [size_is(ch_length)] cds_ReplicaPointerP_t   ch_members[];
    } cds_CH_t;

The structure fields have the following definitions:

ch_length: Contains the number of elements in the array ch_members.
ch_members: The array of replica pointers.

Clearinghouse State

The structure that determines the state of a clearinghouse is defined as follows:

typedef struct {
        byte_u  cs_value;
} CHState_t;

The structure field has the following definition:

cs_value

A flag that specifies the state, which can be one of the following:

 

CS_newCH        1
CS_on           2
CS_dyingCH      3

Version Number

The structure defining a version number is defined as follows:

typedef struct {
        unsigned small int    ver_major;
        unsigned small int    ver_minor;
        } cds_Version_t;

The structure fields have the following values:

ver_major: Contains the major version number.
ver_minor: Contains the minor version number.

Principal and Group Identities

The sec_id_t structure is the basic unit for identifying principals or groups. It is defined as follows:

typedef struct {
        uuid_t                   uuid;
        [ string,ptr ] char      *name;
        } sec_id_t;

The structure fields have the following definitions:

uuid: Contains the UUID that provides an object handle for the identity.
name: Contains the optional printstring name.

Foreign Identities

The sec_id_foreign_t structure defines an identity from a foreign realm. It is defined as follows:

typedef struct {
        sec_id_t            id;
        sec_id_t            realm;
        } sec_id_foreign_t;

The structure fields have the following definitions:

id: Contains the identifier of the foreign user or group.
realm: Contains the identifier of the foreign realm.

Error Status Returns

The structure for an error status return is defined as follows:

typedef struct {
        unsigned long int       er_status;
        [ptr] cds_FullName_t    *er_name;
        } cds_status_t;

The structure fields have the following definitions:

er_status: Contains the status number.
er_name: Contains a pointer to a full name if the status [CDS_UNKNOWN_ENTRY] is returned.

Please note that the html version of this specification may contain formatting aberrations. The definitive version is available as an electronic publication on CD-ROM from The Open Group.

Contents

Next section

Index