Macaroons are a modern form of bearer tokens. Offering a unique set of features. They have become a crucial part of the decentralized systems, particularly in Lightning Labs products. In this article, we’ll equip you with a thorough understanding of these innovative authentication solutions.
What are Macaroons?
In digital security, Macaroons are a modern kind of bearer token, similar to cookies or access tokens used in web applications, but with a few significant distinctions that make them powerful and flexible. Macaroons, for instance, allow for verification without needing to access a centralized database.
Macaroons were developed by researchers at Google as a new form of authorization credential, providing an innovative way to handle permissions and rights within a system. They’re specially designed to handle the complex situations that arise in distributed systems, like those in the Lightning Network.
But how do they differ from traditional tokens? Macaroons offer a set of features that includes:
- Caveats: These are conditions or constraints that can be embedded into the macaroon. For instance, you could add a caveat that restricts usage to a specific time window or mandates the presence of certain identifying information.
- Delegation: Macaroons can be securely delegated, enabling the holder to pass on limited rights to others without contacting the issuing authority. This is useful in complex systems where a user might need to delegate some of their access rights to another user.
- Attenuation: The concept of attenuation allows the rights given by a macaroon to be narrowed or limited further. Once a macaroon is created, its permissions can only be reduced, not increased.
Today, Macaroons are widely used in Lightning Labs products. They form the basis of L402, used by Lightning Pool and Lightning Loop to authenticate users, alongside preimages obtained through Lightning Network payments.
How do They Work?
Macaroons work on a simple principle: they carry their restrictions with them. These restrictions, or caveats, define the conditions under which the macaroon is valid. This could be anything from time limits to the need for a particular signature.
When a server issues a macaroon, it begins with an identifier and a secret. The secret, known only to the server, creates a signature for the macaroon. Any additional caveats are appended to the macaroon and included in the updated signature.
Here’s where it gets really interesting. If clients want to delegate their permissions to another user, they can add caveats to the macaroon. However, they don’t need to know the original secret used to create the macaroon. Instead, they derive a new secret from the existing macaroon’s secret and update the signature. This way, the client can’t increase the permissions of the macaroon; they can only add more restrictions, a process known as attenuation.
Third-party caveats can also be incorporated into Macaroons. These require interaction with a third party to obtain an additional secret to complete the Macaroon. A notable example is Lightning API Credentials (L402s), which enable the creation of Macaroons that are only complete upon the payment of an attached Lightning Network invoice.
Using Macaroons
Macaroons are extensively used by the Lightning Network Daemon (lnd) and Lightning Network command line interface (lncli). Upon startup, lnd checks if the admin.macaroon, readonly.macaroon, and invoice.macaroon files exist. If not, lnd updates its database with a new Macaroon ID and generates these three files, all sharing the same ID.
Different levels of access can be obtained with these Macaroons. The readonly.macaroon file includes a caveat restricting the caller from using only read-only methods, while the invoice.macaroon restricts the caller to using only invoice-related methods.
Further customization is available through lnd’s Macaroon bakery, accessible via gRPC and the command line. Users can bake their Macaroons with custom permissions if the default Macaroons (admin, invoice, and read-only) don’t suffice.
Macaroons offer an innovative and secure authentication solution for distributed systems like Bitcoin and the Lightning Network. Their ability to carry their permissions and be amended with user-defined restrictions empowers users and aligns with the principles of decentralization. Macaroons may seem simple and sweet, but they offer a rich and complex flavor once you dig in.
Accessing Your Voltage Node’s Macaroons
If you need to access your voltage node’s macaroons, you can find them in the “Connect” menu in the node dashboard. You can find additional information in our documentation.
Create your own node below. Also, enjoy exploring our LSP Flow or start using our time series data tool Surge.
