Macaroons are Beautiful, and Easy to Understand!

Sometimes I hear that macaroons are confusing and that bums me out as I find them to be so elegant and simple. So let me see if I can effectively communicate how beautiful this little piece of tech is…

Let’s imagine that you have a server that has some data to serve up and you want to gate your content and perhaps charge for it.

Step one, create a secret. Here we’ll use just the word “secreto”, which is of course “secret” in Spanish. The tricky part for you is that you have to know what a hash function is, and the tricky part for your server is that it has to hold on to and protect this secret.

Now perhaps you want to give your users ID’s. Something complex and official looking like “id12345678id”. To make a very simple macaroon for your user you simple hash “secreto” together with that ID “id12345678id”. You can try this yourself on the command line if you like.

$ echo “secreto;id12345678id” | sha256sum

The result is:

55413cca2fbc3a31f5ef5ab7b18390c926dd7f9d466034ea8ec2a0867e19e26d

And congratulations you created a macaroon! (Kinda)

You then hand your user this data:

id12345678id 55413cca2fbc3a31f5ef5ab7b18390c926dd7f9d466034ea8ec2a0867e19e26d

You don’t have to hold on to any data at all besides that secret. You can hold on to that ID data if you like, but tomorrow when the holder of this macaroon shows back up to access your services, how can you validate them?

Very simply as you know the secret! You take that ID “id12345678id” and hash it together with your secret

$ echo “secreto;id12345678id” | sha256sum

To see if you get the hash that they showed up with:

55413cca2fbc3a31f5ef5ab7b18390c926dd7f9d466034ea8ec2a0867e19e26d

If you do, then you know that your server created that macaroon and you can let them right in. Easy peasy lemon squeezy.

Well, ackchyually…

What I’ve described above is really more of an HMAC(Hash-based Message Authentication Code) than a macaroon. What macroons are really for is chaining hashes and adding attenuations. So let’s add in one more step.

You don’t want this user to have access to your server forever, so you want to add an expiration date to this authentication token. Let’s say April 27th 2027. So let’s add that to our HMAC thus turning it into a proper macaroon!

Right now we have:

id12345678id 55413cca2fbc3a31f5ef5ab7b18390c926dd7f9d466034ea8ec2a0867e19e26d

How do we add our new attenuation? With another hash of course!!! We take our existing hash, and hash it with our new data, “expires:2027–04–27”.

$ echo “55413cca2fbc3a31f5ef5ab7b18390c926dd7f9d466034ea8ec2a0867e19e26d;expires:2027–04–27” | sha256sum

We now have a new hash!

bf41dee1dacfe63e1d917c46d024e6ceb13506632e092fa218bd96df041f7b0e

This is now the macaroon that we give our user:

id12345678id
expires:2027–04–27 bf41dee1dacfe63e1d917c46d024e6ceb13506632e092fa218bd96df041f7b0e

And still, only we know the secret. And so, this user can’t change this macaroon as doing so would alter that hash thus making our validation of it fail.

So how can we validate it? Also, very, very simply with just that secret and a few hash functions!

As we have the secret, all we need to do is recreate the macaroon and see if we get the final hash that the user showed up with. Hash together the secret with the ID. Take that result and hash it together with the expiration data. If the result is the same hash as the user presented to us then we know that macaroon was created using our secret. So either someone has stolen our secret, or we created that macaroon!

Don’t trust, verify. Try it yourself on your machine.

$ echo “secreto;id12345678id” | sha256sum

This produces:

55413cca2fbc3a31f5ef5ab7b18390c926dd7f9d466034ea8ec2a0867e19e26d

Then…

$ echo “55413cca2fbc3a31f5ef5ab7b18390c926dd7f9d466034ea8ec2a0867e19e26d;expires:2027–04–27” | sha256sum

Which produces:

bf41dee1dacfe63e1d917c46d024e6ceb13506632e092fa218bd96df041f7b0e

The hashes match, authentication complete!

…one more ackchyually. A real HMAC function is slightly more complicated than demonstrated above. HMAC functions handle the data more carefully than just taking a string, and there lots of details in formatting, and there are details on how third party caveats are added, etc.

However, if you’ve made it this far, congratulations, you understand macaroons!