14259349056

Committed 04 Apr 2025 06:24AM UTC coverage: 69.043% (+10.4%) from 58.637%

Build # 14259349056

Build Type

Pull #9635

github

Committed by

web-flow

Commit Message

Merge 6155d9bf5 into 6a3845b79

Pull Request Pull Request #9635: aezeed : add error handling for unexpected plaintext size in decipherCiph…

Run Details

1 of 6 new or added lines in 1 file covered. (16.67%)

26 existing lines in 7 files now uncovered.

133435 of 193265 relevant lines covered (69.04%)

22207.23 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

88.04

/aezeed/cipherseed.go

package aezeed

import (
        "bytes"
        "crypto/rand"
        "encoding/binary"
        "fmt"
        "hash/crc32"
        "io"
        "time"

        "github.com/Yawning/aez"
        "github.com/kkdai/bstream"
        "golang.org/x/crypto/scrypt"
)

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 to generate
        // the seed.
        EntropySize = 16

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

        // SaltSize is the size of the salt we'll generate to use with scrypt
        // to generate a key for use within aez from the user's passphrase. The
        // role of the salt is to make the creation of rainbow tables
        // infeasible.
        SaltSize = 5

        // adSize is the size of the encoded associated data that will be
        // passed into aez when enciphering and deciphering the seed. The AD
        // itself (associated data) is just the cipher seed version and salt.
        adSize = 6

        // checkSumSize is the size of the checksum applied to the final
        // encoded ciphertext.
        checkSumSize = 4

        // keyLen is the size of the key that we'll use for encryption with
        // aez.
        keyLen = 32

        // BitsPerWord is the number of bits each word in the wordlist encodes.
        // We encode our mnemonic using 24 words, so 264 bits (33 bytes).
        BitsPerWord = 11

        // saltOffset is the index within an enciphered cipher seed that marks
        // the start of the salt.
        saltOffset = EncipheredCipherSeedSize - checkSumSize - SaltSize

        // checkSumSize is the index within an enciphered cipher seed that
        // marks the start of the checksum.
        checkSumOffset = EncipheredCipherSeedSize - checkSumSize
)

var (
        // Below at the default scrypt parameters that are tied to cipher seed
        // version zero.
        scryptN = 32768
        scryptR = 8
        scryptP = 1

        // crcTable is a table that presents the polynomial we'll use for
        // computing our checksum.
        crcTable = crc32.MakeTable(crc32.Castagnoli)

        // defaultPassphrase is the default passphrase that will be used for
        // encryption in the case that the user chooses not to specify their
        // own passphrase.
        defaultPassphrase = []byte("aezeed")
)

var (
        // BitcoinGenesisDate is the timestamp of Bitcoin's genesis block.
        // We'll use this value in order to create a compact birthday for the
        // seed. The birthday will be interested as the number of days since
        // the genesis date. We refer to this time period as ABE (after Bitcoin
        // era).
        BitcoinGenesisDate = time.Unix(1231006505, 0)
)

// SeedOptions is a type that holds options that configure the generation of a
// new cipher seed.
type SeedOptions struct {
        // randomnessSource is the source of randomness that is used to generate
        // the salt that is used for encrypting the seed.
        randomnessSource io.Reader
}

// DefaultOptions returns the default seed options.
func DefaultOptions() *SeedOptions {
        return &SeedOptions{
                randomnessSource: rand.Reader,
        }
}

// SeedOptionModifier is a function signature for modifying the default
// SeedOptions.
type SeedOptionModifier func(*SeedOptions)

// WithRandomnessSource returns an option modifier that replaces the default
// randomness source with the given reader.
func WithRandomnessSource(src io.Reader) SeedOptionModifier {
        return func(opts *SeedOptions) {
                opts.randomnessSource = src
        }
}

// CipherSeed is a fully decoded instance of the aezeed scheme. At a high
// level, the encoded cipher seed 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.
type CipherSeed struct {
        // InternalVersion is the version of the plaintext cipher seed. 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

        // salt is the salt that was used to generate the key from the user's
        // specified passphrase.
        salt [SaltSize]byte
}

