forgot to document the relaxed=True keyword, and the strict-parameters policy.

17 files changed, 290 insertions, 9 deletions

diff --git a/CHANGES b/CHANGES
index cf4cdbd..c8a2235 100644
--- a/CHANGES
+++ b/CHANGES
@@ -106,6 +106,22 @@ Existing Hashes
 
         .. [#consteq] "constant time" is a misnomer, it actually takes ``THETA(len(righthand_value))`` time.
 
+    .. _strict-parameters:
+
+    *Strict Parameters*
+        Previous releases of Passlib would silently correct any invalid values
+        (such as ``rounds`` parameters that were out of range). This is was deemed
+        undesirable, as it leaves developers unaware they are requesting
+        an incorrect (and potentially insecure) value.
+
+        Starting with this release, providing invalid values to
+        :meth:`PasswordHash.encrypt <passlib.ifc.PasswordHash.encrypt>`
+        will result in a :exc:`ValueError`. However, most hashes now accept
+        an optional ``relaxed=True`` keyword, which causes Passlib
+        to try and correct invalid values, and if successful,
+        issue a :exc:`~passlib.exc.PasslibHashWarning` instead.
+        These warnings can then be filtered if desired.
+
     :doc:`bcrypt <lib/passlib.hash.bcrypt>`
         The BCrypt hash now supports the `crypt_blowfish <http://www.openwall.com/crypt/>`_ project's
         ``$2y$`` hash prefix.
diff --git a/docs/password_hash_api.rst b/docs/password_hash_api.rst
index 4dc2314..0bc2476 100644
--- a/docs/password_hash_api.rst
+++ b/docs/password_hash_api.rst
@@ -480,14 +480,16 @@ the hashes in passlib:
         offer the same level of security.
 
     ``relaxed``
-        If supported, ``relaxed=True`` will cause the handler to
-        be more forgiving about invalid input. Instead of immediately throwing
-        a :exc:`ValueError`, it will first attempt to correct the input,
-        and issue a :exc:`~passlib.exc.PasslibHashWarning` if successful.
-        This includes actions like clamping out-of-range rounds values,
-        and truncating salts that are too long.
-
-        Many of the hashes in Passlib support this option, even if it's not listed.
+        By default, passing :meth:`~PasswordHash.encrypt` an invalid
+        value will result in a :exc:`ValueError`. However, if ``relaxed=True``,
+        Passlib will attempt to correct the error, and if successful,
+        issue a :exc:`~passlib.exc.PasslibHashWarning` instead.
+        This warning may then be filtered if desired.
+        Correctable errors include (but aren not limited to): ``rounds``
+        and ``salt_size`` values that are too low or too high, ``salt``
+        strings that are too large, etc.
+
+        This option is supported by most of the hashes in Passlib.
 
 .. attribute:: PasswordHash.context_kwds
 
diff --git a/passlib/handlers/bcrypt.py b/passlib/handlers/bcrypt.py
index 5086b36..66e4743 100644
--- a/passlib/handlers/bcrypt.py
+++ b/passlib/handlers/bcrypt.py
@@ -83,6 +83,16 @@ class bcrypt(uh.HasManyIdents, uh.HasRounds, uh.HasSalt, uh.HasManyBackends, uh.
         but it can be set to ``2`` to use the older (and less secure)
         version of the BCrypt algorithm.
 
+    :type relaxed: bool
+    :param relaxed:
+        By default, providing an invalid value for one of the other
+        keywords will result in a :exc:`ValueError`. If ``relaxed=True``,
+        and the error can be corrected, a :exc:`~passlib.exc.PasslibHashWarning`
+        will be issued instead. Correctable errors include ``rounds``
+        that are too small or too large, and ``salt`` strings that are too long.
+
+        .. versionadded:: 1.6
+
     .. versionchanged:: 1.6
         This class now supports ``2y`` hashes, and recognizes
         (but does not support) the broken ``2x`` hashes.
diff --git a/passlib/handlers/cisco.py b/passlib/handlers/cisco.py
index 3bc90a7..196e38b 100644
--- a/passlib/handlers/cisco.py
+++ b/passlib/handlers/cisco.py
@@ -95,13 +95,23 @@ class cisco_type7(uh.GenericHandler):
     instead of a real hash.
 
     The :meth:`~passlib.ifc.PasswordHash.encrypt` and :meth:`~passlib.ifc.PasswordHash.genhash` methods
-    have the following optional keyword:
+    have the following optional keywords:
 
     :type salt: int
     :param salt:
         This may be an optional salt integer drawn from ``range(0,16)``.
         If omitted, one will be chosen at random.
 
+    :type relaxed: bool
+    :param relaxed:
+        By default, providing an invalid value for one of the other
+        keywords will result in a :exc:`ValueError`. If ``relaxed=True``,
+        and the error can be corrected, a :exc:`~passlib.exc.PasslibHashWarning`
+        will be issued instead. Correctable errors include
+        ``salt`` values that are out of range.
+        
+        .. versionadded:: 1.6
+
     Note that while this class outputs digests in upper-case hexidecimal,
     it will accept lower-case as well.
 
diff --git a/passlib/handlers/des_crypt.py b/passlib/handlers/des_crypt.py
index 81c689a..d549815 100644
--- a/passlib/handlers/des_crypt.py
+++ b/passlib/handlers/des_crypt.py
@@ -127,6 +127,16 @@ class des_crypt(uh.HasManyBackends, uh.HasSalt, uh.GenericHandler):
         Optional salt string.
         If not specified, one will be autogenerated (this is recommended).
         If specified, it must be 2 characters, drawn from the regexp range ``[./0-9A-Za-z]``.
+
+    :type relaxed: bool
+    :param relaxed:
+        By default, providing an invalid value for one of the other
+        keywords will result in a :exc:`ValueError`. If ``relaxed=True``,
+        and the error can be corrected, a :exc:`~passlib.exc.PasslibHashWarning`
+        will be issued instead. Correctable errors include
+        ``salt`` strings that are too long.
+
+        .. versionadded:: 1.6
     """
     #=========================================================
     # class attrs
@@ -208,6 +218,16 @@ class bsdi_crypt(uh.HasManyBackends, uh.HasRounds, uh.HasSalt, uh.GenericHandler
         Optional number of rounds to use.
         Defaults to 5001, must be between 1 and 16777215, inclusive.
 
+    :type relaxed: bool
+    :param relaxed:
+        By default, providing an invalid value for one of the other
+        keywords will result in a :exc:`ValueError`. If ``relaxed=True``,
+        and the error can be corrected, a :exc:`~passlib.exc.PasslibHashWarning`
+        will be issued instead. Correctable errors include ``rounds``
+        that are too small or too large, and ``salt`` strings that are too long.
+
+        .. versionadded:: 1.6
+
     .. versionchanged:: 1.6
         :meth:`encrypt` will now issue a warning if an even number of rounds is used
         (see :ref:`bsdi-crypt-security-issues` regarding weak DES keys).
@@ -331,6 +351,16 @@ class bigcrypt(uh.HasSalt, uh.GenericHandler):
         Optional salt string.
         If not specified, one will be autogenerated (this is recommended).
         If specified, it must be 22 characters, drawn from the regexp range ``[./0-9A-Za-z]``.
+
+    :type relaxed: bool
+    :param relaxed:
+        By default, providing an invalid value for one of the other
+        keywords will result in a :exc:`ValueError`. If ``relaxed=True``,
+        and the error can be corrected, a :exc:`~passlib.exc.PasslibHashWarning`
+        will be issued instead. Correctable errors include
+        ``salt`` strings that are too long.
+
+        .. versionadded:: 1.6
     """
     #=========================================================
     # class attrs
@@ -404,6 +434,16 @@ class crypt16(uh.HasSalt, uh.GenericHandler):
         Optional salt string.
         If not specified, one will be autogenerated (this is recommended).
         If specified, it must be 2 characters, drawn from the regexp range ``[./0-9A-Za-z]``.
+
+    :type relaxed: bool
+    :param relaxed:
+        By default, providing an invalid value for one of the other
+        keywords will result in a :exc:`ValueError`. If ``relaxed=True``,
+        and the error can be corrected, a :exc:`~passlib.exc.PasslibHashWarning`
+        will be issued instead. Correctable errors include
+        ``salt`` strings that are too long.
+
+        .. versionadded:: 1.6
     """
     #=========================================================
     # class attrs
diff --git a/passlib/handlers/django.py b/passlib/handlers/django.py
index 229b885..e8d1ec9 100644
--- a/passlib/handlers/django.py
+++ b/passlib/handlers/django.py
@@ -205,6 +205,14 @@ class django_pbkdf2_sha256(DjangoVariableHash):
         Optional number of rounds to use.
         Defaults to 10000, but must be within ``range(1,1<<32)``.
 
+    :type relaxed: bool
+    :param relaxed:
+        By default, providing an invalid value for one of the other
+        keywords will result in a :exc:`ValueError`. If ``relaxed=True``,
+        and the error can be corrected, a :exc:`~passlib.exc.PasslibHashWarning`
+        will be issued instead. Correctable errors include ``rounds``
+        that are too small or too large, and ``salt`` strings that are too long.
+
     This should be compatible with the hashes generated by
     Django 1.4's :class:`!PBKDF2PasswordHasher` class.
 
@@ -250,6 +258,14 @@ class django_pbkdf2_sha1(django_pbkdf2_sha256):
         Optional number of rounds to use.
         Defaults to 10000, but must be within ``range(1,1<<32)``.
 
+    :type relaxed: bool
+    :param relaxed:
+        By default, providing an invalid value for one of the other
+        keywords will result in a :exc:`ValueError`. If ``relaxed=True``,
+        and the error can be corrected, a :exc:`~passlib.exc.PasslibHashWarning`
+        will be issued instead. Correctable errors include ``rounds``
+        that are too small or too large, and ``salt`` strings that are too long.
+
     This should be compatible with the hashes generated by
     Django 1.4's :class:`!PBKDF2SHA1PasswordHasher` class.
 
diff --git a/passlib/handlers/fshp.py b/passlib/handlers/fshp.py
index b95f034..fe82415 100644
--- a/passlib/handlers/fshp.py
+++ b/passlib/handlers/fshp.py
@@ -50,6 +50,16 @@ class fshp(uh.HasRounds, uh.HasRawSalt, uh.HasRawChecksum, uh.GenericHandler):
         * ``1`` - uses SHA-2/256 digest (default).
         * ``2`` - uses SHA-2/384 digest.
         * ``3`` - uses SHA-2/512 digest.
+
+    :type relaxed: bool
+    :param relaxed:
+        By default, providing an invalid value for one of the other
+        keywords will result in a :exc:`ValueError`. If ``relaxed=True``,
+        and the error can be corrected, a :exc:`~passlib.exc.PasslibHashWarning`
+        will be issued instead. Correctable errors include ``rounds``
+        that are too small or too large, and ``salt`` strings that are too long.
+
+        .. versionadded:: 1.6
     """
 
     #=========================================================
diff --git a/passlib/handlers/ldap_digests.py b/passlib/handlers/ldap_digests.py
index 29bade9..17c9686 100644
--- a/passlib/handlers/ldap_digests.py
+++ b/passlib/handlers/ldap_digests.py
@@ -148,6 +148,16 @@ class ldap_salted_md5(_SaltedBase64DigestHelper):
         but some systems use larger salts, and Passlib supports
         any value between 4-16.
 
+    :type relaxed: bool
+    :param relaxed:
+        By default, providing an invalid value for one of the other
+        keywords will result in a :exc:`ValueError`. If ``relaxed=True``,
+        and the error can be corrected, a :exc:`~passlib.exc.PasslibHashWarning`
+        will be issued instead. Correctable errors include
+        ``salt`` strings that are too long.
+
+        .. versionadded:: 1.6
+
     .. versionchanged:: 1.6
         This format now supports variable length salts, instead of a fix 4 bytes.
     """
@@ -178,6 +188,16 @@ class ldap_salted_sha1(_SaltedBase64DigestHelper):
         but some systems use larger salts, and Passlib supports
         any value between 4-16.
 
+    :type relaxed: bool
+    :param relaxed:
+        By default, providing an invalid value for one of the other
+        keywords will result in a :exc:`ValueError`. If ``relaxed=True``,
+        and the error can be corrected, a :exc:`~passlib.exc.PasslibHashWarning`
+        will be issued instead. Correctable errors include
+        ``salt`` strings that are too long.
+
+        .. versionadded:: 1.6
+
     .. versionchanged:: 1.6
         This format now supports variable length salts, instead of a fix 4 bytes.
     """
diff --git a/passlib/handlers/md5_crypt.py b/passlib/handlers/md5_crypt.py
index cd413d6..6832dcf 100644
--- a/passlib/handlers/md5_crypt.py
+++ b/passlib/handlers/md5_crypt.py
@@ -236,6 +236,16 @@ class md5_crypt(uh.HasManyBackends, _MD5_Common):
         Optional salt string.
         If not specified, one will be autogenerated (this is recommended).
         If specified, it must be 0-8 characters, drawn from the regexp range ``[./0-9A-Za-z]``.
+
+    :type relaxed: bool
+    :param relaxed:
+        By default, providing an invalid value for one of the other
+        keywords will result in a :exc:`ValueError`. If ``relaxed=True``,
+        and the error can be corrected, a :exc:`~passlib.exc.PasslibHashWarning`
+        will be issued instead. Correctable errors include
+        ``salt`` strings that are too long.
+
+        .. versionadded:: 1.6
     """
     #=========================================================
     # class attrs
@@ -285,6 +295,16 @@ class apr_md5_crypt(_MD5_Common):
         Optional salt string.
         If not specified, one will be autogenerated (this is recommended).
         If specified, it must be 0-8 characters, drawn from the regexp range ``[./0-9A-Za-z]``.
+
+    :type relaxed: bool
+    :param relaxed:
+        By default, providing an invalid value for one of the other
+        keywords will result in a :exc:`ValueError`. If ``relaxed=True``,
+        and the error can be corrected, a :exc:`~passlib.exc.PasslibHashWarning`
+        will be issued instead. Correctable errors include
+        ``salt`` strings that are too long.
+
+        .. versionadded:: 1.6
     """
     #=========================================================
     # class attrs
diff --git a/passlib/handlers/mssql.py b/passlib/handlers/mssql.py
index 97cc0cc..359d45a 100644
--- a/passlib/handlers/mssql.py
+++ b/passlib/handlers/mssql.py
@@ -112,6 +112,14 @@ class mssql2000(uh.HasRawSalt, uh.HasRawChecksum, uh.GenericHandler):
         Optional salt string.
         If not specified, one will be autogenerated (this is recommended).
         If specified, it must be 4 bytes in length.
+
+    :type relaxed: bool
+    :param relaxed:
+        By default, providing an invalid value for one of the other
+        keywords will result in a :exc:`ValueError`. If ``relaxed=True``,
+        and the error can be corrected, a :exc:`~passlib.exc.PasslibHashWarning`
+        will be issued instead. Correctable errors include
+        ``salt`` strings that are too long.
     """
     #=========================================================
     #algorithm information
@@ -182,6 +190,14 @@ class mssql2005(uh.HasRawSalt, uh.HasRawChecksum, uh.GenericHandler):
         Optional salt string.
         If not specified, one will be autogenerated (this is recommended).
         If specified, it must be 4 bytes in length.
+
+    :type relaxed: bool
+    :param relaxed:
+        By default, providing an invalid value for one of the other
+        keywords will result in a :exc:`ValueError`. If ``relaxed=True``,
+        and the error can be corrected, a :exc:`~passlib.exc.PasslibHashWarning`
+        will be issued instead. Correctable errors include
+        ``salt`` strings that are too long.
     """
     #=========================================================
     #algorithm information
diff --git a/passlib/handlers/oracle.py b/passlib/handlers/oracle.py
index 08850f0..ac45589 100644
--- a/passlib/handlers/oracle.py
+++ b/passlib/handlers/oracle.py
@@ -114,6 +114,16 @@ class oracle11(uh.HasSalt, uh.GenericHandler):
         Optional salt string.
         If not specified, one will be autogenerated (this is recommended).
         If specified, it must be 20 hexidecimal characters.
+
+    :type relaxed: bool
+    :param relaxed:
+        By default, providing an invalid value for one of the other
+        keywords will result in a :exc:`ValueError`. If ``relaxed=True``,
+        and the error can be corrected, a :exc:`~passlib.exc.PasslibHashWarning`
+        will be issued instead. Correctable errors include
+        ``salt`` strings that are too long.
+
+        .. versionadded:: 1.6
     """
     #=========================================================
     #class attrs
diff --git a/passlib/handlers/pbkdf2.py b/passlib/handlers/pbkdf2.py
index 3eba01c..6d90675 100644
--- a/passlib/handlers/pbkdf2.py
+++ b/passlib/handlers/pbkdf2.py
@@ -120,6 +120,16 @@ def create_pbkdf2_hash(hash_name, digest_size, rounds=12000, ident=None, module=
     :param rounds:
         Optional number of rounds to use.
         Defaults to %(dr)d, but must be within ``range(1,1<<32)``.
+
+    :type relaxed: bool
+    :param relaxed:
+        By default, providing an invalid value for one of the other
+        keywords will result in a :exc:`ValueError`. If ``relaxed=True``,
+        and the error can be corrected, a :exc:`~passlib.exc.PasslibHashWarning`
+        will be issued instead. Correctable errors include ``rounds``
+        that are too small or too large, and ``salt`` strings that are too long.
+
+        .. versionadded:: 1.6
     """ % dict(prf=prf.upper(), dsc=base.default_salt_size, dr=rounds)
     ))
 
