pax_global_header00006660000000000000000000000064123325235770014523gustar00rootroot0000000000000052 comment=7eceae28b60dbbeae4c175021920e193ce3332f3 keygrip-1.0.1/000077500000000000000000000000001233252357700131745ustar00rootroot00000000000000keygrip-1.0.1/.gitignore000066400000000000000000000000421233252357700151600ustar00rootroot00000000000000lib/defaultKeys.js defaultKeys.js keygrip-1.0.1/.travis.yml000066400000000000000000000000531233252357700153030ustar00rootroot00000000000000language: node_js node_js: - 0.6 - 0.8 keygrip-1.0.1/LICENSE.txt000066400000000000000000000020711233252357700150170ustar00rootroot00000000000000Copyright (c) 2012 Jed Schmidt, http://jedschmidt.com/ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.keygrip-1.0.1/README.md000066400000000000000000000070111233252357700144520ustar00rootroot00000000000000Keygrip ======= [![Build Status](https://secure.travis-ci.org/expressjs/keygrip.png)](http://travis-ci.org/expressjs/keygrip) Keygrip is a [node.js](http://nodejs.org/) module for signing and verifying data (such as cookies or URLs) through a rotating credential system, in which new server keys can be added and old ones removed regularly, without invalidating client credentials. ## Install $ npm install keygrip ## API ### keys = new Keygrip([keylist], [hmacAlgorithm], [encoding]) This creates a new Keygrip based on the provided keylist, an array of secret keys used for SHA1 HMAC digests. `keylist` is obligatory. `hmacAlgorithm` defaults to `'sha1'` and `encoding` defaults to `'base64'`. Note that the `new` operator is also optional, so all of the following will work when `Keygrip = require("keygrip")`: ```javascript keys = new Keygrip(["SEKRIT2", "SEKRIT1"]) keys = Keygrip(["SEKRIT2", "SEKRIT1"]) keys = require("keygrip")() keys = Keygrip(["SEKRIT2", "SEKRIT1"], 'sha256', 'hex') keys = Keygrip(["SEKRIT2", "SEKRIT1"], 'sha256') keys = Keygrip(["SEKRIT2", "SEKRIT1"], undefined, 'hex') ``` The keylist is an array of all valid keys for signing, in descending order of freshness; new keys should be `unshift`ed into the array and old keys should be `pop`ped. The tradeoff here is that adding more keys to the keylist allows for more granular freshness for key validation, at the cost of a more expensive worst-case scenario for old or invalid hashes. Keygrip keeps a reference to this array to automatically reflect any changes. This reference is stored using a closure to prevent external access. ### keys.sign(data) This creates a SHA1 HMAC based on the _first_ key in the keylist, and outputs it as a 27-byte url-safe base64 digest (base64 without padding, replacing `+` with `-` and `/` with `_`). ### keys.index(data, digest) This loops through all of the keys currently in the keylist until the digest of the current key matches the given digest, at which point the current index is returned. If no key is matched, `-1` is returned. The idea is that if the index returned is greater than `0`, the data should be re-signed to prevent premature credential invalidation, and enable better performance for subsequent challenges. ### keys.verify(data, digest) This uses `index` to return `true` if the digest matches any existing keys, and `false` otherwise. ## Example ```javascript // ./test.js var assert = require("assert") , Keygrip = require("keygrip") , keylist, keys, hash, index // but we're going to use our list. // (note that the 'new' operator is optional) keylist = ["SEKRIT3", "SEKRIT2", "SEKRIT1"] keys = Keygrip(keylist) // .sign returns the hash for the first key // all hashes are SHA1 HMACs in url-safe base64 hash = keys.sign("bieberschnitzel") assert.ok(/^[\w\-]{27}$/.test(hash)) // .index returns the index of the first matching key index = keys.index("bieberschnitzel", hash) assert.equal(index, 0) // .verify returns the a boolean indicating a matched key matched = keys.verify("bieberschnitzel", hash) assert.ok(matched) index = keys.index("bieberschnitzel", "o_O") assert.equal(index, -1) // rotate a new key in, and an old key out keylist.unshift("SEKRIT4") keylist.pop() // if index > 0, it's time to re-sign index = keys.index("bieberschnitzel", hash) assert.equal(index, 1) hash = keys.sign("bieberschnitzel") ``` ## TODO * Write a library for URL signing Copyright --------- Copyright (c) 2012 Jed Schmidt. See LICENSE.txt for details. Send any questions or comments [here](http://twitter.com/jedschmidt). keygrip-1.0.1/index.js000066400000000000000000000030571233252357700146460ustar00rootroot00000000000000var crypto = require("crypto") function Keygrip(keys, algorithm, encoding) { if (!algorithm) algorithm = "sha1"; if (!encoding) encoding = "base64"; if (!(this instanceof Keygrip)) return new Keygrip(keys, algorithm, encoding) if (!keys || !(0 in keys)) { throw new Error("Keys must be provided.") } function sign(data, key) { return crypto .createHmac(algorithm, key) .update(data).digest(encoding) .replace(/\/|\+|=/g, function(x) { return ({ "/": "_", "+": "-", "=": "" })[x] }) } this.sign = function(data){ return sign(data, keys[0]) } this.verify = function(data, digest) { return this.index(data, digest) > -1 } this.index = function(data, digest) { for (var i = 0, l = keys.length; i < l; i++) { if (constantTimeCompare(digest, sign(data, keys[i]))) return i } return -1 } } Keygrip.sign = Keygrip.verify = Keygrip.index = function() { throw new Error("Usage: require('keygrip')()") } //http://codahale.com/a-lesson-in-timing-attacks/ var constantTimeCompare = function(val1, val2){ if(val1 == null && val2 != null){ return false; } else if(val2 == null && val1 != null){ return false; } else if(val1 == null && val2 == null){ return true; } if(val1.length !== val2.length){ return false; } var matches = 1; for(var i = 0; i < val1.length; i++){ matches &= (val1.charAt(i) === val2.charAt(i) ? 1 : 0); //Don't short circuit } return matches === 1; }; module.exports = Keygrip keygrip-1.0.1/package.json000066400000000000000000000005271233252357700154660ustar00rootroot00000000000000{ "name": "keygrip", "version": "1.0.1", "description": "Key signing and verification for rotated credentials", "scripts": { "test": "node test.js" }, "repository": { "type": "git", "url": "git://github.com/expressjs/keygrip.git" }, "dependencies": {}, "devDependencies": {}, "engines": { "node": "*" } } keygrip-1.0.1/test.js000066400000000000000000000031511233252357700145110ustar00rootroot00000000000000"use strict"; // ./test.js var assert = require("assert") , Keygrip = require("./") , keylist, keys, hash, index // keygrip takes an array of keys. If missing or empty, it will throw. assert.throws(function() { keys = new Keygrip(/* empty list */); }, /must be provided/); // Randomly generated key - don't use this for something real. Don't be that person. keys = new Keygrip(['06ae66fdc6c2faf5a401b70e0bf885cb']); // .sign returns the hash for the first key // all hashes are SHA1 HMACs in url-safe base64 hash = keys.sign("bieberschnitzel") assert.ok(/^[\w\-]{27}$/.test(hash)) // but we're going to use our list. // (note that the 'new' operator is optional) keylist = ["SEKRIT3", "SEKRIT2", "SEKRIT1"] // keylist will be modified in place, so don't reuse keys = Keygrip(keylist) testKeygripInstance(keys); // now pass in a different hmac algorithm and encoding keylist = ["Newest", "AnotherKey", "Oldest"] keys = Keygrip(keylist, "sha256", "hex") testKeygripInstance(keys); function testKeygripInstance(keys) { hash = keys.sign("bieberschnitzel") // .index returns the index of the first matching key index = keys.index("bieberschnitzel", hash) assert.equal(index, 0) // .verify returns the a boolean indicating a matched key var matched = keys.verify("bieberschnitzel", hash) assert.ok(matched) index = keys.index("bieberschnitzel", "o_O") assert.equal(index, -1) // rotate a new key in, and an old key out keylist.unshift("SEKRIT4") keylist.pop() // if index > 0, it's time to re-sign index = keys.index("bieberschnitzel", hash) assert.equal(index, 1) hash = keys.sign("bieberschnitzel") }