From 445ce2588b45d402a5c06ba7e657aca1b830a4b9 Mon Sep 17 00:00:00 2001 From: Eli Collins Date: Wed, 27 Jun 2012 16:09:04 -0400 Subject: various minor updates to documentation & code comments --- CHANGES | 6 +++--- docs/lib/passlib.hash.pbkdf2_digest.rst | 4 ++-- docs/modular_crypt_format.rst | 2 +- docs/password_hash_api.rst | 36 ++++++++++++++++++++++++--------- passlib/utils/des.py | 4 ++-- 5 files changed, 34 insertions(+), 18 deletions(-) diff --git a/CHANGES b/CHANGES index 433deb2..0c58167 100644 --- a/CHANGES +++ b/CHANGES @@ -9,10 +9,10 @@ Release History Minor bugfix release - * FreeBSD 8.3+ has native support for SHA512-Crypt, - updated unittests and documentation accordingly (:issue:`35`) + * *bugfix*: FreeBSD 8.3 added native support for SHA512-Crypt, + updated unittests and documentation accordingly (:issue:`35`). - * Fixed bug in passlib.apache unittest which caused test to fail + * *bugfix:* Fixed bug in passlib.apache unittest which caused test to fail if filesystem had mtime resolution >= 1 second (:issue:`35`). * Various documentation updates and corrections. diff --git a/docs/lib/passlib.hash.pbkdf2_digest.rst b/docs/lib/passlib.hash.pbkdf2_digest.rst index b48f719..522213a 100644 --- a/docs/lib/passlib.hash.pbkdf2_digest.rst +++ b/docs/lib/passlib.hash.pbkdf2_digest.rst @@ -73,7 +73,7 @@ An example :class:`!pbkdf2_sha256` hash (of ``password``):: 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 +* :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 @@ -96,7 +96,7 @@ follow the same format, :samp:`$pbkdf2-{digest}${rounds}${salt}${checksum}`. 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` +and run 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.ab64_encode`. diff --git a/docs/modular_crypt_format.rst b/docs/modular_crypt_format.rst index bab73d1..aa564fb 100644 --- a/docs/modular_crypt_format.rst +++ b/docs/modular_crypt_format.rst @@ -128,7 +128,7 @@ and indicates which operating systems offer native support for them [#gae]_. ==================================== ==================== =========== =========== =========== =========== ======= ======= Scheme Prefix Linux FreeBSD NetBSD OpenBSD Solaris MacOSX ==================================== ==================== =========== =========== =========== =========== ======= ======= -:class:`~passlib.hash.des_crypt` none y y y y y y +:class:`~passlib.hash.des_crypt` y y y y y y :class:`~passlib.hash.bsdi_crypt` ``_`` y y y y :class:`~passlib.hash.md5_crypt` ``$1$`` y y y y y :class:`~passlib.hash.sun_md5_crypt` ``$md5$``, ``$md5,`` y diff --git a/docs/password_hash_api.rst b/docs/password_hash_api.rst index fbaf38d..8d136c2 100644 --- a/docs/password_hash_api.rst +++ b/docs/password_hash_api.rst @@ -67,6 +67,7 @@ using the :class:`~passlib.hash.sha256_crypt` hash as an example:: >>> # you can override the default value via the 'rounds' keyword: >>> sha256_crypt.encrypt("password", rounds=12345) '$5$rounds=12345$UeVpHaN2YFDwBoeJ$NJN8DwVZ4UfQw6.ijJZNWoZtk1Ivi5YfKCDsI2HzSq2' + ^^^^^ >>> # on the other end of things, the verify() method takes care of >>> # checking if a password matches an existing hash string: @@ -146,8 +147,13 @@ and hash comparison. .. classmethod:: PasswordHash.encrypt(secret, \*\*kwds) - Encrypt password, returning resulting hash string. - + Digest password using format-specific algorithm, + returning resulting hash string. + + For most hashes supported by Passlib, this string will include + an algorithm identifier, a copy of the salt (if applicable), + and any other configuration information required to verify the password later. + :type secret: unicode or bytes :arg secret: string containing the password to encode. @@ -157,28 +163,32 @@ and hash comparison. in that hash's documentation; though many of the more common keywords are listed under :attr:`~PasswordHash.setting_kwds` and :attr:`~PasswordHash.context_kwds`. - Examples of common keywords include ``salt`` and ``rounds``. + Examples of common keywords include ``rounds`` and ``salt_size``. :returns: - resulting hash, using an algorithm-specific format. + Resulting hash of password, using an algorithm-specific format. - this will use the native :class:`!str` type - (unicode under Python 3, ``ascii``-encoded bytes under Python 2). + This will always be an instance of :class:`!str` + (i.e. :class:`unicode` under Python 3, ``ascii``-encoded :class:`bytes` under Python 2). :raises ValueError: * If a keyword's value is invalid (e.g. if a ``salt`` string is too small, or a ``rounds`` value is out of range). - * If the *secret* contains characters forbidden by the handler + * If the ``secret`` contains characters forbidden by the handler (e.g. :class:`!des_crypt` forbids NULL characters). :raises TypeError: - * if :samp:`{secret}` is not unicode or bytes. + * if ``secret`` is not unicode or bytes. * if a keyword argument had an incorrect type. * if a required keyword was not provided. + *(Note that the name of this method is a misnomer, password hashes + are typically based on irreversible cryptographic operations, + see* :issue:`21` *).* + .. versionchanged:: 1.6 Hashes now raise :exc:`TypeError` if a required keyword is missing, rather than :exc:`ValueError` like in previous releases; in order @@ -187,7 +197,8 @@ and hash comparison. .. versionchanged:: 1.6 Passlib is now much stricter about input validation: for example, out-of-range ``rounds`` values now cause an error instead of being - clipped (though applications may set ``relaxed=True`` to restore the old behavior). + clipped (though applications may set :ref:`relaxed=True ` + to restore the old behavior). .. classmethod:: PasswordHash.verify(secret, hash, \*\*context_kwds) @@ -202,7 +213,8 @@ and hash comparison. :type secret: unicode or bytes :param hash: - A string containing the hash to check against. + A string containing the hash to check against, + such as returned by :meth:`~encrypt`. Hashes may be specified as :class:`!unicode` or ``ascii``-encoded :class:`!bytes`. @@ -266,6 +278,8 @@ and hash comparison. .. _crypt-methods: +.. rst-class:: html-toggle + Crypt Methods ============= Taken together, the :meth:`~PasswordHash.genconfig` and :meth:`~PasswordHash.genhash` @@ -500,6 +514,8 @@ the hashes in passlib: .. index:: single: relaxed; PasswordHash keyword + + .. _relaxed-keyword: ``relaxed`` By default, passing :meth:`~PasswordHash.encrypt` an invalid diff --git a/passlib/utils/des.py b/passlib/utils/des.py index f21de4d..0422197 100644 --- a/passlib/utils/des.py +++ b/passlib/utils/des.py @@ -622,11 +622,11 @@ def expand_des_key(key): else: raise exc.ExpectedTypeError(key, "bytes or int", "key") key = _unpack56(key) - # NOTE: this function would insert correctly-valued parity bits in each key, + # NOTE: the following would insert correctly-valued parity bits in each key, # but the parity bit would just be ignored in des_encrypt_block(), # so not bothering to use it. ##return join_byte_values(expand_7bit((key >> shift) & 0x7f) - # for shift in _EXPAND_ITER) + ## for shift in _EXPAND_ITER) return join_byte_values(((key>>shift) & 0x7f)<<1 for shift in _EXPAND_ITER) def shrink_des_key(key): -- cgit v1.2.1