Schema used by slapd(8) may be extended to support additional syntaxes, matching rules, attribute types, and object classes. This chapter details how to add user application attribute types and object classes using the syntaxes and matching rules already supported by slapd. slapd can also be extended to support additional syntaxes, matching rules and system schema, but this requires some programming and hence is not discussed here.
There are five steps to defining new schema:
- obtain Object Identifier
- choose a name prefix
- create local schema file
- define custom attribute types (if necessary)
- define custom object classes
Each schema element is identified by a globally unique Object Identifier (OID). OIDs are also used to identify other objects. They are commonly found in protocols described by ASN.1. In particular, they are heavily used by the Simple Network Management Protocol (SNMP). As OIDs are hierarchical, your organization can obtain one OID and branch it as needed. For example, if your organization were assigned OID 1.1, you could branch the tree as follows:
Table 8.2: Example OID hierarchy
|
OID
|
Assignment
|
|
1.1
|
Organization's OID
|
|
1.1.1
|
SNMP Elements
|
|
1.1.2
|
LDAP Elements
|
|
1.1.2.1
|
AttributeTypes
|
|
1.1.2.1.1
|
x-my-Attribute
|
|
1.1.2.2
|
ObjectClasses
|
|
1.1.2.2.1
|
x-my-ObjectClass
|
You are, of course, free to design a hierarchy suitable to your organizational needs under your organization's OID. No matter what hierarchy you choose, you should maintain a registry of assignments you make. This can be a simple flat file or something more sophisticated such as the OpenLDAP OID Registry (https://www.openldap.org/faq/index.cgi?file=197).
For more information about Object Identifiers (and a listing service) see https://www.alvestrand.no/harald/objectid/.
Under no circumstances should you hijack OID namespace!
To obtain a registered OID at no cost, apply for a OID under the Internet Assigned Numbers Authority (ORG:IANA) maintained Private Enterprise arc. Any private enterprise (organization) may request a Private Enterprise Number (PEN) to be assigned under this arc. Just fill out the IANA form at https://pen.iana.org/pen/PenApplication.page and your official PEN will be sent to you usually within a few days. Your base OID will be something like 1.3.6.1.4.1.X where X is an integer.
Note: PENs obtained using this form may be used for any purpose including identifying LDAP schema elements.
Alternatively, OID name space may be available from a national authority (e.g., ANSI, BSI).
In addition to assigning a unique object identifier to each schema element, you should provide a least one textual name for each element. Names should be registered with the IANA or prefixed with "x-" to place in the "private use" name space.
The name should be both descriptive and not likely to clash with names of other schema elements. In particular, any name you choose should not clash with present or future Standard Track names (this is assured if you registered names or use names beginning with "x-").
It is noted that you can obtain your own registered name prefix so as to avoid having to register your names individually. See RFC4520 for details.
In the examples below, we have used a short prefix 'x-my-'. Such a short prefix would only be suitable for a very large, global organization. In general, we recommend something like 'x-de-Firm-' (German company) or 'x-com-Example' (elements associated with organization associated with example.com).
The objectclass and attributeTypes configuration file directives can be used to define schema rules on entries in the directory. It is customary to create a file to contain definitions of your custom schema items. We recommend you create a file local.schema in /usr/local/etc/openldap/schema/local.schema and then include this file in your slapd.conf(5) file immediately after other schema include directives.
# include schema
include /usr/local/etc/openldap/schema/core.schema
include /usr/local/etc/openldap/schema/cosine.schema
include /usr/local/etc/openldap/schema/inetorgperson.schema
# include local schema
include /usr/local/etc/openldap/schema/local.schema
The attributetype directive is used to define a new attribute type. The directive uses the same Attribute Type Description (as defined in RFC4512) used by the attributeTypes attribute found in the subschema subentry, e.g.:
attributetype <RFC4512 Attribute Type Description>
where Attribute Type Description is defined by the following ABNF:
AttributeTypeDescription = "(" whsp
numericoid whsp ; AttributeType identifier
[ "NAME" qdescrs ] ; name used in AttributeType
[ "DESC" qdstring ] ; description
[ "OBSOLETE" whsp ]
[ "SUP" woid ] ; derived from this other
; AttributeType
[ "EQUALITY" woid ; Matching Rule name
[ "ORDERING" woid ; Matching Rule name
[ "SUBSTR" woid ] ; Matching Rule name
[ "SYNTAX" whsp noidlen whsp ] ; Syntax OID
[ "SINGLE-VALUE" whsp ] ; default multi-valued
[ "COLLECTIVE" whsp ] ; default not collective
[ "NO-USER-MODIFICATION" whsp ]; default user modifiable
[ "USAGE" whsp AttributeUsage ]; default userApplications
whsp ")"
AttributeUsage =
"userApplications" /
"directoryOperation" /
"distributedOperation" / ; DSA-shared
"dSAOperation" ; DSA-specific, value depends on server
where whsp is a space (' '), numericoid is a globally unique OID in dotted-decimal form (e.g. 1.1.0), qdescrs is one or more names, woid is either the name or OID optionally followed by a length specifier (e.g {10}).
For example, the attribute types name and cn are defined in core.schema as:
attributeType ( 2.5.4.41 NAME 'name'
DESC 'name(s) associated with the object'
EQUALITY caseIgnoreMatch
SUBSTR caseIgnoreSubstringsMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{32768} )
attributeType ( 2.5.4.3 NAME ( 'cn' 'commonName' )
DESC 'common name(s) assciated with the object'
SUP name )
Notice that each defines the attribute's OID, provides a short name, and a brief description. Each name is an alias for the OID. slapd(8) returns the first listed name when returning results.
The first attribute, name, holds values of directoryString (UTF-8 encoded Unicode) syntax. The syntax is specified by OID (1.3.6.1.4.1.1466.115.121.1.15 identifies the directoryString syntax). A length recommendation of 32768 is specified. Servers should support values of this length, but may support longer values The field does NOT specify a size constraint, so is ignored on servers (such as slapd) which don't impose such size limits. In addition, the equality and substring matching uses case ignore rules. Below are tables listing commonly used syntax and matching rules (slapd(8) supports these and many more).
Table 8.3: Commonly Used Syntaxes
|
Name
|
OID
|
Description
|
|
boolean
|
1.3.6.1.4.1.1466.115.121.1.7
|
boolean value
|
|
directoryString
|
1.3.6.1.4.1.1466.115.121.1.15
|
Unicode (UTF-8) string
|
|
distinguishedName
|
1.3.6.1.4.1.1466.115.121.1.12
|
LDAP DN
|
|
integer
|
1.3.6.1.4.1.1466.115.121.1.27
|
integer
|
|
numericString
|
1.3.6.1.4.1.1466.115.121.1.36
|
numeric string
|
|
OID
|
1.3.6.1.4.1.1466.115.121.1.38
|
object identifier
|
|
octetString
|
1.3.6.1.4.1.1466.115.121.1.40
|
arbitrary octets
|
Table 8.4: Commonly Used Matching Rules
|
Name
|
Type
|
Description
|
|
booleanMatch
|
equality
|
boolean
|
|
caseIgnoreMatch
|
equality
|
case insensitive, space insensitive
|
|
caseIgnoreOrderingMatch
|
ordering
|
case insensitive, space insensitive
|
|
caseIgnoreSubstringsMatch
|
substrings
|
case insensitive, space insensitive
|
|
caseExactMatch
|
equality
|
case sensitive, space insensitive
|
|
caseExactOrderingMatch
|
ordering
|
case sensitive, space insensitive
|
|
caseExactSubstringsMatch
|
substrings
|
case sensitive, space insensitive
|
|
distinguishedNameMatch
|
equality
|
distinguished name
|
|
integerMatch
|
equality
|
integer
|
|
integerOrderingMatch
|
ordering
|
integer
|
|
numericStringMatch
|
equality
|
numerical
|
|
numericStringOrderingMatch
|
ordering
|
numerical
|
|
numericStringSubstringsMatch
|
substrings
|
numerical
|
|
octetStringMatch
|
equality
|
octet string
|
|
octetStringOrderingStringMatch
|
ordering
|
octet string
|
|
octetStringSubstringsStringMatch
|
ordering
|
octet string
|
|
objectIdentiferMatch
|
equality
|
object identifier
|
The second attribute, cn, is a subtype of name hence it inherits the syntax, matching rules, and usage of name. commonName is an alternative name.
Neither attribute is restricted to a single value. Both are meant for usage by user applications. Neither is obsolete nor collective.
The following subsections provide a couple of examples.
Many organizations maintain a single unique name for each user. Though one could use displayName (RFC2798), this attribute is really meant to be controlled by the user, not the organization. We could just copy the definition of displayName from inetorgperson.schema and replace the OID, name, and description, e.g:
attributetype ( 1.1.2.1.1 NAME 'x-my-UniqueName'
DESC 'unique name with my organization'
EQUALITY caseIgnoreMatch
SUBSTR caseIgnoreSubstringsMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
SINGLE-VALUE )
However, if we want this name to be used in name assertions, e.g. (name=*Jane*), the attribute could alternatively be defined as a subtype of name, e.g.:
attributetype ( 1.1.2.1.1 NAME 'x-my-UniqueName'
DESC 'unique name with my organization'
SUP name )
Many organizations maintain a photo of each each user. A x-my-Photo attribute type could be defined to hold a photo. Of course, one could use just use jpegPhoto (RFC2798) (or a subtype) to hold the photo. However, you can only do this if the photo is in JPEG File Interchange Format. Alternatively, an attribute type which uses the Octet String syntax can be defined, e.g.:
attributetype ( 1.1.2.1.2 NAME 'x-my-Photo'
DESC 'a photo (application defined format)'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
SINGLE-VALUE )
In this case, the syntax doesn't specify the format of the photo. It's assumed (maybe incorrectly) that all applications accessing this attribute agree on the handling of values.
If you wanted to support multiple photo formats, you could define a separate attribute type for each format, prefix the photo with some typing information, or describe the value using ASN.1 and use the ;binary transfer option.
Another alternative is for the attribute to hold a URI pointing to the photo. You can model such an attribute after labeledURI (RFC2079) or simply create a subtype, e.g.:
attributetype ( 1.1.2.1.3 NAME 'x-my-PhotoURI'
DESC 'URI and optional label referring to a photo'
SUP labeledURI )
The objectclasses directive is used to define a new object class. The directive uses the same Object Class Description (as defined in RFC4512) used by the objectClasses attribute found in the subschema subentry, e.g.:
objectclass <RFC4512 Object Class Description>
where Object Class Description is defined by the following ABNF:
ObjectClassDescription = "(" whsp
numericoid whsp ; ObjectClass identifier
[ "NAME" qdescrs ]
[ "DESC" qdstring ]
[ "OBSOLETE" whsp ]
[ "SUP" oids ] ; Superior ObjectClasses
[ ( "ABSTRACT" / "STRUCTURAL" / "AUXILIARY" ) whsp ]
; default structural
[ "MUST" oids ] ; AttributeTypes
[ "MAY" oids ] ; AttributeTypes
whsp ")"
where whsp is a space (' '), numericoid is a globally unique OID in dotted-decimal form (e.g. 1.1.0), qdescrs is one or more names, and oids is one or more names and/or OIDs.
To define an auxiliary object class which allows x-my-Photo to be added to any existing entry.
objectclass ( 1.1.2.2.1 NAME 'x-my-PhotoObject'
DESC 'mixin x-my-Photo'
AUXILIARY
MAY x-my-Photo )
If your organization would like have a private structural object class to instantiate users, you can subclass one of the existing person classes, such as inetOrgPerson (RFC2798), and add any additional attributes which you desire.
objectclass ( 1.1.2.2.2 NAME 'x-my-Person'
DESC 'my person'
SUP inetOrgPerson
MUST ( x-my-UniqueName $ givenName )
MAY x-my-Photo )
The object class inherits the required/allowed attribute types of inetOrgPerson but requires x-my-UniqueName and givenName and allows x-my-Photo.
To ease the management and use of OIDs, slapd(8) supports Object Identifier macros. The objectIdentifier directive is used to equate a macro (name) with a OID. The OID may possibly be derived from a previously defined OID macro. The slapd.conf(5) syntax is:
objectIdentifier <name> { <oid> | <name>[:<suffix>] }
The following demonstrates definition of a set of OID macros and their use in defining schema elements:
objectIdentifier myOID 1.1
objectIdentifier mySNMP myOID:1
objectIdentifier myLDAP myOID:2
objectIdentifier myAttributeType myLDAP:1
objectIdentifier myObjectClass myLDAP:2
attributetype ( myAttributeType:3 NAME 'x-my-PhotoURI'
DESC 'URI and optional label referring to a photo'
SUP labeledURI )
objectclass ( myObjectClass:1 NAME 'x-my-PhotoObject'
DESC 'mixin x-my-Photo'
AUXILIARY
MAY x-my-Photo )
