← blog

Understanding Zero-Knowledge Password Managers

alt text

At this point you may have used password managers to store your credentials or atleast heard about them, but have you stopped and wondered how they work under the hood? How they store your data so that even in the case of leaked or stolen database your credentials are safe?

This is where the idea of zero knowledge comes into play.

When a password manager describes itself as zero-knoledge, it essentialy means that its servers cannot access the actual contents of your stored credentials. Your data is encrypted on your device before it is sent to the server. The server may know the metadata attached with the stored object like when its created or updated, but it cannot read the plaintext contents of your vault.

In this post we are gonna explore how this works under the hood by looking at one approach to client-side encryption. We will use a similer method employed by bitwarden and understand it.

Note

Before we move any further, let’s talk about the implementation approach we’ll be following.

All encryption and decryption operations happen on the client side. For this post, however, we’ll implement these operations using Go (Golang).

Go can be compiled to WebAssembly (Wasm), allowing it to run in the browser. This gives us a convenient way to write our cryptographic implementation in Go while still running it on the client side.

Bitwarden follows a similar approach, using Rust for its cryptographic implementation and compiling relevant parts to WebAssembly.

For simplicity, all code examples in this post will be written and executed directly in Go. We’ll leave WebAssembly integration out of scope for now.

The snippets may be missing some definations which I have left out here in the post but can be found in the repo linked at the end

Key derivation

Let’s start with one of the core building blocks of a password manager: key derivation.

You may be wondering, what exactly is key derivation here?

A password manager uses your master password, the one password you should actually remember.

Yes, I have been a victim of forgetting my master password and having to rebuild my entire password manager, because some password managers don’t offer a “Forgot password” option.

Your master password is the starting point for deriving the cryptographic keys used by the password manager. Rather than using the password directly, we pass it through a one-way password-hashing function called Argon2id.

Argon2id is a password-hashing algorithm designed to make guessing passwords expensive. It was selected as the winner of the Password Hashing Competition in 2015.

At its core, Argon2id is deterministic. This means that if you provide it with exactly the same inputs and settings, it will produce exactly the same output every time.

So, what does Argon2id need to do its job?

It takes your master password as input, along with a few parameters that control how the hashing process works:

And finally, we have one more important input: the salt.

A salt is a randomly generated sequence of bytes that is supplied alongside the password. It ensures that even if two users choose the same master password, they can still end up with different derived keys.

As long as the master password, salt, Key lenght and Argon2id parameters remain the same, the algorithm will produce the same output every time.

This is why a password manager following this design does not need to store your master password on its server. Instead, it stores the salt and the Argon2id parameters used during signup. These include the time cost, memory cost, and parallelism settings.

The salt is generated by the client during signup and sent to the server along with these parameters. When you log in again, the server provides the same salt and settings to the client. The client then uses them together with your master password to derive the same key as before.

For this post, we’ll use a 16-byte salt and a fixed output length of 32 bytes. Since the output length is fixed in our implementation, we don’t need to pass it around with the other KDF settings.

┌─────────────────┐
│ Master password │──┐
└─────────────────┘  │
┌─────────────────┐  │   ┌───────────┐   ┌────────────────────┐
│ 16-byte salt    │──┼──►│ Argon2id  │──►│ 32-byte master key │
└─────────────────┘  │   └───────────┘   └────────────────────┘
┌─────────────────┐  │
│ KDF settings    │──┘
└─────────────────┘
type KDFParams struct {
	Time        uint32
	MemoryKiB   uint32
	Parallelism uint8
}

const keyLen = 32

func DeriveKeys(password string, salt []byte, p KDFParams) (encKey, authKey []byte, err error) {
	if len(salt) < 16 {
		return nil, nil, errors.New("salt too short")
	}
	master := argon2.IDKey([]byte(password), salt, p.Time, p.MemoryKiB, p.Parallelism, keyLen)

    // We'll derive the encryption and authentication
    // keys from master using HKDF in the next step.
}

Deriving More Keys

Okay, now that we have our handy-dandy master key, we need to derive two more keys from it.

You may be wondering at this point: just how many keys are we going to derive and keep track of? Don’t worry about it. Let’s go one by one.

