ldap.controls High-level access to LDAPv3 extended controls

Variables

ldap.controls.KNOWN_RESPONSE_CONTROLS

Dictionary mapping the OIDs of known response controls to the accompanying ResponseControl classes. This is used by DecodeControlTuples() to automatically decode control values. Calling application can also register their custom ResponseControl classes in this dictionary possibly overriding pre-registered classes.

Classes

This module defines the following classes:

class ldap.controls.RequestControl(controlType=None, criticality=False, encodedControlValue=None)

Base class for all request controls

controlType
OID as string of the LDAPv3 extended request control
criticality
sets the criticality of the control (boolean)
encodedControlValue
control value of the LDAPv3 extended request control (here it is the BER-encoded ASN.1 control value)
encodeControlValue()

sets class attribute encodedControlValue to the BER-encoded ASN.1 control value composed by class attributes set before

class ldap.controls.ResponseControl(controlType=None, criticality=False)

Base class for all response controls

controlType
OID as string of the LDAPv3 extended response control
criticality
sets the criticality of the received control (boolean)
decodeControlValue(encodedControlValue)

decodes the BER-encoded ASN.1 control value and sets the appropriate class attributes

class ldap.controls.LDAPControl(controlType=None, criticality=False, controlValue=None, encodedControlValue=None)

Base class for combined request/response controls mainly for backward-compatibility to python-ldap 2.3.x

Functions

This module defines the following functions:

ldap.controls.RequestControlTuples(ldapControls)

Return list of readily encoded 3-tuples which can be directly passed to C module _ldap

ldapControls
sequence-type of RequestControl objects
ldap.controls.DecodeControlTuples(ldapControlTuples, knownLDAPControls=None)

Returns list of readily decoded ResponseControl objects

ldapControlTuples
Sequence-type of 3-tuples returned by _ldap.result4() containing the encoded ASN.1 control values of response controls.
knownLDAPControls
Dictionary mapping extended control’s OID to ResponseControl class of response controls known by the application. If None ldap.controls.KNOWN_RESPONSE_CONTROLS is used here.

Sub-modules

Various sub-modules implement specific LDAPv3 extended controls. The classes therein are derived from the base-classes ldap.controls.RequestControl, ldap.controls.ResponseControl or ldap.controls.LDAPControl.

Some of them require pyasn1 and pyasn1_modules to be installed:

Usually the names of the method arguments and the class attributes match the ASN.1 identifiers used in the specification. So looking at the referenced RFC or Internet-Draft is very helpful to understand the API.

ldap.controls.simple Very simple controls

class ldap.controls.simple.ValueLessRequestControl(controlType=None, criticality=False)

Base class for controls without a controlValue. The presence of the control in a LDAPv3 request changes the server’s behaviour when processing the request simply based on the controlType.

controlType
OID of the request control
criticality
criticality request control
encodeControlValue()

sets class attribute encodedControlValue to the BER-encoded ASN.1 control value composed by class attributes set before

class ldap.controls.simple.OctetStringInteger(controlType=None, criticality=False, integerValue=None)

Base class with controlValue being unsigend integer values

integerValue
Integer to be sent as OctetString
decodeControlValue(encodedControlValue)

decodes the BER-encoded ASN.1 control value and sets the appropriate class attributes

encodeControlValue()

sets class attribute encodedControlValue to the BER-encoded ASN.1 control value composed by class attributes set before

class ldap.controls.simple.BooleanControl(controlType=None, criticality=False, booleanValue=False)

Base class for simple request controls with boolean control value.

Constructor argument and class attribute:

booleanValue
Boolean (True/False or 1/0) which is the boolean controlValue.
decodeControlValue(encodedControlValue)

decodes the BER-encoded ASN.1 control value and sets the appropriate class attributes

encodeControlValue()

sets class attribute encodedControlValue to the BER-encoded ASN.1 control value composed by class attributes set before

class ldap.controls.simple.ManageDSAITControl(criticality=False)

Manage DSA IT Control

See also

RFC 3296 - Named Subordinate References in Lightweight Directory Access Protocol (LDAP) Directories

class ldap.controls.simple.RelaxRulesControl(criticality=False)

Relax Rules Control

See also

draft-zeilenga-ldap-relax

class ldap.controls.simple.ProxyAuthzControl(criticality, authzId)

Proxy Authorization Control

authzId
string containing the authorization ID indicating the identity on behalf which the server should process the request

See also

RFC 4370 - Lightweight Directory Access Protocol (LDAP): Proxied Authorization Control

class ldap.controls.simple.AuthorizationIdentityRequestControl(criticality)

Authorization Identity Request and Response Controls

See also

RFC 3829 - Lightweight Directory Access Protocol (LDAP): Authorization Identity Request and Response Controls

class ldap.controls.simple.AuthorizationIdentityResponseControl(controlType=None, criticality=False)

Authorization Identity Request and Response Controls

Class attributes:

authzId
decoded authorization identity

See also

RFC 3829 - Lightweight Directory Access Protocol (LDAP): Authorization Identity Request and Response Controls

decodeControlValue(encodedControlValue)

decodes the BER-encoded ASN.1 control value and sets the appropriate class attributes

class ldap.controls.simple.GetEffectiveRightsControl(criticality, authzId=None)

Get Effective Rights Control

ldap.controls.libldap Various controls implemented in OpenLDAP libs

