API Reference

Request Handler

class ldapserver.LDAPRequestHandler(request, client_address, server)

logger = <Logger ldapserver.server (WARNING)>

Logger for request processing

For every connection the logger object is wrapped with a logging.LoggerAdapter that prefixes messages with a unique token for connection tracing.

subschema = <ldapserver.entries.SubschemaSubentry object>: SubschemaSubentry object that describes the schema. Default value uses schema.RFC4519_SCHEMA. Returned by do_search.

rootdse: Any: RootDSE object containing information about the server, such as supported extensions and SASL authentication mechanisms. Content is determined on setup based on the supports_* attributes. Returned by do_search.

bind_object: Any: Opaque bind/authorization state. Initially None and set to None on anonymous bind. Set to whatever the do_bind_* callbacks return.

do_bind_simple_anonymous()

Do LDAP BIND with simple anonymous authentication (RFC 4513 5.1.1.)

Raises:: exceptions.LDAPInvalidCredentials – if authentication failed
Returns:: Bind object on success (see bind_object)

The default implementation always returns None.

do_bind_simple_unauthenticated(dn)

Do LDAP BIND with simple unauthenticated authentication (RFC 4513 5.1.2.)

Parameters:: dn (str) – DN of the object to be authenticated as
Raises:: exceptions.LDAPInvalidCredentials – if authentication failed
Returns:: Bind object on success (see bind_object)

The default implementation always raises LDAPInvalidCredentials.

do_bind_simple_authenticated(dn, password)

Do LDAP BIND with simple name/password authentication (RFC 4513 5.1.3.)

Parameters:

dn (str) – Distinguished name of the object to be authenticated
password (bytes) – Password for object

Raises:

exceptions.LDAPInvalidCredentials – if authentication failed

Returns:

Bind object on success (see bind_object)

The default implementation always raises LDAPInvalidCredentials.

supports_sasl_anonymous = False: Indicate SASL “ANONYMOUS” support

do_bind_sasl_anonymous(trace_info=None)

Do LDAP BIND with SASL “ANONYMOUS” mechanism (RFC 4505)

Parameters:: trace_info (str, optional) – Trace information, either an email address or an opaque string that does not contain the ‘@’ character
Raises:: exceptions.LDAPError – if authentication failed
Returns:: Bind object on success
Return type:: obj

Only called if supports_sasl_anonymous is True. The default implementation raises LDAPAuthMethodNotSupported.

supports_sasl_plain = False: Indicate SASL “PLAIN” support

do_bind_sasl_plain(identity, password, authzid=None)

Do LDAP BIND with SASL “PLAIN” mechanism (RFC 4616)

Parameters:

identity (str) – Authentication identity (authcid)
password (str) – Password (passwd)
authzid (str, optional) – Authorization identity

Raises:

exceptions.LDAPError – if authentication failed

Returns:

Bind object on success

Return type:

obj

Only called if supports_sasl_plain is True. The default implementation raises LDAPAuthMethodNotSupported.

supports_sasl_external = False: Indicate SASL “EXTERNAL” support

do_bind_sasl_external(authzid=None)

Do LDAP BIND with SASL “EXTERNAL” mechanism (RFC 4422 and 4513)

Parameters:: authzid (str, optional) – Authorization identity
Raises:: exceptions.LDAPError – if authentication failed
Returns:: Bind object on success
Return type:: obj

EXTERNAL is commonly used for TLS client certificate authentication or system user based authentication on UNIX sockets.

Only called if supports_sasl_external is True. The default implementation raises LDAPAuthMethodNotSupported.

supports_paged_results = True: Enable/disable support for “Simple Paged Results Manipulation” control (RFC2696). Paginated search uses do_search like non-paginated search does.

do_search(baseobj, scope, filterobj)

Return result candidates for a SEARCH operation

Parameters:

baseobj (str) – Distinguished name of the LDAP entry relative to which the search is to be performed
scope (ldap.SearchScope) – Search scope
filterobj (ldap.Filter) – Filter object

Raises:

exceptions.LDAPError – on error

Returns:

All entries that might match the parameters of the SEARCH operation.

Return type:

Iterable of Entry

The default implementation yields rootdse and subschema. Both are important for feature detection, so make sure to also return them (e.g. with yield from super().do_search(...)).

For every returned object Entry.search is called to filter out non-matching entries and to construct the response.

Note that if this method is a generator, its execution may be paused for extended periods of time or aborted prematurely.

do_compare(dn, attribute, value)

Lookup object for COMPARE operation

Parameters:

dn (str) – Distinguished name of the LDAP entry
attribute (str) – Attribute type
value (bytes) – Attribute value

Raises:

exceptions.LDAPError – on error

Returns:

Entry or None

The default implementation calls do_search and returns the first object for which Entry.compare does not raise exceptions.LDAPNoSuchObject (i.e. the object has the requested DN).

ssl_context = None: ssl.SSLContext for StartTLS

property supports_starttls

Indicate StartTLS support

True per default if ssl_context is set and the connection is not already encrypted, False otherwise.

do_starttls()

Do StartTLS extended operation (RFC 4511)

Called by handle_extended() if supports_starttls is True. The default implementation uses ssl_context.

Note that the (success) response to the request is sent before this method is called. If a call to this method fails, the LDAP connection is immediately terminated.

supports_whoami = False

do_whoami()

Do “Who am I?” extended operation (RFC 4532)

Returns:: Current authorization identity (authzid) or empty string for anonymous sessions
Return type:: str

Called by handle_extended() if supports_whoami is True. The default implementation always returns an empty string.

supports_password_modify = False

do_password_modify(user=None, old_password=None, new_password=None)

