1.. index:: Postgres; md5 hash
2
3==================================================================
4:class:`passlib.hash.postgres_md5` - PostgreSQL MD5 password hash
5==================================================================
6
7.. include:: ../_fragments/insecure_hash_warning.rst
8
9.. currentmodule:: passlib.hash
10
11This class implements the md5-based hash algorithm used by PostgreSQL to store
12its user account passwords. This scheme was introduced in PostgreSQL 7.2;
13prior to this PostgreSQL stored its password in plain text.
14Users will most likely find the frontend provided by :mod:`passlib.apps`
15to be more useful than accessing this class directly.
16That aside, this class can be used directly as follows::
17
18    >>> from passlib.hash import postgres_md5
19
20    >>> # hash password using specified username
21    >>> hash = postgres_md5.hash("password", user="username")
22    >>> hash
23    'md55a231fcdb710d73268c4f44283487ba2'
24
25    >>> # verify correct password
26    >>> postgres_md5.verify("password", hash, user="username")
27    True
28    >>> # verify correct password w/ wrong username
29    >>> postgres_md5.verify("password", hash, user="somebody")
30    False
31    >>> # verify incorrect password
32    >>> postgres_md5.verify("password", hash, user="username")
33    False
34
35.. seealso:: the generic :ref:`PasswordHash usage examples <password-hash-examples>`
36
37Interface
38=========
39.. autoclass:: postgres_md5()
40
41Format & Algorithm
42==================
43Postgres-MD5 hashes all have the format :samp:`md5{checksum}`,
44where :samp:`{checksum}` is 32 hexadecimal digits, encoding a 128-bit checksum.
45This checksum is the MD5 message digest of the password concatenated with the username.
46
47Security Issues
48===============
49This algorithm it not suitable for *any* use besides manipulating existing
50PostgreSQL account passwords, due to the following flaws:
51
52* Its use of the username as a salt value means that common usernames
53  (e.g. ``admin``, ``root``, ``postgres``) will occur more frequently as salts,
54  weakening the effectiveness of the salt in foiling pre-computed tables.
55
56* Since the keyspace of ``user+password`` is still a subset of ascii characters,
57  existing MD5 lookup tables have an increased chance of being able to reverse common hashes.
58
59* Its simplicity makes high-speed brute force attacks much more feasible [#brute]_ .
60
61.. rubric:: Footnotes
62
63.. [#] Discussion leading up to design of algorithm -
64       `<http://archives.postgresql.org/pgsql-hackers/2001-06/msg00952.php>`_
65
66.. [#] Message explaining postgres md5 hash algorithm -
67       `<http://archives.postgresql.org/pgsql-php/2003-01/msg00021.php>`_
68
69.. [#brute] Blog post demonstrating brute-force attack `<http://pentestmonkey.net/blog/cracking-postgres-hashes/>`_.
70