lnd0.3-alpha release, we have addressed issue 20, which is RPC authentication. Until this was implemented, all RPC calls to
lndwere unauthenticated. To fix this, we've utilized macaroons, which are similar to cookies but more capable. This brief overview explains, at a basic level, how they work, how we use them for
lndauthentication, and our future plans.
lncli) can send to a service (like
lnd) to assert that it's allowed to perform an action. The service looks up the macaroon ID and verifies that the macaroon was initially signed with the service's root key. However, unlike a cookie, you can delegate a macaroon, or create a version of it that has more limited capabilities, and then send it to someone else to use.
lnd) to do anything permitted by the macaroon. There is a specific type of restriction, called a "third party caveat," that requires an external service to verify the request; however,
lnddoesn't currently implement those.
lndin an interesting way. By default, when
lndstarts, it creates three files which contain macaroons: a file called
admin.macaroon, which contains a macaroon with no caveats, a file called
readonly.macaroon, which is the same macaroon but with an additional caveat, that permits only methods that don't change the state of
invoice.macaroon, which only has access to invoice related methods.
lndchecks to see if the
invoice.macaroonfiles exist. If they don't exist,
lndupdates its database with a new macaroon ID, generates the three files
invoice.macaroon, all with the same ID. The
readonly.macaroonfile has an additional caveat which restricts the caller to using only read-only methods and the
invoice.macaroonalso has an additional caveat which restricts the caller to using only invoice related methods. This means a few important things:
admin.macaroonand be left with only the
readonly.macaroon, which can sometimes be useful (for example, if you want your
lndinstance to run in autopilot mode and don't want to accidentally change its state).
macaroons.dbfile, this invalidates the
invoice.macaroonfiles. Invalid macaroon files give you errors like
cannot get macaroon: root key with id 0 doesn't existor
verification failed: signature mismatch after caveat verification.
--no-macaroonsoption, which skips the creation of the macaroon files and all macaroon checks within the RPC server. This means you can still pass a macaroon to the RPC server with a client, but it won't be checked for validity. Note that disabling authentication of a server that's listening on a public interface is not allowed. This means the
--no-macaroonsoption is only permitted when the RPC server is in a private network. In CIDR notation, the following IPs are considered private,
lndrequires macaroons by default in order to call RPC methods,
lnclinow reads a macaroon and provides it in the RPC call. Unless the path is changed by the
lnclitries to read the macaroon from the network directory of
lnd's currently active network (e.g. for simnet
lnddir/data/chain/bitcoin/simnet/admin.macaroon) by default and will error if that file doesn't exist unless provided the
--no-macaroonsoption. Keep this in mind when running
lncliwill error out unless called the same way or
lndhas generated a macaroon on a previous run without this option.
lnclialso adds a caveat which makes it valid for only 60 seconds by default to help prevent replay in case the macaroon is somehow intercepted in transmission. This is unlikely with TLS, but can happen e.g. when using a PKI and network setup which allows inspection of encrypted traffic, and an attacker gets access to the traffic logs after interception. The default 60 second timeout can be changed with the
--macaroontimeoutoption; this can be increased for making RPC calls between systems whose clocks are more than 60s apart.
lndcreates several macaroon files in its directory. These are unencrypted and in case of the
admin.macaroonprovide full access to the daemon. This can be seen as quite a big security risk if the
lnddaemon runs in an environment that is not fully trusted.
lndsupports the so called
--stateless_initthat instructs the daemon not
changepasswordthat actually create/update
lncliare not used on the same machine, this
changepasswordcommand still remain valid. If a user wants to
changepasswordcommand should be used!
lncliwill see the returned admin macaroon printed to the screen
lndwill create the macaroon files during the
unlockphase, if the
--stateless_initflag is not used. So to avoid
lndusing the GRPC interface, the macaroons are encoded as a hex string over the wire and can be passed to
lndby specifying the hex-encoded macaroon as GRPC metadata:
<macaroon>is the hex encoded binary data from the macaroon file itself.
curlmay look something like this:
lnclilays the groundwork for future improvements in functionality and security. We will add features such as:
lndact almost like a bank for apps: for example, an app that pays to consume APIs whose budget is limited to the money it receives by providing an API/service
lnd. We look forward to expanding its functionality to make it easy to develop secure apps.