aezeed

Documentation

Index

• Constants
• Variables
• type CipherSeed
  • func New(internalVersion uint8, entropy *[EntropySize]byte, now time.Time) (*CipherSeed, error)
  • func (c *CipherSeed) Encipher(pass []byte) ([EncipheredCipherSeedSize]byte, error)
  • func (c *CipherSeed) ToMnemonic(pass []byte) (Mnemonic, error)
• type ErrUnknownMnenomicWord
  • func (e ErrUnknownMnenomicWord) Error() string
• type Mnemonic
  • func (m *Mnemonic) ChangePass(oldPass, newPass []byte) (Mnemonic, error)
  • func (m *Mnemonic) Decipher(pass []byte) ([DecipheredCipherSeedSize]byte, error)
  • func (m *Mnemonic) ToCipherSeed(pass []byte) (*CipherSeed, error)

Constants

const (
	// CipherSeedVersion is the current version of the aezeed scheme as
	// defined in this package. This version indicates the following
	// parameters for the deciphered cipher seed: a 1 byte version, 2 bytes
	// for the Bitcoin Days Genesis timestamp, and 16 bytes for entropy. It
	// also governs how the cipher seed should be enciphered. In this
	// version we take the deciphered seed, create a 5 byte salt, use that
	// with an optional passphrase to generate a 32-byte key (via scrypt),
	// then encipher with aez (using the salt and version as AD). The final
	// enciphered seed is: version || ciphertext || salt.
	CipherSeedVersion uint8 = 0

	// DecipheredCipherSeedSize is the size of the plaintext seed resulting
	// from deciphering the cipher seed. The size consists of the
	// following:
	//
	//  * 1 byte version || 2 bytes timestamp || 16 bytes of entropy.
	//
	// The version is used by wallets to know how to re-derive relevant
	// addresses, the 2 byte timestamp a BDG (Bitcoin Days Genesis) offset,
	// and finally, the 16 bytes to be used to generate the HD wallet seed.
	DecipheredCipherSeedSize = 19

	// EncipheredCipherSeedSize is the size of the fully encoded+enciphered
	// cipher seed. We first obtain the enciphered plaintext seed by
	// carrying out the enciphering as governed in the current version. We
	// then take that enciphered seed (now 19+4=23 bytes due to ciphertext
	// expansion, essentially a checksum) and prepend a version, then
	// append the salt, and then take a checksum of everything. The
	// checksum allows us to verify that the user input the correct set of
	// words, then we can verify the passphrase due to the internal MAC
	// equiv.  The final breakdown is:
	//
	//  * 1 byte version || 23 byte enciphered seed || 5 byte salt || 4 byte checksum
	//
	// With CipherSeedVersion we encipher as follows: we use
	// scrypt(n=32768, r=8, p=1) to derive a 32-byte key from an optional
	// user passphrase. We then encipher the plaintext seed using a value
	// of tau (with aez) of 8-bytes (so essentially a 32-bit MAC).  When
	// enciphering, we include the version and scrypt salt as the AD.  This
	// gives us a total of 33 bytes. These 33 bytes fit cleanly into 24
	// mnemonic words.
	EncipheredCipherSeedSize = 33

	// CipherTextExpansion is the number of bytes that will be added as
	// redundancy for the enciphering scheme implemented by aez. This can
	// be seen as the size of the equivalent MAC.
	CipherTextExpansion = 4

	// EntropySize is the number of bytes of entropy we'll use the generate
	// the seed.
	EntropySize = 16

	// NummnemonicWords is the number of words that an encoded cipher seed
	// will result in.
	NummnemonicWords = 24
)

Variables

var (
	// ErrIncorrectVersion is returned if a seed bares a mismatched
	// external version to that of the package executing the aezeed scheme.
	ErrIncorrectVersion = fmt.Errorf("wrong seed version")

	// ErrInvalidPass is returned if the user enters an invalid passphrase
	// for a particular enciphered mnemonic.
	ErrInvalidPass = fmt.Errorf("invalid passphrase")

	// ErrIncorrectMnemonic is returned if we detect that the checksum of
	// the specified mnemonic doesn't match. This indicates the user input
	// the wrong mnemonic.
	ErrIncorrectMnemonic = fmt.Errorf("mnemonic phrase checksum doesn't" +
		"match")
)

Types

type CipherSeed

