Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    saltthepasspublic

    saltthepass.js

    v0.2.1

    Copyright 2013 Nic Jansma

    http://nicj.net

    Licensed under the MIT license

    Introduction

    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 password as saltthepass.com does.

    Download

    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 using Node Package Manager (npm):

    npm install saltthepass
    

    Usage

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

    Requirements

    saltthepass.js depends on the CryptoJS library. SaltThePass is tested to work with CryptoJS v3.1.2, which is included in the deps/crypto-js folder.

    You will need to load the following CryptoJS modules in this order prior to loading saltthepass.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

    Browser - Development Versions

    To use un-minified versions of saltthepass.js in the browser, you need to 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>

    Browser - Minified Versions

    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.

    NodeJS

    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');

    Examples

    Using SaltThePass

    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');

    Using DomainNameRules

    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');
        }
    }

    Documentation

    ### saltthepass.getHashes()

    Gets a list of supported hashes.

    Returns

    A list of supported hash names.

    For example: ['md5', 'sha1', 'sha2', 'sha3', 'ripemd160']

    ### saltthepass.getHashFn(hashName)

    Gets the CryptoJS hash function for a specific hash.

    Arguments

    • hashName - Name of the hash, eg md5

    Returns

    Hashing function.

    ### saltthepass.getHashLength(hashName)

    Gets the number of Base64 characters the hash function will return.

    Arguments

    • hashName - Name of the hash, eg md5

    Returns

    Number of characters of the hash.

    ### saltthepass.hash(hashName, phrase)

    Hashes the specified phrase.

    Arguments

    • hashName - Name of the hash, eg md5
    • phrase - Phrase to hash

    Returns

    The Base64 encoded hashed phrase.

    ### saltthepass.saltthepass(hashName, masterPassword, domainName, domainPhrase)

    Generates a salted password identical to saltthepass.com.

    Arguments

    • hashName - Name of the hash, eg md5
    • masterPassword - Master password
    • domainName - Domain name
    • domainPhrase - Domain phrase (optional)

    Returns

    The salted password.

    ### saltthepass.standardizeDomain(url)

    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.DomainNameRule(data)

    Creates a Domain Name Rule.

    Arguments

    • data - Can contain any of the following options:
      • domain - Domain name (eg. 'foo.com')
      • aliases - Array of additional domain names that will match (eg. ['a.foo.com', 'b.foo.com'])
      • description - Description
      • min - Minimum number of characters in the password
      • max - Maximum number of characters in the password
      • invalid - An array of characters that are not allowed in the password (eg. ['!', '_'])
      • required - An array of characters where one of the characters needs to be in the password (eg. ['-', '!'])
      • validregex - A simplified regular expression that would fit in a character set (eg. A-Z0-9, which would fit in [A-Z0-9]). The regular expression is run case-sensitive. validregex should be used in preference over regex (which can contain full regular expressions, not just a character sets), as validregex can easily be inverted (eg [^A-Z0-9]) so passwords can be rewritten if they contain invalid characters.
      • regex - A full regular expression that the password must match. The regex is run case-sensitive.

    Returns

    A DomainNameRule class.

    ### DomainNameRule.matches(domain)

    Determines whether or not the Domain Name Rule matches the specified domain.

    Arguments

    • domain - Domain to match against

    Returns

    True if the Domain Name Rule matches the domain.

    ### DomainNameRule.isValid(password)

    Determines whether or not the Domain Name Rule would pass for the specified password.

    Arguments

    • password - Password to check

    Returns

    True if the Domain Name Rule would pass for the specified password.

    ### DomainNameRule.rewrite(password)

    Attempts to rewrite the password (in a stable and consistent manner) to match the Domain Name Rule.

    Arguments

    • password - Password to rewrite

    Returns

    Rewritten password if possible. Otherwise, undefined.

    Tests

    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
    

    Version History

    • 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

    Keywords

    none

    install

    npm i saltthepass

    Downloadslast 7 days

    5

    version

    0.2.2

    license

    none

    repository

    github.com

    last publish

    collaborators

    • avatar