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

Created on 2017-09-12 16:08 by christian.heimes, last changed 2017-09-13 05:13 by christian.heimes.

Pull Requests
URL Status Linked Edit
PR 3530 open christian.heimes, 2017-09-13 05:13
Messages (2)
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.
History
Date User Action Args
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