[Pkg-javascript-commits] [node-keygrip] 08/68: fleshed out README, added capitalization

[Andrew Kelley]

This is an automated email from the git hooks/post-receive script.

andrewrk-guest pushed a commit to branch master
in repository node-keygrip.

commit 1511dd7031e961c924474053a375b6502ff60c07
Author: Jed Schmidt <tr at nslator.jp>
Date:   Fri Feb 25 17:21:16 2011 +0900

    fleshed out README, added capitalization
---
 README.md      | 39 ++++++++++++++++++++++++++++++++++++---
 lib/keygrip.js | 12 ++++++------
 test.js        |  6 +++---
 3 files changed, 45 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 05ce764..2e837ab 100644
--- a/README.md
+++ b/README.md
@@ -1,16 +1,44 @@
-keygrip
+Keygrip
 =======
 
-keygrip is a [node.js](http://nodejs.org/) module for signing and verifying data, based on a rotating credential system. It can be used to detect tampering for signed URLs or cookies.
+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.
 
 ## Requirements
 
-* [nodejs](http://nodejs.org/), tested with 0.4.1
+* [node.js](http://nodejs.org/), tested with 0.4.1
 
 ## Install
 
     $ npm install keygrip
     
+## API
+
+### keys = new Keygrip([ keylist ])
+
+This creates a new Keygrip based on the provided keylist, an array of secret keys used for SHA1 HMAC digests. Keygrip keeps a reference to this array to automatically reflect any changes. If no list is given, or the list is empty, Keygrip uses the default key created during `npm` installation, and will issue a warning to the console.
+
+Note that the `new` operator is also optional, so all of the following will work when `Keygrip = require( "keygrip" )`:
+
+    keys = new Keygrip
+    keys = new Keygrip([ "SEKRIT2", "SEKRIT1" ])
+    keys = Keygrip()
+    keys = Keygrip([ "SEKRIT2", "SEKRIT1" ])
+    keys = require( "keygrip" )()
+    
+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.
+
+### 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.verify( 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.
+
 ## Example
 
     // ./test.js
@@ -50,6 +78,11 @@ keygrip is a [node.js](http://nodejs.org/) module for signing and verifying data
     index = keys.verify( "bieberschnitzel", hash )
     assert.equal( index, 1 )
     hash = keys.sign( "bieberschnitzel" )
+    
+## TODO
+
+* Rewrite the `cookie` library to use `Keygrip`
+* Write a library for URL signing
 
 Copyright
 ---------
diff --git a/lib/keygrip.js b/lib/keygrip.js
index eec5319..afcb455 100644
--- a/lib/keygrip.js
+++ b/lib/keygrip.js
@@ -1,8 +1,8 @@
 crypto = require( "crypto" )
 defaults = require( "./defaultKeys" )
 
-function KeyGrip( keys ) {
-  if ( !( this instanceof KeyGrip ) ) return new KeyGrip( keys )
+function Keygrip( keys ) {
+  if ( !( this instanceof Keygrip ) ) return new Keygrip( keys )
   
   if ( !keys || !( 0 in keys ) ) {
     console.warn( "No keys specified, using defaults instead." )
@@ -20,17 +20,17 @@ function KeyGrip( keys ) {
 
   this.sign = function( data ){ return sign( data, keys[ 0 ] ) }
 
-  this.verify = function( data, key ) {
+  this.verify = function( data, digest ) {
     for ( var i = 0, l = keys.length; i < l; i++ ) {
-      if ( key === sign( data, keys[ i ] ) ) return i
+      if ( digest === sign( data, keys[ i ] ) ) return i
     }
     
     return -1
   }
 }
 
-KeyGrip.sign = KeyGrip.verify = function() {
+Keygrip.sign = Keygrip.verify = function() {
   throw "Usage: require( 'keygrip' )( <array-of-keys> )"
 }
 
-module.exports = KeyGrip
\ No newline at end of file
+module.exports = Keygrip
\ No newline at end of file
diff --git a/test.js b/test.js
index c9f92f5..b22dc49 100644
--- a/test.js
+++ b/test.js
@@ -1,13 +1,13 @@
 // ./test.js
 var assert = require( "assert" )
-  , keygrip = require( "keygrip" )
+  , Keygrip = require( "keygrip" )
   , keylist, keys, hash, index
 
 // keygrip takes an array of keys, but if none exist,
 // it uses the defaults created during npm installation.
 // (but it'll will warn you)
 console.log( "Ignore this message:" )
-keys = keygrip( /* empty list */ )
+keys = new Keygrip( /* empty list */ )
 
 // .sign returns the hash for the first key
 // all hashes are SHA1 HMACs in url-safe base64
@@ -17,7 +17,7 @@ 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" ]
-keys = keygrip( keylist )
+keys = Keygrip( keylist )
 hash = keys.sign( "bieberschnitzel" )
 
 // .verify returns the index of the first matching key

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-javascript/node-keygrip.git