Password Hash Interface
Overview
While the exact options and behavior will vary between algorithms,
all of the hashes provided by Passlib use the same interface,
defined by the following abstract base class:
-
class passlib.ifc.PasswordHash
This class provides an abstract interface for
an arbitrary password hashing algorithm.
While it offers a number of methods and attributes,
but most applications will only need the two primary methods:
- encrypt() - generate new salt, return hash of password.
- verify() - verify password against existing hash.
While not needed by most applications, the following methods
provide an interface that mimics the traditional Unix crypt()
function:
- genconfig() - create configuration string from salt & other options.
- genhash() - hash password using existing hash or configuration string.
One additional support method is provided:
- identify() - check if hash belongs to this algorithm.
Each hash algorithm also provides a number of informational attributes,
allowing programmatic inspection of it’s options and parameter limits.
Usage Examples
The following code shows how to use the primary
methods of the PasswordHash interface –
encrypt() and verify() –
using the sha256_crypt hash as an example:
>>> # import the handler class
>>> from passlib.hash import sha256_crypt
>>> # hash a password using the default settings:
>>> hash = sha256_crypt.encrypt("password")
>>> hash
'$5$rounds=40000$HIo6SCnVL9zqF8TK$y2sUnu13gp4cv0YgLQMW56PfQjWaTyiHjVbXTgleYG9'
>>> # note that each call to encrypt() generates a new salt,
>>> # and thus the contents of the hash will differ, despite using the same password:
>>> sha256_crypt.encrypt("password")
'$5$rounds=40000$1JfxoiYM5Pxokyh8$ez8uV8jjXW7SjpaTg2vHJmx3Qn36uyZpjhyC9AfBi7B'
>>> # if the hash supports a variable number of iterations (which sha256_crypt does),
>>> # 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:
>>> sha256_crypt.verify("password", hash)
True
>>> sha256_crypt.verify("letmeinplz", hash)
False
Note
Whether a hash supports a particular configuration keywoard (such as rounds)
can be determined from it’s documentation page; but also programmatically from
it’s setting_kwds attribute.
That concludes the most basic example, but there are a few more
common use-cases, such as how to use the identify() method:
>>> # attempting to call verify() with another algorithm's hash will result in a ValueError:
>>> from passlib.hash import sha256_crypt, md5_crypt
>>> other_hash = md5_crypt.encrypt("password")
>>> sha256_crypt.verify("password", other_hash)
Traceback (most recent call last):
<traceback omitted>
ValueError: not a valid sha256_crypt hash
>>> # this can be prevented by using the identify method,
>>> # determines whether a hash belongs to a given algorithm:
>>> hash = sha256_crypt.encrypt("password")
>>> sha256_crypt.identify(hash)
True
>>> sha256_crypt.identify(other_hash)
False
While the initial encrypt() example works for most hashes,
a small number of algorithms require you provide external data
(such as a username) every time a hash is calculated.
An example of this is the oracle10 algorithm:
>>> # for oracle10, encrypt requires a username:
>>> from passlib.hash import oracle10
>>> hash = oracle10.encrypt("secret", user="admin")
'B858CE295C95193F'
>>> # the difference between this and something like the rounds setting (above)
>>> # is that oracle10 also requires the username when verifying a hash:
>>> oracle10.verify("secret", hash, user="admin")
True
>>> # if either the username OR password is wrong, verify() will fail:
>>> oracle10.verify("secret", hash, user="wronguser")
False
>>> oracle10.verify("wrongpassword", hash, user="admin")
False
>>> # forgetting to include the username when it's required will cause a TypeError:
>>> hash = oracle10.encrypt("password")
Traceback (most recent call last):
<traceback omitted>
TypeError: user must be unicode or bytes, not None
Note
Whether a hash requires external parameters (such as user)
can be determined from it’s documentation page; but also programmatically from
it’s context_kwds attribute.
Primary Methods
Most applications will only need to use two methods:
encrypt() to generate new hashes, and verify()
to check passwords against existing hashes.
These methods provide an easy interface for working with a password hash,
and abstract away details such as salt generation, hash normalization,
and hash comparison.
-
classmethod PasswordHash.encrypt(secret, **kwds)
Digest password using format-specific algorithm,
returning resulting hash string.
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.
| Parameters: |
- secret (unicode or bytes) – string containing the password to encode.
- **kwds – All additional keywords are algorithm-specific, and will be listed
in that hash’s documentation; though many of the more common keywords
are listed under setting_kwds
and context_kwds.
Examples of common keywords include rounds and salt_size.
|
|---|
| Returns: | Resulting password hash, encoded in an algorithm-specific format.
This will always be an instance of str
(i.e. unicode under Python 3, ascii-encoded bytes under Python 2).
|
|---|
| Raises: |
- ValueError –
- 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 secret contains characters forbidden by the hash algorithm
(e.g. des_crypt forbids NULL characters).
- TypeError –
- if secret is not unicode or 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: nearly all
password hashes use an irreversible cryptographic digest,
rather than a reversible cipher. see issue 21 ).
Changed in version 1.6: Hashes now raise TypeError if a required keyword is missing,
rather than ValueError like in previous releases; in order
to conform with normal Python behavior.
Changed in version 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).
-
classmethod PasswordHash.verify(secret, hash, **context_kwds)
Verify a secret using an existing hash.
This checks if a secret matches against the one stored
inside the specified hash.
| Parameters: |
- secret (unicode or bytes) – A string containing the password to check.
- hash –
A string containing the hash to check against,
such as returned by encrypt().
Hashes may be specified as unicode or
ascii-encoded bytes.
- **kwds –
Very few hashes will have additional keywords.
The ones that do typically require external contextual information
in order to calculate the digest. For these hashes,
the values must match the ones passed to the original
encrypt() call when the hash was generated,
or the password will not verify.
These additional keywords are algorithm-specific, and will be listed
in that hash’s documentation; though the more common keywords
are listed under context_kwds.
Examples of common keywords include user.
|
|---|
| Returns: | 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 kwds which are not provided,
- if a kwd argument has the wrong type.
- ValueError –
- if hash does not match this algorithm’s format.
- if the secret contains forbidden characters (see
encrypt()).
- if a configuration/salt string generated by genconfig()
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).
|
|---|
Changed in version 1.6: This function now raises 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.
Note
Regarding unicode passwords & non-ASCII characters:
For the majority of hash algorithms and use-cases, passwords should
be provided as either unicode or utf-8-encoded bytes.
There are only two major exceptions:
- Some systems have legacy hashes that were generated using a different
character encoding. In this case, all unicode passwords
should be encoded using the correct encoding before they are hashed;
otherwise non-ASCII passwords may not verify() successfully.
- For historical reasons, lmhash uses cp437
as it’s default encoding. It will handle unicode correctly;
but non-ASCII passwords provided as bytes must either be encoded
using "cp437", or lmhash‘s encoding keyword must
be set to indicate which encoding was used.
Crypt Methods
Taken together, the genconfig() and genhash()
are two tightly-coupled methods that mimic the standard Unix
“crypt” interface. The first method generates salt / configuration
strings from a set of settings, and the second hashes the password
using the provided configuration string.
See also
Most applications will find encrypt() much more useful,
as it combines the functionality of these two methods into one.
-
classmethod PasswordHash.genconfig(**setting_kwds)
Returns a configuration string encoding settings for hash generation.
This function takes in all the same setting_kwds
as encrypt(), fills in suitable defaults,
and encodes the settings into a single “configuration” string,
suitable passing to genhash().
| Parameters: | **kwds – All additional keywords are algorithm-specific, and will be listed
in that hash’s documentation; though many of the more common keywords
are listed under setting_kwds
Examples of common keywords include salt and rounds. |
|---|
| Returns: | A configuration string (as str), or None if the scheme
does not support a separate configuration. |
|---|
| Raises ValueError, TypeError: |
|---|
| | This function raises exceptions for the same
reasons as encrypt(). |
Note
This configuration string is typically the same as the full hash string,
except that it lacks the final portion containing the digested password.
This is sometimes referred to as a “salt” string, though it typically
contains much more than just the salt parameter.
-
classmethod PasswordHash.genhash(secret, config, **context_kwds)
Encrypt secret using specified configuration string.
This takes in a password and a configuration string,
and returns a hash for that password.
| Parameters: |
- secret (unicode or bytes) – string containing the password to be encrypted.
- config (unicode or bytes or None) –
configuration string to use when encrypting secret.
this can either be an existing hash that was previously
returned by genhash(), or a configuration string
that was previously created by genconfig().
None is accepted only for the hashes which lack a configuration
string (for which genconfig() always returns None).
- **kwds –
Very few hashes will have additional keywords.
The ones that do typically require external contextual information
in order to calculate the digest. For these hashes,
the values must match the ones passed to the original
encrypt() call when the hash was generated,
or the password will not verify.
These additional keywords are algorithm-specific, and will be listed
in that hash’s documentation; though the more common keywords
are listed under :context_kwds.
Examples of common keywords include user.
|
|---|
| Returns: | Encoded hash matching specified secret, config, and kwds.
This will always be a native str instance.
|
|---|
| Raises ValueError, TypeError: |
|---|
| | This function raises exceptions for the same
reasons as encrypt().
|
Warning
Traditionally, password verification using the “crypt” interface
was done by testing if hash == genhash(password, hash).
This test is only reliable for a handful of algorithms,
as various hash representation issues may cause false results.
Applications are strongly urged to use verify() instead.
Support Methods
There is currently one additional support method, identify():
-
classmethod PasswordHash.identify(hash)
Quickly identify if a hash string belongs to this algorithm.
| Parameters: | hash (unicode or bytes) – the candidate hash string to check |
|---|
| Returns: |
- True if the input is a configuration string or hash string
- identifiable as belonging to this scheme (even if it’s malformed).
- False if the input does not belong to this scheme.
|
|---|
| Raises TypeError: |
|---|
| | if hash is not a unicode or bytes instance. |
Note
A small number of the hashes supported by Passlib lack a reliable
method of identification (e.g. lmhash
and nthash both consist of 32 hexidecimal characters,
with no distinguishing features). For such hashes, this method
may return false positives.
See also
If you are considering using this method to select from multiple
algorithms (e.g. in order to verify a password), you will be better served
by the CryptContext class.
Choosing the right rounds value
For hash algorithms which support a variable time-cost,
Passlib’s default rounds choices attempt to be secure enough for
the average 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 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 periodically
by taking a rough estimate of what an “average” system is capable of,
and then setting all hash.default_rounds values to take ~300ms on such a system.
However, some older algorithms (e.g. 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 much lower than Passlib’s default.
