PYTHON-2396 Deprecate ssl_keyfile and ssl_certfile URI options (#616)

(cherry picked from commit 6e1009e)

Author: prashantmital

doc/examples/tls.rst

@@ -153,25 +153,31 @@ PyMongo can be configured to present a client certificate using the
   ...                              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::
+If the private key for the client certificate is stored in a separate file,
+it should be concatenated with the certificate file. For example, to
+concatenate a PEM-formatted certificate file ``cert.pem`` and a PEM-formatted
+keyfile ``key.pem`` into a single file ``combined.pem``, on Unix systems,
+users can run::
+
+  $ cat key.pem cert.pem > combined.pem
+
+PyMongo can be configured with the concatenated certificate keyfile using the
+``tlsCertificateKeyFile`` option::
 
   >>> client = pymongo.MongoClient('example.com',
   ...                              tls=True,
-  ...                              tlsCertificateKeyFile='/path/to/client.pem',
-  ...                              ssl_keyfile='/path/to/key.pem')
+  ...                              tlsCertificateKeyFile='/path/to/combined.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 ``tlsCertificateKeyFilePassword``
-option::
+If the private key contained in the certificate keyfile is encrypted,
+Python 2.7.9+ (pypy 2.5.1+) and 3.3+ support providing a password or
+passphrase to decrypt the encrypted private key. The password/passphrase
+can be specified using the ``tlsCertificateKeyFilePassword`` option::
 
   >>> client = pymongo.MongoClient('example.com',
   ...                              tls=True,
-  ...                              tlsCertificateKeyFile='/path/to/client.pem',
-  ...                              ssl_keyfile='/path/to/key.pem',
+  ...                              tlsCertificateKeyFile='/path/to/combined.pem',
   ...                              tlsCertificateKeyFilePassword=<passphrase>)
 
-
 These options can also be passed as part of the MongoDB URI.
 
 .. _OCSP:

pymongo/common.py

@@ -711,6 +711,14 @@ def validate_tzinfo(dummy, value):
     'ssl_match_hostname': ('renamed', 'tlsAllowInvalidHostnames'),
     'ssl_crlfile': ('renamed', 'tlsCRLFile'),
     'ssl_ca_certs': ('renamed', 'tlsCAFile'),
+    'ssl_certfile': ('removed', (
+        'Instead of using ssl_certfile to specify the certificate file, '
+        'use tlsCertificateKeyFile to pass a single file containing both '
+        'the client certificate and the private key')),
+    'ssl_keyfile': ('removed', (
+        'Instead of using ssl_keyfile to specify the private keyfile, '
+        'use tlsCertificateKeyFile to pass a single file containing both '
+        'the client certificate and the private key')),
     'ssl_pem_passphrase': ('renamed', 'tlsCertificateKeyFilePassword'),
     'waitqueuemultiple': ('removed', (
         'Instead of using waitQueueMultiple to bound queuing, limit the size '

pymongo/mongo_client.py

@@ -458,28 +458,18 @@ def __init__(
             certificates passed from the other end of the connection.
             Implies ``tls=True``. Defaults to ``None``.
           - `tlsCertificateKeyFile`: A file containing the client certificate
-            and private key. If you want to pass the certificate and private
-            key as separate files, use the ``ssl_certfile`` and ``ssl_keyfile``
-            options instead. Implies ``tls=True``. Defaults to ``None``.
+            and private key. Implies ``tls=True``. Defaults to ``None``.
           - `tlsCRLFile`: A file containing a PEM or DER formatted
             certificate revocation list. Only supported by python 2.7.9+
             (pypy 2.5.1+). Implies ``tls=True``. Defaults to ``None``.
           - `tlsCertificateKeyFilePassword`: The password or passphrase for
-            decrypting the private key in ``tlsCertificateKeyFile`` or
-            ``ssl_keyfile``. Only necessary if the private key is encrypted.
-            Only supported by python 2.7.9+ (pypy 2.5.1+) and 3.3+. Defaults
-            to ``None``.
+            decrypting the private key in ``tlsCertificateKeyFile``. Only
+            necessary if the private key is encrypted. Only supported by
+            python 2.7.9+ (pypy 2.5.1+) and 3.3+. Defaults to ``None``.
           - `tlsDisableOCSPEndpointCheck`: (boolean) If ``True``, disables
             certificate revocation status checking via the OCSP responder
             specified on the server certificate. Defaults to ``False``.
           - `ssl`: (boolean) Alias for ``tls``.
-          - `ssl_certfile`: The certificate file used to identify the local
-            connection against mongod. Implies ``tls=True``. Defaults to
-            ``None``.
-          - `ssl_keyfile`: The private keyfile used to identify the local
-            connection against mongod. Can be omitted if the keyfile is
-            included with the ``tlsCertificateKeyFile``. Implies ``tls=True``.
-            Defaults to ``None``.
 
           | **Read Concern options:**
           | (If not set explicitly, this will use the server default)
@@ -520,6 +510,10 @@ def __init__(
 
         .. versionchanged:: 3.12
            Added the ``server_api`` keyword argument.
+           The following keyword arguments were deprecated:
+
+             - ``ssl_certfile`` and ``ssl_keyfile`` were deprecated in favor
+               of ``tlsCertificateKeyFile``.
 
         .. versionchanged:: 3.11
            Added the following keyword arguments and URI options:

test/test_ssl.py

@@ -42,6 +42,7 @@
 from test.utils import (EventListener,
                         cat_files,
                         connected,
+                        ignore_deprecations,
                         remove_all_users)
 
 
@@ -99,6 +100,7 @@ def test_no_ssl_module(self):
                           MongoClient, ssl_certfile=CLIENT_PEM)
 
     @unittest.skipUnless(HAVE_SSL, "The ssl module is not available.")
+    @ignore_deprecations
     def test_config_ssl(self):
         # Tests various ssl configurations
         self.assertRaises(ValueError, MongoClient, ssl='foo')
@@ -202,6 +204,7 @@ def test_simple_ssl(self):
         self.assertClientWorks(self.client)
 
     @client_context.require_ssl_certfile
+    @ignore_deprecations
     def test_ssl_pem_passphrase(self):
         # Expects the server to be running with server.pem and ca.pem
         #
@@ -234,6 +237,7 @@ def test_ssl_pem_passphrase(self):
 
     @client_context.require_ssl_certfile
     @client_context.require_no_auth
+    @ignore_deprecations
     def test_cert_ssl_implicitly_set(self):
         # Expects the server to be running with server.pem and ca.pem
         #
@@ -257,6 +261,7 @@ def test_cert_ssl_implicitly_set(self):
 
     @client_context.require_ssl_certfile
     @client_context.require_no_auth
+    @ignore_deprecations
     def test_cert_ssl_validation(self):
         # Expects the server to be running with server.pem and ca.pem
         #
@@ -294,6 +299,7 @@ def test_cert_ssl_validation(self):
 
     @client_context.require_ssl_certfile
     @client_context.require_no_auth
+    @ignore_deprecations
     def test_cert_ssl_uri_support(self):
         # Expects the server to be running with server.pem and ca.pem
         #
@@ -307,6 +313,7 @@ def test_cert_ssl_uri_support(self):
 
     @client_context.require_ssl_certfile
     @client_context.require_no_auth
+    @ignore_deprecations
     def test_cert_ssl_validation_optional(self):
         # Expects the server to be running with server.pem and ca.pem
         #
@@ -337,6 +344,7 @@ def test_cert_ssl_validation_optional(self):
 
     @client_context.require_ssl_certfile
     @client_context.require_server_resolvable
+    @ignore_deprecations
     def test_cert_ssl_validation_hostname_matching(self):
         # Expects the server to be running with server.pem and ca.pem
         #
@@ -404,6 +412,7 @@ def test_cert_ssl_validation_hostname_matching(self):
                                   **self.credentials))
 
     @client_context.require_ssl_certfile
+    @ignore_deprecations
     def test_ssl_crlfile_support(self):
         if not hasattr(ssl, 'VERIFY_CRL_CHECK_LEAF') or _ssl.IS_PYOPENSSL:
             self.assertRaises(
@@ -442,6 +451,7 @@ def test_ssl_crlfile_support(self):
 
     @client_context.require_ssl_certfile
     @client_context.require_server_resolvable
+    @ignore_deprecations
     def test_validation_with_system_ca_certs(self):
         # Expects the server to be running with server.pem and ca.pem.
         #
@@ -559,6 +569,7 @@ def test_wincertstore(self):
 
     @client_context.require_auth
     @client_context.require_ssl_certfile
+    @ignore_deprecations
     def test_mongodb_x509_auth(self):
         host, port = client_context.host, client_context.port
         ssl_client = MongoClient(
@@ -667,6 +678,7 @@ def test_mongodb_x509_auth(self):
             self.fail("Invalid certificate accepted.")
 
     @client_context.require_ssl_certfile
+    @ignore_deprecations
     def test_connect_with_ca_bundle(self):
         def remove(path):
             try: