4c8d374007
This commit adds the --stateless_init flag to all three wallet unlocker operations. Once you initialize a wallet stateless, you need to set this flag for every further wallet unlocker operation. Otherwise you risk non-encrypted macaroon information to leak to the underlying system.
239 lines
9.1 KiB
Protocol Buffer
239 lines
9.1 KiB
Protocol Buffer
syntax = "proto3";
|
|
|
|
import "rpc.proto";
|
|
|
|
package lnrpc;
|
|
|
|
option go_package = "github.com/lightningnetwork/lnd/lnrpc";
|
|
|
|
/*
|
|
* Comments in this file will be directly parsed into the API
|
|
* Documentation as descriptions of the associated method, message, or field.
|
|
* These descriptions should go right above the definition of the object, and
|
|
* can be in either block or // comment format.
|
|
*
|
|
* An RPC method can be matched to an lncli command by placing a line in the
|
|
* beginning of the description in exactly the following format:
|
|
* lncli: `methodname`
|
|
*
|
|
* Failure to specify the exact name of the command will cause documentation
|
|
* generation to fail.
|
|
*
|
|
* More information on how exactly the gRPC documentation is generated from
|
|
* this proto file can be found here:
|
|
* https://github.com/lightninglabs/lightning-api
|
|
*/
|
|
|
|
// WalletUnlocker is a service that is used to set up a wallet password for
|
|
// lnd at first startup, and unlock a previously set up wallet.
|
|
service WalletUnlocker {
|
|
/*
|
|
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.
|
|
*/
|
|
rpc GenSeed (GenSeedRequest) returns (GenSeedResponse);
|
|
|
|
/*
|
|
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.
|
|
*/
|
|
rpc InitWallet (InitWalletRequest) returns (InitWalletResponse);
|
|
|
|
/* lncli: `unlock`
|
|
UnlockWallet is used at startup of lnd to provide a password to unlock
|
|
the wallet database.
|
|
*/
|
|
rpc UnlockWallet (UnlockWalletRequest) returns (UnlockWalletResponse);
|
|
|
|
/* lncli: `changepassword`
|
|
ChangePassword changes the password of the encrypted wallet. This will
|
|
automatically unlock the wallet database if successful.
|
|
*/
|
|
rpc ChangePassword (ChangePasswordRequest) returns (ChangePasswordResponse);
|
|
}
|
|
|
|
message GenSeedRequest {
|
|
/*
|
|
aezeed_passphrase is an optional user provided passphrase that will be used
|
|
to encrypt the generated aezeed cipher seed. When using REST, this field
|
|
must be encoded as base64.
|
|
*/
|
|
bytes aezeed_passphrase = 1;
|
|
|
|
/*
|
|
seed_entropy is an optional 16-bytes generated via CSPRNG. If not
|
|
specified, then a fresh set of randomness will be used to create the seed.
|
|
When using REST, this field must be encoded as base64.
|
|
*/
|
|
bytes seed_entropy = 2;
|
|
}
|
|
message GenSeedResponse {
|
|
/*
|
|
cipher_seed_mnemonic is a 24-word mnemonic that encodes a prior aezeed
|
|
cipher seed obtained by the user. This field is optional, as if not
|
|
provided, then the daemon will generate a new cipher seed for the user.
|
|
Otherwise, then the daemon will attempt to recover the wallet state linked
|
|
to this cipher seed.
|
|
*/
|
|
repeated string cipher_seed_mnemonic = 1;
|
|
|
|
/*
|
|
enciphered_seed are the raw aezeed cipher seed bytes. This is the raw
|
|
cipher text before run through our mnemonic encoding scheme.
|
|
*/
|
|
bytes enciphered_seed = 2;
|
|
}
|
|
|
|
message InitWalletRequest {
|
|
/*
|
|
wallet_password is the passphrase that should be used to encrypt the
|
|
wallet. This MUST be at least 8 chars in length. After creation, this
|
|
password is required to unlock the daemon. When using REST, this field
|
|
must be encoded as base64.
|
|
*/
|
|
bytes wallet_password = 1;
|
|
|
|
/*
|
|
cipher_seed_mnemonic is a 24-word mnemonic that encodes a prior aezeed
|
|
cipher seed obtained by the user. This may have been generated by the
|
|
GenSeed method, or be an existing seed.
|
|
*/
|
|
repeated string cipher_seed_mnemonic = 2;
|
|
|
|
/*
|
|
aezeed_passphrase is an optional user provided passphrase that will be used
|
|
to encrypt the generated aezeed cipher seed. When using REST, this field
|
|
must be encoded as base64.
|
|
*/
|
|
bytes aezeed_passphrase = 3;
|
|
|
|
/*
|
|
recovery_window is an optional argument specifying the address lookahead
|
|
when restoring a wallet seed. The recovery window applies to each
|
|
individual branch of the BIP44 derivation paths. Supplying a recovery
|
|
window of zero indicates that no addresses should be recovered, such after
|
|
the first initialization of the wallet.
|
|
*/
|
|
int32 recovery_window = 4;
|
|
|
|
/*
|
|
channel_backups is an optional argument that allows clients to recover the
|
|
settled funds within a set of channels. This should be populated if the
|
|
user was unable to close out all channels and sweep funds before partial or
|
|
total data loss occurred. If specified, then after on-chain recovery of
|
|
funds, lnd begin to carry out the data loss recovery protocol in order to
|
|
recover the funds in each channel from a remote force closed transaction.
|
|
*/
|
|
ChanBackupSnapshot channel_backups = 5;
|
|
|
|
/*
|
|
stateless_init is an optional argument instructing the daemon NOT to create
|
|
any *.macaroon files in its filesystem. If this parameter is set, then the
|
|
admin macaroon returned in the response MUST be stored by the caller of the
|
|
RPC as otherwise all access to the daemon will be lost!
|
|
*/
|
|
bool stateless_init = 6;
|
|
}
|
|
message InitWalletResponse {
|
|
/*
|
|
The binary serialized admin macaroon that can be used to access the daemon
|
|
after creating the wallet. If the stateless_init parameter was set to true,
|
|
this is the ONLY copy of the macaroon and MUST be stored safely by the
|
|
caller. Otherwise a copy of this macaroon is also persisted on disk by the
|
|
daemon, together with other macaroon files.
|
|
*/
|
|
bytes admin_macaroon = 1;
|
|
}
|
|
|
|
message UnlockWalletRequest {
|
|
/*
|
|
wallet_password should be the current valid passphrase for the daemon. This
|
|
will be required to decrypt on-disk material that the daemon requires to
|
|
function properly. When using REST, this field must be encoded as base64.
|
|
*/
|
|
bytes wallet_password = 1;
|
|
|
|
/*
|
|
recovery_window is an optional argument specifying the address lookahead
|
|
when restoring a wallet seed. The recovery window applies to each
|
|
individual branch of the BIP44 derivation paths. Supplying a recovery
|
|
window of zero indicates that no addresses should be recovered, such after
|
|
the first initialization of the wallet.
|
|
*/
|
|
int32 recovery_window = 2;
|
|
|
|
/*
|
|
channel_backups is an optional argument that allows clients to recover the
|
|
settled funds within a set of channels. This should be populated if the
|
|
user was unable to close out all channels and sweep funds before partial or
|
|
total data loss occurred. If specified, then after on-chain recovery of
|
|
funds, lnd begin to carry out the data loss recovery protocol in order to
|
|
recover the funds in each channel from a remote force closed transaction.
|
|
*/
|
|
ChanBackupSnapshot channel_backups = 3;
|
|
|
|
/*
|
|
stateless_init is an optional argument instructing the daemon NOT to create
|
|
any *.macaroon files in its file system.
|
|
*/
|
|
bool stateless_init = 4;
|
|
}
|
|
message UnlockWalletResponse {
|
|
}
|
|
|
|
message ChangePasswordRequest {
|
|
/*
|
|
current_password should be the current valid passphrase used to unlock the
|
|
daemon. When using REST, this field must be encoded as base64.
|
|
*/
|
|
bytes current_password = 1;
|
|
|
|
/*
|
|
new_password should be the new passphrase that will be needed to unlock the
|
|
daemon. When using REST, this field must be encoded as base64.
|
|
*/
|
|
bytes new_password = 2;
|
|
|
|
/*
|
|
stateless_init is an optional argument instructing the daemon NOT to create
|
|
any *.macaroon files in its filesystem. If this parameter is set, then the
|
|
admin macaroon returned in the response MUST be stored by the caller of the
|
|
RPC as otherwise all access to the daemon will be lost!
|
|
*/
|
|
bool stateless_init = 3;
|
|
|
|
/*
|
|
new_macaroon_root_key is an optional argument instructing the daemon to
|
|
rotate the macaroon root key when set to true. This will invalidate all
|
|
previously generated macaroons.
|
|
*/
|
|
bool new_macaroon_root_key = 4;
|
|
}
|
|
message ChangePasswordResponse {
|
|
/*
|
|
The binary serialized admin macaroon that can be used to access the daemon
|
|
after rotating the macaroon root key. If both the stateless_init and
|
|
new_macaroon_root_key parameter were set to true, this is the ONLY copy of
|
|
the macaroon that was created from the new root key and MUST be stored
|
|
safely by the caller. Otherwise a copy of this macaroon is also persisted on
|
|
disk by the daemon, together with other macaroon files.
|
|
*/
|
|
bytes admin_macaroon = 1;
|
|
}
|