@@ -163,6 +173,16 @@ class cta_pbkdf2_sha1(uh.HasRounds, uh.HasRawSalt, uh.HasRawChecksum, uh.Generic
     :param rounds:
         Optional number of rounds to use.
         Defaults to 60000, must be within ``range(1,1<<32)``.
+
+    :type relaxed: bool
+    :param relaxed:
+        By default, providing an invalid value for one of the other
+        keywords will result in a :exc:`ValueError`. If ``relaxed=True``,
+        and the error can be corrected, a :exc:`~passlib.exc.PasslibHashWarning`
+        will be issued instead. Correctable errors include ``rounds``
+        that are too small or too large, and ``salt`` strings that are too long.
+
+        .. versionadded:: 1.6
     """
 
     #=========================================================
@@ -252,6 +272,16 @@ class dlitz_pbkdf2_sha1(uh.HasRounds, uh.HasSalt, uh.GenericHandler):
     :param rounds:
         Optional number of rounds to use.
         Defaults to 60000, must be within ``range(1,1<<32)``.
+
+    :type relaxed: bool
+    :param relaxed:
+        By default, providing an invalid value for one of the other
+        keywords will result in a :exc:`ValueError`. If ``relaxed=True``,
+        and the error can be corrected, a :exc:`~passlib.exc.PasslibHashWarning`
+        will be issued instead. Correctable errors include ``rounds``
+        that are too small or too large, and ``salt`` strings that are too long.
+
+        .. versionadded:: 1.6
     """
 
     #=========================================================
@@ -331,6 +361,16 @@ class atlassian_pbkdf2_sha1(uh.HasRawSalt, uh.HasRawChecksum, uh.GenericHandler)
         Optional salt bytes.
         If specified, the length must be exactly 16 bytes.
         If not specified, a salt will be autogenerated (this is recommended).
+
+    :type relaxed: bool
+    :param relaxed:
+        By default, providing an invalid value for one of the other
+        keywords will result in a :exc:`ValueError`. If ``relaxed=True``,
+        and the error can be corrected, a :exc:`~passlib.exc.PasslibHashWarning`
+        will be issued instead. Correctable errors include
+        ``salt`` strings that are too long.
+
+        .. versionadded:: 1.6
     """
     #--GenericHandler--
     name = "atlassian_pbkdf2_sha1"
@@ -390,6 +430,16 @@ class grub_pbkdf2_sha512(uh.HasRounds, uh.HasRawSalt, uh.HasRawChecksum, uh.Gene
     :param rounds:
         Optional number of rounds to use.
         Defaults to 12000, but must be within ``range(1,1<<32)``.
+
+    :type relaxed: bool
+    :param relaxed:
+        By default, providing an invalid value for one of the other
+        keywords will result in a :exc:`ValueError`. If ``relaxed=True``,
+        and the error can be corrected, a :exc:`~passlib.exc.PasslibHashWarning`
+        will be issued instead. Correctable errors include ``rounds``
+        that are too small or too large, and ``salt`` strings that are too long.
+
+        .. versionadded:: 1.6
     """
     name = "grub_pbkdf2_sha512"
     setting_kwds = ("salt", "salt_size", "rounds")
diff --git a/passlib/handlers/phpass.py b/passlib/handlers/phpass.py
index e364b51..0cafea1 100644
--- a/passlib/handlers/phpass.py
+++ b/passlib/handlers/phpass.py
@@ -51,6 +51,16 @@ class phpass(uh.HasManyIdents, uh.HasRounds, uh.HasSalt, uh.GenericHandler):
         phpBB3 uses ``H`` instead of ``P`` for it's identifier,
         this may be set to ``H`` in order to generate phpBB3 compatible hashes.
         it defaults to ``P``.
+
+    :type relaxed: bool
+    :param relaxed:
+        By default, providing an invalid value for one of the other
+        keywords will result in a :exc:`ValueError`. If ``relaxed=True``,
+        and the error can be corrected, a :exc:`~passlib.exc.PasslibHashWarning`
+        will be issued instead. Correctable errors include ``rounds``
+        that are too small or too large, and ``salt`` strings that are too long.
+
+        .. versionadded:: 1.6
     """
 
     #=========================================================
diff --git a/passlib/handlers/scram.py b/passlib/handlers/scram.py
index 6e1b144..2af3980 100644
--- a/passlib/handlers/scram.py
+++ b/passlib/handlers/scram.py
@@ -63,6 +63,16 @@ class scram(uh.HasRounds, uh.HasRawSalt, uh.HasRawChecksum, uh.GenericHandler):
         use :mod:`!hashlib` or `IANA <http://www.iana.org/assignments/hash-function-text-names>`_
         hash names.
 
+    :type relaxed: bool
+    :param relaxed:
+        By default, providing an invalid value for one of the other
+        keywords will result in a :exc:`ValueError`. If ``relaxed=True``,
+        and the error can be corrected, a :exc:`~passlib.exc.PasslibHashWarning`
+        will be issued instead. Correctable errors include ``rounds``
+        that are too small or too large, and ``salt`` strings that are too long.
+
+        .. versionadded:: 1.6
+
     In addition to the standard :ref:`password-hash-api` methods,
     this class also provides the following methods for manipulating Passlib
     scram hashes in ways useful for pluging into a SCRAM protocol stack:
@@ -394,6 +404,7 @@ class scram(uh.HasRounds, uh.HasRawSalt, uh.HasRawChecksum, uh.GenericHandler):
             else:
                 return correct
         else:
+            # XXX: should this just always use sha1 hash? would be faster.
             # otherwise only verify against one hash, pick one w/ best security.
             for alg in self._verify_algs:
                 if alg in chkmap:
diff --git a/passlib/handlers/sha1_crypt.py b/passlib/handlers/sha1_crypt.py
index 36d6780..5098a72 100644
--- a/passlib/handlers/sha1_crypt.py
+++ b/passlib/handlers/sha1_crypt.py
@@ -49,6 +49,16 @@ class sha1_crypt(uh.HasManyBackends, uh.HasRounds, uh.HasSalt, uh.GenericHandler
     :param rounds:
         Optional number of rounds to use.
         Defaults to 40000, must be between 1 and 4294967295, inclusive.
+
+    :type relaxed: bool
+    :param relaxed:
+        By default, providing an invalid value for one of the other
+        keywords will result in a :exc:`ValueError`. If ``relaxed=True``,
+        and the error can be corrected, a :exc:`~passlib.exc.PasslibHashWarning`
+        will be issued instead. Correctable errors include ``rounds``
+        that are too small or too large, and ``salt`` strings that are too long.
+
+        .. versionadded:: 1.6
     """
 
     #=========================================================
diff --git a/passlib/handlers/sha2_crypt.py b/passlib/handlers/sha2_crypt.py
index 4bcf3f2..065102a 100644
--- a/passlib/handlers/sha2_crypt.py
+++ b/passlib/handlers/sha2_crypt.py
@@ -385,6 +385,16 @@ class sha256_crypt(_SHA2_Common):
         when encoding it to a string; this is only permitted by the spec for rounds=5000,
         and the flag is ignored otherwise. the spec requires the two different
         encodings be preserved as they are, instead of normalizing them.
+
+    :type relaxed: bool
+    :param relaxed:
+        By default, providing an invalid value for one of the other
+        keywords will result in a :exc:`ValueError`. If ``relaxed=True``,
+        and the error can be corrected, a :exc:`~passlib.exc.PasslibHashWarning`
+        will be issued instead. Correctable errors include ``rounds``
+        that are too small or too large, and ``salt`` strings that are too long.
+
+        .. versionadded:: 1.6
     """
     #=========================================================
     # class attrs
@@ -435,6 +445,16 @@ class sha512_crypt(_SHA2_Common):
         when encoding it to a string; this is only permitted by the spec for rounds=5000,
         and the flag is ignored otherwise. the spec requires the two different
         encodings be preserved as they are, instead of normalizing them.
+
+    :type relaxed: bool
+    :param relaxed:
+        By default, providing an invalid value for one of the other
+        keywords will result in a :exc:`ValueError`. If ``relaxed=True``,
+        and the error can be corrected, a :exc:`~passlib.exc.PasslibHashWarning`
+        will be issued instead. Correctable errors include ``rounds``
+        that are too small or too large, and ``salt`` strings that are too long.
+
+        .. versionadded:: 1.6
     """
 
     #=========================================================
diff --git a/passlib/handlers/sun_md5_crypt.py b/passlib/handlers/sun_md5_crypt.py
index 8a6c163..8296e5e 100644
--- a/passlib/handlers/sun_md5_crypt.py
+++ b/passlib/handlers/sun_md5_crypt.py
@@ -195,6 +195,16 @@ class sun_md5_crypt(uh.HasRounds, uh.HasSalt, uh.GenericHandler):
         This flag can be ignored by most users.
         Defaults to ``False``.
         (see :ref:`smc-bare-salt` for details).
+
+    :type relaxed: bool
+    :param relaxed:
+        By default, providing an invalid value for one of the other
+        keywords will result in a :exc:`ValueError`. If ``relaxed=True``,
+        and the error can be corrected, a :exc:`~passlib.exc.PasslibHashWarning`
+        will be issued instead. Correctable errors include ``rounds``
+        that are too small or too large, and ``salt`` strings that are too long.
+
+        .. versionadded:: 1.6
     """
     #=========================================================
     #class attrs