doc: describe macaroon bakery

This commit is contained in:
Oliver Gugger 2019-11-04 14:54:44 +01:00
parent 083b574fd8
commit ae04bdb98a
No known key found for this signature in database
GPG Key ID: 8E4256593F177720
2 changed files with 32 additions and 2 deletions

@ -119,6 +119,11 @@ A very simple example using `curl` may look something like this:
Have a look at the [Java GRPC example](/docs/grpc/java.md) for programmatic usage details. Have a look at the [Java GRPC example](/docs/grpc/java.md) for programmatic usage details.
## Creating macaroons with custom permissions
The macaroon bakery is described in more detail in the
[README in the macaroons package](../macaroons/README.md).
## Future improvements to the `lnd` macaroon implementation ## Future improvements to the `lnd` macaroon implementation
The existing macaroon implementation in `lnd` and `lncli` lays the groundwork The existing macaroon implementation in `lnd` and `lncli` lays the groundwork
@ -131,8 +136,6 @@ such as:
* Root key rotation and possibly macaroon invalidation/rotation * Root key rotation and possibly macaroon invalidation/rotation
* Tools to allow you to easily delegate macaroons in more flexible ways
* Additional restrictions, such as limiting payments to use (or not use) * Additional restrictions, such as limiting payments to use (or not use)
specific routes, channels, nodes, etc. specific routes, channels, nodes, etc.

@ -87,3 +87,30 @@ be found in `constraints.go`:
* `IPLockConstraint`: Locks the macaroon to a specific IP address. * `IPLockConstraint`: Locks the macaroon to a specific IP address.
This constraint can be set by adding the parameter `--macaroonip a.b.c.d` to This constraint can be set by adding the parameter `--macaroonip a.b.c.d` to
the `lncli` command. the `lncli` command.
## Bakery
As of lnd `v0.9.0-beta` there is a macaroon bakery available through gRPC and
command line.
Users can create their own macaroons with custom permissions if the provided
default macaroons (`admin`, `invoice` and `readonly`) are not sufficient.
For example, a macaroon that is only allowed to manage peers would be created
with the following command:
`lncli bakemacaroon peers:read peers:write`
A full and up-to-date list of available entity/action pairs can be found by
looking at the `rpcserver.go` in the root folder of the project.
### Upgrading from v0.8.0-beta or earlier
Users upgrading from a version prior to `v0.9.0-beta` might get a `permission
denied ` error when trying to use the `lncli bakemacaroon` command.
This is because the bakery requires a new permission (`macaroon/generate`) to
access.
Users can obtain a new `admin.macaroon` that contains this permission by
removing all three default macaroons (`admin.macaroon`, `invoice.macaroon` and
`readonly.macaroon`, **NOT** the `macaroons.db`!) from their
`data/chain/<chain>/<network>/` directory inside the lnd data directory and
restarting lnd.