Skip to content

Commit b210bff

Browse files
ShaneHarveyShaneHarvey
authored
PYTHON-2344 Update TLS examples to use unified TLS URI options (#504)
1 parent 7f1644c commit b210bff

File tree

2 files changed

+44
-48
lines changed

2 files changed

+44
-48
lines changed

‎doc/examples/authentication.rst

Lines changed: 14 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -128,29 +128,26 @@ MONGODB-X509
128128

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

135-
>>> import ssl
136135
>>> from pymongo import MongoClient
137136
>>> client = MongoClient('example.com',
138137
... username="<X.509 derived username>"
139138
... authMechanism="MONGODB-X509",
140-
... ssl=True,
141-
... ssl_certfile='/path/to/client.pem',
142-
... ssl_cert_reqs=ssl.CERT_REQUIRED,
143-
... ssl_ca_certs='/path/to/ca.pem')
139+
... tls=True,
140+
... tlsCertificateKeyFile='/path/to/client.pem',
141+
... tlsCAFile='/path/to/ca.pem')
144142

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

148146
>>> uri = "mongodb://<X.509 derived username>@example.com/?authMechanism=MONGODB-X509"
149147
>>> client = MongoClient(uri,
150-
... ssl=True,
151-
... ssl_certfile='/path/to/client.pem',
152-
... ssl_cert_reqs=ssl.CERT_REQUIRED,
153-
... ssl_ca_certs='/path/to/ca.pem')
148+
... tls=True,
149+
... tlsCertificateKeyFile='/path/to/client.pem',
150+
... tlsCAFile='/path/to/ca.pem')
154151
>>>
155152

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

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

248-
>>> import ssl
249245
>>> from pymongo import MongoClient
250246
>>> uri = "mongodb://user:[email protected]/?authMechanism=PLAIN"
251247
>>> client = MongoClient(uri,
252-
... ssl=True,
253-
... ssl_certfile='/path/to/client.pem',
254-
... ssl_cert_reqs=ssl.CERT_REQUIRED,
255-
... ssl_ca_certs='/path/to/ca.pem')
248+
... tls=True,
249+
... tlsCertificateKeyFile='/path/to/client.pem',
250+
... tlsCAFile='/path/to/ca.pem')
256251
>>>
257252

258253
.. _MONGODB-AWS:

‎doc/examples/tls.rst

Lines changed: 30 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -77,14 +77,14 @@ Basic configuration
7777
...................
7878

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

83-
>>> client = pymongo.MongoClient('example.com', ssl=True)
83+
>>> client = pymongo.MongoClient('example.com', tls=True)
8484

85-
Or passing ``ssl=true`` in the URI::
85+
Or passing ``tls=true`` in the URI::
8686

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

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

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

100-
>>> import ssl
101101
>>> client = pymongo.MongoClient('example.com',
102-
... ssl=True,
103-
... ssl_cert_reqs=ssl.CERT_NONE)
102+
... tls=True,
103+
... tlsAllowInvalidCertificates=True)
104104

105105
Or, in the URI::
106106

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

110110
Specifying a CA file
@@ -113,32 +113,32 @@ Specifying a CA file
113113
In some cases you may want to configure PyMongo to use a specific set of CA
114114
certificates. This is most often the case when you are acting as your own
115115
certificate authority rather than using server certificates signed by a well
116-
known authority. The `ssl_ca_certs` option takes a path to a CA file. It can be
116+
known authority. The ``tlsCAFile`` option takes a path to a CA file. It can be
117117
passed as a keyword argument::
118118

119119
>>> client = pymongo.MongoClient('example.com',
120-
... ssl=True,
121-
... ssl_ca_certs='/path/to/ca.pem')
120+
... tls=True,
121+
... tlsCAFile='/path/to/ca.pem')
122122

123123
Or, in the URI::
124124

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

128128
Specifying a certificate revocation list
129129
........................................
130130

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

135135
>>> client = pymongo.MongoClient('example.com',
136-
... ssl=True,
137-
... ssl_crlfile='/path/to/crl.pem')
136+
... tls=True,
137+
... tlsCRLFile='/path/to/crl.pem')
138138

139139
Or, in the URI::
140140

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

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

149149
PyMongo can be configured to present a client certificate using the
150-
`ssl_certfile` option::
150+
``tlsCertificateKeyFile`` option::
151151

152152
>>> client = pymongo.MongoClient('example.com',
153-
... ssl=True,
154-
... ssl_certfile='/path/to/client.pem')
153+
... tls=True,
154+
... tlsCertificateKeyFile='/path/to/client.pem')
155155

156156
If the private key for the client certificate is stored in a separate file use
157-
the `ssl_keyfile` option::
157+
the ``ssl_keyfile`` option::
158158

159159
>>> client = pymongo.MongoClient('example.com',
160-
... ssl=True,
161-
... ssl_certfile='/path/to/client.pem',
160+
... tls=True,
161+
... tlsCertificateKeyFile='/path/to/client.pem',
162162
... ssl_keyfile='/path/to/key.pem')
163163

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

167168
>>> client = pymongo.MongoClient('example.com',
168-
... ssl=True,
169-
... ssl_certfile='/path/to/client.pem',
169+
... tls=True,
170+
... tlsCertificateKeyFile='/path/to/client.pem',
170171
... ssl_keyfile='/path/to/key.pem',
171-
... ssl_pem_passphrase=<passphrase>)
172+
... tlsCertificateKeyFilePassword=<passphrase>)
172173

173174

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

0 commit comments

Comments
 (0)