Skip to content

Commit afd80fd

Browse files
tirantiran
committed
Check and warn if OPT_X_TLS_NEWCTX is required
See #55 Signed-off-by: Christian Heimes <cheimes@redhat.com>
1 parent 084ffe0 commit afd80fd

File tree

10 files changed

+265
-40
lines changed

10 files changed

+265
-40
lines changed

‎Doc/reference/ldap.rst‎

Lines changed: 139 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,13 @@ This module defines the following functions:
8484
.. py:function:: set_option(option, invalue) -> None
8585
8686
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`.
8894

8995

9096
.. _ldap-constants:
@@ -124,10 +130,10 @@ Options
124130

125131
:manpage:`ldap.conf(5)` and :manpage:`ldap_get_option(3)`
126132

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:
131137

132138
.. py:data:: OPT_API_FEATURE_INFO
133139
@@ -220,34 +226,162 @@ SASL options
220226
TLS options
221227
:::::::::::
222228

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+
223241
.. py:data:: OPT_X_TLS
224242
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+
225257
.. py:data:: OPT_X_TLS_ALLOW
226258
259+
Value for :py:const:`OPT_X_TLS_REQUIRE_CERT`
260+
227261
.. py:data:: OPT_X_TLS_CACERTDIR
228262
263+
get/set path to directory with CA certs
264+
229265
.. py:data:: OPT_X_TLS_CACERTFILE
230266
267+
get/set path to PEM file with CA certs
268+
231269
.. py:data:: OPT_X_TLS_CERTFILE
232270
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+
233278
.. py:data:: OPT_X_TLS_CIPHER_SUITE
234279
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+
235299
.. py:data:: OPT_X_TLS_CTX
236300
301+
get address of internal memory address of TLS context (**DO NOT USE**)
302+
237303
.. py:data:: OPT_X_TLS_DEMAND
238304
305+
Value for :py:const:`OPT_X_TLS_REQUIRE_CERT`
306+
239307
.. py:data:: OPT_X_TLS_HARD
240308
309+
Value for :py:const:`OPT_X_TLS` and :py:const:`OPT_X_TLS_REQUIRE_CERT`
310+
241311
.. py:data:: OPT_X_TLS_KEYFILE
242312
313+
get/set path to file with PEM encoded key for client cert authentication,
314+
requires :py:const:`OPT_X_TLS_CERTFILE`.
315+
243316
.. py:data:: OPT_X_TLS_NEVER
244317
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+
245354
.. py:data:: OPT_X_TLS_RANDOM_FILE
246355
356+
get/set path to /dev/urandom (**DO NOT USE**)
357+
247358
.. py:data:: OPT_X_TLS_REQUIRE_CERT
248359
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+
249377
.. py:data:: OPT_X_TLS_TRY
250378
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+
251385
.. _ldap-keepalive-options:
252386

253387
Keepalive options

‎Doc/spelling_wordlist.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ defresult
3838
dereferenced
3939
dereferencing
4040
desc
41+
dev
4142
directoryOperation
4243
distinguished
4344
distributedOperation
@@ -143,6 +144,7 @@ UDP
143144
Umich
144145
unparsing
145146
unsigend
147+
urandom
146148
uri
147149
urlPrefix
148150
urlscheme

‎Lib/ldap/constants.py‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -281,7 +281,6 @@ class Str(Constant):
281281
TLSInt('OPT_X_TLS_DEMAND'),
282282
TLSInt('OPT_X_TLS_ALLOW'),
283283
TLSInt('OPT_X_TLS_TRY'),
284-
TLSInt('OPT_X_TLS_PEERCERT', optional=True),
285284

286285
TLSInt('OPT_X_TLS_VERSION', optional=True),
287286
TLSInt('OPT_X_TLS_CIPHER', optional=True),

‎Makefile‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,10 @@ PYTHON_SUPP=/usr/share/doc/python3-devel/valgrind-python.supp
99
.NOTPARALLEL:
1010

1111
.PHONY: all
12-
all:
12+
all: Modules/constants_generated.h
13+
14+
Modules/constants_generated.h: Lib/ldap/constants.py
15+
$(PYTHON) $^ > $@
1316

1417
.PHONY: clean
1518
clean:

0 commit comments

Comments
 (0)