Skip to content

Commit

Permalink
v0.2.0: standardizeDomain() and DomainNameRule added
Browse files Browse the repository at this point in the history
  • Loading branch information
@nicjansma
nicjansma committed Jul 16, 2013
1 parent 9022e85 commit d0990be
Show file tree
Hide file tree
Showing 13 changed files with 938 additions and 179 deletions.
44 changes: 24 additions & 20 deletions Gruntfile.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,11 @@ module.exports = function(grunt) {
build: {
files: {
'dist/<%= pkg.name %>.min.js': [
'src/<%= pkg.name %>.js'
'src/utils.js',
'src/domainnamerule.js',
'src/saltthepass.js'
],
'dist/<%= pkg.name %>.withcryptojs.min.js': [
'dist/<%= pkg.name %>.withdeps.min.js': [
'deps/crypto-js/core.js',
'deps/crypto-js/x64-core.js',
'deps/crypto-js/sha1.js',
Expand All @@ -20,33 +22,35 @@ module.exports = function(grunt) {
'deps/crypto-js/md5.js',
'deps/crypto-js/ripemd160.js',
'deps/crypto-js/enc-base64.js',
'src/<%= pkg.name %>.js'
'src/utils.js',
'src/domainnamerule.js',
'src/saltthepass.js'
]
}
}
},
jshint: {
files: [ 'src/**/*.js', 'test/**/*.js' ],
options: {
bitwise: true,
camelcase: true,
curly: true,
eqeqeq: true,
forin: true,
bitwise: true,
camelcase: true,
curly: true,
eqeqeq: true,
forin: true,
immed: true,
indent: 4,
latedef: true,
newcap: true,
noempty: true,
nonew: true,
quotmark: true,
indent: 4,
latedef: true,
newcap: true,
noempty: true,
nonew: true,
quotmark: true,
jquery: true,
undef: true,
unused: true,
strict: true,
trailing: true,
browser: true,
node: true,
undef: true,
unused: true,
strict: true,
trailing: true,
browser: true,
node: true,
white: false,
globals: {
define: true,
Expand Down
159 changes: 132 additions & 27 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# saltthepass.js

v0.1.0
v0.2.0

Copyright 2013 Nic Jansma

Expand All @@ -19,14 +19,14 @@ saltthepass.js can be used to build your own app, website or program to generate

Releases are available for download from [GitHub](https://github.com/nicjansma/saltthepass.js).

__Development:__ [saltthepass.js](https://github.com/nicjansma/saltthepass.js/raw/master/src/saltthepass.js)
- 6,861b
__Development:__ [src/* folder](https://github.com/nicjansma/saltthepass.js/raw/master/src/)
~ 17kb total

__Production (without CryptoJS):__ [saltthepass.min.js](https://github.com/nicjansma/saltthepass.js/raw/master/dist/saltthepass.min.js)
- 650b (minified / gzipped)
~ 1.5kb (minified / gzipped)

__Production (with CryptoJS built-in):__ [saltthepass.withcryptojs.min.js](https://github.com/nicjansma/saltthepass.js/raw/master/dist/saltthepass.withcryptojs.min.js)
- 7,658b (minified / gzipped)
__Production (with CryptoJS built-in):__ [saltthepass.withdeps.min.js](https://github.com/nicjansma/saltthepass.js/raw/master/dist/saltthepass.withdeps.min.js)
~ 8.5kb (minified / gzipped)

saltthepass.js is also available as the [npm saltthepass module](https://npmjs.org/package/saltthepass). You can install
using Node Package Manager (npm):
Expand All @@ -40,8 +40,9 @@ Please see [SaltThePass.com](https://saltthepass.com/) for a description of how/
### Requirements

saltthepass.js depends on the [CryptoJS library](http://code.google.com/p/crypto-js/). 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:
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
Expand All @@ -65,28 +66,29 @@ To use un-minified versions of saltthepass.js in the browser, you need to load t
<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:
There are two minified versions of saltthepass.js provided in the `dist/` folder:

* ``saltthepass.min.js`` - Does not include CryptoJS
* ``saltthepass.withcryptojs.min.js`` - Include CryptoJS
* `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 your site already has the required CryptoJS modules loaded, you can use `saltthepass.min.js`.

If you are not already using CryptoJS and do not need to add additional CryptoJS modules, you can use
``saltthepass.withcryptojs.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:
Then `require()` it:

```js
var saltthepass = require('saltthepass');
Expand All @@ -95,10 +97,12 @@ var saltedPassword = saltthepass.saltthepass('md5', 'mypassword', 'mydomain', 'm

### Examples

#### Using SaltThePass

First, load saltthepass.js in the browser:

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

or in Node:
Expand All @@ -114,30 +118,55 @@ 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()``](#getHashFn) and [``saltthepass.getHashLength()``](#getHashLength).
[`saltthepass.getHashFn()`](#getHashFn) and [`saltthepass.getHashLength()`](#getHashLength).

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

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

#### Using DomainNameRules

After getting your `saltthepass` object (see above), create a new [`DomainNameRule`](#DomainNameRule):

```js
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`](#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:

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

## Documentation

<a name="getHashes" />
### getHashes()
### saltthepass.getHashes()

Gets a list of supported hashes.

__Returns__

A list of supported hash names.

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

<a name="getHashFn" />
### getHashFn(hashName)
### saltthepass.getHashFn(hashName)

Gets the [CryptoJS](http://code.google.com/p/crypto-js/) hash function for a specific hash.

Expand All @@ -150,7 +179,7 @@ __Returns__
Hashing function.

<a name="getHashLength" />
### getHashLength(hashName)
### saltthepass.getHashLength(hashName)

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

Expand All @@ -163,7 +192,7 @@ __Returns__
Number of characters of the hash.

<a name="hash" />
### hash(hashName, phrase)
### saltthepass.hash(hashName, phrase)

Hashes the specified phrase.

Expand All @@ -177,7 +206,7 @@ __Returns__
The Base64 encoded hashed phrase.

<a name="saltthepass" />
### saltthepass(hashName, masterPassword, domainName, domainPhrase)
### saltthepass.saltthepass(hashName, masterPassword, domainName, domainPhrase)

Generates a salted password identical to saltthepass.com.

Expand All @@ -192,13 +221,88 @@ __Returns__

The salted password.

<a name="standardizeDomain" />
### saltthepass.standardizeDomain(url)

Standardizes a domain name for use with <a href="#DomainNameRule">DomainNameRules</a>.

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

__Arguments__

* `url` - URL

__Returns__

Standardized domain for use in <a href="#DomainNameRule">DomainNameRules</a>.

<a name="DomainNameRule" />
### 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. `['-', '!']`)
* `regex` - A regular expression of valid characters (eg. `'A-Z0-9'`) (*The regex is run case-insensitively*)

__Returns__

A DomainNameRule class.

<a name="DomainNameRule.matches" />
### 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.

<a name="DomainNameRule.isValid" />
### 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.

<a name="DomainNameRule.rewrite" />
### 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``:
saltthepass.js tests are provided in the `test/` directory, and can be run via `nodeunit`:

nodeunit test/test.js

Or via ``grunt``:
Or via `grunt`:

grunt test

Expand All @@ -208,4 +312,5 @@ The tests can also be run in a web browser:

## Version History

* v0.0.1 - 2013-05-22: Initial version
* v0.1.0 - 2013-05-22: Initial version
* v0.2.0 - 2013-07-16: `DomainNameRule` and `standardizeDomain()` added.
4 changes: 2 additions & 2 deletions dist/saltthepass.min.js
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 0 additions & 2 deletions dist/saltthepass.withcryptojs.min.js
View file

This file was deleted.

2 changes: 2 additions & 0 deletions dist/saltthepass.withdeps.min.js
View file

Large diffs are not rendered by default.

8 changes: 5 additions & 3 deletions package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
"description": "SaltThePass.com algorithm",
"main": "./src/saltthepass",
"author": "Nic Jansma",
"version": "0.1.0",
"version": "0.2.0",
"repository" : {
"type" : "git",
"url" : "http://github.com/nicjansma/saltthepass.js.git"
Expand All @@ -24,7 +24,9 @@
"grunt": "~0.4.0",
"grunt-contrib-jshint": ">0.0.0",
"grunt-contrib-nodeunit": ">0.0.0",
"grunt-contrib-uglify": ">0.0.0",
"crypto-js": "~3.1.0"
"grunt-contrib-uglify": ">0.0.0"
},
"dependencies": {
"crypto-js": ">= 3.1.2-1"
}
}
Loading

0 comments on commit d0990be

Please sign in to comment.