Upash
🔒Unified API for password hashing algorithms
Install / Use
/learn @simonepri/UpashREADME
Synopsis
Password breaches have become more and more frequent.
See: [Yahoo][breach:yahoo] ([twice][breach:yahoo2]), [LinkedIn][breach:linkedin], [Adobe][breach:adobe],
[Ashley Madison][breach:ashley-madison], and [a whole lot more][breach:hibp-breaches].
Indeed, the above examples doubles as a list of "how NOT to do password storage": simple hashing, unsalted values, misuse of encryption, and failed password migration. (For more information on why these are bad, see our [introduction to password hashing theory][docs:password-hashing-theory])
There are two possible interpretations here: first, companies do not put adequate resources in securing passwords; and secondly, getting password hashing right is hard. Furthermore, even if you have followed previous best practice, keeping it right is another technical challenge: algorithm choices, security levels, parameter selection change regularly.
Make passwords painless
<img src="https://github.com/simonepri/upash/raw/master/media/api.png" alt="upash api" width="400" align="right"/>The upash ([pronounced u-pash][upash:pronounce]) project aims is to allow you to have a clean and easy-to-use API to use any password hashing algorithm seamlessly in your application.
Highlights
- Simple API for all password hashing algorithms
- Easy to maintain and upgradable logic
- Easy to test configurations through the CLI
- Step by step migration guide
- Comprehensive list of supported hashing algorithms
Do you believe that this is useful? Has it saved you time? Or maybe you simply like it?
If so, [support my work with a Star ⭐️][start] and [follow me 📩][github:simonepri].
Usage
The upash solution is straight-forward but it is important to follow all the steps carefully.
Firstly, you need to install this package.
npm install --save upash
Then, you need to choose from the
list of supported password hashing algorithms
the one that best suits your needs and install that too.
In the following, we will assume that you choose @phc/argon2, that is also a
suitable solution in case you don't know which one fits better for you.
npm install --save @phc/argon2
Finally, you can enjoy the easy APIs.
const upash = require('upash');
// Install the algorithm of your choice.
upash.install('argon2', require('@phc/argon2'));
// Hash API
const hashstr = await upash.hash('password');
// => "$argon2id$v=19$m=4096,t=3,p=1$PcEZHj1maR/+ZQynyJHWZg$2jEN4xcww7CYp1jakZB1rxbYsZ55XH2HgjYRtdZtubI"
// Verify API
const match = await upash.verify(hashstr, 'password');
// => true
You can store the hash returned by the hash function directly into your database.
You can also install more than one algorithm at once.
This is really handy when you want to update your current password hashing
algorithm.
const upash = require('upash');
// Install the algorithms of your choice.
upash.install('pbkdf2', require('@phc/pbkdf2'));
upash.install('argon2', require('@phc/argon2'));
// You can explicitly tell upash which algorithm to use.
const hashstr_pbkdf2 = await upash.use('pbkdf2').hash('password');
// => "$pbkdf2-sha512$i=10000$O484sW7giRw+nt5WVnp15w$jEUMVZ9adB+63ko/8Dr9oB1jWdndpVVQ65xRlT+tA1GTKcJ7BWlTjdaiILzZAhIPEtgTImKvbgnu8TS/ZrjKgA"
// If you don't do so it will automatically use the last one installed.
const hashstr_argon2 = await upash.hash('password');
// => "$argon2i$v=19$m=4096,t=3,p=1$mTFYKhlcxmjS/v6Y8aEd5g$IKGY+vj0MdezVEKHQ9bvjpROoR5HPun5/AUCjQrHSIs"
// When you verify upash will automatically choose the algorithm to use based
// on the identifier contained in the hash string.
const match_pbkdf2 = await upash.verify(hashstr_pbkdf2, 'password');
// => true
// This will allow you to easily migrate from an algorithm to another.
const match_argon2 = await upash.verify(hashstr_argon2, 'password');
// => true
Recommended algorithms implementations
The following is a curated list of algorithms that adhere to the upash APIs
guidelines and are ready to work at a production level straight out of the box.
All the functions come pre-configured but fine-tuning is always a good practice.
The defaults are maintained by the community and the aim of this project is also
to bring together experts to be able to provide you reasonably secure default
configurations.
Packages that are implemented natively (Node.js only)
- [@phc/argon2][alg:@phc/argon2] - 🔒 Node.JS argon2 password hashing algorithm following the PHC string format.
- [@phc/pbkdf2][alg:@phc/pbkdf2] - 🔒 Node.JS pbkdf2 password hashing algorithm following the PHC string format.
- [@phc/scrypt][alg:@phc/scrypt] - 🔒 Node.JS scrypt password hashing algorithm following the PHC string format.
- [@phc/bcrypt][alg:@phc/bcrypt] - 🔒 Node.JS bcrypt password hashing algorithm following the PHC string format.
Packages that are implemented in JavaScript (Browser compatible)
- WIP
If you wanna help me with these [DM me on twitter][twitter:simoneprimarosa].
Packages that are implemented in WebAssembly (Browser compatible)
- WIP
If you wanna help me with these [DM me on twitter][twitter:simoneprimarosa].
Want your package listed here? [Open an issue][new issue] and we will review it.
Test configurations through the CLI
<img src="https://github.com/simonepri/upash/raw/master/media/cli.gif" alt="upash cli" width="400" align="right"/>Generally, each function allows configuration of 'work factors’. Underlying mechanisms used to achieve irreversibility and govern work factors (such as time, space, and parallelism) vary between functions.
You want to adjust the work factor to keep pace with threats' increasing hardware capabilities so as to impede attackers while providing acceptable user experience and scale.
A common rule of thumb for tuning the work factor (or cost) is to make the function run as slow as possible without affecting the users' experience and without increasing the need for extra hardware over budget.
The CLI lets you hash and verify password directly from your terminal.
You can use it to test work, memory and parallelism parameters on different
machines.
For installation and usage information about the CLI, see the [upash-cli][gh:upash-cli] page.
Migrating your existing password hashing solution
If you are not building a new application, chances are high that you have
already implemented some hash/verify logic for your passwords.
The [migration guide][docs:migration-guide] provides some good guidance on how
to accomplish an upgrade in place without adversely affecting existing user
accounts and future proofing your upgrade so you can seamlessly upgrade again
(which you eventually will need to do).
Please if you do not find a migration documentation that fits your case, [open an issue][new issue].
