AES-256-GCM in the browser: what the Web Crypto API does
For a private note to stay private, it has to be scrambled before it leaves your device — not once it reaches a server. That only works if the scrambling is done well: a strong algorithm, a properly generated key, and an implementation without subtle mistakes. Every modern browser now ships exactly such an implementation. This guide explains what AES-256-GCM is, what the Web Crypto API adds, and how the two combine to encrypt a note on your own machine before anything is uploaded.
The goal: encrypt before upload
The whole point of client-side encryption is timing. If your note is turned into ciphertext — an unreadable, scrambled blob — inside your browser, then the server that stores it only ever receives that blob. There is nothing readable to log, index, or hand over. The provider is blind by design rather than by promise.
But "encrypt on the device" is only meaningful if the encryption is sound. A weak cipher, a predictable key, or a buggy implementation would leave you with the feeling of security and none of the substance. So the real questions are: which algorithm, and whose code runs it?
What AES is
AES — the Advanced Encryption Standard — is a symmetric cipher. Symmetric means the same key both encrypts the plaintext and decrypts the ciphertext. There is one secret, shared between whoever locks the data and whoever unlocks it. That fits a one-time note perfectly: the person who writes it and the person who reads it need to end up holding the same key, and nothing else.
The 256 refers to the key size — 256 bits. A longer key means an astronomically larger space of possible keys, which is what makes brute-force guessing hopeless. AES has been public, standardised, and scrutinised for over two decades, and the 256-bit variant is the conservative choice for data meant to stay confidential for a long time.
Symmetric encryption is also fast, which matters in a browser encrypting a file you just dropped in. Its one classic difficulty — getting two people to share the same secret key without an eavesdropper catching it — is handled separately, by key derivation and by where the key travels. More on that below.
What GCM adds
AES on its own describes how to transform one block of data. A mode of operation defines how to apply it across a whole message. GCM — Galois/Counter Mode — is a mode that provides authenticated encryption: it delivers two guarantees at once.
- Confidentiality — the contents cannot be read without the key.
- Integrity — any change to the ciphertext is detected. GCM produces a short authentication tag, a cryptographic checksum bound to both the data and the key. On decryption the tag is verified first; if a single bit was altered, decryption fails outright instead of returning wrong-but-plausible data.
That second property is easy to underrate. Unauthenticated encryption keeps a message secret but does nothing to prove it arrived intact. An attacker who cannot read your ciphertext might still flip bits in it, and without an authentication tag the recipient would decrypt the tampered blob and trust the result. GCM closes that door: a modified note refuses to decrypt at all.
The Web Crypto API
Knowing which algorithm to use is half the problem; running it correctly is the other half. The
Web Crypto API is a cryptography interface built into the browser itself, reached
through window.crypto.subtle. When you call it to encrypt with AES-256-GCM, the actual
work is done by the browser's own native code — not by JavaScript you shipped over the network.
That distinction carries real weight:
- It is written and audited by browser vendors. The AES-GCM implementation in Chrome, Firefox, and Safari is maintained by teams whose full-time job is getting this right.
- It can use hardware acceleration. Most processors have dedicated AES instructions. Native browser code can reach them, so encrypting even a large file is quick.
-
It avoids common footguns. Hand-rolled JavaScript crypto is notorious for subtle,
dangerous bugs: timing side channels that leak the key, weak randomness, misused nonces. The Web
Crypto API gives you constant-time primitives and a proper cryptographic random source
(
crypto.getRandomValues), and it steers you away from the sharp edges.
In short, using the browser's built-in engine means the sensitive parts are handled by well-reviewed code, rather than reinvented in application JavaScript where mistakes hide easily.
Where the key comes from
A cipher is only as strong as the key feeding it — AES-256 with a guessable key protects nothing. So how the key is produced matters as much as the cipher, and it is a separate step called key derivation: turning some starting secret into a full-strength encryption key.
There are two common starting points. When the secret is a high-entropy random value — such as a 128-bit link secret carried in a share link — the key is derived with HKDF-SHA-256, a fast function that expands strong random input into a clean, uniform key. When the secret is a human-chosen password, which is far more guessable, a deliberately slow function like PBKDF2 is used instead, to make each guess expensive for an attacker. Both feed the same AES-256-GCM engine. We cover each in its own guide: the URL fragment and password protection with PBKDF2.
Putting it together with classified
classified is a working example of this stack. When you create a note or attach a file:
- The browser generates the key material. A 128-bit link secret is produced with the browser's secure random source, and the AES key is derived from it via HKDF-SHA-256 — or, in password mode, from your password via PBKDF2-HMAC-SHA-512 with 310,000 iterations.
- The browser encrypts with AES-256-GCM. All of this uses the native Web Crypto API — no third-party cryptography libraries are involved.
-
Only the ciphertext is uploaded. The server receives an opaque blob and an
identifier, nothing more. The key stays in the URL
#fragment, which browsers never send to servers, or is derived from your password and never leaves the device. - Decryption happens only in a browser that holds the key. The recipient's browser re-derives the key from the link or password, verifies the GCM tag, and reveals the note once — after which it self-destructs.
Because classified verifies the GCM authentication tag before showing anything, a note that was corrupted or tampered with in storage or transit will simply fail to open. You never see altered content presented as genuine — the failure is loud, not silent.
Honest limits
Client-side AES-256-GCM is a strong protection, but it is worth being precise about what it does and does not cover.
- It protects data from the provider, in transit and at rest. The server holds only ciphertext it cannot read — exactly what this design is for.
- It does not protect a compromised device. Encryption happens in your browser, so if your machine is infected with malware or someone is looking over your shoulder, the plaintext is exposed before the cipher ever runs. Security lives at the endpoints.
- The client code must be trustworthy. You are relying on the JavaScript your browser loaded to actually call the Web Crypto API honestly and to keep the key off the wire. Standard, browser-native cryptography and inspectable clients are stronger signals than a closed app that asks for your trust.
- AES-256 is a symmetric cipher — one 256-bit key both encrypts and decrypts — which suits a shared one-time note.
- GCM adds an authentication tag, so tampering is detected and a modified note refuses to decrypt.
- The Web Crypto API runs vendor-audited, hardware-accelerated crypto in the browser, avoiding the footguns of hand-rolled JavaScript.
- The cipher is only as strong as its key, which is why key derivation (HKDF or PBKDF2) is a step in its own right.
- It shields data from the provider, not from a compromised device or an untrustworthy client.
classified encrypts your note with AES-256-GCM in your own browser, using nothing but the Web Crypto API, and uploads only the ciphertext. The key never reaches our servers.
Try classified free