Do password modify extended operation (RFC 3062)

Parameters:

user (str, optional) – User the request relates to, may or may not be a distinguished name. If absent, the request relates to the user currently associated with the LDAP connection
old_password (bytes, optional) – Current password of user
new_password (bytes, optional) – Desired password for user

Called by handle_extended() if supports_password_modify is True. The default implementation always raises an LDAPUnwillingToPerform error.

Distinguished Names

class ldapserver.DN(schema, *args, **kwargs)

Distinguished Name consisting of zero ore more RDN objects

schema: Any

classmethod from_str(schema, expr)

Parse string representation of a DN according to RFC 4514

Parameters:

schema (schema.Schema) – Schema for the DN
expr (str) – DN string representation

Raises:

ValueError – if expr is invalid

Returns:

Parsed DN

Return type:

DN

__str__()

Return string representation of DN according to RFC 4514

Returns:: Representation of self
Return type:: str

is_direct_child_of(base)

Return whether self is a direct child of base

Parameters:: base (DN) – parent DN
Return type:: bool

Example:

>>> schema = schema.RFC4519_SCHEMA
>>> dn1 = DN(schema, 'uid=jsmith,dc=example,dc=net')
>>> dn2 = DN(schema, 'dc=example,dc=net')
>>> dn3 = DN(schema, 'dc=net')
>>> dn1.is_direct_child_of(dn2)
True
>>> dn1.is_direct_child_of(dn1) or dn1.is_direct_child_of(dn3)
False

in_subtree_of(base)

Return whether self is in the subtree of base

Parameters:: base (DN) – parent DN
Return type:: bool

Example:

>>> schema = schema.RFC4519_SCHEMA
>>> dn1 = DN(schema, 'uid=jsmith,dc=example,dc=net')
>>> dn2 = DN(schema, 'dc=example,dc=net')
>>> dn3 = DN(schema, 'dc=net')
>>> dn1.in_subtree_of(dn1) and dn1.in_subtree_of(dn2) and dn1.in_subtree_of(dn3)
True
>>> dn2.in_subtree_of(dn1)
False

property object_attribute: Attribute name of the first RDN. None if there are no RDNs or if the first RDN consists of more than one assertion.

property object_attribute_type: schema.AttributeType of the first RDN. None if there are no RDNs or if the first RDN consists of more than one assertion.

property object_value: Attribute value of the first RDN. None if there are no RDNs or if the first RDN consists of more than one assertion. Type of value depends on the syntax of the attribute type.

class ldapserver.RDN(schema, *assertions, **kwargs)

Relative Distinguished Name consisting of one or more RDNAssertion objects

schema: Any

classmethod from_str(schema, expr)

Parse string representation of an RDN according to RFC 4514

Parameters:

schema (schema.Schema) – Schema for the RDN
expr (str) – RDN string representation

Raises:

ValueError – if expr is invalid

Returns:

Parsed RDN

Return type:

RDN

__str__()

Return string representation of RDN according to RFC 4514

Returns:: Representation of self
Return type:: str

Example:

>>> str(RDN(ou='Sales', cn='J.  Smith'))
'ou=Sales+cn=J.  Smith'

property attribute: Attribute name of the contained assertion. None if the RDN consists of more than one assertion.

property attribute_type: Attribute type of the contained assertion. None if the RDN consists of more than one assertion.

property value: Attribute value of the contained assertion. None if the RDN consists of more than one assertion. Type of value depends on the syntax of the attribute type.

class ldapserver.RDNAssertion(schema, attribute, value)

attribute: str: Attribute name

attribute_type: Any: schema.AttributeType

value: Any: Attribute value (type depends on the syntax of the attribute type)

schema: Any

classmethod from_str(schema, expr)

Parse string representation of an RDN assertion according to RFC 4514

Parameters:

schema (schema.Schema) – Schema for the RDN assertion
expr (str) – RDN assertion string representation

Raises:

ValueError – if expr is invalid

Returns:

Parsed assertion

Return type:

RDNAssertion

__str__()

Return string representation of the RDN assertion according to RFC 4514

Returns:: Representation of self
Return type:: str

class ldapserver.DNWithUID(schema, dn, uid=None)

Distinguished Name with an optional bit string

Used to represent values of the “Name and Optional UID” syntax (see RFC4517) This syntax is used for e.g. the “uniqueMember” attribute type (RFC4519).

If created without the optional bit string (uid) part, a regular DN object is returned.

schema: Any

classmethod from_str(schema, expr)

Parse string representation

Parameters:

schema (schema.Schema) – Schema
expr (str) – DN string representation with optional #-separated bit string part (e.g. 0b1010)

Raises:

ValueError – if expr is invalid

Returns:

DNWithUID if expr includes the optional bit string part, DN otherwise

Return type:

DN or DNWithUID

__str__()

Return string representation

Returns:: Representation of self
Return type:: str

property dn: Return DN part as a regular DN object

Entries

An LDAP server provides access to a tree of directory entries (the DIT). There are different kinds of entries: Object entries holding actual data objects (see ObjectEntry), alias entries providing alternative naming for other entries (not supported) and subentries holding administrative/operational information (see SubschemaSubentry and RootDSE).

class ldapserver.AttributeDict(schema, **attributes)

Special dictionary holding LDAP attribute values

Attribute values can be set and accessed by their attribute type’s numeric OID or short descriptive name. Attribute types must be defined within the schema to be used. Attribute values are always lists. Accessing an unset attribute behaves the same as accessing an empty attribute. List items must conform to the attribute’s syntax.

schema

class ldapserver.Entry(schema, dn, **attributes)

Base class for all directory entries

