Navigation

SHA-256 Crypt and SHA-512 Crypt were developed in 2008 by Ulrich Drepper [1],
designed as the successor to md5_crypt.
They include fixes and advancements such as variable rounds, and use of NIST-approved cryptographic primitives.
The design involves repeated composition of the underlying digest algorithm,
using various arbitrary permutations of inputs.
SHA-512 / SHA-256 Crypt are currently the default password hash for many systems
(notably Linux), and have no known weaknesses.
SHA-256 Crypt is one of the three hashes Passlib recommends
for new applications.
This class can be used directly as follows:

salt (str) – Optional salt string.
If not specified, one will be autogenerated (this is recommended).
If specified, it must be 0-16 characters, drawn from the regexp range [./0-9A-Za-z].

rounds (int) – Optional number of rounds to use.
Defaults to 110000, must be between 1000 and 999999999, inclusive.

implicit_rounds (bool) –

this is an internal option which generally doesn’t need to be touched.

this flag determines whether the hash should omit the rounds parameter
when encoding it to a string; this is only permitted by the spec for rounds=5000,
and the flag is ignored otherwise. the spec requires the two different
encodings be preserved as they are, instead of normalizing them.

relaxed (bool) –

By default, providing an invalid value for one of the other
keywords will result in a ValueError. If relaxed=True,
and the error can be corrected, a PasslibHashWarning
will be issued instead. Correctable errors include rounds
that are too small or too large, and salt strings that are too long.

This implementation of sha256-crypt differs from the specification,
and other implementations, in a few ways:

Zero-Padded Rounds:

The specification does not specify how to deal with zero-padding
within the rounds portion of the hash. No existing examples
or test vectors have zero padding, and allowing it would
result in multiple encodings for the same configuration / hash.
To prevent this situation, Passlib will throw an error if the rounds
parameter in a hash has leading zeros.

Restricted salt string character set:

The underlying algorithm can unambiguously handle salt strings
which contain any possible byte value besides \x00 and $.
However, Passlib strictly limits salts to the
hash64 character set,
as nearly all implementations of sha256-crypt generate
and expect salts containing those characters,
but may have unexpected behaviors for other character values.

Unicode Policy:

The underlying algorithm takes in a password specified
as a series of non-null bytes, and does not specify what encoding
should be used; though a us-ascii compatible encoding
is implied by nearly all implementations of sha256-crypt
as well as all known reference hashes.

In order to provide support for unicode strings,
Passlib will encode unicode passwords using utf-8
before running them through sha256-crypt. If a different
encoding is desired by an application, the password should be encoded
before handing it to Passlib.