add rsa_generate_private_key function to replace RSAPrivateKey.generate

refs #1026. #1101 is dependent on this

3 files changed, 38 insertions, 18 deletions

diff --git a/cryptography/hazmat/primitives/asymmetric/rsa.py b/cryptography/hazmat/primitives/asymmetric/rsa.py
index 481797fe..94f07902 100644
--- a/cryptography/hazmat/primitives/asymmetric/rsa.py
+++ b/cryptography/hazmat/primitives/asymmetric/rsa.py
@@ -21,6 +21,17 @@ from cryptography.hazmat.backends.interfaces import RSABackend
 from cryptography.hazmat.primitives import interfaces
 
 
+def generate_rsa_private_key(public_exponent, key_size, backend):
+    if not isinstance(backend, RSABackend):
+        raise UnsupportedAlgorithm(
+            "Backend object does not implement RSABackend.",
+            _Reasons.BACKEND_MISSING_INTERFACE
+        )
+
+    _verify_rsa_parameters(public_exponent, key_size)
+    return backend.generate_rsa_private_key(public_exponent, key_size)
+
+
 def _verify_rsa_parameters(public_exponent, key_size):
     if public_exponent < 3:
         raise ValueError("public_exponent must be >= 3.")
diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst
index 54839119..ff9b0a7b 100644
--- a/docs/hazmat/primitives/asymmetric/rsa.rst
+++ b/docs/hazmat/primitives/asymmetric/rsa.rst
@@ -7,13 +7,22 @@ RSA
 
 `RSA`_ is a `public-key`_ algorithm for encrypting and signing messages.
 
+
+.. function:: generate_rsa_private_key(public_exponent, key_size, backend)
+
+    .. versionadded:: 0.5
+
+    Generate a provider of
+    :class:`~cryptography.hazmat.primitives.interfaces.RSAPrivateKey`
+    using ``backend``.
+
 .. class:: RSAPrivateKey(p, q, private_exponent, dmp1, dmq1, iqmp, public_exponent, modulus)
 
     .. versionadded:: 0.2
 
     An RSA private key is required for decryption and signing of messages.
 
-    You should use :meth:`~generate` to generate new keys.
+    You should use :func:`generate_rsa_private_key` to generate new keys.
 
     .. warning::
         This method only checks a limited set of properties of its arguments.
diff --git a/tests/hazmat/primitives/test_rsa.py b/tests/hazmat/primitives/test_rsa.py
index a76c0ec2..730025eb 100644
--- a/tests/hazmat/primitives/test_rsa.py
+++ b/tests/hazmat/primitives/test_rsa.py
@@ -94,32 +94,32 @@ class TestRSA(object):
         )
     )
     def test_generate_rsa_keys(self, backend, public_exponent, key_size):
-        skey = rsa.RSAPrivateKey.generate(public_exponent, key_size, backend)
+        skey = rsa.generate_rsa_private_key(public_exponent, key_size, backend)
         _check_rsa_private_key(skey)
         assert skey.key_size == key_size
         assert skey.public_exponent == public_exponent
 
     def test_generate_bad_public_exponent(self, backend):
         with pytest.raises(ValueError):
-            rsa.RSAPrivateKey.generate(public_exponent=1,
-                                       key_size=2048,
-                                       backend=backend)
+            rsa.generate_rsa_private_key(public_exponent=1,
+                                         key_size=2048,
+                                         backend=backend)
 
         with pytest.raises(ValueError):
-            rsa.RSAPrivateKey.generate(public_exponent=4,
-                                       key_size=2048,
-                                       backend=backend)
+            rsa.generate_rsa_private_key(public_exponent=4,
+                                         key_size=2048,
+                                         backend=backend)
 
     def test_cant_generate_insecure_tiny_key(self, backend):
         with pytest.raises(ValueError):
-            rsa.RSAPrivateKey.generate(public_exponent=65537,
-                                       key_size=511,
-                                       backend=backend)
+            rsa.generate_rsa_private_key(public_exponent=65537,
+                                         key_size=511,
+                                         backend=backend)
 
         with pytest.raises(ValueError):
-            rsa.RSAPrivateKey.generate(public_exponent=65537,
-                                       key_size=256,
-                                       backend=backend)
+            rsa.generate_rsa_private_key(public_exponent=65537,
+                                         key_size=256,
+                                         backend=backend)
 
     @pytest.mark.parametrize(
         "pkcs1_example",
@@ -377,7 +377,7 @@ def test_rsa_generate_invalid_backend():
     pretend_backend = object()
 
     with raises_unsupported_algorithm(_Reasons.BACKEND_MISSING_INTERFACE):
-        rsa.RSAPrivateKey.generate(65537, 2048, pretend_backend)
+        rsa.generate_rsa_private_key(65537, 2048, pretend_backend)
 
 
 @pytest.mark.rsa
@@ -963,7 +963,7 @@ class TestRSAVerification(object):
 
     def test_rsa_verifier_invalid_backend(self, backend):
         pretend_backend = object()
-        private_key = rsa.RSAPrivateKey.generate(65537, 2048, backend)
+        private_key = rsa.generate_rsa_private_key(65537, 2048, backend)
         public_key = private_key.public_key()
 
         with raises_unsupported_algorithm(_Reasons.BACKEND_MISSING_INTERFACE):
@@ -1454,7 +1454,7 @@ class TestRSADecryption(object):
 
     def test_rsa_decrypt_invalid_backend(self, backend):
         pretend_backend = object()
-        private_key = rsa.RSAPrivateKey.generate(65537, 2048, backend)
+        private_key = rsa.generate_rsa_private_key(65537, 2048, backend)
 
         with raises_unsupported_algorithm(_Reasons.BACKEND_MISSING_INTERFACE):
             private_key.decrypt(
@@ -1633,7 +1633,7 @@ class TestRSAEncryption(object):
 
     def test_rsa_encrypt_invalid_backend(self, backend):
         pretend_backend = object()
-        private_key = rsa.RSAPrivateKey.generate(65537, 512, backend)
+        private_key = rsa.generate_rsa_private_key(65537, 512, backend)
         public_key = private_key.public_key()
 
         with raises_unsupported_algorithm(_Reasons.BACKEND_MISSING_INTERFACE):