diceware

README

diceware v2

A Go library for generating secure, memorable Diceware passphrases. Backed by crypto/rand, ships with multiple wordlists, and supports optional special-character entropy enhancement.

What's in v2

• Options-struct API (PassphraseOptions + RollWords) alongside the original positional SimpleRollWords.
• DefaultOptions() for a sensible 6-word EFF Long passphrase.
• RandomSource interface for deterministic testing or alternate entropy sources.
• Sentinel errors (ErrInvalidWordlist, ErrInvalidWordCount, ErrInvalidWordFetched).

Background

• Diceware homepage
• Wikipedia

Requirements

• Go 1.26 or newer

Installation

go get github.com/everlastingbeta/diceware/v2

Usage

Defaults

package main

import (
	"fmt"

	"github.com/everlastingbeta/diceware/v2"
)

func main() {
	// 6 words, space-separated, EFF Long wordlist, crypto/rand.
	passphrase, err := diceware.RollWords(diceware.DefaultOptions())
	if err != nil {
		panic(err)
	}

	fmt.Println(passphrase)
}

Custom options

package main

import (
	"fmt"

	"github.com/everlastingbeta/diceware/v2"
	"github.com/everlastingbeta/diceware/v2/wordlist"
)

func main() {
	opts := diceware.PassphraseOptions{
		WordCount:      8,
		Separator:      "-",
		Wordlist:       wordlist.EFFLong,
		EnhanceEntropy: true,
	}

	passphrase, err := diceware.RollWords(opts)
	if err != nil {
		panic(err)
	}

	fmt.Println(passphrase)
}

v1-compatible positional API

passphrase, err := diceware.SimpleRollWords(6, " ", wordlist.EFFLong)
// or with entropy enhancement:
passphrase, err = diceware.SimpleRollWords(6, "-", wordlist.Original, true)

Sample output

default:              upstart embezzle haystack brainwash bombard hertz
custom (EFF Long):    playlist-wisplike-chive-coaster-caution-hypnoses-reliable-mangy
enhanced entropy:     c:onsult+ma9roon+sizzl3e+sm-ugly+usea?ble+supermom
EFF Short:            churn-wish-july-aroma-agile-curry-stain-boxer
Original:             bunny count cloy trust mw mere queasy egg

Security notes

• Randomness comes from crypto/rand by default.
• Entropy per word, by wordlist:
  • Original (7,776 words): ~12.9 bits
  • EFF Long (7,776 words): ~12.9 bits
  • EFF Short (1,296 words): ~10.3 bits
• Recommended minimum: 6 words from EFF Long (~77 bits of entropy).
• EnhanceEntropy injects random special characters into one or more words to add further entropy.

License

MIT

Documentation

Overview

Package diceware generates secure, memorable passphrases using the Diceware algorithm.

Diceware selects words at random from a wordlist by simulating dice rolls. This package draws randomness from crypto/rand by default and offers configurable word counts, separators, wordlists, and optional special-character entropy enhancement.

Quick start

passphrase, err := diceware.RollWords(diceware.DefaultOptions())

Custom options

opts := diceware.PassphraseOptions{
    WordCount:      8,
    Separator:      "-",
    Wordlist:       wordlist.EFFShort,
    EnhanceEntropy: true,
}
passphrase, err := diceware.RollWords(opts)

v1-compatible API

SimpleRollWords preserves the positional-argument API from v1:

passphrase, err := diceware.SimpleRollWords(6, " ", wordlist.Original, true)

Wordlists

Built-in wordlists live in the github.com/everlastingbeta/diceware/v2/wordlist subpackage: Original, EFFLong, EFFShort, EFFShortPrefix, and ExtraEntropy. Custom wordlists implement the Wordlist interface; the easiest path is wordlist.NewMap.

Testing

The RandomSource interface lets tests substitute a deterministic random source for crypto/rand. CryptoRandom is the default implementation.

