himalayan-salt

Cryptographically strong password salting and hashing library for Node.js

!Photo by Autri Taheri https://unsplash.com/@ataheri?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText

Status: Alpha

I maintain this library for use in my own projects. It is built upon Node.js Crypto which is easy to integrate. You may like to look though this himalayan-salt integration in order to make your own - or install it and use it :)

What's next...

* Implement Scrypt password-based key derivation function version.

Features in this version

---

$3

Returns cryptographically strong, unique 64 character hex encoded salt, and SHA-256 hash for a given passphrase. Returned in an instance of Hashes.

Usage:

- generateSHA256PassphraseHash( 'passphrase') => Hashes instance containing generated salt and hash

Error handling:

- generateSHA256PassphraseHash( 'passwor') => RangeError for string length < 8
- generateSHA256PassphraseHash( 123) => TypeError when argument is other than string
- generateSHA256PassphraseHash() => TypeError when argument is falsey (null, undefined)

Generated strings are returned in a Hashes instance. You can choose to return them separately or combined, depending on your requirements.

+ getSalt() => 64 character hex encoded salt result
+ getHash() => 64 character hex encoded hash result
+ getCombined() => 128 character hex encoded result where the first 64 characters are the salt and the remaining 64 characters are the hash.

---

$3

Verifies a given passphrase against a given salt and hash.

Usage:

- verify( 'passphrase', 64 character hex encoded salt, 64 character hex encoded hash) => true/false

Error handling:

- verify() => TypeError when any argument is not provided
- verify( 'passphrase', 123, 123) => RangeError when salt or hash is not a 64 character string.

---

Overview

- Built upon Crypto.
- SHA-256 unique 32 byte salt generated for each call
- SHA-256 salted passphrase hash
- Salt and hash returned as 64 character hex encoded strings - separate or combined.

```javascript
// demo.js

// ES6 import
import {himalayanSalt} from './himalayan-salt.js';
// or require
// const hs = require('./himalayan-salt.js');
// const himalayanSalt = hs.himalayanSalt;

const passphrase1 = 'testY9O/<2uWguEU';
console.log(passphrase is: ${passphrase1});
const result1 = himalayanSalt.generate(passphrase1);
console.log(SALT >>> ${result1.getSalt()});
console.log(HASH >>> ${result1.getHash()});
console.log(COMBINED >>> ${result1.getCombined()});
console.log(VERIFICATION >>> ${himalayanSalt.verify(passphrase1, result1.getSalt(), result1.getHash())});

const passphrase2 = 'testY9O/<2uWguEU'; // same passphrase
console.log(passphrase is: ${passphrase2});
const result2 = himalayanSalt.generate(passphrase2);
console.log(SALT >>> ${result2.getSalt()}); // unique salt,
console.log(HASH >>> ${result2.getHash()}); // and hash
console.log(COMBINED >>> ${result2.getCombined()});
console.log(VERIFICATION >>> ${himalayanSalt.verify(passphrase2, result2.getSalt(), result2.getHash())});
``

Output...

``
passphrase is: testY9O/<2uWguEU
SALT >>> e4f4b47ac78e90c647cb78f30dff5f07517a6a9a11ff896dcf8b3c9946039f1f
HASH >>> 1f2b189c0991287baa5ac597229aa6626d79c6f4201d8fb869697fd30f1f2f89
COMBINED >>> e4f4b47ac78e90c647cb78f30dff5f07517a6a9a11ff896dcf8b3c9946039f1f1f2b189c0991287baa5ac597229aa6626d79c6f4201d8fb869697fd30f1f2f89
VERIFICATION >>> true

passphrase is: testY9O/<2uWguEU
SALT >>> 1450c8044a9334b83bbe77dbfe858c455051f709162275c107519d573e9210d0
HASH >>> 42a6e24e481fdc100b6447d3ae1a935ea455f578f43ad7be2b6cf059233be0f8
COMBINED >>> 1450c8044a9334b83bbe77dbfe858c455051f709162275c107519d573e9210d042a6e24e481fdc100b6447d3ae1a935ea455f578f43ad7be2b6cf059233be0f8
VERIFICATION >>> true
``




Download

Prerequisite: Node.js 13.5x installation.

``bash
user $ git clone git@github.com:burntsugar/himalayan-salt.git
user $ cd himalayan-salt
user/himalayan-salt $ npm install
``

$3

Compile .ts to .js in ./out

``bash
user/himalayan-salt $ npm run tsc
``

$3

(compile first!)

Run Jest test suites.

``bash
user/himalayan-salt $ npm test
``

$3

(compile first!)

``bash
user/himalayan-salt $ npm run demo
``




Install into your own project

``bash
npm install --save himalayan-salt
``

``javascript
// your.js

// ES6 import
import {himalayanSalt} from 'himalayan-salt';
``

...or...

``javascript
// your.js

// require
const hs = require('himalayan-salt');
``




Standalone

Start with -v | -verify followed by passphrase, salt and hash.

Start with -g | -generate followed by passphrase.




Docker

docker pull burntsugar/himalayan-salt

$3


docker run --rm himalayan-salt demo

$3

docker run --rm himalayan-salt -generate

$3

docker run --rm himalayan-salt -verify `

See dockerhub repository

Modern password security for system designers

This project is guided by Modern password security for system designers.

Passwords...

> *Allow the largest character set possible, such as
UTF-8, including emoji.*

> *Have a long minimum length and allow very long
passwords.*

What's inside

* TDD~categories~(~))~searchTerm~'TDD~sort~false~sortDirection~'asc~page~1))
* TypeScript
* Crypto
* Jest
* ES6

---

rrr@burntsugar.rocks