DirX Directory String Representation for LDAP Binds

This chapter describes LDAP-style string representations of simple and structured DirX Directory attributes, search filters and distinguished names. This string representation is used with the administration program dirxcp for LDAP binds to enter and display directory information. (See section Bind Types and Bind IDs of chapter DirX Directory Commands in the DirX Directory Administration Reference for details.)

This chapter provides:

  • A table of reserved characters for attributes

  • An overview of the elements and format of simple and structured attributes

  • An overview of elements and format of distinguished names

  • An overview of elements and format of search filters

  • A description of attribute syntax

Refer to the series of LDAP RFCs (RFC 4511 ff) for additional information about LDAP.

Reserved Characters

The following table describes reserved characters used for simple and structured attributes and distinguished names.

Character Purpose

{}

For attributes and distinguished names: Encloses the entire attribute (type and value) or distinguished name to indicate that white space is part of an attribute value. For example,
{cn=Henry Mueller} or {o=SNI AG, c=de}

;

For attributes: Separates multiple values.

\

Escapes a reserved character.
The section titled String Representations for Structured Attribute Syntaxes and RFC 2252 specifies additional reserved characters as separators, for example "'", "$" or "#", that also must be escaped if it should occur in that attribute values.

Simple and Structured Attributes

Simple attributes are in the form:

type=simple_value[;_simple_value_ …​ ]

Structured attributes are in the form:

type=structured_value[;_structured_value_ …​ ]

Each of the elements in simple and structured attributes is described in the following sections.

Attribute Types

For both simple and structured attributes, the type parameter identifies the attribute.

Internally attribute types are identified by OID (object identifiers), a unique series of integers separated by the period (.) character. For example, 2.5.4.3 is the OID for the Common-Name attribute type. You can identify attributes by OID, but to make it easier to specify attributes, the dirxcp commands allow you to identify them by LDAP names in command lines. There are no abbreviated and verbose forms as for attribute types for DAP binds.

The LDAP name(s) of an attribute are specified in the system schema. For example, the LDAP name c or countryName represents the Country attribute type, the LDAP name cn or commonName represents the Common-Name attribute type. When specifying LDAP names in dirxcp commands, LDAP names are treated case-insensitive; for example, cn, Cn, and CN are all valid ways to specify the LDAP name for the Common-Name attribute type independent of the exact value for the LDAP name specified in the system schema.

When you display attributes, dirxcp uses

  • the exact LDAP name value specified in the system schema, when the LDAP name was specified in the request.

  • the first exact LDAP name value specified in the system, when specifying options like –allattr in requests.

  • the object identifier (OID), when the object identifier was specified in the request.

See sections Attribute Table and Object Classes Table of chapter DirX Directory Default DSA Schema in the DirX Directory Administration Reference for the LDAP names of attributes and object classes of the default schema.

Simple Attribute Values

For simple attributes, the simple_value parameter is the value assigned to the attribute. simple_value can be only a simple value, not another attribute. To enter more than one simple_value, separate each with a semicolon as shown in the following examples:

{telephoneNumber=+1 964 123 456}
{2.5.4.20=+1 964 123 456}
{telephoneNumber=+1 964 123 456;+1 965 234 543}

Simple attribute values are always treated as UTF-8 strings for LDAP binds.

Structured Attribute Values

In contrast to the DAP protocol, the LDAP protocol usually handles all attribute values as UTF-8 strings. There is no common rule how to specify structured attribute values. Refer to section String Representations for Structured Attribute Syntaxes of this chapter and RFC 2252 (Attribute Syntax Definitions) for structured attribute syntaxes that are supported by the LDAP server and how they are specified. When displayed structured attribute values are not broken into subcomponents in pretty mode.

Attribute Lists for Simple and Structured Attributes

Most dirxcp operations allow you to specify more than one simple or structured attribute on the command line. To specify more than one attribute, separate each attribute type and value string with white space. The following -attribute option specifies an OCL, DSC and TN simple attributes, all separated by a space. Note that the DSC and TN attributes are enclosed in braces ({ }) because they contain white space for readability.

-attribute objectClass=organizationalUnit
           {description=Engineering Department}
           {telephoneNumber=+1 964 123 4567}

Binary Attribute Values

The LDAP v3 protocol supports the specification of attribute values in binary format, that is the ASN.1 encoding of the attribute value. To display and specify the binary attribute values on the user interface of dirxcp the Base-64 encoded representation of the attribute value is used. To specify or read attribute values in binary format the syntax is as follows:

{attribute;binary}

to read the attribute value binary

{attribute;binary=attribute_value}

to specify the attribute value binary

where attribute specifies the attribute type and attribute_value specifies the Base-64 encoding of the binary attribute value when creating or modifying this value.

When the syntax of the attribute is not OCTET STRING null bytes in the value are not allowed.

Specifying the attribute value in binary format is possible for the following dirxcp operations:

  • obj create (-attribute option)

  • obj modify (-addattr, -changeattr, -removeattr options)

  • obj compare (-attribute option)

  • obj search (-attribute option)

  • obj show (-attribute option)

Examples:

The following example displays the Street Address attribute (street) of the person cn=Digger, ou=Development, o=My-Company Base-64 encoded:

show cn=Digger,ou=Development,o=my-company -attr {street;binary} -p

The output of the sample command as follows:

1) cn=Digger,ou=Development,o=my-company
   street;binary : MjQgRG91Z2FuIFN0cmVldA==

Attribute Values in a File