What we’re going to do next isn’t computationally intensive. We’re simply taking the master key we derived using Argon2id and using it to derive two more keys.

For this, we’ll use HKDF-SHA256. Unlike Argon2id, which is deliberately computationally expensive, HKDF is a lightweight key-derivation function. It allows us to derive multiple independent keys from a single input key.

The two keys we’ll derive are called the encryption key and the authentication key (auth key). Each serves a different purpose.

Encryption key

This is the key that will encrypt the key protecting your actual data. Yes, you read that right. This isn’t the key that directly encrypts your data. Instead, it’s the key that protects the key that encrypts your data.

Yeah, that’s a bit of a tongue twister, but that’s how it works!

The important thing to understand here is that your master password never gets anywhere near your database, nor is it directly used to encrypt your stored data. It is used to derive the master key, which in turn derives the encryption key. That encryption key will then protect another key, which we’ll look at later. And that other key is what actually encrypts your data.

Auth key

This is the key the server uses to authenticate you when you try to access your data.

During signup, the client sends the derived auth key to the server. However, the server doesn’t store the auth key itself. Instead, it calculates a hash of the received auth key and stores that hash in its database. This way, even if the database is leaked, the stored value doesn’t directly reveal the original auth key.

When you try to log in again, the same key derivation process happens on the client. Your master password is used to derive the master key, and the master key is then used to derive both the encryption key and the auth key.

The client sends the newly derived auth key to the server. The server hashes it and compares the result with the hash it stored during signup.

If both hashes match, the server knows that the client has supplied the expected auth key and can proceed with issuing the necessary tokens to access your stored data.

┌─────────────────────────────────────────────┐
│ 32-byte master key (Argon2id output)        │
└──────────────────────┬──────────────────────┘
                       │ HKDF-Expand
           ┌───────────┴───────────┐
           ▼                       ▼
┌─────────────────────┐ ┌─────────────────────┐
│ Encryption key      │ │ Auth key            │
│ (wraps vault key)   │ │ (sent to server)    │
└─────────────────────┘ └─────────────────────┘
func expand(master []byte, label string) ([]byte, error) {
	out := make([]byte, keyLen)
	_, err := io.ReadFull(hkdf.Expand(sha256.New, master, []byte(label)), out)
	return out, err
}

We’ll use the same Expand function to derive both the encryption key and the auth key from our master key.

You may wonder: hey, what is that label string over there? Why do we need it?

Well, this is where the difference between the two keys comes in.

If we use the same label for both keys, we’ll essentially derive the same output. Remember, HKDF is deterministic: the same input key and the same context produce the same output.

So, what we do is pass a different label for each key. For the first one, we’ll pass a context string saying, “this is an encryption key”. For the second one, we’ll pass another context string saying, “this is an authentication key”.

HKDF uses the master key along with this context string to derive the output. Since the context strings are different, the resulting keys are different too.

If you look up HKDF, you’ll see that it isn’t simply another hashing function. It’s designed to derive cryptographic keys from existing key material. Essentially, its job is to create new keys from an existing secret.

This is how we call it in from DeriveKeys

func DeriveKeys(password string, salt []byte, p KDFParams) (encKey, authKey []byte, err error) {
	if len(salt) < 16 {
		return nil, nil, errors.New("salt too short")
	}
	master := argon2.IDKey([]byte(password), salt, p.Time, p.MemoryKiB, p.Parallelism, keyLen)
	if encKey, err = expand(master, "vault/enc/v1"); err != nil {
		return nil, nil, err
	}
	if authKey, err = expand(master, "vault/auth/v1"); err != nil {
		return nil, nil, err
	}
	return encKey, authKey, err
}

Vault key

Yeah, I think this is the part we’ve all been waiting for!

I’ve been hyping up this one key for a while now, saying that this is the key that’s actually going to protect your data. So, how are we going to derive this key?

Simple. We’re going to generate a random 32-byte key.

Don’t scratch your head just yet. I know you might be thinking: wait a minute, this person has been saying that the server doesn’t store any of our secret values. Now he’s saying we’re going to use another random key. How does that even make sense?

Trust me, I went through the same confusion when I started learning about this. But it’s all going to make sense in a minute.