All entries implement the methods Entry.search and Entry.compare. LDAPRequestHandler uses them to process the corresponding LDAP requests.

Entries also provide dict-like access to attributes. See AttributeDict.

dn: Entry’s distinguished name (DN)

search(base_obj, scope, filter_obj, attributes, types_only)

Return SEARCH result for the entry if it matches the operation parameters

Parameters:

base_obj (str) – DN of the base entry
scope (ldap.SearchScope) – Scope of base_obj
filter_obj (ldap.Filter) – Search filter
attributes (list of str) – Requested attributes
types_only (bool) – Omit values in ldap.PartialAttribute

Returns:

SEARCH result for the entry if it matches the operation parameters, None otherwise

Return type:

ldap.SearchResultEntry or None

Conforms to RFC4511 and RFC4526 (empty AND/OR filters are supported and treated as absolute TRUE/FALSE).

compare(dn, attribute, value)

Return the result of the COMPARE operation applied to the entry

Parameters:

dn (str) – DN of the entry to be compared
attribute (str) – Attribute OID or short descriptive name
value (bytes) – Assertion value

Raises:

exceptions.LDAPNoSuchObject – if dn does not refer to the entry
exceptions.LDAPError – if operation results to anything other than TRUE/FALSE

Returns:

True/False if COMPARE operation evaluates to TRUE/FALSE

Return type:

bool

Evaluation is essentially applying the EQUALITY matching rule of attribute on the values of attribute with the assertion value.

class ldapserver.RootDSE(schema, **attributes)

Root DSA-specific (server-specific) Entry

Root of the Directory Information Tree (DIT). It’s always identified by the empty DN. Provides information about the server, like supported features.

class ldapserver.SubschemaSubentry(schema, dn, **attributes)

Subentry providing information on a Schema

AttributeDict: Shorthand for AttributeDict

ObjectEntry: Shorthand for ObjectEntry

RootDSE: Shorthand for RootDSE

EntryTemplate: Shorthand for EntryTemplate

DN: Shorthand for DN

RDN: Shorthand for RDN

RDNAssertion: Shorthand for RDNAssertion

ldapserver.WILDCARD: Special wildcard singleton for EntryTemplate

class ldapserver.EntryTemplate(schema, parent_dn, rdn_attribute, **attributes)

Utility class for dynamically generated object entries

Set all entry-specific attributes to the special WILDCARD value and call EntryTemplate.match_search to decide if any entries based on the template might match a SEARCH request. Call EntryTemplate.create_entry with the actual values to create entries based on a template.

match_search(base_obj, scope, filter_obj)

Return whether entries based on this template might match the search parameters

Parameters:

base_obj (str) – DN of the base entry
scope (ldap.SearchScope) – Scope of base_obj
filter_obj (ldap.Filter) – Search filter

Returns:

True if entries based on this template might match the SEARCH parameters or False if they do not match

Return type:

bool

extract_search_constraints(base_obj, scope, filter_obj)

Return approximate value constraints for entries that match SEARCH parameters

Returns:: AttributeDict with values that any entry must have to match potentially match SEARCH parameters
Return type:: AttributeDict

Example:

>>> subschema = SubschemaSubentry(schema.RFC4519_SCHEMA, 'cn=Subschema')
>>> template = subschema.EntryTemplate('ou=users,dc=example,dc=com', 'cn', objectclass=['person', 'top'], sn=WILDCARD)
>>> template.extract_search_constraints('cn=test,ou=users,dc=example,dc=com', ldap.SearchScope.baseObject, ldap.FilterEqual('sn', b'foobar'))
subschema.AttributeDict(cn=['test'], sn=['foobar'])

Note that the results are an approximation (i.e. some constrains may be missing) and the quality may improve over time. Also note that every entry that matches the SEARCH parameters also matches the constrains, but not vice versa.

create_entry(rdn_value, **attributes)

Instantiate Entry based on template

Parameters:: rdn_value (any) – RDN value for DN construction
Return type:: Entry

Template attributes set to WILDCARD are stripped. Only template attributes set to WILDCARD may be overwritten with attributes.

Schema

The schema.Schema class and the schema-bound classes like schema.Syntax provide a high-level interface to the low-level schema definition objects.

Objects of the schema-bound classes reference other objects within their schema directly. They are automatically instantiated when a schema.Schema object is created based on the passed definition objects.

class ldapserver.schema.Schema(object_class_definitions=None, attribute_type_definitions=None, matching_rule_definitions=None, syntax_definitions=None)

Consistent collection of syntaxes, matching rules, attribute types and object classes forming an LDAP schema

Parameters:

object_class_definitions – List of ObjectClassDefinition or str
attribute_type_definitions – List of AttributeTypeDefinition or str
matching_rule_definitions – List of MatchingRuleDefinition
syntax_definitions – List of SyntaxDefinition

Is also a mapping of OIDs and short descriptive names to the respective schema element objects (Syntax, …).

syntaxes: Mapping of syntax OIDs to Syntax objects

syntax_definitions: Sequence of SyntaxDefinition objects

matching_rules: Mapping of matching rule OIDs and short descriptive names to EqualityMatchingRule, OrderingMatchingRule and SubstrMatchingRule objects

matching_rule_definitions: Sequence of MatchingRuleDefinition objects

attribute_types: Mapping of attribute type OIDs and short descriptive names to AttributeType objects

user_attribute_types: Set of user (non-operational) attribute types

operational_attribute_types: Set of operational (non-user) attribute types

attribute_type_definitions: Sequence of AttributeTypeDefinition objects

object_classes: Mapping of object class OIDs and short descriptive names to ObjectClass objects

