diff options
Diffstat (limited to 'docs/lib')
| -rw-r--r-- | docs/lib/passlib.apps.rst | 2 | ||||
| -rw-r--r-- | docs/lib/passlib.context-options.rst | 4 | ||||
| -rw-r--r-- | docs/lib/passlib.hash.atlassian_pbkdf2_sha1.rst | 60 | ||||
| -rw-r--r-- | docs/lib/passlib.hash.dlitz_pbkdf2_sha1.rst | 66 | ||||
| -rw-r--r-- | docs/lib/passlib.hash.grub_pbkdf2_sha512.rst | 84 | ||||
| -rw-r--r-- | docs/lib/passlib.hash.ldap_crypt.rst | 73 | ||||
| -rw-r--r-- | docs/lib/passlib.hash.ldap_digests.rst | 105 | ||||
| -rw-r--r-- | docs/lib/passlib.hash.ldap_std.rst | 102 | ||||
| -rw-r--r-- | docs/lib/passlib.hash.mysql323.rst | 2 | ||||
| -rw-r--r-- | docs/lib/passlib.hash.pbkdf2_digest.rst | 85 | ||||
| -rw-r--r-- | docs/lib/passlib.hash.pbkdf2_digests.rst | 222 | ||||
| -rw-r--r-- | docs/lib/passlib.hash.phpass.rst | 2 | ||||
| -rw-r--r-- | docs/lib/passlib.hash.plaintext.rst | 5 | ||||
| -rw-r--r-- | docs/lib/passlib.hash.rst | 158 | ||||
| -rw-r--r-- | docs/lib/passlib.hosts.rst | 114 | ||||
| -rw-r--r-- | docs/lib/passlib.registry.rst | 10 |
16 files changed, 615 insertions, 479 deletions
diff --git a/docs/lib/passlib.apps.rst b/docs/lib/passlib.apps.rst index 27e2058..3af39f1 100644 --- a/docs/lib/passlib.apps.rst +++ b/docs/lib/passlib.apps.rst @@ -53,7 +53,7 @@ Passlib provides two contexts related to ldap hashes: This object provides a pre-configured :class:`!CryptContext` instance for handling LDAPv2 password hashes. It recognizes all - the formats in the :doc:`ldap_digests listing <passlib.hash.ldap_digests>`. + the :ref:`standard ldap hashes <standard-ldap-hashes>`. It defaults to using the ``{SSHA}`` password hash. For times when there should be another default, using code such as the following:: diff --git a/docs/lib/passlib.context-options.rst b/docs/lib/passlib.context-options.rst index e799cdf..8a6a19e 100644 --- a/docs/lib/passlib.context-options.rst +++ b/docs/lib/passlib.context-options.rst @@ -34,7 +34,9 @@ of the :class:`!CryptContext` instance itself: Potential names can include the name of any class importable from the :mod:`passlib.hash` module. For example, to specify the :class:`passlib.hash.sha256_crypt` and the :class:`passlib.hash.des_crypt` schemes - should be supported for your new context, set ``schemes=["sha256_crypt", "des_crypt"]``. + should be supported for your new context:: + + >>> myctx = CryptContext(schemes=["sha256_crypt", "des_crypt"]) ``deprecated`` diff --git a/docs/lib/passlib.hash.atlassian_pbkdf2_sha1.rst b/docs/lib/passlib.hash.atlassian_pbkdf2_sha1.rst new file mode 100644 index 0000000..beed5ca --- /dev/null +++ b/docs/lib/passlib.hash.atlassian_pbkdf2_sha1.rst @@ -0,0 +1,60 @@ +=========================================================================== +:class:`passlib.hash.atlassian_pbkdf2_sha1` - Atlassian's PBKDF2-based Hash +=========================================================================== + +.. index:: atlassian, pbkdf2; password hash + +.. currentmodule:: passlib.hash + +This class provides an implementation of +the PBKDF2 based hash used by Atlassian in Jira and other products. +Note that unlike the most PBKDF2 hashes supported by Passlib, +this one uses a fixed number of rounds (10000). That is currently +a sufficient amount, but it cannot be altered; so this +scheme should only be used to read existing hashes, and not +used in new applications. + +.. seealso:: + + :doc:`passlib.hash.pbkdf2_digest <passlib.hash.pbkdf2_digest>` + for some other PBKDF2-based hashes. + +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>`. + +Interface +========= +.. autoclass:: atlassian_pbkdf2_sha1() + +Format & Algorithm +================== + +All of this scheme's hashes have the format :``{PKCS5S2}<data>``, +where :samp:`<data>` is a 64 character base64 encoded string; +which (when decoded), contains a 16 byte salt, +and a 32 byte checksum. + +A example hash (of ``password``) is: + + ``{PKCS5S2}DQIXJU038u4P7FdsuFTY/+35bm41kfjZa57UrdxHp2Mu3qF2uy+ooD+jF5t1tb8J`` + +Once decoded, the salt value (in hexdecimal octets) is: + + ``0d0217254d37f2ee0fec576cb854d8ff`` + +and the checksum value (in hexidecimal octets) is: + + ``edf96e6e3591f8d96b9ed4addc47a7632edea176bb2fa8a03fa3179b75b5bf09`` + +When calculating the checksum: +the password is encoded into UTF-8 if not already encoded. +Using the specified salt, and a fixed 10000 rounds, +PBKDF2-HMAC-SHA1 is used to generate a 32 byte key, +which appended to the salt and encoded in base64. + +References +========== +.. [#pbkdf2] The specification for the PBKDF2 algorithm - `<http://tools.ietf.org/html/rfc2898#section-5.2>`_. diff --git a/docs/lib/passlib.hash.dlitz_pbkdf2_sha1.rst b/docs/lib/passlib.hash.dlitz_pbkdf2_sha1.rst new file mode 100644 index 0000000..c220c9f --- /dev/null +++ b/docs/lib/passlib.hash.dlitz_pbkdf2_sha1.rst @@ -0,0 +1,66 @@ +======================================================================== +:class:`passlib.hash.dlitz_pbkdf2_sha1` - Dwayne Litzenger's PBKDF2 hash +======================================================================== + +.. index:: pbkdf2; password hash + +.. currentmodule:: passlib.hash + +This class provides an implementation of Dwayne Litzenberger's +PBKDF2-HMAC-SHA1 hash format [#dlitz]_. PBKDF2 is a key derivation function [#pbkdf2]_ +that is ideally suited as the basis for a password hash, as it provides +variable length salts, variable number of rounds. + +.. seealso:: + + :doc:`passlib.hash.pbkdf2_digest <passlib.hash.pbkdf2_digest>` + for some other PBKDF2-based hashes. + +Usage +===== +This class support both rounds and salts, +and can be used in the exact same manner +as :doc:`SHA-512 Crypt <passlib.hash.sha512_crypt>`. + +Interface +========= +.. autoclass:: dlitz_pbkdf2_sha1() + +.. rst-class:: html-toggle + +Format & Algorithm +================== + +A example hash (of ``password``) is: + + ``$p5k2$2710$.pPqsEwHD7MiECU0$b8TQ5AMQemtlaSgegw5Je.JBE3QQhLbO``. + +All of this scheme's hashes have the format :samp:`$p5k2${rounds}${salt}${checksum}`, +where: + +* ``$p5k2$`` is used as the :ref:`modular-crypt-format` identifier. + +* :samp:`{rounds}` is the number of PBKDF2 iterations to perform, + stored as lowercase hexidecimal number with no zero-padding (in the example: ``2710`` or 10000 iterations). + +* :samp:`{salt}` is the salt string, which can be any number of characters, + drawn from the :ref:`hash64 charset <h64charset>` + (``.pPqsEwHD7MiECU0`` in the example). + +* :samp:`{checksum}` is 32 characters, which encode + the resulting 24-byte PBKDF2 derived key using :func:`~passlib.utils.adapted_b64_encode` + (``b8TQ5AMQemtlaSgegw5Je.JBE3QQhLbO`` in the example). + +In order to generate the checksum, the password is first encoded into UTF-8 if it's unicode. +Then, the entire configuration string (all of the hash except the checksum, ie :samp:`$p5k2${rounds}${salt}`) +is used as the PBKDF2 salt. PBKDF2 is called using the encoded password, the full salt, +the specified number of rounds, and using HMAC-SHA1 as it's psuedorandom function. +24 bytes of derived key are requested, and the resulting key is encoded and used +as the checksum portion of the hash. + +References +========== + +.. [#dlitz] The reference for this hash format - `<http://www.dlitz.net/software/python-pbkdf2/>`_. + +.. [#pbkdf2] The specification for the PBKDF2 algorithm - `<http://tools.ietf.org/html/rfc2898#section-5.2>`_. diff --git a/docs/lib/passlib.hash.grub_pbkdf2_sha512.rst b/docs/lib/passlib.hash.grub_pbkdf2_sha512.rst new file mode 100644 index 0000000..a9673d3 --- /dev/null +++ b/docs/lib/passlib.hash.grub_pbkdf2_sha512.rst @@ -0,0 +1,84 @@ +============================================================= +:class:`passlib.hash.grub_pbkdf2_sha512` - Grub's PBKDF2 Hash +============================================================= + +.. index:: pbkdf2; password hash + +.. currentmodule:: passlib.hash + +This class provides an implementation of Grub's PBKDF2-HMAC-SHA512 +password hash [#grub]_, as generated by the :command:`grub-mkpasswd-pbkdf2` command, +and may be found in Grub2 configuration files. +PBKDF2 is a key derivation function [#pbkdf2]_ +that is ideally suited as the basis for a password hash, as it provides +variable length salts, variable number of rounds. + +.. seealso:: + + :doc:`passlib.hash.pbkdf2_digest <passlib.hash.pbkdf2_digest>` + for some other PBKDF2-based hashes. + +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>`. + +Interface +========= +.. autoclass:: grub_pbkdf2_sha512() + +Format & Algorithm +================== + +A example hash (of ``password``) is :: + + grub.pbkdf2.sha512.10000.4483972AD2C52E1F590B3E2260795FDA9CA0B07B + 96FF492814CA9775F08C4B59CD1707F10B269E09B61B1E2D11729BCA8D62B7827 + B25B093EC58C4C1EAC23137.DF4FCB5DD91340D6D31E33423E4210AD47C7A4DF9 + FA16F401663BF288C20BF973530866178FE6D134256E4DBEFBD984B652332EED3 + ACAED834FEA7B73CAE851D + +All of this scheme's hashes have the format :samp:`grub.pbkdf2.sha512.{rounds}.{salt}.{checksum}`, +where :samp:`{rounds}` is the number of iteration stored in decimal, +:samp:`{salt}` is the salt string encoded using upper-case hexdecimal, +and :samp:`{checksum}` is the resulting 64-byte derived key, also +encoded in upper-case hexidecimal. It can be identified by the prefix ``grub.pdkdf2.sha512.``. + +The algorithm used is the same as :class:`pbkdf2_sha1`: the password is encoded into UTF-8 if not already encoded, +and passed through :func:`~passlib.utils.pbkdf2.pbkdf2` +along with the decoded salt, and the number of rounds. +The result is then encoded into hexidecimal. + +.. + Hash Translation + ---------------- + Note that despite encoding and format differences, + :class:`pbkdf2_sha512` and :class:`!grub_pbkdf2_sha512` share an identical algorithm, + and one can be converted to the other using the following code:: + + >>> from passlib.hash import pbkdf2_sha512, grub_pbkdf2_sha512 + + >>> #given a pbkdf2_sha512 hash... + >>> h = pbkdf2_sha512.encrypt("password") + >>> h + '$pbkdf2-sha512$6400$y6vYff3SihJiqumIrNXwGw$NobVwyUlVI52/Cvrguwli5fX6XgKHNUf7fWWS2VgoWEevaTCiZx4OCYhwGFwzUAuz/g1zQVSIf.9JEb0BEVEEA' + + >>> #it can be parsed into options + >>> hobj = pbkdf2_sha512.from_string(h) + >>> rounds, salt, chk = hobj.rounds, hobj.salt, hobj.checksum + + >>> #and a new grub hash can be created + >>> gobj = grub_pbkdf2_sha512(rounds=rounds, salt=salt, checksum=chk) + >>> g = gobj.to_string() + >>> g + + >>> grub_pbkdf2_sha512.verify("password", g) + True + +References +========== + +.. [#grub] Information about Grub's password hashes - `<http://grub.enbug.org/Authentication>`_. + +.. [#pbkdf2] The specification for the PBKDF2 algorithm - `<http://tools.ietf.org/html/rfc2898#section-5.2>`_. diff --git a/docs/lib/passlib.hash.ldap_crypt.rst b/docs/lib/passlib.hash.ldap_crypt.rst new file mode 100644 index 0000000..04e6f93 --- /dev/null +++ b/docs/lib/passlib.hash.ldap_crypt.rst @@ -0,0 +1,73 @@ +=========================================================== +:samp:`passlib.hash.ldap_{crypt}` - LDAP crypt() Wrappers +=========================================================== + +.. currentmodule:: passlib.hash + +Passlib provides support for all the standard +LDAP hash formats specified by :rfc:`2307`. +One of these, identified by RFC 2307 as the ``{CRYPT}`` scheme, +is somewhat different from the others. +Instead of specifying a password hashing scheme, +it's supposed to wrap the host OS's :func:`!crypt()`. + +Being host-dependant, the actual hashes supported +by this scheme may differ greatly between host systems. +In order to provide uniform support across platforms, +Passlib defines a corresponding :samp:`ldap_{xxx}_crypt` scheme +for each of the :ref:`standard unix hashes <standard-unix-hashes>`. + +.. seealso:: + + * :doc:`passlib.hash.ldap_std` - the other standard LDAP hashes. + + * :mod:`!passlib.apps` for a :ref:`list of premade ldap contexts <ldap-contexts>`. + +Usage +===== +These classes all wrap the underlying implementations, +and are mainly useful only for plugging them into a :class:`~passlib.context.CryptContext`. +However, they can be used directly as follows:: + + >>> from passlib.hash import ldap_md5_crypt as lmc + + >>> #encrypt password + >>> h = lmc.encrypt("password") + >>> h + '{CRYPT}$1$gwvn5BO0$3dyk8j.UTcsNUPrLMsU6/0' + + >>> lmc.identify(h) #check if hash is recognized + True + >>> lmc.identify('JQMuyS6H.AGMo') #check if some other hash is recognized + False + + >>> lmc.verify("password", h) #verify correct password + True + >>> lmc.verify("secret", h) #verify incorrect password + False + +Interface +========= +.. class:: ldap_des_crypt() +.. class:: ldap_bsdi_crypt() +.. class:: ldap_md5_crypt() +.. class:: ldap_bcrypt() +.. class:: ldap_sha1_crypt() +.. class:: ldap_sha256_crypt() +.. class:: ldap_sha512_crypt() + + All of these classes have the same interface as their corresponding + underlying hash (eg :class:`des_crypt`, :class:`md5_crypt`, etc). + +.. note:: + + In order to determine if a particular hash is actually supported + natively by your host OS, use an test such as + ``ldap_des_crypt.has_backend("os_crypt")`` or similar. + +References +========== + +.. [#pwd] The manpage for :command:`slappasswd` - `<http://gd.tuwien.ac.at/linuxcommand.org/man_pages/slappasswd8.html>`_. + +.. [#rfc] The basic format for these hashes is laid out in RFC 2307 - `<http://www.ietf.org/rfc/rfc2307.txt>`_ diff --git a/docs/lib/passlib.hash.ldap_digests.rst b/docs/lib/passlib.hash.ldap_digests.rst deleted file mode 100644 index 28f02a0..0000000 --- a/docs/lib/passlib.hash.ldap_digests.rst +++ /dev/null @@ -1,105 +0,0 @@ -=========================================================== -:samp:`passlib.hash.ldap_{digest}` - LDAP / RFC2307 Digests -=========================================================== - -.. currentmodule:: passlib.hash - -PassLib provides support for a most of the hashes -used by LDAP, as stored in the :rfc:`2307` format. -This includes ``{MD5}``, ``{SMD5}``, ``{SHA}``, ``{SSHA}``. -Many of these schemes are somewhat to very insecure, -and should not be used except when required. -The ``{CRYPT}`` scheme is supported by individual handlers -for each underlying crypt algorithm. - -.. seealso:: - - :mod:`!passlib.apps` for a :ref:`list of premade ldap contexts <ldap-contexts>`. - -Usage -===== -These classes all wrap the underlying hashlib implementations, -and are mainly useful only for plugging them into a :class:`~passlib.context.CryptContext`. -However, they can be used directly as follows:: - - >>> from passlib.hash import ldap_salted_md5 as lsm - - >>> #encrypt password - >>> h = lsm.encrypt("password") - >>> h - '{SMD5}OqsUXNHIhHbznxrqHoIM+ZT8DmE=' - - >>> hs.identify(h) #check if hash is recognized - True - >>> hs.identify('JQMuyS6H.AGMo') #check if some other hash is recognized - False - - >>> hs.verify("password", h) #verify correct password - True - >>> hs.verify("secret", h) #verify incorrect password - False - -Interface -========= -.. autoclass:: ldap_md5() -.. autoclass:: ldap_salted_md5() -.. autoclass:: ldap_sha1() -.. autoclass:: ldap_salted_sha1() -.. autoclass:: ldap_plaintext() - -As well, passlib supports the following `{CRYPT}` schemes, -which wrap their respective underlying unix crypt scheme: - -.. class:: ldap_des_crypt() -.. class:: ldap_bsdi_crypt() -.. class:: ldap_md5_crypt() -.. class:: ldap_bcrypt() -.. class:: ldap_sha1_crypt() -.. class:: ldap_sha256_crypt() -.. class:: ldap_sha512_crypt() - -.. rst-class:: html-toggle - -Format & Algorithm -================== -All of these classes follow a single basic format [#rfc]_: - -ldap_md5, ldap_sha1 - - These hashes have the format :samp:`{prefix}{checksum}`. - - * :samp:`{prefix}` is `{MD5}` for ldap_md5, - and `{SHA}` for ldap_sha1. - * :samp:`{checksum}` is the base64 encoding - of the raw message digest of the password, - using the appropriate digest algorithm. - - An example ldap_md5 hash (of ``password``) is ``{MD5}X03MO1qnZdYdgyfeuILPmQ==``. - An example ldap_sha1 hash (of ``password``) is ``{SHA}W6ph5Mm5Pz8GgiULbPgzG37mj9g=``. - -ldap_salted_md5, ldap_salted_sha1 - - These hashes have the format :samp:`{prefix}{data}`. - - * :samp:`{prefix}` is `{SMD5}` for ldap_salted_md5, - and `{SSHA}` for ldap_salted_sha1. - * :samp:`{data}` is the base64 encoding of :samp:`{checksum}{salt}`; - and in turn :samp:`{salt}` is a 4 byte binary salt, - and :samp:`{checksum}` is the raw digest of the - the string :samp:`{password}{salt}`, - using the appropriate digest algorithm. - - An example hash (of ``password``) is ``{SMD5}jNoSMNY0cybfuBWiaGlFw3Mfi/U=``. - After decoding, this results in a raw salt string ``s\x1f\x8b\xf5``, - and a raw MD5 checksum of ``\x8c\xda\x120\xd64s&\xdf\xb8\x15\xa2hiE\xc3``. - - An example hash (of ``password``) is ``{SSHA}pKqkNr1tq3wtQqk+UcPyA3HnA2NsU5NJ``. - After decoding, this results in a raw salt string ``lS\x93I``, - and a raw SHA1 checksum of ``\xa4\xaa\xa46\xbdm\xab|-B\xa9>Q\xc3\xf2\x03q\xe7\x03c``. - -References -========== - -.. [#pwd] The manpage for :command:`slappasswd` - `<http://gd.tuwien.ac.at/linuxcommand.org/man_pages/slappasswd8.html>`_. - -.. [#rfc] The basic format for these hashes is laid out in RFC 2307 - `<http://www.ietf.org/rfc/rfc2307.txt>`_ diff --git a/docs/lib/passlib.hash.ldap_std.rst b/docs/lib/passlib.hash.ldap_std.rst new file mode 100644 index 0000000..d38c3c0 --- /dev/null +++ b/docs/lib/passlib.hash.ldap_std.rst @@ -0,0 +1,102 @@ +============================================================= +:samp:`passlib.hash.ldap_{digest}` - RFC2307 Standard Digests +============================================================= + +.. currentmodule:: passlib.hash + +Passlib provides support for all the standard +LDAP hash formats specified by :rfc:`2307`. +This includes ``{MD5}``, ``{SMD5}``, ``{SHA}``, ``{SSHA}``. +Many of these schemes are somewhat to very insecure, +and should not be used except when required. + +.. note:: + + RFC 2307 also specifies a ``{CRYPT}`` scheme, + which is supposed to wrap the host OS's :func:`!crypt()`. + Being host-dependant, this scheme is somewhat different, + and is details in :doc:`passlib.hash.ldap_crypt`. + +.. seealso:: + + * :doc:`passlib.hash.ldap_crypt` + + * :mod:`!passlib.apps` for a :ref:`list of premade ldap contexts <ldap-contexts>`. + +Usage +===== +These classes all wrap the underlying hashlib implementations, +and are mainly useful only for plugging them into a :class:`~passlib.context.CryptContext`. +However, they can be used directly as follows:: + + >>> from passlib.hash import ldap_salted_md5 as lsm + + >>> #encrypt password + >>> h = lsm.encrypt("password") + >>> h + '{SMD5}OqsUXNHIhHbznxrqHoIM+ZT8DmE=' + + >>> lms.identify(h) #check if hash is recognized + True + >>> lms.identify('JQMuyS6H.AGMo') #check if some other hash is recognized + False + + >>> lms.verify("password", h) #verify correct password + True + >>> lms.verify("secret", h) #verify incorrect password + False + +Plain Hashes +============ +.. autoclass:: ldap_md5() +.. autoclass:: ldap_sha1() + +These hashes have the format :samp:`{prefix}{checksum}`. + +* :samp:`{prefix}` is `{MD5}` for ldap_md5, and `{SHA}` for ldap_sha1. +* :samp:`{checksum}` is the base64 encoding + of the raw message digest of the password, + using the appropriate digest algorithm. + +An example ldap_md5 hash (of ``password``) is ``{MD5}X03MO1qnZdYdgyfeuILPmQ==``. +An example ldap_sha1 hash (of ``password``) is ``{SHA}W6ph5Mm5Pz8GgiULbPgzG37mj9g=``. + +Salted Hashes +============= +.. autoclass:: ldap_salted_md5() +.. autoclass:: ldap_salted_sha1() + +These hashes have the format :samp:`{prefix}{data}`. + +* :samp:`{prefix}` is `{SMD5}` for ldap_salted_md5, + and `{SSHA}` for ldap_salted_sha1. +* :samp:`{data}` is the base64 encoding of :samp:`{checksum}{salt}`; + and in turn :samp:`{salt}` is a 4 byte binary salt, + and :samp:`{checksum}` is the raw digest of the + the string :samp:`{password}{salt}`, + using the appropriate digest algorithm. + +An example hash (of ``password``) is ``{SMD5}jNoSMNY0cybfuBWiaGlFw3Mfi/U=``. +After decoding, this results in a raw salt string ``s\x1f\x8b\xf5``, +and a raw MD5 checksum of ``\x8c\xda\x120\xd64s&\xdf\xb8\x15\xa2hiE\xc3``. + +An example hash (of ``password``) is ``{SSHA}pKqkNr1tq3wtQqk+UcPyA3HnA2NsU5NJ``. +After decoding, this results in a raw salt string ``lS\x93I``, +and a raw SHA1 checksum of ``\xa4\xaa\xa46\xbdm\xab|-B\xa9>Q\xc3\xf2\x03q\xe7\x03c``. + +Plaintext +========= +.. autoclass:: ldap_plaintext() + +This handler does not hash passwords at all, +rather it encoded them into UTF-8. +The only difference between this class and :class:`passlib.hash.plaintext` +is that this class will NOT recognize any strings using +the ``{SCHEME}HASH`` format. + +References +========== + +.. [#pwd] The manpage for :command:`slappasswd` - `<http://gd.tuwien.ac.at/linuxcommand.org/man_pages/slappasswd8.html>`_. + +.. [#rfc] The basic format for these hashes is laid out in RFC 2307 - `<http://www.ietf.org/rfc/rfc2307.txt>`_ diff --git a/docs/lib/passlib.hash.mysql323.rst b/docs/lib/passlib.hash.mysql323.rst index 7bbc129..81adb09 100644 --- a/docs/lib/passlib.hash.mysql323.rst +++ b/docs/lib/passlib.hash.mysql323.rst @@ -19,7 +19,7 @@ hash algorithm was introduced (see :class:`~passlib.hash.mysql41`). .. seealso:: - :mod:`!passlib.apps` for a :ref:`list of premade mysql contexts <mysql-contexts>`. + :mod:`!passlib.apps` for a list of predefined :ref:`mysql contexts <mysql-contexts>`. Usage ===== diff --git a/docs/lib/passlib.hash.pbkdf2_digest.rst b/docs/lib/passlib.hash.pbkdf2_digest.rst new file mode 100644 index 0000000..1014907 --- /dev/null +++ b/docs/lib/passlib.hash.pbkdf2_digest.rst @@ -0,0 +1,85 @@ +=============================================================== +:samp:`passlib.hash.pbkdf2_{digest}` - Simple PBKDF2 Hashes +=============================================================== + +.. index:: pbkdf2; password hash + +.. currentmodule:: passlib.hash + +PassLib provides three custom hash schemes based on the PBKDF2 [#pbkdf2]_ algorithm +which are compatible with the :ref:`modular crypt format <modular-crypt-format>`: +:class:`pbkdf2_sha1`, :class:`pbkdf2_sha256`, :class:`pbkdf2_sha512`. +They feature variable length salts, variable rounds. + +Security-wise, PBKDF2 is currently one of the leading key derivation functions, +and has no known security issues. +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. + +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>`. + +Interface +========= +.. class:: pbkdf2_sha1() + + except for the choice of message digest, + this class is the same as :class:`pbkdf2_sha512`. + +.. class:: pbkdf2_sha256() + + except for the choice of message digest, + this class is the same as :class:`pbkdf2_sha512`. + +.. autoclass:: pbkdf2_sha512() + +.. rst-class:: html-toggle + +Format & Algorithm +================== +An example :class:`!pbkdf2_sha256` hash (of ``password``): + +``$pbkdf2-sha256$6400$.6UI/S.nXIk8jcbdHx3Fhg$98jZicV16ODfEsEZeYPGHU3kbrUrvUEXOPimVSQDD44``. + +All of the pbkdf2 hashes defined by passlib +follow the same format, :samp:`$pbkdf2-{digest}${rounds}${salt}${checksum}`. + +* :samp:`$pbkdf2-{digest}$`` is used as the :ref:`modular-crypt-format` identifier + (``$pbkdf2-sha256$`` in the example). + +* :samp:`{digest}` - this specifies the particular cryptographic hash + used in conjunction with HMAC to form PBKDF2's pseudorandom function + for that particular hash (``sha256`` in the example). + +* :samp:`{rounds}` - the number of iterations that should be performed. + this is encoded as a positive decimal number with no zero-padding + (``6400`` in the example). + +* :samp:`{salt}` - this is the :func:`adapted base64 encoding <passlib.utils.adapted_b64_encode>` + of the raw salt bytes passed into the PBKDF2 function. + +* :samp:`{checksum}` - this is the :func:`adapted base64 encoding <passlib.utils.adapted_b64_encode>` + of the raw derived key bytes returned from the PBKDF2 function. + Each scheme uses output size of it's specific :samp:`{digest}` + as the size of the raw derived key. This is enlarged + by appromixately 4/3 by the base64 encoding, + resulting in a checksum size of 27, 43, and 86 for each of the respective algorithms. + +The algorithm used by all of these schemes is deliberately identical and simple: +The password is encoded into UTF-8 if not already encoded, +and passed through :func:`~passlib.utils.pbkdf2.pbkdf2` +along with the decoded salt, the number of rounds, +and a prf built from HMAC + the respective message digest. +The result is then encoded using :func:`~passlib.utils.adapted_b64_encode`. + +References +========== +.. [#pbkdf2] The specification for the PBKDF2 algorithm - `<http://tools.ietf.org/html/rfc2898#section-5.2>`_, + part of :rfc:`2898`. + +.. [#hmac-sha1] While SHA1 has fallen to collision attacks, HMAC-SHA1 is still considered secure - `<http://www.schneier.com/blog/archives/2005/02/sha1_broken.html>`_. diff --git a/docs/lib/passlib.hash.pbkdf2_digests.rst b/docs/lib/passlib.hash.pbkdf2_digests.rst deleted file mode 100644 index 666bd83..0000000 --- a/docs/lib/passlib.hash.pbkdf2_digests.rst +++ /dev/null @@ -1,222 +0,0 @@ -========================================================== -:samp:`passlib.hash.pbkdf2_{digest}` - PBKDF2-based Hashes -========================================================== - -.. index:: pbkdf2; password hashes, grub, grub; grub-mkpasswd-pbkdf2 - -.. currentmodule:: passlib.hash - -Overview -======== -PassLib provides support for a number of hashes based -on the PBKDF2 [#pbkdf2]_ algorithm. PBKDF2 is ideally -suited as the basis for a password hash, as it provides -variable length salts, variable number of rounds, -and (in combination with HMAC) can be tailored -to use almost any cryptographic hash as the basis -for it's operation. - -PassLib supports 5 PBKDF2-based hash schemes: - -* PassLib's PBKDF2 hashes -- :class:`!pbkdf2_sha1`, - :class:`!pbkdf2_sha256`, :class:`!pbkdf2_sha512` -- - are three custom schemes defined and provided by PassLib. - They have a straightforward implementation, - and a format almost identical to that of :class:`sha512_crypt`. - Thus, while they are currently only implemented within PassLib, - they should be secure and extremely portable. - -* :class:`!dlitz_pbkdf2_sha1` provides an implementation of Dwayne Litzenberger's - PBKDF2-HMAC-SHA1 hash format [#dlitz]_. - -* :class:`!grub_pbkdf2_sha512` provides an implementation of Grub's PBKDF2-HMAC-SHA512 - password hash [#grub]_, as generated by the :command:`grub-mkpasswd-pbkdf2` command, - and may be found in Grub2 configuration files. - -* :class:`!atlassian_pbkdf2_sha1` provides an implementation of - the PBKDF2 based hash used by Atlassian in Jira and other products. - Note that unlike the above PBKDF2 hashes, this one uses a fixed - number of rounds. - -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>`. - -Interface -========= -.. autoclass:: pbkdf2_sha1() -.. autoclass:: pbkdf2_sha256() -.. autoclass:: pbkdf2_sha512() -.. autoclass:: dlitz_pbkdf2_sha1() -.. autoclass:: grub_pbkdf2_sha512() -.. autoclass:: atlassian_pbkdf2_sha1() - -.. rst-class:: html-toggle - -Format & Algorithm -================== - -Passlib's PBKDF2 Hashes ------------------------ -:class:`!pbkdf2_sha1`, :class:`!pbkdf2_sha256`, :class:`!pbkdf2_sha512` - - An example :class:`!pbkdf2_sha256` hash (of ``password``): - - ``$pbkdf2-sha256$6400$.6UI/S.nXIk8jcbdHx3Fhg$98jZicV16ODfEsEZeYPGHU3kbrUrvUEXOPimVSQDD44``. - - All of the pbkdf2 hashes defined by passlib - follow the same format, :samp:`$pbkdf2-{digest}${rounds}${salt}${checksum}`. - - * :samp:`$pbkdf2-{digest}$`` is used as the :ref:`modular-crypt-format` identifier - (``$pbkdf2-sha256$`` in the example). - - * :samp:`{digest}` - this specifies the particular cryptographic hash - used in conjunction with HMAC to form PBKDF2's pseudorandom function - for that particular hash (``sha256`` in the example). - - * :samp:`{rounds}` - the number of iterations that should be performed. - this is encoded as a positive decimal number with no zero-padding - (``6400`` in the example). - - * :samp:`{salt}` - this is the :func:`adapted base64 encoding <passlib.utils.adapted_b64_encode>` - of the raw salt bytes passed into the PBKDF2 function. - - * :samp:`{checksum}` - this is the :func:`adapted base64 encoding <passlib.utils.adapted_b64_encode>` - of the raw derived key bytes returned from the PBKDF2 function. - Each scheme uses output size of it's specific :samp:`{digest}` - as the size of the raw derived key. This is enlarged - by appromixately 4/3 by the base64 encoding, - resulting in a checksum size of 27, 43, and 86 for each of the respective algorithms. - - The algorithm used by all of these schemes is deliberately identical and simple: - The password is encoded into UTF-8 if not already encoded, - and passed through :func:`~passlib.utils.pbkdf2.pbkdf2` - along with the decoded salt, and the number of rounds. - The result is then encoded using :func:`~passlib.utils.adapted_b64_encode`. - - .. note:: - - The base64 encoding used by these functions uses the same - :mod:`hash64 <passlib.utils.h64>` character set as most - other Unix password hashes, but uses the standard base64 encoding scheme, - instead of hash64's alternate value mapping. - - This was done deliberately to create a simple implementation using - common components, which none-the-less uses the same character set - as existing :ref:`modular-crypt-format` hashes, so it can be - used the same contexts without breaking charset expectations. - -Other PBKDF2 Hashes -------------------- -:class:`!dlitz_pbkdf2_sha1` - - A example hash (of ``password``) is: - - ``$p5k2$2710$.pPqsEwHD7MiECU0$b8TQ5AMQemtlaSgegw5Je.JBE3QQhLbO``. - - All of this scheme's hashes have the format :samp:`$p5k2${rounds}${salt}${checksum}`, - where: - - * ``$p5k2$`` is used as the :ref:`modular-crypt-format` identifier. - - * :samp:`{rounds}` is the number of PBKDF2 iterations to perform, - stored as lowercase hexidecimal number with no zero-padding (in the example: ``2710`` or 10000 iterations). - - * :samp:`{salt}` is the salt string, which can be any number of characters, - drawn from the :ref:`hash64 charset <h64charset>` - (``.pPqsEwHD7MiECU0`` in the example). - - * :samp:`{checksum}` is 32 characters, which encode - the resulting 24-byte PBKDF2 derived key using :func:`~passlib.utils.adapted_b64_encode` - (``b8TQ5AMQemtlaSgegw5Je.JBE3QQhLbO`` in the example). - - In order to generate the checksum, the password is first encoded into UTF-8 if it's unicode. - Then, the entire configuration string (all of the hash except the checksum, ie :samp:`$p5k2${rounds}${salt}`) - is used as the PBKDF2 salt. PBKDF2 is called using the encoded password, the full salt, - the specified number of rounds, and using HMAC-SHA1 as it's psuedorandom function. - 24 bytes of derived key are requested, and the resulting key is encoded and used - as the checksum portion of the hash. - -:class:`!grub_pbkdf2_sha512` - - A example hash (of ``password``) is :: - - grub.pbkdf2.sha512.10000.4483972AD2C52E1F590B3E2260795FDA9CA0B07B - 96FF492814CA9775F08C4B59CD1707F10B269E09B61B1E2D11729BCA8D62B7827 - B25B093EC58C4C1EAC23137.DF4FCB5DD91340D6D31E33423E4210AD47C7A4DF9 - FA16F401663BF288C20BF973530866178FE6D134256E4DBEFBD984B652332EED3 - ACAED834FEA7B73CAE851D - - All of this scheme's hashes have the format :samp:`grub.pbkdf2.sha512.{rounds}.{salt}.{checksum}`, - where :samp:`{rounds}` is the number of iteration stored in decimal, - :samp:`{salt}` is the salt string encoded using upper-case hexdecimal, - and :samp:`{checksum}` is the resulting 64-byte derived key, also - encoded in upper-case hexidecimal. It can be identified by the prefix ``grub.pdkdf2.sha512.``. - - The algorithm used is the same as :class:`pbkdf2_sha1`: the password is encoded into UTF-8 if not already encoded, - and passed through :func:`~passlib.utils.pbkdf2.pbkdf2` - along with the decoded salt, and the number of rounds. - The result is then encoded into hexidecimal. - -:class:`!atlassian_pbkdf2_sha1` - - All of this scheme's hashes have the format :``{PKCS5S2}<data>``, - where :samp:`<data>` is a 64 character base64 encoded string; - which (when decoded), contains a 16 byte salt, - and a 32 byte checksum. - - A example hash (of ``password``) is: - - ``{PKCS5S2}DQIXJU038u4P7FdsuFTY/+35bm41kfjZa57UrdxHp2Mu3qF2uy+ooD+jF5t1tb8J`` - - Once decoded, the salt value (in hexdecimal octets) is: - - ``0d0217254d37f2ee0fec576cb854d8ff`` - - and the checksum value (in hexidecimal octets) is: - - ``edf96e6e3591f8d96b9ed4addc47a7632edea176bb2fa8a03fa3179b75b5bf09`` - - When calculating the checksum: - the password is encoded into UTF-8 if not already encoded. - Using the specified salt, and a fixed 10000 rounds, - PBKDF2-HMAC-SHA1 is used to generate a 32 byte key, - which appended to the salt and encoded in base64. - -Hash Translation ----------------- -Note that despite encoding and format differences, -:class:`!pbkdf2_sha512` and :class:`!grub_pbkdf2_sha512` share an identical algorithm, -and one can be converted to the other using the following code:: - - >>> from passlib.hash import pbkdf2_sha512, grub_pbkdf2_sha512 - - >>> #given a pbkdf2_sha512 hash... - >>> h = pbkdf2_sha512.encrypt("password") - >>> h - '$pbkdf2-sha512$6400$y6vYff3SihJiqumIrNXwGw$NobVwyUlVI52/Cvrguwli5fX6XgKHNUf7fWWS2VgoWEevaTCiZx4OCYhwGFwzUAuz/g1zQVSIf.9JEb0BEVEEA' - - >>> #it can be parsed into options - >>> hobj = pbkdf2_sha512.from_string(h) - >>> rounds, salt, chk = hobj.rounds, hobj.salt, hobj.checksum - - >>> #and a new grub hash can be created - >>> gobj = grub_pbkdf2_sha512(rounds=rounds, salt=salt, checksum=chk) - >>> g = gobj.to_string() - >>> g - - >>> grub_pbkdf2_sha512.verify("password", g) - True - -References -========== - -.. [#hmac-sha1] While SHA1 has fallen to collision attacks, HMAC-SHA1 is still considered secure - `<http://www.schneier.com/blog/archives/2005/02/sha1_broken.html>`_. - -.. [#pbkdf2] The specification for the PBKDF2 algorithm - `<http://tools.ietf.org/html/rfc2898#section-5.2>`_. - -.. [#dlitz] Dwayne C. Litzenberger's PBKDF2 hash - `<http://www.dlitz.net/software/python-pbkdf2/>`_. - -.. [#grub] Information about Grub's password hashes - `<http://grub.enbug.org/Authentication>`_. diff --git a/docs/lib/passlib.hash.phpass.rst b/docs/lib/passlib.hash.phpass.rst index c628005..a185a8c 100644 --- a/docs/lib/passlib.hash.phpass.rst +++ b/docs/lib/passlib.hash.phpass.rst @@ -1,3 +1,5 @@ +.. index:: phpass; portable hash + ================================================================== :class:`passlib.hash.phpass` - PHPass' Portable Hash ================================================================== diff --git a/docs/lib/passlib.hash.plaintext.rst b/docs/lib/passlib.hash.plaintext.rst index d8ad3ac..5d51ac1 100644 --- a/docs/lib/passlib.hash.plaintext.rst +++ b/docs/lib/passlib.hash.plaintext.rst @@ -9,6 +9,11 @@ This is, of course, ridiculously insecure; it is provided for backwards compatibility when migrating existing applications. *It should not be used* for any other purpose. +.. seealso:: + + * :class:`passlib.hash.ldap_plaintext` is probably more appropriate + to use in conjunction with other LDAP style hashes. + Usage ===== This class is mainly useful only for plugging into a :class:`~passlib.context.CryptContext`. diff --git a/docs/lib/passlib.hash.rst b/docs/lib/passlib.hash.rst index ac1afce..8a2e99c 100644 --- a/docs/lib/passlib.hash.rst +++ b/docs/lib/passlib.hash.rst @@ -1,33 +1,55 @@ -============================================ -:mod:`passlib.hash` - Password Hash Schemes -============================================ +============================================== +:mod:`passlib.hash` - Password Hashing Schemes +============================================== .. module:: passlib.hash :synopsis: all password hashes provided by PassLib -This module contains classes implementing each of the password hashes built into -passlib. As well, any external hashes registered using :func:`register_crypt_handler` -will be inserted into this module. +Overview +======== +The :mod:`!passlib.hash` module contains all the password hashes built into Passlib. +Each object within this package implements a different password hashing scheme, +but all have the same uniform interface. The hashes in this module can used in two ways: -Each class within this package implements a single password hashing scheme, -and follows passlib's :ref:`password-hash-api`. -While many applications may find it easier to use a :class:`CryptContext` -instance, or retreive handlers via :func:`get_crypt_handler`, they can -also be imported and used directly from this package, as in the following example: +They can be imported and used directly, as in the following example:: >>> from passlib.hash import md5_crypt - >>> hash = md5_crypt.encrypt("password") + >>> md5_crypt.encrypt("password") + '$1$IU54yC7Y$nI1wF8ltcRvaRHwMIjiJq1' -PassLib contains the following builtin password algorithms: +More commonly, they can be referenced by name +when constructing a custom :doc:`CryptContext <passlib.context>` object, +as in the following example:: + + >>> from passlib.context import CryptContext + >>> #note below that md5_crypt and des_crypt are both names of classes in passlib.hash + >>> pwd_context = CryptContext(["md5_crypt", "des_crypt"]) + >>> pwd_context.encrypt("password") + '$1$2y72Yi12$o6Yu2OyjN.9FiK.9HJ7i5.' + +.. seealso:: + + * the :ref:`password hash api <password-hash-api>` for details of the + interface used by all password hashes in this module. + +.. _mcf-hashes: + +Unix & "Modular Crypt" Hashes +============================= +Aside from the "archaic" schemes below, most modern Unix flavors +use password hashes which follow the :ref:`modular crypt format <modular-crypt-format>`, +allowing them to be easily distinguished when used within the same file. +The basic format :samp:`${scheme}${hash}` has also been adopted for use +by other applications and password hash schemes. .. _archaic-unix-schemes: Archaic Unix Schemes -------------------- -All these schemes are/were used by various unix flavors to store user passwords; -most are based on the DES block cipher, -and predate the arrival of the :ref:`modular crypt format <modular-crypt-format>`. -There are all considered insecure (at best), but may be useful when reading +All of the following hashes are/were used by various Unix flavors +to store user passwords; most are based on the DES block cipher, +and predate the arrival of the modular crypt format. +They should all be considered insecure at best, but may be useful when reading legacy password entries: .. toctree:: @@ -38,10 +60,12 @@ legacy password entries: passlib.hash.bigcrypt passlib.hash.crypt16 +.. _standard-unix-hashes: + Standard Unix Schemes --------------------- -All these schemes are currently used by various unix flavors to store user passwords. -They all follow the :ref:`modular crypt format <modular-crypt-format>` for encoding idenfiable hashes. +All these schemes are currently used by various Unix flavors to store user passwords. +They all follow the modular crypt format. .. toctree:: :maxdepth: 1 @@ -53,12 +77,11 @@ They all follow the :ref:`modular crypt format <modular-crypt-format>` for encod passlib.hash.sha256_crypt passlib.hash.sha512_crypt -Non-Standard Unix-Compatible Schemes ------------------------------------- -While most of these schemes are not commonly used by any unix flavor to store user passwords, -these are compatible with the :ref:`modular crypt format <modular-crypt-format>`, and can be -used in contexts which support them, in parallel with the others following -the modular crypt format. +Other Modular Crypt Schemes +--------------------------- +While most of these schemes are not (commonly) used by any Unix flavor to store user passwords, +these are compatible with the modular crypt format, and can be used +compatible by along side others in this section. .. toctree:: :maxdepth: 1 @@ -66,10 +89,72 @@ the modular crypt format. passlib.hash.apr_md5_crypt passlib.hash.phpass passlib.hash.nthash - passlib.hash.pbkdf2_digests + passlib.hash.pbkdf2_digest + passlib.hash.dlitz_pbkdf2_sha1 + +Special note should be made of the fallback helper, +which is not an actual hash scheme, but provides "disabled account" +behavior found in many Linux & BSD password files: + +.. toctree:: + :maxdepth: 1 + + passlib.hash.unix_fallback + +.. _ldap-hashes: + +LDAP / RFC2307 Hashes +===================== + +All of the following hashes use a variant of the password hash format +used by LDAPv2. Originally specified in :rfc:`2307` and used by OpenLDAP [#openldap]_, +the basic format ``{SCHEME}HASH`` has seen widespread adoption in a number of programs. + +.. _standard-ldap-hashes: + +Standard LDAP Schemes +--------------------- +.. toctree:: + :hidden: + + passlib.hash.ldap_std -Database Schemes ----------------- +The following schemes are explicitly defined by RFC 2307, +and are supported by OpenLDAP. + +* :class:`passlib.hash.ldap_md5` - MD5 digest +* :class:`passlib.hash.ldap_sha1` - SHA1 digest +* :class:`passlib.hash.ldap_salted_md5` - salted MD5 digest +* :class:`passlib.hash.ldap_salted_sha1` - salted SHA1 digest + +.. toctree:: + :maxdepth: 1 + + passlib.hash.ldap_crypt + +Also present is a special handler for LDAP plaintext passwords: + +* :class:`passlib.hash.ldap_plaintext` - LDAP-Aware Plaintext Handler + +Non-Standard LDAP Schemes +------------------------- +None of the following schemes are actually used by LDAP, +but follow the LDAP format: + +.. toctree:: + :maxdepth: 1 + + passlib.hash.atlassian_pbkdf2_sha1 + +.. + passlib.hash.roundup_plaintext + passlib.hash.ldap_hex_md5 + passlib.hash.ldap_hex_sha1 + +.. _database-hashes: + +Database Hashes +=============== The following schemes are used by various SQL databases to encode their own user accounts. These schemes have encoding and contextual requirements @@ -84,15 +169,22 @@ not seen outside those specific contexts: passlib.hash.oracle10 passlib.hash.oracle11 -Other Schemes -------------- +.. _other-hashes: + +Other Hashes +============ The following schemes are used in various contexts, -mainly for legacy compatibility purposes. +but have formats or uses which cannot be easily placed +in one of the above categories: .. toctree:: :maxdepth: 1 passlib.hash.hex_digests - passlib.hash.ldap_digests passlib.hash.plaintext - passlib.hash.unix_fallback + passlib.hash.grub_pbkdf2_sha512 + +References +========== + +.. [#openldap] OpenLDAP homepage - `<http://www.openldap.org/>`_. diff --git a/docs/lib/passlib.hosts.rst b/docs/lib/passlib.hosts.rst index 9f8e280..163e1e6 100644 --- a/docs/lib/passlib.hosts.rst +++ b/docs/lib/passlib.hosts.rst @@ -16,32 +16,15 @@ their use is oriented primarily towards Linux and BSD variants. Unix Password Hashes ==================== - -Supported Schemes ------------------ PassLib provides a number of pre-configured :class:`!CryptContext` instances which can identify and manipulate all the formats used by Linux and BSD. -The following chart lists the various operating systems, which -hash algorithms are known to be supported, as well as the hash's -identifying prefix (see the :ref:`modular crypt format <modular-crypt-format>`). - -==================================== ========== =========== =========== =========== =========== -Scheme Prefix Linux FreeBSD NetBSD OpenBSD -==================================== ========== =========== =========== =========== =========== -:class:`~passlib.hash.nthash` ``$3$`` y -:class:`~passlib.hash.des_crypt` n/a y y y y -:class:`~passlib.hash.bsdi_crypt` ``_`` y y -:class:`~passlib.hash.md5_crypt` ``$1$`` y y y y -:class:`~passlib.hash.bcrypt` ``$2a$`` y y y -:class:`~passlib.hash.sha1_crypt` ``$sha1$`` y -:class:`~passlib.hash.sha256_crypt` ``$5$`` y -:class:`~passlib.hash.sha512_crypt` ``$6$`` y -==================================== ========== =========== =========== =========== =========== +See the :ref:`modular crypt identifier list <mcf-identifiers>` for a complete +list of which hashes are supported by which operating system. Predefined Contexts ------------------- PassLib provides :class:`!CryptContext` instances -for the following Unix variants listed in `supported schemes`_: +for the following Unix variants: .. data:: linux_context @@ -116,97 +99,6 @@ Current Host OS In version 1.3 and earlier, it was available on non-Unix systems, though it did nothing useful. -.. _modular-crypt-format: -.. rst-class:: html-toggle - -Modular Crypt Format --------------------- - -Historically, most unix systems supported only :class:`~passlib.hash.des_crypt`. -Around the same time, many incompatible variations were also developed, -but their hashes were not easily distingiushable from each other -(see :ref:`archaic-unix-schemes`); making it impossible to use -multiple hashes on one system, or progressively migrate to a newer scheme. - -This was solved with the advent of the *Modular Crypt Format*, -introduced around the time that :class:`~passlib.hash.md5_crypt` was developed. -This format allows hashs from multiple schemes to exist within the same -database, by requiring that all hash strings begin with a unique prefix -using the format :samp:`${identifier}$`. - -Unfortunately, there is no specification document for this format. -Instead, it exists in *de facto* form only; the following -is an attempt to roughly identify the guidelines followed -by the modular crypt format hashes: - -1. Hash strings must use only 7-bit ascii characters. - - This is not strictly enforced at all; - for example Linux will accept 8-bit characters - within hash salt strings. However, **no** known - system generates hashes violating this rule; - and no such test vectors exist either, - so it can probably be assumed to be a case - of "permissive in what you accept, strict in what you generate". - -2. Hash strings should always start with the prefix :samp:`${identifier}$`, - where :samp:`{identifier}` is a short string uniquely identifying - hashes generated by that algorithm, using only lower case ascii - letters, numbers, and hyphens. - - Initially, most schemes adhereing to this format - only used a single digit to identify the hash - (eg ``$1$`` for :class:`!md5_crypt`). - Because of this, many systems only look at the first - character when attempting to distinguish hashes. - - Despite this, as Unix systems have branched off, - new hashes have been developed which used larger - identifying strings (eg ``$sha1$`` for :class:`sha1_crypt`); - so in general identifier strings should not be assumed to use a single character. - -3. Aside from the prefix, hashes should contain only ascii letters, - ascii numbers, and the characters in ``./``; though ``$`` - may be used as an internal field separator. - - This is the least adhered-to of any modular crypt format rule. - Other characters (such as ``=``, ``,``) are sometimes - used by various formats. - - The only hard and fast stricture - is that ``:`` and non-printable characters be avoided, - since this would interfere with parsing of /etc/passwd - where these hashes are typically stored. - - Pretty much all modular-crypt-format hashes - use ascii letters, numbers, ``.``, and ``/`` - to provide base64 encoding of their raw data, - though the exact character value assignments vary between hashes - (see :mod:`passlib.utils.h64`). - -4. Hash schemes should put their "checksum" portion - at the end of the hash, preferrably separated - by a ``$``. - - This allows password hashes to be easily truncated - to a "configuration string" containing just - the identifying prefix, rounds, salt, etc. - - This string then encodes all the information - generated needed to generate a new hash - in order to verify a password, without - having to perform excessive parsing. - - Most modular crypt format hashes follow this, - though some (like :class:`~passlib.hash.bcrypt`) omit the ``$`` separator. - -.. note:: - - All of the above is guesswork based on examination of existing - hashes and OS implementations; and was written merely - to clarify the issue of what the "modular crypt format" is. - It is drawn from no authoritative sources. - References ========== diff --git a/docs/lib/passlib.registry.rst b/docs/lib/passlib.registry.rst index 2d7a8a4..02efd91 100644 --- a/docs/lib/passlib.registry.rst +++ b/docs/lib/passlib.registry.rst @@ -21,11 +21,11 @@ Interface .. note:: - All password hashes registered with passlib are exposed as objects - importable from :mod:`passlib.hash`. This is true not just of the builtin - classes, but ones that are registered using the functions below. - The :mod:`!passlib.hash` module acts as a proxy object for this registry, - changes made here will affect it as well. + All password hashes registered with passlib + can be imported by name from the :mod:`passlib.hash` module. + This is true just just of the built-in hashes, + but for any hash registered with the registration functions + in this module. Usage ===== |