vault

Overview ¶

Package vault provides recipients.txt management for multi-user encryption support. Recipients can be added to enable multiple parties to decrypt vault entries.

Package vault provides encrypted storage and search for OpenPass entries.

============================================================================= DESIGN DOCUMENT: Scalable Search for Large Vaults =============================================================================

Current Bottleneck: ------------------- Find() uses a two-pass approach. The first pass (path matching) is fast O(n). The second pass (field search) requires decrypting ALL entries where the path didn't match. This sequential decryption is the primary bottleneck for large vaults. For a vault with 50k entries where no paths match, we must sequentially decrypt 50k entries before returning results.

Why Concurrent Decryption Helps: -------------------------------- Modern CPUs have multiple cores. Sequential decryption leaves cores idle. By decrypting entries in parallel using a bounded worker pool, we can utilize multiple cores simultaneously, proportionally reducing wall-clock time.

Bounded Parallelism Rationale: ----------------------------- We use a bounded worker pool (default: 4 concurrent decryptions) rather than unbounded parallelism for these reasons:

1. Memory Pressure: Each decrypted entry consumes memory. With unbounded parallelism on a 50k entry vault, we could spawn 50k goroutines all trying to decrypt simultaneously, causing memory exhaustion.

2. I/O Saturation: The underlying storage (SSD/HDD) has finite read throughput. Beyond a certain concurrency level, additional workers simply compete for the same I/O bandwidth without improvement.

3. Cryptographic Operations: Age decryption involves CPU-intensive operations (X25519 key exchange, ChaCha20-Poly1305). Too many concurrent operations can cause CPU cache thrashing.

4. Practical Results: Testing shows 4 workers provides near-optimal throughput for typical user machines while keeping memory bounded.

Performance Targets (4 workers): -------------------------------- - 50k entries, path-only: ~500ms (no decryption needed) - 50k entries, field-search: ~2-4s (bounded by decrypt parallelism) - 10k entries, field-search: ~500ms-1s - 1k entries, field-search: ~100-200ms

Security Tradeoffs of Persistent Encrypted Index: ------------------------------------------------ An alternative approach would be to build a persistent index that maps search terms to encrypted entry references. This would enable O(1) or O(log n) searches without decryption.

Security Considerations:

• A persistent index MUST be encrypted at rest to prevent leakage of entry relationships and search patterns
• The index encryption key must be derived from the user's passphrase (like the vault identity key) ensuring only authorized users can access it
• Even with encryption, an index reveals search patterns over time:
• Which terms are searched frequently
• Which entries are accessed together
• Temporal patterns of access
• If the index is stored alongside the vault (e.g., in the vault directory), it could be stolen alongside encrypted entries

Attack Scenarios:

• A passive observer who steals the vault but not the passphrase: encrypted index provides no additional advantage over encrypted entries
• An active observer with passphrase but no vault: reveals search history but not content
• A side-channel attack on a compromised machine: index access patterns could reveal search behavior even with encrypted index

For these reasons, we currently prefer the on-demand decrypt approach which provides no persistent search metadata to steal.

Future encrypted index implementation would need to: 1. Use a key derived from the vault's master key 2. Store only term->entry mapping, never plaintext content 3. Consider adding plausible deniability via fake entries

============================================================================= END DESIGN DOCUMENT =============================================================================

Performance Characteristics:

List is O(n) where n is the number of entries. It performs no decryption, only directory walking. For large vaults (1k+ entries), List is fast.

Find uses a two-pass approach:

• First pass: O(n) path-only comparison (no decryption)
• Second pass: O(k) decryption + field search where k = entries where path didn't match

The fast path optimization means:

• Queries matching paths (e.g., "github" matching "github.com/user") avoid decryption entirely
• Only field content searches require decrypting entries

FindConcurrent uses a bounded worker pool for parallel decryption:

• Same two-pass logic as Find, but decrypts entries concurrently
• Default 4 concurrent workers balances throughput vs memory pressure
• Best for field-search queries on large vaults (10k+ entries)

Limits:

• 100 entries: ~10ms (path-only when possible)
• 1,000 entries: ~100ms (path-only when possible)
• 10,000 entries: ~1s (path-only when possible)
• Field searches scale with number of non-path-matching entries