💻 computer science

WebAuthn PRF-Based Vault Key Wrapping and Zero-Knowledge PWA Storage Architecture

This paper presents a client-side security architecture for web-based credential vaults that achieves strong zero-knowledge properties by combining WebAuthn's PRF extension with symmetric cryptography and optimized browser storage patterns.

Original authors: Ian Pinto

Published 2026-07-08✓ Author reviewed ⓘ

📖 5 min read🧠 Deep dive

CC BY 4.0

Original authors: Ian Pinto

Original paper licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). ✨ This is an AI-generated explanation of the paper below. It is not written by the authors. For technical accuracy, refer to the original paper. Read full disclaimer

Imagine you have a digital safe (a "vault") where you keep your most important secrets, like passwords or private notes. Usually, to open this safe, you need a master key (a password). But what if you could open it using your face, your fingerprint, or a physical security key instead? And what if, even if a hacker stole a copy of your safe's contents, they still couldn't read a single word inside without your specific biometric key?

This paper by Ian Pinto describes a new way to build that kind of ultra-secure digital safe for web browsers. It combines a few high-tech concepts into a system that keeps your data "zero-knowledge"—meaning the server or the storage system knows nothing about what's inside, not even the key to open it.

Here is how it works, broken down into simple parts:

1. The Magic Key: WebAuthn PRF

Think of your passkey (the one you use to log in with your face or fingerprint) not just as a "Yes/No" gatekeeper, but as a secret recipe generator.

The Old Way: You prove you are you, and the system says "Access Granted."
The New Way (PRF): When you prove you are you, your device secretly runs a complex math recipe (called a Pseudo-Random Function or PRF) using a special "salt" (a random ingredient). This recipe produces a unique, high-quality "secret sauce" (a 32-byte code) that only your specific device knows how to make.
The Catch: This secret sauce is created inside your device's secure chip. It never leaves the device, and it is never saved to the hard drive. It exists for a split second, just long enough to unlock your safe, and then it is immediately wiped clean.

2. The Lock: Wrapping the Vault Key

Your vault has a master key (let's call it Key K) that actually locks the data.

The system takes that fleeting "secret sauce" from your passkey and uses it to wrap Key K in a digital envelope (encryption).
Once wrapped, Key K is locked inside this envelope. The system saves this envelope to your browser's storage (IndexedDB).
Crucial Point: The system never saves the secret sauce or the unwrapped Key K. It only saves the locked envelope. If a hacker steals the storage, they only have a locked box with no key.

3. The Safe House: IndexedDB Storage

The paper proposes a specific way to organize this data in the browser's storage (IndexedDB), which is like a digital filing cabinet.

The Filing System: The system creates three specific folders:
1. The Vaults: Where the locked envelopes (the wrapped keys) live.
2. The Credentials: A list of your passkeys and their "serial numbers" (to make sure no one is using a fake copy of your key).
3. The Meta: General notes for the app.
Zero-Knowledge Guarantee: The paper argues that because the storage only contains the locked envelopes and public metadata, a thief who steals the entire filing cabinet cannot reconstruct the key. They are stuck with the locked box and no way to open it without your physical device.

4. The Backup Plan: The "Password Fallback"

What if your browser doesn't support this fancy "secret sauce" feature (like on some Android tablets)?

The system has a backup plan called pw-v1. Instead of using the passkey's secret sauce, it uses a very slow, heavy-duty math puzzle (scrypt) based on a traditional password you type in.
This is slower and less convenient, but it ensures you can still open your safe even if the fancy hardware feature isn't available. It's like having a physical keyhole next to the biometric scanner.

5. Safety Checks: Stopping Replay Attacks

The paper emphasizes a "replay check."

Imagine a thief records your "unlock" signal and tries to play it back later to open the safe.
The system keeps a counter (like a mileage tracker on a car). Every time you unlock the safe, the counter goes up. If the system sees a signal with an old counter number, it knows it's a recording and rejects it.
Note: The paper admits this isn't perfect for all devices (some synced passkeys don't update the counter), but it adds a layer of defense.

6. What This Paper Does NOT Do

The author is very careful to say what this system doesn't protect against:

