/niceware

Generate or convert random bytes into passphrases in Node and the browser.

Primary LanguageJavaScriptMIT LicenseMIT

niceware

Build Status

A JS library for generating random-yet-memorable passwords, either server-side in Node or in the browser. Each word provides 16 bits of entropy, so a useful password requires at least 3 words.

Because the wordlist is of exactly size 2^16, Niceware is also useful for convert cryptographic keys and other sequences of random bytes into human-readable phrases. With Niceware, a 128-bit key is equivalent to an 8-word phrase.

Demo: https://diracdeltas.github.io/niceware/

WARNING: The wordlist has not been rigorously checked for offensive words. Use at your own risk.

Sample use cases

  • Niceware can be used to generate secure, semi-memorable, easy-to-type passphrases. A random 3-5 word phrase in Niceware is equivalent to a strong password for authentication to most online services. For instance, +8svofk0Y1o= and bacca cavort west volley are equally strong (64 bits of randomness).
  • Niceware can be used to display cryptographic key material in a way that users can easily backup or copy between devices. For instance, the 128-bit random seed used to generate a 256-bit ECC key (~equivalent to a 3072-bit RSA key) is only 8 Niceware words. With this 8-word phrase, you can reconstruct the entire public/private key pair.

Usage in Node

To install:

npm install niceware

To generate an 8-byte passphrase:

const niceware = require('niceware')

// The number of bytes must be even
const passphrase = niceware.generatePassphrase(8)

// Result: [ 'deathtrap', 'stegosaur', 'nilled', 'nonscheduled' ]

Usage in browser

To use Niceware in modern browsers, include browser/niceware.js in a script tag. Niceware is then available in the window.niceware object.

<script src='niceware.js'></script>
<script>
  const passphrase = window.niceware.generatePassphrase(8)
</script>

Niceware uses window.{crypto, msCrypto}.getRandomValues for entropy in the browser.

Docs

NOTE: When used in the browser, Buffer is replaced with window.Uint8Array.

niceware ⏏

Kind: Exported constant

niceware.bytesToPassphrase(bytes) ⇒ Array.<string>

Converts a byte array into a passphrase.

Kind: static method of niceware

Param Type Description
bytes Buffer The bytes to convert

niceware.passphraseToBytes(words) ⇒ Buffer

Converts a phrase back into the original byte array.

Kind: static method of niceware

Param Type Description
words Array.<string> The words to convert

niceware.generatePassphrase(size) ⇒ Array.<string>

Generates a random passphrase with the specified number of bytes. NOTE: size must be an even number.

Kind: static method of niceware

Param Type Description
size number The number of random bytes to use

Niceware ports

Credits

Niceware was inspired by Diceware. Its wordlist is derived from http://www-01.sil.org/linguistics/wordlists/english/. This project is based on my work on OpenPGP key backup for the Yahoo End-to-End project.