PYTHON-1094 - Document how to use TLS securely in 2.x

doc/examples/index.rst

@@ -28,3 +28,4 @@ MongoDB, you can start it like so:
    mod_wsgi
    requests
    tailable
+   tls

doc/examples/tls.rst

@@ -0,0 +1,60 @@
+TLS/SSL and PyMongo 2.x
+=======================
+
+PyMongo supports connecting to MongoDB over TLS/SSL. This guide covers the
+configuration options supported by PyMongo. See `the server documentation
+<http://docs.mongodb.org/manual/tutorial/configure-ssl/>`_ to configure
+MongoDB.
+
+To make a secure TLS connection create
+:class:`~pymongo.mongo_client.MongoClient`
+(or :class:`~pymongo.mongo_replica_set_client.MongoReplicaSetClient`)
+with the following options::
+
+  >>> import ssl
+  >>> client = pymongo.MongoClient('example.com',
+  ...                              ssl=True,
+  ...                              ssl_cert_reqs=ssl.CERT_REQUIRED,
+  ...                              ssl_ca_certs='/path/to/ca.pem')
+
+Or, in the URI::
+
+  >>> uri = 'mongodb://example.com/?ssl=true&ssl_cert_reqs=CERT_REQUIRED&ssl_ca_certs=/path/to/ca.pem'
+  >>> client = pymongo.MongoClient(uri)
+
+To verify server certificates signed by a well known certificate authority, use
+`certifi <https://pypi.python.org/pypi/certifi>`_::
+
+  >>> import certifi
+  >>> import ssl
+  >>> client = pymongo.MongoClient('example.com',
+  ...                              ssl=True,
+  ...                              ssl_cert_reqs=ssl.CERT_REQUIRED,
+  ...                              ssl_ca_certs=certifi.where())
+  >>>
+  >>> uri = 'mongodb://example.com/?ssl=true&ssl_cert_reqs=CERT_REQUIRED&ssl_ca_certs=%s' % (certifi.where(),)
+  >>> client = pymongo.MongoClient(uri)
+
+Client certificates
+...................
+
+PyMongo can be configured to present a client certificate using the
+`ssl_certfile` option::
+
+  >>> client = pymongo.MongoClient('example.com',
+  ...                              ssl=True,
+  ...                              ssl_cert_reqs=ssl.CERT_REQUIRED,
+  ...                              ssl_ca_certs='/path/to/ca.pem',
+  ...                              ssl_certfile='/path/to/client.pem')
+
+If the private key for the client certificate is stored in a separate file use
+the `ssl_keyfile` option::
+
+  >>> client = pymongo.MongoClient('example.com',
+  ...                              ssl=True,
+  ...                              ssl_cert_reqs=ssl.CERT_REQUIRED,
+  ...                              ssl_ca_certs='/path/to/ca.pem',
+  ...                              ssl_certfile='/path/to/client.pem',
+  ...                              ssl_keyfile='/path/to/key.pem')
+
+These options can also be passed as part of the MongoDB URI.

pymongo/connection.py

@@ -168,6 +168,8 @@ class Connection(MongoClient):
 
           | **SSL configuration:**
 
+            See :doc:`/examples/tls` for examples.
+
           - `ssl`: If ``True``, create the connection to the server using SSL.
             Defaults to ``False``.
           - `ssl_keyfile`: The private keyfile used to identify the local

pymongo/mongo_client.py

@@ -207,6 +207,8 @@ class MongoClient(common.BaseObject):
 
           | **SSL configuration:**
 
+            See :doc:`/examples/tls` for examples.
+
           - `ssl`: If ``True``, create the connection to the server using SSL.
             Defaults to ``False``.
           - `ssl_keyfile`: The private keyfile used to identify the local

pymongo/mongo_replica_set_client.py

@@ -548,6 +548,8 @@ class MongoReplicaSetClient(common.BaseObject):
 
           | **SSL configuration:**
 
+            See :doc:`/examples/tls` for examples.
+
           - `ssl`: If ``True``, create the connection to the servers using SSL.
             Defaults to ``False``.
           - `ssl_keyfile`: The private keyfile used to identify the local

pymongo/replica_set_connection.py

@@ -167,6 +167,8 @@ class ReplicaSetConnection(MongoReplicaSetClient):
 
           | **SSL configuration:**
 
+            See :doc:`/examples/tls` for examples.
+
           - `ssl`: If ``True``, create the connection to the servers using SSL.
             Defaults to ``False``.
           - `ssl_keyfile`: The private keyfile used to identify the local