How Firefox Checks URLs Locally with Google Safe Browsing

This article explains how the Mozilla Firefox web browser protects users from malicious websites using the Google Safe Browsing API without compromising user privacy. Instead of sending every visited website address to Google for verification, Firefox downloads a compressed list of obfuscated, dangerous URL fragments directly to the user's device. By performing the initial safety checks locally and only requesting additional data from Google when a potential threat is detected, Firefox ensures your browsing history remains private while keeping you safe from phishing and malware.

The Privacy Challenge

To protect users from phishing, malware, and unwanted software, browsers must check visited URLs against a constantly updated database of known dangerous websites. Google maintains one of the most comprehensive threat databases in the world. However, querying Google’s servers every time a user clicks a link would allow Google to track a user's entire browsing history in real-time. Firefox solves this by using the Google Safe Browsing Update API to shift the verification process to the user's local machine.

Step 1: Downloading the Local Database

When you use Firefox, it periodically connects to Google’s Safe Browsing servers to download the latest threat lists. Sending a list of millions of full URLs to every browser would consume too much bandwidth and storage. Instead, Google hashes every malicious URL using the SHA-256 algorithm, which turns a URL of any length into a unique, unreadable 256-bit string of characters.

Google then truncates these hashes, keeping only the first 32 bits (4 bytes), known as a "hash prefix." Firefox downloads this highly compressed list of hash prefixes and stores it locally on your computer. The browser updates this local database roughly every 30 minutes.

Step 2: Checking URLs Locally

Every time you type a web address or click a link, Firefox performs the following steps entirely on your device:

  1. Hashing: The browser runs the visited URL through the SHA-256 cryptographic function to generate its full 256-bit hash.
  2. Truncation: Firefox takes the first 32 bits of that generated hash.
  3. Local Comparison: It compares this 32-bit prefix against the downloaded local database of malicious hash prefixes.

If there is no match in the local database, the website is deemed safe, and the page loads immediately. At this point, zero data has been sent to Google. Because the vast majority of websites are safe, almost all of your browsing checks stop right here.

Step 3: Handling a Prefix Match

Because the local database only uses 32-bit prefixes instead of the full 256-bit hashes, "hash collisions" can occur. This means a completely safe website might accidentally share the same first 32 bits of its hash with a known malicious website.

When Firefox detects a match in its local database, it cannot immediately block the site, as it might be a false positive. It must verify the full 256-bit hash to be certain.

Step 4: The Privacy-Preserving Server Check

To confirm if the website is genuinely dangerous without revealing the exact URL to Google, Firefox executes a final verification step:

  1. Sending the Prefix: Firefox sends only the matching 32-bit hash prefix to the Google Safe Browsing server, asking for a list of all full 256-bit hashes that begin with that specific prefix.
  2. Receiving the Full Hashes: Google responds by sending back all the full 256-bit malicious hashes in its database that start with those 32 bits.
  3. Final Local Verification: Firefox compares the full 256-bit hash of the website you are trying to visit against the small list of full hashes Google just sent back.

If the full hashes match, Firefox blocks the page and displays a warning screen. If they do not match, it was merely a hash collision, and Firefox loads the page normally.

Throughout this entire process, Google never learns the exact URL you visited. Even during the final verification step, Google only learns that your browser encountered one of many possible URLs that share the same 32-bit prefix, keeping your specific browsing activity private.