# secure-random

> Normalize the creation of cryptographically strong random values.

Latest version **1.1.2** (published 2019-05-22) · MIT license · 0 weekly downloads

## Install

```sh
npm install secure-random
pnpm add secure-random
yarn add secure-random
bun add secure-random
```

## Health

**Score 23/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.2 |
| Published | 2019-05-22 |
| First published | 2013-11-07 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/secure-random) |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 7.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 62 |
| Author | JP Richardson |
| Maintainers | jprichardson |
| Keywords | crypto, cryptography, secure, random, rand, generator, number |

## Links

- npm: https://www.npmjs.com/package/secure-random
- Repository: https://github.com/jprichardson/secure-random
- Homepage: https://github.com/jprichardson/secure-random#readme
- Issues: https://github.com/jprichardson/secure-random/issues
- npm.io page: https://npm.io/package/secure-random

## Alternatives

- [random-seedable](https://npm.io/package/random-seedable.md) — 27.9K weekly downloads
- [n2words](https://npm.io/package/n2words.md) — 22.2K weekly downloads
- [@stdlib/math-base-special-factorialln](https://npm.io/package/@stdlib/math-base-special-factorialln.md) — 5.7K weekly downloads
- [@stdlib/math-base-special-abs2](https://npm.io/package/@stdlib/math-base-special-abs2.md) — 1.7K weekly downloads
- [commons-math-interpolation](https://npm.io/package/commons-math-interpolation.md) — 1.4K weekly downloads

## Recent versions

- 1.1.2 (latest) — 2019-05-22
- 1.1.1 — 2014-06-30
- 1.1.0 — 2014-06-30
- 1.0.0 — 2014-06-03
- 0.2.1 — 2014-03-20
- 0.2.0 — 2013-12-17
- 0.1.0 — 2013-12-08
- 0.0.1 — 2013-11-07

## README

secure-random
==============

[![build status](https://secure.travis-ci.org/jprichardson/secure-random.png)](http://travis-ci.org/jprichardson/secure-random)

[![browser support](https://ci.testling.com/jprichardson/secure-random.png)](https://ci.testling.com/jprichardson/secure-random)

A simple JavaScript component to normalize the creation of cryptographically strong random values.


Why?
----

Context switching between the browser and Node.js and creating cryptographically secure random numbers is annoying. This normalizes the behavior. Used by [CryptoCoinJS](http://cryptocoinjs.com) and [BitcoinJS](https://github.com/bitcoinjs/bitcoinjs-lib).



Install
-------

### Node.js/Browserify

    npm install --save secure-random


### Component

    component install jprichardson/secure-random


### Bower

    bower install secure-random


### Script

```html
<script src="/path/to/secure-random.js"></script>
```


Usage
-----

### secureRandom(byteCount, options)

- **byteCount**: is the number of bytes to return. 
- **options**: options to pass. Only valid value at this time `type`. `type` can be
either `Array`, `Uint8Array`, or `Buffer`. `Buffer` is only valid in Node.js or 
[Browserify](https://github.com/substack/node-browserify) environments - it will throw an error otherwise.


return an `Array`:

```js
var bytes = secureRandom(10) //return an Array of 10 bytes
console.log(bytes.length) //10
```

or:

```js
var bytes = secureRandom(10, {type: 'Array'}) //return an Array of 10 bytes
console.log(bytes.length) //10
```

return a `Buffer`:

```js
var bytes = secureRandom(10, {type: 'Buffer'}) //return a Buffer of 10 bytes
console.log(bytes.length) //10
```

return a `Uint8Array`:

```js
var bytes = secureRandom(10, {type: 'Uint8Array'}) //return a Uint8Array of 10 bytes
console.log(bytes.length) //10
```

### randomArray(byteCount)

Sugar for `secureRandom(byteCount, {type: 'Array'})`.

```js
var secureRandom = require('secure-random')
var data = secureRandom.randomArray(10)
```

### randomUint8Array(byteCount)

Sugar for `secureRandom(byteCount, {type: 'Uint8Array'})`.

```js
var secureRandom = require('secure-random')
var data = secureRandom.randomUint8Array(10)
```

### randomBuffer(byteCount)

Sugar for `secureRandom(byteCount, {type: 'Buffer'})`.

```js
var secureRandom = require('secure-random')
var data = secureRandom.randomBuffer(10)
```

Handling Errors
-----

An error will be thrown if a secure random number generator is not available.

```javascript
throw new Error("Your browser does not support window.crypto.")
```

References
----------
* [Node.js crypto.randomBytes()](http://nodejs.org/api/crypto.html#crypto_crypto_randombytes_size_callback)
* [Node.js Buffer](http://nodejs.org/api/buffer.html)
* [window.crypto.getRandomValues()](https://developer.mozilla.org/en-US/docs/Web/API/window.crypto.getRandomValues)
* [JavaScript typed arrays](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Typed_arrays)


License
-------

(MIT License)

Copyright 2013-2014, JP Richardson

---
_Source: https://npm.io/package/secure-random · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._