# `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)
    componentType = <NamedTypes object, types <NamedType object, type changeTypes=<Integer schema object, tagSet <TagSet object, tags 0:0:2>>>, <NamedType object, type changesOnly=<Boolean schema object, tagSet <TagSet object, tags 0:0:1>, subtypeSpec <ConstraintsIntersection object, consts <SingleValueConstraint object, consts 0, 1>>, namedValues <NamedValues object, enums False=0, True=1>>>, <NamedType object, type returnECs=<Boolean schema object, tagSet <TagSet object, tags 0:0:1>, subtypeSpec <ConstraintsIntersection object, consts <SingleValueConstraint object, consts 0, 1>>, namedValues <NamedValues object, enums False=0, True=1>>>>

      Default collection of ASN.1 types of component (e.g. `NamedType`) object imposing size constraint on Asn1Type objects

  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)
    componentType = <NamedTypes object, types <NamedType object, type sessionSourceIp=<LDAPString schema object, tagSet <TagSet object, tags 0:0:4>, encoding iso-8859-1>>, <NamedType object, type sessionSourceName=<LDAPString schema object, tagSet <TagSet object, tags 0:0:4>, encoding iso-8859-1>>, <NamedType object, type formatOID=<LDAPOID schema object, tagSet <TagSet object, tags 0:0:4>, encoding iso-8859-1>>, <NamedType object, type sessionTrackingIdentifier=<LDAPString schema object, tagSet <TagSet object, tags 0:0:4>, encoding iso-8859-1>>>

      Default collection of ASN.1 types of component (e.g. `NamedType`) object imposing size constraint on Asn1Type objects

  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