Skip to content

PYTHON-2344 Update TLS examples to use unified TLS URI options #504

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 19, 2020
Merged

PYTHON-2344 Update TLS examples to use unified TLS URI options #504

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 14 additions & 19 deletions doc/examples/authentication.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -128,29 +128,26 @@ MONGODB-X509

The MONGODB-X509 mechanism authenticates a username derived from the
distinguished subject name of the X.509 certificate presented by the driver
during SSL negotiation. This authentication method requires the use of SSL
connections with certificate validation and is available in MongoDB 2.6
and newer::
during TLS/SSL negotiation. This authentication method requires the use of
TLS/SSL connections with certificate validation and is available in
MongoDB 2.6 and newer::

>>> import ssl
>>> from pymongo import MongoClient
>>> client = MongoClient('example.com',
... username="<X.509 derived username>"
... authMechanism="MONGODB-X509",
... ssl=True,
... ssl_certfile='/path/to/client.pem',
... ssl_cert_reqs=ssl.CERT_REQUIRED,
... ssl_ca_certs='/path/to/ca.pem')
... tls=True,
... tlsCertificateKeyFile='/path/to/client.pem',
... tlsCAFile='/path/to/ca.pem')

MONGODB-X509 authenticates against the $external virtual database, so you
do not have to specify a database in the URI::

>>> uri = "mongodb://<X.509 derived username>@example.com/?authMechanism=MONGODB-X509"
>>> client = MongoClient(uri,
... ssl=True,
... ssl_certfile='/path/to/client.pem',
... ssl_cert_reqs=ssl.CERT_REQUIRED,
... ssl_ca_certs='/path/to/ca.pem')
... tls=True,
... tlsCertificateKeyFile='/path/to/client.pem',
... tlsCAFile='/path/to/ca.pem')
>>>

.. versionchanged:: 3.4
Expand Down Expand Up @@ -242,17 +239,15 @@ These examples use the $external virtual database for LDAP support::
>>>

SASL PLAIN is a clear-text authentication mechanism. We **strongly** recommend
that you connect to MongoDB using SSL with certificate validation when using
the SASL PLAIN mechanism::
that you connect to MongoDB using TLS/SSL with certificate validation when
using the SASL PLAIN mechanism::

>>> import ssl
>>> from pymongo import MongoClient
>>> uri = "mongodb://user:[email protected]/?authMechanism=PLAIN"
>>> client = MongoClient(uri,
... ssl=True,
... ssl_certfile='/path/to/client.pem',
... ssl_cert_reqs=ssl.CERT_REQUIRED,
... ssl_ca_certs='/path/to/ca.pem')
... tls=True,
... tlsCertificateKeyFile='/path/to/client.pem',
... tlsCAFile='/path/to/ca.pem')
>>>

.. _MONGODB-AWS:
Expand Down
59 changes: 30 additions & 29 deletions doc/examples/tls.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,14 +77,14 @@ Basic configuration
...................

In many cases connecting to MongoDB over TLS/SSL requires nothing more than
passing ``ssl=True`` as a keyword argument to
passing ``tls=True`` as a keyword argument to
:class:`~pymongo.mongo_client.MongoClient`::

>>> client = pymongo.MongoClient('example.com', ssl=True)
>>> client = pymongo.MongoClient('example.com', tls=True)

Or passing ``ssl=true`` in the URI::
Or passing ``tls=true`` in the URI::

>>> client = pymongo.MongoClient('mongodb://example.com/?ssl=true')
>>> client = pymongo.MongoClient('mongodb://example.com/?tls=true')

This configures PyMongo to connect to the server using TLS, verify the server's
certificate and verify that the host you are attempting to connect to is listed
Expand All @@ -94,17 +94,17 @@ Certificate verification policy
...............................

By default, PyMongo is configured to require a certificate from the server when
TLS is enabled. This is configurable using the `ssl_cert_reqs` option. To
disable this requirement pass ``ssl.CERT_NONE`` as a keyword parameter::
TLS is enabled. This is configurable using the ``tlsAllowInvalidCertificates``
option. To disable this requirement pass ``tlsAllowInvalidCertificates=True``
as a keyword parameter::

