Crypto.PasswordStore

pwstore-fast-2.3: Secure password storage.

Copyright | (c) Peter Scott, 2011
License | BSD-style
Maintainer | pjscott@iastate.edu
Stability | experimental
Portability | portable
Safe Haskell | Safe
Language | Haskell98

Crypto.PasswordStore

Contents

- Registering and verifying passwords
- Updating password hash strength
- Utilities

Description

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.

Synopsis

- makePassword :: ByteString -> Int -> IO ByteString
- makePasswordSalt :: ByteString -> Salt -> Int -> ByteString
- verifyPassword :: 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

# Registering and verifying passwords

makePassword :: ByteString -> Int -> IO ByteString

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, for example on Windows) `Random`, which is included in the hashed output.

makePasswordSalt :: ByteString -> Salt -> Int -> ByteString

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 -> Bool

`verifyPassword userInput pwHash` verifies the password `userInput` given by the user against the stored password hash `pwHash`. Returns `True` if the given password is correct, and `False` if it is not.

# Updating password hash strength

strengthenPassword :: ByteString -> Int -> ByteString

Try to strengthen a password hash, by hashing it some more times. ``strengthenPassword` pwHash new_strength` will return a new password hash with strength at least `new_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 -> Int

Return the strength of a password hash.

# Utilities

data Salt

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`.

Instances

Eq Salt |
Ord Salt |
Show Salt |

isPasswordFormatValid :: ByteString -> Bool

Is the format of a password hash valid? Attempts to parse a given password hash. Returns `True` if it parses correctly, and `False` otherwise.

genSaltIO :: IO Salt

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`.

genSaltRandom :: RandomGen b => b -> (Salt, b)

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.

makeSalt :: ByteString -> Salt

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.

exportSalt :: Salt -> ByteString

Convert a `Salt` into a `ByteString`. The resulting `ByteString` will be base64-encoded. Most users will not need to use this function.