SHA-256 Crypt — Passlib v1.7.4 Documentation (2024)

See also

• password hash usage – for more usage examples
• sha512_crypt – the companion 512-bit version of this hash.

Interface¶

class passlib.hash.sha256_crypt¶

This class implements the SHA256-Crypt password hash, and follows the PasswordHash API.

It supports a variable-length salt, and a variable number of rounds.

The using() method accepts the following optional keywords:

Parameters:

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 535000, must be between 1000 and 999999999, inclusive. Note per the official specification, when the rounds parameter is set to 5000,it may be omitted from the hash string. relaxed (bool) – By default, providing an invalid value for one of the otherkeywords will result in a ValueError. If relaxed=True,and the error can be corrected, a PasslibHashWarningwill be issued instead. Correctable errors include roundsthat are too small or too large, and salt strings that are too long. New in version 1.6.

Format & Algorithm¶

An example sha256-crypt hash (of the string password) is:

$5$rounds=80000$wnsT7Yr92oJoP28r$cKhJImk5mfuSKV9b3mumNzlbstFUplKtQXXMo4G6Ep5

An sha256-crypt hash string has the format $5$rounds=rounds$salt$checksum, where:

• $5$ is the prefix used to identify sha256-crypt hashes,following the Modular Crypt Format
• rounds is the decimal number of rounds to use (80000 in the example).
• salt is 0-16 characters drawn from [./0-9A-Za-z], providing a96-bit salt (wnsT7Yr92oJoP28r in the example).
• checksum is 43 characters drawn from the same set, encoding a 256-bitchecksum (cKhJImk5mfuSKV9b3mumNzlbstFUplKtQXXMo4G6Ep5 in the example).

The official implementation allows omitting the rounds section when it’s set to 5000,resulting in an alternate hash format: $5$salt$checksum.(Passlib supports this via the implicit_rounds constructor parameter).

The algorithm used by SHA256-Crypt is laid out in detailin the specification document linked to below [1].

Security Issues¶

• The algorithm’s initialization stage contains a loop which varies linearly with thesquare of the password size; and further loops which vary linearly with thepassword size * rounds.

  • This means an attacker could provide a maliciously large password at the login screento attempt a DOS on a publically visible login. For example, a 32kib passwordwould require hashing 1gib of data.Passlib mitigates this by limiting the maximum password size to 4k by default.
  • An attacker could also theoretically determine a password’s size by observingthe time taken on a successful login, and then attempting verification themselvesto find the size password which has an equivalent delay. This has not been appliedin practice, probably due to the fact that (for normal passwords < 64 bytes),the contribution of the password size to the overall time taken is belowthe observable noise level when evesdropping on the timings of successful loginsfor a single user.

Deviations¶

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-paddingwithin the rounds portion of the hash. No existing examplesor test vectors have zero padding, and allowing it wouldresult in multiple encodings for the same configuration / hash.To prevent this situation, Passlib will throw an error if the roundsparameter in a hash has leading zeros.

• Restricted salt string character set:

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

• Unicode Policy:

  The underlying algorithm takes in a password specifiedas a series of non-null bytes, and does not specify what encodingshould be used; though a us-ascii compatible encodingis implied by nearly all implementations of sha256-cryptas 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 differentencoding is desired by an application, the password should be encodedbefore handing it to Passlib.

Footnotes