Crate macarunes

source ·
Expand description


This library provides an implementation of Macaroons. For an introduction to macaroons, check out the paper, or the Python README.


  • We rely upon the type system to provide memory safety. Secrets are scrubbed after use, but there’s no guarantee the linker won’t optimize away such code. Until an end-to-end solution emerges in the Rust compiler, it won’t be possible to guarantee secrets don’t leak in the presence of memory vulnerability.

  • This library relies upon the determinism of the protocol buffers code. This is guaranteed by prototk.

  • Intentionally restrictive language compared to the Python implementation. The only cases you need in the core library are to make exact comparisons (which are born out as format strings), to set an expiration, or to use a third-party caveat that enforces some arbitrary predicate before the discharge macaroon is granted.

Third-Party Macaroons

This is the algorithm for satisfying third-party secrets:

  1. Obtain signature from the macaroon to which we want to add a third-party caveat.
  2. Make an RPC to the third-party that exchanges signature for a ThirdPartySecret.
  3. Call Macaroon.add_third_party(location, identifier, third_party_secret).

About Locations

A location is a hint that is not part of the macaroons’s signature. The library does this intentionally as the paper suggests that only keys speak.

For that reason, locations should be treated as hints that give a plain-text description of how to use the endpoint. The location in the macaroon is not the endpoint for discharge; it’s a opaque identifier that the RequestBuilder will iterate over.

For each third party, a Loader should be developed that negotiates the protocol to get discharge macaroons. A location that’s not known to a client cannot be trusted. Given that we have to trust servers that give us macaroons, this is not a compromise or limitation.


Active development.


This library should provide a verifier and a client-side library.


  • This library is under-used and will see active development in the future.


The latest documentation is always available at


  • A Macaroon has a location, identifier, signature, and caveats.
  • RequestBuilder handles assembly of requests, picking the minimal set of discharge macaroons.
  • A Secret holds SIGNATURE_BYTES that will be scrubbed at the end of its lifetime.
  • A third party secret. It is intended that this be generated by the server that holds a secret for discharge macaroons.
  • Verifier implements the servers-side portion of macaroons. Note that the caveats we’ve chosen require very little logic from the server.


  • The error cases macarunes can encounter.