Credentials

Secure password hashing and verification with core Node.js modules.

• Time consuming hashing (PBKDF2 with SHA-512) to combat brute force
• Per password salt to combat rainbow tables
• Incrementing work/complexity to combat future computing advances
• Constant time equality check to combat timing attacks

const {hash, verify} = require('credentials')

verify(hash('password'), 'password') // → true

If you find a security flaw in this code, please contact [email protected].

Usage

npm install credentials

const {hash, verify, expired} = require('credentials')

hash(password /*[, opts]*/) // → hashed (string), ready for storage
verify(hashed, password) // → isValid (Boolean)
expired(hashed /*[, days[, opts]]*/) // → isExpired (Boolean)

hash optionally accepts an object literal of configuration values. Defaults to:

{
  keyLength: 64,  // length of salt
  work: 1,        // relative work load (0.5 for half the work)
}

expired optionally accepts an object literal of configuration values. Defaults to:

{
  work: 1,
}

Preconfigured functions:

const {hash, verify, expired} = require('credentials').configure({
  // defaults:
  keyLength: 64,
  work: 1,
  expiry: 90,
})

Examples

Sign up

const {hash} = require('credentials')

hash(userInput).then(hashed => saveHash(hashed))

Sign in

const {verify} = require('credentials')

verify(hashed, userInput).then(isValid => {
  if (!isValid) throw new Error('Bad credentials')

  // allow access
})

CLI

$ credentials --help

  Usage: cmd [options] [command]


  Commands:

    hash [options] [password]  Hash password
    verify [hash] <password>   Verify password

  Options:

    -h, --help  output usage information

$ credentials hash --help

  Usage: hash [options] [password]

  Hash password

  Options:

    -h, --help                    output usage information
    -w --work <work>              relative work load (0.5 for half the work)
    -k --key-length <key-length>  length of salt

The password argument for hash and the hash argument for verify both support piping by replacing with a dash (-):

$ echo -n "my password" | credentials hash - | credentials verify - "my password"
Verified

Exit codes 0 and 1 are used to communicate verified or invalid as well.

Expiry

The expiry configuration value is used entirely by the expired method. verify does not check if a password is expired.

The main purpose of this concept is to tell the user to update their password.

Inspiration

This was initially a fork of @ericelliott's great effort at https://github.com/ericelliott/credential with the main differences being:

• Better default values (SHA-512 and a key length of 64 bytes)
• Promises
• There's a CLI
• Each instance is separate - no globals or leak to other instances

Produced hashes are compatible.

A merge was not possible due to differences discovered in https://github.com/ericelliott/credential/issues/25