We’re going to generate this 32-byte random key on the client. This key is called the vault key, and it’s the key that will protect all your stored contents.

Whenever you upload a login item, this is the key that will be used to encrypt it. And whenever you want to retrieve that item, this is the same key that will be used to decrypt it.

We’ll get into the actual encryption and decryption process shortly, but for now, remember that this is the key that protects your data.

But how do we protect this key itself?

Remember the encryption key we derived in the previous section? That’s where it comes in. We’re going to use that encryption key to encrypt the vault key and send the encrypted version to the server.

Yes, read that carefully. The plaintext vault key never needs to leave your client. Only its encrypted version is sent to the server and stored there.

Moreover, we should never deliberately persist the plaintext vault key anywhere. It should remain in the client’s memory only. No local storage, no session storage, no cookies, and no other persistent browser storage.

When you need to access your data again, the client retrieves the encrypted vault key from the server and decrypts it using the encryption key we derived earlier.

And that’s how we can use a randomly generated key to protect all your stored contents without having to store that key in plaintext on the server.

You might still be wondering: why go through all this trouble? Why not just use the encryption key to encrypt our data directly?

Here’s the neat part. Because the vault key is random and only wrapped by the encryption key, changing your master password doesn’t mean re-encrypting your entire vault. The client simply derives a new encryption key from the new password, decrypts the vault key with the old one, encrypts it again with the new one, and sends the new encrypted vault key to the server. Your stored items stay exactly as they are, since they were never encrypted with your master password in the first place.

One important thing to remember: the plaintext vault key should be kept in memory only for as long as it’s needed. Once the user logs out or the session ends, the application should discard its in-memory reference to it.

func NewVaultKey() ([]byte, error) {
	k := make([]byte, keyLen)
	if _, err := rand.Read(k); err != nil {
		return nil, err
	}

	return k, nil
}

Encryption and Decryption

Now, let’s get into the encryption and decryption part.

For this post, we’ll use an encryption algorithm called AES-GCM.

Unlike Argon2id, which we discussed earlier, AES-GCM is a symmetric, two-way encryption algorithm. More precisely, it’s an authenticated encryption algorithm.

What does that mean?

If you provide it with a key, some plaintext, and a few additional parameters, it will encrypt the plaintext and give you an encrypted blob in return.

And if you provide that same blob with the correct key and parameters, you can decrypt it and get the exact original plaintext back.

This is quite different from Argon2id. Argon2id is a one-way password-hashing function. You cannot simply reverse its output to get the original password back. Of course, someone can still try guessing passwords and checking their derived outputs, which is why we use a deliberately expensive algorithm like Argon2id.

AES-GCM, on the other hand, is designed to let you recover your original data when you have the correct key and the required parameters. With a properly generated strong key, brute-forcing AES-256 is considered computationally infeasible.

For our password manager, AES-GCM will use a few important pieces of information.

  1. Nounce: A nonce is a number used once. In our implementation, we’ll generate a random 12-byte nonce for every encryption operation.

    This nonce is not secret, so we can safely store it alongside the encrypted data. However, it’s very important that we never reuse the same nonce with the same key. Reusing a nonce with AES-GCM can seriously compromise the security of the encryption.

  2. Version indicator: This helps us identify which encryption format or algorithm version was used to encrypt a particular blob. If we decide to change our encryption implementation in the future, this indicator can help us determine how to decrypt older stored data.

  3. AAD(Additional Authenticated Data): AAD is additional information that is authenticated during encryption, but it isn’t encrypted or stored inside the encrypted blob itself. Think of it as extra context associated with the data we’re encrypting.

    For example, when encrypting a login item, we can use its UUID as the AAD. This ties the encrypted data to that particular item.

Now, here’s where things get interesting.

AES-GCM generates something called an authentication tag. This tag is used to verify that the ciphertext and the supplied AAD haven’t been tampered with.

When we decrypt the data, we must provide the same AAD that was used during encryption. If the ciphertext has been modified, the AAD is different, or the wrong key is supplied, authentication fails and decryption returns an error.

So, even though the AAD isn’t stored inside the encrypted blob, it still plays an important role in protecting the integrity of our data.

Overall, the final encrypted output will look something like this:

[version][nonce][ciphertext][auth tag]

The version indicator and nonce are stored in plaintext, followed by the encrypted data and its authentication tag.

Let’s see how we can implement this in Go.

func Seal(key, plaintext []byte, aad []byte) ([]byte, error) {
    gcm, err := newGCM(key)
    if err != nil {
        return nil, err
    }

    out := make([]byte,
        1+gcm.NonceSize(),
        1+gcm.NonceSize()+len(plaintext)+gcm.Overhead(),
    )

    out[0] = blobV1

    nonce := out[1:]
    if _, err := rand.Read(nonce); err != nil {
        return nil, err
    }

    return gcm.Seal(out, nonce, plaintext, aad), nil
}

// Open reverses Seal. GCM authenticates the data,
// so a wrong key or tampered data returns an error.
func Open(key, blob []byte, aad []byte) ([]byte, error) {
    if len(blob) < 1 {
        return nil, ErrBlobTooShort
    }

    if blob[0] != blobV1 {
        return nil, ErrUnsupportedVersion
    }

    gcm, err := newGCM(key)
    if err != nil {
        return nil, err
    }

    minLen := 1 + gcm.NonceSize() + gcm.Overhead()
    if len(blob) < minLen {
        return nil, ErrBlobTooShort
    }

    nonce := blob[1 : 1+gcm.NonceSize()]
    ciphertext := blob[1+gcm.NonceSize():]

    return gcm.Open(nil, nonce, ciphertext, aad)
}

And with that our whole our vault key encryption will look like something below.

┌──────────────────────┐
│ Vault key (32 bytes) │──┐
└──────────────────────┘  │
┌──────────────────────┐  │   ┌──────────────┐   ┌─────────────────────┐
│ Encryption key       │──┼──►│ AES-256-GCM  │──►│ Encrypted vault key │
└──────────────────────┘  │   └──────────────┘   └─────────────────────┘
┌──────────────────────┐  │
│ AAD (context string) │──┘
└──────────────────────┘

Encrypted vault key, as stored:

┌─────────┬──────────┬────────────┬──────────┐
│ version │  nonce   │ ciphertext │ auth tag │
│ 1 byte  │ 12 bytes │            │ 16 bytes │
└─────────┴──────────┴────────────┴──────────┘

We then send over this word key to the server where it will be stored and send back to the user when they are properly authenticated.

Notice that we’re not sending the actual vault key to the server. Only its encrypted version leaves the client.

Storing login items

From this point onwards, things are not that different from what we’ve done so far.

The client collects the credentials or whatever information the user wants to store. It then serializes this information into a format such as JSON.

Next, the client passes this plaintext data to our already established encryption function, along with the vault key that is currently in memory. We also generate a unique ID for the login item, which we can use as the AAD during encryption.

The encryption function gives us an encrypted blob in return. This is what we send to the server for storage.

The server doesn’t need to know what’s inside that blob. It simply stores the item ID, revision information and encrypted data. When the user requests their stored items, the server sends the encrypted blobs back to the client, where they can be decrypted using the vault key.

For the context of this post, I’m not going to explain how the HTTP server works or how the requests and responses are handled. That’s a broader topic, and what we’re really interested in here is the encryption and decryption that happens on the client side.

Conclusion

And that’s essentially the basic idea behind a zero-knowledge password manager!

Of course, there’s more to building a secure password manager than just implementing encryption and key derivation. There are other things to consider, such as secure session management, rate limiting, protection against brute-force attacks and keeping sensitive data out of persistent client-side storage.

If you’re interested in the full code, Check out my GitHub repository. I’ve implemented a minimal version of this password manager with the complete authentication and storage flow, rate limiting, and a client interface using Go and React.

There’s also a live demo you can try. You can even open your browser’s developer tools and inspect the network requests to see what is being sent between the client and server.

Just a heads-up: this is an experimental learning project, not an audited password manager. Please don’t store real passwords in the demo.

Thank you for sticking with me until the end and putting up with all my rambling. I hope this gave you a better understanding of how zero-knowledge password managers work.

Have a nice day!