Skip to content

Commit e3d82d6

Browse files
tiranencukou
tiran
and
encukou
committed
Improve TLS documentation
See: #55 Signed-off-by: Christian Heimes <cheimes@redhat.com> Co-authored-by: Petr Viktorin <encukou@gmail.com>
1 parent f8f10a9 commit e3d82d6

File tree

5 files changed

+145
-12
lines changed

5 files changed

+145
-12
lines changed

‎Doc/reference/ldap.rst

Lines changed: 138 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,12 @@ This module defines the following functions:
8383
This function sets the value of the global option specified by *option* to
8484
*invalue*.
8585

86+
.. note::
87+
88+
Most global settings do not affect existing :py:class:`LDAPObject`
89+
connections. Applications should call :py:func:`set_option()` before
90+
they establish connections with :py:func:`initialize`.
91+
8692
.. versionchanged:: 3.1
8793

8894
The deprecated functions ``ldap.init()`` and ``ldap.open()`` were removed.
@@ -221,35 +227,158 @@ SASL options
221227
TLS options
222228
:::::::::::
223229

224-
.. py:data:: OPT_X_TLS
230+
.. warning::
231+
232+
libldap does not materialize all TLS settings immediately. You must use
233+
:py:const:`OPT_X_TLS_NEWCTX` with value ``0`` to instruct libldap to
234+
apply pending TLS settings and create a new internal TLS context::
235+
236+
conn = ldap.initialize("ldap://ldap.example")
237+
conn.set_option(ldap.OPT_X_TLS_CACERTFILE, '/path/to/ca.pem')
238+
conn.set_option(ldap.OPT_X_TLS_NEWCTX, 0)
239+
conn.start_tls_s()
240+
conn.simple_bind_s(dn, password)
241+
225242

226243
.. py:data:: OPT_X_TLS_NEWCTX
227244
228-
.. py:data:: OPT_X_TLS_ALLOW
245+
set and apply TLS settings to internal TLS context. Value ``0`` creates
246+
a new client-side context.
247+
248+
.. py:data:: OPT_X_TLS_PACKAGE
249+
250+
Get TLS implementation, known values are
251+
252+
* ``GnuTLS``
253+
* ``MozNSS`` (Mozilla NSS)
254+
* ``OpenSSL``
255+
229256

230257
.. py:data:: OPT_X_TLS_CACERTDIR
231258
259+
get/set path to directory with CA certs
260+
232261
.. py:data:: OPT_X_TLS_CACERTFILE
233262
263+
get/set path to PEM file with CA certs
264+
234265
.. py:data:: OPT_X_TLS_CERTFILE
235266
236-
.. py:data:: OPT_X_TLS_CIPHER_SUITE
267+
get/set path to file with PEM encoded cert for client cert authentication,
268+
requires :py:const:`OPT_X_TLS_KEYFILE`.
237269

