Documention for CERT_OPTIONAL is misleading

[tiran]

BPO	31432
Nosy	@tiran, @ned-deily, @alex, @dstufft, @iritkatriel
PRs	bpo-31432: Clarify CERT_NONE/OPTIONAL/REQUIRED doc #3530 [3.7] bpo-31432: Clarify ssl CERT_NONE/OPTIONAL/REQUIRED docs. (GH-3530) #7649 bpo-31432: Revert unrelated code changes to _ssl.c and test_ssl #7650 [3.7] bpo-31432: Revert unrelated code changes to _ssl.c and test_ssl (GH-7650) #7651 [3.6] bpo-31432: Clarify ssl CERT_NONE/OPTIONAL/REQUIRED docs. (GH-3530) #7652

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2020-10-21.16:30:55.361>
created_at = <Date 2017-09-12.16:08:39.644>
labels = ['expert-SSL', 'type-bug', '3.7', 'docs']
title = 'Documention for CERT_OPTIONAL is misleading'
updated_at = <Date 2020-10-21.16:30:55.361>
user = 'https://github.com/tiran'

bugs.python.org fields:

activity = <Date 2020-10-21.16:30:55.361>
actor = 'christian.heimes'
assignee = 'docs@python'
closed = True
closed_date = <Date 2020-10-21.16:30:55.361>
closer = 'christian.heimes'
components = ['Documentation', 'SSL']
creation = <Date 2017-09-12.16:08:39.644>
creator = 'christian.heimes'
dependencies = []
files = []
hgrepos = []
issue_num = 31432
keywords = ['patch']
message_count = 8.0
messages = ['301970', '301976', '319350', '319351', '319352', '319355', '319356', '378272']
nosy_count = 7.0
nosy_names = ['janssen', 'christian.heimes', 'ned.deily', 'alex', 'docs@python', 'dstufft', 'iritkatriel']
pr_nums = ['3530', '7649', '7650', '7651', '7652']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue31432'
versions = ['Python 2.7', 'Python 3.6', 'Python 3.7']

[tiran]

From bpo-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.

[tiran]

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 bpo-31372.

[ned-deily]

New changeset ef24b6c by Ned Deily (Christian Heimes) in branch 'master':
bpo-31432: Clarify ssl CERT_NONE/OPTIONAL/REQUIRED docs. (GH-3530)
ef24b6c

[ned-deily]

New changeset a5db479 by Ned Deily (Miss Islington (bot)) in branch '3.7':
bpo-31432: Clarify ssl CERT_NONE/OPTIONAL/REQUIRED docs. (GH-3530) (GH-7649)
a5db479

[ned-deily]

New changeset 4531ec7 by Ned Deily in branch 'master':
bpo-31432: Revert unrelated code changes to _ssl.c and test_ssl (GH-7650)
4531ec7

[ned-deily]

New changeset 4219857 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)
4219857

[ned-deily]

New changeset e257574 by Ned Deily in branch '3.6':
bpo-31432: Clarify ssl CERT_NONE/OPTIONAL/REQUIRED docs. (GH-3530) (GH-7652)
e257574

[iritkatriel]

This seems complete, can it be closed?