radiofreejohn / cryptohat

Cryptographically strong, hat-compatible, pseudo-random nubmer generator

Hat-Compatible CSPRNG

This is a node.js package that implements hat's main API, but uses a cryptographically secure pseudo-random number generator to generate the random identifiers. This is especially beneficial when using older versions of [V8](https://en.wikipedia.org/wiki/V8_(JavaScript_engine) that exhibit this bug.

In our use cases, cryptohat takes up to 3x more time to produce a random identifier than hat. cryptohat also exposes an alternative API that produces random numbers up to 2x faster than hat, while still using a CSPRNG.

Prerequisites

This package is tested on node.js 0.10 and above. Browser support is planned for a future version.

Installation

Install using npm.

npm install cryptohat@0.1.x --save

Usage

cryptohat implements the hat(bits, base) API. As long as you don't need the hat.rack method, cryptohat can be used as a drop-in replacement.

var hat = require('cryptohat');

hat();  // '39a00e331acce7516a8ea69b85e191f0'
hat(53, 10);  // '6738095220277140'

Pass in zero (0) for the base argument to get a number. This is significantly faster than obtaining a string and converting it into a number. Keep in mind that JavaScript numbers can accurately represent integers of at most 53 bits.

var cryptohat = require('cryptohat');

cryptohat(53, 0);  // 6738095220277140
cryptohat(32, 0);  // 3840742823
cryptohat(63, 0);  // RangeError: JavaScript numbers can accurately represent at most 53 bits

For maximum throughput, use the cryptohat.generator API. It takes exactly the same arguments as the hat API, but it returns a generator function. Calling the function yields random numbers or identifiers.

var rng1 = cryptohat.generator(53, 0);
rng1();  // 4438236126178078
rng1();  // 187896805323588

var rng2 = cryptohat.generator(32, 10);
rng2();  // '0053668130'
rng2();  // '1939036909'

Development

After cloning the repository, install the dependencies.

npm install

Make sure the tests pass after making a change.

SKIP_BENCHMARKS=1 npm test

When adding new functionality, make sure it has good test coverage and that it does not regress the code's performance.

SKIP_BENCHMARKS=1 npm run cov
npm test

When adding new functionality, also make sure that the documentation looks reasonable.

npm run doc

If you submit a pull request, Travis CI will run the test suite against your code on the node versions that we support. Please fix any errors that it reports.

Copyright

Copyright (c) 2016 Heap Inc., released under the MIT license.