// 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 fixed argument should be the time at which the seed was
// created, followed by optional seed option modifiers.
func New(internalVersion uint8, entropy *[EntropySize]byte,
        now time.Time, modifiers ...SeedOptionModifier) (*CipherSeed, error) {

        opts := DefaultOptions()
        for _, modifier := range modifiers {
                modifier(opts)
        }

        // If a set of entropy wasn't provided, then we'll read a set of bytes
        // from the randomness source provided (which by default is the system's
        // CSPRNG).
        var seed [EntropySize]byte
        if entropy == nil {
                if _, err := opts.randomnessSource.Read(seed[:]); err != nil {
                        return nil, err
                }
        } else {
                // Otherwise, we'll copy the set of bytes.
                copy(seed[:], entropy[:])
        }

        // To compute our "birthday", we'll first use the current time, then
        // subtract that from the Bitcoin Genesis Date. We'll then convert that
        // value to days.
        birthday := uint16(now.Sub(BitcoinGenesisDate) / (time.Hour * 24))

        c := &CipherSeed{
                InternalVersion: internalVersion,
                Birthday:        birthday,
                Entropy:         seed,
        }

        // Next, we'll read a random salt that will be used with scrypt to
        // eventually derive our key.
        if _, err := opts.randomnessSource.Read(c.salt[:]); err != nil {
                return nil, err
        }

        return c, nil
}

// encode attempts to encode the target cipherSeed into the passed io.Writer
// instance.
func (c *CipherSeed) encode(w io.Writer) error {
        err := binary.Write(w, binary.BigEndian, c.InternalVersion)
        if err != nil {
                return err
        }

        if err := binary.Write(w, binary.BigEndian, c.Birthday); err != nil {
                return err
        }

        if _, err := w.Write(c.Entropy[:]); err != nil {
                return err
        }

        return nil
}

// decode attempts to decode an encoded cipher seed instance into the target
// CipherSeed struct.
func (c *CipherSeed) decode(r io.Reader) error {
        err := binary.Read(r, binary.BigEndian, &c.InternalVersion)
        if err != nil {
                return err
        }

        if err := binary.Read(r, binary.BigEndian, &c.Birthday); err != nil {
                return err
        }

        if _, err := io.ReadFull(r, c.Entropy[:]); err != nil {
                return err
        }

        return nil
}

// encodeAD returns the fully encoded associated data for use when performing
// our current enciphering operation. The AD is: version || salt.
func encodeAD(version uint8, salt [SaltSize]byte) [adSize]byte {
        var ad [adSize]byte
        ad[0] = version
        copy(ad[1:], salt[:])

        return ad
}

// extractAD extracts an associated data from a fully encoded and enciphered
// cipher seed. This is to be used when attempting to decrypt an enciphered
// cipher seed.
func extractAD(encipheredSeed [EncipheredCipherSeedSize]byte) [adSize]byte {
        var ad [adSize]byte
        ad[0] = encipheredSeed[0]

        copy(ad[1:], encipheredSeed[saltOffset:checkSumOffset])

        return ad
}

// encipher takes a fully populated cipher seed instance, and enciphers the
// encoded seed, then appends a randomly generated seed used to stretch the
// passphrase out into an appropriate key, then computes a checksum over the
// preceding.
func (c *CipherSeed) encipher(pass []byte) ([EncipheredCipherSeedSize]byte,
        error) {

        var cipherSeedBytes [EncipheredCipherSeedSize]byte

        // If the passphrase wasn't provided, then we'll use the string
        // "aezeed" in place.
        passphrase := pass
        if len(passphrase) == 0 {
                passphrase = defaultPassphrase
        }

        // With our salt pre-generated, we'll now run the password through a
        // KDF to obtain the key we'll use for encryption.
        key, err := scrypt.Key(
                passphrase, c.salt[:], scryptN, scryptR, scryptP, keyLen,
        )
        if err != nil {
                return cipherSeedBytes, err
        }

        // Next, we'll encode the serialized plaintext cipher seed into a buffer
        // that we'll use for encryption.
        var seedBytes bytes.Buffer
        if err := c.encode(&seedBytes); err != nil {
                return cipherSeedBytes, err
        }

        // With our plaintext seed encoded, we'll now construct the AD that
        // will be passed to the encryption operation. This ensures to
        // authenticate both the salt and the external version.
        ad := encodeAD(CipherSeedVersion, c.salt)

        // With all items assembled, we'll now encipher the plaintext seed
        // with our AD, key, and MAC size.
        cipherSeed := seedBytes.Bytes()
        cipherText := aez.Encrypt(
                key, nil, [][]byte{ad[:]}, CipherTextExpansion, cipherSeed, nil,
        )

        // Finally, we'll pack the {version || ciphertext || salt || checksum}
        // seed into a byte slice for encoding as a mnemonic.
        cipherSeedBytes[0] = CipherSeedVersion
        copy(cipherSeedBytes[1:saltOffset], cipherText)
        copy(cipherSeedBytes[saltOffset:], c.salt[:])

        // With the seed mostly assembled, we'll now compute a checksum all the
        // contents.
        checkSum := crc32.Checksum(cipherSeedBytes[:checkSumOffset], crcTable)

        // With our checksum computed, we can finish encoding the full cipher
        // seed.
        var checkSumBytes [4]byte
        binary.BigEndian.PutUint32(checkSumBytes[:], checkSum)
        copy(cipherSeedBytes[checkSumOffset:], checkSumBytes[:])

        return cipherSeedBytes, nil
}

