Earlier this year, I embarked on a deep dive into how 1Password works. In particular, I wanted to understand what could happen if an attacker managed to collect a user’s Master Password – how hard would it then be to get all their passwords?

As part of this quest, I’ve explored the 1Password vault structure, read their security white papers, asked for help from engineers in their support forum, and written multiple tools to Read All The Passwords.

The 1Password service is available in so many flavors that it’s impossible to do every aspect of the ecosystem justice. Native clients exist for macOS, Windows, iOS, and Android. There are browser-based clients. We have browser extensions and mini clients. Shared vaults in the cloud. Private vaults (which can also be synced over things like Dropbox). There’s even an official command-line interface.

Fortunately, AgileBits (the creators of 1Password) are very open as to how their systems work. Their “1Password for Teams” whitepaper is an essential resource for understanding the product, and ultimately, what risks it may present to an organization. But the documentation is by no means complete. I’ve had to dig, experiment, and frequently, cajole AgileBits support and engineers, until I really understood how things work. And so now I’m here to try and share that information.

Why bother?

Why do I need to do this, if AgileBits has done such a good job? First, because they are still missing fairly important details here and there. But mostly, because I think it’s important to verify. I personally don’t feel I’ve understood how something works until I’ve written my own tool to demonstrate it. And understanding how things work is vital to understanding whether to trust them. What risks does something present to an organization (or family?) Under what circumstances can the service be breached? How do we prevent that, or at least mitigate it?

Ultimately, many of the things we use on a daily basis are just “Black Boxes” that we’re asked to trust. This is my small effort to further the implied “…but verify” step of trusting these tools.

Full disclosure: I’ve been a very happy 1Password user for years – since at least 2009. So take any “this is the best thing ever!” comments that creep into this with a grain of salt. I’ve toyed with some other tools here and there, but never seriously investigated any of them because I’ve always been happy with how 1Password works. This isn’t meant to be an unbiased product review – this is a tech-geek exploration of fun crypto-things. So hopefully any biases won’t matter much anyway.

A note on technical details

The goal of this series is to help explain how 1Password works, with enough detail that the reader (if they’re so inclined) can actually build their own client to verify that it’s working as we expect. I devote a whole lot of bits to showing detailed cryptographic computations – hex dumps of keys, ciphertexts, HMAC tags, and so forth, with lots of intermediate results. I don’t really expect those to be terribly clear as text, but they should help you if you’re trying to build your own system. So don’t despair when you see a screen full of binary data – just skim through those and come back to them whenever you’re trying to debug your own tools.


So here we go – let’s explore how the thing works. But note that despite what I may have just said about filling in the gaps, this still won’t be 100% comprehensive. It’s going to be somewhat focused on the things that I personally find most interesting – the cryptography underpinning the system. I’ll talk a little bit about some of the network protocols and some other bits and pieces, but really, this is all about me trying to take a string of unintelligible encrypted bits and turn them back into a readable password. So client-server traffic won’t really be explored.

I’m also not comparing 1Password to other password managers. I know there are a lot of choices out there, and some of them are pretty good. I use and like 1Password, and so that’s the system I explored.

Bits of this have also been presented in different venues, including at NoVAHackers in May 2018, as an internal “Lunch and Learn” at Expel, and at BSides Delaware in November 2018. Slides from the last (the most polished of the three) are available here.

As I said, there’s a lot to talk about, far too much for one post. So instead, I’ll be writing this as a series of posts. We’ll begin with unlocking the Mac client. You can list the entire series by clicking here.