This module wraps C functions in OpenLDAP client libs which implement various request and response controls into Python classes.

class ldap.controls.libldap.AssertionControl(criticality=True, filterstr='(objectClass=*)')

LDAP Assertion control, as defined in RFC 4528

filterstr
LDAP filter string specifying which assertions have to match so that the server processes the operation

See also

RFC 4528 - Lightweight Directory Access Protocol (LDAP) Assertion Control

encodeControlValue()

sets class attribute encodedControlValue to the BER-encoded ASN.1 control value composed by class attributes set before

class ldap.controls.libldap.MatchedValuesControl(criticality=False, filterstr='(objectClass=*)')

LDAP Matched Values control, as defined in RFC 3876

filterstr
LDAP filter string specifying which attribute values should be returned

See also

RFC 3876 - Returning Matched Values with the Lightweight Directory Access Protocol version 3 (LDAPv3)

encodeControlValue()

sets class attribute encodedControlValue to the BER-encoded ASN.1 control value composed by class attributes set before

class ldap.controls.libldap.SimplePagedResultsControl(criticality=False, size=None, cookie=None)

LDAP Control Extension for Simple Paged Results Manipulation

size
Page size requested (number of entries to be returned)
cookie
Cookie string received with last page

See also

RFC 2696 - LDAP Control Extension for Simple Paged Results Manipulation

decodeControlValue(encodedControlValue)

decodes the BER-encoded ASN.1 control value and sets the appropriate class attributes

encodeControlValue()

sets class attribute encodedControlValue to the BER-encoded ASN.1 control value composed by class attributes set before

ldap.controls.psearch LDAP Persistent Search

This module implements request and response controls for LDAP persistent search.

See also

draft-ietf-ldapext-psearch

class ldap.controls.psearch.PersistentSearchControl(criticality=True, changeTypes=None, changesOnly=False, returnECs=True)

Implements the request control for persistent search.

changeTypes
List of strings specifying the types of changes returned by the server. Setting to None requests all changes.
changesOnly
Boolean which indicates whether only changes are returned by the server.
returnECs
Boolean which indicates whether the server should return an Entry Change Notification response control
class PersistentSearchControlValue(**kwargs)
encodeControlValue()

sets class attribute encodedControlValue to the BER-encoded ASN.1 control value composed by class attributes set before

class ldap.controls.psearch.EntryChangeNotificationControl(controlType=None, criticality=False)

Implements the response control for persistent search.

Class attributes with values extracted from the response control:

changeType
String indicating the type of change causing this result to be returned by the server
previousDN
Old DN of the entry in case of a modrdn change
changeNumber
A change serial number returned by the server (optional).
decodeControlValue(encodedControlValue)

decodes the BER-encoded ASN.1 control value and sets the appropriate class attributes

ldap.controls.sessiontrack Session tracking control

See also

draft-wahl-ldap-session

class ldap.controls.sessiontrack.SessionTrackingControl(sessionSourceIp, sessionSourceName, formatOID, sessionTrackingIdentifier)

Class for Session Tracking Control

Because criticality MUST be false for this control it cannot be set from the application.

sessionSourceIp
IP address of the request source as string
sessionSourceName
Name of the request source as string
formatOID
OID as string specifying the format
sessionTrackingIdentifier
String containing a specific tracking ID
class SessionIdentifierControlValue(**kwargs)
encodeControlValue()

sets class attribute encodedControlValue to the BER-encoded ASN.1 control value composed by class attributes set before

ldap.controls.readentry Read entry control

See also

RFC 4527 - Lightweight Directory Access Protocol (LDAP): Read Entry Controls

Changed in version 4.0: The attribute values of the entry now consists of bytes instead of ISO8859-1 decoded str.

class ldap.controls.readentry.ReadEntryControl(criticality=False, attrList=None)

Base class for read entry control described in RFC 4527

attrList
list of attribute type names requested

Class attributes with values extracted from the response control:

dn
string holding the distinguished name of the LDAP entry
entry
dictionary holding the LDAP entry
decodeControlValue(encodedControlValue)

decodes the BER-encoded ASN.1 control value and sets the appropriate class attributes

encodeControlValue()

sets class attribute encodedControlValue to the BER-encoded ASN.1 control value composed by class attributes set before

class ldap.controls.readentry.PreReadControl(criticality=False, attrList=None)

Class for pre-read control described in RFC 4527

attrList
list of attribute type names requested

Class attributes with values extracted from the response control:

dn
string holding the distinguished name of the LDAP entry before the operation was done by the server
entry
dictionary holding the LDAP entry before the operation was done by the server
class ldap.controls.readentry.PostReadControl(criticality=False, attrList=None)

Class for post-read control described in RFC 4527

attrList
list of attribute type names requested

Class attributes with values extracted from the response control:

dn
string holding the distinguished name of the LDAP entry after the operation was done by the server
entry
dictionary holding the LDAP entry after the operation was done by the server

ldap.controls.ppolicy Password Policy Control

See also

draft-behera-ldap-password-policy

class ldap.controls.ppolicy.PasswordPolicyControl(criticality=False)

Indicates the errors and warnings about the password policy.

timeBeforeExpiration

The time before the password expires.

Type:int
graceAuthNsRemaining

The number of grace authentications remaining.

Type:int
error

The password and authentication errors.

Type:int
decodeControlValue(encodedControlValue)

decodes the BER-encoded ASN.1 control value and sets the appropriate class attributes