akovalenko/lnd.xprv
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

docs: describe stateless wallet initialization

Browse Source
This commit is contained in:
Oliver Gugger 2020-10-06 17:23:41 +02:00
parent 24adf475ce
commit 0b9b7def15
No known key found for this signature in database
GPG Key ID: 8E4256593F177720
1 changed files with 43 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
docs/macaroons.md
View File

@ -109,6 +109,49 @@ timeout can be changed with the `--macaroontimeout` option; this can be
increased for making RPC calls between systems whose clocks are more than 60s
apart.
## Stateless initialization
As mentioned above, by default `lnd` creates several macaroon files in its
directory. These are unencrypted and in case of the `admin.macaroon` provide
full access to the daemon. This can be seen as quite a big security risk if
the `lnd` daemon runs in an environment that is not fully trusted.
The macaroon files are the only files with highly sensitive information that
are not encrypted (unlike the wallet file and the macaroon database file that
contains the [root key](../macaroons/README.md), these are always encrypted,
even if no password is used).
To avoid leaking the macaroon information, `lnd` supports the so called
`stateless initialization` mode:
* The three startup commands `create`, `unlock` and `changepassword` of `lncli`
all have a flag called `--stateless_init` that instructs the daemon **not**
to create `*.macaroon` files.
* The two operations `create` and `changepassword` that actually create/update
the macaroon database will return the admin macaroon in the RPC call.
Assuming the daemon and the `lncli` are not used on the same machine, this
will leave no unencrypted information on the machine where `lnd` runs on.
* To be more precise: By default, when using the `changepassword` command, the
macaroon root key in the macaroon DB is just re-encrypted with the new
password. But the key remains the same and therefore the macaroons issued
before the `changepassword` command still remain valid. If a user wants to
invalidate all previously created macaroons, the `--new_mac_root_key` flag
of the `changepassword` command should be used!
* An user of `lncli` will see the returned admin macaroon printed to the screen
or saved to a file if the parameter `--save_to=some_file.macaroon` is used.
* **Important:** By default, `lnd` will create the macaroon files during the
`unlock` phase, if the `--stateless_init` flag is not used. So to avoid
leakage of the macaroon information, use the stateless initialization flag
for all three startup commands of the wallet unlocker service!
Examples:
* Create a new wallet stateless (first run):
* `lncli create --stateless_init --save_to=/safe/location/admin.macaroon`
* Unlock a wallet that has previously been initialized stateless:
* `lncli unlock --stateless_init`
* Use the created macaroon:
* `lncli --macaroonpath=/safe/location/admin.macaroon getinfo`
## Using Macaroons with GRPC clients
When interacting with `lnd` using the GRPC interface, the macaroons are encoded