How does Password Manager by 2Stable work under the hood? Part 1, The Vault.

Today, I will try to explain how Password Manager by 2Stable works, with some tech details to help you understand it better. I’ll show you how we use some cool tech to keep your passwords safe and make your online life easier. Expect a deep dive into the technical aspects, complete with links to documentation and source codes. You’ll get a clear picture of how we make sure your passwords are really secure.

So, let’s dive in and see how Password Manager by 2Stable works to keep your online stuff safe.

The Vault

To begin, let’s understand a simple but important idea in digital security:

Encryption is Easy, Key Management is Hard.

This idea is key to how we do things. Here’s a simple look at how we address this in our app.

When you sign up, your first step is to create what we call a Vault as you begin using the app. But this Vault isn’t just a place to store items; it’s a unique space from which your own encryption key is generated. This encryption key is crucial for securing your information, ensuring that only you can access it. It’s like having a secret formula that guarantees everything in your Vault remains secure and accessible only to you.

The first step in creating a Vault is to choose a Password. This password, often referred to as the Master Password.

This Password isn’t saved or stored anywhere except in your head. It’s important to remember it, as there are no ways to recover it if forgotten.

After confirming the password, we generate an encryption key, known as the Master Key or MK. The Master Key is a random key consisting of 512 bits (64 bytes).

Additionally, we create another key, called the Intermediate Key or IK. The Intermediate Key is a random key comprising 256 bits (32 bytes).

Next, we generate a Salt. The Salt is a 128-bit (16 bytes) random data.

Following this, we perform some manipulations with your Password:

• We trim any whitespaces and newlines.
• We normalize the Password using the Unicode Normalization Form KD.

This normalized Password is now referred to as NP.

At this point, we’re ready to derive the so-called Derivated Master Password or DMP. We achieve this by utilizing the Argon2ID13 algorithm along with the NP and the Salt, using a minimum memory size of 32 MB, a minimum number of iterations of 20, and a degree of parallelism of 1. More information about this process can be found here.

Next, we encrypt the IK with our DMP using xchacha20poly1305ietf and a Nonce of 192 bits (24 bytes). This encrypted IK is denoted as EIK. More information about this encryption process can be found here.

The next step is to encrypt our MK with our IK using the same xchacha20poly1305ietf algorithm. The resulting encrypted MK is denoted as EMK.

Let’s sum up:

1. Generate Master Key = MK
2. Generate Intermediate Key = IK
3. Generate Salt = Salt
4. trim(Password) = Password
5. normalize(Password) = NP
6. Argon2ID13(NP, Salt, 20, 32*1024*1024, 1) = DMP
7. xchacha20poly1305ietf(IK, DMP) = EIK
8. xchacha20poly1305ietf(MK, IK) = EMK

Finally, we are ready to create our Vault struct, which looks like this in Swift:

struct Vault {
    let primary: String
    let name: String
    let version: UInt64
    let salt: Crypto.Kdf.Salt
    let encryptedIntermediateKey: Bytes
    let encryptedMasterKey: Bytes
}

We include the version property in case we need to migrate the Vault to some other algorithm or parameters.

So, we’ve created the Vault, and it can be stored on your device. More importantly, this Vault is designed to be synced with the user’s iCloud. This means you can get back your Master Key from any of your devices that are connected to the same iCloud account. Just remember your Password.

Keep in mind that at this point, your Master Key is secure as long as you choose a Strong Password. We want to emphasize the importance of understanding the risks involved. While we don’t enforce any limitations on Password choice, it is crucial that you pick a strong, unique password to ensure the security of your Vault and its contents.

Why do we need the Intermediate Key?

When you use your fingerprint or face to unlock your app, it doesn’t make sense to use Argon2ID13, which can be really resource-intensive. For example, in cases like the Autofill Extension, where there’s a limit of only 120 MB of memory available, using Argon2ID13 would be too much. So instead, we store the Intermediate Key in a secure place called the Secure Enclave.

Secure Enclave is a special part of the device’s hardware that’s specifically designed to keep sensitive information safe.

In the future, we’re thinking about adding a special feature called an Emergency Kit. It’s like a secret code that you can scan to get into your account if you forget your Password. But you don’t really want to include your Password in this Emergency Kit, in case you want to keep it, like under a rock or in your parents’ safe. Instead, you want to include the Intermediate Key.

We’ve just gone through the process of how the Vault is created in our Password Manager. This is a key part in safeguarding your digital life, ensuring that your sensitive information is well-protected.

Next, I’ll dive into how we use the Master Key in our security setup.

Stay with us as we continue to reveal more about our security measures, designed to keep your information secure while making it easily accessible to you.

• Published: 14 Mar 2024

• Updated: 26 Jun 2024