bip39

Documentation

Overview

Package bip39 implements the BIP39 mnemonic encoding scheme for private key seed data.

To generate a mnemonic, generate some random entropy (either 16, 20, 24, 28, or 32 bytes), and use EncodeToWords to encode the entropy as a mnemonic. Normally this phrase is given to the user as a backup.

To utilize the mnemonic to generate a seed for cryptographic keys, pass the mnemonic and an optional deniability passphrase to DeriveSeed.

https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki

Index

• Constants
• Variables
• func DecodeWords(words []string) (entropy []byte, err error)
• func DeriveSeed(words []string, passphrase string) []byte
• func EncodeToWords(entropy []byte) ([]string, error)
• func GenerateEntropy(rand io.Reader, bitSize int) ([]byte, error)
• func GenerateMnemonic(rand io.Reader, nWords int) ([]string, error)
• func ValidateEntropySize(bitSize int) error

Constants

const (
	// EntropyMinimumSize and EntropyMaximumSize specify the minimum/maximum number of bits of
	// entropy needed to generate a secure mnemonic.
	EntropyMinimumSize = 128
	EntropyMaximumSize = 256
)

const (
	// SeedSaltPrefix is the salt used for BIP39 seed generation via the PBKDF2 function.
	SeedSaltPrefix = "mnemonic"
	// SeedIterationCount is the PBKDF2 iteration count used to generate seeds.
	SeedKDFIterationCount = 2048
	// SeedLength is the output size of BIP39 seeds generated by the PBKDF2 function.
	SeedLength = 64
)

Variables

var (
	// ErrInvalidWordsLength is returned by DecodeWords if the given mnemonic is of
	// an incorrect length.
	ErrInvalidWordsLength = errors.New(
		"invalid BIP39 mnemonic length; must be 12, 15, 18, 21, or 24 words",
	)

	// ErrInvalidWord is returned by DecodeWords if the given mnemonic contains an unknown word.
	ErrInvalidWord = errors.New("BIP39 mnemonic contains word not found in english word list")

	// ErrInvalidChecksum is returned by DecodeWords if the given mnemonic fails checksum validation.
	ErrInvalidChecksum = errors.New("BIP39 mnemonic has invalid checksum")
)

var ErrInvalidEntropySize = errors.New(
	"bad entropy bit size; must be between 128 - 256 bits and must be divisible by 32",
)

ErrInvalidEntropySize is returned by ValidateEntropySize and GenerateEntropy if the entropy's bit size is not within the bounds of EntropyMinimumSize and EntropyMaximumSize.

var WordList = []string{}/* 2048 elements not displayed */

WordList is the BIP39 English wordlist sourced from:

https://github.com/bitcoin/bips/blob/52f68fecd8ec9604672e26392468e7e7edf25a5e/bip-0039/english.txt

var WordMap map[string]int

WordMap is a mapping of English BIP39 words to their indices.

Functions

func DecodeWords

func DecodeWords(words []string) (entropy []byte, err error)

DecodeWords decodes the given mnemonic into the entropy it encodes, while also verifying the length of the mnemonic and its checksum.

Returns any one of ErrInvalidWordsLength, ErrInvalidWord, or ErrInvalidChecksum if the mnemonic is not valid.

func DeriveSeed

func DeriveSeed(words []string, passphrase string) []byte

DeriveSeed determinstically converts a BIP39 mnemonic and passphrase into 64-bytes suitable for use as a cryptographic key.

NOTE: the validity of the mnemonic is not checked in this function. Use DecodeWords to confirm the words and checksum are valid before deriving key material from a user-given mnemonic.

func EncodeToWords

func EncodeToWords(entropy []byte) ([]string, error)

EncodeToWords encodes the given entropy as a BIP39 mnemonic. Checks the entropy is of a valid length (either 16, 20, 24, 28, or 32 bytes).

func GenerateEntropy

func GenerateEntropy(rand io.Reader, bitSize int) ([]byte, error)

GenerateEntropy creates entropy of the given bitSize. Returns ErrInvalidEntropySize if size is not valid.

func GenerateMnemonic

func GenerateMnemonic(rand io.Reader, nWords int) ([]string, error)

GenerateMnemonic creates a random BIP39 mnemonic phrase using entropy from rand.

func ValidateEntropySize

func ValidateEntropySize(bitSize int) error

ValidateEntropySize checks if entropy of bitSize bits is valid and returns ErrInvalidEntropySize if it is not.