himalayan-salt

Cryptographically strong password salting and hashing library for Node.js

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

+ generate(passphrase)

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.

+ verify(passphrase, salt, hash)

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.

// 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.

user $ git clone [email protected]:burntsugar/himalayan-salt.git
user $ cd himalayan-salt
user/himalayan-salt $ npm install

Compile TypeScript

Compile .ts to .js in ./out

user/himalayan-salt $ npm run tsc

Test

(compile first!)

Run Jest test suites.

user/himalayan-salt $ npm test

Run demo

(compile first!)

user/himalayan-salt $ npm run demo

Install into your own project

npm install --save himalayan-salt

// your.js

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

...or...

// 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

Demo

docker run --rm himalayan-salt demo

Generate salt and hash

docker run --rm himalayan-salt -generate <passphrase>

Verify passphrase

docker run --rm himalayan-salt -verify <passphrase> <salt> <hash>

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
• TypeScript
• Crypto
• Jest
• ES6

rrr@burntsugar.rocks