passlib.hash.sha256_crypt - SHA-256 Crypt¶
SHA-256 Crypt and SHA-512 Crypt were developed in 2008 by Ulrich Drepper ,
designed as the successor to
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:
>>> from passlib.hash import sha256_crypt >>> # generate new salt, encrypt password >>> hash = sha256_crypt.encrypt("password") >>> hash '$5$rounds=80000$wnsT7Yr92oJoP28r$cKhJImk5mfuSKV9b3mumNzlbstFUplKtQXXMo4G6Ep5' >>> # same, but with explict number of rounds >>> sha256_crypt.encrypt("password", rounds=12345) '$5$rounds=12345$q3hvJE5mn5jKRsW.$BbbYTFiaImz9rTy03GGi.Jf9YY5bmxN0LU3p3uI1iUB' >>> # verify password >>> sha256_crypt.verify("password", hash) True >>> sha256_crypt.verify("letmein", hash) False
This class implements the SHA256-Crypt password hash, and follows the Password Hash Interface.
It supports a variable-length salt, and a variable number of rounds.
- 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
- rounds (int) – Optional number of rounds to use. Defaults to 535000, 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
relaxed=True, and the error can be corrected, a
PasslibHashWarningwill be issued instead. Correctable errors include
roundsthat are too small or too large, and
saltstrings that are too long.
New in version 1.6.
- 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
This class will use the first available of two possible backends:
crypt(), if the host OS supports SHA256-Crypt (most Linux systems).
- a pure python implementation of SHA256-Crypt built into Passlib.
You can see which backend is in use by calling the
Format & Algorithm¶
An example sha256-crypt hash (of the string
An sha256-crypt hash string has the format
$5$is the prefix used to identify sha256-crypt hashes, following the Modular Crypt Format
roundsis the decimal number of rounds to use (80000 in the example).
saltis 0-16 characters drawn from
[./0-9A-Za-z], providing a 96-bit salt (
wnsT7Yr92oJoP28rin the example).
checksumis 43 characters drawn from the same set, encoding a 256-bit checksum (
cKhJImk5mfuSKV9b3mumNzlbstFUplKtQXXMo4G6Ep5in the example).
There is also an alternate format
which can be used when the rounds parameter is equal to 5000
implicit_rounds parameter above).
The algorithm used by SHA256-Crypt is laid out in detail in the specification document linked to below .
This implementation of sha256-crypt differs from the specification, and other implementations, in a few ways:
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
$. However, Passlib strictly limits salts to the
hash64character set, as nearly all implementations of sha256-crypt generate and expect salts containing those characters, but may have unexpected behaviors for other character values.
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-asciicompatible 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-8before running them through sha256-crypt. If a different encoding is desired by an application, the password should be encoded before handing it to Passlib.
|||(1, 2) Ulrich Drepper’s SHA-256/512-Crypt specification, reference implementation, and test vectors - sha-crypt specification|