@@ -84,7 +84,13 @@ This module defines the following functions:
84
84
.. py :function :: set_option(option, invalue) -> None
85
85
86
86
This function sets the value of the global option specified by *option * to
87
- *invalue *.
87
+ *invalue *. Any change to global settings
88
+
89
+ .. note ::
90
+
91
+ Most global settings do not affect existing :py:class: `LDAPObject `
92
+ connections. Applications should call :py:func: `set_option() ` before
93
+ they establish connections with :py:func: `initialize `.
88
94
89
95
90
96
.. _ldap-constants :
@@ -124,10 +130,10 @@ Options
124
130
125
131
:manpage: `ldap.conf(5)` and :manpage: `ldap_get_option(3)`
126
132
127
-
128
- For use with functions :py: func: set_option() and :py: func:get_option()
129
- and methods :py: method: LDAPObject.set_option() and :py: method:LDAPObject. get_option() the
130
- following option identifiers are defined as constants:
133
+ For use with functions :py:func: ` set_option() ` and :py:func: ` get_option() `
134
+ and methods :py:meth: ` LDAPObject. set_option()` and
135
+ :py:meth: ` LDAPObject.get_option() ` the following option identifiers
136
+ are defined as constants:
131
137
132
138
.. py :data :: OPT_API_FEATURE_INFO
133
139
@@ -220,34 +226,162 @@ SASL options
220
226
TLS options
221
227
:::::::::::
222
228
229
+ .. warning ::
230
+ libldap does not materialize all TLS settings immediately, with the
231
+ exception of :py:const: `OPT_X_TLS `. You must use
232
+ :py:const: `OPT_X_TLS_NEWCTX ` to instruct libldap to apply pending TLS
233
+ settings and create a new internal TLS context::
234
+
235
+ conn = ldap.initialize(ldap_uri)
236
+ conn.set_option(ldap.OPT_X_TLS_CACERTFILE, '/path/to/ca.pem')
237
+ conn.set_option(ldap.OPT_X_TLS_NEWCTX, 0)
238
+ conn.start_tls_s()
239
+ conn.simple_bind_s(dn, password)
240
+
223
241
.. py :data :: OPT_X_TLS
224
242
243
+ TLS enforcement mode, perform STARTTLS for plain LDAP connections. The
244
+ setting has no affect when the LDAP connection is already established.
245
+
246
+ :py:const: `OPT_X_TLS_NEVER `
247
+ Don't enforce TLS (default)
248
+
249
+ :py:const: `OPT_X_TLS_HARD `
250
+ Enforce TLS. libldap will automatically perform STARTTLS for plain
251
+ LDAP connections.
252
+
253
+ .. py :data :: OPT_X_TLS_ALL
254
+
255
+ Value for :py:const: `OPT_X_TLS_CRLCHECK `
256
+
225
257
.. py :data :: OPT_X_TLS_ALLOW
226
258
259
+ Value for :py:const: `OPT_X_TLS_REQUIRE_CERT `
260
+
227
261
.. py :data :: OPT_X_TLS_CACERTDIR
228
262
263
+ get/set path to directory with CA certs
264
+
229
265
.. py :data :: OPT_X_TLS_CACERTFILE
230
266
267
+ get/set path to PEM file with CA certs
268
+
231
269
.. py :data :: OPT_X_TLS_CERTFILE
232
270
271
+ get/set path to file with PEM encoded cert for client cert authentication,
272
+ requires :py:const: `OPT_X_TLS_KEYFILE `.
273
+
274
+ .. py :data :: OPT_X_TLS_CIPHER
275
+
276
+ get cipher suite name from TLS session
277
+
233
278
.. py :data :: OPT_X_TLS_CIPHER_SUITE
234
279
280
+ get/set allowed cipher suites
281
+
282
+ .. py :data :: OPT_X_TLS_CRLCHECK
283
+
284
+ get/set CRL check mode. CRL validation needs :py:const: `OPT_X_TLS_CRLFILE `
285
+
286
+ :py:const: `OPT_X_TLS_NONE `
287
+ Don't perform CRL checks
288
+
289
+ :py:const: `OPT_X_TLS_PEER `
290
+ Perform CRL check for peer's end entity cert.
291
+
292
+ :py:const: `OPT_X_TLS_ALL `
293
+ Perform CRL checks for the whole cert chain
294
+
295
+ .. py :data :: OPT_X_TLS_CRLFILE
296
+
297
+ get/set path to CRL file
298
+
235
299
.. py :data :: OPT_X_TLS_CTX
236
300
301
+ get address of internal memory address of TLS context (**DO NOT USE **)
302
+
237
303
.. py :data :: OPT_X_TLS_DEMAND
238
304
305
+ Value for :py:const: `OPT_X_TLS_REQUIRE_CERT `
306
+
239
307
.. py :data :: OPT_X_TLS_HARD
240
308
309
+ Value for :py:const: `OPT_X_TLS ` and :py:const: `OPT_X_TLS_REQUIRE_CERT `
310
+
241
311
.. py :data :: OPT_X_TLS_KEYFILE
242
312
313
+ get/set path to file with PEM encoded key for client cert authentication,
314
+ requires :py:const: `OPT_X_TLS_CERTFILE `.
315
+
243
316
.. py :data :: OPT_X_TLS_NEVER
244
317
318
+ Value for :py:const: `OPT_X_TLS ` and :py:const: `OPT_X_TLS_REQUIRE_CERT `
319
+
320
+ .. py :data :: OPT_X_TLS_NEWCTX
321
+
322
+ set and apply TLS settings to underlying TLS context
323
+
324
+ .. py :data :: OPT_X_TLS_NONE
325
+
326
+ Value for :py:const: `OPT_X_TLS_CRLCHECK `
327
+
328
+ .. py :data :: OPT_X_TLS_PACKAGE
329
+
330
+ Get TLS implementation, known values are
331
+
332
+ * ``GnuTLS ``
333
+ * ``MozNSS `` (Mozilla NSS)
334
+ * ``OpenSSL ``
335
+
336
+ .. py :data :: OPT_X_TLS_PEER
337
+
338
+ Value for :py:const: `OPT_X_TLS_CRLCHECK `
339
+
340
+ .. py :data :: OPT_X_TLS_PEERCERT
341
+
342
+ Get peer's certificate as BER/DER data structure (not supported)
343
+
344
+ .. py :data :: OPT_X_TLS_PROTOCOL_MIN
345
+
346
+ get/set minimum protocol version (wire protocol version as int)
347
+
348
+ * ``0x300 `` for SSL 3.0
349
+ * ``0x301 `` for TLS 1.0
350
+ * ``0x302 `` for TLS 1.1
351
+ * ``0x303 `` for TLS 1.2
352
+ * ``0x304 `` for TLS 1.3
353
+
245
354
.. py :data :: OPT_X_TLS_RANDOM_FILE
246
355
356
+ get/set path to /dev/urandom (**DO NOT USE **)
357
+
247
358
.. py :data :: OPT_X_TLS_REQUIRE_CERT
248
359
360
+ get/set validation strategy for server cert.
361
+
362
+ :py:const: `OPT_X_TLS_NEVER `
363
+ Don't check server cert and host name
364
+
365
+ :py:const: `OPT_X_TLS_ALLOW `
366
+ Ignore cert validation errors and don't check host name
367
+
368
+ :py:const: `OPT_X_TLS_TRY `
369
+ This value is only used by slapd server internally. (**DO NOT USE **)
370
+
371
+ :py:const: `OPT_X_TLS_DEMAND `
372
+ Validate peer cert chain and host name
373
+
374
+ :py:const: `OPT_X_TLS_HARD `
375
+ Same as :py:const: `OPT_X_TLS_DEMAND `
376
+
249
377
.. py :data :: OPT_X_TLS_TRY
250
378
379
+ Value for :py:const: `OPT_X_TLS_REQUIRE_CERT `
380
+
381
+ .. py :data :: OPT_X_TLS_VERSION
382
+
383
+ Get negotiated TLS protocol version as string
384
+
251
385
.. _ldap-keepalive-options :
252
386
253
387
Keepalive options
0 commit comments