Zero-Knowledge Architecture
Passary implements a zero-knowledge architecture where decryption keys are derived exclusively on the client device.
The application executes all cryptographic operations within the local browser environment. At no point does the application transmit passwords, derived keys, or unencrypted vault data to any remote endpoint.
Server-side components, when utilized for synchronization, act strictly as oblivious storage for opaque encrypted blobs. They possess no cryptographic material capable of decrypting the stored data.
Threat Model
This section defines the specific capabilities of attackers and the security boundaries enforced by the architecture.
Mitigated Scenarios
- Database CompromiseAttackers with full read access to the storage backend retrieve only encrypted ciphertext and unencrypted metadata headers.
- Network CompromiseAttackers intercepting network traffic observe only TLS-encrypted streams containing AES-256 encrypted payloads.
- Offline AttacksAttackers attempting brute-force decryption on stolen vault files face high computational costs imposed by memory-hard key derivation.
- Rainbow Table AttacksAttackers cannot use pre-computed tables due to the enforcement of unique, randomly generated 32-byte salts for every vault.
Out of Scope
- Client Endpoint CompromiseThe architecture does not protect against malware, keyloggers, or malicious extensions resident on the client device during active sessions.
- CoercionThe system does not implement plausible deniability or hidden volumes to mitigate forced disclosure scenarios.
- Low-Entropy CredentialsWhile Argon2id raises the cost of guessing, it cannot mathematically prevent exhaustive search of weak passwords.
Cryptographic Primitives
Passary utilizes standardized primitives accessible via the Web Crypto API and WebAssembly.
| Function | Algorithm | Parameters |
|---|---|---|
| Symmetric Encryption | AES-GCM | 256-bit key, nonce (96-bit), 128-bit tag |
| Password Hashing | Argon2id | 256 MB RAM, 3 iterations, 2 lanes |
| Key Binding | HKDF-SHA256 | HMAC-based key derivation |
| Digest | SHA-256 | Keyfile hashing |
Authentication & Key Derivation
Key derivation transforms low-entropy user inputs into a cryptographically strong 256-bit encryption key. This process establishes the computational work factor required to decrypt the vault without the password.
Argon2id Configuration
Argon2id protects against GPU and ASIC-based attacks by enforcing significant memory requirements. The configuration targets modern client hardware capabilities:
Memory Cost: 256 MB
The function allocates 256 MiB of RAM. This memory hardness imposes a linear cost scaling for attackers attempting parallel execution on specialized hardware.
Time Cost: 3 Iterations
The function performs 3 passes over the memory block. This increases the total execution time, resisting trade-off attacks that attempt to reduce memory usage.
Key Derivation and HKDF Binding
The application utilizes HKDF-SHA256 to deterministically bind the Argon2id output with other entropy sources.
The derivation pipeline proceeds as follows:
This construction ensures that the final key is mathematically dependent on all inputs.
Symmetric Encryption
Data confidentiality and integrity are provided by AES-256-GCM (Galois/Counter Mode).
As an Authenticated Encryption with Associated Data (AEAD) cipher, AES-GCM ensures that any modification to the ciphertext destroys the validity of the authentication tag, causing decryption to fail.
Additional Authenticated Data (AAD)
The AAD input binds the vault header to the encrypted payload. The following fields are included in the AAD calculation:
Authentication of the header prevents manipulation of parameters. Attackers cannot alter KDF settings or swap nonces without invalidating the tag.
Local Persistence
Passary persists data locally using the IndexedDB API.
The storage layer receives only the encrypted vault blob (ciphertext + tag) and the unencrypted header required for key derivation. The encryption key is never written to IndexedDB, LocalStorage, or cookies.
Vault File Format
The .passaryvault file uses a JSON structure containing a cleartext header and an encrypted payload.
{
"header": {
"fileFormatVersion": 2,
"kdfVersion": 2,
"vaultId": "550e8400-e29b-41d4-a716-446655440000",
"salt_pw": "a1b2c3d4...",
"kdfParams": {
"memoryKiB": 262144,
"timeCost": 3,
"parallelism": 2,
"argon2Version": 19
},
"cipher": "aes-256-gcm",
"nonce": "oCy1FX7Sg08EL..."
},
"ciphertext": "..."
}Structure definition allowing header parsing prior to decryption.
Keyfile Usage
When enabled, the keyfile serves as a mandatory high-entropy input for the key derivation function.
Entropy Input
The file is hashed using SHA-256. The resulting 32-byte digest contributes to the entropy pool used by HKDF.
Binding
The key is derived from HKDF(Argon2id(Password) || SHA256(Keyfile)). Decryption requires the precise combination of both secrets.
Separation
The keyfile is neither stored in the vault nor referenced by path. It must be provided by the user at runtime.
Failure Mode
Bitwise modification or loss of the keyfile results in an incorrect derived key, causing decryption to fail.
Deterministic Key Derivation
The derivation process is deterministic and stateless.
Reproducibility
Identical inputs (password, salt, keyfile, parameters) always yield the same encryption key.
Portability
This property allows vaults to be opened on independent devices without synchronizing keys or accessing a central authority.
Validation
The system verifies correctness solely through the AES-GCM authentication tag. It does not verify the password against a stored hash.
Encryption Sessions & Nonce Handling
Passary enforces strict nonce management to satisfy AES-GCM security requirements.
A cryptographically strong random 12-byte nonce (96-bit) is generated for every encryption operation.
Key-nonce pairs are never reused. Updating a vault triggers re-encryption with a fresh nonce.
The nonce is included in the Authenticated Data (AAD) block, preventing malicious modification in transit.
Parameter Agility
Cryptographic parameters are stored explicitly within the vault header, distinct from the application logic.
Versioning
The header version and KDF parameters dictate the derivation path, allowing the application to support multiple generations of security standards.
Evolution
Memory and time costs for Argon2id can be increased in future revisions without invalidating existing vaults.
Constraint
Downgrade attacks are prevented by the AAD signature, which includes the parameter set.
Integrity Guarantees
The architecture enforces data integrity alongside confidentiality.
Tamper Proofing
The GCM tag detects bitwise corruption, truncation, or malicious formatting.
Atomic Success
Decryption is all-or-nothing. If the authentication tag is invalid, the operation yields no plaintext data.
Header Integrity
The header is authenticated (but not encrypted). This allows parameter inspection prior to derivation while preventing undetected modification.
Client Execution Environment
Execution occurs within the constraints of the browser runtime.
Memory Lifecycle
Sensitive variables exist in heap memory which is subject to garbage collection. The application cannot force immediate memory zeroization.
Volatile State
Keys are held only in volatile memory. Reloading the page or closing the browser terminates the process and clears the memory state.
Extension Isolation
The model assumes the absence of malicious browser extensions with permissions to read DOM or request content.
Offline Operation
The architecture eliminates dependency on network services for core functionality.
Local Validation
Key derivation and decryption require no communication with a central server.
Availability
Access to the vault is guaranteed as long as the user possesses the device and the credentials.
Data Minimization
The system adheres to strict data minimization principles regarding sensitive material.
Ephemeral Keys
Keys exist only during the active use session.
No Telemetry
Cryptographic operations emit no usage data or error reports to external collectors.
Opaque Blobs
Persistent storage sees only opaque, high-entropy byte arrays.
Auditability
The design facilitates independent verification of security properties.
Standard Primitives
All algorithms are standardized and widely reviewed (AES-GCM, SHA-256, Argon2), utilizing open implementations.
Inspectable Storage
The vault format is documented and structurally simple, allowing tools to verify header parameters and payload structure.
Scope of Trust
The security model explicitly defines the required trust anchor.
Trusted Components
- •The end-user device hardware and operating system.
- •The browser runtime environment (JavaScript engine, Web Crypto API).
- •The integrity of the client-side code delivered to the browser.
Untrusted Components
- •Network transport mechanisms.
- •Storage backend servers.
- •Third-party scripts or frames (none are loaded).