If you are unfamiliar with cryptography concepts or the vocabulary it uses, or especially you are looking for guidance on "password encryption", please read [this page first](https://paragonie.com/blog/2015/08/you-wouldnt-base64-a-password-cryptography-decoded).
We've previously said that [even security advice should carry an expiration date](https://paragonie.com/blog/2015/06/guide-securing-your-business-s-online-presence-for-non-experts). So unlike most of our past blog posts, this page should be considered a living document: As requirements change and new attacks are discovered, we will update it accordingly. A [changelog](#changelog) is at the end of the document.
> **Semantic point:** Don't store the password, store a hash of the password. ([Obligatory](http://howtosafelystoreapassword.com).)
## Modern, Secure, Salted Password Hashing Made Simple
**The Problem**: You want people to be able to create a unique user account, with a password, which they will use to access your application. How can you safely implement this feature?
**Easiest Solution**: [Use libsodium](https://paragonie.com/blog/2015/09/how-to-safely-implement-cryptography-in-any-application), which provides a secure password hashing API in most languages. As of version 1.0.9, libsodium delivers **Argon2**, the most recent, carefully-selected algorithm from the [Password Hashing Competition](https://password-hashing.net/). Libsodium offers [bindings for most programming languages](https://download.libsodium.org/doc/bindings_for_other_languages/index.html).
* [Libsodium documentation](https://download.libsodium.org/doc/)
* [Libsodium source code](https://github.com/jedisct1/libsodium)
> **Note:** There was a published [attack on an earlier version of Argon2i](http://permalink.gmane.org/gmane.comp.security.phc/3606), the recommended variant of Argon2 for general purpose password hashing. The practical implications weren't severe; if you're using Argon2i version 1.3 or higher (with at least 3 passes) you're safe. Libsodium does this.
If you, for whatever reason, cannot reconcile your requirements with installing libsodium, you have other options. In preparing this blog post, our security team has investigated several password hashing libraries in multiple programming languages. What follows is our current recommendations for secure password storage with example code.
Acceptable Password Hashing Algorithms
Although there is disagreement about how to rank them, cryptography experts agree that these algorithms are the only ones you should be using to store passwords in 2016:
* **Argon2**, the [Password Hashing Competition winner](https://password-hashing.net).
* **bcrypt**
* **scrypt**
* The other Password Hashing Competition finalists (**Catena**, **Lyra2**, **Makwa**, and **yescrypt**)
* **PBKDF2** (nearly everyone except FIPS agrees [PBKDF2 is the worst of the acceptable options](http://www.openwall.com/presentations/PHDays2014-Yescrypt/mgp00004.html), but is still acceptable)
Secure Password Storage in PHP
If you want to upgrade to Argon2i before PHP's password hashing API catches up, the only way to do so is through [libsodium](https://paragonie.com/book/pecl-libsodium/read/07-password-hashing.md#crypto-pwhash-str). Refer to the relevant section of the documentation for instructions on [installing libsodium for PHP](https://paragonie.com/book/pecl-libsodium/read/00-intro.md#installing-libsodium).
// Password hashing:
$hash_str = \Sodium\crypto_pwhash_str(
$password,
\Sodium\CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
\Sodium\CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE
);
// Password verification:
if (\Sodium\crypto_pwhash_str_verify($hash_str, $password)) {
// recommended: wipe the plaintext password from memory
\Sodium\memzero($password);
// Password was valid.
} else {
// recommended: wipe the plaintext password from memory
\Sodium\memzero($password);
// Password was invalid.
}
If you're using [Halite](https://paragonie.com/blog/2016/05/solve-all-your-cryptography-problems-in-three-easy-steps-with-halite#encrypted-password-hashes) (our developer-friendly FOSS PHP libsodium wrapper), the `Password` class uses Argon2i since version 2.0.0.
Alternative: Bcrypt Password Hashing in PHP
First, make sure you're using a [supported version of PHP](https://secure.php.net/supported-versions.php). If you are, then [the PHP password API](https://secure.php.net/manual/en/ref.password.php) will be available for use. If you aren't, consider upgrading. If you can't, check out [password_compat](https://github.com/ircmaxell/password_compat).
$hash = password_hash($userPassword, PASSWORD_DEFAULT);
[`password_hash()`](https://secure.php.net/password_hash) takes care of salting the hash, transparently. You can, however, specify your own [cost](http://security.stackexchange.com/a/3993/43688). The absolute minimum value you should consider using is `10`. `12` is good, provided your hardware supports it. The default cost parameter is `10`.
$hash = password_hash($userPassword, PASSWORD_DEFAULT, ['cost' => 12]);
Verifying a password against a stored hash is incredibly simple:
if (password_verify($userPassword, $hash)) {
// Login successful.
if (password_needs_rehash($hash, PASSWORD_DEFAULT, ['cost' => 12])) {
// Recalculate a new password_hash() and overwrite the one we stored previously
}
}
As of PHP 7, `PASSWORD_DEFAULT` still uses bcrypt. In a future version, it may migrate to Argon2.
Alternative: Scrypt Password Hashing in PHP
If you aren't using libsodium (which we strongly recommend that you *do* use!), you can still get scrypt hashes in PHP through [Dominic Black's Scrypt PHP Extension](https://github.com/DomBlack/php-scrypt) from PECL.
# If you don't have PECL installed, get that first.
pecl install scrypt
echo "extension=scrypt.so" > /etc/php5/mods-available/scrypt.ini
php5enmod scrypt
Next, grab a copy of [the bundled PHP wrapper](https://github.com/DomBlack/php-scrypt/blob/master/scrypt.php) and include it in your project.
# Hashing
$hash = \Password::hash($userProvidedPassword);
# Validation
if (\Password::check($userProvidedPassword, $hash)) {
// Logged in successfully.
}
Secure Password Storage in Java
There is a [Java implementation of Argon2](https://github.com/phxql/argon2-jvm) outside of libsodium, but it requires you to specify the parameters rather than providing sane defaults.
// Create instance
Argon2 argon2 = Argon2Factory.create();
// Read password from user
char[] passwd = readPasswordFromUser();
try {
int N = 65536;
int r = 2;
int p = 1;
// Hash password
String hashed = argon2.hash(r, N, p, passwd);
// Validating a hash
if (argon2.verify(hash, passwd)) {
// Login successful
}
} finally {
// Wipe confidential data
argon2.wipeArray(passwd);
}
Alternative: Bcrypt Password Hashing in Java
[jBCrypt](https://github.com/jeremyh/jBCrypt) provides the bcrypt password hashing algorithm.
String hash = BCrypt.hashpw(userProvidedPassword, BCrypt.gensalt());
Verifying a bcrypt hash in Java:
if (BCrypt.checkpw(userProvidedPassword, hash)) {
// Login successful.
}
Alternative: Scrypt Password Hashing in Java
There is a [Java implementation of scrypt](https://github.com/wg/scrypt), but it requires you to specify the parameters rather than providing sane defaults.
# Calculating a hash
int N = 16384;
int r = 8;
int p = 1;
String hashed = SCryptUtil.scrypt(passwd, N, r, p);
# Validating a hash
if (SCryptUtil.check(passwd, hashed)) {
// Login successful
}
Secure Password Storage in C# (.NET)
Argon2 is available for .NET developers through [the .NET bindings for libsodium](https://github.com/adamcaudill/libsodium-net).
// Hashing a password
var hash = PasswordHash.ArgonHashString(yourPasswordString, Strength.Interactive)
if (PasswordHash.ArgonHashStringVerify(hash, yourPasswordString) {
//correct password
}
Alternative: Bcrypt Secure Password Storage in C# (.NET)
We recommend [Chris McKee's Bcrypt.NET](https://github.com/BcryptNet/bcrypt.net) over `System.Security.Cryptography.Rfc2898DeriveBytes`, which is PBKDF2-SHA1. (We're not saying PBKDF2-SHA1 is unsafe, but that bcrypt is preferable to it.)
// Calculating a hash
string hash = BCrypt.HashPassword(usersPassword, BCrypt.GenerateSalt());
// Validating a hash
if (BCrypt.Verify(usersPassword, hash)) {
// Login successful
}
Alternative: Scrypt Password Hashing in C# (.NET)
There is an [Scrypt package in NuGET](https://github.com/viniciuschiele/Scrypt) as well.
// This is necessary:
ScryptEncoder encoder = new ScryptEncoder();
// Calculating a hash
SecureString hashedPassword = encoder.Encode(usersPassword);
// Validating a hash
if (encoder.Compare(usersPassword, hashedPassword)) {
// Login successful
}
Secure Password Storage in Ruby
There is a [Ruby Argon2 gem](https://github.com/technion/ruby-argon2), which is rather straightforward to use:
hasher = Argon2::Password.new
hashed_password = hasher.create("password")
if Argon2::Password.verify_password("password", hashed_password)
# Login successful
Alternative: Bcrypt Hashing in Ruby
From the author of ["Use bcrypt. Use bcrypt. Use bcrypt..."](https://codahale.com/how-to-safely-store-a-password/) comes a [Ruby gem for bcrypt password hashing](https://github.com/codahale/bcrypt-ruby).
require "bcrypt"
# Calculating a hash
my_password = BCrypt::Password.create(usersPassword)
# Validating a hash
if my_password == usersPassword
# Login successful
Beware that, as of this writing, this library is not following [cryptography coding best practices](https://cryptocoding.net/index.php/Coding_rules#Compare_secret_strings_in_constant_time). Consider applying [this patch](https://github.com/codahale/bcrypt-ruby/pull/119/files) until they get around to merging it.
Alternative: Scrypt Hashing in Ruby
There is also a [Ruby gem for scrypt password hashing](https://github.com/pbhogan/scrypt).
require "scrypt"
# Calculating a hash
password = SCrypt::Password.create(usersPassword)
# Validating a hash
if password == usersPassword
# Login successful
Secure Password Storage in Python
Python developers generally prefer [passlib](https://pypi.python.org/pypi/passlib) ([Bitbucket](https://bitbucket.org/ecollins/passlib/wiki/Home)). Since version 1.7.0, offers [Argon2 support](http://pythonhosted.org/passlib/lib/passlib.hash.argon2.html).
from passlib.hash import argon2
# Calculating a hash
hash = argon2.using(rounds=4).hash(usersPassword)
# Validating a hash
if argon2.verify(usersPassword, hash):
# Login successful
Alternative: Bcrypt Hashing in Python
Passlib also offers bcrypt password hashing. Before version 1.7.0, however, it was called `bcrypt.encrypt()` rather than `bcrypt.hash()`.
from passlib.hash import bcrypt
# Calculating a hash
hash = bcrypt.hash(usersPassword, rounds=12)
# Misnomer, but that's what it was called before v1.7.0:
# hash = bcrypt.encrypt(usersPassword, rounds=12)
# Validating a hash
if bcrypt.verify(usersPassword, hash):
# Login successful
Alternatively, you can't go wrong with the [bcrypt Python package](https://pypi.python.org/pypi/bcrypt/2.0.0) (also on [github](https://github.com/pyca/bcrypt)):
import bcrypt
import hmac
# Calculating a hash
password = b"correct horse battery staple"
hashed = bcrypt.hashpw(password, bcrypt.gensalt())
# Validating a hash (don't use ==)
if (hmac.compare_digest(bcrypt.hashpw(password, hashed), hashed)):
# Login successful
Alternative: Scrypt Hashing in Python
Passlib, since version 1.7.0, offers [Scrypt support](http://pythonhosted.org/passlib/lib/passlib.hash.scrypt.html).
from passlib.hash import scrypt
# Calculating a hash
hash = scrypt.using(rounds=8).hash(usersPassword)
# Validating a hash
if scrypt.verify(usersPassword, hash):
# Login successful
Secure Password Storage in Node.js
There are other implementations of Argon2 available in the Node.js ecosystem, but you're better off using [node-sodium](https://github.com/paixaop/node-sodium), which handles salt generation for you.
// notice the .api part; that's important
var sodium = require('sodium').api;
var hash = new Buffer(sodium.crypto_pwhash_STRBYTES);
var passwordBuffer = new Buffer("password goes here");
hash = sodium.crypto_pwhash_str(
passwordBuffer,
sodium.crypto_pwhash_OPSLIMIT_INTERACTIVE,
sodium.crypto_pwhash_MEMLIMIT_INTERACTIVE
);
// Validation:
if (sodium.crypto_pwhash_str_verify(
hash,
passwordBuffer
)) {
// You are logged in
}
Alternative: Bcrypt Password Hashing in Node.js
There are two secure implementations of bcrypt in Node.js, although [bcrypt](https://www.npmjs.com/package/bcrypt) ([Github](https://github.com/ncb000gt/node.bcrypt.js)) seems to be the preferred one. We're making extensive use of [Promises](https://gist.github.com/joepie91/791640557e3e5fd80861) to greatly simplify error handling in the examples below:
var Promise = require("bluebird");
var bcrypt = Promise.promisifyAll(require("bcrypt"));
function addBcryptType(err) {
// Compensate for `bcrypt` not using identifiable error types
err.type = "bcryptError";
throw err;
}
// Calculating a hash:
Promise.try(function() {
return bcrypt.hashAsync(usersPassword, 10).catch(addBcryptType);
}).then(function(hash) {
// Store hash in your password DB.
});
// Validating a hash:
// Load hash from your password DB.
Promise.try(function() {
return bcrypt.compareAsync(usersPassword, hash).catch(addBcryptType);
}).then(function(valid) {
if (valid) {
// Login successful
} else {
// Login wrong
}
});
// You would handle errors something like this, but only at the top-most point where it makes sense to do so:
Promise.try(function() {
// Generate or compare a hash here
}).then(function(result) {
// ... some other stuff ...
}).catch({type: "bcryptError"}, function(err) {
// Something went wrong with bcrypt
});
Alternative: Scrypt Password Hashing in Node.js
We recommend [scrypt for humans](https://www.npmjs.com/package/scrypt-for-humans) ([Github](https://github.com/joepie91/scrypt-for-humans)), a developer-friendly node-scrypt wrapper that's easy to use and hard to misuse.
var Promise = require("bluebird");
var scrypt = require("scrypt-for-humans");
// Calculating a hash:
Promise.try(function() {
return scrypt.hash(usersPassword);
}).then(function(hash) {
// Store hash for long term use
});
// Validating a hash:
Promise.try(function() {
return scrypt.verifyHash(usersPassword, hash);
}).then(function() {
// Login successful
}).catch(scrypt.PasswordError, function(err) {
// Login failed
});
(Example code made better by Sven Slootweg, the scrypt-for-humans maintainer.)
Frequently Asked Questions
Where's PBKDF2?
Although PBKDF2 is more widely available than bcrypt or scrypt, it doesn't offer the GPU resistance that we need from a password hashing function. If you must use PBKDF2, make sure you use at least `100,000` iterations and a SHA2 family hash function.
To reiterate: **PBKDF2 can still be secure.** It's the least secure of the acceptable password hashing algorithms on this page, so we aren't going to provide any example code.
Why prioritize bcrypt over scrypt?
On a technical level, they're vastly different, but for practical purposes they're morally equivalent. The real weakness is in not using an acceptable password hashing function at all. If you can use either of these two, use it. They're both fine.
Our choice for bcrypt as the default was simply: In PHP (which represents a little over 80% of the Internet), the easiest choice for developers to implement in their applications is bcrypt (via the password hashing API that shipped with PHP 5.5). Using scrypt requires root access and the ability to install PHP extensions via PECL.
Why choose scrypt over bcrypt:
* Bcrypt [truncates after 72 characters](https://3v4l.org/3G7mX).
* Bcrypt [truncates on `NUL` bytes](https://3v4l.org/b3tOW).
* (These aren't bugs in the PHP implementation. They're bugs in the algorithm itself.)
Why choose bcrypt over scrypt:
* Scrypt's memory hardness [isn't perfect](http://blog.ircmaxell.com/2014/03/why-i-dont-recommend-scrypt.html)
* Scrypt requires about 1000 times the memory as bcrypt for the same security against GPU attacks
If you have to choose between the two for password hashing, they're both good options. If you choose bcrypt, however, passing a base64-encoded SHA-384 hash to bcrypt is probably a good move:
* `base64_encode(hash('sha384', $password, true))` is 64 characters, which nearly fills up the 72 character keyspace
* A base64-encoded hash is guaranteed to not contain `NUL` bytes
* Two passwords with the same 72 character prefix but differ after the 73rd character will, with overwhelming likelihood, produce different SHA-384 hashes
* SHA-384 has about 192 bits of birthday collision resistance
* SHA-384 is also the largest SHA-2 family hash function that is resistant to [length extension attacks](https://blog.skullsecurity.org/2012/everything-you-need-to-know-about-hash-length-extension-attacks)
The above construction may invite theoretical concerns about entropy reduction (i.e. 72 characters of raw binary without any `NUL` bytes comes out to about 573 bits of possible entropy, but a SHA-384 hash outputs are clearly limited to 384 bits).
A birthday SHA-384 collision still requires $2^{192}$ guesses. $2^{192}$ is large enough to fall under [boring cryptography](http://cr.yp.to/talks/2015.10.05/slides-djb-20151005-a4.pdf), barring any new attacks.
I'm not using bcrypt/scrypt. How should I migrate my legacy hashes?
The most straightforward approach to migrating your legacy hashes from, e.g. MD5, to bcrypt/scrypt is to follow this strategy (which was first introduced to us in a Reddit discussion by [NeoThermic](https://www.reddit.com/r/PHP/comments/3lwxlw/hash_and_verify_passwords_in_php_the_right_way/cva6y6p)):
1. Add a column to your user accounts table, called `legacy_password` (or equivalent).
2. Calculate the bcrypt/scrypt/Argon2 hash of **the existing password hashes** and store them in the database.
3. Modify your authentication code to handle the legacy flag.
When a user attempts to login, first check if the `legacy_password` flag is set. If it is, first pre-hash their password with your old password hashing algorithm, then use this prehashed value in place of their password. Afterwards, *recalculate* the bcrypt hash and store the new hash in the database, disabling the `legacy_password` flag in the process. A very loose example in PHP 7+ follows:
/**
* This is example code. Please feel free to use it for reference but don't just copy/paste it.
*
* @param string $username Unsafe user-supplied data: The username
* @param string $password Unsafe user-supplied data: The password
* @return int The primary key for that user account
* @throws InvalidUserCredentialsException
*/
public function authenticate(string $username, string $password): int
{
// Database lookup
$stmt = $this->db->prepare(
"SELECT
userid, passwordhash, legacy_password
FROM
user_accounts
WHERE
username = ?"
);
$stmt->execute([$username]);
$stored = $stmt->fetch(PDO::FETCH_ASSOC);
if (!$stored) {
// No such user, throw an exception
throw new InvalidUserCredentialsException();
}
if ($stored['legacy_password']) {
// This is the legacy password upgrade code
if (password_verify(legacy_hashing_algorithm($password), $stored['passwordhash'])) {
$newHash = password_hash($password, PASSWORD_DEFAULT);
$stmt = $this->db
->prepare(
"UPDATE
user_accounts
SET
passwordhash = ?,
legacy_password = FALSE
WHERE
userid = ?"
)->execute([
$newHash,
$stored['userid']
]);
// Return the user ID (integer)
return $stored['userid'];
}
} elseif (password_verify($password, $stored['passwordhash'])) {
// This is the general purpose upgrade code e.g. if a future version of PHP upgrades to Argon2
if (password_needs_rehash($stored['passwordhash'], PASSWORD_DEFAULT)) {
$newhash = password_hash($password, PASSWORD_DEFAULT);
$this->db
->prepare("UPDATE user_accounts SET passwordhash = ? WHERE userid = ?")
->execute([$newhash, $stored['userid']]);
}
// Return the user ID (integer)
return $stored['userid'];
}
// When all else fails, throw an exception
throw new InvalidUserCredentialsException();
}
Usage:
try {
$userid = $this->authenticate($username, $password);
// Update the session state
// Redirect to the post-authentication landing page
} catch (InvalidUserCredentialsException $e) {
// Log the failure
// Redirect to the login form
}
Proactively upgrading legacy hashes is a security win over an opportunistic strategy (rehashing when the user logs in, but leave the insecure hashes in the database for inactive users): With a proactive strategy, if your server gets compromised before everyone logs in again, their passwords are already using an acceptable algorithm (bcrypt, in the example code).
The above example code is also available in [Bcrypt-SHA-384](https://gist.github.com/paragonie-scott/66469d391deef2e3b875) flavor.
What about password managers?
Password managers are a different beast. When we say "don't encrypt passwords", we're talking about server-side password validation. You should [definitely use a password manager](https://paragonie.com/blog/2015/06/guide-securing-your-business-s-online-presence-for-non-experts).
How do I implement secure server-side password storage in (other language)?
If you'd like us to consider another programming language for inclusion on this page, please [reach out to our `security@` team directly](https://paragonie.com/contact) and we'll let popular demand guide our investigations.
I followed the advice on this page, but how can I be sure I did it correctly?
Check the library you're using; it should provide test vectors. If all else fails: [We audit code](https://paragonie.com/service/code-review).
Changelog
* **2017-03-19** - Recommend a better (and maintained) Bcrypt implementation for .NET projects.
* **2016-12-13** - We now recommend Argon2 as the go-to algorithm of choice, and demoted bcrypt to an alternative.
* **2016-05-16** - Argon2 v1.3 has matured and landed in libsodium. We've updated our recommendations for each language to explain how to get Argon2i as an alternative. Once it's widely adopted, we will make it the primary recommendation. Specifically covered:
* [PHP](#php-argon2)
* [Ruby](#ruby-argon2)
* [Node.js](#nodejs-argon2)
* [C# (.NET)](#csharp-argon2)