v0.2.2

Copyright 2017 Nic Jansma

http://nicj.net

Licensed under the MIT license

saltthepass.js is the algorithm that generates salted passwords for SaltThePass.com.

saltthepass.js can be used to build your own app, website or program to generate the same salted passwords as saltthepass.com does.

Releases are available for download from GitHub.

Development: src/* folder ~ 17kb total

Production (without CryptoJS): saltthepass.min.js ~ 1.5kb (minified / gzipped)

Production (with CryptoJS built-in): saltthepass.withdeps.min.js ~ 8.5kb (minified / gzipped)

saltthepass.js is also available as the npm saltthepass module. You can install it using Node Package Manager (npm):

npm install saltthepass

Please see SaltThePass.com for a description of how/why you would use salted passwords.

saltthepass.js depends on the CryptoJS library. SaltThePass is tested to work with CryptoJS v3.1.2, which can be installed via the bower cryptojslib package.

You will need to load the following CryptoJS modules in this order prior to using saltthepass.js, if not using one of the pre-built versions in dist/ such as saltthepass.withdeps.js or saltthepass.withdeps.min.js:

• crypto-js/core
• crypto-js/x64-core
• crypto-js/sha1
• crypto-js/sha512
• crypto-js/sha3
• crypto-js/md5
• crypto-js/ripemd160
• crypto-js/enc-base64

To use un-minified versions of saltthepass.js in the browser, you need to have the cryptojslib bower package:

bower install cryptojslib

Then load the files in this order:

<script type="text/javascript" src="deps/crypto-js/core.js"></script>
<script type="text/javascript" src="deps/crypto-js/x64-core.js"></script>
<script type="text/javascript" src="deps/crypto-js/sha1.js"></script>
<script type="text/javascript" src="deps/crypto-js/sha512.js"></script>
<script type="text/javascript" src="deps/crypto-js/sha3.js"></script>
<script type="text/javascript" src="deps/crypto-js/md5.js"></script>
<script type="text/javascript" src="deps/crypto-js/ripemd160.js"></script>
<script type="text/javascript" src="deps/crypto-js/enc-base64.js"></script>
<script type="text/javascript" src="src/util.js"></script>
<script type="text/javascript" src="src/domainnamerule.js"></script>
<script type="text/javascript" src="src/saltthepass.js"></script>

The file dist/saltthepass.withdeps.js is a single JavaScript file with all of the above components in the correct order, so it can be used instead if desired:

<script type="text/javascript" src="dist/saltthepass.withdeps.js"></script>

There are two minified versions of saltthepass.js provided in the dist/ folder:

• saltthepass.min.js - Does not include CryptoJS
• saltthepass.withdeps.min.js - Includes CryptoJS

If your site already has the required CryptoJS modules loaded, you can use saltthepass.min.js.

If you are not already using CryptoJS, you can use saltthepass.withdeps.min.js.

To use saltthepass.js in NodeJS, you just need to install:

npm install saltthepass

Then require() it:

var saltthepass = require('saltthepass');
var saltedPassword = saltthepass.saltthepass('md5', 'mypassword', 'mydomain', 'myphrase');

First, load saltthepass.js in the browser:

<script type="text/javascript" src="dist/saltthepass.withdeps.min.js"></script>

or in Node:

var saltthepass = require('saltthepass');

Next, you can get a list of available hashes:

var hashes = saltthepass.getHashes();

This will be a list of strings, such as md5, sha3, etc. You can get additional data about the hashes via saltthepass.getHashFn() and saltthepass.getHashLength().

To generate a salted password, you simply call saltthepass.saltthepass() with the master password, domain name and (optional) domain phrase:

var saltedPassword = saltthepass.saltthepass('md5', 'mypassword', 'domain.com', 'domain phrase');

After getting your saltthepass object (see above), create a new DomainNameRule:

var dnr = new saltthepass.DomainNameRule({
    domain: 'foo.com',
    aliases: ['a.foo.com', 'b.foo.com'],
    min: 8,
    max: 16,
    regex: 'A-Z0-9'
});

Now that you have a DomainNameRule, you can see if it matches your domain, if your password is valid, and have it attempt to automatically rewrite your password if not:

if (dnr.matches('foo.com')) {
    if (!dnr.isValid('mypassword')) {
        var myNewPassword = dnr.rewrite('mypassword');
    }
}

Gets the CryptoJS hash function for a specific hash.

Arguments

• hashName - Name of the hash, eg md5

Returns

Hashing function.

Standardizes a domain name for use with DomainNameRules.

For example, will take http://foo.com/path and return foo.com.

Arguments

• url - URL

Returns

Standardized domain for use in DomainNameRules.

saltthepass.js tests are provided in the test/ directory, and can be run via nodeunit:

nodeunit test/test.js

Or via grunt:

grunt test

The tests can also be run in a web browser:

test/test.html

• v0.1.0 - 2013-05-22: Initial version
• v0.2.0 - 2013-07-16: DomainNameRule and standardizeDomain() added.
• v0.2.1 - 2013-07-17: DomainNameRule.validregex added
• v0.2.2 - 2013-07-17: DomainNameRule.validregex and DomainNameRule.regex are case-sensitive now