diff options
author | Eli Collins <elic@assurancetechnologies.com> | 2011-08-17 19:31:35 -0400 |
---|---|---|
committer | Eli Collins <elic@assurancetechnologies.com> | 2011-08-17 19:31:35 -0400 |
commit | 257bf008f87fffa1aaf9e575a4e7e81ca6751e60 (patch) | |
tree | 5619e7826d9bb2fdd9bf92b799ca653a1f071801 /docs | |
parent | 1b3602428d73825344062a4381e038c8d5cb1aad (diff) | |
download | passlib-257bf008f87fffa1aaf9e575a4e7e81ca6751e60.tar.gz |
traditional post-release tweaks to documentation
Diffstat (limited to 'docs')
-rw-r--r-- | docs/install.rst | 4 | ||||
-rw-r--r-- | docs/lib/passlib.hash.bcrypt.rst | 37 | ||||
-rw-r--r-- | docs/lib/passlib.hash.pbkdf2_digest.rst | 31 | ||||
-rw-r--r-- | docs/lib/passlib.hash.sha512_crypt.rst | 2 | ||||
-rw-r--r-- | docs/new_app_quickstart.rst | 5 |
5 files changed, 68 insertions, 11 deletions
diff --git a/docs/install.rst b/docs/install.rst index 4d13b9d..57e39ab 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -16,6 +16,8 @@ Passlib should work with all operating systems, as it contains builtin fallbacks for almost all OS-dependant features. +.. _optional-libraries: + Optional Libraries ================== * `py-bcrypt <http://www.mindrot.org/projects/py-bcrypt/>`_ or @@ -25,7 +27,7 @@ Optional Libraries support for the BCrypt hash algorithm. This is required if you want to handle BCrypt hashes, and your OS does not provide native BCrypt support - via stdlib's :mod:`!crypt` (this is pretty much all non-BSD systems). + via stdlib's :mod:`!crypt` (which includes pretty much all non-BSD systems). * `M2Crypto <http://chandlerproject.org/bin/view/Projects/MeTooCrypto>`_ diff --git a/docs/lib/passlib.hash.bcrypt.rst b/docs/lib/passlib.hash.bcrypt.rst index ccc7c7b..2b9a22d 100644 --- a/docs/lib/passlib.hash.bcrypt.rst +++ b/docs/lib/passlib.hash.bcrypt.rst @@ -8,18 +8,43 @@ BCrypt was developed to replace :class:`~passlib.hash.md5_crypt` for BSD systems It uses a modified version of the Blowfish stream cipher. Featuring a large salt and variable number of rounds, it's currently the default password hash for many systems (notably BSD), and has no known weaknesses. +It is one of the three hashes Passlib :ref:`recommends <recommended-hashes>` +for new applications. .. note:: - It is strongly recommended to install PyBcrypt or BCryptor if this algorithm - is going to be used. + It is strongly recommended to install + :ref:`PyBcrypt or BCryptor <optional-libraries>` + if this algorithm is going to be used. Usage ===== - -.. todo:: - - write usage instructions +This class can be used directly as follows:: + + >>> from passlib.hash import bcrypt + + >>> #generate new salt, encrypt password + >>> h = bcrypt.encrypt("password") + >>> h + '$2a$12$NT0I31Sa7ihGEWpka9ASYrEFkhuTNeBQ2xfZskIiiJeyFXhRgS.Sy' + + >>> #same, but with explict number of rounds + >>> bcrypt.encrypt("password", rounds=8) + '$2a$08$8wmNsdCH.M21f.LSBSnYjQrZ9l1EmtBc9uNPGL.9l75YE8D8FlnZC' + + >>> #check if hash is a bcrypt hash + >>> bcrypt.identify(h) + True + >>> #check if some other hash is recognized + >>> bcrypt.identify('$1$3azHgidD$SrJPt7B.9rekpmwJwtON31') + False + + >>> #verify correct password + >>> bcrypt.verify("password", h) + True + >>> #verify incorrect password + >>> bcrypt.verify("wrong", h) + False Interface ========= diff --git a/docs/lib/passlib.hash.pbkdf2_digest.rst b/docs/lib/passlib.hash.pbkdf2_digest.rst index 0f2b1c6..6cd3ea6 100644 --- a/docs/lib/passlib.hash.pbkdf2_digest.rst +++ b/docs/lib/passlib.hash.pbkdf2_digest.rst @@ -17,6 +17,8 @@ Though the original PBKDF2 specification uses the SHA-1 message digest, it is not vulnerable to any of the known weaknesses of SHA-1 [#hmac-sha1]_, and can be safely used. However, for those still concerned, SHA-256 and SHA-512 versions are offered as well. +PBKDF2-SHA512 is one of the three hashes Passlib +:ref:`recommends <recommended-hashes>` for new applications. .. seealso:: @@ -24,9 +26,32 @@ versions are offered as well. Usage ===== -These classes support both rounds and salts, -and can be used in the exact same manner -as :doc:`SHA-512 Crypt <passlib.hash.sha512_crypt>`. +All of the following classes can be used directly as follows:: + + >>> from passlib.hash import pbkdf2_sha256 as engine + + >>> #generate new salt, encrypt password + >>> hash = engine.encrypt("password") + >>> hash + '$pbkdf2-sha256$6400$0ZrzXitFSGltTQnBWOsdAw$Y11AchqV4b0sUisdZd0Xr97KWoymNE0LNNrnEgY4H9M' + + >>> #same, but with explicit number of rounds and salt length + >>> engine.encrypt("password", rounds=8000, salt_size=10) + '$pbkdf2-sha256$8000$XAuBMIYQQogxRg$tRRlz8hYn63B9LYiCd6PRo6FMiunY9ozmMMI3srxeRE' + + >>> #check if hash is a pbkdf2-sha256 hash + >>> engine.identify(hash) + True + >>> #check if some other hash is recognized + >>> engine.identify('$1$3azHgidD$SrJPt7B.9rekpmwJwtON31') + False + + >>> #verify correct password + >>> engine.verify("password", hash) + True + >>> #verify incorrect password + >>> engine.verify("wrong", hash) + False Interface ========= diff --git a/docs/lib/passlib.hash.sha512_crypt.rst b/docs/lib/passlib.hash.sha512_crypt.rst index db727c9..d9aa1ea 100644 --- a/docs/lib/passlib.hash.sha512_crypt.rst +++ b/docs/lib/passlib.hash.sha512_crypt.rst @@ -9,6 +9,8 @@ as a successor to :class:`~passlib.hash.md5_crypt`. They include fixes and advancements such as variable rounds, and use of NIST-approved cryptographic primitives. SHA-256 / SHA-512 Crypt are currently the default password hash for many systems (notably Linux), and have no known weaknesses. +SHA-512 Crypt is one of the three hashes Passlib :ref:`recommends <recommended-hashes>` +for new applications. Usage ===== diff --git a/docs/new_app_quickstart.rst b/docs/new_app_quickstart.rst index ca31f11..a3a84ff 100644 --- a/docs/new_app_quickstart.rst +++ b/docs/new_app_quickstart.rst @@ -35,6 +35,8 @@ For applications which started using this preset, but whose needs have grown beyond it, it is recommended to create your own :mod:`CryptContext <passlib.context>` instance; see below for more... +.. _recommended-hashes: + Choosing a Hash ================ *If you already know what hash algorithm(s) you want to use, @@ -93,7 +95,8 @@ of simultaneous logon attempts (eg web apps). For BCrypt support on non-BSD systems, Passlib requires a C-extension module - provided by the external pybcrypt or bcryptor packages. + provided by the external + :ref:`PyBcrypt or BCryptor <optional-libraries>` packages. Neither of these currently supports Python 3. SHA512-Crypt |