# `passlib.hash.bcrypt_sha256` - BCrypt+SHA256

Added in version 1.6.2.

BCrypt was developed to replace `md5_crypt` for BSD systems. It uses a modified version of the Blowfish stream cipher. It does, however, truncate passwords to 72 bytes, and some other minor quirks (see BCrypt Password Truncation for details). This class works around that issue by first running the password through HMAC-SHA2-256. This class can be used directly as follows:

    >>> from passlib.hash import bcrypt_sha256

    >>> # generate new salt, hash password
    >>> h = bcrypt_sha256.hash("password")
    >>> h
    '$bcrypt-sha256$v=2,t=2b,r=12$n79VH.0Q2TMWmt3Oqt9uku$Kq4Noyk3094Y2QlB8NdRT8SvGiI4ft2'

    >>> # the same, but with an explicit number of rounds
    >>> bcrypt_sha256.using(rounds=13).hash("password")
    '$bcrypt-sha256$v=2,t=2b,r=13$AmytCA45b12VeVg0YdDT3.$IZTbbJKgJlD5IJoCWhuDUqYjnJwNPlO'

    >>> # verify password
    >>> bcrypt_sha256.verify("password", h)
    True
    >>> bcrypt_sha256.verify("wrong", h)
    False

Note

It is strongly recommended that you install bcrypt when using this hash. See passlib.hash.bcrypt - BCrypt for more details.

## Interface

class passlib.hash.bcrypt_sha256

  This class implements a composition of BCrypt + HMAC_SHA256, and follows the PasswordHash API.

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

  The `hash()` and `genconfig()` methods accept all the same optional keywords as the base `bcrypt` hash.

  Added in version 1.6.2.

  Changed in version 1.7: Now defaults to `"2b"` bcrypt variant; though supports older hashes generated using the `"2a"` bcrypt variant.

  Changed in version 1.7.3: For increased security, updated to use HMAC-SHA256 instead of plain SHA256. Now only supports the `"2b"` bcrypt variant. Hash format updated to “v=2”.

## Format

Bcrypt-SHA256 is compatible with the Modular Crypt Format, and uses `$bcrypt-sha256$` as the identifying prefix for all it’s strings. An example hash (of `password`) is:

> `$bcrypt-sha256$v=2,t=2b,r=12$n79VH.0Q2TMWmt3Oqt9uku$Kq4Noyk3094Y2QlB8NdRT8SvGiI4ft2`

Version 1 of this format had the format `$bcrypt-sha256$type,rounds$salt$digest`. Passlib 1.7.3 introduced version 2 of this format, which changed the algorithm slightly (see below), and adjusted the format to indicate a version: `$bcrypt-sha256$v=2,t=type,r=rounds$salt$digest`, where:

- `type` is the BCrypt variant in use (always `2b` under version 2; though `2a` was allowed under version 1).

- `rounds` is a cost parameter, encoded as decimal integer, which determines the number of iterations used via `iterations=2**rounds` (rounds is 12 in the example).

- `salt` is a 22 character salt string, using the characters in the regexp range `[./A-Za-z0-9]` (`n79VH.0Q2TMWmt3Oqt9uku` in the example).

- `digest` is a 31 character digest, using the same characters as the salt (`Kq4Noyk3094Y2QlB8NdRT8SvGiI4ft2` in the example).

## Algorithm

The algorithm this hash uses is as follows:

- first the password is encoded to `UTF-8` if not already encoded.

- the next step is to hash the password before handing it off to bcrypt:

  > - Under version 2 of this algorithm (the default as of passlib 1.7.3), the password is run through HMAC-SHA2-256, with the HMAC key set to the bcrypt salt (encoded as a 22 character ascii salt string).

  > - Under the older version 1 of this algorithm, the password was instead run through plain SHA2-256.

  > In either case, this generates a 32 byte digest.

- this hash is then encoded using base64, resulting in a 44-byte result (including the trailing padding `=`). For the example `"password"` and the salt `"n79VH.0Q2TMWmt3Oqt9uku"`, the output from this stage would be `b"7CwRr5rxo2JZcVmSDAi/2JPTkvkAdNy20Cz2LwYC0fw="` (for version 2).

- this base64 string is then passed on to the underlying bcrypt algorithm as the new password to be hashed. See passlib.hash.bcrypt - BCrypt for details on it’s operation. For the example in the prior line, the resulting bcrypt digest component would be `"Kq4Noyk3094Y2QlB8NdRT8SvGiI4ft2"`.