Skip to content

Commit 2522c4f

Browse files
tirantiran
committed
Check and warn if OPT_X_TLS_NEWCTX is required
Without OPT_X_TLS_NEWCTX, most settings TLS settings are not applied. See #55 Signed-off-by: Christian Heimes <cheimes@redhat.com>
1 parent dc7a3fe commit 2522c4f

File tree

15 files changed

+306
-52
lines changed

15 files changed

+306
-52
lines changed

‎Doc/reference/ldap.rst‎

Lines changed: 143 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,154 @@ SASL options
220226
TLS options
221227
:::::::::::
222228

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+
223240
.. py:data:: OPT_X_TLS
224241
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+
225250
.. py:data:: OPT_X_TLS_ALLOW
226251
252+
Value for :py:const:`OPT_X_TLS_REQUIRE_CERT`
253+
227254
.. py:data:: OPT_X_TLS_CACERTDIR
228255
256+
get/set path to directory with CA certs
257+
229258
.. py:data:: OPT_X_TLS_CACERTFILE
230259
260+
get/set path to PEM file with CA certs
261+
231262
.. py:data:: OPT_X_TLS_CERTFILE
232263
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+
233271
.. py:data:: OPT_X_TLS_CIPHER_SUITE
234272
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+
235292
.. py:data:: OPT_X_TLS_CTX
236293
294+
get address of internal memory address of TLS context (**DO NOT USE**)
295+
237296
.. py:data:: OPT_X_TLS_DEMAND
238297
298+
Value for :py:const:`OPT_X_TLS_REQUIRE_CERT`
299+
239300
.. py:data:: OPT_X_TLS_HARD
240301
302+
Value for :py:const:`OPT_X_TLS_REQUIRE_CERT`
303+
241304
.. py:data:: OPT_X_TLS_KEYFILE
242305
306+
get/set path to file with PEM encoded key for client cert authentication,
307+
requires :py:const:`OPT_X_TLS_CERTFILE`.
308+
243309
.. py:data:: OPT_X_TLS_NEVER
244310
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+
245347
.. py:data:: OPT_X_TLS_RANDOM_FILE
246348
349+
get/set path to /dev/urandom (**DO NOT USE**)
350+
247351
.. py:data:: OPT_X_TLS_REQUIRE_CERT
248352
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+
249367
.. py:data:: OPT_X_TLS_TRY
250368
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+
251377
.. _ldap-keepalive-options:
252378

253379
Keepalive options
@@ -564,6 +690,8 @@ The above exceptions are raised when a result code from an underlying API
564690
call does not indicate success.
565691

566692

693+
.. _ldap-warnings:
694+
567695
Warnings
568696
========
569697

@@ -575,6 +703,16 @@ Warnings
575703

576704
.. versionadded:: 3.0.0
577705

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+
578716

579717
.. _ldap-objects:
580718

‎Doc/spelling_wordlist.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ defresult
3939
dereferenced
4040
dereferencing
4141
desc
42+
dev
4243
directoryOperation
4344
distinguished
4445
distributedOperation
@@ -144,6 +145,7 @@ UDP
144145
Umich
145146
unparsing
146147
unsigend
148+
urandom
147149
uri
148150
urlPrefix
149151
urlscheme

‎Lib/ldap/__init__.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -86,7 +86,7 @@ def release(self):
8686

8787
from ldap.functions import open,initialize,init,get_option,set_option,escape_str,strf_secs,strp_secs
8888

89-
from ldap.ldapobject import NO_UNIQUE_ENTRY, LDAPBytesWarning
89+
from ldap.ldapobject import NO_UNIQUE_ENTRY, LDAPBytesWarning, LDAPTLSWarning
9090

9191
from ldap.dn import explode_dn,explode_rdn,str2dn,dn2str
9292
del str2dn

‎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),

‎Lib/ldap/ldapobject.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,8 @@
1414
'LDAPObject',
1515
'SimpleLDAPObject',
1616
'ReconnectLDAPObject',
17-
'LDAPBytesWarning'
17+
'LDAPBytesWarning',
18+
'LDAPTLSWarning',
1819
]
1920

2021

@@ -25,6 +26,7 @@
2526
import sys,time,pprint,_ldap,ldap,ldap.sasl,ldap.functions
2627
import warnings
2728

29+
from _ldap import LDAPTLSWarning
2830
from ldap.schema import SCHEMA_ATTRS
2931
from ldap.controls import LDAPControl,DecodeControlTuples,RequestControlTuples
3032
from ldap.extop import ExtendedRequest,ExtendedResponse

‎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)