libldap OpenLDAP C library interface module

Module libldap is a Python3 wrapper for OpenLDAP (Lightweight Directory Access Protocol) C library.

Functions

Following functions are defined by module libldap:

libldap.ldap_initialize(uri [, version=LDAP_VERSION3]])

Creates and initializes a new connection object (LDAPObject) to access a LDAP server and returns this object.

Parameters:
  • uri (str) –

    LDAP URI (Uniform Resource Identifier). It has the following form: ldap[is]://host[:port][/dn]. This parameter is identical to that of the underlying function ldap_initialize() of the library openLDAP except the optional dn. When this dn is provided, each parameter of a method of an instance of a LDAPObject which is a DN, is automatically completed by dn unless it already ends with dn. For example, in the code below:

    >>> l = ldap_initialize('ldap:://host.test/dc=example,dc=test')
>>> l.simple_bind_s(user='cn=admin', password='secret')

    parameter user is rewritten to ‘cn=admin,dc=example,dc=test’ before passed to the underlying OpenLDAP library C function

  • version (LDAP_VERSION2 or LDAP_VERSION3) – version of LDAP protocol
Returns:

a new LDAPObject
Raises:

LDAPError, TypeError or ValueError

See also

ldap_open(3)

libldap.ldap_get_option(option)

This routine is used to retreive global options. See Options for available options.

Parameters:option (int) – global option to retreive
Returns:option value
Return type:int
Raises:LDAPError

For example, to get the peer certificate checking strategy:

>>> ldap_get_option(LDAP_OPT_PROTOCOL_VERSION)
2

See also

ldap_get_option(3)

libldap.ldap_set_option(option, optval)

This routine permits to set global options. See Options for available options.

Parameters:
  • option (int) – global option to set
  • optval (int) – option value
Returns:

None
Raises:

LDAPError

For example, to set the peer certificate checking strategy:

>>> ldap_set_option(LDAP_OPT_X_TLS_REQUIRE_CERT, LDAP_OPT_X_TLS_NEVER)

See also

ldap_set_option(3)

libldap.ldap_is_valid_dn(dn[, flags=LDAP_DN_FORMAT_LDAPV3])

checks DN syntax

Parameters:
Returns:

True if DN is valid, False otherwise

See also

ldap_str2dn(3)

Schema parsing functions

These functions are used to parse schema definitions in the syntax defined in RFC 4512 into Python dictionaries

libldap.ldap_str2syntax(string[, flags])
Parameters:
  • string (str) – the string to parse
  • flags (int) – flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. Default is LDAP_SCHEMA_ALLOW_NONE, see section Flags for more details
Returns:

{'oid': <str>, 'names': <list_of_strs>, 'desc': <str>|None, 'extensions': (<str>, <list_of_strs>)|None}
Raises:

LDAPError, TypeError

The returned value is a Python dictionary corresponding to the C-structure LDAPSyntax of the OpenLDAP library

See also

ldap_schema(3)

libldap.ldap_str2matchingrule(string[, flags])
Parameters:
  • string (str) – the string to parse
  • flags (int) – flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. Default is LDAP_SCHEMA_ALLOW_NONE, see section Flags for more details
Returns:

{'oid': <str>, 'names': <list_of_strs>, 'desc': <str>|None, 'obsolete': <bool>, 'syntax_oid': <str>|None, 'extensions': (<str>, <list_of_strs>)|None}
Raises:

LDAPError, TypeError

The returned value is a Python dictionary corresponding to the C-structure LDAPMatchingRule of the OpenLDAP library

See also

ldap_schema(3)

libldap.ldap_str2matchingruleuse(string[, flags])
Parameters:
  • string (str) – the string to parse
  • flags (int) – flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. Default is LDAP_SCHEMA_ALLOW_NONE, see section Flags for more details
Returns:

{'oid': <str>, 'names': <list_of_strs>, 'desc': <str>|None, 'obsolete': <bool>, 'applies_oids': <list_of_strs>, 'extensions': (<str>, <list_of_strs>)|None}
Raises:

LDAPError, TypeError

The returned value is a Python dictionary corresponding to the C-structure LDAPMatchingRuleUse of the OpenLDAP library

See also

ldap_schema(3)

libldap.ldap_str2attributetype(string[, flags])
Parameters:
  • string (str) – the string to parse
  • flags (int) – flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. Default is LDAP_SCHEMA_ALLOW_NONE, see section Flags for more details
Returns:

{'oid': <str>, 'names': <list_of_strs>, 'desc': <str>|None, 'obsolete': <bool>, 'sup_oid': <str>|None, 'equality_oid': <str>|None, 'ordering_oid': <str>|None, 'substr_oid': <str>|None, 'syntax_oid': <str>|None, 'syntax_len': <int>, 'single_value': <bool>, 'collective': <bool>, 'no_user_mod': <bool>, 'usage': <int>, 'extensions': (<str>, <list_of_strs>)|None}
Raises:

LDAPError, TypeError

The returned value is a Python dictionary corresponding to the C-structure LDAPAttributeType of the OpenLDAP library. For possible values of the field usage see Attribute types

See also

ldap_schema(3)

libldap.ldap_str2objectclass(string[, flags])
Parameters:
  • string (str) – the string to parse
  • flags (int) – flags is a bit mask of parsing options controlling the relaxation of the objectclass recognized. Default is LDAP_SCHEMA_ALLOW_NONE, see section Flags for more details
