Merge pull request #883 from reaperhulk/deprecation-dance

move salt_length from MGF1 to PSS and start deprecation cycle

3 files changed, 25 insertions, 22 deletions

diff --git a/docs/doing-a-release.rst b/docs/doing-a-release.rst
index 5571e0f3..ad3b4791 100644
--- a/docs/doing-a-release.rst
+++ b/docs/doing-a-release.rst
@@ -49,3 +49,6 @@ Post-release tasks
 * Add new :doc:`/changelog` entry with next version and note that it is under
   active development
 * Send a pull request with these items
+* Check for any outstanding code undergoing a deprecation cycle by looking in
+  ``cryptography.utils`` for ``DeprecatedIn**`` definitions. If any exist open
+  a ticket to increment them for the next release.
diff --git a/docs/hazmat/primitives/asymmetric/padding.rst b/docs/hazmat/primitives/asymmetric/padding.rst
index 2a5de3c7..89af7eaa 100644
--- a/docs/hazmat/primitives/asymmetric/padding.rst
+++ b/docs/hazmat/primitives/asymmetric/padding.rst
@@ -10,10 +10,13 @@ Padding
     correct padding signatures can be forged, messages decrypted, and private
     keys compromised.
 
-.. class:: PSS(mgf)
+.. class:: PSS(mgf, salt_length)
 
     .. versionadded:: 0.3
 
+    .. versionchanged:: 0.4
+        Added ``salt_length`` parameter.
+
     PSS (Probabilistic Signature Scheme) is a signature scheme defined in
     :rfc:`3447`. It is more complex than PKCS1 but possesses a `security proof`_.
     This is the `recommended padding algorithm`_ for RSA signatures.
@@ -21,6 +24,14 @@ Padding
     :param mgf: A mask generation function object. At this time the only
         supported MGF is :class:`MGF1`.
 
+    :param int salt_length: The length of the salt. It is recommended that this
+        be set to ``PSS.MAX_LENGTH``.
+
+    .. attribute:: MAX_LENGTH
+
+        Pass this attribute to ``salt_length`` to get the maximum salt length
+        available.
+
 .. class:: PKCS1v15()
 
     .. versionadded:: 0.3
@@ -31,10 +42,13 @@ Padding
 Mask generation functions
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. class:: MGF1(algorithm, salt_length)
+.. class:: MGF1(algorithm)
 
     .. versionadded:: 0.3
 
+    .. versionchanged:: 0.4
+        Deprecated the ``salt_length`` parameter.
+
     MGF1 (Mask Generation Function 1) is used as the mask generation function
     in :class:`PSS` padding. It takes a hash algorithm and a salt length.
 
@@ -42,14 +56,6 @@ Mask generation functions
         :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`
         provider.
 
-    :param int salt_length: The length of the salt. It is recommended that this
-        be set to ``MGF1.MAX_LENGTH``.
-
-    .. attribute:: MAX_LENGTH
-
-        Pass this attribute to ``salt_length`` to get the maximum salt length
-        available.
-
 
 .. _`Padding is critical`: http://rdist.root.org/2009/10/06/why-rsa-encryption-padding-is-critical/
 .. _`security proof`: http://eprint.iacr.org/2001/062.pdf
diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst
index 5c554abc..5074f1c5 100644
--- a/docs/hazmat/primitives/asymmetric/rsa.rst
+++ b/docs/hazmat/primitives/asymmetric/rsa.rst
@@ -73,10 +73,8 @@ RSA
             ... )
             >>> signer = private_key.signer(
             ...     padding.PSS(
-            ...         mgf=padding.MGF1(
-            ...             algorithm=hashes.SHA256(),
-            ...             salt_length=padding.MGF1.MAX_LENGTH
-            ...         )
+            ...         mgf=padding.MGF1(hashes.SHA256()),
+            ...         salt_length=padding.PSS.MAX_LENGTH
             ...     ),
             ...     hashes.SHA256(),
             ...     default_backend()
@@ -158,10 +156,8 @@ RSA
             ... )
             >>> signer = private_key.signer(
             ...     padding.PSS(
-            ...         mgf=padding.MGF1(
-            ...             algorithm=hashes.SHA256(),
-            ...             salt_length=padding.MGF1.MAX_LENGTH
-            ...         )
+            ...         mgf=padding.MGF1(hashes.SHA256()),
+            ...         salt_length=padding.PSS.MAX_LENGTH
             ...     ),
             ...     hashes.SHA256(),
             ...     default_backend()
@@ -173,10 +169,8 @@ RSA
             >>> verifier = public_key.verifier(
             ...     signature,
             ...     padding.PSS(
-            ...         mgf=padding.MGF1(
-            ...             algorithm=hashes.SHA256(),
-            ...             salt_length=padding.MGF1.MAX_LENGTH
-            ...         )
+            ...         mgf=padding.MGF1(hashes.SHA256()),
+            ...         salt_length=padding.PSS.MAX_LENGTH
             ...     ),
             ...     hashes.SHA256(),
             ...     default_backend()