// cipherTextToMnemonic converts the aez ciphertext appended with the salt to a
// 24-word mnemonic pass phrase.
func cipherTextToMnemonic(cipherText [EncipheredCipherSeedSize]byte) (Mnemonic,
        error) {

        var words [NumMnemonicWords]string

        // First, we'll convert the ciphertext itself into a bitstream for easy
        // manipulation.
        cipherBits := bstream.NewBStreamReader(cipherText[:])

        // With our bitstream obtained, we'll read 11 bits at a time, then use
        // that to index into our word list to obtain the next word.
        for i := 0; i < NumMnemonicWords; i++ {
                index, err := cipherBits.ReadBits(BitsPerWord)
                if err != nil {
                        return Mnemonic{}, err
                }

                words[i] = DefaultWordList[index]
        }

        return words, nil
}

// 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.
func (c *CipherSeed) ToMnemonic(pass []byte) (Mnemonic, error) {
        // First, we'll convert the valid seed triple into an aez cipher text
        // with our KDF salt appended to it.
        cipherText, err := c.encipher(pass)
        if err != nil {
                return Mnemonic{}, err
        }

        // Now that we have our cipher text, we'll convert it into a mnemonic
        // phrase.
        return cipherTextToMnemonic(cipherText)
}

// Encipher maps the cipher seed to an aez ciphertext using an optional
// passphrase.
func (c *CipherSeed) Encipher(pass []byte) ([EncipheredCipherSeedSize]byte,
        error) {

        return c.encipher(pass)
}

// BirthdayTime returns the cipher seed's internal birthday format as a native
// golang Time struct.
func (c *CipherSeed) BirthdayTime() time.Time {
        offset := time.Duration(c.Birthday) * 24 * time.Hour
        return BitcoinGenesisDate.Add(offset)
}

// Mnemonic is a 24-word passphrase as of cipher seed version 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.
type Mnemonic [NumMnemonicWords]string

// mnemonicToCipherText converts a 24-word mnemonic phrase into a 33 byte
// cipher text.
//
// NOTE: This assumes that all words have already been checked to be amongst
// our word list.
func mnemonicToCipherText(mnemonic *Mnemonic) [EncipheredCipherSeedSize]byte {
        var cipherText [EncipheredCipherSeedSize]byte

        // We'll now perform the reverse mapping to that of
        // cipherTextToMnemonic: we'll get the index of the word, then write
        // out that index to the bit stream.
        cipherBits := bstream.NewBStreamWriter(EncipheredCipherSeedSize)
        for _, word := range mnemonic {
                // Using the reverse word map, we'll locate the index of this
                // word within the word list.
                index := uint64(ReverseWordMap[word])

                // With the index located, we'll now write this out to the
                // bitstream, appending to what's already there.
                cipherBits.WriteBits(index, BitsPerWord)
        }

        copy(cipherText[:], cipherBits.Bytes())

        return cipherText
}

// 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.
func (m *Mnemonic) ToCipherSeed(pass []byte) (*CipherSeed, error) {
        // First, we'll attempt to decipher the mnemonic by mapping back into
        // our byte slice and applying our deciphering scheme.
        plainSeed, salt, err := m.Decipher(pass)
        if err != nil {
                return nil, err
        }

        // If decryption was successful, then we'll decode into a fresh
        // CipherSeed struct.
        c := CipherSeed{
                salt: salt,
        }
        if err := c.decode(bytes.NewReader(plainSeed[:])); err != nil {
                return nil, err
        }

        return &c, nil
}

