Skip to content

Commit 1299d11

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 db4a6ff commit 1299d11

File tree

10 files changed

+266
-40
lines changed

10 files changed

+266
-40
lines changed

‎Doc/reference/ldap.rst‎

Lines changed: 140 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
@@ -214,34 +220,163 @@ SASL options
214220
TLS options
215221
:::::::::::
216222

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+
217236
.. py:data:: OPT_X_TLS
218237
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+
219252
.. py:data:: OPT_X_TLS_ALLOW
220253
254+
Value for :py:const:`OPT_X_TLS_REQUIRE_CERT`
255+
221256
.. py:data:: OPT_X_TLS_CACERTDIR
222257
258+
get/set path to directory with CA certs
259+
223260
.. py:data:: OPT_X_TLS_CACERTFILE
224261
262+
get/set path to PEM file with CA certs
263+
225264
.. py:data:: OPT_X_TLS_CERTFILE
226265
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+
227273
.. py:data:: OPT_X_TLS_CIPHER_SUITE
228274
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+
229294
.. py:data:: OPT_X_TLS_CTX
230295
296+
get address of internal memory address of TLS context (**DO NOT USE**)
297+
231298
.. py:data:: OPT_X_TLS_DEMAND
232299
300+
Value for :py:const:`OPT_X_TLS_REQUIRE_CERT`
301+
233302
.. py:data:: OPT_X_TLS_HARD
234303
304+
Value for :py:const:`OPT_X_TLS` and :py:const:`OPT_X_TLS_REQUIRE_CERT`
305+
235306
.. py:data:: OPT_X_TLS_KEYFILE
236307
308+
get/set path to file with PEM encoded key for client cert authentication,
309+
requires :py:const:`OPT_X_TLS_CERTFILE`.
310+
237311
.. py:data:: OPT_X_TLS_NEVER
238312
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+
239349
.. py:data:: OPT_X_TLS_RANDOM_FILE
240350
351+
get/set path to /dev/urandom (**DO NOT USE**)
352+
241353
.. py:data:: OPT_X_TLS_REQUIRE_CERT
242354
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+
243372
.. py:data:: OPT_X_TLS_TRY
244373
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+
245380
.. _ldap-keepalive-options:
246381

247382
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
@@ -8,7 +8,10 @@ SCAN_REPORT=build/scan_report
88
.NOTPARALLEL:
99

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

1316
.PHONY: clean
1417
clean:

0 commit comments

Comments
 (0)