diff options
Diffstat (limited to 'docs/password_hash_api.rst')
| -rw-r--r-- | docs/password_hash_api.rst | 85 |
1 files changed, 45 insertions, 40 deletions
diff --git a/docs/password_hash_api.rst b/docs/password_hash_api.rst index 19a2b8d..d2ec5d5 100644 --- a/docs/password_hash_api.rst +++ b/docs/password_hash_api.rst @@ -150,9 +150,9 @@ and hash comparison. 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. + For most hashes supported by Passlib, the returned string will contain: + an algorithm identifier, a cost parameter, the salt string, + and finally the password digest itself. :type secret: unicode or bytes :arg secret: string containing the password to encode. @@ -166,28 +166,27 @@ and hash comparison. Examples of common keywords include ``rounds`` and ``salt_size``. :returns: - Resulting hash of password, using an algorithm-specific format. - + Resulting password hash, encoded in an algorithm-specific format. 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 + * If a ``kwd``'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 ``secret`` contains characters forbidden by the hash algorithm (e.g. :class:`!des_crypt` forbids NULL characters). :raises TypeError: - * if ``secret`` is not unicode or bytes. - * if a keyword argument had an incorrect type. - * if a required keyword was not provided. + * if ``secret`` is not :class:`!unicode` or :class:`bytes`. + * if a ``kwd`` argument has an incorrect type. + * if an algorithm-specific required ``kwd`` is not provided. - *(Note that the name of this method is a misnomer, password hashes - are typically based on irreversible cryptographic operations, - see* :issue:`21` *).* + *(Note that the name of this method is a misnomer: nearly all + password hashes use an irreversible cryptographic digest, + rather than a reversible cipher. see* :issue:`21` *).* .. versionchanged:: 1.6 Hashes now raise :exc:`TypeError` if a required keyword is missing, @@ -237,23 +236,23 @@ and hash comparison. ``True`` if the secret matches, otherwise ``False``. :raises TypeError: - * if either *secret* or *hash* is not a unicode or bytes instance. - * if the hash requires additional keywords which are not provided, - or have the wrong type. + * if either ``secret`` or ``hash`` is not a unicode or bytes instance. + * if the hash requires additional ``kwds`` which are not provided, + * if a ``kwd`` argument has the wrong type. :raises ValueError: - * if *hash* does not match this algorithm's format. - * if the secret contains forbidden characters (see + * if ``hash`` does not match this algorithm's format. + * if the ``secret`` contains forbidden characters (see :meth:`~PasswordHash.encrypt`). * if a configuration/salt string generated by :meth:`~PasswordHash.genconfig` - is passed in as the value for *hash* (these strings look + is passed in as the value for ``hash`` (these strings look similar to a full hash, but typically lack the digest portion needed to verify a password). .. versionchanged:: 1.6 - This function now raises :exc:`ValueError` if a ``None`` or config string is provided - instead of a proper hash; previous releases were inconsistent - in their handling of these cases. + This function now raises :exc:`ValueError` if ``None`` or a config string is provided + instead of a properly-formed hash; previous releases were inconsistent + in their handling of these two border cases. .. _hash-unicode-behavior: @@ -398,14 +397,16 @@ There is currently one additional support method, :meth:`~PasswordHash.identify` .. note:: - Hashes which lack a reliable method of identification may incorrectly - identify each-other's hashes (e.g. both :class:`~passlib.hash.lmhash` - and :class:`~passlib.hash.nthash` hash consist 32 hexidecimal characters). + A small number of the hashes supported by Passlib lack a reliable + method of identification (e.g. :class:`~passlib.hash.lmhash` + and :class:`~passlib.hash.nthash` both consist of 32 hexidecimal characters, + with no distinguishing features). For such hashes, this method + may return false positives. .. seealso:: If you are considering using this method to select from multiple - algorithms in order to verify a password, you may be better served + algorithms (e.g. in order to verify a password), you will be better served by the :ref:`CryptContext <context-overview>` class. .. @@ -518,17 +519,19 @@ the hashes in passlib: .. _relaxed-keyword: ``relaxed`` - By default, passing :meth:`~PasswordHash.encrypt` an invalid - value will result in a :exc:`ValueError`. However, if ``relaxed=True``, - Passlib will attempt to correct the error, and if successful, + By default, passing an invalid value to :meth:`~PasswordHash.encrypt` + will result in a :exc:`ValueError`. However, if ``relaxed=True`` + then Passlib will attempt to correct the error and (if successful) issue a :exc:`~passlib.exc.PasslibHashWarning` instead. This warning may then be filtered if desired. - Correctable errors include (but aren not limited to): ``rounds`` + Correctable errors include (but are not limited to): ``rounds`` and ``salt_size`` values that are too low or too high, ``salt`` - strings that are too large, etc. + strings that are too large. This option is supported by most of the hashes in Passlib. + .. versionadded:: 1.6 + .. attribute:: PasswordHash.context_kwds Tuple listing the keywords supported by :meth:`~PasswordHash.encrypt`, @@ -585,7 +588,7 @@ and the following attributes should be defined: .. attribute:: PasswordHash.min_salt_size The minimum number of bytes/characters required for the salt. - Must be an integer between 0 or :attr:`~PasswordHash.max_salt_size`. + Must be an integer between 0 and :attr:`~PasswordHash.max_salt_size`. .. attribute:: PasswordHash.default_salt_size @@ -619,8 +622,8 @@ and the following attributes should be defined: Rounds Information ------------------ -For schemes which support a variable number of iterations to adjust their time-cost, -``"rounds"`` should be listed in :attr:`~PasswordHash.setting_kwds`, +For schemes which support a variable time-cost parameter, +``"rounds"`` should be listed in their :attr:`~PasswordHash.setting_kwds`, and the following attributes should be defined: .. attribute:: PasswordHash.max_rounds @@ -717,23 +720,25 @@ and the following attributes should be defined: Choosing the right rounds value =============================== -Passlib's default rounds settings attempt to be secure enough for +For hash algorithms which support a variable time-cost, +Passlib's default ``rounds`` choices attempt to be secure enough for the average [#avgsys]_ system. But the "right" value for a given hash is dependant on the server, it's cpu, it's expected load, and it's users. Since larger values mean increased work for an attacker, -**the right** ``rounds`` **value for a given server should be the largest -possible value that doesn't cause intolerable delay for your users**. +*the right* ``rounds`` *value for a given hash & server should be the largest +possible value that doesn't cause intolerable delay for your users*. + For most public facing services, you can generally have signin take upwards of 250ms - 400ms before users start getting annoyed. For superuser accounts, it should take as much time as the admin can stand (usually ~4x more delay than a regular account). -Passlib's ``default_rounds`` values are retuned every major release (at a minimum) +Passlib's ``default_rounds`` values are retuned periodically by taking a rough estimate of what an "average" system is capable of, -and setting all the ``default_rounds`` values to take ~300ms on such a system. +and then setting all :samp:`{hash}.default_rounds` values to take ~300ms on such a system. However, some older algorithms (e.g. :class:`~passlib.hash.bsdi_crypt`) are weak enough that a tradeoff must be made, choosing "secure but intolerably slow" over "fast but unacceptably insecure". -For this reason, it is strongly recommended to not use a value lower than Passlib's default. +For this reason, it is strongly recommended to not use a value much lower than Passlib's default. .. [#avgsys] For Passlib 1.6, all hashes were retuned to take ~250ms on a system with a 3 ghz 64 bit CPU. |