scrypt - npm Package Compare versions

Comparing version 1.1.0 to 1.2.0

package.json

 {
     "name": "scrypt",
     "description": "The scrypt crypto library for NodeJS",
-    "version": "1.1.0",
+    "version": "1.2.0",
     "keywords": [
@@ -6,0 +6,0 @@ "scrypt",

Readme.md

 #Scrypt For NodeJS
 node-scrypt is a native node C++ wrapper for Colin Percival's scrypt [key derivation](http://en.wikipedia.org/wiki/Key_derivation_function) utility. It is fully asynchronous (in fact, there is no synchronous mode due to the time input of scrypt which would block the event loop).
 
-node-scrypt wraps scrypt's atomic key derivation operations. In other words, this library does not implement an authentication scheme, it merely implements the atomics that are necessary for it.
+node-scrypt wraps scrypt's atomic key derivation operations and provides implementation for a password hash and password verification scheme.
 
@@ -16,3 +16,3 @@ ##What Is Scrypt?
 ##Why Use Scrypt?
-It is probably the most advanced means of performing authentication out there. This is quote taken from a comment in hacker news:
+It is probably the most advanced means of performing authentication that is available. This is quote taken from a comment in hacker news:
 
@@ -32,2 +32,12 @@ >Passwords hashed with scrypt with sufficiently-high strength values (there are 3 tweakable input numbers) are fundamentally impervious to being cracked. I use the word "fundamental" in the literal sense, here; even if you had the resources of a large country, you would not be able to design any hardware (whether it be GPU hardware, custom-designed hardware, or otherwise) which could crack these hashes. Ever. (For sufficiently-small definitions of "ever". At the very least "within your lifetime"; probably far longer.)
 
+###The Three Tweakable Inputs
+**Note**: This is a very important section to understand. The three tweakable inputs mentioned above are actually just *human understandable* inputs into a translation function that produces the inputs required for the internal scrypt cryptographic function. These inputs (as defined in the [scrypt paper](http://www.tarsnap.com/scrypt/scrypt.pdf)) are as follows:
+
+1. **N** - general work factor, iteration count.
+2. **r** - blocksize in use for underlying hash; fine-tunes the relative memory-cost.
+3. **p** - parallelization factor; fine-tunes the relative cpu-cost.
+
+Values for *maxtime*, *maxmemfrac* and *maxmem* are translated into the above values, which are then fed to the scrypt function. The translation function also takes into account the CPU and Memory capabilities of a machine. Therefore values of *N*, *r* and *p* may differ for different machines that have different specs.
+
+## Pros And Cons
 Here are some pros and cons for using it:
@@ -37,2 +47,3 @@
 
+* The scrypt algorithm has been published by [IETF](http://en.wikipedia.org/wiki/IETF) as an [Internet Draft](http://en.wikipedia.org/wiki/Internet_Draft) and is thus on track to becoming a standard. See [here](https://tools.ietf.org/html/draft-josefsson-scrypt-kdf-00) for the draft.
 * It is being actively used in production at [Tarsnap](http://www.tarsnap.com/).
@@ -56,3 +67,9 @@ * It is much more secure than bcrypt.
 #Dependencies
+There are no Node module dependencies, but the scrypt C library requires the following:
 
+* Openssl Library - this is linked with `lcrypto` in the makefile (binding.gyp).
+* Realtime Extensions Library - linked with `lrt`, used for translation of three tweakable inputs into scrypt inputs (see above for details).
+
+The above libraries are standard on Linux.
+
 #Installation Instructions
@@ -72,12 +89,55 @@ As of now (Dec 2012), this library has been tested and works on Linux (Ubuntu to be exact).
 #Usage
-I will write an example application that uses scrypt for authentication in a few days time. What follows here is using scrypt to encrypt and decrypt data. Note that for the case of pure encryption and decryption, scrypt is not a good candidate (rather use [AES]()). Remember that scrypt is designed to be a key derivation function, and therefore being *slow* is an advantage.
+##Authentication
+For interactive authentication, set `maxtime` to `0.1` - 100 milliseconds. 
+   
+###To create a password hash
+ 
+    var scrypt = require("scrypt");
+    var hash;
+    var password = "This is a password";
+    var maxtime = 0.1;
 
+    scrypt.passwordHash(password, maxtime, function(err, pwdhash) {
+        if (!err)
+            hash = pwdhash; //This should now be stored in the database
+    });
+
+Note `maxmem` and `maxmemfrac` can also be passed to hash function. If they are not passed, then `maxmem` defaults to `0` and `maxmemfrac` defaults to `0.5`. If these values are to be passed, then they must be passed after `maxtime`  and before the callback function like so:
+    
     var scrypt = require("scrypt");
+    var hash;
+    var password = "This is a password";
+    var maxtime = 0.1;
+    var maxmem = 0, maxmemfrac = 0.5;
+
+    scrypt.passwordHash(password, maxtime, maxmem, maxmemfrac, function(err, pwdhash) {
+        if (!err)
+            hash = pwdhash; //This should now be stored in the database
+    });
+
+###To verify a password hash
+
+    var scrypt = require("scrypt");
+    var password = "This is a password";
+    var hash; //This should be obtained from the database
+
+    scrypt.verifyHash(hash, password, function(err, result) {
+        if (!err)
+            return result; //Will be True
+        
+        return False;    
+    });
+
+
+##Encryption and Decryption
+I suspect scrypt will be used mainly as a key derivation function, but I have also ported the scrypt encryption and decryption functions. Performing scrypt cryptography is done if you value security over speed. Scrypt is more secure than a vanilla block cipher (e.g. AES) but it is much slower.
+
+    var scrypt = require("scrypt");
     var message = "Hello World";
     var password = "Pass";
-    var max_time = 1.0;
+    var maxtime = 1.0;
 
-    scrypt.encrypt(message, password, max_time, function(err, cipher) {
+    scrypt.encrypt(message, password, maxtime, function(err, cipher) {
         console.log(cipher);
-        scrypt.decrypt(cipher, password, max_time, function(err, msg) {
+        scrypt.decrypt(cipher, password, maxtime, function(err, msg) {
             console.log(msg);
@@ -87,3 +147,3 @@ });
 
-Note that `maxmem` and `maxmemfrac` can also be passed to the functions. If they are not passed, then `maxmem` defaults to `0` and `maxmemfrac` defaults to `0.5`. If these values are to be passed, then they must be passed after `max_time`  and before the callback function like so:
+Note that `maxmem` and `maxmemfrac` can also be passed to the functions. If they are not passed, then `maxmem` defaults to `0` and `maxmemfrac` defaults to `0.5`. If these values are to be passed, then they must be passed after `maxtime`  and before the callback function like so:
     
@@ -93,9 +153,9 @@ var scrypt = require("scrypt");
     var password = "Pass";
-    var max_time = 1.0;
+    var maxtime = 1.0;
     var maxmem = 1; //Defaults to 0 if not set
     var maxmemfrac = 1.5; //Defaults to 0.5 if not set
 
-    scrypt.encrypt(message, password, max_time, maxmem, maxmemfrac, function(err, cipher) {
+    scrypt.encrypt(message, password, maxtime, maxmem, maxmemfrac, function(err, cipher) {
         console.log(cipher);
-        scrypt.decrypt(cipher, password, max_time, maxmem, maxmemfrac, function(err, msg) {
+        scrypt.decrypt(cipher, password, maxtime, maxmem, maxmemfrac, function(err, msg) {
             console.log(msg);
@@ -105,6 +165,45 @@ });
 
-#Still To Do
+#Api
 
-1. Finish writing testing scripts.
-2. Find collaborators to help port it to windows.
-3. Make an example password authentication script.
+##Authentication
+
+* `passwordHash(password, maxtime, maxmem, maxmemfrac, callback_function)`
+    * `password` - [REQUIRED] - a password string.
+    * `maxtime` - [REQUIRED] - a decimal (double) representing the maxtime in seconds for running scrypt. Use 0.1 (100 milliseconds) for interactive logins.
+    * `maxmem` - [OPTIONAL] - instructs scrypt to use the specified number of bytes of RAM (default 0).
+    * `maxmemfrac` - [OPTIONAL] - instructs scrypt to use the specified fracion of RAM (defaults 0.5).
+    * `callback_function` - [REQUIRED] - a callback function that will handle processing when result is ready.
+* `verifyHash(hash, password, callback_function)` 
+    * `hash` - [REQUIRED] - the password created with the above `passwordHash` function.
+    * `password` - [REQUIRED] - a password string.
+    * `callback_function` - [REQUIRED] - a callback function that will handle processing when result is ready.
+           
+##Encryption/Decryption
+
+* `encrypt(message, password, maxtime, maxmem, maxmemfrac, callback_function)`
+    * `message` - [REQUIRED] - the message data to be encrypted.
+    * `password` - [REQUIRED] - a password string.
+    * `maxtime` - [REQUIRED] - a decimal (double) representing the maxtime in seconds for running scrypt.
+    * `maxmem` - [OPTIONAL] - instructs scrypt to use the specified number of bytes of RAM (default 0).
+    * `maxmemfrac` - [OPTIONAL] - instructs scrypt to use the specified fracion of RAM (defaults 0.5).
+    * `callback_function` - [REQUIRED] - a callback function that will handle processing when result is ready.
+* `decrypt(cipher, password, maxtime, maxmem, maxmemfrac, callback_function)`
+    * `cipher` - [REQUIRED] - the cipher to be decrypted.
+    * `password` - [REQUIRED] - a password string.
+    * `maxtime` - [REQUIRED] - a decimal (double) representing the maxtime in seconds for running scrypt.
+    * `maxmem` - [OPTIONAL] - instructs scrypt to use the specified number of bytes of RAM (default 0).
+    * `maxmemfrac` - [OPTIONAL] - instructs scrypt to use the specified fracion of RAM (defaults 0.5).
+    * `callback_function` - [REQUIRED] - a callback function that will handle processing when result is ready.
+
+#Credits
+The scrypt library is Colin Percival's [scrypt](http://www.tarsnap.com/scrypt.html) project. This includes the encryption/decryption functions which are basically just wrappers into this library.
+
+The password hash and verify functions are also very heavily influenced by the scrypt source code, with most functionality being copied from various placed within scrypt.
+
+#A Call For Help
+
+I need help with the following please:
+
+1. Porting this to Windows and Mac.
+2. Scrutiny by cryptographers.
+3. Testing against bcrypt (from the scrypt paper, Colin Percival says it is much more secure, and provides proof - but I would like a back up of that fact).

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

151413

increased by6.04%

Number of lines in readme file

202

increased by96.12%

No dependency changes