object_class_definitions: Sequence of ObjectClassDefinition objects

matching_rule_use_definitions: Sequence of MatchingRuleUseDefinition objects

extend(object_class_definitions=None, attribute_type_definitions=None, matching_rule_definitions=None, syntax_definitions=None): Return new schema with all schema elements and additional ones

class ldapserver.schema.ObjectClass(schema, definition)

Representation of an object class within a schema

schema

definition: Corresponding AttributeTypeDefinition object

oid: Numeric OID of object class (string, e.g. '2.5.6.0')

names: List of short descriptive names of the object class (list of strings, e.g. ['top'])

ref: Preferred name of object class (first item of names or oid, e.g. 'top')

class ldapserver.schema.AttributeType(schema, definition)

schema

definition: Corresponding AttributeTypeDefinition object

oid: Numeric OID of the attribute type (string, e.g. '2.5.4.3')

names: List of short descriptive names of the attribute type (list of strings, e.g. ['cn', 'commonName'])

ref: Preferred name of attribute type (first item of names or oid, e.g. 'cn')

sup: Superior AttributeType or None

subtypes: Set of subordinate attribute types

equality: EqualityMatchingRule of the attribute type or None if the attribute type has no equality matching rule

ordering: OrderingMatchingRule of the attribute type or None if the attribute type has no ordering matching rule

substr: SubstrMatchingRule of the attribute type or None if the attribute type has no substring matching rule

syntax: Syntax of attribute values

is_operational: True if attribute type is operational, False if it is a user application attribute type.

compatible_matching_rules: Set of all matching rules in schema that can be applied to values of the attribute type

encode(value)

Encode attribute value to its LDAP-specific encoding

Parameters:: value (any) – Native value
Return type:: bytes

decode(raw_value)

Decode LDAP-specific encoding of an attribute value

Parameters:: raw_value (bytes) – LDAP-specific encoding
Return type:: any

match_equal(attribute_values, assertion_value)

Return whether any attribute value equals the assertion value

Parameters:

attribute_values (List of any) – Attribute values (type according to syntax)
assertion_value (bytes) – Assertion value

Returns:

True if any attribute values matches, False otherwise

Return type:

bool

Raises:

exceptions.LDAPError – if the result is undefined

match_substr(attribute_values, inital_substring, any_substrings, final_substring)

Return whether any attribute value matches the substring assertion

Parameters:

attribute_values (List of any) – Attribute values (type according to syntax)
inital_substring (bytes or None) – Substring to match the beginning (optional)
any_substrings (list of bytes) – List of substrings to match between initial and final in order
final_substring (bytes or None) – Substring to match the end (optional)

Returns:

True if any attribute values matches, False otherwise

Return type:

bool

Raises:

exceptions.LDAPError – if the result is undefined

match_approx(attribute_values, assertion_value)

Return whether any attribute value approximately equals the assertion value

Parameters:

attribute_values (List of any) – Attribute values (type according to syntax)
assertion_value (bytes) – Assertion value

Returns:

True if any attribute values matches, False otherwise

Return type:

bool

Raises:

exceptions.LDAPError – if the result is undefined

match_greater_or_equal(attribute_values, assertion_value)

Return whether any attribute value is greater than or equal to assertion value

Parameters:

attribute_values (List of any) – Attribute values (type according to syntax)
assertion_value (bytes) – Assertion value

Returns:

True if any attribute values matches, False otherwise

Return type:

bool

Raises:

exceptions.LDAPError – if the result is undefined

match_less_or_equal(attribute_values, assertion_value)

Return whether any attribute value is less than or equal to assertion value

Parameters:

attribute_values (List of any) – Attribute values (type according to syntax)
assertion_value (bytes) – Assertion value

Returns:

True if any attribute values matches, False otherwise

Return type:

bool

Raises:

exceptions.LDAPError – if the result is undefined

match_extensible(attribute_values, assertion_value, matching_rule=None)

Return whether any attribute value matches the assertion value

Parameters:

attribute_values (List of any) – Attribute values (type according to syntax)
assertion_value (bytes) – Assertion value
matching_rule (EqualityMatchingRule, OrderingMatchingRule, SubstrMatchingRule or None) – Optional matching rule, if None AttributeType.equality is used

Returns:

True if any attribute values matches, False otherwise

Return type:

bool

Raises:

exceptions.LDAPError – if the result is undefined

class ldapserver.schema.EqualityMatchingRule(schema, definition, syntaxes_by_tag)

match_extensible(attribute_values, assertion_value)

Return whether any attribute value equals the assertion value

Returns:: True if any attribute values matches, False otherwise
Return type:: bool
Raises:: exceptions.LDAPError – if the result is undefined

match_equal(attribute_values, assertion_value)

Return whether any attribute value equals the assertion value

Returns:: True if any attribute values matches, False otherwise
Return type:: bool
Raises:: exceptions.LDAPError – if the result is undefined

match_approx(attribute_values, assertion_value)

Return whether any attribute value approximately equals the assertion value

Returns:: True if any attribute values matches, False otherwise
Return type:: bool
Raises:: exceptions.LDAPError – if the result is undefined

definition: Corresponding MatchingRuleDefinition object

oid: Numeric OID of matching rule (string, e.g. '2.5.13.2')

syntax: Syntax of assertion values. For schema.SubstrMatchingRule.match_substr the syntax of the attribute’s equality matching rule is used instead.

names: List of short descriptive names of the matching rule (list of strings, e.g. ['caseIgnoreMatch'])

ref: Preferred name of matching rule (first item of names or oid, e.g. 'caseIgnoreMatch')