For LDAPv3 binds, attribute values can also be specified in a file or written to a file. The syntax is as follows:

attribute[;binary]_FILE=filename1[;_filename2 …_]

where attribute specifies the attribute type and filename the name of the file containing the attribute value. When specifying multiple attribute values each value is saved in a separate file. filename1*;*filename2 … then specify the value files. When reading multiple attribute values .*number is appended to filename where number is *1 to n (total number of values). The first value is written to filename.

If the keyword ;binary is specified, the file contains the valid ASN.1 encoded value of the attribute.

For the X.509 attributes Authority Revocation List, CA-Certificate, Certificate Revocation List, Cross-Certificate-Pair, Delta Revocation List, and User Certificate the file always contains the valid ASN.1 encoded value of the attribute regardless of specifying the keyword ;binary.

Specifying the attribute value in a file is possible for the following dirxcp operations:

  • obj create (-attribute option)

  • obj modify (-addattr, -changeattr, -removeattr, -replaceattr options)

  • obj compare (-attribute option)

  • obj show (-attribute option)

  • obj search (-attribute option)

Examples:

  1. The following example adds two pictures to the jpegPhoto attribute. The files "/tmp/john1.jpg" and "/tmp/john2.jpg" contain the binary representation of the pictures.

    modify cn=Huber,ou=sales,o=my-company \
       -addattr {jpegPhoto_FILE=/tmp/john1.jpg;/tmp/john2.jpg}

  2. Compare the jpegPhoto attribute. The file "pict.jpg" contains the value of the jpegPhoto attribute in binary representation.

    compare cn=zapf,ou=asw,o=my-company \
        -attr jpegPhoto_FILE=pict.jpg

  3. Modify the value of the jpegPhoto attribute. The file "pict_old.jpg" contains the old value and the file "pict_new.jpg" contains the new value.

    modify cn=Mayer,ou=sales,o=my-company \
       -changeattr jpegPhoto_FILE=pict_old.jpg \
                   jpegPhoto_FILE=pict_new.jpg

  4. Create an entry. The file "cert.cer" contains the ASN.1 encoded value of the user certificate attribute.

    create cn=Huber,ou=sales,o=my-company -attr \
{objectClass=person;organizaionalPerson;strongAuthenticationUser} \
       sn=Huber {userCertificate;binary_FILE=cert.cer}

  5. Show an entry. The ASN.1 encoded value of the user certificate attribute is written to the file "huber.cer".

    show cn=Huber,ou=sales,o=my-company -attr \
      {userCertificate;binary_FILE=huber.cer}

  1. Search several objects. The result contains eight objects two of them containing multiple attribute values.

    search o=my-company -subtree -attr jpegPhoto_FILE=photo.jpg

The output is as follows:

{ou=Sales,o=my-company}
{{cn=Smith John,ou=Sales,o=my-company}}
{cn=Mayer,ou=Sales,o=my-company}
{cn=Hohner,ou=Sales,o=my-company
 {jpegPhoto_FILE=photo.jpg;photo.jpg.1;photo.jpg.2}}
{cn=Richter,ou=Sales,o=my-company}
{cn=Abele,ou=Sales,o=my-company
 {jpegPhoto_FILE=photo.jpg.3;photo.jpg.4}}
{cn=Reichel,ou=Sales,o=my-company}
{cn=hohner2,ou=Sales,o=my-company}

Distinguished Names

A distinguished name consists of a list of one or more relative distinguished names (RDNs), separated by a comma (,).The list of relative distinguished names starts with the last namepart and ends with the first namepart under the root entry.For example:

cn=schmid+ou=ap11,ou=dap11,o=my-company

Each RDN consists of one or more naming attributes in the following format:

type=value[+type=value]…​

where type is an LDAP name or an OID that corresponds to a naming attribute type and value is the string representation that corresponds to the attribute syntax assigned to the attribute type.The plus sign (+) is used to separate multiple AVAs within one RDN.For example:

  • c=de

or

  • 2.5.6.2=de

or

  • ou=dap11+l=munich

The maximum length of an ASN.1 encoded RDN is 470 bytes. The value length of the naming attribute is affected by

  • the length of the object identifier

  • the number of 2-byte UTF8 characters contained in the attribute value

  • the number of attribute value assertions (AVAs) the RDN consists of.

When the name of the root entry is specified the slash (/) must be used.

