ldap.rst 36 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221
  1. .. % $Id: ldap.rst,v 1.18 2011/02/19 13:05:16 stroeder Exp $
  2. *****************************************
  3. :mod:`ldap` LDAP library interface module
  4. *****************************************
  5. .. module:: ldap
  6. :platform: UNIX,Windows
  7. :synopsis: Access to an underlying LDAP C library.
  8. .. moduleauthor:: python-ldap project (see http://www.python-ldap.org/)
  9. This module provides access to the LDAP (Lightweight Directory Access Protocol)
  10. C API implemented in OpenLDAP 2.3 or newer. It is similar to the C API, with
  11. the notable differences that lists are manipulated via Python list operations
  12. and errors appear as exceptions. For far more detailed information on the C
  13. interface, please see the (expired) draft-ietf-ldapext-ldap-c-api-04. This
  14. documentation is current for the Python LDAP module, version |release|. Source
  15. and binaries are available from http://www.python-ldap.org/.
  16. .. % not standard, in C
  17. .. % Author of the module code;
  18. .. % Leave at least one blank line after this, to simplify ad-hoc tools
  19. .. % that are sometimes used to massage these files.
  20. .. % ==== 2. ====
  21. .. % Give a short overview of what the module does.
  22. .. % If it is platform specific, mention this.
  23. .. % Mention other important restrictions or general operating principles.
  24. .. % ==== 3. ====
  25. .. % List the public functions defined by the module. Begin with a
  26. .. % standard phrase. You may also list the exceptions and other data
  27. .. % items defined in the module, insofar as they are important for the
  28. .. % user.
  29. Functions
  30. =========
  31. The :mod:`ldap` module defines the following functions:
  32. .. function:: initialize(uri [, trace_level=0 [, trace_file=sys.stdout [, trace_stack_limit=None]]])
  33. Opens a new connection with an LDAP server, and return an LDAP object
  34. (see :ref:`ldap-objects`) used to perform operations on that server. Parameter
  35. *uri* has to be a valid LDAP URL.
  36. The optional arguments are for generating debug log information:
  37. *trace_level* specifies the amount of information being logged,
  38. *trace_file* specifies a file-like object as target of the debug log and
  39. *trace_stack_limit* specifies the stack limit of tracebacks in debug log.
  40. Possible values for *trace_level* are
  41. :const:`0` for no logging,
  42. :const:`1` for only logging the method calls with arguments,
  43. :const:`2` for logging the method calls with arguments and the complete results and
  44. :const:`3` for also logging the traceback of method calls.
  45. .. seealso::
  46. :rfc:`4516` - Lightweight Directory Access Protocol (LDAP): Uniform Resource Locator
  47. .. % -> LDAPObject
  48. .. function:: open(host [, port=PORT])
  49. Opens a new connection with an LDAP server, and return an LDAP object (see
  50. :ref:`ldap-objects`) used to perform operations on that server. *host* is a
  51. string containing solely the host name. *port* is an integer specifying the
  52. port where the LDAP server is listening (default is 389). Note: Using this
  53. function is deprecated.
  54. .. % -> LDAPObject
  55. .. % %------------------------------------------------------------
  56. .. % % get_option
  57. .. function:: get_option(option)
  58. This function returns the value of the global option specified by *option*.
  59. .. % -> None
  60. .. % %------------------------------------------------------------
  61. .. % % set_option
  62. .. function:: set_option(option, invalue)
  63. This function sets the value of the global option specified by *option* to
  64. *invalue*.
  65. .. % -> None
  66. .. _ldap-constants:
  67. Constants
  68. =========
  69. The module defines various constants. Note that some constants depend
  70. on the build options and which underlying libs were used or even on
  71. the version of the libs. So before using those constants the application has
  72. to explicitly check whether they are available.
  73. General
  74. -------
  75. .. data:: PORT
  76. The assigned TCP port number (389) that LDAP servers listen on.
  77. .. data:: SASL_AVAIL
  78. Integer where a non-zero value indicates that python-ldap was built with
  79. support for SASL (Cyrus-SASL).
  80. .. data:: TLS_AVAIL
  81. Integer where a non-zero value indicates that python-ldap was built with
  82. support for SSL/TLS (OpenSSL or similar libs).
  83. .. _ldap-options:
  84. Options
  85. -------
  86. .. seealso::
  87. :manpage:`ldap.conf{5}` and :manpage:`ldap_get_options{3}`
  88. For use with functions and method set_option() and get_option() the
  89. following option identifiers are defined as constants:
  90. .. data:: OPT_API_FEATURE_INFO
  91. .. data:: OPT_API_INFO
  92. .. data:: OPT_CLIENT_CONTROLS
  93. .. data:: OPT_DEBUG_LEVEL
  94. Sets the debug level within the underlying LDAP C lib.
  95. .. data:: OPT_DEFBASE
  96. .. data:: OPT_DEREF
  97. Specifies how alias derefencing is done within the underlying LDAP C lib.
  98. .. data:: OPT_ERROR_STRING
  99. .. data:: OPT_DIAGNOSTIC_MESSAGE
  100. .. data:: OPT_HOST_NAME
  101. .. data:: OPT_MATCHED_DN
  102. .. data:: OPT_NETWORK_TIMEOUT
  103. .. data:: OPT_PROTOCOL_VERSION
  104. Sets the LDAP protocol version used for a connection. This is mapped to
  105. object attribute `ldap.LDAPObject.protocol_version`
  106. .. data:: OPT_REFERRALS
  107. int specifying whether referrals should be automatically chased within
  108. the underlying LDAP C lib.
  109. .. data:: OPT_REFHOPLIMIT
  110. .. data:: OPT_RESTART
  111. .. data:: OPT_SERVER_CONTROLS
  112. .. data:: OPT_SIZELIMIT
  113. .. data:: OPT_SUCCESS
  114. .. data:: OPT_TIMELIMIT
  115. .. data:: OPT_TIMEOUT
  116. .. data:: OPT_URI
  117. .. _ldap-sasl-options:
  118. SASL options
  119. ::::::::::::
  120. .. data:: OPT_X_SASL_AUTHCID
  121. .. data:: OPT_X_SASL_AUTHZID
  122. .. data:: OPT_X_SASL_MECH
  123. .. data:: OPT_X_SASL_NOCANON
  124. If set to zero SASL host name canonicalization is disabled.
  125. .. data:: OPT_X_SASL_REALM
  126. .. data:: OPT_X_SASL_SECPROPS
  127. .. data:: OPT_X_SASL_SSF
  128. .. data:: OPT_X_SASL_SSF_EXTERNAL
  129. .. data:: OPT_X_SASL_SSF_MAX
  130. .. data:: OPT_X_SASL_SSF_MIN
  131. .. _ldap-tls-options:
  132. TLS options
  133. :::::::::::
  134. .. data:: OPT_X_TLS
  135. .. data:: OPT_X_TLS_ALLOW
  136. .. data:: OPT_X_TLS_CACERTDIR
  137. .. data:: OPT_X_TLS_CACERTFILE
  138. .. data:: OPT_X_TLS_CERTFILE
  139. .. data:: OPT_X_TLS_CIPHER_SUITE
  140. .. data:: OPT_X_TLS_CTX
  141. .. data:: OPT_X_TLS_DEMAND
  142. .. data:: OPT_X_TLS_HARD
  143. .. data:: OPT_X_TLS_KEYFILE
  144. .. data:: OPT_X_TLS_NEVER
  145. .. data:: OPT_X_TLS_RANDOM_FILE
  146. .. data:: OPT_X_TLS_REQUIRE_CERT
  147. .. data:: OPT_X_TLS_TRY
  148. .. _ldap-keepalive-options:
  149. Keepalive options
  150. :::::::::::::::::
  151. .. data:: OPT_X_KEEPALIVE_IDLE
  152. .. data:: OPT_X_KEEPALIVE_PROBES
  153. .. data:: OPT_X_KEEPALIVE_INTERVAL
  154. .. _ldap-dn-flags:
  155. DN format flags
  156. ----------------
  157. This constants are used for DN-parsing functions found in
  158. sub-module :mod:`ldap.dn`.
  159. .. seealso::
  160. :manpage:`ldap_str2dn{3}`
  161. .. data:: DN_FORMAT_LDAP
  162. .. data:: DN_FORMAT_LDAPV3
  163. .. data:: DN_FORMAT_LDAPV2
  164. .. data:: DN_FORMAT_DCE
  165. .. data:: DN_FORMAT_UFN
  166. .. data:: DN_FORMAT_AD_CANONICAL
  167. .. data:: DN_FORMAT_MASK
  168. .. data:: DN_PRETTY
  169. .. data:: DN_SKIP
  170. .. data:: DN_P_NOLEADTRAILSPACES
  171. .. data:: DN_P_NOSPACEAFTERRDN
  172. .. data:: DN_PEDANTIC
  173. .. _ldap-exceptions:
  174. Exceptions
  175. ==========
  176. The module defines the following exceptions:
  177. .. exception:: LDAPError
  178. This is the base class of all execeptions raised by the module :mod:`ldap`.
  179. Unlike the C interface, errors are not returned as result codes, but
  180. are instead turned into exceptions, raised as soon an the error condition
  181. is detected.
  182. The exceptions are accompanied by a dictionary possibly
  183. containing an string value for the key :const:`desc`
  184. (giving an English description of the error class)
  185. and/or a string value for the key :const:`info`
  186. (giving a string containing more information that the server may have sent).
  187. A third possible field of this dictionary is :const:`matched` and
  188. is set to a truncated form of the name provided or alias dereferenced
  189. for the lowest entry (object or alias) that was matched.
  190. .. exception:: ADMINLIMIT_EXCEEDED
  191. .. exception:: AFFECTS_MULTIPLE_DSAS
  192. .. exception:: ALIAS_DEREF_PROBLEM
  193. A problem was encountered when dereferencing an alias.
  194. (Sets the :const:`matched` field.)
  195. .. exception:: ALIAS_PROBLEM
  196. An alias in the directory points to a nonexistent entry.
  197. (Sets the :const:`matched` field.)
  198. .. exception:: ALREADY_EXISTS
  199. The entry already exists. E.g. the *dn* specified with :meth:`add()`
  200. already exists in the DIT.
  201. .. exception:: AUTH_UNKNOWN
  202. The authentication method specified to :meth:`bind()` is not known.
  203. .. exception:: BUSY
  204. The DSA is busy.
  205. .. exception:: CLIENT_LOOP
  206. .. exception:: COMPARE_FALSE
  207. A compare operation returned false.
  208. (This exception should never be seen because :meth:`compare()` returns
  209. a boolean result.)
  210. .. exception:: COMPARE_TRUE
  211. A compare operation returned true.
  212. (This exception should never be seen because :meth:`compare()` returns
  213. a boolean result.)
  214. .. exception:: CONFIDENTIALITY_REQUIRED
  215. Indicates that the session is not protected by a protocol such
  216. as Transport Layer Security (TLS), which provides session
  217. confidentiality.
  218. .. exception:: CONNECT_ERROR
  219. .. exception:: CONSTRAINT_VIOLATION
  220. An attribute value specified or an operation started violates some
  221. server-side constraint
  222. (e.g., a postalAddress has too many lines or a line that is too long
  223. or a password is expired).
  224. .. exception:: CONTROL_NOT_FOUND
  225. .. exception:: DECODING_ERROR
  226. An error was encountered decoding a result from the LDAP server.
  227. .. exception:: ENCODING_ERROR
  228. An error was encountered encoding parameters to send to the LDAP server.
  229. .. exception:: FILTER_ERROR
  230. An invalid filter was supplied to :meth:`search()`
  231. (e.g. unbalanced parentheses).
  232. .. exception:: INAPPROPRIATE_AUTH
  233. Inappropriate authentication was specified (e.g. :const:`AUTH_SIMPLE`
  234. was specified and the entry does not have a userPassword attribute).
  235. .. exception:: INAPPROPRIATE_MATCHING
  236. Filter type not supported for the specified attribute.
  237. .. exception:: INSUFFICIENT_ACCESS
  238. The user has insufficient access to perform the operation.
  239. .. exception:: INVALID_CREDENTIALS
  240. Invalid credentials were presented during :meth:`bind()` or
  241. :meth:`simple_bind()`.
  242. (e.g., the wrong password).
  243. .. exception:: INVALID_DN_SYNTAX
  244. A syntactically invalid DN was specified. (Sets the :const:`matched` field.)
  245. .. exception:: INVALID_SYNTAX
  246. An attribute value specified by the client did not comply to the
  247. syntax defined in the server-side schema.
  248. .. exception:: IS_LEAF
  249. The object specified is a leaf of the diretcory tree.
  250. Sets the :const:`matched` field of the exception dictionary value.
  251. .. exception:: LOCAL_ERROR
  252. Some local error occurred. This is usually due to failed memory allocation.
  253. .. exception:: LOOP_DETECT
  254. A loop was detected.
  255. .. exception:: MORE_RESULTS_TO_RETURN
  256. .. exception:: NAMING_VIOLATION
  257. A naming violation occurred. This is raised e.g. if the LDAP server
  258. has constraints about the tree naming.
  259. .. exception:: NO_OBJECT_CLASS_MODS
  260. Modifying the objectClass attribute as requested is not allowed
  261. (e.g. modifying structural object class of existing entry).
  262. .. exception:: NOT_ALLOWED_ON_NONLEAF
  263. The operation is not allowed on a non-leaf object.
  264. .. exception:: NOT_ALLOWED_ON_RDN
  265. The operation is not allowed on an RDN.
  266. .. exception:: NOT_SUPPORTED
  267. .. exception:: NO_MEMORY
  268. .. exception:: NO_OBJECT_CLASS_MODS
  269. Object class modifications are not allowed.
  270. .. exception:: NO_RESULTS_RETURNED
  271. .. exception:: NO_SUCH_ATTRIBUTE
  272. The attribute type specified does not exist in the entry.
  273. .. exception:: NO_SUCH_OBJECT
  274. The specified object does not exist in the directory.
  275. Sets the :const:`matched` field of the exception dictionary value.
  276. .. exception:: OBJECT_CLASS_VIOLATION
  277. An object class violation occurred when the LDAP server checked
  278. the data sent by the client against the server-side schema
  279. (e.g. a "must" attribute was missing in the entry data).
  280. .. exception:: OPERATIONS_ERROR
  281. An operations error occurred.
  282. .. exception:: OTHER
  283. An unclassified error occurred.
  284. .. exception:: PARAM_ERROR
  285. An ldap routine was called with a bad parameter.
  286. .. exception:: PARTIAL_RESULTS
  287. Partial results only returned. This exception is raised if
  288. a referral is received when using LDAPv2.
  289. (This exception should never be seen with LDAPv3.)
  290. .. exception:: PROTOCOL_ERROR
  291. A violation of the LDAP protocol was detected.
  292. .. exception:: RESULTS_TOO_LARGE
  293. The result does not fit into a UDP packet. This happens only when using
  294. UDP-based CLDAP (connection-less LDAP) which is not supported anyway.
  295. .. exception:: SASL_BIND_IN_PROGRESS
  296. .. exception:: SERVER_DOWN
  297. The LDAP library can't contact the LDAP server.
  298. .. exception:: SIZELIMIT_EXCEEDED
  299. An LDAP size limit was exceeded.
  300. This could be due to a ``sizelimit`` configuration on the LDAP server.
  301. .. exception:: STRONG_AUTH_NOT_SUPPORTED
  302. The LDAP server does not support strong authentication.
  303. .. exception:: STRONG_AUTH_REQUIRED
  304. Strong authentication is required for the operation.
  305. .. exception:: TIMELIMIT_EXCEEDED
  306. An LDAP time limit was exceeded.
  307. .. exception:: TIMEOUT
  308. A timelimit was exceeded while waiting for a result from the server.
  309. .. exception:: TYPE_OR_VALUE_EXISTS
  310. An attribute type or attribute value specified already
  311. exists in the entry.
  312. .. exception:: UNAVAILABLE
  313. The DSA is unavailable.
  314. .. exception:: UNAVAILABLE_CRITICAL_EXTENSION
  315. Indicates that the LDAP server was unable to satisfy a request
  316. because one or more critical extensions were not available. Either
  317. the server does not support the control or the control is not appropriate
  318. for the operation type.
  319. .. exception:: UNDEFINED_TYPE
  320. An attribute type used is not defined in the server-side schema.
  321. .. exception:: UNWILLING_TO_PERFORM
  322. The DSA is unwilling to perform the operation.
  323. .. exception:: USER_CANCELLED
  324. The operation was cancelled via the :meth:`abandon()` method.
  325. The above exceptions are raised when a result code from an underlying API
  326. call does not indicate success.
  327. .. _ldap-objects:
  328. LDAPObject class
  329. ================
  330. .. % This label is generally useful for referencing this section, but is
  331. .. % also used to give a filename when generating HTML.
  332. .. %\noindent
  333. Instances of :class:`ldap.LDAPObject` are returned by :func:`initialize()`
  334. and :func:`open()` (deprecated). The connection is automatically unbound
  335. and closed when the LDAP object is deleted.
  336. Arguments for LDAPv3 controls
  337. -----------------------------
  338. The :mod:`ldap.controls` module can be used for constructing and
  339. decoding LDAPv3 controls. These arguments are available in the methods
  340. with names ending in :const:`_ext` or :const:`_ext_s`:
  341. *serverctrls*
  342. is a list of :class:`LDAPControl` instances sent to the server along
  343. with the LDAP request (see module :mod:`ldap.controls`). These are
  344. controls which alter the behaviour of the server when processing the
  345. request if the control is supported by the server. The effect of controls
  346. might differ depending on the type of LDAP request or controls might not
  347. be applicable with certain LDAP requests at all.
  348. *clientctrls*
  349. is a list of :class:`LDAPControl` instances passed to the
  350. client API and alter the behaviour of the client when processing the
  351. request.
  352. Sending LDAP requests
  353. ---------------------
  354. Most methods on LDAP objects initiate an asynchronous request to the
  355. LDAP server and return a message id that can be used later to retrieve
  356. the result with :meth:`result()`.
  357. Methods with names ending in :const:`_s` are the synchronous form
  358. and wait for and return with the server's result, or with
  359. :const:`None` if no data is expected.
  360. LDAPObject instances have the following methods:
  361. .. %%------------------------------------------------------------
  362. .. %% abandon
  363. .. method:: LDAPObject.abandon(msgid)
  364. .. method:: LDAPObject.abandon_ext(msgid [, serverctrls=None [, clientctrls=None]])
  365. Abandons an LDAP operation in progress without waiting for a LDAP response.
  366. The *msgid* argument should be the message ID of an outstanding LDAP
  367. operation as returned by the asynchronous methods :meth:`search()`, :meth:`modify()`, etc.
  368. The caller can expect that the result of an abandoned operation will not be
  369. returned from a future call to :meth:`result()`.
  370. *serverctrls* and *clientctrls* like described above.
  371. .. %%------------------------------------------------------------
  372. .. %% add
  373. .. method:: LDAPObject.add(dn, modlist)
  374. .. % -> int
  375. .. method:: LDAPObject.add_s(dn, modlist)
  376. .. % -> None
  377. .. method:: LDAPObject.add_ext(dn, modlist [, serverctrls=None [, clientctrls=None]])
  378. .. % -> int
  379. .. method:: LDAPObject.add_ext_s(dn, modlist [, serverctrls=None [, clientctrls=None]])
  380. .. % -> None
  381. Performs an LDAP add operation. The *dn* argument is the distinguished
  382. name (DN) of the entry to add, and *modlist* is a list of attributes to be
  383. added. The modlist is similar the one passed to :meth:`modify()`, except that the
  384. operation integer is omitted from the tuples in modlist. You might want to
  385. look into sub-module \refmodule{ldap.modlist} for generating the modlist.
  386. The asynchronous methods :meth:`add()` and :meth:`add_ext()`
  387. return the message ID of the initiated request.
  388. *serverctrls* and *clientctrls* like described above.
  389. .. %%------------------------------------------------------------
  390. .. %% bind
  391. .. method:: LDAPObject.bind(who, cred, method)
  392. .. % -> int
  393. .. method:: LDAPObject.bind_s(who, cred, method)
  394. .. % -> None
  395. .. method:: LDAPObject.simple_bind([who='' [, cred='']])
  396. .. % -> int
  397. .. method:: LDAPObject.simple_bind_s([who='' [, cred='']])
  398. .. % -> None
  399. After an LDAP object is created, and before any other operations can be
  400. attempted over the connection, a bind operation must be performed.
  401. This method attempts to bind with the LDAP server using
  402. either simple authentication, or Kerberos (if available).
  403. The first and most general method, :meth:`bind()`,
  404. takes a third parameter, *method* which can currently solely
  405. be :const:`AUTH_SIMPLE`.
  406. .. %%------------------------------------------------------------
  407. .. %% sasl_interactive_bind_s
  408. .. method:: LDAPObject.sasl_interactive_bind_s(who, auth)
  409. .. % -> None
  410. This call is used to bind to the directory with a SASL bind request.
  411. .. %%------------------------------------------------------------
  412. .. %% cancel
  413. .. method:: LDAPObject.cancel( cancelid, [, serverctrls=None [, clientctrls=None]])
  414. Send cancels extended operation for an LDAP operation specified by *cancelid*.
  415. The *cancelid* should be the message id of an outstanding LDAP operation as returned
  416. by the asynchronous methods search(), modify() etc. The caller
  417. can expect that the result of an abandoned operation will not be
  418. returned from a future call to :meth:`result()`.
  419. In opposite to :meth:`abandon()` this extended operation gets an result from
  420. the server and thus should be preferred if the server supports it.
  421. *serverctrls* and *clientctrls* like described above.
  422. :rfc:`3909` - Lightweight Directory Access Protocol (LDAP): Cancel Operation
  423. .. %%------------------------------------------------------------
  424. .. %% compare
  425. .. method:: LDAPObject.compare(dn, attr, value)
  426. .. % -> int
  427. .. method:: LDAPObject.compare_s(dn, attr, value)
  428. .. % -> tuple
  429. .. method:: LDAPObject.compare_ext(dn, attr, value [, serverctrls=None [, clientctrls=None]])
  430. .. % -> int
  431. .. method:: LDAPObject.compare_ext_s(dn, attr, value [, serverctrls=None [, clientctrls=None]])
  432. .. % -> tuple
  433. Perform an LDAP comparison between the attribute named *attr* of
  434. entry *dn*, and the value *value*. The synchronous forms
  435. returns :const:`0` for false, or :const:`1` for true.
  436. The asynchronous forms returns the message ID of the initiated request,
  437. and the result of the asynchronous compare can be obtained using
  438. :meth:`result()`.
  439. Note that the asynchronous technique yields the answer
  440. by raising the exception objects :exc:`ldap.COMPARE_TRUE` or
  441. :exc:`ldap.COMPARE_FALSE`.
  442. *serverctrls* and *clientctrls* like described above.
  443. .. note::
  444. A design fault in the LDAP API prevents *value*
  445. from containing nul characters.
  446. .. %%------------------------------------------------------------
  447. .. %% delete
  448. .. method:: LDAPObject.delete(dn)
  449. .. % -> int
  450. .. method:: LDAPObject.delete_s(dn)
  451. .. % -> None
  452. .. method:: LDAPObject.delete_ext(dn [, serverctrls=None [, clientctrls=None]])
  453. .. % -> int
  454. .. method:: LDAPObject.delete_ext_s(dn [, serverctrls=None [, clientctrls=None]])
  455. .. % -> None
  456. Performs an LDAP delete operation on *dn*. The asynchronous form
  457. returns the message id of the initiated request, and the result can be obtained
  458. from a subsequent call to :meth:`result()`.
  459. *serverctrls* and *clientctrls* like described above.
  460. .. %%------------------------------------------------------------
  461. .. %% modify
  462. .. method:: LDAPObject.modify(dn, modlist)
  463. .. % -> int
  464. .. method:: LDAPObject.modify_s(dn, modlist)
  465. .. % -> None
  466. .. method:: LDAPObject.modify_ext(dn, modlist [, serverctrls=None [, clientctrls=None]])
  467. .. % -> int
  468. .. method:: LDAPObject.modify_ext_s(dn, modlist [, serverctrls=None [, clientctrls=None]])
  469. .. % -> None
  470. Performs an LDAP modify operation on an entry's attributes.
  471. The *dn* argument is the distinguished name (DN) of the entry to modify,
  472. and *modlist* is a list of modifications to make to that entry.
  473. Each element in the list *modlist* should be a tuple of the form
  474. *(mod_op,mod_type,mod_vals)*,
  475. where *mod_op* indicates the operation (one of :const:`MOD_ADD`,
  476. :const:`MOD_DELETE`, or :const:`MOD_REPLACE`),
  477. *mod_type* is a string indicating the attribute type name, and
  478. *mod_vals* is either a string value or a list of string values to add,
  479. delete or replace respectively. For the delete operation, *mod_vals*
  480. may be :const:`None` indicating that all attributes are to be deleted.
  481. *serverctrls* and *clientctrls* like described above.
  482. The asynchronous methods :meth:`modify()` and :meth:`modify_ext()`
  483. return the message ID of the initiated request.
  484. You might want to look into sub-module :mod:`ldap.modlist` for
  485. generating *modlist*.
  486. .. %%------------------------------------------------------------
  487. .. %% modrdn
  488. .. method:: LDAPObject.modrdn(dn, newrdn [, delold=1])
  489. .. %-> int
  490. .. method:: LDAPObject.modrdn_s(dn, newrdn [, delold=1])
  491. .. % -> None
  492. Perform a ``modify RDN`` operation, (i.e. a renaming operation).
  493. These routines take *dn* (the DN of the entry whose RDN is to be changed,
  494. and *newrdn*, the new RDN to give to the entry. The optional parameter
  495. *delold* is used to specify whether the old RDN should be kept as an
  496. attribute of the entry or not.
  497. The asynchronous version returns the initiated message id.
  498. This operation is emulated by :meth:`rename()` and :meth:`rename_s()` methods
  499. since the modrdn2* routines in the C library are deprecated.
  500. .. %%------------------------------------------------------------
  501. .. %% passwd
  502. .. method:: LDAPObject.passwd(user, oldpw, newpw [, serverctrls=None [, clientctrls=None]])
  503. .. %-> int
  504. .. method:: LDAPObject.passwd_s(user, oldpw, newpw [, serverctrls=None [, clientctrls=None]])
  505. .. % -> None
  506. Perform a ``LDAP Password Modify Extended Operation`` operation
  507. on the entry specified by *user*.
  508. The old password in *oldpw* is replaced with the new
  509. password in *newpw* by a LDAP server supporting this operation.
  510. *serverctrls* and *clientctrls* like described above.
  511. The asynchronous version returns the initiated message id.
  512. .. seealso::
  513. :rfc:`3062` - LDAP Password Modify Extended Operation
  514. .. %%------------------------------------------------------------
  515. .. %% rename
  516. .. method:: LDAPObject.rename(dn, newrdn [, newsuperior=None [, delold=1 [, serverctrls=None [, clientctrls=None]]]])
  517. .. %-> int
  518. .. method:: LDAPObject.rename_s(dn, newrdn [, newsuperior=None [, delold=1 [, serverctrls=None [, clientctrls=None]]]])
  519. .. % -> None
  520. Perform a ``Rename`` operation, (i.e. a renaming operation).
  521. These routines take *dn* (the DN of the entry whose RDN is to be changed,
  522. and *newrdn*, the new RDN to give to the entry.
  523. The optional parameter *newsuperior* is used to specify
  524. a new parent DN for moving an entry in the tree
  525. (not all LDAP servers support this).
  526. The optional parameter *delold* is used to specify
  527. whether the old RDN should be kept as an attribute of the entry or not.
  528. *serverctrls* and *clientctrls* like described above.
  529. .. %%------------------------------------------------------------
  530. .. %% result
  531. .. method:: LDAPObject.result([msgid=RES_ANY [, all=1 [, timeout=-1]]])
  532. .. % -> 2-tuple
  533. This method is used to wait for and return the result of an operation
  534. previously initiated by one of the LDAP *asynchronous* operations
  535. (eg :meth:`search()`, :meth:`modify()`, etc.)
  536. The *msgid* parameter is the integer identifier returned by that method.
  537. The identifier is guaranteed to be unique across an LDAP session,
  538. and tells the :meth:`result()` method to request the result of that
  539. specific operation.
  540. If a result is desired from any one of the in-progress operations,
  541. *msgid* should be specified as the constant :const:`RES_ANY`
  542. and the method :meth:`result2()` should be used instead.
  543. The *all* parameter only has meaning for :meth:`search()` responses
  544. and is used to select whether a single entry of the search
  545. response should be returned, or to wait for all the results
  546. of the search before returning.
  547. A search response is made up of zero or more search entries
  548. followed by a search result. If *all* is 0, search entries will
  549. be returned one at a time as they come in, via separate calls
  550. to :meth:`result()`. If all is 1, the search response will be returned
  551. in its entirety, i.e. after all entries and the final search
  552. result have been received.
  553. For *all* set to 0, result tuples
  554. trickle in (with the same message id), and with the result types
  555. :const:`RES_SEARCH_ENTRY` and :const:`RES_SEARCH_REFERENCE`,
  556. until the final result which has a result type of :const:`RES_SEARCH_RESULT`
  557. and a (usually) empty data field. When all is set to 1, only one result is returned,
  558. with a result type of RES_SEARCH_RESULT, and all the result tuples
  559. listed in the data field.
  560. The *timeout* parameter is a limit on the number of seconds that the
  561. method will wait for a response from the server.
  562. If *timeout* is negative (which is the default),
  563. the method will wait indefinitely for a response.
  564. The timeout can be expressed as a floating-point value, and
  565. a value of :const:`0` effects a poll.
  566. If a timeout does occur, a :exc:`ldap.TIMEOUT` exception is raised,
  567. unless polling, in which case ``(None, None)`` is returned.
  568. The :meth:`result()` method returns a tuple of the form
  569. ``(result-type, result-data)``.
  570. The first element, ``result-type`` is a string, being one of
  571. these module constants:
  572. :const:`RES_BIND`, :const:`RES_SEARCH_ENTRY`,
  573. :const:`RES_SEARCH_REFERENCE`, :const:`RES_SEARCH_RESULT`,
  574. :const:`RES_MODIFY`, :const:`RES_ADD`, :const:`RES_DELETE`,
  575. :const:`RES_MODRDN`, or :const:`RES_COMPARE`.
  576. If *all* is :const:`0`, one response at a time is returned on
  577. each call to :meth:`result()`, with termination indicated by
  578. ``result-data`` being an empty list.
  579. See :meth:`search()` for a description of the search result's
  580. ``result-data``, otherwise the ``result-data`` is normally meaningless.
  581. .. %%------------------------------------------------------------
  582. .. %% result2
  583. .. method:: LDAPObject.result2([msgid=RES_ANY [, all=1 [, timeout=-1]]])
  584. .. % -> 3-tuple
  585. This method behaves almost exactly like :meth:`result()`. But
  586. it returns a 3-tuple also containing the message id of the
  587. outstanding LDAP operation a particular result message belongs
  588. to. This is especially handy if one needs to dispatch results
  589. obtained with ``msgid=``:const:`RES_ANY` to several consumer
  590. threads which invoked a particular LDAP operation.
  591. .. %%------------------------------------------------------------
  592. .. %% result3
  593. .. method:: LDAPObject.result3([msgid=RES_ANY [, all=1 [, timeout=-1]]])
  594. .. % -> 4-tuple
  595. This method behaves almost exactly like :meth:`result2()`. But it
  596. returns an extra item in the tuple, the decoded server controls.
  597. .. %%------------------------------------------------------------
  598. .. %% search
  599. .. method:: LDAPObject.search(base, scope [,filterstr='(objectClass=*)' [, attrlist=None [, attrsonly=0]]])
  600. .. %->int
  601. .. method:: LDAPObject.search_s(base, scope [,filterstr='(objectClass=*)' [, attrlist=None [, attrsonly=0]]])
  602. .. %->list|None
  603. .. method:: LDAPObject.search_st(base, scope [,filterstr='(objectClass=*)' [, attrlist=None [, attrsonly=0 [, timeout=-1]]]])
  604. .. method:: LDAPObject.search_ext(base, scope [,filterstr='(objectClass=*)' [, attrlist=None [, attrsonly=0 [, serverctrls=None [, clientctrls=None [, timeout=-1 [, sizelimit=0]]]]]]])
  605. .. %->int
  606. .. method:: LDAPObject.search_ext_s(base, scope [,filterstr='(objectClass=*)' [, attrlist=None [, attrsonly=0 [, serverctrls=None [, clientctrls=None [, timeout=-1 [, sizelimit=0]]]]]]])
  607. .. %->list|None
  608. Perform an LDAP search operation, with *base* as the DN of the entry
  609. at which to start the search, *scope* being one of
  610. :const:`SCOPE_BASE` (to search the object itself),
  611. :const:`SCOPE_ONELEVEL` (to search the object's immediate children), or
  612. :const:`SCOPE_SUBTREE` (to search the object and all its descendants).
  613. The *filterstr* argument is a string representation of the filter to apply in
  614. the search.
  615. .. seealso::
  616. :rfc:`4515` - Lightweight Directory Access Protocol (LDAP): String Representation of Search Filters.
  617. Each result tuple is of the form ``(dn, attrs)``,
  618. where *dn* is a string containing the DN (distinguished name) of the
  619. entry, and *attrs* is a dictionary containing the attributes associated
  620. with the entry. The keys of *attrs* are strings, and the associated
  621. values are lists of strings.
  622. The DN in *dn* is automatically extracted using the underlying libldap
  623. function :cfunc:`ldap_get_dn()`, which may raise an exception if the
  624. DN is malformed.
  625. If *attrsonly* is non-zero, the values of *attrs* will be meaningless
  626. (they are not transmitted in the result).
  627. The retrieved attributes can be limited with the *attrlist* parameter.
  628. If *attrlist* is :const:`None`, all the attributes of each entry are returned.
  629. *serverctrls* and *clientctrls* like described above.
  630. The synchronous form with timeout, :meth:`search_st()` or :meth:`search_ext_s()`,
  631. will block for at most *timeout* seconds (or indefinitely if *timeout*
  632. is negative). A :exc:`ldap.TIMEOUT` exception is raised if no result is received
  633. within the specified time.
  634. The amount of search results retrieved can be limited with the
  635. *sizelimit* parameter when using :meth:`search_ext()`
  636. or :meth:`search_ext_s()` (client-side search limit). If non-zero
  637. not more than *sizelimit* results are returned by the server.
  638. .. %%------------------------------------------------------------
  639. .. %% start_tls_s
  640. .. method:: LDAPObject.start_tls_s()
  641. .. % -> None
  642. Negotiate TLS with server. The ``version`` attribute must have been
  643. set to :const:`VERSION3` (which it is by default) before calling this method.
  644. If TLS could not be started an exception will be raised.
  645. .. seealso::
  646. :rfc:`2830` - Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security
  647. .. %%------------------------------------------------------------
  648. .. %% unbind
  649. .. method:: LDAPObject.unbind()
  650. .. % -> int
  651. .. method:: LDAPObject.unbind_s()
  652. .. % -> None
  653. .. method:: LDAPObject.unbind_ext([, serverctrls=None [, clientctrls=None]])
  654. .. % -> int
  655. .. method:: LDAPObject.unbind_ext_s([, serverctrls=None [, clientctrls=None]])
  656. .. % -> None
  657. This call is used to unbind from the directory, terminate the
  658. current association, and free resources. Once called, the connection to the
  659. LDAP server is closed and the LDAP object is marked invalid.
  660. Further invocation of methods on the object will yield exceptions.
  661. *serverctrls* and *clientctrls* like described above.
  662. These methods are all synchronous in nature.
  663. .. %%------------------------------------------------------------
  664. .. %% whoami_s
  665. .. method:: LDAPObject.whoami_s()
  666. .. % -> string
  667. This synchronous method implements the LDAP "Who Am I?"
  668. extended operation.
  669. It is useful for finding out to find out which identity
  670. is assumed by the LDAP server after a SASL bind.
  671. .. seealso::
  672. :rfc:`4532` - Lightweight Directory Access Protocol (LDAP) "Who am I?" Operation
  673. Connection-specific LDAP options
  674. --------------------------------
  675. .. %%------------------------------------------------------------
  676. .. %% get_option
  677. .. method:: LDAPObject.get_option(option)
  678. .. % -> None
  679. This method returns the value of the LDAPObject option
  680. specified by *option*.
  681. .. %%------------------------------------------------------------
  682. .. %% set_option
  683. .. method:: LDAPObject.set_option(option, invalue)
  684. .. % -> None
  685. This method sets the value of the LDAPObject option
  686. specified by *option* to *invalue*.
  687. Object attributes
  688. -----------------
  689. If the underlying library provides enough information,
  690. each LDAP object will also have the following attributes.
  691. These attributes are mutable unless described as read-only.
  692. .. %%------------------------------------------------------------
  693. .. %% deref
  694. .. attribute:: LDAPObject.deref
  695. .. % -> int
  696. Controls whether aliases are automatically dereferenced.
  697. This must be one of :const:`DEREF_NEVER`, :const:`DEREF_SEARCHING`, :const:`DEREF_FINDING`,
  698. or :const:`DEREF_ALWAYS`.
  699. This option is mapped to option constant :const:`OPT_DEREF`
  700. and used in the underlying OpenLDAP lib.
  701. .. %%------------------------------------------------------------
  702. .. %% network_timeout
  703. .. attribute:: LDAPObject.network_timeout
  704. .. % -> int
  705. Limit on waiting for a network response, in seconds.
  706. Defaults to :const:`NO_LIMIT`.
  707. This option is mapped to option constant :const:`OPT_NETWORK_TIMEOUT`
  708. and used in the underlying OpenLDAP lib.
  709. .. %%------------------------------------------------------------
  710. .. %% protocol_version
  711. .. attribute:: LDAPObject.protocol_version
  712. .. % -> int
  713. Version of LDAP in use (either :const:`VERSION2` for LDAPv2
  714. or :const:`VERSION3` for LDAPv3).
  715. This option is mapped to option constant :const:`OPT_PROTOCOL_VERSION`
  716. and used in the underlying OpenLDAP lib.
  717. .. note::
  718. It is highly recommended to set the protocol version after establishing
  719. a LDAP connection with :func:`initialize()` and before submitting
  720. the first request.
  721. .. %%------------------------------------------------------------
  722. .. %% sizelimit
  723. .. attribute:: LDAPObject.sizelimit
  724. .. % -> int
  725. Limit on size of message to receive from server.
  726. Defaults to :const:`NO_LIMIT`.
  727. This option is mapped to option constant :const:`OPT_SIZELIMIT`
  728. and used in the underlying OpenLDAP lib. Its use is deprecated
  729. in favour of *sizelimit* parameter when using :meth:`search_ext()`.
  730. .. %%------------------------------------------------------------
  731. .. %% timelimit
  732. .. attribute:: LDAPObject.timelimit
  733. .. % -> int
  734. Limit on waiting for any response, in seconds.
  735. Defaults to :const:`NO_LIMIT`.
  736. This option is mapped to option constant :const:`OPT_TIMELIMIT`
  737. and used in the underlying OpenLDAP lib. Its use is deprecated
  738. in favour of using *timeout*.
  739. .. %%------------------------------------------------------------
  740. .. %% timeout
  741. .. attribute:: LDAPObject.timeout
  742. .. % -> int
  743. Limit on waiting for any response, in seconds.
  744. Defaults to :const:`NO_LIMIT`.
  745. This option is used in the wrapper module.
  746. .. _ldap-example:
  747. Example
  748. =======
  749. The following example demonstrates how to open a connection to an
  750. LDAP server using the :mod:`ldap` module and invoke a synchronous
  751. subtree search.
  752. >>> import ldap
  753. >>> l = ldap.initialize('ldap://localhost:1390')
  754. >>> l.search_s('ou=Testing,dc=stroeder,dc=de',ldap.SCOPE_SUBTREE,'(cn=fred*)',['cn','mail'])
  755. [('cn=Fred Feuerstein,ou=Testing,dc=stroeder,dc=de', {'cn': ['Fred Feuerstein']})]
  756. >>> r = l.search_s('ou=Testing,dc=stroeder,dc=de',ldap.SCOPE_SUBTREE,'(objectClass=*)',['cn','mail'])
  757. >>> for dn,entry in r:
  758. >>> print 'Processing',repr(dn)
  759. >>> handle_ldap_entry(entry)