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-compability 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
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
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.
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

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

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

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)

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

ldap.controls.psearch LDAP Persistent Search

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

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

Implements the request control for persistent search.

changeTypes
List of strings specifiying 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 Notication response control
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).

ldap.controls.sessiontrack Session tracking control

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

ldap.controls.readentry Read entry control

See also

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

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
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