// decipherCipherSeed attempts to decipher the passed cipher seed ciphertext
// using the passed passphrase. This function is the opposite of
// the encipher method.
func decipherCipherSeed(cipherSeedBytes [EncipheredCipherSeedSize]byte,
        pass []byte) ([DecipheredCipherSeedSize]byte, [SaltSize]byte, error) {

        var (
                plainSeed [DecipheredCipherSeedSize]byte
                salt      [SaltSize]byte
        )

        // Before we do anything, we'll ensure that the version is one that we
        // understand. Otherwise, we won't be able to decrypt, or even parse
        // the cipher seed.
        if cipherSeedBytes[0] != CipherSeedVersion {
                return plainSeed, salt, ErrIncorrectVersion
        }

        // Next, we'll slice off the salt from the pass cipher seed, then
        // snip off the end of the cipher seed, ignoring the version, and
        // finally the checksum.
        copy(salt[:], cipherSeedBytes[saltOffset:saltOffset+SaltSize])
        cipherSeed := cipherSeedBytes[1:saltOffset]
        checksum := cipherSeedBytes[checkSumOffset:]

        // Before we perform any crypto operations, we'll re-create and verify
        // the checksum to ensure that the user input the proper set of words.
        freshChecksum := crc32.Checksum(
                cipherSeedBytes[:checkSumOffset], crcTable,
        )
        if freshChecksum != binary.BigEndian.Uint32(checksum) {
                return plainSeed, salt, ErrIncorrectMnemonic
        }

        // With the salt separated from the cipher text, we'll now obtain the
        // key used for encryption.
        key, err := scrypt.Key(pass, salt[:], scryptN, scryptR, scryptP, keyLen)
        if err != nil {
                return plainSeed, salt, err
        }

        // We'll also extract the AD that will be required to properly pass the
        // MAC check.
        ad := extractAD(cipherSeedBytes)

        // With the key, we'll attempt to decrypt the plaintext. If the
        // ciphertext was altered, or the passphrase is incorrect, then we'll
        // error out.
        plainSeedBytes, ok := aez.Decrypt(
                key, nil, [][]byte{ad[:]}, CipherTextExpansion, cipherSeed, nil,
        )
        if !ok {
                return plainSeed, salt, ErrInvalidPass
        }
        if len(plainSeedBytes) != DecipheredCipherSeedSize {
                return plainSeed, salt,
                        fmt.Errorf("unexpected plaintext "+
                                "size: got %d, want %d", len(plainSeedBytes),
                                DecipheredCipherSeedSize)
        }
        copy(plainSeed[:], plainSeedBytes)

        return plainSeed, salt, nil

}

// Decipher attempts to decipher the encoded mnemonic by first mapping to the
// original ciphertext, then applying our deciphering scheme. ErrInvalidPass
// will be returned if the passphrase is incorrect.
func (m *Mnemonic) Decipher(pass []byte) ([DecipheredCipherSeedSize]byte,
        [SaltSize]byte, error) {

        // Before we attempt to map the mnemonic back to the original
        // ciphertext, we'll ensure that all the word are actually a part of
        // the current default word list.
        wordDict := make(map[string]struct{}, len(DefaultWordList))
        for _, word := range DefaultWordList {
                wordDict[word] = struct{}{}
        }

        for i, word := range m {
                if _, ok := wordDict[word]; !ok {
                        emptySeed := [DecipheredCipherSeedSize]byte{}
                        return emptySeed, [SaltSize]byte{},
                                ErrUnknownMnemonicWord{
                                        Word:  word,
                                        Index: uint8(i),
                                }
                }
        }

        // If the passphrase wasn't provided, then we'll use the string
        // "aezeed" in place.
        passphrase := pass
        if len(passphrase) == 0 {
                passphrase = defaultPassphrase
        }

        // Next, we'll map the mnemonic phrase back into the original cipher
        // text.
        cipherText := mnemonicToCipherText(m)

        // Finally, we'll attempt to decipher the enciphered seed. The result
        // will be the raw seed minus the ciphertext expansion, external
        // version, and salt.
        return decipherCipherSeed(cipherText, passphrase)
}

// 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 (m *Mnemonic) ChangePass(oldPass, newPass []byte) (Mnemonic, error) {
        var newMnemonic Mnemonic

        // First, we'll try to decrypt the current mnemonic using the existing
        // passphrase. If this fails, then we can't proceed any further.
        cipherSeed, err := m.ToCipherSeed(oldPass)
        if err != nil {
                return newMnemonic, err
        }

        // If the deciphering was successful, then we'll now re-encipher using
        // the new user provided passphrase.
        return cipherSeed.ToMnemonic(newPass)
}

lightningnetwork / lnd / 14259349056

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous