This post is part of a series on my pet projects that I’ve worked on over the years and I feel would be nice to showcase. So if you like this idea, make sure to check out my Atari 2600 emulator from my previous post!
I’ve been using password managers for many years, trusting them with literally everything: from my bank accounts to my inbox; my entire digital life actually. And since you’re reading this, you probably do too.
From the moment I started using a password manager, I wondered: how does this actually work? Why is this secure, is this secure? I pieced together a pretty firm idea of how things must work under the hood. And as it turns out, I wasn’t too far off.
But there’s a difference between having a mental model and really understanding something. For me, the best way to bridge such a gap is to build it. So I created a fully 1Password-compatible TypeScript library and turned it into an interactive explainer. I'm a web developer, not a cryptographer, but the implementation works with real 1Password data, which means I must have understood something 😅
Let me walk you through the process, using the credentials of the one and only legendary actor and director Tommy Wiseau, an avid 1Password user and ambassador himself!
Protecting Tommy Wiseau’s scripts and your passwords
Imagine you’re the Tommy Wiseau: you’re between takes on your latest project, and you need to access your script notes. But here’s the thing: you can’t afford to have your scripts leaked. Your creative process is unique. Your dialogue is distinctive. One leak and the internet would have a field day.
Tommy Wiseau famously starred in the Stopping Bad Actors commercial for 1Password, check it out!
So, naturally, you use a password manager, 1Password in particular. But how does 1Password actually protect Tommy’s precious scripts? How does it keep his passwords secure even from 1Password themselves? Let’s find out.
The Journey: from curiosity to code
It started with a simple question: "how does 1Password encrypt my data so securely that even they can't access it?"
Tommy's passwords are stored on 1Password's servers, but they claim they can't decrypt his vault even if they wanted to. How does that work? What's stopping a rogue employee from accessing his script for "The Room 2"? (hey, one can dream)
I found my answer in 1Password's Security Design white paper. It's an excellent read and it's pretty palatable, much more so than I expected beforehand. A recommended read for sure!
But understanding theory is one thing. I wanted to implement it. Because for me, the best way to truly understand something is to build it. So I set out to create a TypeScript library that implements 1Password's security model, which is capable of decrypting actual 1Password vault data; if my implementation couldn't handle the real thing, how would I know I truly understood it?
A pleasant surprise: the Web Crypto API, SubtleCrypto in particular, handles all the heavy lifting. PBKDF2, AES-256-GCM, RSA-OAEP, it's all built into every modern browser. No external crypto libraries needed.
And so I verified it can process actual 1Password data
To verify full compatibility, I created a test account, intercepted the encrypted data using Burp Suite and the 1Password Session Analyzer plugin to strip away the in-transit encryption 1Password layers on top of TLS, and wrote a test that decrypts it using my library. The test passes, because the implementation is byte-for-byte compatible with 1Password's production encryption. Pretty cool, right?
"But I don't want to look at code, just explain it to me"
Fair enough, let's step through the process of what happens when Tommy unlocks his 1Password vault.
1. Account Password + Secret Key = Account Unlock Key (AUK)
Tommy's password and his Secret Key are combined using PBKDF2 (650,000 iterations), plus some salts here and there, to create the AUK. Which is an intentionally expensive operation, happening once per session. It keeps brute-force attacks at bay.
2. AUK decrypts a keyset's Symmetric Key
The AUK unlocks a fast AES-256-GCM symmetric key. This key protects Tommy's RSA private key, while also making it easy to change the Account Password or Secret Key: only the Keyset Access Key needs to be re-encrypted with the new AUK. Everything downstream stays untouched. No need to re-encrypt your entire account.
3. Symmetric Key decrypts RSA Private Key
The symmetric key unlocks Tommy's RSA private key. Together with the public key, this keypair can decrypt his vault-specific keys without exposing his Account Password.
4. RSA Keypair decrypts Vault Keys, which encrypt Tommy's Data
Each of Tommy's vaults has its own AES-256-GCM key, encrypted by his RSA public key. These vault keys finally decrypt his actual passwords and data, including those precious script notes.
Here's what this looks like in the actual, albeit simplified, response from 1Password's servers:
{
"uuid": "rv4ge63poeyompbhty2efk5xxi",
"encryptedBy": "mp", // mp / auk
// Layer 2: Symmetric key (encrypted by AUK)
"encSymKey": {
"alg": "PBES2g-HS256",
"data": "xKj4pR0Ws-FyikpQGSxGk...", // Encrypted symmetric key
"p2c": 650000 // PBKDF2 iterations
// ...
},
// Layer 3: RSA private key (encrypted by symmetric key)
"encPriKey": {
"data": "UN1mx3kJh_Qeqdyt-7Jvq...", // Encrypted private key
"kid": "rv4ge63poeyompbhty2efk5xxi",
// ...
},
// Layer 3: RSA public key (unencrypted)
"pubKey": {
"alg": "RSA-OAEP",
"n": "rwVd9EM4bEwLAI4QWzJhq...",
// ...
}
}
Why four layers?
- PBKDF2 is slow by design which adds protection against brute force
- Symmetric crypto is fast, perfect for protecting the larger RSA private key
- RSA enables sharing: vaults can be shared without sending Vault Passwords in plaintext or revealing your Account Password
- Per-vault keys mean compromising one vault doesn't compromise others -** Rolling Account Credentials is simple** only the Keyset Access Key needs to be re-encrypted with the new AUK
Try It Yourself
Want to see this encryption chain in action? Head over to my interactive 1Password explainer. You'll see each layer of the encryption process unfold step by step.
That's Encryption, Baby!
Building this TypeScript implementation helped me understand why each layer exists. PBKDF2 slows down attackers. Symmetric crypto protects your private key efficiently. RSA enables secure sharing. Per-vault keys contain breaches. Seeing how these pieces fit together and getting it to work with real 1Password data, turned abstract concepts into some pretty thorough understanding.
If you're curious about the implementation details or want to integrate 1Password vault decryption into your own projects, the full TypeScript library is available at https://github.com/edeckers/lib1password-unofficial. It's fully compatible with real 1Password data, just don't use it in production, and obviously don't trust a library by some internet stranger like myself with your actual credentials and secrets.
For a deeper dive into 1Password's security model, particularly how it works in local client applications, David Schuetz's deep dive series is an excellent resource that goes into even more technical detail. Fun fact: I found his series because I encountered the string "Obfuscation Does Not Provide Security But It Doesn't Hurt" (pretty funny, I think) in the source of the 1Password site, and Googling it, his site was the only hit. He touches on it briefly :)
Did this post spark your curiosity about cryptography or password security? Are you working on similar projects, or do you have questions about the implementation? Let me know in the comments!
If the Dutch language doesn't scare you, and you'd like to know more about what keeps me busy aside from my pet projects, check my company website branie.it! Maybe we can work together on something someday :)
Top comments (0)