It doesn't protect against a virus on your computer. If a hacker is already inside your browser watching you type, they can steal the key while it's being used. This system only protects the data at rest (when it's sitting in storage).
It doesn't protect against "side-channel" leaks. If the app compresses data before locking it, or if the size of the locked box changes based on how long your password is, a clever hacker might guess what's inside just by measuring the box size. The paper warns developers to pad their data (make all boxes the same size) to prevent this.

Summary

This paper presents a blueprint for a web-based password vault that is mathematically proven to be unreadable to anyone who doesn't have your specific physical passkey. It uses your passkey to generate a temporary, one-time code that locks your data, ensures that code is never saved, and organizes the storage so that even a total theft of the database yields nothing but locked boxes. It's a "Zero-Knowledge" system where the storage provider (or a hacker) knows nothing about your secrets.

Technical Summary: WebAuthn PRF-Based Vault Key Wrapping and Zero-Knowledge PWA Storage Architecture

Problem Statement
The paper addresses the challenge of implementing robust zero-knowledge security for credential vaults within Progressive Web Applications (PWAs). While WebAuthn and passkeys provide strong public-key authentication, they traditionally do not expose a high-entropy symmetric secret to the web application for encrypting user data. Existing solutions often rely on server-side trust or master passwords, which can be vulnerable to offline attacks or require complex trust models. The specific problem is how to securely derive a symmetric encryption key from a passkey credential using the WebAuthn PRF (Pseudo-Random Function) extension, wrap a vault key, and store the resulting state in browser storage (IndexedDB) such that the persisted data reveals nothing about the user's secrets without a live authentication ceremony on the authenticator.

Methodology
The proposed architecture combines the WebAuthn PRF extension with symmetric cryptography and a rigorously designed IndexedDB storage schema.

Key Wrapping Scheme:
- Enrollment: During enrollment, the application requests a 32-byte PRF output from the authenticator using a unique, random 32-byte salt. This output serves as the Input Keying Material (IKM) for HKDF-SHA256.
- Derivation: The HKDF uses a frozen, versioned domain-separation label ("webauthn-prf-zktv vault key wrap v1") and an empty salt to derive a non-extractable AES-256-GCM wrap key ( $K_w$ ).
- Encryption: The vault key ( $K_v$ ) is encrypted using $K_w$ and a fresh 96-bit nonce.
- Storage: Only the resulting WrappedSecretRecord is persisted. This record contains the scheme identifier (prf-v1), the ciphertext, the nonce, and the PRF salt. Crucially, the PRF output and the derived wrap key are never stored; they are zeroized in memory immediately after use.
- Fallback: For clients where PRF is unavailable (e.g., Android WebView), a pw-v1 scheme is provided. This uses a memory-hard scrypt derivation (with fixed high-cost parameters) from a user password instead of the PRF, maintaining the same record structure.
Unwrapping and Verification:
- Replay Protection: The unwrapping process includes a mandatory replay verification step. The application re-evaluates the PRF with the stored salt and verifies the client data (challenge, origin) and the signature counter. The counter must be strictly increasing (unless it is zero, a known behavior for synced passkeys) to prevent replay attacks.
- Error Handling: The system is designed to be generic in failure modes. Decryption failures (due to wrong keys or tampering) raise a generic DecryptError that does not distinguish between a wrong key and corrupted data, preventing side-channel leakage.
Storage Architecture (IndexedDB):
- The library (webauthn-prf-zktv) defines a schema with three object stores: vaults, credentials, and meta.
- The vaults store uses a composite primary key [vaultId, scheme], allowing a single vault to hold both a prf-v1 record and a pw-v1 fallback record simultaneously.
- The credentials store holds non-secret metadata, including the last verified signature counter and the PRF salt, but never the secret keys themselves.
- The schema enforces structural invariants (e.g., nonce length, salt size) upon every load to ensure data integrity.

Key Contributions
The paper formalizes and provides an open-source implementation of:

A PRF-Based Vault Key Wrapping Scheme: A method to use the WebAuthn PRF output as the root of trust for deriving a symmetric wrap key, utilizing HKDF with strict domain separation.
A Zero-Knowledge IndexedDB Schema: A storage pattern where the persisted state contains no recomputable key inputs. The security of the stored data relies entirely on the secrecy of the authenticator's internal key.
The webauthn-prf-zktv Library: A reusable, typed TypeScript library that encapsulates the cryptographic logic, storage management, and migration paths (including a one-shot adapter for legacy TrustVault-PWA records).
Client-Side Replay Verification: The integration of signature counter checks and challenge/origin verification directly into the vault unlock algorithm, a feature often omitted in generic PRF helper libraries.

Results and Evaluation
The paper evaluates the architecture along three axes:

Security: The zero-knowledge argument posits that without the authenticator, the stored ciphertext is computationally useless. The scheme relies on the pseudo-randomness of the authenticator's PRF, the security of HKDF-SHA256, and the IND-CPA/INT-CTXT security of AES-256-GCM. The paper notes that while the symmetric layer is post-quantum adequate (AES-256), the asymmetric authentication layer remains vulnerable to quantum attacks, though this does not compromise the confidentiality of the stored vault key.
Performance: Unlock latency is dominated by the user verification gesture required by the authenticator. The cryptographic operations (HKDF derivation and AES-GCM decryption of a 32-byte payload) are negligible. The password fallback (scrypt) is intentionally expensive to deter offline attacks, though this may cause latency on low-end mobile devices.
Usability and Robustness: The system supports graceful degradation via the pw-v1 fallback for unsupported clients. It employs a "best-effort" approach to cloned credential detection (handling the zero-counter edge case of synced passkeys) and ensures that partial failures (e.g., crashes during counter updates) do not permanently lock the user out, prioritizing availability over strict replay protection in edge cases.

Significance and Claims
The paper claims to provide a formalized, production-ready pattern for achieving zero-knowledge storage in web applications using modern passkey technology. Its significance lies in:

Removing Server Trust: It shifts the confidentiality boundary entirely to the client, ensuring that even if the server or a synchronized backup is compromised, the user's secrets remain secure provided the authenticator is not compromised.
Standardization of Patterns: By defining a frozen v1 format and specific domain-separation labels, it prevents the silent invalidation of records due to algorithm changes and provides a clear migration path for future versions (e.g., prf-v2).
Holistic Security: It explicitly addresses non-cryptographic leakage vectors (such as pre-encryption compression and record size correlation) in the application-layer guidance, acknowledging that the storage layer alone cannot guarantee zero-knowledge if the application leaks metadata.

The author emphasizes that the library is a tool for developers to adopt these patterns without re-deriving the complex key-hygiene and storage discipline required for secure client-side vaults.