>>> import ssl
>>> client = pymongo.MongoClient('example.com',
... ssl=True,
... ssl_cert_reqs=ssl.CERT_NONE)
... tls=True,
... tlsAllowInvalidCertificates=True)

Or, in the URI::

>>> uri = 'mongodb://example.com/?ssl=true&ssl_cert_reqs=CERT_NONE'
>>> uri = 'mongodb://example.com/?tls=true&tlsAllowInvalidCertificates=true'
>>> client = pymongo.MongoClient(uri)

Specifying a CA file
Expand All @@ -113,32 +113,32 @@ 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 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
known authority. The ``tlsCAFile`` option takes a path to a CA file. It can be
passed as a keyword argument::

>>> client = pymongo.MongoClient('example.com',
... ssl=True,
... ssl_ca_certs='/path/to/ca.pem')
... tls=True,
... tlsCAFile='/path/to/ca.pem')

Or, in the URI::

>>> uri = 'mongodb://example.com/?ssl=true&ssl_ca_certs=/path/to/ca.pem'
>>> uri = 'mongodb://example.com/?tls=true&tlsCAFile=/path/to/ca.pem'
>>> client = pymongo.MongoClient(uri)

Specifying a certificate revocation list
........................................

Python 2.7.9+ (pypy 2.5.1+) and 3.4+ provide support for certificate revocation
lists. The `ssl_crlfile` option takes a path to a CRL file. It can be passed as
a keyword argument::
lists. The ``tlsCRLFile`` option takes a path to a CRL file. It can be passed
as a keyword argument::

>>> client = pymongo.MongoClient('example.com',
... ssl=True,
... ssl_crlfile='/path/to/crl.pem')
... tls=True,
... tlsCRLFile='/path/to/crl.pem')

Or, in the URI::

>>> uri = 'mongodb://example.com/?ssl=true&ssl_crlfile=/path/to/crl.pem'
>>> uri = 'mongodb://example.com/?tls=true&tlsCRLFile=/path/to/crl.pem'
>>> client = pymongo.MongoClient(uri)

.. note:: Certificate revocation lists and :ref:`OCSP` cannot be used together.
Expand All @@ -147,28 +147,29 @@ Client certificates
...................

PyMongo can be configured to present a client certificate using the
`ssl_certfile` option::
``tlsCertificateKeyFile`` option::

>>> client = pymongo.MongoClient('example.com',
... ssl=True,
... ssl_certfile='/path/to/client.pem')
... tls=True,
... tlsCertificateKeyFile='/path/to/client.pem')

If the private key for the client certificate is stored in a separate file use
the `ssl_keyfile` option::
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've kept in ssl_keyfile because we currently still support it. https://jira.mongodb.org/browse/PYTHON-2396 will figure out if we want to remove it in PyMongo 4.0.

the ``ssl_keyfile`` option::

>>> client = pymongo.MongoClient('example.com',
... ssl=True,
... ssl_certfile='/path/to/client.pem',
... tls=True,
... tlsCertificateKeyFile='/path/to/client.pem',
... ssl_keyfile='/path/to/key.pem')

Python 2.7.9+ (pypy 2.5.1+) and 3.3+ support providing a password or passphrase
to decrypt encrypted private keys. Use the `ssl_pem_passphrase` option::
to decrypt encrypted private keys. Use the ``tlsCertificateKeyFilePassword``
option::

>>> client = pymongo.MongoClient('example.com',
... ssl=True,
... ssl_certfile='/path/to/client.pem',
... tls=True,
... tlsCertificateKeyFile='/path/to/client.pem',
... ssl_keyfile='/path/to/key.pem',
... ssl_pem_passphrase=<passphrase>)
... tlsCertificateKeyFilePassword=<passphrase>)


These options can also be passed as part of the MongoDB URI.
Expand Down