Returns:

{'oid': <str>, 'names': <list_of_strs>, 'desc': <str>|None, 'obsolete': <bool>, 'sup_oids': <list_of_strs>, 'kind': <int>, 'oids_must': <list_of_strs>', 'oids_may': <list_of_strs>', extensions': (<str>, <list_of_strs>)|None}
Raises:

LDAPError, TypeError

The returned value is a Python dictionary corresponding to the C-structure LDAPObjectClass of the OpenLDAP library. For possible values of the field kind see Object classes

See also

ldap_schema(3)

Examples

>>> ldap_str2syntax("( 1.3.6.1.4.1.1466.115.121.1.4 DESC 'Audio' X-NOT-HUMAN-READABLE 'TRUE' )")
{'extensions': [('X-NOT-HUMAN-READABLE', ['TRUE'])], 'oid': '1.3.6.1.4.1.1466.115.121.1.4', 'desc': 'Audio', 'names': []}
>>> ldap_str2matchingrule("( 1.3.6.1.1.16.3 NAME 'UUIDOrderingMatch' SYNTAX 1.3.6.1.1.16.1 )")
{'names': ['UUIDOrderingMatch'], 'desc': None, 'syntax_oid': '1.3.6.1.1.16.1', 'oid': '1.3.6.1.1.16.3', 'obsolete': False, 'extensions': None}

Constants

General

libldap.LDAP_VERSION2
libldap.LDAP_VERSION3
libldap.LDAP_NO_LIMIT
libldap.LDAP_AUTH_SIMPLE

Modify constants

libldap.LDAP_MOD_ADD
libldap.LDAP_MOD_DELETE
libldap.LDAP_MOD_REPLACE

Scope constants

libldap.LDAP_SCOPE_BASE

search the object itself

libldap.LDAP_SCOPE_ONELEVEL

search the object’s immediate children

libldap.LDAP_SCOPE_SUBTREE

search the object and all its descendants

libldap.LDAP_SCOPE_CHILDREN

search all of the descendants

SASL constants

libldap.LDAP_SASL_AUTOMATIC

use defaults if available, prompt otherwise

libldap.LDAP_SASL_INTERACTIVE

always prompt

libldap.LDAP_SASL_QUIET

never prompt

libldap.LDAP_SASL_SIMPLE

select simple authentication

Schema constants

See also

ldap_schema(3)

libldap.LDAP_SCHEMA_BASE

The base DN used to retreive an LDAP server schema. It is usually the string: 'cn=Subschema'

Flags
libldap.LDAP_SCHEMA_ALLOW_NONE

Strict parsing according to RFC 4512

libldap.LDAP_SCHEMA_ALLOW_NO_OID

Permit definitions that do not contain an initial OID

libldap.LDAP_SCHEMA_ALLOW_QUOTED

Permit quotes around some items that should not have them

libldap.LDAP_SCHEMA_ALLOW_DESCR

Permit a descr instead of a numeric OID in places where the syntax expect the latter

libldap.LDAP_SCHEMA_ALLOW_DESCR_PREFIX

permit that the initial numeric OID contains a prefix in descr format

libldap.LDAP_SCHEMA_ALLOW_ALL

Be very liberal, include all options

Attribute types
libldap.LDAP_SCHEMA_USER_APPLICATIONS

The attribute type is non-operational

libldap.LDAP_SCHEMA_DIRECTORY_OPERATION

The attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type

libldap.LDAP_SCHEMA_DISTRIBUTED_OPERATION

The attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect

libldap.LDAP_SCHEMA_DSA_OPERATION

The attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry

Object classes
libldap.LDAP_SCHEMA_ABSTRACT

The object class is abstract, i.e. there cannot be entries of this class alone

libldap.LDAP_SCHEMA_STRUCTURAL

The object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added

libldap.LDAP_SCHEMA_AUXILIARY

The object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation

DN Constants

libldap.LDAP_DN_FORMAT_LDAPV3
libldap.LDAP_DN_FORMAT_LDAPV2
libldap.LDAP_DN_FORMAT_DCE
libldap.LDAP_DN_PEDANTIC

does not allow extra spaces in the DN

See also

ldap_str2dn(3)

Options

libldap.LDAP_OPT_PROTOCOL_VERSION

SASL options

libldap.LDAP_OPT_X_SASL_MECH

to get the SASL mechanism

libldap.LDAP_OPT_X_SASL_MECHLIST

to get the list of the available SASL mechanisms. For example:

>>> ldap_get_option(LDAP_OPT_X_SASL_MECHLIST)
('ANONYMOUS', 'LOGIN', 'PLAIN', 'CRAM-MD5', 'NTLM', 'EXTERNAL', 'DIGEST-MD5')

TLS options

libldap.LDAP_OPT_X_TLS_REQUIRE_CERT
libldap.LDAP_OPT_X_TLS_NEVER
libldap.LDAP_OPT_X_TLS_HARD
libldap.LDAP_OPT_X_TLS_DEMAND
libldap.LDAP_OPT_X_TLS_ALLOW
libldap.LDAP_OPT_X_TLS_TRY

Exceptions

The module libldap defines only one exception:

exception libldap.LDAPError

This exception is in particular thrown when a call to a function of the OpenLDAP library fails. In this case, the error message associated with this exception is the string returned by ldap_err2string() (see ldap_error(3) for more details)