1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
|
==================================================================
:class:`passlib.hash.bcrypt` - BCrypt
==================================================================
.. currentmodule:: passlib.hash
BCrypt was developed to replace :class:`~passlib.hash.md5_crypt` for BSD systems.
It uses a modified version of the Blowfish stream cipher. Featuring
a large salt and variable number of rounds, it's currently the default
password hash for many systems (notably BSD), and has no known weaknesses.
.. note::
It is strongly recommended to install PyBcrypt if this algorithm
is going to be used.
Usage
=====
.. todo::
write usage instructions
Functions
=========
.. autoclass:: bcrypt
Format & Algorithm
==================
Bcrypt is compatible with the :ref:`modular-crypt-format`, and uses ``$2$`` and ``$2a$`` as the identifying prefix
for all it's strings (``$2$`` is seen only for legacy hashes which used an older version of Bcrypt).
An example hash (of ``password``) is ``$2a$12$GhvMmNVjRW29ulnudl.LbuAnUtN/LRfe1JsBm1Xu6LE3059z5Tr8m``.
Bcrypt hashes have the format ``$2a${cost}${salt}{checksum}``, where:
* ``{cost}`` is the cost parameter, encoded as 2 zero-padded decimal digits,
which determines the number of rounds used via ``rounds=2**cost`` (cost is 12 in the example).
* ``{salt}`` is the 22 character salt string, using the characters ``[./A-Za-z0-9]`` (``GhvMmNVjRW29ulnudl.Lbu`` in the example).
* ``{checksum}`` is the 31 character checksum, using the same characters as the salt (``AnUtN/LRfe1JsBm1Xu6LE3059z5Tr8m`` in the example).
BCrypt's algorithm is described in detail in it's specification document,
listed below.
Deviations
==========
This implementation of bcrypt differs from others in a few ways:
* The bcrypt specification (and implementations) have no predefined
or predictable behavior when passed a salt containing characters
outside of the base64 range. To avoid this situtation,
PassLib will simply throw an error if invalid characters
are provided for the salt.
* Before generating a hash, PassLib encodes unicode passwords using UTF-8.
While the algorithm accepts passwords containing any 8-bit value
except for ``\x00``, it specifies no preference for encodings,
or for handling unicode strings.
References
==========
* `<http://www.usenix.org/event/usenix99/provos/provos_html/>`_ - the bcrypt format specification
* `<http://www.mindrot.org/projects/jBCrypt/>`_ - java implementation used as reference for PassLib
|
