How the Firefox Primary Password Encrypts Local Login Data

This article explains the cryptographic process behind the Firefox Primary Password and how it secures your saved credentials on your local machine. Specifically, it details the relationship between the logins.json and key4.db files, how Firefox handles encryption by default, and how enabling a Primary Password locks down the master cryptographic key to prevent unauthorized local access to your passwords.

The Role of logins.json and key4.db

Firefox uses two specific files in your user profile folder to manage saved passwords:

  • logins.json: This file stores your actual website login data. While metadata like website URLs and timestamps are stored in plain text, the usernames and passwords themselves are stored as encrypted ciphertext.
  • key4.db: This is an SQLite database managed by Mozilla’s Network Security Services (NSS). It stores the master decryption key required to unlock the ciphertext inside the logins.json file.

The Default State: No Primary Password

A common misconception is that Firefox stores passwords in plain text until you set a Primary Password. In reality, the usernames and passwords inside logins.json are always encrypted.

However, without a Primary Password, the master key stored inside key4.db is encrypted using a blank (empty) password. Because the password is blank, Firefox can automatically unlock key4.db in the background and decrypt logins.json whenever you need to log into a website. While this protects your data from basic text-scraping malware, any attacker or third-party tool with local access to both logins.json and key4.db can easily decrypt your passwords because the key is essentially left in the lock.

What Happens When You Set a Primary Password

Setting a Primary Password does not actually change the encryption of the logins.json file. Instead, it encrypts the master key held inside key4.db. The process works through the following cryptographic steps:

  1. Salt Generation: Firefox generates a random string of data known as a cryptographic salt. This ensures that even if two users have the exact same Primary Password, their resulting encryption keys will be completely different.
  2. Key Derivation (PBKDF2): Firefox takes the Primary Password you typed, combines it with the salt, and runs it through PBKDF2 (Password-Based Key Derivation Function 2) using the HMAC-SHA256 hashing algorithm for thousands of iterations. This creates a strong "Derived Key." The high number of iterations intentionally slows down the process to make brute-force attacks difficult.
  3. Encrypting the Master Key: Firefox uses this newly created Derived Key (via the AES-256-CBC encryption algorithm) to encrypt the internal master key stored inside key4.db.
  4. Securing the Database: The salt and the newly encrypted master key are saved to key4.db. The actual Primary Password is never saved anywhere on your computer.

How Decryption Works During a Session

Once the Primary Password is active, logins.json becomes useless to anyone who cannot unlock key4.db. When you open Firefox and attempt to use a saved password, the following sequence occurs:

  1. Firefox prompts you for your Primary Password.
  2. You enter the password, and Firefox combines it with the salt stored in key4.db.
  3. Firefox runs the PBKDF2 algorithm to recreate the Derived Key in your computer's temporary memory (RAM).
  4. The Derived Key decrypts the master key inside key4.db.
  5. The unlocked master key (which uses 3DES or AES) is then used to decrypt the specific username and password entries inside logins.json.

Once unlocked, Firefox keeps the master key in your system's RAM for the duration of your browsing session so you do not have to type your Primary Password for every single website. When you close Firefox, the key is wiped from memory, and the key4.db file returns to its locked state.