The following special characters must be escaped in distinguished names:

  • a SPACE or # character at the beginning of a string

  • a SPACE character at the end of a string

  • the characters comma (,), plus sign (+), quotation mark ("), backslash (\), lower than (<), greater than (>), or semicolon (;).

To escape these characters prefix the character by a backslash, for example O=Sue\, Grabbit and Runn. (See RFC 2253 for details.)

Search Filters

Use search filter expressions to specify a filter in a dirxcp search operation.A search filter is composed of one or more simple attributes, structured attributes, or distinguished name strings, and search filter operators.The following virtual attributes must not be used in search filters:

  • numSubordinates

  • numAllSubordinates

  • structuralObjectClass

If the listed virtual attributes are used, an Unwilling to Perform error will be returned.

Recall from section Tcl Command Language in chapter DirX Directory Commands that you must enclose the filter expression in curly brackets ({}) or quotation marks ("") if attribute values contain a space character.Specify a search filter in the following format:

([logical_operator](type matching_operator value)[(type matching_operator value) …])

where

logical_operator

is one of the following operators:

Operator Meaning

&

To “logically AND” two specified conditions

|

To “logically OR” two specified conditions

!

To “logically NEGATE” a specified condition
type

specifies an LDAP name or an object identifier.

matching_operator

is one of the following operators:

Operator Meaning

=

To specify equality

~=

To specify phonetic matching

>=

To match values that are greater than or equal to a specified value

<=

To match values that are less than or equal to a specified value
value

specifies the attribute value in LDAP syntax. * is used to specify substrings or to check for the presence of an attribute.

No SPACE character is permitted between type and matching_operator and matching_operator and value.

Search Filter Expression Example

The following sample search filter string

(&(cn~=schmid) \
(|(objectClass=organizationalPerson) \
(objectClass=residentialPerson)) \
(!(sn=ronnie)))

directs dirxcp to search for names that meet all the following criteria:

  • Have an object class attribute value of Organizational-Person or Residential-Person

  • Have a Common-Name attribute value that approximately matches schmid

  • Do not have a Surname attribute value of ronnie.

The following search filter string test for the presence of the Common-Name attribute type:

(&(c=de)(cn=*))

Certificates in Search Filters

In order to support searching for attributes with the certificate syntax, for example userCertificates and caCertificates, DirX Directory supports the following two matching rules:

  • The certificateExactMatching rule (OID 2.5.13.34)

  • The certificateMatching rule (OID 2.5.13.35)

For both of these matching rules, LDAP clients can use the extensible filter feature to express such a search filter. (See RFC 4511 the LDAP protocol for details about the extensible filter feature.)

The components of a certificate that can be used in search filters are defined in X.509 in the following CertificateAssertion ASN.1 definition:

CertificateAssertion :: SEQUENCE {
   serialNumber             [0] CertificateSerialNumber  OPTIONAL,
   issuer                   [1] Name                     OPTIONAL,
   subjectKeyIdentifier     [2] SubjectKeyIdentifier     OPTIONAL,
   authorityKeyIdentifier   [3] AuthorityKeyIdentifier   OPTIONAL,
   certificateValid         [4] Time                     OPTIONAL,
   privateKeyValid          [5] GeneralizedTime          OPTIONAL,
   subjectPublicKeyAlgID    [6] OBJECT IDENTIFIER        OPTIONAL,
   keyUsage                 [7] KeyUsage                 OPTIONAL,
   subjectAltName           [8] AltNameType              OPTIONAL,
   policy                   [9] CertPolicySet            OPTIONAL,
   pathToName              [10] Name                     OPTIONAL,
   certificateInvalid      [20] Time                     OPTIONAL,
   certificateExpired      [21] Time                     OPTIONAL,
   certificateNotYetValid  [22] Time                     OPTIONAL }

The keywords of the components, for example serialNumber, must be specified case-sensitive.

See section Attribute Table in chapter DirX Directory Default DSA Schema in the DirX Directory Administration Reference for attributes with Certificate syntax.

The certificateExactMatching Rule

This rule specifies that two certificates are equal, if their serialNumber and issuer components are equal. These two components are mandatory in the matching rule assertion.

The syntax of an LDAP search filter for this rule is as follows:

  1. (certificateAttribute:2.5.13.34:={serialNumber serial_number,issuer rdnSequence:"distinguished_name"})

or

  1. (certificateAttribute:2.5.13.34:=serial_number$distinguished_name)

The certificateAttribute must be the LDAP name of an attribute with the syntax Certificate. The serial_number must be specified as a decimal integer.

In the dirxcp command, the $ character used as separator must be escaped with a \ (backslash) character.

In order to use the attribute index for the exact certificate match there must be an INITIAL index for the certificate attribute.

Example

Format 1:

dirxcp> search o=my-company -sub
         -filt {(usercertificate:2.5.13.34:={serialNumber 30,
                 issuer rdnSequence:"cn=admin,o=pqrupmann02"})}

Format 2:

dirxcp> search o=my-company -sub
          -filt (UserCertificate:2.5.13.34:=30\$cn=admin,o=pqrupmann02)

The certificateMatching Rule

This rule specifies a set of optional certificate components in the extended LDAP search filter. DirX Directory supports the components keyUsage, issuer, certificateValid, certificateExpired and certificateNotYetValid. According to this matching rule, a certificate matches the presented filter if the certificate contains all requested values.

In order to use the attribute index for the certificate matching rule there must be a CONTAINS index for the attribute.

The following sections provide the filter syntax for each component and how they can be combined.

Searching for Certificates with a specific keyUsage:

The syntax of an LDAP search filter for this rule is as follows:

(certificateAttribute:2.5.13.35:={keyUsage {keyUsage_values}})

The certificateAttribute must be the LDAP name of an attribute with the syntax Certificate. A SPACE character must separate multiple keyUsage_value. All specified values must be present in the key usage of a stored certificate to match the filter condition.

Valid keyUsage_values (strings defined by X.509) are:

digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly, decipherOnly

Example

In the following example the search operation will return all entries below o=my-company that userCertificate attribute must have either no keyUsage extension or must have a keyUsage extension with the values keyEncipherment and digitalSignature. (Additional values may be set in the keyUsage extension).

dirxcp> search o=my-company -sub
          -filt {(usercertificate:2.5.13.35:=
                  {keyUsage {keyEncipherment digitalSignature}})}
Searching for Certificates issued by a specific CA (issuer):

The syntax of an LDAP search filter for this rule is as follows:

(certificateAttribute:2.5.13.35:={issuer {dn}})

The certificateAttribute must be the LDAP name of an attribute with the syntax Certificate. The dn is the distinguished name of the issuer in LDAP format. (See Distinguished Names above.)

Example

Usually the issuer component of a user certificate contains the distinguished name of the issuing CA. In the following example the search operation will return all entries below o=my-company that userCertificate was issued by the CA with the distinguished name cn=trustedCA,o=CA,c=de:

dirxcp> search o=my-company -sub
          -filt {(usercertificate:2.5.13.35:=
                  {issuer {cn=trustedCA,o=CA,c=de}})}
Searching for Certificates that are valid (certificateValid):

The syntax of an LDAP search filter for certificates that are valid for a specific time or time-period is as follows:

(certificateAttribute:2.5.13.35:={certificateValid {time}})

The certificateAttribute must be the LDAP name of an attribute with the syntax Certificate. Specify time in one of the following formats:

  • An absolute Zulu timestamp in GeneralizedTime format, for example 20130703000000Z. Specifying milliseconds is prohibited.

  • An offset to the current time in the format

    now{+|-}integer{d|m|y}

    where now represents the current time, + represents the time-period after the current time, - represents the time-period before the current time, the integer the number of days, months or years, and d represents days, m months and y years; for example now+3m means a time-period of three month after the current time.

Examples

In the following example the search operation will return all entries below o=my-company that userCertificate is valid on 3 July 2013:

dirxcp> search o=my-company -sub
          -filt {(usercertificate:2.5.13.35:=
                  { certificateValid {20130703000000Z}})}

In the following example the search operation will return all entries below o=my-company that userCertificate is valid for three months from now on:

dirxcp> search o=my-company -sub
          -filt {(usercertificate:2.5.13.35:=
                  {certificateValid {now+3m}})}
Searching for Certificates that expires at a specific time (certificateExpired):

The syntax of an LDAP search filter for certificates that expires at a specific time is as follows:

(certificateAttribute:2.5.13.35:={certificateExpired {time}})

The certificateAttribute must be the LDAP name of an attribute with the syntax Certificate. See Searching for Certificates that are valid (certificateValid): above about specifying time.

A NOT filter for certificateValid and a filter for certificateExpired may return different search results, for example

{ (! (usercertificate:2.5.13.35:={ certificateValid { now }}))}

and

{ (usercertificate:2.5.13.35:={ certificateExpired { now }})}

return different results for an entry that contains one expired and one valid certificate. The first filter will not return a result list containing this entry but the result list for the second filter will contain the entry.
Example

In the following example the search operation will return all entries below o=my-company that userCertificate will expire in one month from now on:

dirxcp> search o=my-company -sub
          -filt {(usercertificate:2.5.13.35:=
                  {certificateExpired {now+1m}})}
Searching for Certificates that are not yet valid (certificateNotYetValid):

The syntax of an LDAP search filter for certificates that are not yet valid for a specific time is as follows:

(certificateAttribute:2.5.13.35:={certificateNotYetValid {time}})

The certificateAttribute must be the LDAP name of an attribute with the syntax Certificate. See Searching for Certificates that are valid (certificateValid): above about specifying time.

Example

In the following example the search operation will return all entries below o=my-company that userCertificate is not valid before 1 January 2015:

dirxcp> search o=my-company -sub
          -filt {(usercertificate:2.5.13.35:=
                  {certificateNotYetValid {20150101000000Z}})}
Searching for Certificates with a combined extended LDAP filter:

When combining components in a single extended LDAP filter a comma (,) separates multiple components. All components are combined with the logically AND. The syntax is as follows:

(certificateAttribute:2.5.13.35:={component_keyword_1 {component_value_1},
        component_keyword_2 {component_value_2},
        …,
        component_keyword_n {component_value_n}})

The certificateAttribute must be the LDAP name of an attribute with the syntax Certificate. component_keyword is one of the supported components keywords keyUsage, issuer, certificateValid, certificateExpired or certificateNotYetValid and component_value the value of this component.

Example

In the following example the search operation will return all entries below o=my-company that userCertificate is expired and has either no keyUsage extension or that keyUsage extension has the values keyCertSign and cRLSign:

dirxcp> search o=my-company -sub
          -filt {(usercertificate:2.5.13.35:=
                  {certificateExpired {now},
                   keyUsage {keyCertSign cRLSign}})}

LDAP Matched Value Only Filter Control

Use the LDAP Matched Value Only Filter Control in search operation to further narrow the values returned in the search result. If an attribute holds many values - for example, the userCertificate attribute or an attribute containing hundreds of options - it may be desirable for the user to be able to selectively retrieve a subset of the values, specifically, those attribute values that match some user-defined selection criteria. Without using this control, a client must read all of the attribute’s values and filter out the unwanted values, requiring the client to implement the matching rules. (The use of this control impacts performance, since the DSA normalizes and decodes each value of the selected multivalued attributes to be able to perform the value filtering.)

The filter string within this control is only used to narrow the attribute values to be returned by a search operation in a search result. The original search filter is first executed, producing an intermediate search result to which the filter in the control value is then applied. The control affects only those attribute types in the final result of the search, which appear in both the intermediate result from the original search filter and the filter string in the control value.

A search operation that carries the LDAP Matched Value Only Filter Control will do the following:

  1. The Search Filter is first executed to determine which entries satisfy the search criteria. This step generates the filter result, which contains only the requested attributes with all attribute values.

  2. For each attribute value of each entry contained in the filter result (prepared in step 1), the filter in the control value is evaluated:

    • If the attribute type of the filter result is not contained in the filter in the control value, the control has no effect: the attribute with all its values will be present in the final search result entry.

    • If the attribute type is contained in the filter in the control value, each value of this attribute type is checked against the filter in the control value. If the filter in the control value evaluates to FALSE, the given value will be removed from the final search result entry.

The value of this control is a filter string as described in the section Search Filters above with some further restrictions:

  • If the values for more than one attribute type should be filtered, these different attribute types must be put in an outermost OR filter.

  • Otherwise, complex filter (AND, OR, NOT) can only contain the same attribute type.

  • Extensible filter value matching is only supported for certificateExactMatching and certificateMatching rules with the same syntax and restrictions, as described in the section Certificates in Search Filters.

Therefore, the following filter strings are invalid examples in the control value:

(&(mail=*hotmail.com)(telephoneNumber=1234*))
(!(|(mail=*hotmail.com)(telephoneNumber=1234*)))

and will be rejected by the server.

The following valid sample filter string in the control value

(|(mail=*hotmail.com)(mail=*gmail.com)(telephoneNumber=5*))

directs the server to filter further the values in the search result:

  • All attribute values of attribute types other than mail or telephoneNumber will remain present on the output (same number of values, as without this control.)

  • From the mail attribute, only the values ending with hotmail.com or gmail.com will be present on the output. (If no such matching value is found, also the attribute type will not be present on the output.)

  • From the telephoneNumber attribute, only the values starting with 5 will be present on the output. (If no such matching value is found, also the attribute type will not be present on the output.)

The following sample filter string in the control value

(usercertificate:2.5.13.35:={issuer {cn=trustedCA,o=CA,c=de}})

directs the server to filter the userCertificate values, and return only those certificates that were issued by {cn=trustedCA,o=CA,c=de}.

Some attribute types are not supported in the filter in the control value; for example, attributes that are calculated at runtime, like numSubordinates.

The attributes occurring in the filter must have one of the following syntaxes:

  • DirectoryString (including T61, Printable, BMP, Universal and UTF-8 String)

  • IA5 String

  • Numeric String

  • Integer

  • Boolean

  • GeneralizedTime

  • Certificate with matching rule certificateExactMatch

  • Certificate with matching rule certificateMatch

Attribute Syntax

The attribute syntax of all attribute types is treated as UTF-8 strings for LDAP binds.

Undefined Types

To specify an attribute type that has not been assigned an LDAP name in the system schema, use the attribute type OID, for example, 1.2.325.67890.4.2.

In the output, the dirxcp program returns a string in the form:

oid=attribute_value

For example:

1.2.325.67890.4.2=xyz

which indicates that the attribute with the object identifier 1.2.325.67890.4.2 has a value of xyz.The value of the attribute type must be specified according to its attribute syntax.

String Representations for Simple Attribute Syntaxes

The following section describes the string representations for simple attribute syntaxes supported.All other simple attribute syntaxes not described in this section are treated as UTF-8 string.

Attribute Type Syntax

Specify an attribute type as an LDAP name (defined in the system schema) or the attribute type’s object identifier (OID) in dotted notation (for example, 1.2.5.6).

Bit String Syntax

Specify a bit string as a sequence of 1’s and 0’s enclosed by the character ' and the character B appended (for example, '11110100100001001101101'B).

Boolean Syntax

Specify a boolean as the string TRUE or FALSE.

Object ID Syntax

Specify an OID as an LDAP name (defined in the system schema) or a dotted notation. For example, Organizational-Person could be specified as organizationalPerson or 2.5.6.7.

Generalized Time Syntax

The syntax is the same as in DAP style. (See section Generalized Time Syntax of chapter DirX Directory String Representation for DAP Binds for details.)

IA5 String Syntax

The syntax is the same as in DAP style. (See section IA5 String Syntax of chapter DirX Directory String Representation for DAP Binds for details.)

Integer String Syntax

The syntax is the same as in DAP style. (See section Integer String Syntax of chapter DirX Directory String Representation for DAP Binds for details.)

Numeric String Syntax

The syntax is the same as in DAP style. (See section Numeric String Syntax of chapter DirX Directory String Representation for DAP Binds for details.)

Preferred Delivery Method Syntax

Preferred-delivery-method syntax is a syntax for single-valued attributes that document the order of preference for message delivery methods. Specify this syntax in the following format:

preferredDeliveryMethod=option [$ option…​]

option is one or more of the following keywords that describe the delivery methods and the order of preference:

  • any—Any method of delivery

  • mhs—Message handling system delivery

  • physical—Physical delivery

  • telex—Telex delivery

  • teletex—Teletex delivery

  • g3fax—G3 FAX delivery

  • g4fax—G4 FAX delivery

  • ia5—IA5 terminal delivery

  • videotex—Videotex delivery

  • telephone—Telephone delivery

The keywords are specified diminishing order of preference, with the most preferred method first in the list. Separate multiple keywords with the string " $ ". For example:

preferredDeliveryMethod=mhs $ teletex $ telephone

Printable String Syntax

The syntax is the same as in DAP style.(See section Printable String Syntax of chapter DirX Directory String Representation for DAP Binds for details.)

UTC Time Syntax

The syntax is the same as in DAP style.(See section UTC Time Syntax of chapter DirX Directory String Representation for DAP Binds for details.)

String Representations for Structured Attribute Syntaxes

This section describes the following structured attribute syntaxes supported by DirX Directory for LDAP binds.

  • Syntaxes for schema attribute types

    • Attribute-Type-Description

    • Object-Class-Description

  • Syntaxes for miscellaneous attribute types and subcomponents

    • Facsimile-Telephone-Number

    • Name-And-Optional-UID

    • Postal-Address

    • Teletex-Terminal-Identifier

    • Telex-Number

All attributes with a structure attribute syntax not described in this section must be specified in binary format for LDAP binds.(See section Binary Attribute Values above in this chapter for details.)

Attribute-Type-Description

An attribute syntax for schema attributes that specify attribute types. The attributeTypes (LAT) attribute is an example of such attributes in the default DSA schema.

Synopsis

attributeTypes=( attribute_identifier
    NAME [( ]'attribute_type_name' […​ )]
    [DESC 'attribute_type_description' ]
    [OBSOLETE ]
    [SUP derivation]
    [EQUALITY equality_matching_rule ]
    [ORDERING ordering_matching_rule ]
    [SUBSTR substrings_matching_rule ]
    [SYNTAX attribute_syntax[{length}]]
    [SINGLE-VALUE ]
    [COLLECTIVE ]
    [NO-USER-MODIFICATION ]
    [USAGE usage ])

Attribute Type

attributeTypes

The LDAP name or OID that corresponds to a structured attribute with the Attribute-Type-Description (ATTR_TYPE_DESCR) syntax. The LDAP Attribute-Types (LAT, attributeTypes) operational attribute, which specifies the attribute types used within the schema, has the ATTR_TYPE_DESCR attribute syntax. The LAT attribute is multivalued; each value describes one attribute type. The information held in this attribute should be complete and in accordance with the registered definition of each attribute type. The LAT attribute also provides the LDAP names of the attribute types.

Components

attribute_identifer

An object identifier (OID) that corresponds to an attribute type.

NAME 'attribute_type_name'

A string (of up to 1024 characters long) that provides the LDAP name(s) for the attribute type. The values are enclosed by single quotation marks (') and separated by a whitespace character. A list of LDAP names is enclosed by brackets (( …​ )). For LDAP names only the following characters are permitted: A to Z, a to z (case ignore), 0 to 9, and - (hyphen). LDAP names must start with a letter. A maximum of five LDAP names can be specified.

DESC 'attribute_type_description'

A UTF-8 string (of up to 1024 characters long) that describes the attribute type. The value is enclosed by single quotation marks (').

OBSOLETE

The keyword OBSOLETE indicates that the attribute type is no longer supported (but its characteristics are maintained). If an attribute type is deleted it is set to OBSOLETE, that is this attribute cannot be added to an entry or modified. (The error Unwilling to Perform is returned.) The values of obsolete attributes are returned by search and read operations. The default is that the specified attribute type is supported and the keyword OBSOLETE is omitted.

SUP derivation

Specifies the attribute type LDAP name or OID that corresponds to the attribute type of which this attribute is a subtype. This component is used only for attributes defined with a supertype.

EQUALITY equality_matching_rule

Specifies the LDAP name or OID of an equality matching rule. This is an optional component, but it should be specified for attributes defined with equality matching rules. If additionally an ordering matching rule and / or a substrings matching rule is specified then all specified matching rules must have the same case sensitivity.

ORDERING ordering_matching_rule

Specifies the LDAP name or OID of an ordering matching rule. This is an optional component, but it should be specified for attributes defined with ordering matching rules.

SUBSTR substrings_matching_rule

Specifies the LDAP name or OID of a substrings matching rule. This is an optional component, but it should be specified for attributes defined with substrings matching rules.

SYNTAX attribute_syntax [{ length }]

Specifies the OID of the attribute type syntax for use with LDAP, and an optional indication of the maximum length length of a value of this attribute.

SINGLE-VALUE

The keyword SINGLE-VALUE indicates that the attribute type is single-valued. The default is that the specified attribute type is multi-valued and the keyword SINGLE-VALUE is omitted.

COLLECTIVE

The keyword COLLECTIVE indicates that the attribute type is a collective attribute. The default is that the specified attribute type is not collective and the keyword COLLECTIVE is omitted.

NO-USER-MODIFICATION

The keyword NO-USER-MODIFICATION indicates that the attribute type is not modifiable by users. The default is that the specified attribute type is user modifiable and the keyword NO-USER-MODIFICATION is omitted.

USAGE usage

Specifies how the attribute is to be used. This value is one of the following keywords:

  • userApplications - For normal user attributes

  • directoryOperation - For operational attributes used by the DSA as part of non-distrubuted operations (for example, timestamp attributes, access control attributes)

  • distributedOperation - For operational attributes used by several DSAs as part of distributed operations (e.g., knowledge-reference attributes)

  • dSAOperation - For operational attributes that are used purely locally to this DSA

The default value is userApplications.

Description

The LDAP Attribute-Types attribute is provided to permit an LDAP server to publish the static details of the attributes that it supports within its schema. It is also used to manage the schema. Attribute type descriptions are represented with the ATTR_TYPE_DESCR attribute syntax.

The components of this syntax are separated by a whitespace character.

For each attribute type either the SUP or the SYNTAX component must be specified.

The sequence of the components must be provided as specified in the synopsis section above.

Only creation and restricted modifications are allowed for attribute types. Deleting attribute types is prohibited. To modify the values of an existing attribute type the attribute type must be deleted and then added with modified values in a single modify operation. When specifying an attribute type for the -removeattr option only the attribute_identifier component must be specified. (See the dirxcp obj modify operation in the DirX Directory Administration Reference for details.)

Only the values of the following components can be modified:

  • COLLECTIVE

  • DESCRIPTION

  • NAME

  • NO-USER-MODIFICATION

  • ORDERING - If an equality matching rule (component EQUALITY) already exists in the old attribute type description an ordering matching rule can be specified.

  • SINGLE-VALUE - This component can be omitted in the new specification. However it cannot be specified for an existing multi value attribute type.

All other already existing component values must be specified unchanged.

When creating a new attribute type that should also be used in the –filter option of search requests or as naming attribute an equalitity matching rule (component EQUALITY) must be specified.

Examples

attributeTypes=
....
( 2.5.4.20 NAME 'MYtelephoneNumber' EQUALITY telephoneNumberMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.44{32} )
....

Object-Class-Description

An attribute syntax for schema attributes that specify object classes. The objectClasses (LOC) attribute is an example of such attributes in the default DSA schema.

Synopsis

objectClasses=( object_class_identifier
    NAME 'object_class_name'
    [DESC 'object_class_description' ]
    [OBSOLETE ]
    [SUP [( ]superior_object_class[$ …​ )]]
    [kind ]
    [MUST [( ]attribute_type [$ …​ )]]
    [MAY [( ]attribute_type [$ …​ )]] )

Attribute Type

objectClasses

The LDAP name or OID that corresponds to a structured attribute with the Object-Class-Description (OBJECT_CLASS_DESCR) syntax. The LDAP Object-Classes (LOC, objectClasses) operational attribute is a multi-valued attribute of the schema used to describe which object classes are supported by the LDAP server. Each value describes one object class. The LOC attribute provides the LDAP names of the object classes.

The information specified for this attribute should be complete and in accordance with the registered definition of each object class.

Components

object_class_identifer

An OID that corresponds to an object class.

NAME 'object_class_name'

A string (of up to 1024 characters long) that corresponds to LDAP name given to the object class. Only one LDAP name is provided. It is enclosed by single quotation marks ('). For LDAP names only the following characters are permitted: A to Z, a to z (case ignore), 0 to 9, and - (hyphen). The LDAP name must start with a letter.

DESC 'object_class_description'

A UTF-8 string (of up to 1024 characters long) that describes the object class. The value is enclosed by single quotation marks (').

OBSOLETE

The keyword OBSOLETE indicates that the object class is no longer supported (but its characteristics are maintained). If an object class is deleted it is set to OBSOLETE, that is this enrties of this object class cannot be added or modified. (The error Unwilling to Perform is returned.) Entries of obsolete object classes are returned by search and read operations. The default is that the specified object class is supported and the keyword OBSOLETE is omitted.

SUP derivation

Specifies the LDAP names or OIDs that corresponds to the object classes (if any) that are the superclass for this object lass. A list of object classes is enclosed by brackets and the object classes are separated by a $ character.

kind

Specifies the kind of object-class that the object class registration specifies. The value is one of the following keywords:

  • STRUCTURAL - Represents a real-world object (for example, device, organization) that is concrete enough to have a place in the DIT

  • AUXILIARY - Descriptive of real-world objects (usually being applicable to more than one)

  • ABSTRACT - Represents an abstraction of real-world objects which does not exist in it own right

MUST attribute_types

Specifies one or more LDAP names or OIDs that correspond to attributes that are registered as mandatory for entries of this object class. A list of attributes is enclosed by brackets and the attribute types are separated by a $ character.

MAY attribute_types

Specifies one or more LDAP names or OIDs that correspond to attributes that are registered as optional for entries of this object class. A list of attributes is enclosed by brackets and the attribute types are separated by a $ character.

Description

The Object-Class-Description permits a LDAP server to publish the static details of the object-classes it supports. It is also used to manage the schema. Object class descriptions are represented with the OBJECT_CLASS_DESCR schema attribute syntax.

The components of this syntax are separated by a whitespace character.

The sequence of the components must be provided as specified in the synopsis section above.

Only creation and restricted modifications are allowed for object classes. Deleting an object class is prohibited. To modify the values of an existing object class the object class must be deleted and then added with modified values in a single operation. When specifying an object class for the –removeattr option only the object_class_identifier component must be specified. (See the dirxcp obj modify operation in the DirX Directory Administration Reference for details.)

Only the values of the following components can be modified:

  • DESCRIPTION

  • MAY - Only additional attribute types can be added. The already existing attribute types must also be specified. All these attribute type specifications must exist.

  • MUST - Attribute types can be moved to the optional attribute types (component MAY). This modification is prohibited for the object class top.

  • NAME

All other already existing component values must be specified unchanged.

Examples

objectClasses=
....
( 2.5.6.16 NAME 'MYcertificationAuthority' SUP top AUXILIARY MUST ( cACertificate $ certificateRevocationList $ authorityRevocationList ) MAY crossCertificatePair )
....

Facsimile-Telephone-Number

An attribute syntax for attributes that specify Facsimile (FAX) numbers.

Synopsis

FacsimileTelephoneNumber=phone_number
    [$fax_parameters]

Attribute Type

FacsimileTelephoneNumber

The LDAP name or OID that corresponds to a structured attribute with the Facsimile-Telephone-Number (FAX_TELEPHONE_NO) syntax. For example, facsimileTelephoneNumber is such an attribute.

Components

phone_number

The fax number in Printable string format (of up to 32 characters long).

fax_parameters

The settings for the G3 Fax parameters. Note that setting G3 parameters is hardly ever required. Specify fax_parameters in the following format:

fax_parameter[*$*fax_parameters]

where fax_parameter is one of the following identifiers:

  • twoDimensional

  • fineResolution

  • unlimitedLength

  • b4Length

  • a3Width

  • uncompressed

Description

FAX numbers are represented with the Facsimile-Telephone-Number attribute syntax. The number consists the country code and number in Printable string format. You can also set G3 non-basic parameters.

The components of this attribute syntax are separated by a $ character.

Example

facsimileTelephoneNumber={plus}49 89 12345

Name-And-Optional-UID

An attribute syntax for attributes that identify objects by a distinguished name and an optional identifier that can remove ambiguity from names that have been re-used.

Synopsis

NameAndOptionalUID=distinguished_name
    [#BIT_string]

Attribute Type

NameAndOptionalUID

The LDAP name or OID that corresponds to a structured attribute with the Name-And-Optional-UID syntax. For example, uniqueMember is such an attribute. The uniqueMember attribute can be used in objects which represent lists of names.

Components

distinguished_name

The distinguished name of the object. (See section Distinguished Name above in this chapter for details.)

Although the # character is used as separator for the components of this syntax and it may occur in a string representation of a distinguished_name, no additional special quoting is done.

BIT_string

A bit string that uniquely identifies the object. The bit string can be used when an object is removed from the Directory, and another object is subsequently given the same Directory name. The bit string must be chosen for uniqueness, such as a time-stamp (for example). (See section Bit String Syntax above in this chapter for details.)

Description

The identity of objects can be represented with the Name-And-Optional-UID attribute syntax. The attribute consists of the object distinguished name and an optional bit string that distinguishes between objects with the same distinguished name. The association between a user of the Directory and a name when the UID is present can be established by strong authentication using Version 2 (or later) certificates.

The components of this attribute syntax are separated by a # character.

Examples

uniqueMember=o=sni,c=DE#'100'B

Postal-Address

A structured attribute syntax for postal addresses.

Synopsis

PostalAddress=postal-address-string1
    [$postal-address-string2]
    [$postal-address-string3]
    [$postal-address-string4]
    [$postal-address-string5]
    [$postal-address-string6]

Attribute Type

PostalAddress

The abbreviation that corresponds to a structured attribute with the Postal-Address (POSTAL_ADDR) syntax. For example, postalAddress is such an attribute.

Components

postal-address-stringn

A UTF-8 string (of up to 30 characters long) that provides a line of a postal address.

Backslashes (\) and $ characters, if they occur in a component, are escaped by using an additional backslash, for example the string A\$ represents the value A$ in a component.

Description

Postal addresses are represented with the Postal-Address attribute syntax. The attribute consists of up to 6 address lines in UTF-8 string format. Each address line is limited to 30 characters in (in accordance with ITU-T recommendation F.401). One address line is required; the remaining 5 are optional.

The components of this attribute syntax are separated by a $ character.

Example

postalAddress=My-Company AG$Sales Dpt$Einstein-Ring 4$D-81789 Munich$Germany

Teletex-Terminal-Identifier

An attribute syntax for attributes that specify a Teletex terminal.

Synopsis

TeletexTerminalIdentifier=teletex-terminal
    [$teletex-non-basic-parameters]

Attribute Type

TeletexTerminalIdentifier

The LDAP name or OID that corresponds to a structured attribute with the Teletex-Terminal-Identifier syntax. For example, teletexTerminalIdentifier is such an attribute.

Components

teletex-terminal

A string (of up to 1024 characters long) that identifies the terminal. Specify the teletex-terminal parameter using the Printable String syntax. See Simple Attribute Syntax for a description of Printable String Syntax representation.

teletex-non-basic-parameters

A component that sets non-basic parameters for various teletex options. Specify teletex-non-basic-parameters in the following format:

[$control:control_character_sets]
[$graphic:graphic_character_sets]
[$misc:miscellaneous_capabilities]
[$page:page_formats]
[$private:private_use]

where:

control:control_character_sets

A string that defines the control character sets to use.

graphic:graphic_character_sets

A string that defines the graphic character sets to use.

misc:miscellaneous_capabilities

A string that defines miscellaneous capabilities to use.

page:page_formats

A string that defines the page formats to use.

private:private_use

A string that defines user-defined Teletex parameters.

Description

Teletex terminals and their parameters are represented by the Teletex-Terminal-Identifier attribute syntax. The information consists of a printable string that identifies the terminal and optional non-basic, advanced parameters that control terminal parameters such as character sets, page formats and other capabilities.

The components of this attribute syntax are separated by a $ character.

Examples

{teletexTerminalIdentifier=My Company AG Teletex center$page:letter}

Telex-Number

An attribute syntax for attributes that specify Telex numbers.

Synopsis

TelexNumber=telex_number
    [$country_code]
    [$answer_back]}

Attribute Type

TelexNumber

The LDAP name or OID that corresponds to a structured attribute with the Telex-Number (TELEX_NO) syntax. For example, telexNumber is such an attribute.

Components

telex_number

The telex number in Printable string format (of up to 14 characters long).

country_code

The county code in Printable string format (of up to 4 characters long).

answer_back

The short textual string (of up to 8 characters long), in Printable string format, with which the telex station responds when required to indicate its identity. (For example, when the telex station is connected to.)

Description

Telex numbers are represented with the Telex-Number attribute syntax. The number consists of the country code, Telex number, and answer-back code.

The components of this attribute syntax are separated by a $ character.

Example

{telexNumber=24344$046$GAMEX B}