Secure Password Storage v2.0

This repository contains peer-reviewed libraries for password storage in PHP, C#, Ruby, and Java. Passwords are "hashed" with PBKDF2 (64,000 iterations of SHA1 by default) using a cryptographically-random salt. The implementations are compatible with each other, so you can, for instance, create a hash in PHP and then verify it in C#.

Should you use this code?

This code uses the PBKDF2 algorithm to protect passwords. Better technologies for protecting passwords exist today, like bcrypt, scrypt, or Argon2. Before using this code, you should try to find a well-reviewed and carefully-made implementation of one of those algorithms for the language that you are using. These algorithms are "memory hard," meaning that they don't just need a lot of CPU power to compute, they also require a lot of memory (unlike PBKDF2). By using a memory hard algorithm, your passwords will be better protected.

One thing you could do would be to use libsodium to hash your passwords with scrypt. It has bindings available for many languages. For PHP apps, a great option is to use the built-in password_hash() and password_verify() functions.

Since there are better options, this code is now in "maintenance mode." Only bugs will be fixed, no new features will be added. It is currently safe to use, but using libsodium would be better.

Usage

You should not store users' passwords in plain text on your servers. Nor should you even store them in encrypted form. The correct way to store a password is to store something created from the password, which we'll call a "hash." Hashes don't allow you to recover the password, they only let you check if a password is the same as the one that created the hash.

There are a lot of subtle details about password hashing that this library hides from you. You don't need to worry about things like "salt" with this library. It takes care of all of that for you.

To implement a user login system, you need two parts: creating new accounts, and logging in to existing accounts. When you create a new account, your code will create a hash of the new account's password and save it somewhere. When you log in to an account, your code will use the hash to check if the login password is correct.

To create a hash, when a new account is added to your system, you call the CreateHash() method provided by this library. To verify a password, you call VerifyPassword() method provided by this library.

Here is more specific documentation for both functions. The behavior should be the same for all of the implementations (although the method names differ slightly). If one implementation behaves differently than another, that is a bug, and should be filed in the GitHub issue tracker.

CreateHash(password)

Preconditions:

You're intending to create a new account, or the password to an existing account is being changed.
password is the password for the new account, or the new password for an existing account.

Postconditions:

CreateHash() gives you a string which can be used with VerifyPassword() to check, in the future, if a password is the same as the password given to this call.

Obligations:

Store the string CreateHash() returns to you in a safe place. If an attacker can modify your hashes, they will be able to change them to, for instance, the hash of "1234", and then log in to any account. If an attacker can view your hashes, they can begin cracking them (by trying to guess-and-check passwords).

Exceptions:

CannotPerformOperationException: If this exception is thrown, it means something is wrong with the platform your code is running on, and it's not safe to create a hash. For example, if your system's random number generator doesn't work properly, this kind of exception will be thrown.

VerifyPassword(password, correctHash)

Preconditions:

Someone is logging in to a user account which has been created in the past.
password is the password provided by the person trying to log in.
correctHash is the hash of the account's correct password, made with CreateHash() when the account was created or when its password was last changed. Make sure you are providing the hash for the correct user account!
correctHash hasn't been seen by or changed by an attacker since it was created.

Postconditions:

True is returned if the password provided by the person logging in is correct. False is returned if not.

Obligations:

Make sure the correctHash you're giving is for the right account. If you give a hash for the wrong account, it would let someone log into Alice's account using Bob's password!

Exceptions:

CannotPerformOperationException: If this exception is thrown, it means something is wrong with the platform your code is running on, and for some reason it's not safe to verify a password on it.
InvalidHashException: The correctHash you gave was somehow corrupted. Note that some ways of corrupting a hash are impossible to detect, and their only symptom will be that VerifyPassword() will return false even though the correct password was given. So InvalidHashException is not guaranteed to be thrown if a hash has been changed, but if it is thrown then you can be sure that the hash was changed.

Customization

Each implementation provides several constants that can be changed. Only change these if you know what you are doing, and have help from an expert:

PBKDF2_HASH_ALGORITHM: The hash function PBKDF2 uses. By default, it is SHA1 for compatibility across implementations, but you may change it to SHA256 if you don't care about compatibility. Although SHA1 has been cryptographically broken as a collision-resistant function, it is still perfectly safe for password storage with PBKDF2.
PBKDF2_ITERATIONS: The number of PBKDF2 iterations. By default, it is 32,000. To provide greater protection of passwords, at the expense of needing more processing power to validate passwords, increase the number of iterations. The number of iterations should not be decreased.
PBKDF2_SALT_BYTES: The number of bytes of salt. By default, 24 bytes, which is 192 bits. This is more than enough. This constant should not be changed.
PBKDF2_HASH_BYTES: The number of PBKDF2 output bytes. By default, 18 bytes, which is 144 bits. While it may seem useful to increase the number of output bytes, doing so can actually give an advantage to the attacker, as it introduces unnecessary (avoidable) slowness to the PBKDF2 computation. 144 bits was chosen because it is (1) Less than SHA1's 160-bit output (to avoid unnecessary PBKDF2 overhead), and (2) A multiple of 6 bits, so that the base64 encoding is optimal.

Note that these constants are encoded into the hash string when it is created with CreateHash so that they can be changed without breaking existing hashes. The new (changed) values will apply only to newly-created hashes.

Hash Format

The hash format is five fields separated by the colon (':') character.

algorithm:iterations:hashSize:salt:hash

Where:

algorithm is the name of the cryptographic hash function ("sha1").
iterations is the number of PBKDF2 iterations ("64000").
hashSize is the length, in bytes, of the hash field (after decoding).
salt is the salt, base64 encoded.
hash is the PBKDF2 output, base64 encoded. It must encode hashSize bytes.

Here are some example hashes (all of the password "foobar"):

sha1:64000:18:B6oWbvtHvu8qCgoE75wxmvpidRnGzGFt:R1gkPOuVjqIoTulWP1TABS0H
sha1:64000:18:/GO9XQOPexBFVzRjC9mcOkVEi7ZHQc0/:0mY83V5PvmkkHRR41R1iIhx/
sha1:64000:18:rxGkJ9fMTNU7ezyWWqS7QBOeYKNUcVYL:tn+Zr/xo99LI+kSwLOUav72X
sha1:64000:18:lFtd+Qf93yfMyP6chCxJP5nkOxri6Zbh:B0awZ9cDJCTdfxUVwVqO+Mb5

The hash length in bytes is included to prevent an accident where the hash gets truncated. For instance, if the hash were stored in a database column that wasn't big enough, and the database was configured to truncate it, the result when the hash gets read back would be an easy-to-break hash, since the PBKDF2 output is right at the end. Therefore, the length of the hash should not be determined solely from the length of the last field; it must be compared against the stored length.

More Information

For more information on secure password storage, see Crackstation's page on Password Hashing Security.

markphillips01/password-hashing