type CipherSeed struct {
	// InternalVersion is the version of the plaintext cipherseed. This is
	// to be used by wallets to determine if the seed version is compatible
	// with the derivation schemes they know.
	InternalVersion uint8

	// Birthday is the time that the seed was created. This is expressed as
	// the number of days since the timestamp in the Bitcoin genesis block.
	// We use days as seconds gives us wasted granularity. The oldest seed
	// that we can encode using this format is through the date 2188.
	Birthday uint16

	// Entropy is a set of bytes generated via a CSPRNG. This is the value
	// that should be used to directly generate the HD root, as defined
	// within BIP0032.
	Entropy [EntropySize]byte
	// contains filtered or unexported fields
}

CipherSeed is a fully decoded instance of the aezeed scheme. At a high level, the encoded cipherseed is the enciphering of: a version byte, a set of bytes for a timestamp, the entropy which will be used to directly construct the HD seed, and finally a checksum over the rest. This scheme was created as the widely used schemes in the space lack two critical traits: a version byte, and a birthday timestamp. The version allows us to modify the details of the scheme in the future, and the birthday gives wallets a limit of how far back in the chain they'll need to start scanning. We also add an external version to the enciphering plaintext seed. With this addition, seeds are able to be "upgraded" (to diff params, or entirely diff crypt), while maintaining the semantics of the plaintext seed.

The core of the scheme is the usage of aez to carefully control the size of the final encrypted seed. With the current parameters, this scheme can be encoded using a 24 word mnemonic. We use 4 bytes of ciphertext expansion when enciphering the raw seed, giving us the equivalent of 40-bit MAC (as we check for a particular seed version). Using the external 4 byte checksum, we're able to ensure that the user input the correct set of words. Finally, the password in the scheme is optional. If not specified, "aezeed" will be used as the password. Otherwise, the addition of the password means that users can encrypt the raw "plaintext" seed under distinct passwords to produce unique mnemonic phrases.

func New

func New(internalVersion uint8, entropy *[EntropySize]byte,
	now time.Time) (*CipherSeed, error)

New generates a new CipherSeed instance from an optional source of entropy. If the entropy isn't provided, then a set of random bytes will be used in place. The final argument should be the time at which the seed was created.

func (*CipherSeed) Encipher

func (c *CipherSeed) Encipher(pass []byte) ([EncipheredCipherSeedSize]byte, error)

Encipher maps the cipher seed to an aez ciphertext using an optional passphrase.

func (*CipherSeed) ToMnemonic

func (c *CipherSeed) ToMnemonic(pass []byte) (Mnemonic, error)

ToMnemonic maps the final enciphered cipher seed to a human readable 24-word mnemonic phrase. The password is optional, as if it isn't specified aezeed will be used in its place.

type ErrUnknownMnenomicWord

type ErrUnknownMnenomicWord struct {
	// contains filtered or unexported fields
}

ErrUnknownMnenomicWord is returned when attempting to decipher and enciphered mnemonic, but a word encountered isn't a member of our word list.

func (ErrUnknownMnenomicWord) Error

func (e ErrUnknownMnenomicWord) Error() string

Error returns a human readable string describing the error.

type Mnemonic

type Mnemonic [NummnemonicWords]string

Mnemonic is a 24-word passphrase as of CipherSeedVersion zero. This passphrase encodes an encrypted seed triple (version, birthday, entropy). Additionally, we also encode the salt used with scrypt to derive the key that the cipher text is encrypted with, and the version which tells us how to decipher the seed.

func (*Mnemonic) ChangePass

func (m *Mnemonic) ChangePass(oldPass, newPass []byte) (Mnemonic, error)

ChangePass takes an existing mnemonic, and passphrase for said mnemonic and re-enciphers the plaintext cipher seed into a brand new mnemonic. This can be used to allow users to re-encrypt the same seed with multiple pass phrases, or just change the passphrase on an existing seed.

func (*Mnemonic) Decipher

func (m *Mnemonic) Decipher(pass []byte) ([DecipheredCipherSeedSize]byte, error)

Decipher attempts to decipher the encoded mnemonic by first mapping to the original chipertext, then applying our deciphering scheme. ErrInvalidPass will be returned if the passphrase is incorrect.

func (*Mnemonic) ToCipherSeed

func (m *Mnemonic) ToCipherSeed(pass []byte) (*CipherSeed, error)

ToCipherSeed attempts to map the mnemonic to the original cipher text byte slice. Then we'll attempt to decrypt the ciphertext using aez with the passed passphrase, using the last 5 bytes of the ciphertext as a salt for the KDF.