mnemonics

README

entropy-mnemonics

This repository has moved to GitLab.

Documentation

Overview

Package mnemonics is a package that converts []byte's into human-friendly phrases, using common words pulled from a dictionary. The dictionary size is 1626, and multiple languages are supported. Each dictionary supports modified phrases. Only the first few characters of each word are important. These characters form a unique prefix. For example, in the English dictionary, the unique prefix len (EnglishUniquePrefixLen) is 3, which means the word 'abbey' could be replaced with the word 'abbot', and the program would still run as expected.

The primary purpose of this library is creating human-friendly cryptographically secure passwords. A cryptographically secure password needs to contain between 128 and 256 bits of entropy. Humans are typically incapable of generating sufficiently secure passwords without a random number generator, and 256-bit random numbers tend to difficult to memorize and even to write down (a single mistake in the writing, or even a single somewhat sloppy character can render the backup useless).

By using a small set of common words instead of random numbers, copying errors are more easily spotted and memorization is also easier, without sacrificing password strength.

The mnemonics package does not have any functions for actually generating entropy, it just converts existing entropy into human-friendly phrases.

Index

• Constants
• func FromPhrase(p Phrase, did DictionaryID) ([]byte, error)
• func FromString(str string, did DictionaryID) ([]byte, error)
• type Dictionary
• type DictionaryID
• type Phrase
  • func ToPhrase(entropy []byte, did DictionaryID) (Phrase, error)
  • func (p Phrase) String() string

Constants

const (
	// DictionarySize specifies the size of the dictionaries that are used by
	// the mnemonics package. All dictionaries are the same length so that the
	// same []byte can be encoded into multiple languages and all results will
	// resemble eachother.
	DictionarySize = 1626
)

Functions

func FromPhrase

func FromPhrase(p Phrase, did DictionaryID) ([]byte, error)

FromPhrase converts an input phrase back to the original []byte.

func FromString

func FromString(str string, did DictionaryID) ([]byte, error)

FromString converts an input string into a phrase, and then calls 'FromPhrase'.

Types

type Dictionary

type Dictionary [DictionarySize]string

Dictionary is a DictionarySize list of words which can be used to create human-friendly entropy.

type DictionaryID

type DictionaryID string

DictionaryID is a type-safe identifier that indicates which dictionary should be used.

const (
	// English is an id pointing to the standard password dictionary for
	// english users.
	English DictionaryID = "english"

	// EnglishUniquePrefixLen indicates the number of letters needed to achieve
	// unique prefixes throughout the english dictionary. No two words in the
	// dictionary have the same prefix of len EnglishUniquePrefixLen.
	EnglishUniquePrefixLen = 3
)

const (
	// German is an id pointing to the standard password dictionary for german
	// users.
	German DictionaryID = "german"

	// GermanUniquePrefixLen indicates the number of letters needed to achieve
	// unique prefixes throughout the german dictionary. No two words in the
	// dictionary have the same prefix of len GermanUniquePrefixLen.
	GermanUniquePrefixLen = 4
)

const (
	// Japanese is an id pointing to the standard password dictionary for
	// Japanese users.
	Japanese DictionaryID = "japanese"

	// JapaneseUniquePrefixLen indicates the number of letters needed to
	// achieve unique prefixes throughout the Japanese dictionary. No two
	// words in the dictionary have the same prefix of len
	// JapaneseUniquePrefixLen.
	JapaneseUniquePrefixLen = 3
)

type Phrase

type Phrase []string

Phrase is the human readable version of a random []byte. Most typically, a phrase is displayed to the user using the String method.

func ToPhrase

func ToPhrase(entropy []byte, did DictionaryID) (Phrase, error)

ToPhrase converts an input []byte to a human-friendly phrase. The conversion is reversible.

func (Phrase) String

func (p Phrase) String() string

String combines a phrase into a single string by concatenating the individual words with space separation.