From d46bd1671c3fbc246e3a174468eba66826aa1234 Mon Sep 17 00:00:00 2001 From: Bernie Hackett Date: Fri, 21 Feb 2020 09:32:45 -0800 Subject: [PATCH] PYTHON-2093 Documentation for OCSP --- README.rst | 12 +++++++++- doc/atlas.rst | 12 ++++++++-- doc/changelog.rst | 19 ++++++++++++++++ doc/examples/tls.rst | 52 +++++++++++++++++++++++++++++++++++++++----- doc/installation.rst | 12 +++++++++- 5 files changed, 98 insertions(+), 9 deletions(-) diff --git a/README.rst b/README.rst index a1f3664e4..7e4d16b19 100644 --- a/README.rst +++ b/README.rst @@ -113,6 +113,16 @@ PyMongo:: $ python -m pip install pymongo[tls] +.. note:: Users of Python versions older than 2.7.9 will also + receive the dependencies for OCSP when using the tls extra. + +:ref:`OCSP` requires `PyOpenSSL +`_, `requests +`_ and `service_identity +`_:: + + $ python -m pip install pymongo[ocsp] + Wire protocol compression with snappy requires `python-snappy `_:: @@ -126,7 +136,7 @@ Wire protocol compression with zstandard requires `zstandard You can install all dependencies automatically with the following command:: - $ python -m pip install pymongo[snappy,gssapi,srv,tls,zstd] + $ python -m pip install pymongo[gssapi,ocsp,snappy,srv,tls,zstd] Other optional packages: diff --git a/doc/atlas.rst b/doc/atlas.rst index bb661e859..59605b58e 100644 --- a/doc/atlas.rst +++ b/doc/atlas.rst @@ -14,13 +14,21 @@ dependencies using the following pip command:: $ python -m pip install pymongo[tls] +Starting with PyMongo 3.11 this installs `PyOpenSSL +`_, `requests`_ +and `service_identity +`_ +for users of Python versions older than 2.7.9. PyOpenSSL supports SNI for these +old Python versions, allowing applictions to connect to Altas free and shared +tier instances. + Earlier versions of PyMongo require you to manually install the dependencies. For a list of TLS/SSL-related dependencies, see :doc:`examples/tls`. .. note:: Connecting to Atlas "Free Tier" or "Shared Cluster" instances requires Server Name Indication (SNI) support. SNI support requires CPython - 2.7.9 / PyPy 2.5.1 or newer. To check if your version of Python supports - SNI run the following command:: + 2.7.9 / PyPy 2.5.1 or newer or PyMongo 3.11+ with PyOpenSSL. + To check if your version of Python supports SNI run the following command:: $ python -c "import ssl; print(getattr(ssl, 'HAS_SNI', False))" diff --git a/doc/changelog.rst b/doc/changelog.rst index f8ed9f702..8a742e005 100644 --- a/doc/changelog.rst +++ b/doc/changelog.rst @@ -1,6 +1,25 @@ Changelog ========= +Changes in Version 3.11.0 +------------------------- + +Version 3.11 adds support for MongoDB 4.4. Highlights include: + +- Support for :ref:`OCSP` (Online Certificate Status Protocol) +- Support for `PyOpenSSL `_ as an + alternative TLS implementation. PyOpenSSL is required for :ref:`OCSP` + support. It will also be installed when using the "tls" extra if the + version of Python in use is older than 2.7.9. + +Issues Resolved +............... + +See the `PyMongo 3.11.0 release notes in JIRA`_ for the list of resolved issues +in this release. + +.. _PyMongo 3.11.0 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=24799 + Changes in Version 3.10.1 ------------------------- diff --git a/doc/examples/tls.rst b/doc/examples/tls.rst index 4454a1e4b..133c4125d 100644 --- a/doc/examples/tls.rst +++ b/doc/examples/tls.rst @@ -16,6 +16,14 @@ command:: $ python -m pip install pymongo[tls] +Starting with PyMongo 3.11 this installs `PyOpenSSL +`_, `requests`_ +and `service_identity +`_ +for users of Python versions older than 2.7.9. PyOpenSSL supports SNI for these +old Python versions allowing applictions to connect to Altas free and shared +tier instances. + Earlier versions of PyMongo require you to manually install the dependencies listed below. @@ -103,8 +111,9 @@ Specifying a CA file .................... In some cases you may want to configure PyMongo to use a specific set of CA -certificates. This is most often the case when using "self-signed" server -certificates. The `ssl_ca_certs` option takes a path to a CA file. It can be +certificates. This is most often the case when you are acting as your own +certificate authority rather than using server certificates signed by a well +known authority. The `ssl_ca_certs` option takes a path to a CA file. It can be passed as a keyword argument:: >>> client = pymongo.MongoClient('example.com', @@ -132,6 +141,8 @@ Or, in the URI:: >>> uri = 'mongodb://example.com/?ssl=true&ssl_crlfile=/path/to/crl.pem' >>> client = pymongo.MongoClient(uri) +.. note:: Certificate revocation lists and :ref:`OCSP` cannot be used together. + Client certificates ................... @@ -162,12 +173,37 @@ to decrypt encrypted private keys. Use the `ssl_pem_passphrase` option:: These options can also be passed as part of the MongoDB URI. +.. _OCSP: + +OCSP +.... + +Starting with PyMongo 3.11, if PyMongo was installed with the "ocsp" extra:: + + python -m pip install pymongo[ocsp] + +certificate revocation checking is enabled by way of `OCSP (Online Certification +Status Protocol) `_. +MongoDB 4.4+ `staples OCSP responses `_ +to the TLS handshake which PyMongo will verify, failing the TLS handshake if +the stapled OCSP response is invalid or indicates that the peer certificate is +revoked. + +When connecting to a server version older than 4.4, or when a 4.4+ version of +MongoDB does not staple an OCSP response, PyMongo will attempt to connect +directly to an OCSP endpoint if the peer certificate specified one. The TLS +handshake will only fail in this case if the response indicates that the +certificate is revoked. Invalid or malformed responses will be ignored, +favoring availability over maximum security. + + Troubleshooting TLS Errors .......................... -TLS errors often fall into two categories, certificate verification failure or -protocol version mismatch. An error message similar to the following means that -OpenSSL was not able to verify the server's certificate:: +TLS errors often fall into three categories - certificate verification failure, +protocol version mismatch or certificate revocation checking failure. An error +message similar to the following means that OpenSSL was not able to verify the +server's certificate:: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed @@ -200,3 +236,9 @@ TLS protocols be disabled in some MongoDB deployments. Some deployments may disable TLS 1.0, others may disable TLS 1.0 and TLS 1.1. See the warning earlier in this document for troubleshooting steps and solutions. +An error message similar to the following message means that certificate +revocation checking failed:: + + [('SSL routines', 'tls_process_initial_server_flight', 'invalid status response')] + +See :ref:`OCSP` for more details. diff --git a/doc/installation.rst b/doc/installation.rst index ca702b6fb..4875d72aa 100644 --- a/doc/installation.rst +++ b/doc/installation.rst @@ -70,6 +70,16 @@ PyMongo:: $ python -m pip install pymongo[tls] +.. note:: Users of Python versions older than 2.7.9 will also + receive the dependencies for OCSP when using the tls extra. + +:ref:`OCSP` requires `PyOpenSSL +`_, `requests +`_ and `service_identity +`_:: + + $ python -m pip install pymongo[ocsp] + Wire protocol compression with snappy requires `python-snappy `_:: @@ -83,7 +93,7 @@ Wire protocol compression with zstandard requires `zstandard You can install all dependencies automatically with the following command:: - $ python -m pip install pymongo[snappy,gssapi,srv,tls,zstd] + $ python -m pip install pymongo[gssapi,ocsp,snappy,srv,tls,zstd] Other optional packages: