Merge pull request #1592 from public/move-rsa-interfaces

Move RSA*Key interfaces to cryptography.hazmat.primitives.asymmetric.rsa
pyca · Jan 25, 2015 · efec065 · efec065
2 parents b9690ab + f79c231
commit efec065
Show file tree

Hide file tree

Showing 8 changed files with 260 additions and 203 deletions.
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -18,6 +18,12 @@ Changelog
   :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKeyWithNumbers`
   were moved from :mod:`~cryptography.hazmat.primitives.interfaces` to
   :mod:`~cryptography.hazmat.primitives.asymmetric.dsa`
+* :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey`,
+  :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKeyWithNumbers`,
+  :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey` and
+  :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKeyWithNumbers`
+  were moved from :mod:`~cryptography.hazmat.primitives.interfaces` to
+  :mod:`~cryptography.hazmat.primitives.asymmetric.rsa`.
 
 0.7.2 - 2015-01-16
 ~~~~~~~~~~~~~~~~~~

diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst
@@ -234,7 +234,7 @@ A specific ``backend`` may provide one or more of these interfaces.
             at least 2048.
 
         :return: A new instance of a
-            :class:`~cryptography.hazmat.primitives.interfaces.RSAPrivateKey`
+            :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey`
             provider.
 
         :raises ValueError: If the public_exponent is not valid.
@@ -265,7 +265,7 @@ A specific ``backend`` may provide one or more of these interfaces.
             :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateNumbers`.
 
         :returns: A provider of
-            :class:`~cryptography.hazmat.primitives.interfaces.RSAPrivateKey`.
+            :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey`.
 
         :raises ValueError: This is raised when the values of ``p``, ``q``,
             ``private_exponent``, ``public_exponent``, or ``modulus`` do not
@@ -280,7 +280,7 @@ A specific ``backend`` may provide one or more of these interfaces.
             :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateNumbers`.
 
         :returns: A provider of
-            :class:`~cryptography.hazmat.primitives.interfaces.RSAPublicKey`.
+            :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey`.
 
         :raises ValueError: This is raised when the values of
             ``public_exponent`` or ``modulus`` do not match the bounds

diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst
@@ -38,14 +38,17 @@ mathematical properties`_.
     :param int public_exponent: The public exponent of the new key.
         Usually one of the small Fermat primes 3, 5, 17, 257, 65537. If in
         doubt you should `use 65537`_.
+
     :param int key_size: The length of the modulus in bits. For keys
         generated in 2015 it is strongly recommended to be
         `at least 2048`_ (See page 41). It must not be less than 512.
         Some backends may have additional limitations.
+
     :param backend: A backend which provides
         :class:`~cryptography.hazmat.backends.interfaces.RSABackend`.
+
     :return: An instance of
-        :class:`~cryptography.hazmat.primitives.interfaces.RSAPrivateKey`.
+        :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey`.
 
     :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if
         the provided ``backend`` does not implement
@@ -286,7 +289,7 @@ is unavailable.
             provider.
 
         :returns: A new instance of a
-            :class:`~cryptography.hazmat.primitives.interfaces.RSAPublicKey`
+            :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey`
             provider.
 
 .. class:: RSAPrivateNumbers(p, q, d, dmp1, dmq1, iqmp, public_numbers)
@@ -355,7 +358,7 @@ is unavailable.
             provider.
 
         :returns: A
-            :class:`~cryptography.hazmat.primitives.interfaces.RSAPrivateKey`
+            :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey`
             provider.
 
 Handling partial RSA private keys
@@ -406,6 +409,140 @@ this without having to do the math themselves.
     :return: A tuple ``(p, q)``
 
 
+Key interfaces
+~~~~~~~~~~~~~~
+
+.. class:: RSAPrivateKey
+
+    .. versionadded:: 0.2
+
+    An `RSA`_ private key.
+
+    .. method:: signer(padding, algorithm)
+
+        .. versionadded:: 0.3
+
+        Sign data which can be verified later by others using the public key.
+
+        :param padding: An instance of a
+            :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding`
+            provider.
+
+        :param algorithm: An instance of a
+            :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`
+            provider.
+
+        :returns:
+            :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignatureContext`
+
+    .. method:: decrypt(ciphertext, padding)
+
+        .. versionadded:: 0.4
+
+        Decrypt data that was encrypted with the public key.
+
+        :param bytes ciphertext: The ciphertext to decrypt.
+
+        :param padding: An instance of an
+            :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding`
+            provider.
+
+        :return bytes: Decrypted data.
+
+    .. method:: public_key()
+
+        :return: :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey`
+
+        An RSA public key object corresponding to the values of the private key.
+
+    .. attribute:: key_size
+
+        :type: int
+
+        The bit length of the modulus.
+
+
+.. class:: RSAPrivateKeyWithNumbers
+
+    .. versionadded:: 0.5
+
+    Extends :class:`RSAPrivateKey`.
+
+    .. method:: private_numbers()
+
+        Create a
+        :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateNumbers`
+        object.
+
+        :returns: An
+            :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateNumbers`
+            instance.
+
+
+.. class:: RSAPublicKey
+
+    .. versionadded:: 0.2
+
+    An `RSA`_ public key.
+
+    .. method:: verifier(signature, padding, algorithm)
+
+        .. versionadded:: 0.3
+
+        Verify data was signed by the private key associated with this public
+        key.
+
+        :param bytes signature: The signature to verify.
+
+        :param padding: An instance of a
+            :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding`
+            provider.
+
+        :param algorithm: An instance of a
+            :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`
+            provider.
+
+        :returns:
+            :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricVerificationContext`
+
+    .. method:: encrypt(plaintext, padding)
+
+        .. versionadded:: 0.4
+
+        Encrypt data with the public key.
+
+        :param bytes plaintext: The plaintext to encrypt.
+
+        :param padding: An instance of a
+            :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding`
+            provider.
+
+        :return bytes: Encrypted data.
+
+    .. attribute:: key_size
+
+        :type: int
+
+        The bit length of the modulus.
+
+
+.. class:: RSAPublicKeyWithNumbers
+
+    .. versionadded:: 0.5
+
+    Extends :class:`RSAPublicKey`.
+
+    .. method:: public_numbers()
+
+        Create a
+        :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicNumbers`
+        object.
+
+        :returns: An
+            :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicNumbers`
+            instance.
+
+
 .. _`RSA`: https://en.wikipedia.org/wiki/RSA_(cryptosystem)
 .. _`public-key`: https://en.wikipedia.org/wiki/Public-key_cryptography
 .. _`specific mathematical properties`: https://en.wikipedia.org/wiki/RSA_(cryptosystem)#Key_generation

diff --git a/docs/hazmat/primitives/asymmetric/serialization.rst b/docs/hazmat/primitives/asymmetric/serialization.rst
@@ -44,10 +44,10 @@ methods.
     .. doctest::
 
         >>> from cryptography.hazmat.backends import default_backend
-        >>> from cryptography.hazmat.primitives import interfaces
+        >>> from cryptography.hazmat.primitives.asymmetric import rsa
         >>> from cryptography.hazmat.primitives.serialization import load_pem_private_key
         >>> key = load_pem_private_key(pem_data, password=None, backend=default_backend())
-        >>> if isinstance(key, interfaces.RSAPrivateKey):
+        >>> if isinstance(key, rsa.RSAPrivateKey):
         ...     signature = sign_with_rsa_key(key, message)
         ... elif isinstance(key, interfaces.DSAPrivateKey):
         ...     signature = sign_with_dsa_key(key, message)

diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst
@@ -143,135 +143,8 @@ Asymmetric interfaces
 RSA
 ~~~
 
-.. class:: RSAPrivateKey
-
-    .. versionadded:: 0.2
-
-    An `RSA`_ private key.
-
-    .. method:: signer(padding, algorithm)
-
-        .. versionadded:: 0.3
-
-        Sign data which can be verified later by others using the public key.
-
-        :param padding: An instance of a
-            :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding`
-            provider.
-
-        :param algorithm: An instance of a
-            :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`
-            provider.
-
-        :returns:
-            :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignatureContext`
-
-    .. method:: decrypt(ciphertext, padding)
-
-        .. versionadded:: 0.4
-
-        Decrypt data that was encrypted with the public key.
-
-        :param bytes ciphertext: The ciphertext to decrypt.
-
-        :param padding: An instance of an
-            :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding`
-            provider.
-
-        :return bytes: Decrypted data.
-
-    .. method:: public_key()
-
-        :return: :class:`~cryptography.hazmat.primitives.interfaces.RSAPublicKey`
-
-        An RSA public key object corresponding to the values of the private key.
-
-    .. attribute:: key_size
-
-        :type: int
-
-        The bit length of the modulus.
-
-.. class:: RSAPrivateKeyWithNumbers
-
-    .. versionadded:: 0.5
-
-    Extends :class:`RSAPrivateKey`.
-
-    .. method:: private_numbers()
-
-        Create a
-        :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateNumbers`
-        object.
-
-        :returns: An
-            :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateNumbers`
-            instance.
-
-
-.. class:: RSAPublicKey
-
-    .. versionadded:: 0.2
-
-    An `RSA`_ public key.
-
-    .. method:: verifier(signature, padding, algorithm)
-
-        .. versionadded:: 0.3
-
-        Verify data was signed by the private key associated with this public
-        key.
-
-        :param bytes signature: The signature to verify.
-
-        :param padding: An instance of a
-            :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding`
-            provider.
-
-        :param algorithm: An instance of a
-            :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`
-            provider.
-
-        :returns:
-            :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricVerificationContext`
-
-    .. method:: encrypt(plaintext, padding)
-
-        .. versionadded:: 0.4
-
-        Encrypt data with the public key.
-
-        :param bytes plaintext: The plaintext to encrypt.
-
-        :param padding: An instance of a
-            :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding`
-            provider.
-
-        :return bytes: Encrypted data.
-
-    .. attribute:: key_size
-
-        :type: int
-
-        The bit length of the modulus.
-
-
-.. class:: RSAPublicKeyWithNumbers
-
-    .. versionadded:: 0.5
-
-    Extends :class:`RSAPublicKey`.
-
-    .. method:: public_numbers()
-
-        Create a
-        :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicNumbers`
-        object.
-
-        :returns: An
-            :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicNumbers`
-            instance.
-
+In 0.8 the RSA key interfaces were moved to the
+:mod:`cryptography.hazmat.primitives.asymmetric.rsa` module.
 
 .. class:: EllipticCurve
 

diff --git a/docs/x509.rst b/docs/x509.rst
@@ -129,17 +129,17 @@ X.509 Certificate Object
     .. method:: public_key()
 
         :type:
-            :class:`~cryptography.hazmat.primitives.interfaces.RSAPublicKey` or
+            :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey` or
             :class:`~cryptography.hazmat.primitives.interfaces.DSAPublicKey` or
             :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurvePublicKey`
 
         The public key associated with the certificate.
 
         .. doctest::
 
-            >>> from cryptography.hazmat.primitives import interfaces
+            >>> from cryptography.hazmat.primitives.asymmetric import rsa
             >>> public_key = cert.public_key()
-            >>> isinstance(public_key, interfaces.RSAPublicKey)
+            >>> isinstance(public_key, rsa.RSAPublicKey)
             True
 
     .. attribute:: not_valid_before