[Pkg-javascript-commits] [node-keygrip] 60/68: .index -> .indexOf, docs++
Andrew Kelley
andrewrk-guest at moszumanska.debian.org
Fri Jun 27 22:13:29 UTC 2014
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 07a9e3abc23f9e93b347589df00940ec54d39273
Author: Jonathan Ong <jonathanrichardong at gmail.com>
Date: Tue Jun 3 23:03:31 2014 -0700
.index -> .indexOf, docs++
---
History.md | 2 ++
LICENSE.txt | 12 +++++----
README.md | 81 +++++++++++++++++++------------------------------------------
index.js | 8 +++---
test.js | 6 ++---
5 files changed, 42 insertions(+), 67 deletions(-)
diff --git a/History.md b/History.md
index 945cf48..dfab6d9 100644
--- a/History.md
+++ b/History.md
@@ -4,5 +4,7 @@
* remove the `[algorithm]` option, use `.hash=` instead
* remove the `[encoding]` option, `Buffer`s are now always returned
+ * no longer returns any URL-safe hashes
* add `.encrypt()`, `.decrypt()`, and `.cipher=`
* default hash algorithm is now `sha256`
+ * changed `.index()` to `.indexOf()`
diff --git a/LICENSE.txt b/LICENSE.txt
index 161dfc3..02114d7 100644
--- a/LICENSE.txt
+++ b/LICENSE.txt
@@ -1,5 +1,7 @@
-Copyright (c) 2012 Jed Schmidt, http://jedschmidt.com/
-
+
+The MIT License (MIT)
+Copyright (c) 2014 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
@@ -7,14 +9,14 @@ 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.
\ No newline at end of file
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/README.md b/README.md
index 4a32c1c..a9d9e6f 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,7 @@ Keygrip
[](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.
+Keygrip is a [node.js](http://nodejs.org/) module for signing and verifying data through a rotating credential system, in which new server keys can be added and old ones removed regularly, without invalidating client credentials.
## Install
@@ -11,19 +11,13 @@ Keygrip is a [node.js](http://nodejs.org/) module for signing and verifying data
## API
-### keys = new Keygrip([keylist], [hmacAlgorithm], [encoding])
+### keys = Keygrip(keylist)
-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")`:
+This creates a new Keygrip based on the provided `keylist`.
```javascript
-keys = new Keygrip(["SEKRIT2", "SEKRIT1"])
+var Keygrip = require('keygrip')
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.
@@ -32,65 +26,40 @@ The tradeoff here is that adding more keys to the keylist allows for more granul
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)
+When using `Keygrip` to encrypt and decrypt data, each `key`'s length is important.
+
+### var buf = 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 `_`).
+This creates a HMAC based on the _first_ key in the keylist, and outputs it as a buffer.
-### keys.index(data, digest)
+Uses `.hash=` as the underlying algorithm.
+
+### var index = keys.indexOf(data)
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)
+### var bool = keys.verify(data)
This uses `index` to return `true` if the digest matches any existing keys, and `false` otherwise.
-## Example
+### var buf = keys.encrypt(message, [iv])
-```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")
-```
+Creates an encrypted message as a buffer based on the _first_ key in the keylist and optionally based on an initialization vector.
+
+Uses `.cipher=` as the underlying algorithm.
+Note that `iv` length is important.
+
+### var buf = keys.decrypt(message, [iv])
-## TODO
+Decrypts a message, optionally with an initialization vector.
+Returns a buffer.
-* Write a library for URL signing
+### keys.hash=
-Copyright
----------
+Set the hashing algorithm for signing, defaulting to `sha256`.
-Copyright (c) 2012 Jed Schmidt. See LICENSE.txt for details.
+### .cipher=
-Send any questions or comments [here](http://twitter.com/jedschmidt).
+Set the algorithm used for message encryption, defaulting to `aes-256-cbc`.
diff --git a/index.js b/index.js
index 100f59e..c5947c4 100644
--- a/index.js
+++ b/index.js
@@ -99,10 +99,11 @@ Keygrip.prototype.sign = function Keygrip$_sign(data, key) {
}
Keygrip.prototype.verify = function Keygrip$_verify(data, digest) {
- return this.index(data, digest) > -1
+ return this.indexOf(data, digest) > -1
}
-Keygrip.prototype.index = function Keygrip$_index(data, digest) {
+Keygrip.prototype.index =
+Keygrip.prototype.indexOf = function Keygrip$_index(data, digest) {
var keys = this.keys
for (var i = 0, l = keys.length; i < l; i++) {
if (constantTimeCompare(digest, this.sign(data, keys[i]))) return i
@@ -115,6 +116,7 @@ Keygrip.encrypt =
Keygrip.decrypt =
Keygrip.sign =
Keygrip.verify =
-Keygrip.index = function() {
+Keygrip.index =
+Keygrip.indexOf = function() {
throw new Error("Usage: require('keygrip')(<array-of-keys>)")
}
diff --git a/test.js b/test.js
index 768fb0d..d4e9608 100644
--- a/test.js
+++ b/test.js
@@ -119,14 +119,14 @@ function testKeygripInstance(keys) {
hash = keys.sign("bieberschnitzel")
// .index returns the index of the first matching key
- index = keys.index("bieberschnitzel", hash)
+ index = keys.indexOf("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")
+ index = keys.indexOf("bieberschnitzel", "o_O")
assert.equal(index, -1)
// rotate a new key in, and an old key out
@@ -134,7 +134,7 @@ function testKeygripInstance(keys) {
keylist.pop()
// if index > 0, it's time to re-sign
- index = keys.index("bieberschnitzel", hash)
+ index = keys.indexOf("bieberschnitzel", hash)
assert.equal(index, 1)
hash = keys.sign("bieberschnitzel")
}
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-javascript/node-keygrip.git
More information about the Pkg-javascript-commits
mailing list