![\"upash\"](\"https://github.com/simonepri/upash/raw/master/media/upash.png\")
\n \n\n \n \n \n
\n \n \n ![\"Mac/Linux](\"https://img.shields.io/travis/com/simonepri/upash/master.svg?label=MacOS%20%26%20Linux\")
\n \n \n \n ![\"Windows](\"https://img.shields.io/appveyor/ci/simonepri/upash/master.svg?label=Windows\")
\n \n \n \n ![\"Codecov](\"https://img.shields.io/codecov/c/github/simonepri/upash/master.svg\")
\n \n \n \n ![\"Known](\"https://snyk.io/test/github/simonepri/upash/badge.svg?targetFile=package.json\"){kind=icon}
\n \n \n \n ![\"Dependency](\"https://david-dm.org/simonepri/upash/status.svg\")
\n \n\n
\n\n \n \n ![\"XO](\"https://img.shields.io/badge/code_style-XO+Prettier-5ed9c7.svg\"){kind=icon}
\n \n \n \n ![\"AVA](\"https://img.shields.io/badge/test_runner-AVA-fb3170.svg\"){kind=icon}
\n \n \n \n ![\"Istanbul](\"https://img.shields.io/badge/test_coverage-NYC-fec606.svg\"){kind=icon}
\n \n \n \n ![\"NI](\"https://img.shields.io/badge/initialized_with-ni-e74c3c.svg\"){kind=icon}
\n \n \n \n ![\"NP](\"https://img.shields.io/badge/released_with-np-6c8784.svg\"){kind=icon}
\n \n\n
\n\n \n \n ![\"Mentioned](\"https://awesome.re/mentioned-badge.svg\"){kind=icon}
\n \n \n \n ![\"Latest](\"https://img.shields.io/npm/v/upash.svg\")
\n \n \n \n ![\"Project](\"https://img.shields.io/github/license/simonepri/upash.svg\")
\n \n
\n π Unified API for PASsword Hashing algorithms\n\n
\n\n \n Coded with β€οΈ by Simone Primarosa.\n \n
![\"upash](\"https://github.com/simonepri/upash/raw/master/media/api.png\")
\n\nThe upash ([pronounced u-pash][upash:pronounce]) project aims is to allow you to\nhave a clean and easy-to-use API to use any password hashing algorithm\nseamlessly in your application.\n***\n\n#### Highlights\n- Simple API for all password hashing algorithms\n- Easy to maintain and [upgradable](#upgrading-your-password-hashing-algorithm) logic\n- Easy to test configurations through the [CLI](#test-configurations-through-the-cli)\n- Step by step [migration guide](#migrating-your-existing-password-hashing-solution)\n- Comprehensive list of supported [hashing algorithms](#recommended-algorithms-implementations)\n\nDo you believe that this is useful? Has it saved you time? Or maybe you simply like it? \nIf so, [support my work with a Star βοΈ][start].\n\n## Usage\nThe upash solution is straight-forward but it is important to follow all the\nsteps carefully.\n\nFirstly, you need to install this package.\n\n```bash\nnpm install --save upash\n```\nThen, you need to choose from the\n[list of supported password hashing algorithms](#recommended-algorithms-implementations)\nthe one that best suits your needs and install that too. \nIn the following, we will assume that you choose `@phc/argon2`, that is also a\nsuitable solution in case you don't know which one fits better for you.\n\n```bash\nnpm install --save @phc/argon2\n```\n\nFinally, you can enjoy the easy APIs.\n\n```js\nconst upash = require('upash');\n\n// Install the algorithm of your choice.\nupash.install('argon2', require('@phc/argon2'));\n\n// Hash API\nconst hashstr = await upash.hash('password');\n// => \"$argon2id$v=19$m=4096,t=3,p=1$PcEZHj1maR/+ZQynyJHWZg$2jEN4xcww7CYp1jakZB1rxbYsZ55XH2HgjYRtdZtubI\"\n\n// Verify API\nconst match = await upash.verify(hashstr, 'password');\n// => true\n```\n\nYou can store the hash returned by the `hash` function directly into your database.\n\nYou can also install more than one algorithm at once. \nThis is really handy when you want to update your current password hashing\nalgorithm.\n\n```js\nconst upash = require('upash');\n\n// Install the algorithms of your choice.\nupash.install('pbkdf2', require('@phc/pbkdf2'));\nupash.install('argon2', require('@phc/argon2'));\n\n// You can explicitly tell upash which algorithm to use.\nconst hashstr_pbkdf2 = await upash.use('pbkdf2').hash('password');\n// => \"$pbkdf2-sha512$i=10000$O484sW7giRw+nt5WVnp15w$jEUMVZ9adB+63ko/8Dr9oB1jWdndpVVQ65xRlT+tA1GTKcJ7BWlTjdaiILzZAhIPEtgTImKvbgnu8TS/ZrjKgA\"\n\n// If you don't do so it will automatically use the last one installed.\nconst hashstr_argon2 = await upash.hash('password');\n// => \"$argon2i$v=19$m=4096,t=3,p=1$mTFYKhlcxmjS/v6Y8aEd5g$IKGY+vj0MdezVEKHQ9bvjpROoR5HPun5/AUCjQrHSIs\"\n\n// When you verify upash will automatically choose the algorithm to use based\n// on the identifier contained in the hash string.\nconst match_pbkdf2 = await upash.verify(hashstr_pbkdf2, 'password');\n// => true\n\n// This will allow you to easily migrate from an algorithm to another.\nconst match_argon2 = await upash.verify(hashstr_argon2, 'password');\n// => true\n```\n\n## Recommended algorithms implementations\nThe following is a curated list of algorithms that adhere to the upash APIs\nguidelines and are ready to work at a production level straight out of the box. \nAll the functions come pre-configured but fine-tuning is always a good practice. \nThe defaults are maintained by the community and the aim of this project is also\nto bring together experts to be able to provide you reasonably secure default\nconfigurations.\n\n#### Packages that adhere to the PHC string format\n- [@phc/argon2][alg:@phc/argon2]\n- [@phc/pbkdf2][alg:@phc/pbkdf2]\n- [@phc/scrypt][alg:@phc/scrypt]\n- [@phc/bcrypt][alg:@phc/bcrypt]\n\n#### Other packages\n- N/A\n\nWant your package listed here? [Open an issue][new issue] and we will review it.\n\n## Test configurations through the CLI\n![\"upash](\"https://github.com/simonepri/upash/raw/master/media/cli.gif\")
\n\nGenerally, each function allows configuration of 'work factorsβ.\nUnderlying mechanisms used to achieve irreversibility and govern work factors\n(such as time, space, and parallelism) vary between functions. \n\nYou want to adjust the work factor to keep pace with threats' increasing hardware\ncapabilities so as to impede attackers while providing acceptable user experience\nand scale.\n\nA common rule of thumb for tuning the work factor (or cost) is to make the\nfunction run as slow as possible without affecting the users' experience and\nwithout increasing the need for extra hardware over budget.\n\nThe CLI lets you hash and verify password directly from your terminal. \nYou can use it to test work, memory and parallelism parameters on different\nmachines.\n\nFor installation and usage information about the CLI, see the\n[upash-cli][gh:upash-cli] page.\n\n## Migrating your existing password hashing solution\nIf you are not building a new application, chances are high that you have\nalready implemented some hash/verify logic for your passwords. \nThe [migration guide][docs:migration-guide] provides some good guidance on how\nto accomplish an upgrade in place without adversely affecting existing user\naccounts and future proofing your upgrade so you can seamlessly upgrade again\n(which you eventually will need to do).\n\nPlease if you do not find a migration documentation that fits your case,\n[open an issue][new issue].\n\n## Upgrading your password hashing algorithm\nUpgrading the hashing algorithm used to hash passwords inside your application\ncan be a really painful operation if not done well.\nYou should take a lot of attention in order to not adversely affect existing\nuser accounts. \n\n[This article][docs:ext:upgrade-algorithm] is a nice start that should give you\nsome ideas on what are the problems related to that process. \n\nExample of implementations can be found in the\n[upgrade algorithm guide][docs:upgrade-algorithm].\n\n## API\nInstalls a compatible password hashing function.
\nUninstalls a password hashing function previously installed.
\nArray.<string>Gets the list of the installed password hashing functions.
\nObjectSelects manually which password hashing function to use.\nYou can call hash and verify on the object returned.
\nstring | nullReturns the name of the algorithm that has generated the hash string.
\nPromise.<boolean>Determines whether or not the hash provided matches the hash generated for\nthe given password choosing the right algorithm based on the identifier\ncontained in the hash.
\nPromise.<string>Computes the hash string of the given password using the 'last' algorithm\ninstalled.
\nstring | The name of the password hashing function. |\n| algorithm | Object | The password hashing function object. |\n| algorithm.hash | function | A function that takes a password and returns a cryptographically secure password hash string. |\n| algorithm.verify | function | A function that takes a secure password hash string and a password and returns whether or not the password is valid for the given hash string. |\n| algorithm.identifiers | function | A function that returns the list of identifiers that this password hashing algorithm is able to generate / verify. |\n\n\n\n### uninstall(name)\nUninstalls a password hashing function previously installed.\n\n**Kind**: global function \n**Access**: public \n\n| Param | Type | Description |\n| --- | --- | --- |\n| name | string | The name of the algorithm to uninstall or 'last' to uninstall the last one installed. |\n\n\n\n### list() β Array.<string>\nGets the list of the installed password hashing functions.\n\n**Kind**: global function \n**Returns**: Array.<string> - The array of the available password hashing\nfunctions. \n**Access**: public \n\n\n### use(name) β Object\nSelects manually which password hashing function to use.\nYou can call hash and verify on the object returned.\n\n**Kind**: global function \n**Returns**: Object - The password hashing function object. \n**Access**: public \n\n| Param | Type | Description |\n| --- | --- | --- |\n| name | string \\| undefined | The name of the algorithm to use. |\n\n\n\n### which(hashstr) β string \\| null\nReturns the name of the algorithm that has generated the hash string.\n\n**Kind**: global function \n**Returns**: string \\| null - The name of password hashing algorithm. \n**Access**: public \n\n| Param | Type | Description |\n| --- | --- | --- |\n| hashstr | string | Secure hash string generated from this package. |\n\n\n\n### verify(hashstr, password) β Promise.<boolean>\nDetermines whether or not the hash provided matches the hash generated for\nthe given password choosing the right algorithm based on the identifier\ncontained in the hash.\n\n**Kind**: global function \n**Returns**: Promise.<boolean> - A boolean that is true if the hash computed\nfor the password matches. \n**Access**: public \n\n| Param | Type | Description |\n| --- | --- | --- |\n| hashstr | string | Secure hash string generated from this package. |\n| password | string | User's password input. |\n\n\n\n### hash(password, [options]) β Promise.<string>\nComputes the hash string of the given password using the 'last' algorithm\ninstalled.\n\n**Kind**: global function \n**Returns**: Promise.<string> - The generated secure hash string. \n**Access**: public \n\n| Param | Type | Description |\n| --- | --- | --- |\n| password | string | The password to hash. |\n| [options] | Object | Optional configurations related to the hashing function. See the algorithm specific documentation for the options supported. |\n\n## Contributing\nContributions are REALLY welcome and if you find a security flaw in this code,\nPLEASE [report it][new issue]. \n\n## Authors\n- **Simone Primarosa** - *Github* ([@simonepri][github:simonepri]) β’ *Twitter* ([@simoneprimarosa][twitter:simoneprimarosa])\n\nSee also the list of [contributors][contributors] who participated in this project.\n\n## License\nThis project is licensed under the MIT License - see the [license][license] file for details.\n\n\n[start]: https://github.com/simonepri/upash#start-of-content\n[new issue]: https://github.com/simonepri/upash/issues/new\n[contributors]: https://github.com/simonepri/upash/contributors\n\n[license]: https://github.com/simonepri/upash/tree/master/license\n\n[gh:upash-cli]: https://github.com/simonepri/upash-cli\n\n[alg:@phc/argon2]: https://github.com/simonepri/upash-argon2\n[alg:@phc/scrypt]: https://github.com/simonepri/upash-scrypt\n[alg:@phc/bcrypt]: https://github.com/simonepri/upash-bcrypt\n[alg:@phc/pbkdf2]: https://github.com/simonepri/upash-pbkdf2\n\n[github:simonepri]: https://github.com/simonepri\n[twitter:simoneprimarosa]: http://twitter.com/intent/user?screen_name=simoneprimarosa\n\n[argon2:password-competition]: https://password-hashing.net/\n[upash:pronounce]: https://translate.google.com/translate_tts?ie=UTF-8&client=tw-ob&tl=en&q=u-pash\n\n[docs:migration-guide]: https://github.com/simonepri/upash/tree/master/docs/migrate-your-solution.md\n[docs:upgrade-algorithm]: https://github.com/simonepri/upash/tree/master/docs/upgrade-algorithm.md\n[docs:password-hashing-theory]: https://github.com/simonepri/upash/tree/master/docs/password-hashing-theory.md\n[docs:ext:upgrade-algorithm]: https://veggiespam.com/painless-password-hash-upgrades/\n\n[breach:yahoo]: https://help.yahoo.com/kb/account/SLN27925.html\n[breach:yahoo2]: https://help.yahoo.com/kb/account/sln28092.html\n[breach:linkedin]: https://motherboard.vice.com/en_us/article/78kk4z/another-day-another-hack-117-million-linkedin-emails-and-password\n[breach:adobe]: https://www.troyhunt.com/adobe-credentials-and-serious/\n[breach:ashley-madison]: https://krebsonsecurity.com/2015/07/online-cheating-site-ashleymadison-hacked/\n[breach:hibp-breaches]: https://haveibeenpwned.com/PwnedWebsites\n","readmeFilename":"readme.md"}