Security

• Randomness comes from crypto/rand.
• Entropy per word: ~12.9 bits for Original and EFF Long (7,776 words), ~10.3 bits for EFF Short (1,296 words).
• Six words from EFF Long yields roughly 77 bits of entropy.
• EnhanceEntropy injects characters from ExtraEntropy into one or more words to add further entropy.

Index

• Variables
• func RollWord(wl Wordlist, randomSource RandomSource) (string, error)
• func RollWords(opts PassphraseOptions) (string, error)
• func SimpleRollWords(wordCount int, separator string, wl Wordlist, enhanceEntropy ...bool) (string, error)
• type CryptoRandom
  • func (CryptoRandom) GetRandom(maxVal *big.Int) (*big.Int, error)
• type PassphraseOptions
  • func DefaultOptions() PassphraseOptions
• type RandomSource
• type Wordlist

Variables

var (
	// ErrInvalidWordlist is returned when a nil wordlist is provided.
	ErrInvalidWordlist = errors.New("invalid nil wordlist provided")

	// ErrInvalidWordFetched is returned when a roll value does not map to a word.
	ErrInvalidWordFetched = errors.New("invalid empty word fetched")

	// ErrInvalidWordCount is returned when the requested word count is not positive.
	ErrInvalidWordCount = errors.New("invalid word count: must be positive")
)

Functions

func RollWord

func RollWord(wl Wordlist, randomSource RandomSource) (string, error)

RollWord rolls dice against wl and returns the matching word. If randomSource is nil, crypto/rand is used.

func RollWords

func RollWords(opts PassphraseOptions) (string, error)

RollWords generates a passphrase using the provided options.

func SimpleRollWords

func SimpleRollWords(wordCount int, separator string, wl Wordlist, enhanceEntropy ...bool) (string, error)

SimpleRollWords is the v1-compatible positional API for RollWords. Pass true as the optional fourth argument to enable entropy enhancement.

Types

type CryptoRandom

type CryptoRandom struct{}

CryptoRandom is the default RandomSource, backed by crypto/rand.

func (CryptoRandom) GetRandom

func (CryptoRandom) GetRandom(maxVal *big.Int) (*big.Int, error)

GetRandom returns a cryptographically secure random integer in [0, maxVal).

type PassphraseOptions

type PassphraseOptions struct {
	// WordCount is the number of words in the passphrase. Must be > 0.
	WordCount int

	// Separator is placed between words in the final passphrase.
	Separator string

	// Wordlist is the word source. Required.
	Wordlist Wordlist

	// EnhanceEntropy injects random special characters into some of the words.
	EnhanceEntropy bool

	// RandomSource overrides the default crypto/rand source. Optional.
	RandomSource RandomSource
}

PassphraseOptions configures passphrase generation.

func DefaultOptions

func DefaultOptions() PassphraseOptions

DefaultOptions returns a sensible PassphraseOptions: 6 words, space-separated, EFF Long wordlist, no entropy enhancement, crypto/rand source. EFF Long with 6 words yields roughly 77 bits of entropy.

type RandomSource

type RandomSource interface {
	// GetRandom returns a uniformly random integer in [0, maxVal).
	GetRandom(maxVal *big.Int) (*big.Int, error)
}

RandomSource abstracts random-number generation so tests (or alternative entropy sources) can substitute a deterministic implementation.

type Wordlist

type Wordlist interface {
	// FetchWord returns the word that corresponds to a dice-roll value,
	// or an empty string if no word is mapped to it.
	FetchWord(diceroll int) string

	// Rolls returns the number of dice this wordlist expects per word
	// (5 for Original and EFF Long, 4 for EFF Short, 2 for ExtraEntropy).
	Rolls() int

	// SidesOfDice returns the number of sides on each die (typically 6).
	SidesOfDice() *big.Int
}

Wordlist is the contract a diceware word source must satisfy.