CryptContext can now run passwords through SASLPrep via "passprep" options [issue 24]

1 files changed, 31 insertions, 0 deletions

diff --git a/docs/lib/passlib.context-options.rst b/docs/lib/passlib.context-options.rst
index 629a2b1..9753e39 100644
--- a/docs/lib/passlib.context-options.rst
+++ b/docs/lib/passlib.context-options.rst
@@ -139,6 +139,37 @@ Within INI files, this may be specified using the alternate format :samp:`{hash}
         These are configurable per-context limits,
         they will be clipped by any hard limits set in the hash algorithm itself.
 
+.. _passprep:
+
+:samp:`{hash}__passprep`
+
+    Normalize unicode passwords before passing them to the underlying
+    hash algorithm. This is primarily useful if users are likely
+    to use non-ascii characters in their password (e.g. vowels characters
+    with accent marks), which unicode offers multiple representations for.
+
+    This may be one of the following values:
+
+    * ``"raw"`` - use all unicode inputs as-is (the default).
+      unnormalized unicode input may not verify against a hash
+      generated from normalized unicode input (or vice versa).
+
+    * ``"saslprep"`` - run all passwords through the SASLPrep
+      unicode normalization algorithm (:rfc:`4013`) before hashing.
+      this is recommended for new deployments, particularly
+      in non-ascii environments.
+
+    * ``"saslprep,raw"`` - compatibility mode: encryption of new passwords
+      will be run through SASLPrep; but verification will be done
+      against the SASLPrep *and* raw versions of the password. This allows
+      existing hashes that were generated from unnormalized input
+      to continue to work.
+
+    .. note::
+
+        It is recommended to set this for all hashes via ``all__passprep``,
+        instead of settings it per algorithm.
+
 :samp:`{hash}__{setting}`
 
     Any other option values, which match the name of a parameter listed