passphrasegenerator

README

Phrase Generator

This package implements a high entropy, performant passphrase generator in Go utilizing the Ganymede algorithm. It uses a phrase "mask" to represent the type of symbol that is included, whether a word, special character, or any other modifier.

Driving Principles

The goal is to create a phrase generator that creates phrases with as much or more entropy than a Diceware generated phrase, along with additional configurability and customizability. The Ganymede algorithm also includes the ability to calculate the strength of a generated phrase in real time.

Kerckhoff's Principle holds that even if all parts of a system are known, a secure system should still be secure. Anything less is Security through Obscurity, which is no security at all.

Discouraging discussion of weaknesses of the algorithm or any vulnerabilities is counterproductive; the Ganymede team takes any potential security issues very seriously. Please submit a PR or Issue if you feel there is a potential vulnerability or weakness.

Mask

Unlike other phrase generators, this generator doesn't rely on selecting a specific number of words, rather, words are generated independently until the correct value is achieved.

This is enabled by the generation of a "mask" specifying the unique item types that go into a passphrase. Depending on which modifiers are specified when the passphrase is generated, it ensures the exact number of correct items are outputted when the phrase is generated.

This also allows for even greater customizability of the generator, allowing it to generate a passphrase tailored to any modifier.

Entropy

The entropy of a passphrase can be also be calculated using the mask. Each unique identifier has an entropy, the sum of each adds up to the total entropy of a given phrase without any knowledge of the phrase itself.

Without any modifiers, the entropy of each word in the list is 13.2 bits, compared to the 12.9 bits in the Diceware word list.

Calculating Entropy

Calculating the entropy of a phrase is easy using just the phrase mask.

Given a mask M:

M = [WORD][SEP][NUMBER][SPEC_CHAR][WORD][SEP][LAST_WORD]

We can measure the entropy of the passphrase using the formula below, with H being the total Entropy.

Shannon Entropy Formula

$$ H(x) = -\sum_{i=1}^n [P(x_i) * log_bP(x_i)] = \sum_{i=1}^n [P(x_i) * log_b(1 / P(x_i))] $$

Entropy is calculated using the Shannon entropy formula, and measures the "unpredictability" of a password or passphrase. A higher entropy password offers additional protection from those that may try to crack a passphrase.

A higher entropy is better, it's recommended to use a password with a minimum of 25-30 bits of entropy for non-vital accounts and 60 bits or more for important accounts.

Documentation

Index

• Constants
• func CryptoShuffle(arr []int32) []int32
• func New(opts Options) (string, error)
• func NewPassword(opts Options) (string, error)
• func NewWithEntropy(opts Options) (string, float64)
• func SubSetSum(set []int32, target int32) (subset []int32, err error)
• type Options

Constants

const (
	PG_SPEC_CHAR int32 = 1 << iota

	PG_NUMBER

	PG_SEPARATOR

	PG_WORD
	// Only the last word is given this value
	PG_LAST_WORD
	// TODO: Add a bitmask representing the lengths of each word
	PG_WORD_LENGTH
)

Phrase modifiers

const (
	FILE_NAME = "./newwords.txt"
)

Functions

func CryptoShuffle

func CryptoShuffle(arr []int32) []int32

CryptoShuffle is an implementation of the Fisher-Yates shuffle

func New

func New(opts Options) (string, error)

New returns a newly generated passphrase.

func NewPassword

func NewPassword(opts Options) (string, error)

func NewWithEntropy

func NewWithEntropy(opts Options) (string, float64)

NewWithEntropy returns a new passphrase as well as a float32 containing the total entropy of the generated phrase.

func SubSetSum

func SubSetSum(set []int32, target int32) (subset []int32, err error)

Types

type Options

type Options struct {
	// Specify the desired maximum length of any single word.
	// Shorter words are easier to remember. Default word list
	// has a cap of 15
	MaxWordLength int
	// Desired Length of the phrase.
	PhraseLength int
	// Minimum number of special characters to
	// include in a generated phrase.
	SpecialChars int
	// Minimum number of numbers to include
	// in a generated phrase.
	Numbers int
	// Whether the letter case should be changed
	// in a generated phrase
	ChangeCase bool
	// The separator to separate different words.
	//
	// If no separator is desired enter "" for the value.
	Separator string
}