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! 🥳