Locking files in the browser with Web Crypto: PBKDF2, HKDF, and 1 MiB AES-GCM records

A solo developer built Clipboard Share, a same-network file-sharing web app, and added an opt-in password lock implemented entirely with the browser's Web Crypto API. The scheme derives a 256-bit encryption key and a separate verifier from the password via PBKDF2-SHA256 at 600,000 iterations, splits them with HKDF, wraps a random per-file key with AES-GCM, and encrypts file bodies in 1 MiB AES-GCM records decrypted by a service worker as bytes arrive. The server stores only ciphertext, the verifier's SHA-256 hash, the wrapped file key and an encrypted filename, so it never sees the password or encryption key.

I built a small web app called Clipboard Share. Devices on the same Wi-Fi network see each other automatically, no sign-up, and you drag a file or paste some text to send it. It was made with Claude Code, and I'm the only person working on it. The thing about "same network, no account" is that anyone on that network can join the room. That's fine for a meme or a photo. It's less fine for a scan of an ID card or a contract that you want to move to a shared PC. So I added an opt-in "lock with a password" switch. This post is about how it works, with the real code, and a list of what it still doesn't do. Locking is off by default, and you turn it on per upload. The last point shaped everything else. It led to chunked encryption, a service worker on the download side, and a few details I would have skipped otherwise. Password → PBKDF2 → HKDF splits it into encKey and verifier → a random per-file key is wrapped with encKey and stored in metadata → the file body is encrypted in 1 MiB AES-GCM records → on download, a service worker decrypts while the bytes arrive. The server stores ciphertext, the hash of the verifier, the wrapped file key, and the encrypted file name. It never receives the password or encKey . The password goes through PBKDF2-SHA256 with 600,000 iterations PBKDF2 ITERATIONS = 600000 . The salt is 16 random bytes, generated once each time you set up a lock. Within one session I reuse the derived keys, because running 600,000 iterations per file would be painfully slow. There's a design problem here. The server has to check that the password is right, so the client has to send something. That something must not be the encryption key. So I split the PBKDF2 output with HKDF into two independent values, using different info strings: js const hkdf = await subtle .importKey 'raw', masterBytes, 'HKDF', false, 'deriveBits', 'deriveKey' const empty = new Uint8Array 0 const encKey = await subtle .deriveKey { name: 'HKDF', hash: 'SHA-256', salt: empty, info: INFO ENC }, hkdf, { name: 'AES-GCM', length: 256 }, false, 'encrypt', 'decrypt' const verifierBits = await subtle .deriveBits { name: 'HKDF', hash: 'SHA-256', salt: empty, info: INFO VERIFY }, hkdf, 256 const vh = toHex await subtle .digest 'SHA-256', verifierBits That's deriveLockFromMaster in utils/lockCrypto.js . The info strings are cs-lock-v1/enc and cs-lock-v1/verify . encKey is created with extractable: false , so page JavaScript can use it but can't read the raw bytes. The server stores only vh , the SHA-256 of the verifier. To unlock, the client sends the verifier and the server hashes it and compares. So the server can recognize the right password, but it can't compute encKey from what it holds. I don't encrypt file contents with encKey directly. Each file gets its own random 32-byte key the DK . The DK encrypts the body and the file name. encKey only wraps the DK. wrapFileKey encrypts the DK with AES-GCM under a random 12-byte IV and the additional data cs-lock-v1/key . The result is 48 bytes 32 + the 16-byte tag , which goes into the object metadata along with the IV. Two things come out of this. Files locked with the same password still have different keys. And the QR link later on can carry the key for one file only, instead of anything password-wide. The file name is encrypted with the DK too, trimmed to 180 UTF-8 bytes without cutting a character in half and keeping the extension. In the UI, a locked file's card shows random characters instead of its name until it's unlocked. The uploading device also creates a random 32-byte delete key. Only its SHA-256 dh goes to the server. The key itself stays in that device's memory. AES-GCM only gives you the plaintext after it has verified the whole message. If I encrypted a 2 GB file as one message, the browser would have to hold all of it, and the receiver couldn't release a single byte until the end. So the plaintext is cut into 1 MiB records RECORD SIZE = 1024 1024 , and each record is its own AES-GCM message with a 16-byte tag. The IV is a random 4-byte per-file prefix plus the record index as a 64-bit big-endian number. The additional authenticated data holds the index and a flag for "last record": js export function recordAad index, isLast { const aad = new Uint8Array AAD RECORD PREFIX.length + 9 aad.set AAD RECORD PREFIX, 0 const view = new DataView aad.buffer writeU64 view, AAD RECORD PREFIX.length, index aad aad.length - 1 = isLast ? 1 : 0 return aad } The last-record flag matters. With independently authenticated records, chopping the end off a file leaves every earlier record valid, so a truncated file would decrypt "successfully" into a shorter one. With the flag in the AAD, the new final record fails authentication because it wasn't encrypted as the last one. The decryptor's finish also checks that exactly the expected number of records arrived LOCK TRUNCATED , LOCK TRAILING DATA . Uploading reuses the existing multipart uploader. The server is told it's receiving a "virtual file" the size of the ciphertext. One part is 64 records, which is 64 × 1 MiB + 16 bytes of ciphertext. If the server's part size doesn't match, records would straddle part boundaries and become impossible to decrypt, so the client checks before starting and bails out: js const created = await baseApi.create rid, { size: pt, lock: meta } if created.partSize == CT PART SIZE { // 파트 경계가 다르면 레코드가 파트 사이에 걸쳐 풀 수 없게 된다 → 시작하지 않는다 try { await baseApi.abort rid, { uploadId: created.uploadId, key: created.key, size: total } } catch { / ignore / } throw Object.assign new Error 'Unexpected part size' , { code: 'LOCK PART SIZE', retryable: false } } The comment is in Korean: "if the part boundary differs, a record would span two parts and couldn't be decrypted, so don't start." Each part is encrypted just before it's uploaded, reading only that slice of the file encryptPart , so the full file never sits in memory. One limitation: locked uploads don't save resume state to localStorage. Retries during a session work, but you can't close the tab and resume later. Downloading a multi-gigabyte ciphertext and decrypting afterwards would crash a phone. Instead, a service worker intercepts requests to / locked/<token , decrypts records as the bytes arrive, and streams the plaintext to the browser, which treats it as a normal download. js const body = new ReadableStream { async pull controller { for ;; { const { done, value } = await reader.read if done { decryptor.finish controller.close return } const out = await decryptor.push value if out.length 0 { for const pt of out controller.enqueue pt return } } } } That's trimmed from handleLockedDownload in public/sw.js ; I removed progress notifications and error handling. The decryptor accepts chunks of any size, buffers them, and returns plaintext whenever a full record is available. Service workers aren't bundled in this project, so sw.js can't import lockCrypto.js . The decryption logic exists twice. It's ugly, but a test checks the worker's copy too. The key goes to the worker through a MessageChannel as a one-time job with a random token. Jobs expire after two minutes LOCKED JOB TTL MS and are deleted the first time they're used. When there's no active service worker controller, or the device is iOS, the app falls back to in-memory decryption. That path refuses files over 500 MB MEMORY DECRYPT LIMIT and tells the user to download from another device. I haven't tested large files on real devices well enough to quote a real-world ceiling, so I'm not going to. A password is only as strong as the effort needed to guess it, so wrong guesses are rate limited on the server. My first thought was per file, but then N files locked with the same password would give an attacker N times the attempts. So the counter is keyed by vh , one bucket for everything locked with that password: js export const UNLOCK MAX TOTAL = 30; export const UNLOCK MAX PER IP = 5; export function unlockRemaining vh: string, ipKey: string, now: number = Date.now : number { const e = entries.get vh ; if e || now - e.at ENTRY TTL MS return Math.min UNLOCK MAX TOTAL, UNLOCK MAX PER IP ; const ip = e.perIp.get ipKey ?? 0; return Math.max 0, Math.min UNLOCK MAX TOTAL - e.total, UNLOCK MAX PER IP - ip ; } There are 30 wrong guesses total and 5 per IP, whichever runs out first. The delete endpoint shares the same counter. If deleting accepted a verifier without limits, it would be an unlimited password-guessing oracle, which would make the limit pointless. Deleting requires proof of one of two things: the delete key from the uploading device hashed and compared with the stored dh , or the password verifier. Neither means a 403. Comparisons use timingSafeEqual . The unlock endpoint only hands out a presigned download URL after the verifier matches, and that URL lives for 60 seconds LOCKED DOWNLOAD EXPIRES SEC . Locked objects also sit in a separate R2 bucket R2 LOCKED BUCKET NAME . Typing a password on a phone is annoying, so every locked file has a "share by QR code" action. The link looks like this: {origin}/ /lk?r={roomId}&i={id}&v={verifier}&k={file key} Everything is after the , so it isn't sent in HTTP requests to the server or CDN. k is the DK of that one file. The password and encKey are not in the link. v is the verifier the server needs before it gives out a download URL. export function buildLockedLink origin, { roomId, id, verifier, key } { const q = new URLSearchParams { r: roomId, i: id, v: verifier, k: key } return ${origin}/${LOCKED LINK PREFIX}${q.toString } } index.html strips the fragment from the address bar before the analytics script runs and keeps it only in window. csLockedLink . When the link is opened, the app uses k to decrypt the file name; if that fails, it reports LOCK LINK INVALID . Anyone who has the link or a photo of the QR code can download that file without the password. You can only create one if you locked the file yourself or confirmed the password in this session. I'd rather list the limits than have somebody find them. 1. The password lock doesn't cover text or device info. It protects files and file names. Text you send, the animal-name labels for devices, file sizes and upload times are all visible. Text locking was pushed to a second phase in the design doc. 2. Browser crypto means trusting the JavaScript the server sends. The encryption runs in your browser, but the site delivers the code. If the site's code were changed, the browser-side encryption wouldn't help. Every web app that does crypto in the page has this limit. The accurate summary for files you lock with a password is: if you received the genuine code, the password isn't sent to the server. It's not "the server can never see anything." 3. The verifier is per password, not per file. The v in a QR link comes from the password. So with the same password on several files in one room, someone holding one QR link can also ask the server to download or delete the other files' ciphertext. They still can't decrypt those files, because k is per file, but the delete request is a real gap. 4. Attempt counters live in server memory. It's a Map . Restart the server and the counters reset. The design doc lists this as a known limit, and I haven't moved it to persistent storage. Related: the same doc notes that whoever holds the server's vh and a ciphertext could try short passwords offline. PBKDF2 at 600,000 iterations slows that down but doesn't remove it. The input currently only requires 4 characters MIN LOCK PASSWORD = 4 . And there's no recovery. If you forget the password, the file stays locked. Locked files are kept like regular ones: they're deleted soon after everyone leaves, and at most about a day. PBKDF2 at 600,000 iterations, HKDF to separate encKey and verifier, a wrapped random key per file, 1 MiB AES-GCM records with a last-record flag, a service worker that decrypts as bytes arrive, and attempt limits counted per password. If you spot something wrong, especially in the crypto, please tell me. You can try it here: Feedback is welcome, either in the comments or through the "건의하기" suggestions link at the bottom of the site. Originally published in Korean on velog https://velog.io/@ch kang/%EB%B8%8C%EB%9D%BC%EC%9A%B0%EC%A0%80-%ED%8C%8C%EC%9D%BC-%EC%95%94%ED%98%B8%ED%99%94-Web-Crypto-AES-GCM%EC%9C%BC%EB%A1%9C-%ED%8C%8C%EC%9D%BC-%EC%9E%A0%EA%B7%B8%EA%B8%B0-%EC%98%A8%EB%9D%BC%EC%9D%B8-%ED%81%B4%EB%A6%BD%EB%B3%B4%EB%93%9C-%EA%B0%9C%EB%B0%9C%EA%B8%B0 .