Added sync version and bumped major version.

ricmoo · Nov 13, 2019 · e55eb39 · e55eb39
1 parent ea5ade0
commit e55eb39
Show file tree

Hide file tree

Showing 6 changed files with 886 additions and 268 deletions.
diff --git a/README.md b/README.md
@@ -1,7 +1,10 @@
 scrypt
 ======
 
-The [scrypt](https://en.wikipedia.org/wiki/Scrypt) password-base key derivation function (pbkdf) is an algorithm designed to be brute-force resistant that converts human readable passwords into fixed length arrays of bytes, which can then be used as a key for symmetric block ciphers, private keys, et cetera.
+The [scrypt](https://en.wikipedia.org/wiki/Scrypt) password-base key derivation
+function (pbkdf) is an algorithm designed to be brute-force resistant that
+converts human readable passwords into fixed length arrays of bytes, which can
+then be used as a key for symmetric block ciphers, private keys, et cetera.
 
 ### Features:
 - **Non-blocking** - Gives other events in the event loop opportunities to run (asynchronous)
@@ -40,12 +43,28 @@ npm install scrypt-js
 API
 ---
 
+**scrypt . scrypt ( password , salt , N , r , p , dkLen [ , progressCallback ] )** *=> Promise<Uint8Array>*
+
+Compute the scrypt PBKDF asynchronously using a Promise. If *progressCallback* is
+provided, it is periodically called with a single parameter, a number between 0 and
+1 (inclusive) indicating the completion progress; it will **always** emit 0 at the
+beginning and 1 at the end, and numbers between may repeat.
+
+**scrypt . syncScrypt ( password , salt , N , r , p , dkLen )** *=> Uint8Array*
+
+Compute the scrypt PBKDF synchronously. Keep in mind this may stall UI and other tasks and the
+asynchronous version is highly preferred.
+
+
+Example
+-------
+
 ```html
 <html>
   <body>
+    <div><span id="progress"></span>% complete...</div>
     <!-- These two libraries are highly recommended for encoding password/salt -->
     <script src="libs/buffer.js" type="text/javascript"></script>
-    <script src="libs/unorm.js" type="text/javascript"></script>
 
     <!-- This shim library greatly improves performance of the scrypt algorithm -->
     <script src="libs/setImmediate.js" type="text/javascript"></script>
@@ -54,24 +73,26 @@ API
     <script type="text/javascript">
 
       // See the section below: "Encoding Notes"
-      var password = new buffer.SlowBuffer("anyPassword".normalize('NFKC'));
-      var salt = new buffer.SlowBuffer("someSalt".normalize('NFKC'));
+      const password = new buffer.SlowBuffer("anyPassword".normalize('NFKC'));
+      const salt = new buffer.SlowBuffer("someSalt".normalize('NFKC'));
 
-      var N = 1024, r = 8, p = 1;
-      var dkLen = 32;
+      const N = 1024, r = 8, p = 1;
+      const dkLen = 32;
 
-      scrypt(password, salt, N, r, p, dkLen, function(error, progress, key) {
-        if (error) {
-          console.log("Error: " + error);
+      function updateInterface(progress) {
+          document.getElementById("progress").textContent = Math.trunc(100 * progress);
+      }
 
-        } else if (key) {
-          console.log("Found: " + key);
+      // Async
+      const keyPromise = scrypt.scrypt(password, salt, N, r, p, dkLen, updateInterface);
 
-        } else {
-          // update UI with progress complete
-          updateInterface(progress);
-        }
+      keyPromise.then(function(key) {
+          console.log("Derived Key (async): ", key);
       });
+
+      // Sync
+      const key = scrypt.syncScrypt(password, salt, N, r, p, dkLen);
+      console.log("Derived Key (sync): ", key);
     </script>
   </body>
 </html>
@@ -131,14 +152,22 @@ true
 
 **Normalizing**
 
-The `normalize()` method of a string can be used to convert a string to a specific form. Without going into too much detail, I generally recommend `NFKC`, however if you wish to dive deeper into this, a nice short summary can be found in Pythons [unicodedata module](https://docs.python.org/2/library/unicodedata.html#unicodedata.normalize)'s documentation.
+The `normalize()` method of a string can be used to convert a string to a
+specific form. Without going into too much detail, I generally recommend
+`NFKC`, however if you wish to dive deeper into this, a nice short summary
+can be found in Pythons [unicodedata module](https://docs.python.org/2/library/unicodedata.html#unicodedata.normalize)'s
+documentation.
 
-For browsers without `normalize()` support, the [npm unorm module](https://www.npmjs.com/package/unorm) can be used to polyfill strings.
+For browsers without `normalize()` support, the [npm unorm module](https://www.npmjs.com/package/unorm)
+can be used to polyfill strings.
 
 
 **Another example of encoding woes**
 
-One quick story I will share is a project which used the `SHA256(encodeURI(password))` as a key, which (ignoring [rainbow table attacks](https://en.wikipedia.org/wiki/Rainbow_table)) had an unfortunate consequence of old web browsers replacing spaces with `+` while on new web browsers, replacing it with a `%20`, causing issues for anyone who used spaces in their password.
+One quick story I will share is a project which used the `SHA256(encodeURI(password))` as
+a key, which (ignoring [rainbow table attacks](https://en.wikipedia.org/wiki/Rainbow_table))
+had an unfortunate consequence of old web browsers replacing spaces with `+` while on new web
+browsers, replacing it with a `%20`, causing issues for anyone who used spaces in their password.
 
 
 ### Suggestions
@@ -161,7 +190,8 @@ npm test
 Special Thanks
 --------------
 
-I would like to thank @dchest for his [scrypt-async](https://github.com/dchest/scrypt-async-js) library and for his assistance providing feedback and optimization suggestions.
+I would like to thank @dchest for his [scrypt-async](https://github.com/dchest/scrypt-async-js)
+library and for his assistance providing feedback and optimization suggestions.
 
 
 License
@@ -183,8 +213,7 @@ References
 Donations
 ---------
 
-Obviously, it's all licensed under the MIT license, so use it as you wish; but if you'd like to buy me a coffee, I won't complain. =)
+Obviously, it's all licensed under the MIT license, so use it as you wish;
+but if you'd like to buy me a coffee, I won't complain. =)
 
-- Bitcoin - `1LsxZkCZpQXyiGsoAnAW9nRRfck3Nvv7QS`
-- Dogecoin - `DF1VMTgyPsew619hwq5tT2RP8BNh2ZpzWA`
-- Testnet3 - `muf7Vak4ZCVgtYZCnGStDXuoEdmZuo2nhA`
+- Ethereum - `ricmoo.eth`