sha3 - npm Package Compare versions

Comparing version 1.2.2 to 2.0.0

package.json

 {
   "name": "sha3",
-  "version": "1.2.2",
-  "description": "A Node.js C++ extension for SHA-3 (Keccak)",
+  "version": "2.0.0",
+  "description": "The Keccak family of hashing algorithms.",
+  "main": "index.js",
   "keywords": [
@@ -9,2 +10,3 @@ "sha",
     "sha-3",
+    "keccak",
     "hash",
@@ -17,22 +19,30 @@ "hashing"
   },
-  "main": "build/Release/sha3",
-  "scripts": {
-    "install": "node-gyp rebuild",
-    "test": "python test/generate_tests.py > test/test_vectors.js && node test/test_vectors.js && mocha test/unit_tests.js"
+  "author": {
+    "name": "Devin Canterberry",
+    "email": "[e-mail]"
   },
-  "gypfile": true,
+  "license": "MIT",
   "directories": {
     "test": "test"
   },
-  "author": {
-    "name": "Hongli Lai (Phusion)",
-    "email": "[e-mail]"
+  "scripts": {
+    "build": "babel --only '**/index.js' --no-comments --compact true --minified --source-maps false --out-dir lib src; cp -vfR README.md LICENSE package.json yarn.lock lib/",
+    "coverage": "nyc report",
+    "lint": "eslint src test",
+    "test": "nyc --silent --check-coverage --lines 100 --per-file mocha --require @babel/register --recursive test"
   },
-  "license": "MIT",
+  "devDependencies": {
+    "@babel/cli": "7.1.5",
+    "@babel/core": "7.1.5",
+    "@babel/preset-env": "7.1.5",
+    "@babel/register": "7.0.0",
+    "babel-eslint": "10.0.1",
+    "eslint": "5.9.0",
+    "eslint-plugin-ante": "1.0.1",
+    "mocha": "5.2.0",
+    "nyc": "13.1.0"
+  },
   "dependencies": {
-    "nan": "2.10.0"
-  },
-  "devDependencies": {
-    "mocha": "5.1.1"
+    "buffer": "5.2.1"
   }
 }

README.md

@@ -1,2 +0,2 @@
-# A Node.js C++ extension for SHA-3 (Keccak)
+# SHA-3 for JavaScript
 
@@ -10,4 +10,8 @@ [![Travis CI][3]][4]
 
-This Node.js extension implements the SHA-3 ([Keccak][1]) cryptographic hashing algorithm. It is based on the reference C implementation, version 3.2. The exposed interface is almost identical to that of the `crypto` standard library.
+A pure JavaScript implementation of the Keccak family of cryptographic hashing algorithms, most notably including Keccak and SHA3.
 
+> :bulb: **Legacy Note:** In previous versions of this library, the `SHA3Hash` object provided a *Keccak* hash, **not** what we
+> currently know as a SHA-3 hash. For backwards-compatibility, this object is still exported. However, users are encouraged to
+> switch to using the `SHA3` or `Keccak` objects instead, which provide the SHA-3 and Keccak hashing algorithms, respectively.
+
 [![Phusion][13]][2]
@@ -31,54 +35,166 @@
 
-Keccak supports 5 hash lengths: 224-bit, 256-bit, 384-bit, 512-bit and variable length. Variable length is not supported by this Node.js extension. Unless the user specifies otherwise, this Node.js extension assumes 512-bit.
+You can use this library from Node.js, from web browsers, and/or using ES6 imports.
 
+### Node.js (CommonJS style)
+
 ```javascript
-const SHA3 = require('sha3');
+// Standard FIPS 202 SHA-3 implementation
+const { SHA3 } = require('sha3');
 
-// Generate 512-bit digest.
-let d = new SHA3.SHA3Hash();
-d.update('foo');
-d.digest('hex');
-// => "1597842a..."
+// The Keccak hash function is also available
+const { Keccak } = require('sha3');
+```
 
-// Generate 224-bit digest.
-d = new SHA3.SHA3Hash(224);
-d.update('foo');
-d.digest('hex');
-// => "daa94da7..."
+### ES6
+
+```javascript
+// Standard FIPS 202 SHA-3 implementation
+import { SHA3 } from 'sha3';
+
+// The Keccak hash function is also available
+import { Keccak } from 'sha3';
 ```
 
-### new SHA3Hash([hashlen])
+### What's in the box
 
-This is the hash object. `hashlen` is 512 by default.
+FIPS-compatible interfaces for the following algorithms:
 
-### hash.update(data, [input_encoding])
+ * `SHA3`: The SHA3 algorithm.
+ * `Keccak`: The Keccak algorithm.
 
-Updates the hash content with the given data, the encoding of which is given in `input_encoding` and can be `'utf8'`, `'ascii'` or `'binary'`. Defaults to `'binary'`. This can be called many times with new data as it is streamed.
+> :bulb: **Legacy Note:** Savvy inspectors may notice that `SHA3Hash` is also provided. Prior to v2.0.0,
+> this library only implemented an early version of the SHA3 algorithm. Since then, SHA3 has diverged from
+> Keccak and is using a different padding scheme, but for compatibility, this alias is sticking around
+> for a bit longer.
 
-### hash.digest([encoding])
+### Examples
 
-Calculates the digest of all of the passed data to be hashed. The encoding can be `'hex'` or `'binary'`. Defaults to `'binary'`.
+#### Generating a SHA3-512 hash
 
-Note: unlike `crypto.Hash`, a `SHA3Hash` object _can_ still be used after the `digest()` method been called.
+```javascript
+import { SHA3 } from 'sha3';
 
-## Running the test suite
+const hash = new SHA3(512);
 
-Run the test suite as follows:
+hash.update('foo');
+hash.digest('hex');
+```
 
-```bash
-$ npm test
+#### Generating a Keccak-256 hash
+
+```javascript
+import { Keccak } from 'sha3';
+
+const hash = new Keccak(256);
+
+hash.update('foo');
+hash.digest('hex');
 ```
 
-The test suite is automatically generated from Keccak's reference test suite.
-It requires that you have Python 2.7 installed and available via the
-`python` executable.
+### API Reference
 
-## Warning
+All hash implementations provided by this library conform to the following API specification.
 
-Do not use SHA-3 for hashing passwords. Do not even use SHA-3 + salt for hashing passwords. Use a [slow hash][14] instead.
+#### `#constructor([size=512])`
 
-## See also
+The constructor for each hash (e.g: `Keccak`, `SHA3`), expects the following parameters:
 
-[Digest::SHA3 for Ruby](https://github.com/phusion/digest-sha3-ruby)
+ * `size` (Number): Optional. The size of the hash to create, in bits. If provided, this must be one of `224`, `256`, `384`, or `512`. Defaults to `512`.
 
+##### Example
+
+```javascript
+// Construct a new Keccak hash of size 256
+const hash = new Keccak(256);
+```
+
+#### `#update(data, [encoding='utf8'])`
+
+Updates the hash content with the given data. Returns the hash object itself.
+
+ * `data` (Buffer|string): **Required.** The data to read into the hash.
+ * `encoding` (string): **Optional.** The encoding of the given `data`, if of type `string`. Defaults to `'utf8'`.
+
+> :bulb: See [Buffers and Character Encodings][15] for a list of allowed encodings.
+
+##### Example
+
+```javascript
+const hash = new Keccak(256);
+
+hash.update('hello');
+
+hash.update('we can also chain these').update('together');
+```
+
+#### `#digest([encoding='binary'])`
+
+Digests the hash and returns the result. After calling this function, the hash **may** continue to receive input.
+
+ * `encoding` (string): **Optional.** The encoding to use for the returned digest. Defaults to `'binary'`.
+
+If an `encoding` is provided and is a value other than `'binary'`, then this function returns a `string`.
+Otherwise, it returns a `Buffer`.
+
+> :bulb: See [Buffers and Character Encodings][15] for a list of allowed encodings.
+
+##### Example
+
+```javascript
+const hash = new Keccak(256);
+
+hash.update('hello');
+
+hash.digest('hex');
+// => hash of 'hello' as a hex-encoded string
+
+hash.update('we can keep reading data even after digesting');
+
+hash.digest();
+// => hash of everything so far as a Buffer object
+```
+
+#### `#reset()`
+
+Resets a hash to its initial state.
+
+ * All input buffers are cleared from memory.
+ * The hash object can safely be reused to compute another hash.
+
+##### Example
+
+```javascript
+const hash = new Keccak(256);
+
+hash.update('hello');
+hash.digest();
+// => hash of 'hello'
+
+hash.reset();
+
+hash.update('world');
+hash.digest();
+// => hash of 'world'
+```
+
+## Testing
+
+Run `yarn test` for the full test suite.
+
+## Disclaimer
+
+Cryptographic hashes provide **integrity**, but do not provide **authenticity** or **confidentiality**.
+Hash functions are one part of the cryptographic ecosystem, alongside other primitives like ciphers and
+MACs. If considering this library for the purpose of protecting passwords, you may actually be looking
+for a [key derivation function][16], which can provide much better security guarantees for this use case.
+
+## Special Thanks
+
+The following resources were invaluable to this implementation and deserve special thanks
+for work well done:
+
+ * [Keccak pseudocode][17]: The Keccak team's excellent pseudo-code and technical descriptions.
+
+ * [mjosaarinen/tiny_sha3][18]: Markku-Juhani O. Saarinen's compact, legible, and hackable implementation.
+
 [1]: https://keccak.team/keccak.html
@@ -98,1 +214,5 @@ [2]: https://www.phusion.nl/
 [14]: http://codahale.com/how-to-safely-store-a-password/
+[15]: https://nodejs.org/api/buffer.html#buffer_buffers_and_character_encodings
+[16]: https://www.npmjs.com/package/pbkdf2
+[17]: https://keccak.team/keccak_specs_summary.html
+[18]: https://github.com/mjosaarinen/tiny_sha3

New alerts

Empty package

Supply chain risk

Package does not contain any code. It may be removed, is name squatting, or the result of a faulty package publish.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Minified code

Quality

This package contains minified code. This may be harmless in some cases where minified code is included in packaged libraries, however packages on npm should not minify code.

Found 3 instances in 1 package

Fixed alerts

Native code

Supply chain risk

Contains native code which could be a vector to obscure malicious code, and generally decrease the likelihood of reproducible or reliable installs.

Found 1 instance in 1 package

Improved metrics

Number of package files

31

increased by24%

Number of lines in readme file

216

increased by125%

Worsened metrics

Total package byte prevSize

25797

decreased by-99.53%

Dev dependency count

9

increased by800%

Lines of code

0

decreased by-100%

Number of low quality alerts

15

increased by1400%

Number of medium supply chain risk alerts

2

increased by100%

Dependency changes

• + Addedbuffer@5.2.1

• + Addedbase64-js@1.5.1(transitive)

• + Addedbuffer@5.2.1(transitive)

• + Addedieee754@1.2.1(transitive)

• - Removednan@2.10.0

• - Removednan@2.10.0(transitive)