compatible_syntaxes: Set of all compatible syntaxes within the schema whose values the matching rule can be applied to

compatible_attribute_types: Set of all compatible attribute types within the schema whose values the matching rule can be applied to

class ldapserver.schema.OrderingMatchingRule(schema, definition, syntaxes_by_tag)

match_less(attribute_values, assertion_value)

Return whether any attribute value is less than assertion value

Returns:: True if any attribute values matches, False otherwise
Return type:: bool
Raises:: exceptions.LDAPError – if the result is undefined

match_greater_or_equal(attribute_values, assertion_value)

Return whether any attribute value is greater than or equal to assertion value

Returns:: True if any attribute values matches, False otherwise
Return type:: bool
Raises:: exceptions.LDAPError – if the result is undefined

definition: Corresponding MatchingRuleDefinition object

oid: Numeric OID of matching rule (string, e.g. '2.5.13.2')

syntax: Syntax of assertion values. For schema.SubstrMatchingRule.match_substr the syntax of the attribute’s equality matching rule is used instead.

names: List of short descriptive names of the matching rule (list of strings, e.g. ['caseIgnoreMatch'])

ref: Preferred name of matching rule (first item of names or oid, e.g. 'caseIgnoreMatch')

compatible_syntaxes: Set of all compatible syntaxes within the schema whose values the matching rule can be applied to

compatible_attribute_types: Set of all compatible attribute types within the schema whose values the matching rule can be applied to

class ldapserver.schema.SubstrMatchingRule(schema, definition, syntaxes_by_tag)

match_extensible(attribute_values, assertion_value)

Return whether any attribute value matches the substring assertion in assertion_value

Parameters:

attribute_values (List of any) – Attribute values (type according to attribute’s syntax)
assertion_value (Tuple[any or None, List[any] or None, any or None]) – 3-tuple with initial substring, any substrings and final substring

Returns:

True if any attribute values matches, False otherwise

Return type:

bool

Raises:

exceptions.LDAPError – if the result is undefined

match_substr(attribute_values, inital_substring, any_substrings, final_substring)

Return whether any attribute value matches the substring assertion

The type of inital_substring, any_substrings and final_substring depends on the syntax of the attribute’s equality matching rule!

Parameters:

attribute_values (List of any) – Attribute values (type according to attribute’s syntax)
inital_substring (any) – Substring to match the beginning (optional)
any_substrings (list of any) – List of substrings to match between initial and final in order
final_substring (any) – Substring to match the end (optional)

Returns:

True if any attribute values matches, False otherwise

Return type:

bool

Raises:

exceptions.LDAPError – if the result is undefined

definition: Corresponding MatchingRuleDefinition object

oid: Numeric OID of matching rule (string, e.g. '2.5.13.2')

syntax: Syntax of assertion values. For schema.SubstrMatchingRule.match_substr the syntax of the attribute’s equality matching rule is used instead.

names: List of short descriptive names of the matching rule (list of strings, e.g. ['caseIgnoreMatch'])

ref: Preferred name of matching rule (first item of names or oid, e.g. 'caseIgnoreMatch')

compatible_syntaxes: Set of all compatible syntaxes within the schema whose values the matching rule can be applied to

compatible_attribute_types: Set of all compatible attribute types within the schema whose values the matching rule can be applied to

class ldapserver.schema.Syntax(schema, definition, syntaxes_by_tag)

LDAP syntax for attribute and assertion values

schema

definition: Corresponding SyntaxDefinition object

oid: Numeric OID of syntax (string, e.g. '1.3.6.1.4.1.1466.115.121.1.15')

ref: Preferred name for syntax (same as oid)

compatible_matching_rules: Set of all matching rules within the schema that can be applied to values of the syntax

encode(value)

Encode value to its LDAP-specific encoding

Parameters:: value (any) – Native value
Return type:: bytes

decode(raw_value)

Decode LDAP-specific encoding of a value

Parameters:: raw_value (bytes) – LDAP-specific encoding
Return type:: any

Low-level Schema Definitions

schema.AttributeTypeDefinition and schema.ObjectClassDefinition objects are nothing more than parsed representations of attribute type and object class definition strings found in standard documents such as RFC4519. schema.MatchingRuleDefinition and schema.SyntaxDefinition also provide methods for encoding/decoding or matching.

Instance attributes of definition objects are named after the definition string keywords converted to snake-case (e.g. NAME becomes name, NO-USER-MODIFICATION becomes no_user_modification).

class ldapserver.schema.SyntaxDefinition(oid, desc='', extensions=None, extra_compatability_tags=None)

oid: Numeric OID (string)

desc: Description (string, empty if there is none)

extensions

compatability_tags

Set of compatability tags (strings, usually numeric OIDs). Syntaxes always have at least their own numeric OID as a compatability tag.

A matching rule can be applied to the values of a syntax if the matching rules compatability tag is one of the syntaxes compatability tags.

__str__()

Return LDAP syntax definition string according to RFC4512

Example:

( 1.3.6.1.4.1.1466.115.121.1.15 DESC ‘Directory String’ )

property first_component_oid: Used by objectIdentifierFirstComponentMatch matching rule

encode(schema, value)

Encode native value to its LDAP-specific encoding

Parameters:

schema (Schema) – Schema of the object in whose context encoding takes place
value (any) – native value (depends on syntax)

Returns:

LDAP-specific encoding of the value

Return type:

bytes

decode(schema, raw_value)

Decode LDAP-specific encoding of a value to a native value

Parameters:

schema (Schema) – Schema of the object in whose context decoding takes place
raw_value (bytes) – LDAP-specific encoding of the value

Returns:

native value (depends on syntax)

Return type:

any

Raises:

exceptions.LDAPError – if raw_value is invalid

class ldapserver.schema.MatchingRuleDefinition(oid, name=None, desc='', obsolete=False, syntax=None, extensions=None, compatability_tag=None, kind=None)

oid: Numeric OID (string)

syntax: OID of assertion value syntax (string)

name: Short descriptive names (list of strings, may be empty)

desc: Description (string, empty if there is none)

obsolete: bool

extensions

compatability_tag

Compatability tag (string, usually a numeric OIDs). Defaults to the OID of its syntax.

A matching rule can be applied to the values of a syntax if the matching rules compatability tag is one of the syntaxes compatability tags.

kind

__str__()

Return matching rule definition string according to RFC4512

Example:

( 2.5.13.2 NAME ‘caseIgnoreMatch’ SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 )

property first_component_oid: Used by objectIdentifierFirstComponentMatch matching rule

match_equal(schema, attribute_values, assertion_value)

Return whether any attribute value equals the assertion value

Only available for EQUALITY matching rules.

Returns:: True if any attribute values matches, False otherwise
Return type:: bool
Raises:: exceptions.LDAPError – if the result is undefined

match_approx(schema, attribute_values, assertion_value)

Return whether any attribute value approximately equals the assertion value

Only available for EQUALITY matching rules.

Returns:: True if any attribute values matches, False otherwise
Return type:: bool
Raises:: exceptions.LDAPError – if the result is undefined

match_less(schema, attribute_values, assertion_value)

Return whether any attribute value is less than assertion value

Only available for ORDERING matching rules.

Returns:: True if any attribute values matches, False otherwise
Return type:: bool
Raises:: exceptions.LDAPError – if the result is undefined

match_greater_or_equal(schema, attribute_values, assertion_value)

Return whether any attribute value is greater than or equal to assertion value

Only available for ORDERING matching rules.

Returns:: True if any attribute values matches, False otherwise
Return type:: bool
Raises:: exceptions.LDAPError – if the result is undefined

match_substr(schema, attribute_values, inital_substring, any_substrings, final_substring)

Return whether any attribute value matches the substring assertion

Only available for SUBSTR matching rules.

The type of inital_substring, any_substrings and final_substring depends on the syntax of the attribute’s equality matching rule!

Parameters:

schema (Schema) – Schema of the object whose attribute values are matched
attribute_values (List of any) – Attribute values (type according to attribute’s syntax)
inital_substring (any) – Substring to match the beginning (optional)
any_substrings (list of any) – List of substrings to match between initial and final in order
final_substring (any) – Substring to match the end (optional)

Returns:

True if any attribute values matches, False otherwise

Return type:

bool

Raises:

exceptions.LDAPError – if the result is undefined

class ldapserver.schema.MatchingRuleUseDefinition(oid, name=None, desc='', obsolete=False, applies=None, extensions=None)

oid: Numeric OID (string)

name: Short descriptive names (list of strings, may be empty)

desc: Description (string, empty if there is none)

obsolete: bool

applies: OIDs or short descriptive names of attribute types the matching rule can be applied to (list of strings)

extensions

__str__()

Return matching rule use definition string according to RFC4512

Example:

( 2.5.13.0 NAME ‘objectIdentifierMatch’ APPLIES ( supportedControl $ supportedExtension $ supportedFeatures $ supportedApplicationContext ) )

property first_component_oid: Used by objectIdentifierFirstComponentMatch matching rule