238-
.. py:data:: OPT_X_TLS_CTX
270+
.. py:data:: OPT_X_TLS_KEYFILE
271+
272+
get/set path to file with PEM encoded key for client cert authentication,
273+
requires :py:const:`OPT_X_TLS_CERTFILE`.
274+
275+
276+
.. py:data:: OPT_X_TLS_CRLCHECK
277+
278+
get/set certificate revocation list (CRL) check mode. CRL validation
279+
requires :py:const:`OPT_X_TLS_CRLFILE`.
280+
281+
:py:const:`OPT_X_TLS_CRL_NONE`
282+
Don't perform CRL checks
283+
284+
:py:const:`OPT_X_TLS_CRL_PEER`
285+
Perform CRL check for peer's end entity cert.
286+
287+
:py:const:`OPT_X_TLS_CRL_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+
294+
.. py:data:: OPT_X_TLS_CRL_ALL
295+
296+
value for :py:const:`OPT_X_TLS_CRLCHECK`
297+
298+
.. py:data:: OPT_X_TLS_CRL_NONE
299+
300+
value for :py:const:`OPT_X_TLS_CRLCHECK`
301+
302+
.. py:data:: OPT_X_TLS_CRL_PEER
303+
304+
value for :py:const:`OPT_X_TLS_CRLCHECK`
305+
306+
307+
.. py:data:: OPT_X_TLS_REQUIRE_CERT
308+
309+
get/set validation strategy for server cert.
310+
311+
:py:const:`OPT_X_TLS_NEVER`
312+
Don't check server cert and host name
313+
314+
:py:const:`OPT_X_TLS_ALLOW`
315+
Used internally by slapd server.
316+
317+
:py:const:`OPT_X_TLS_DEMAND`
318+
Validate peer cert chain and host name
319+
320+
:py:const:`OPT_X_TLS_HARD`
321+
Same as :py:const:`OPT_X_TLS_DEMAND`
322+
323+
.. py:data:: OPT_X_TLS_ALLOW
324+
325+
Value for :py:const:`OPT_X_TLS_REQUIRE_CERT`
239326

240327
.. py:data:: OPT_X_TLS_DEMAND
241328
329+
Value for :py:const:`OPT_X_TLS_REQUIRE_CERT`
330+
242331
.. py:data:: OPT_X_TLS_HARD
243332
244-
.. py:data:: OPT_X_TLS_KEYFILE
333+
Value for :py:const:`OPT_X_TLS_REQUIRE_CERT`
245334

246335
.. py:data:: OPT_X_TLS_NEVER
247336
337+
Value for :py:const:`OPT_X_TLS_REQUIRE_CERT`
338+
339+
.. py:data:: OPT_X_TLS_TRY
340+
341+
.. deprecated:: 3.3.0
342+
This value is only used by slapd server internally. It will be removed
343+
in the future.
344+
345+
346+
.. py:data:: OPT_X_TLS_CIPHER
347+
348+
get cipher suite name from TLS session
349+
350+
.. py:data:: OPT_X_TLS_CIPHER_SUITE
351+
352+
get/set allowed cipher suites
353+
354+
.. py:data:: OPT_X_TLS_CTX
355+
356+
get address of internal memory address of TLS context (**DO NOT USE**)
357+
358+
.. py:data:: OPT_X_TLS_PEERCERT
359+
360+
Get peer's certificate as binary ASN.1 data structure (not supported)
361+
362+
.. py:data:: OPT_X_TLS_PROTOCOL_MIN
363+
364+
get/set minimum protocol version (wire protocol version as int)
365+
366+
* ``0x303`` for TLS 1.2
367+
* ``0x304`` for TLS 1.3
368+
369+
.. py:data:: OPT_X_TLS_VERSION
370+
371+
Get negotiated TLS protocol version as string
372+
248373
.. py:data:: OPT_X_TLS_RANDOM_FILE
249374
250-
.. py:data:: OPT_X_TLS_REQUIRE_CERT
375+
get/set path to /dev/urandom (**DO NOT USE**)
251376

252-
.. py:data:: OPT_X_TLS_TRY
377+
.. py:data:: OPT_X_TLS
378+
379+
.. deprecated:: 3.3.0
380+
The option is deprecated in OpenLDAP and should no longer be used. It
381+
will be removed in the future.
253382

254383
.. note::
255384

@@ -572,6 +701,8 @@ The above exceptions are raised when a result code from an underlying API
572701
call does not indicate success.
573702

574703

704+
.. _ldap-warnings:
705+
575706
Warnings
576707
========
577708

‎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
@@ -145,6 +146,7 @@ UDP
145146
Umich
146147
unparsing
147148
unsigend
149+
urandom
148150
uri
149151
urlPrefix
150152
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: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,11 @@ AUTOPEP8_OPTS=--aggressive
1212
.PHONY: all
1313
all:
1414

15+
Modules/constants_generated.h: Lib/ldap/constants.py
16+
$(PYTHON) $^ > $@
17+
indent Modules/constants_generated.h
18+
rm -f Modules/constants_generated.h~
19+
1520
.PHONY: clean
1621
clean:
1722
rm -rf build dist *.egg-info .tox MANIFEST

‎Modules/constants_generated.h

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -213,10 +213,6 @@ add_int(OPT_X_TLS_DEMAND);
213213
add_int(OPT_X_TLS_ALLOW);
214214
add_int(OPT_X_TLS_TRY);
215215

216-
#if defined(LDAP_OPT_X_TLS_PEERCERT)
217-
add_int(OPT_X_TLS_PEERCERT);
218-
#endif
219-
220216
#if defined(LDAP_OPT_X_TLS_VERSION)
221217
add_int(OPT_X_TLS_VERSION);
222218
#endif

0 commit comments

Comments
 (0)