@@ -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,154 @@ SASL options
220
226
TLS options
221
227
:::::::::::
222
228
229
+ .. warning ::
230
+ libldap does not materialize all TLS settings immediately. You must use
231
+ :py:const: `OPT_X_TLS_NEWCTX ` to instruct libldap to apply pending TLS
232
+ settings and create a new internal TLS context::
233
+
234
+ conn = ldap.initialize(ldap_uri)
235
+ conn.set_option(ldap.OPT_X_TLS_CACERTFILE, '/path/to/ca.pem')
236
+ conn.set_option(ldap.OPT_X_TLS_NEWCTX, 0)
237
+ conn.start_tls_s()
238
+ conn.simple_bind_s(dn, password)
239
+
223
240
.. py :data :: OPT_X_TLS
224
241
242
+ .. deprecated :: 3.0
243
+ The option is deprecated in OpenLDAP and should no longer be used. It
244
+ will be removed in the future.
245
+
246
+ .. py :data :: OPT_X_TLS_ALL
247
+
248
+ Value for :py:const: `OPT_X_TLS_CRLCHECK `
249
+
225
250
.. py :data :: OPT_X_TLS_ALLOW
226
251
252
+ Value for :py:const: `OPT_X_TLS_REQUIRE_CERT `
253
+
227
254
.. py :data :: OPT_X_TLS_CACERTDIR
228
255
256
+ get/set path to directory with CA certs
257
+
229
258
.. py :data :: OPT_X_TLS_CACERTFILE
230
259
260
+ get/set path to PEM file with CA certs
261
+
231
262
.. py :data :: OPT_X_TLS_CERTFILE
232
263
264
+ get/set path to file with PEM encoded cert for client cert authentication,
265
+ requires :py:const: `OPT_X_TLS_KEYFILE `.
266
+
267
+ .. py :data :: OPT_X_TLS_CIPHER
268
+
269
+ get cipher suite name from TLS session
270
+
233
271
.. py :data :: OPT_X_TLS_CIPHER_SUITE
234
272
273
+ get/set allowed cipher suites
274
+
275
+ .. py :data :: OPT_X_TLS_CRLCHECK
276
+
277
+ get/set CRL check mode. CRL validation needs :py:const: `OPT_X_TLS_CRLFILE `
278
+
279
+ :py:const: `OPT_X_TLS_NONE `
280
+ Don't perform CRL checks
281
+
282
+ :py:const: `OPT_X_TLS_PEER `
283
+ Perform CRL check for peer's end entity cert.
284
+
285
+ :py:const: `OPT_X_TLS_ALL `
286
+ Perform CRL checks for the whole cert chain
287
+
288
+ .. py :data :: OPT_X_TLS_CRLFILE
289
+
290
+ get/set path to CRL file
291
+
235
292
.. py :data :: OPT_X_TLS_CTX
236
293
294
+ get address of internal memory address of TLS context (**DO NOT USE **)
295
+
237
296
.. py :data :: OPT_X_TLS_DEMAND
238
297
298
+ Value for :py:const: `OPT_X_TLS_REQUIRE_CERT `
299
+
239
300
.. py :data :: OPT_X_TLS_HARD
240
301
302
+ Value for :py:const: `OPT_X_TLS_REQUIRE_CERT `
303
+
241
304
.. py :data :: OPT_X_TLS_KEYFILE
242
305
306
+ get/set path to file with PEM encoded key for client cert authentication,
307
+ requires :py:const: `OPT_X_TLS_CERTFILE `.
308
+
243
309
.. py :data :: OPT_X_TLS_NEVER
244
310
311
+ Value for :py:const: `OPT_X_TLS_REQUIRE_CERT `
312
+
313
+ .. py :data :: OPT_X_TLS_NEWCTX
314
+
315
+ set and apply TLS settings to underlying TLS context
316
+
317
+ .. py :data :: OPT_X_TLS_NONE
318
+
319
+ Value for :py:const: `OPT_X_TLS_CRLCHECK `
320
+
321
+ .. py :data :: OPT_X_TLS_PACKAGE
322
+
323
+ Get TLS implementation, known values are
324
+
325
+ * ``GnuTLS ``
326
+ * ``MozNSS `` (Mozilla NSS)
327
+ * ``OpenSSL ``
328
+
329
+ .. py :data :: OPT_X_TLS_PEER
330
+
331
+ Value for :py:const: `OPT_X_TLS_CRLCHECK `
332
+
333
+ .. py :data :: OPT_X_TLS_PEERCERT
334
+
335
+ Get peer's certificate as BER/DER data structure (not supported)
336
+
337
+ .. py :data :: OPT_X_TLS_PROTOCOL_MIN
338
+
339
+ get/set minimum protocol version (wire protocol version as int)
340
+
341
+ * ``0x300 `` for SSL 3.0
342
+ * ``0x301 `` for TLS 1.0
343
+ * ``0x302 `` for TLS 1.1
344
+ * ``0x303 `` for TLS 1.2
345
+ * ``0x304 `` for TLS 1.3
346
+
245
347
.. py :data :: OPT_X_TLS_RANDOM_FILE
246
348
349
+ get/set path to /dev/urandom (**DO NOT USE **)
350
+
247
351
.. py :data :: OPT_X_TLS_REQUIRE_CERT
248
352
353
+ get/set validation strategy for server cert.
354
+
355
+ :py:const: `OPT_X_TLS_NEVER `
356
+ Don't check server cert and host name
357
+
358
+ :py:const: `OPT_X_TLS_ALLOW `
359
+ Ignore cert validation errors and don't check host name
360
+
361
+ :py:const: `OPT_X_TLS_DEMAND `
362
+ Validate peer cert chain and host name
363
+
364
+ :py:const: `OPT_X_TLS_HARD `
365
+ Same as :py:const: `OPT_X_TLS_DEMAND `
366
+
249
367
.. py :data :: OPT_X_TLS_TRY
250
368
369
+ .. deprecated :: 3.0
370
+ This value is only used by slapd server internally. It will be removed
371
+ in the future.
372
+
373
+ .. py :data :: OPT_X_TLS_VERSION
374
+
375
+ Get negotiated TLS protocol version as string
376
+
251
377
.. _ldap-keepalive-options :
252
378
253
379
Keepalive options
@@ -564,6 +690,8 @@ The above exceptions are raised when a result code from an underlying API
564
690
call does not indicate success.
565
691
566
692
693
+ .. _ldap-warnings :
694
+
567
695
Warnings
568
696
========
569
697
@@ -575,6 +703,16 @@ Warnings
575
703
576
704
.. versionadded :: 3.0.0
577
705
706
+ .. py :exception :: LDAPTLSWarning
707
+
708
+ Raised when python-ldap detects missing call of
709
+ :py:meth: `LDAPObject.set_option ` with
710
+ option :py:const: `OPT_X_TLS_NEWCTX `.
711
+
712
+ See :ref: `ldap-tls-options ` for details.
713
+
714
+ .. versionadded :: 3.0.0
715
+
578
716
579
717
.. _ldap-objects :
580
718
0 commit comments