This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Documention for CERT_OPTIONAL is misleading
Type: behavior Stage: resolved
Components: Documentation, SSL Versions: Python 3.7, Python 3.6, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: alex, christian.heimes, docs@python, dstufft, iritkatriel, janssen, ned.deily
Priority: normal Keywords: patch

Created on 2017-09-12 16:08 by christian.heimes, last changed 2022-04-11 14:58 by admin. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 3530 merged christian.heimes, 2017-09-13 05:13
PR 7649 merged miss-islington, 2018-06-11 23:00
PR 7650 merged ned.deily, 2018-06-12 00:08
PR 7651 merged miss-islington, 2018-06-12 00:27
PR 7652 merged ned.deily, 2018-06-12 01:15
Messages (8)
msg301970 - (view) Author: Christian Heimes (christian.heimes) * (Python committer) Date: 2017-09-12 16:08
From #31431, the documentation of CERT_OPTIONAL and CERT_REQUIRED are misleading. For client side sockets, CERT_OPTIONAL does **NOT** mean that no certificates will be required from the other side of the socket connection. The server **must** provide a cert and the client **requires** the cert to be valid and trusted by trusted CA. 

Internally, the _ssl.c extension module sets:

CERT_NONE: SSL_CTX_set_verify(ctx, SSL_VERIFY_NONE, verify_cb)
CERT_OPTIONAL: SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER, verify_cb)
CERT_REQUIRED: SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER | SSL_VERIFY_FAIL_IF_NO_PEER_CERT, verify_cb)

According to https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_verify.html SSL_VERIFY_FAIL_IF_NO_PEER_CERT is ignored in client mode.

This means for client-side sockets:

CERT_NONE: server must provide any cert, verification error does not prevent handshake
CERT_OPTIONAL == CERT_REQUIRED
CERT_REQUIRED: server must provide a correct certificate that is trusted by a root CA in the trust store of the client


For server-side sockets:

CERT_NONE: Don't ask client for a TLS client auth cert
CERT_OPTIONAL: Ask client for a TLS client auth cert, don't fail if the client does not provide one. IIRC the cert must validate and be trusted by a CA in the trust store of the server (TODO: verify this)
CERT_REQUIRED: Ask client for TLS client auth cert, fail if client does not provide a certificate during the handshake.
msg301976 - (view) Author: Christian Heimes (christian.heimes) * (Python committer) Date: 2017-09-12 16:41
PS: OpenSSL still validates the chain when SSL_VERIFY_NONE is set. In that mode OpenSSL just does not abort the handshake when an error occurs. OpenSSL keeps the last verification error around, see #31372.
msg319350 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2018-06-11 22:59
New changeset ef24b6c54d40e7820456873a6eab6ef57d2bd0db by Ned Deily (Christian Heimes) in branch 'master':
bpo-31432: Clarify ssl CERT_NONE/OPTIONAL/REQUIRED docs. (GH-3530)
https://github.com/python/cpython/commit/ef24b6c54d40e7820456873a6eab6ef57d2bd0db
msg319351 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2018-06-11 23:20
New changeset a5db479ac4cdcc0d94ec1d7a594720a651d90433 by Ned Deily (Miss Islington (bot)) in branch '3.7':
bpo-31432: Clarify ssl CERT_NONE/OPTIONAL/REQUIRED docs. (GH-3530) (GH-7649)
https://github.com/python/cpython/commit/a5db479ac4cdcc0d94ec1d7a594720a651d90433
msg319352 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2018-06-12 00:26
New changeset 4531ec74c4a9c8e15ee2bdec11b12796ce000f6f by Ned Deily in branch 'master':
bpo-31432: Revert unrelated code changes to _ssl.c and test_ssl (GH-7650)
https://github.com/python/cpython/commit/4531ec74c4a9c8e15ee2bdec11b12796ce000f6f
msg319355 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2018-06-12 00:58
New changeset 42198571c586e0dc56836b79329f94952b1975bb by Ned Deily (Miss Islington (bot)) in branch '3.7':
bpo-31432: Revert unrelated code changes to _ssl.c and test_ssl (GH-7650) (GH-7651)
https://github.com/python/cpython/commit/42198571c586e0dc56836b79329f94952b1975bb
msg319356 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2018-06-12 01:45
New changeset e25757408dc22561af9f9589c2c7e2a2fbb66ee4 by Ned Deily in branch '3.6':
bpo-31432: Clarify ssl CERT_NONE/OPTIONAL/REQUIRED docs. (GH-3530) (GH-7652)
https://github.com/python/cpython/commit/e25757408dc22561af9f9589c2c7e2a2fbb66ee4
msg378272 - (view) Author: Irit Katriel (iritkatriel) * (Python committer) Date: 2020-10-08 18:51
This seems complete, can it be closed?
History
Date User Action Args
2022-04-11 14:58:52adminsetgithub: 75613
2020-10-21 16:30:55christian.heimessetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2020-10-08 18:51:56iritkatrielsetnosy: + iritkatriel
messages: + msg378272
2018-06-12 01:45:03ned.deilysetmessages: + msg319356
2018-06-12 01:15:08ned.deilysetpull_requests: + pull_request7271
2018-06-12 00:58:12ned.deilysetmessages: + msg319355
2018-06-12 00:27:47miss-islingtonsetpull_requests: + pull_request7270
2018-06-12 00:26:34ned.deilysetmessages: + msg319352
2018-06-12 00:08:29ned.deilysetpull_requests: + pull_request7269
2018-06-11 23:20:27ned.deilysetmessages: + msg319351
2018-06-11 23:00:09miss-islingtonsetpull_requests: + pull_request7268
2018-06-11 22:59:48ned.deilysetnosy: + ned.deily
messages: + msg319350
2017-09-13 05:13:38christian.heimessetkeywords: + patch
stage: patch review
pull_requests: + pull_request3527
2017-09-12 16:41:44christian.heimessetmessages: + msg301976
2017-09-12 16:08:56christian.heimessetnosy: + janssen, alex, dstufft
2017-09-12 16:08:39christian.heimescreate