class ldapserver.schema.AttributeTypeUsage(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Values for AttributeTypeDefinition.usage

userApplications = 1: user (not an operational attribute)

directoryOperation = 2: directory operational

distributedOperation = 3: DSA-shared operational

dSAOperation = 4: DSA-specific operational

class ldapserver.schema.AttributeTypeDefinition(oid, name=None, desc='', obsolete=False, sup=None, equality=None, ordering=None, substr=None, syntax=None, syntax_len=None, single_value=False, collective=False, no_user_modification=False, usage=AttributeTypeUsage.userApplications, extensions=None)

oid: Numeric OID (string)

name: Short descriptive names (list of strings, may be empty)

desc: Description (string, empty if there is none)

obsolete: bool

sup: OID or short descriptive name of superior attribute type (string or None)

equality: OID or short descriptive name of equality matching rule (string or None)

ordering: OID or short descriptive name of ordering matching rule (string or None)

substr: OID or short descriptive name of substrings matching rule (string or None)

syntax: OID of attribute value syntax (string or None)

syntax_len: Suggested minimum upper bound for attribute value length (int or None)

single_value: Whether attribute values are restricted to a single value (bool)

collective: bool

no_user_modification: bool

usage: Value of AttributeTypeUsage

extensions

__str__()

Return attribute type definition string according to RFC4512

Example:

( 2.5.4.3 NAME ( ‘cn’ ‘commonName’ ) DESC ‘RFC4519: common name(s) for which the entity is known by’ SUP name )

The string can be decoded into an equalivalent AttributeTypeDefinition object with from_str.

classmethod from_str(string)

Decode attribute type definition string according to RFC4512

Returns:: Equivalent attribute type definition object
Return type:: AttributeTypeDefinition

See __str__ for the string format.

property first_component_oid: Used by objectIdentifierFirstComponentMatch matching rule

class ldapserver.schema.ObjectClassKind(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Values for ObjectClassDefinition.kind

ABSTRACT = 1

STRUCTURAL = 2

AUXILIARY = 3

class ldapserver.schema.ObjectClassDefinition(oid, name=None, desc='', obsolete=False, sup=None, kind=ObjectClassKind.STRUCTURAL, must=None, may=None, extensions=None)

oid: Numeric OID (string)

name: Short descriptive names (list of strings, may be empty)

desc: Description (string, empty if there is none)

obsolete: bool

sup: OIDs and short descriptive names of superior object classes (list of strings, may be empty)

kind: Value of ObjectClassKind

must: OIDs and short descriptive names of attribute types entries with the object class must have (list of strings, may be empty)

may: OIDs and short descriptive names of attribute types entries with the object class may have (list of strings, may be empty)

extensions

__str__()

Return object class definition string according to RFC4512

Example:

( 2.5.6.0 NAME ‘top’ DESC ‘top of the superclass chain’ ABSTRACT MUST objectClass )

The string can be decoded into an equalivalent ObjectClassDefinition object with from_str.

classmethod from_str(string)

Decode object class definition string according to RFC4512

Returns:: Equivalent object class definition object
Return type:: ObjectClassDefinition

See __str__ for the string format.

property first_component_oid: Used by objectIdentifierFirstComponentMatch matching rule

Built-in Schemas

ldapserver.schema.RFC4512_SCHEMA

ldapserver.schema.CORE_SCHEMA = RFC4512_SCHEMA

ldapserver.schema.RFC4519_SCHEMA

ldapserver.schema.RFC4523_SCHEMA

ldapserver.schema.RFC4524_SCHEMA

ldapserver.schema.COSINE_SCHEMA = RFC4524_SCHEMA

ldapserver.schema.RFC3112_SCHEMA

ldapserver.schema.RFC2079_SCHEMA: Schema implementing the labeledURIObject object class and the labeledURI attribute type.

ldapserver.schema.RFC2798_SCHEMA: Schema implementing the inetOrgPerson object class and its attribute types.

ldapserver.schema.INETORG_SCHMEA = RFC2798_SCHEMA

ldapserver.schema.RFC2307BIS_SCHEMA: Schema implementing draft-howard-rfc2307bis-02 (updated/extended NIS schema)

LDAP Protocol

class ldapserver.ldap.SearchScope(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

enum.Enum of scope values in SEARCH operations

baseObject = 0: Search is constrained to the base object

singleLevel = 1: Search is constrained to the immediate subordinates of the base object

wholeSubtree = 2: Search is constrained to the base object and to all its subordinates

class ldapserver.ldap.Filter

Base class for filters in SEARCH operations

All subclasses implement __str__ according to RFC4515 “String Representation of Search Filters”.

class ldapserver.ldap.FilterAnd(filters=None)

AND conjunction of multiple filters (&filters...)

Supports RFC4526: Empty AND filters ((&)) are considered valid and evaluate to TRUE.

filters: List[Filter]

class ldapserver.ldap.FilterOr(filters=None)

OR conjunction of multiple filters (|filters...)

Supports RFC4526: Empty OR filters ((|)) are considered valid and evaluate to FALSE.

filters: List[Filter]

class ldapserver.ldap.FilterNot(filter=None)

Negation of a filter (!filter)

filter: Filter

class ldapserver.ldap.FilterPresent(attribute=None)

Attribute present filter (attribute=*)

attribute: str

class ldapserver.ldap.FilterEqual(attribute=None, value=None)

Attribute equal filter (attribute=value)

attribute: str

value: bytes

class ldapserver.ldap.FilterApproxMatch(attribute=None, value=None)

Attribute approximately equal filter (attribute~=value)

attribute: str

value: bytes

class ldapserver.ldap.FilterGreaterOrEqual(attribute=None, value=None): Attribute greater or equal filter (attribute>=value)

class ldapserver.ldap.FilterLessOrEqual(attribute=None, value=None)

Attribute less or equal filter (attribute<=value)

attribute: str

value: bytes

class ldapserver.ldap.FilterSubstrings(*args, **kwargs)

Attribute substrings filter (attribute=initial*any1*any2*final)

attribute: str

property initial_substring: Initial substring (bytes). None if there is no initial substring or if the filter is invalid.

property any_substrings: List of “any” substrings (list of bytes, may be empty)

property final_substring: Final substring (bytes). None if there is no final substring or if the filter is invalid.

class ldapserver.ldap.FilterExtensibleMatch(*args, **kwargs)

Extensible match filter (attribute:caseExactMatch:=value)

matchingRule: str: Matching rule OID or short descriptive name (optional, str or None)

type: str: Attribute type OID or short descriptive name (optional, str or None)

matchValue: bytes: Assertion value (bytes, encoded with LDAP-specific encoding according to matching rule syntax)

dnAttributes: bool: Apply matching to all RDN assertions in addition to attribute values (e.g. (dc:dn:=example) matches cn=test,dc=example,dc=com even if it has no dc attribute, because dc=example is part of its DN)

class ldapserver.ldap.SearchResultEntry(*args, **kwargs)

objectName: str

attributes: List[PartialAttribute]

class ldapserver.ldap.PartialAttribute(*args, **kwargs)

type: str

vals: List[bytes]

LDAP Errors

LDAP response messages carry a result code and an optional diagnostic message. The subclasses of ldapserver.exceptions.LDAPError represent the possible (non-success) result codes.

Raising an ldapserver.exceptions.LDAPError instance in a handler method of ldapserver.LDAPRequestHandler aborts the request processing and sends an appropriate response message with the corresponding result code and (if any) the diagnostic message.

exception ldapserver.exceptions.LDAPError(message=''): Base class for all LDAP errors

exception ldapserver.exceptions.LDAPOperationsError(message=''): Indicates that the operation is not properly sequenced with relation to other operations (of same or different type). (RFC 4511)

exception ldapserver.exceptions.LDAPProtocolError(message=''): Indicates the server received data that is not well-formed. (RFC 4511)

exception ldapserver.exceptions.LDAPTimeLimitExceeded(message=''): Indicates that the time limit specified by the client was exceeded before the operation could be completed. (RFC 4511)

exception ldapserver.exceptions.LDAPSizeLimitExceeded(message=''): Indicates that the size limit specified by the client was exceeded before the operation could be completed. (RFC 4511)

exception ldapserver.exceptions.LDAPAuthMethodNotSupported(message=''): Indicates that the authentication method or mechanism is not supported. (RFC 4511)

exception ldapserver.exceptions.LDAPStrongerAuthRequired(message=''): Indicates the server requires strong(er) authentication in order to complete the operation. (RFC 4511)

exception ldapserver.exceptions.LDAPAdminLimitExceeded(message=''): Indicates that an administrative limit has been exceeded. (RFC 4511)

exception ldapserver.exceptions.LDAPUnavailableCriticalExtension(message=''): Indicates a critical control is unrecognized. (RFC 4511)

exception ldapserver.exceptions.LDAPConfidentialityRequired(message=''): Indicates that data confidentiality protections are required. (RFC 4511)

exception ldapserver.exceptions.LDAPNoSuchAttribute(message=''): Indicates that the named entry does not contain the specified attribute or attribute value. (RFC 4511)

exception ldapserver.exceptions.LDAPUndefinedAttributeType(message=''): Indicates that a request field contains an unrecognized attribute description. (RFC 4511)

exception ldapserver.exceptions.LDAPInappropriateMatching(message=''): Indicates that an attempt was made (e.g., in an assertion) to use a matching rule not defined for the attribute type concerned. (RFC 4511)

exception ldapserver.exceptions.LDAPConstraintViolation(message=''): Indicates that the client supplied an attribute value that does not conform to the constraints placed upon it by the data model. (RFC 4511)

exception ldapserver.exceptions.LDAPAttributeOrValueExists(message=''): Indicates that the client supplied an attribute or value to be added to an entry, but the attribute or value already exists. (RFC 4511)

exception ldapserver.exceptions.LDAPInvalidAttributeSyntax(message=''): Indicates that a purported attribute value does not conform to the syntax of the attribute. (RFC 4511)

exception ldapserver.exceptions.LDAPNoSuchObject(message=''): Indicates that the object does not exist in the DIT. (RFC 4511)

exception ldapserver.exceptions.LDAPAliasProblem(message=''): Indicates that an alias problem has occurred. For example, the code may used to indicate an alias has been dereferenced that names no object. (RFC 4511)

exception ldapserver.exceptions.LDAPInvalidDNSyntax(message=''): Indicates that an LDAPDN or RelativeLDAPDN field (e.g., search base, target entry, ModifyDN newrdn, etc.) of a request does not conform to the required syntax or contains attribute values that do not conform to the syntax of the attribute’s type. (RFC 4511)

exception ldapserver.exceptions.LDAPAliasDereferencingProblem(message=''): Indicates that a problem occurred while dereferencing an alias. Typically, an alias was encountered in a situation where it was not allowed or where access was denied. (RFC 4511)

exception ldapserver.exceptions.LDAPInappropriateAuthentication(message=''): Indicates the server requires the client that had attempted to bind anonymously or without supplying credentials to provide some form of credentials. (RFC 4511)

exception ldapserver.exceptions.LDAPInvalidCredentials(message=''): Indicates that the provided credentials (e.g., the user’s name and password) are invalid. (RFC 4511)

exception ldapserver.exceptions.LDAPInsufficientAccessRights(message=''): Indicates that the client does not have sufficient access rights to perform the operation. (RFC 4511)

exception ldapserver.exceptions.LDAPBusy(message=''): Indicates that the server is too busy to service the operation. (RFC 4511)

exception ldapserver.exceptions.LDAPUnavailable(message=''): Indicates that the server is shutting down or a subsystem necessary to complete the operation is offline. (RFC 4511)

exception ldapserver.exceptions.LDAPUnwillingToPerform(message=''): Indicates that the server is unwilling to perform the operation. (RFC 4511)

exception ldapserver.exceptions.LDAPLoopDetect(message=''): Indicates that the server has detected an internal loop (e.g., while dereferencing aliases or chaining an operation). (RFC 4511)

exception ldapserver.exceptions.LDAPNamingViolation(message=''): Indicates that the entry’s name violates naming restrictions. (RFC 4511)

exception ldapserver.exceptions.LDAPObjectClassViolation(message=''): Indicates that the entry violates object class restrictions. (RFC 4511)

exception ldapserver.exceptions.LDAPNotAllowedOnNonLeaf(message=''): Indicates that the operation is inappropriately acting upon a non-leaf entry. (RFC 4511)

exception ldapserver.exceptions.LDAPNotAllowedOnRDN(message=''): Indicates that the operation is inappropriately attempting to remove a value that forms the entry’s relative distinguished name. (RFC 4511)

exception ldapserver.exceptions.LDAPEntryAlreadyExists(message=''): Indicates that the request cannot be fulfilled (added, moved, or renamed) as the target entry already exists. (RFC 4511)

exception ldapserver.exceptions.LDAPObjectClassModsProhibited(message=''): Indicates that an attempt to modify the object class(es) of an entry’s ‘objectClass’ attribute is prohibited. (RFC 4511)

exception ldapserver.exceptions.LDAPAffectsMultipleDSAs(message=''): Indicates that the operation cannot be performed as it would affect multiple servers (DSAs). (RFC 4511)

exception ldapserver.exceptions.LDAPOther(message=''): Indicates the server has encountered an internal error. (RFC 4511)