supergenpass-lib

This is the official JavaScript implementation of SuperGenPass. It provides the code used by the bookmarklet and mobile version of SuperGenPass to generate passwords. If you are building or have built your own JavaScript-based application for SuperGenPass, please consider using this library.

NPM module

npm install supergenpass-lib

Usage

var sgp = require('supergenpass-lib');
 
// A string containing the user's master password.
var masterPassword = 'master-password';
 
// A URI or hostname of the site being visited.
var URI = 'http://www.example.com/page.html';
 
// A callback function to accept the generated password.
var callback = function (password) {/* code */};
 
// Generate the password.
sgp.generate(masterPassword, URI, {/* options */}, callback);

Note: Version 3.0.0 introduces the generate method instead of making this function the root export. This change was made to align with ES6 exports.

Options

As shown above, supergenpass-lib optionally accepts a hash map of options.

hashRounds

• Default 10
• Expects Number

Minimum number of rounds to hash the input. (Hashing may continue past the minimum until the password validation rules are satisfied.)

length

• Default 10
• Expects Number

Length of the generated password. Valid lengths are integers between 4 and 24 inclusive. Note that 23- and 24-character MD5-based passwords provide no additional entropy. (The value for those characters will always be A.)

method

• Default 'md5'
• Expects String or Function

A string specifying the requested hash function. The only supported string values are 'md5' or 'sha512'.

Alternatively, you can supply your own hash function. This hash function must accept a string value and return a string value. Returned hashes should be at least 24 characters and will be subject to SGP’s password validation rules.

removeSubdomains

• Default true
• Expects Boolean

A boolean value directing whether or not to remove subdomains from the hostname before generating the password.

secret

• Default ''
• Expects String

A secret password to be appended to the master password before generating the password. This option is provided for convenience, as the same output can be produced by manually concatenating the master and secret passwords.

Domain name isolation

By default, supergenpass-lib isolates the domain name (e.g., example.com) from the hostname by removing all subdomains. This ensures that the same password is generated at example.com, www.example.com, and login.example.com. It additionally uses a hardcoded list of country-code and special-purpose TLDs to produce different passwords across sites registered there. While this list is no doubt incomplete and out-of-date, it remains static to maintain backwards compatibility. You can disable subdomain removal in the options.

To help provide user feedback about the exact hostname used to generate the password, supergenpass-lib provides a hostname method that can be used separately.

// Isolate a domain name from a URL using SuperGenPass's rules.
var hostname = supergenpass.hostname('http://login.example.com/doLogin.htm', {
  removeSubdomains: true  // default = true
});

Explanation of the algorithm

SuperGenPass is a very simple password hashing scheme. At its essence, it takes a master password and a hostname and concatenates them together:

masterpassword:example.com

It uses this as the input for the user's preferred hash function. It guarantees hashing at least ten times to protect against rainbow tables. The hash is then cut to the user's preferred password length.

For more detail, please see the (well-commented and concise) source code.

Tests

Tests require Node >=4.0. Run npm test.

Dependencies and license

Hash functions are provided by crypto-js. All original code is released under the GPLv2.

Thanks

Development of this library was helped tremendously by Denis Sokolov, author of the SuperGenPass Chrome extension.