1 files changed, 22 insertions, 0 deletions
diff --git a/bcrypt/__init__.py b/bcrypt/__init__.py
index d4f2b2d..78d945d 100644
--- a/bcrypt/__init__.py
+++ b/bcrypt/__init__.py
@@ -20,6 +20,28 @@ gensalt() function:
 
 The parameter "log_rounds" defines the complexity of the hashing. The
 cost increases as 2**log_rounds.
+
+Passwords can be checked against a hashed copy using the checkpw() routine:
+
+  checkpw(password, hashed_password) -> boolean (true if matched)
+
+Passwords and salts for the hashpw and gensalt functions are text strings
+that must not contain embedded nul (ASCII 0) characters.
+
+This module also operates as a key derivation function (KDF) to transform a
+password and salt into bytes suitable for use as cryptographic key material:
+
+  kdf(password, salt, desired_length, rounds) -> key
+
+This will generate a key of "desired_length" in bytes (NB. not bits). For the
+KDF mode the "rounds" parameter is the literal rounds, not the logarithm as
+for gensalt. For the KDF case, "salt" and "password" may be binary strings
+containing embedded nul characters. Note also that the "salt" for the KDF
+should just be a random sequence of bytes (e.g. as generated by os.urandom)
+and not one prepared with gensalt().
+
+The KDF mode is recommended for generating symmetric cipher keys, IVs, hash
+and MAC keys, etc. It should not be used a keystream for encryption itself.
 """
 
 import os