| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Yesod.Auth.Util.PasswordStore
Description
This is a fork of pwstore-fast, originally copyright (c) Peter Scott, 2011, and released under a BSD-style licence.
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|14|jEWU94phx4QzNyH94Qp4CQ==|5GEw+jxP/4WLgzt9VS3Ee3nhqBlDsrKiB+rq7JfMckU="
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" 14 "sha256|14|Zo4LdZGrv/HYNAUG3q8WcA==|zKjbHZoTpuPLp1lh6ATolWGIKjhXvY4TysuKvqtNFyk="
This will hash the password "hunter2", with strength 14, 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 12, and 14 is a good default value at the time of this writing, in 2013.
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.
Note that, as of version 2.4, you can also use PBKDF2, and specify the exact iteration count. This does not have a significant effect on security, but can be handy for compatibility with other code.
Since: 1.4.18
Synopsis
- pbkdf1 :: ByteString -> Salt -> Int -> ByteString
- pbkdf2 :: ByteString -> Salt -> Int -> ByteString
- makePassword :: ByteString -> Int -> IO ByteString
- makePasswordWith :: (ByteString -> Salt -> Int -> ByteString) -> ByteString -> Int -> IO ByteString
- makePasswordSalt :: ByteString -> Salt -> Int -> ByteString
- makePasswordSaltWith :: (ByteString -> Salt -> Int -> ByteString) -> (Int -> Int) -> ByteString -> Salt -> Int -> ByteString
- verifyPassword :: ByteString -> ByteString -> Bool
- verifyPasswordWith :: (ByteString -> Salt -> Int -> ByteString) -> (Int -> Int) -> ByteString -> ByteString -> Bool
- strengthenPassword :: ByteString -> Int -> ByteString
- passwordStrength :: ByteString -> Int
- data Salt
- isPasswordFormatValid :: ByteString -> Bool
- genSaltIO :: IO Salt
- genSaltRandom :: RandomGen b => b -> (Salt, b)
- makeSalt :: ByteString -> Salt
- exportSalt :: Salt -> ByteString
- importSalt :: ByteString -> Salt
Algorithms
pbkdf1 :: ByteString -> Salt -> Int -> ByteString Source #
PBKDF1 key-derivation function. Takes a password, a Salt, and a number of
iterations. The number of iterations should be at least 1000, and probably
more. 5000 is a reasonable number, computing almost instantaneously. This
will give a 32-byte ByteString as output. Both the salt and this 32-byte
key should be stored in the password file. When a user wishes to authenticate
a password, just pass it and the salt to this function, and see if the output
matches.
Since: 1.4.18
pbkdf2 :: ByteString -> Salt -> Int -> ByteString Source #
PBKDF2 key-derivation function.
For details see http://tools.ietf.org/html/rfc2898.
32 is the most common digest size for SHA256, and is
what the algorithm internally uses.
HMAC+SHA256 is used as PRF, because HMAC+SHA1 is considered too weak.
Since: 1.4.18
Registering and verifying passwords
makePassword :: ByteString -> Int -> IO ByteString Source #
Hash a password with a given strength (14 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, for example on Windows)
Random, which is included in the hashed output.
Since: 1.4.18
Arguments
| :: (ByteString -> Salt -> Int -> ByteString) | The algorithm to use (e.g. pbkdf1) |
| -> ByteString | The password to encrypt |
| -> Int | log2 of the number of iterations |
| -> IO ByteString |
A generic version of makePassword, which allow the user
to choose the algorithm to use.
>>>makePasswordWith pbkdf1 "password" 14
Since: 1.4.18
makePasswordSalt :: ByteString -> Salt -> Int -> ByteString Source #
Hash a password with a given strength (14 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" (makeSalt "72cd18b5ebfe6e96") 14 "sha256|14|NzJjZDE4YjVlYmZlNmU5Ng==|yuiNrZW3KHX+pd0sWy9NTTsy5Yopmtx4UYscItSsoxc="
Since: 1.4.18
Arguments
| :: (ByteString -> Salt -> Int -> ByteString) | A function modeling an algorithm (e.g. |
| -> (Int -> Int) | A function to modify the strength |
| -> ByteString | A password, given as clear text |
| -> Salt | A hash |
| -> Int | The password strength (e.g. |
| -> ByteString |
A generic version of makePasswordSalt, meant to give the user
the maximum control over the generation parameters.
Note that, unlike makePasswordWith, this function takes the raw
number of iterations. This means the user will need to specify a
sensible value, typically 10000 or 20000.
Since: 1.4.18
verifyPassword :: ByteString -> ByteString -> Bool Source #
Like verifyPasswordWith, but uses pbkdf1 as algorithm.
Since: 1.4.18
Arguments
| :: (ByteString -> Salt -> Int -> ByteString) | A function modeling an algorithm (e.g. pbkdf1) |
| -> (Int -> Int) | A function to modify the strength |
| -> ByteString | User password |
| -> ByteString | The generated hash (e.g. sha256|14...) |
| -> Bool |
verifyPasswordWith algorithm userInput pwHash verifies
the password userInput given by the user against the stored password
hash pwHash, with the hashing algorithm algorithm. Returns True if the
given password is correct, and False if it is not.
This function allows the programmer to specify the algorithm to use,
e.g. pbkdf1 or pbkdf2.
Note: If you want to verify a password previously generated with
makePasswordSaltWith, but without modifying the number of iterations,
you can do:
>>> verifyPasswordWith pbkdf2 id "hunter2" "sha256..." True
Since: 1.4.18
Updating password hash strength
strengthenPassword :: ByteString -> Int -> ByteString Source #
Try to strengthen a password hash, by hashing it some more
times. 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.
Since: 1.4.18
passwordStrength :: ByteString -> Int Source #
Return the strength of a password hash.
Since: 1.4.18
Utilities
A salt is a unique random value which is stored as part of the password
hash. You can generate a salt with genSaltIO or genSaltRandom, or if you
really know what you're doing, you can create them from your own ByteString
values with makeSalt.
Since: 1.4.18
Generate a Salt from 128 bits of data from /dev/urandom, with the
system RNG as a fallback. This is the function used to generate salts by
makePassword.
Since: 1.4.18
genSaltRandom :: RandomGen b => b -> (Salt, b) Source #
Generate a Salt with 128 bits of data taken from a given random number
generator. 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.
Since: 1.4.18
makeSalt :: ByteString -> Salt Source #
Create a Salt from a ByteString. The input must be at least 8
characters, and can contain arbitrary bytes. Most users will not need to use
this function.
Since: 1.4.18
exportSalt :: Salt -> ByteString Source #
Convert a Salt into a ByteString. The resulting ByteString will be
base64-encoded. Most users will not need to use this function.
Since: 1.4.18
importSalt :: ByteString -> Salt Source #
Convert a raw ByteString into a Salt.
Use this function with caution, since using a weak salt will result in a
weak password.
Since: 1.4.18