README

genpass-lib

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

NPM module

npm install genpass-lib

Usage

var genpass = require('genpass-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';

// Generate the password.
var generatedPassword = genpass(masterPassword, URI, {/* options */});

Options

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

length

Default 8
Expects Number

Length of the generated password. Valid lengths are integers between 4 and 32 inclusive.

passwordCase

Default lowercase
Expects String

A string indicating desired password case. Valid values are lowercase, uppercase, and mixed.

Domain name isolation

By default, genpass-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.

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

// Isolate a domain name from a URL using GenPass's rules.
var hostname = genpass.hostname('http://login.example.com/doLogin.htm');

Browser environments

To use genpass-lib in browser environments, run gulp browserify. Take the created dist/genpass-lib.browser.js and include it on your page. Use the global genpass as documented above.

Explanation of the algorithm

GenPass 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 a hash function (MD5). The hash is then cut to the user's preferred password length.

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

Dependencies and license

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

Usage no npm install needed!