ldap.rst 35 KB

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