Portability | portable |
---|---|
Stability | experimental |
Maintainer | pjscott@iastate.edu |
Securely store hashed, salted passwords. If you need to store and verify passwords, there are many wrong ways to do it, most of them all too common. Some people store users' passwords in plain text. Then, when an attacker manages to get their hands on this file, they have the passwords for every user's account. One step up, but still wrong, is to simply hash all passwords with SHA1 or something. This is vulnerable to rainbow table and dictionary attacks. One step up from that is to hash the password along with a unique salt value. This is vulnerable to dictionary attacks, since guessing a password is very fast. The right thing to do is to use a slow hash function, to add some small but significant delay, that will be negligible for legitimate users but prohibitively expensive for someone trying to guess passwords by brute force. That is what this library does. It iterates a SHA256 hash, with a random salt, a few thousand times. This scheme is known as PBKDF1, and is generally considered secure; there is nothing innovative happening here.
The API here is very simple. What you store are called password hashes. They are strings (technically, ByteStrings) that look like this:
"sha256|12|Ge9pg8a/r4JW356Uux2JHg==|Fdv4jchzDlRAs6WFNUarxLngaittknbaHFFc0k8hAy0="
Each password hash shows the algorithm, the strength (more on that later),
the salt, and the hashed-and-salted password. You store these on your server,
in a database, for when you need to verify a password. You make a password
hash with the makePassword
function. Here's an example:
>>> makePassword "hunter2" 12 "sha256|12|lMzlNz0XK9eiPIYPY96QCQ==|1ZJ/R3qLEF0oCBVNtvNKLwZLpXPM7bLEy/Nc6QBxWro="
This will hash the password "hunter2"
, with strength 12, which is a good
default value. The strength here determines how long the hashing will
take. When doing the hashing, we iterate the SHA256 hash function
2^strength
times, so increasing the strength by 1 makes the hashing take
twice as long. When computers get faster, you can bump up the strength a
little bit to compensate. You can strengthen existing password hashes with
the strengthenPassword
function. Note that makePassword
needs to generate
random numbers, so its return type is IO
ByteString
. If you want to avoid
the IO
monad, you can generate your own salt and pass it to
makePasswordSalt
.
Your strength value should not be less than 10, and 12 is a good default value at the time of this writing, in 2011.
Once you've got your password hashes, the second big thing you need to do
with them is verify passwords against them. When a user gives you a password,
you compare it with a password hash using the verifyPassword
function:
>>> verifyPassword "wrong guess" passwordHash False >>> verifyPassword "hunter2" passwordHash True
These two functions are really all you need. If you want to make existing
password hashes stronger, you can use strengthenPassword
. Just pass it an
existing password hash and a new strength value, and it will return a new
password hash with that strength value, which will match the same password as
the old password hash.
- makePassword :: ByteString -> Int -> IO ByteString
- makePasswordSalt :: ByteString -> ByteString -> Int -> ByteString
- verifyPassword :: ByteString -> ByteString -> Bool
- strengthenPassword :: ByteString -> Int -> ByteString
- passwordStrength :: ByteString -> Int
- isPasswordFormatValid :: ByteString -> Bool
- genSaltIO :: IO ByteString
- genSaltRandom :: RandomGen b => b -> (ByteString, b)
Registering and verifying passwords
makePassword :: ByteString -> Int -> IO ByteStringSource
Hash a password with a given strength (12 is a good default). The output of
this function can be written directly to a password file or
database. Generates a salt using high-quality randomness from
/dev/urandom
or (if that is not available) System.Random
, which is
included in the hashed output.
makePasswordSalt :: ByteString -> ByteString -> Int -> ByteStringSource
Hash a password with a given strength (12 is a good default), using a given salt. The output of this function can be written directly to a password file or database. Example:
>>> makePasswordSalt "hunter2" "72cd18b5ebfe6e96" 12 "sha256|12|72cd18b5ebfe6e96|Xkki10Vus/a2SN/LgCVLTT5R30lvHSCCxH6QboV+U3E="
verifyPassword :: ByteString -> ByteString -> BoolSource
Updating password hash strength
strengthenPassword :: ByteString -> Int -> ByteStringSource
Try to strengthen a password hash, by hashing it some more
times.
will return a new password
hash with strength at least strengthenPassword
pwHash new_strengthnew_strength
. If the password hash already has
strength greater than or equal to new_strength
, then it is returned
unmodified. If the password hash is invalid and does not parse, it will be
returned without comment.
This function can be used to periodically update your password database when computers get faster, in order to keep up with Moore's law. This isn't hugely important, but it's a good idea.
passwordStrength :: ByteString -> IntSource
Return the strength of a password hash.
Utilities
genSaltIO :: IO ByteStringSource
Generate a base64-encoded salt from 128 bits of data from /dev/urandom
,
with the system RNG as a fallback. The result is 24 characters long. This is
the function used to generate salts by makePassword
.
genSaltRandom :: RandomGen b => b -> (ByteString, b)Source
Generate a base64-encoded salt from 128 bits of data taken from a given
random number generator. The result is 24 characters long. Returns the salt
and the updated random number generator. This is meant to be used with
makePasswordSalt
by people who would prefer to either use their own random
number generator or avoid the IO
monad.