drng.js

The hardware-random number generator library using libdrng by Intel.

The recent Intel CPU has a TRNG instructions called RDRAND/RDSEED. You can generate a good-random numbers without any external, expensive hardware. This NPM module enables you to use those instructions from Node.js, applicable for simulation, analysis, games, or anything you want.

API

// node.js
const drng = require('drng');
 
// typescript
import * as drng from 'drng';

Basic API

• drng.Random(): number - returns [0, 1) number; alternative for Math.random().
• drng.GetInteger(): number - returns [0, 1] integer; ramdom binary bits.
• drng.GetInteger(max: number): number - returns [0, max] integer.
• drng.GetInteger(min: number, max: number): number - returns [min, max] integer.

The implementation of these methods will be selected automatically based on your hardware. For example, your processor supports RDSEED instruction and it is 64bit mode, drng.Random() will be an alias of drng.RdSeed.Random64().

Instruction specified API

• The methods drng.RdRand.* uses RDRAND instruction.
• The methods drng.RdSeed.* uses RDSEED instruction.

For each set contains below:

• IsAvailable: boolean - if your hardware is supported a instruction, set true.
• Rand16(): number - returns uint16_t width integer.
• Rand16(retry: number): number - returns uint16_t width integer, set the maximum number of retry generation.
• Rand32(): number - returns uint32_t width integer.
• Rand32(retry: number): number - returns uint32_t width integer, set the maximum number of retry generation.
• Rand32Array(length: number): Uint32Array - returns Uint32Array filled by a random numbers.
• Rand32Array(length: number, skip: number): Uint32Array - returns Uint32Array filled by a random numbers, set start index.
• Rand32Array(length: number, skip: number, max_retries: number): Uint32Array - returns Uint32Array filled by a random numbers, set start index and the maximum number of retry generation.
• RandBytes(length: number): Uint8Array - returns Uint8Array filled by a random numbers.
• RandBytes(length: number, skip: number): Uint8Array - returns Uint8Array filled by a random numbers, set start index.
• RandBytes(length: number, skip: number, max_retries: number): Uint8Array - returns Uint8Array filled by a random numbers, set start index and the maximum number of retry generation.
• Random32(): number - returns [0, 1) float ramdom number, uses uint32_t value internally.
• Random64(): number - returns [0, 1) float ramdom number, uses uint64_t value internally.
• GetInteger(): number - returns [0, 1] integer; ramdom binary bits.
• GetInteger(max: number): number - returns [0, max] integer.
• GetInteger(min: number, max: number): number - returns [min, max] integer.

For more detail, see lib/index.d.ts.

Tested platforms

• Windows10 Pro x64, node-gyp v3.6.1, node v7.10.0

Notes

• This is my first native-addon, so if you find some bug/issue on my code, please report it or create a fix pull-request. Thanks!!
• Not implemented APIs; V8 never supported 64bit integer, there's no way to implement with a native value types.
  • rd{rand,seed}_64
  • rd{rand,seed}_get_n_64

Lisence

For libdrng, see LICENSE.txt. The module itself is under the MIT License.

Changelog

• v0.0.12: Set default retry value for each method
• v0.0.11: Support TypeScript
• v0.0.10:
• v0.0.9:
• v0.0.8:
• v0.0.7: Classify APIs
• v0.0.6: Add helper functions Random*/GetInteger*, switch export API by hardware condition
• v0.0.5: Add Rd{Rand,Seed}Bytes, use TypedArray for the result value for *32Array/*Bytes
• v0.0.4: Support linux
• v0.0.3:
• v0.0.2: Add Rd{Rand,Seed}32Array, fix IsSupportedRd{Rand,Seed} result
• v0.0.1: Initial reelase