walletunlocker

Documentation

Index

• Variables
• func ValidatePassword(password []byte) error
• type ChannelsToRecover
• type UnlockerService
  • func New(chainDir string, params *chaincfg.Params, noFreelistSync bool, ...) *UnlockerService
  • func (u *UnlockerService) ChangePassword(ctx context.Context, in *lnrpc.ChangePasswordRequest) (*lnrpc.ChangePasswordResponse, error)
  • func (u *UnlockerService) GenSeed(_ context.Context, in *lnrpc.GenSeedRequest) (*lnrpc.GenSeedResponse, error)
  • func (u *UnlockerService) InitWallet(ctx context.Context, in *lnrpc.InitWalletRequest) (*lnrpc.InitWalletResponse, error)
  • func (u *UnlockerService) UnlockWallet(ctx context.Context, in *lnrpc.UnlockWalletRequest) (*lnrpc.UnlockWalletResponse, error)
• type WalletInitMsg
• type WalletUnlockMsg

Variables

var (
	// ErrUnlockTimeout signals that we did not get the expected unlock
	// message before the timeout occurred.
	ErrUnlockTimeout = errors.New("got no unlock message before timeout")
)

Functions

func ValidatePassword

func ValidatePassword(password []byte) error

ValidatePassword assures the password meets all of our constraints.

Types

type ChannelsToRecover

type ChannelsToRecover struct {
	// PackedMultiChanBackup is an encrypted and serialized multi-channel
	// backup.
	PackedMultiChanBackup chanbackup.PackedMulti

	// PackedSingleChanBackups is a series of encrypted and serialized
	// single-channel backup for one or more channels.
	PackedSingleChanBackups chanbackup.PackedSingles
}

ChannelsToRecover wraps any set of packed (serialized+encrypted) channel back ups together. These can be passed in when unlocking the wallet, or creating a new wallet for the first time with an existing seed.

type UnlockerService

type UnlockerService struct {
	// InitMsgs is a channel that carries all wallet init messages.
	InitMsgs chan *WalletInitMsg

	// UnlockMsgs is a channel where unlock parameters provided by the rpc
	// client to be used to unlock and decrypt an existing wallet will be
	// sent.
	UnlockMsgs chan *WalletUnlockMsg

	// MacResponseChan is the channel for sending back the admin macaroon to
	// the WalletUnlocker service.
	MacResponseChan chan []byte
	// contains filtered or unexported fields
}

UnlockerService implements the WalletUnlocker service used to provide lnd with a password for wallet encryption at startup. Additionally, during initial setup, users can provide their own source of entropy which will be used to generate the seed that's ultimately used within the wallet.

func New

func New(chainDir string, params *chaincfg.Params, noFreelistSync bool,
	macaroonFiles []string, dbTimeout time.Duration,
	resetWalletTransactions bool) *UnlockerService

New creates and returns a new UnlockerService.

func (*UnlockerService) ChangePassword

func (u *UnlockerService) ChangePassword(ctx context.Context,
	in *lnrpc.ChangePasswordRequest) (*lnrpc.ChangePasswordResponse, error)

ChangePassword changes the password of the wallet and sends the new password across the UnlockPasswords channel to automatically unlock the wallet if successful.

func (*UnlockerService) GenSeed

func (u *UnlockerService) GenSeed(_ context.Context,
	in *lnrpc.GenSeedRequest) (*lnrpc.GenSeedResponse, error)

GenSeed is the first method that should be used to instantiate a new lnd instance. This method allows a caller to generate a new aezeed cipher seed given an optional passphrase. If provided, the passphrase will be necessary to decrypt the cipherseed to expose the internal wallet seed.

Once the cipherseed is obtained and verified by the user, the InitWallet method should be used to commit the newly generated seed, and create the wallet.

func (*UnlockerService) InitWallet

func (u *UnlockerService) InitWallet(ctx context.Context,
	in *lnrpc.InitWalletRequest) (*lnrpc.InitWalletResponse, error)

InitWallet is used when lnd is starting up for the first time to fully initialize the daemon and its internal wallet. At the very least a wallet password must be provided. This will be used to encrypt sensitive material on disk.

In the case of a recovery scenario, the user can also specify their aezeed mnemonic and passphrase. If set, then the daemon will use this prior state to initialize its internal wallet.

Alternatively, this can be used along with the GenSeed RPC to obtain a seed, then present it to the user. Once it has been verified by the user, the seed can be fed into this RPC in order to commit the new wallet.

func (*UnlockerService) UnlockWallet

func (u *UnlockerService) UnlockWallet(ctx context.Context,
	in *lnrpc.UnlockWalletRequest) (*lnrpc.UnlockWalletResponse, error)

UnlockWallet sends the password provided by the incoming UnlockWalletRequest over the UnlockMsgs channel in case it successfully decrypts an existing wallet found in the chain's wallet database directory.

type WalletInitMsg

type WalletInitMsg struct {
	// Passphrase is the passphrase that will be used to encrypt the wallet
	// itself. This MUST be at least 8 characters.
	Passphrase []byte

	// WalletSeed is the deciphered cipher seed that the wallet should use
	// to initialize itself.
	WalletSeed *aezeed.CipherSeed

	// RecoveryWindow is the address look-ahead used when restoring a seed
	// with existing funds. A recovery window zero indicates that no
	// recovery should be attempted, such as after the wallet's initial
	// creation.
	RecoveryWindow uint32

	// ChanBackups a set of static channel backups that should be received
	// after the wallet has been initialized.
	ChanBackups ChannelsToRecover

	// StatelessInit signals that the user requested the daemon to be
	// initialized stateless, which means no unencrypted macaroons should be
	// written to disk.
	StatelessInit bool
}

WalletInitMsg is a message sent by the UnlockerService when a user wishes to set up the internal wallet for the first time. The user MUST provide a passphrase, but is also able to provide their own source of entropy. If provided, then this source of entropy will be used to generate the wallet's HD seed. Otherwise, the wallet will generate one itself.

type WalletUnlockMsg

type WalletUnlockMsg struct {
	// Passphrase is the passphrase that will be used to encrypt the wallet
	// itself. This MUST be at least 8 characters.
	Passphrase []byte

	// RecoveryWindow is the address look-ahead used when restoring a seed
	// with existing funds. A recovery window zero indicates that no
	// recovery should be attempted, such as after the wallet's initial
	// creation, but before any addresses have been created.
	RecoveryWindow uint32

	// Wallet is the loaded and unlocked Wallet. This is returned through
	// the channel to avoid it being unlocked twice (once to check if the
	// password is correct, here in the WalletUnlocker and again later when
	// lnd actually uses it). Because unlocking involves scrypt which is
	// resource intensive, we want to avoid doing it twice.
	Wallet *wallet.Wallet

	// ChanBackups a set of static channel backups that should be received
	// after the wallet has been unlocked.
	ChanBackups ChannelsToRecover

	// UnloadWallet is a function for unloading the wallet, which should
	// be called on shutdown.
	UnloadWallet func() error

	// StatelessInit signals that the user requested the daemon to be
	// initialized stateless, which means no unencrypted macaroons should be
	// written to disk.
	StatelessInit bool
}

WalletUnlockMsg is a message sent by the UnlockerService when a user wishes to unlock the internal wallet after initial setup. The user can optionally specify a recovery window, which will resume an interrupted rescan for used addresses.