@@ -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
@@ -214,34 +220,163 @@ SASL options
214
220
TLS options
215
221
:::::::::::
216
222
223
+ .. warning ::
224
+ libldap does not materialize all TLS settings immediately, with the
225
+ exception of :py:const: `OPT_X_TLS `. You must use
226
+ :py:const: `OPT_X_TLS_NEWCTX ` to instruct libldap to apply pending TLS
227
+ settings and create a new internal TLS context::
228
+
229
+ conn = ldap.initialize(ldap_uri)
230
+ conn.set_option(ldap.OPT_X_TLS_REQUIRE_CERT,
231
+ ldap.OPT_X_TLS_HARD)
232
+ conn.set_option(ldap.OPT_X_TLS_NEWCTX, 0)
233
+ conn.start_tls_s()
234
+ conn.simple_bind_s(dn, password)
235
+
217
236
.. py :data :: OPT_X_TLS
218
237
238
+ TLS enforcement mode for ``ldap:// `` URI. The setting has no affect
239
+ when the LDAP connection is already established.
240
+
241
+ :py:const: `OPT_X_TLS_NEVER `
242
+ Don't enforce TLS (default)
243
+
244
+ :py:const: `OPT_X_TLS_HARD `
245
+ Enforce TLS. libldap will automatically perform STARTTLS for plain
246
+ LDAP connections.
247
+
248
+ .. py :data :: OPT_X_TLS_ALL
249
+
250
+ Value for :py:const: `OPT_X_TLS_CRLCHECK `
251
+
219
252
.. py :data :: OPT_X_TLS_ALLOW
220
253
254
+ Value for :py:const: `OPT_X_TLS_REQUIRE_CERT `
255
+
221
256
.. py :data :: OPT_X_TLS_CACERTDIR
222
257
258
+ get/set path to directory with CA certs
259
+
223
260
.. py :data :: OPT_X_TLS_CACERTFILE
224
261
262
+ get/set path to PEM file with CA certs
263
+
225
264
.. py :data :: OPT_X_TLS_CERTFILE
226
265
266
+ get/set path to file with PEM encoded cert for client cert authentication,
267
+ requires :py:const: `OPT_X_TLS_KEYFILE `.
268
+
269
+ .. py :data :: OPT_X_TLS_CIPHER
270
+
271
+ get cipher suite name from TLS session
272
+
227
273
.. py :data :: OPT_X_TLS_CIPHER_SUITE
228
274
275
+ get/set allowed cipher suites
276
+
277
+ .. py :data :: OPT_X_TLS_CRLCHECK
278
+
279
+ get/set CRL check mode. CRL validation needs :py:const: `OPT_X_TLS_CRLFILE `
280
+
281
+ :py:const: `OPT_X_TLS_NONE `
282
+ Don't perform CRL checks
283
+
284
+ :py:const: `OPT_X_TLS_PEER `
285
+ Perform CRL check for peer's end entity cert.
286
+
287
+ :py:const: `OPT_X_TLS_ALL `
288
+ Perform CRL checks for the whole cert chain
289
+
290
+ .. py :data :: OPT_X_TLS_CRLFILE
291
+
292
+ get/set path to CRL file
293
+
229
294
.. py :data :: OPT_X_TLS_CTX
230
295
296
+ get address of internal memory address of TLS context (**DO NOT USE **)
297
+
231
298
.. py :data :: OPT_X_TLS_DEMAND
232
299
300
+ Value for :py:const: `OPT_X_TLS_REQUIRE_CERT `
301
+
233
302
.. py :data :: OPT_X_TLS_HARD
234
303
304
+ Value for :py:const: `OPT_X_TLS ` and :py:const: `OPT_X_TLS_REQUIRE_CERT `
305
+
235
306
.. py :data :: OPT_X_TLS_KEYFILE
236
307
308
+ get/set path to file with PEM encoded key for client cert authentication,
309
+ requires :py:const: `OPT_X_TLS_CERTFILE `.
310
+
237
311
.. py :data :: OPT_X_TLS_NEVER
238
312
313
+ Value for :py:const: `OPT_X_TLS ` and :py:const: `OPT_X_TLS_REQUIRE_CERT `
314
+
315
+ .. py :data :: OPT_X_TLS_NEWCTX
316
+
317
+ set and apply TLS settings to underlying TLS context
318
+
319
+ .. py :data :: OPT_X_TLS_NONE
320
+
321
+ Value for :py:const: `OPT_X_TLS_CRLCHECK `
322
+
323
+ .. py :data :: OPT_X_TLS_PACKAGE
324
+
325
+ Get TLS implementation, known values are
326
+
327
+ * ``GnuTLS ``
328
+ * ``MozNSS `` (Mozilla NSS)
329
+ * ``OpenSSL ``
330
+
331
+ .. py :data :: OPT_X_TLS_PEER
332
+
333
+ Value for :py:const: `OPT_X_TLS_CRLCHECK `
334
+
335
+ .. py :data :: OPT_X_TLS_PEERCERT
336
+
337
+ Get peer's certificate as BER/DER data structure (not supported)
338
+
339
+ .. py :data :: OPT_X_TLS_PROTOCOL_MIN
340
+
341
+ get/set minimum protocol version (wire protocol version as int)
342
+
343
+ * ``0x300 `` for SSL 3.0
344
+ * ``0x301 `` for TLS 1.0
345
+ * ``0x302 `` for TLS 1.1
346
+ * ``0x303 `` for TLS 1.2
347
+ * ``0x304 `` for TLS 1.3
348
+
239
349
.. py :data :: OPT_X_TLS_RANDOM_FILE
240
350
351
+ get/set path to /dev/urandom (**DO NOT USE **)
352
+
241
353
.. py :data :: OPT_X_TLS_REQUIRE_CERT
242
354
355
+ get/set validation strategy for server cert.
356
+
357
+ :py:const: `OPT_X_TLS_NEVER `
358
+ Don't check server cert and host name
359
+
360
+ :py:const: `OPT_X_TLS_ALLOW `
361
+ Ignore cert validation errors and don't check host name
362
+
363
+ :py:const: `OPT_X_TLS_TRY `
364
+ This value is only used by slapd server internally. (**DO NOT USE **)
365
+
366
+ :py:const: `OPT_X_TLS_DEMAND `
367
+ Validate peer cert chain and host name
368
+
369
+ :py:const: `OPT_X_TLS_HARD `
370
+ Same as :py:const: `OPT_X_TLS_DEMAND `
371
+
243
372
.. py :data :: OPT_X_TLS_TRY
244
373
374
+ Value for :py:const: `OPT_X_TLS_REQUIRE_CERT `
375
+
376
+ .. py :data :: OPT_X_TLS_VERSION
377
+
378
+ Get negotiated TLS protocol version as string
379
+
245
380
.. _ldap-keepalive-options :
246
381
247
382
Keepalive options
0 commit comments