Keyper Self-Hosted implements enterprise-grade end-to-end encryption to protect your credentials. This document outlines the security architecture, best practices, and implementation details.

Made with ❤️ by Pink Pixel ✨

• Client-Side Encryption: All sensitive data is encrypted in your browser before transmission
• No Server-Side Secrets: Your passphrase and decrypted data never leave your device
• Database Encryption: Only encrypted blobs are stored in your Supabase database

• Encryption: AES-256-GCM with unique IVs per record
• Key Derivation: Argon2id (preferred) or PBKDF2-HMAC-SHA256 (fallback)
• Master Passphrase: Simplified bcrypt-only authentication for new users
• Legacy Support: Backwards compatibility with wrapped DEK system
• Random Generation: Cryptographically secure random number generation
• Constant-Time Operations: Protection against timing attacks

Parameters:
- Time: 3 iterations
- Memory: 64MB
- Parallelism: 1 thread
- Output: 256-bit key

Benefits:

• Memory-hard function resistant to ASIC attacks
• Winner of the Password Hashing Competition
• Optimal balance of security and performance

Parameters:
- Iterations: 310,000
- Hash: SHA-256
- Salt: 128-bit random
- Output: 256-bit key

When Used:

• Argon2 unavailable or fails to load
• Older browser compatibility
• Resource-constrained environments

1. Salt Generation: 128-bit cryptographically secure random salt
2. Key Derivation: Passphrase + salt → 256-bit AES key
3. IV Generation: 96-bit random initialization vector
4. Encryption: AES-256-GCM with authenticated encryption
5. Storage: Base64-encoded encrypted blob with metadata

{
  "v": 1,
  "kdf": "argon2id",
  "salt": "base64-encoded-salt",
  "iv": "base64-encoded-iv", 
  "ct": "base64-encoded-ciphertext"
}

• Minimum Length: 12 characters (8 minimum enforced)
• Character Variety: Uppercase, lowercase, numbers, symbols
• Pattern Detection: Prevents keyboard patterns and sequences
• Dictionary Checks: Blocks common words and phrases

The system performs comprehensive passphrase analysis:

• Entropy Calculation: Measures randomness and unpredictability
• Pattern Detection: Identifies weak patterns (123, abc, qwerty)
• Crack Time Estimation: Estimates time to break with modern hardware
• Real-Time Feedback: Provides actionable improvement suggestions

✅ DO:

• Use a unique, strong passphrase for Keyper
• Consider using a passphrase manager
• Use 15+ characters for optimal security
• Mix character types (upper, lower, numbers, symbols)
• Use memorable but unpredictable phrases

❌ DON'T:

• Reuse passphrases from other services
• Use personal information (names, dates, etc.)
• Use common words or phrases
• Use keyboard patterns (qwerty, 123456)
• Share your passphrase with anyone

• Default Timeout: 15 minutes of inactivity
• Configurable: Adjust timeout or disable auto-lock
• Activity Detection: Extends timeout on user interaction
• Memory Clearing: Attempts to clear passphrase from memory

default-src 'self';
script-src 'self';
style-src 'self' 'unsafe-inline';
object-src 'none';
base-uri 'self';
frame-ancestors 'none';

referrer-policy: no-referrer
permissions-policy: camera=(), microphone=(), geolocation=()
x-content-type-options: nosniff
cross-origin-opener-policy: same-origin
cross-origin-resource-policy: same-origin

default-src 'self';
script-src 'self' 'unsafe-inline' 'unsafe-eval';
style-src 'self' 'unsafe-inline';
object-src 'none';
base-uri 'self';
frame-ancestors 'none';

Protection Against:

• Cross-Site Scripting (XSS)
• Code injection attacks
• Clickjacking
• MIME type confusion

• Event Tracking: All security operations logged
• Risk Scoring: Automatic threat level assessment
• Failed Attempts: Suspicious activity detection
• Performance Metrics: Operation timing and success rates

Enhanced PostgreSQL policies with WITH CHECK constraints:

-- Prevent data leakage with strict policies
CREATE POLICY "credentials_select_policy" ON credentials
  FOR SELECT USING (user_id = 'self-hosted-user');

CREATE POLICY "credentials_insert_policy" ON credentials
  FOR INSERT WITH CHECK (user_id = 'self-hosted-user');

• Encrypted Storage: Only encrypted blobs stored
• User Isolation: Strict row-level security
• No Plaintext: Sensitive data never stored unencrypted
• Audit Trail: Complete operation logging

• Memory Protection: Passphrase cleared on lock
• Secure Random: Cryptographically secure RNG
• Constant Time: Timing attack protection
• Error Handling: No information leakage in errors

✅ Database Compromise: Encrypted data remains secure
✅ Network Interception: End-to-end encryption
✅ XSS Attacks: Content Security Policy protection
✅ Timing Attacks: Constant-time operations
✅ Brute Force: Strong key derivation functions
✅ Rainbow Tables: Unique salts per record

⚠️ Client Compromise: Malware on your device could access unlocked data
⚠️ Passphrase Loss: No recovery mechanism (by design)
⚠️ Browser Vulnerabilities: Depends on browser security
⚠️ Side-Channel Attacks: Limited protection in JavaScript environment

• Use HTTPS for all connections
• Configure proper CSP headers
• Enable security headers (HSTS, X-Frame-Options)
• Regular security updates
• Monitor security logs

• Use strong, unique passphrase
• Enable auto-lock with appropriate timeout
• Regular security audits
• Monitor failed login attempts
• Keep browser updated

• Regular encrypted backups
• Test restore procedures
• Monitor encryption statistics
• Audit credential access
• Clean up old credentials

• Encryption Rate: Percentage of encrypted credentials
• Failed Attempts: Unusual authentication failures
• Performance: Encryption/decryption timing
• Errors: Cryptographic operation failures

The system logs comprehensive security events:

• Vault unlock/lock operations
• Encryption/decryption activities
• Failed authentication attempts
• Security policy violations
• Performance anomalies

Consider monitoring for:

• Multiple failed unlock attempts
• Unusual access patterns
• Performance degradation
• Security policy violations

1. Immediate: Lock vault and change passphrase
2. Assess: Review security logs for anomalies
3. Rotate: Update all stored credentials
4. Monitor: Watch for continued suspicious activity

1. Backup: Ensure encrypted backups are available
2. Verify: Test backup integrity and decryption
3. Restore: Import encrypted data to new instance
4. Validate: Confirm all data accessible with passphrase

Dual System Architecture:

🆕 New Users (Bcrypt-Only System):

• ✅ Secure emergency passphrase reset available
• 📖 See comprehensive Emergency Passphrase Reset Guide
• 🔒 User-controlled reset process with no admin backdoors
• 🛡️ All encrypted data remains completely safe during reset

🔄 Legacy Users (Wrapped DEK System):

• ⚠️ No recovery mechanism (by original design)
• 🚨 If you lose your passphrase, all encrypted data becomes permanently inaccessible
• 🔄 You must start fresh with a new passphrase
• 🛡️ This is intentional for maximum security

Migration Recommendation: Consider migrating to the new bcrypt-only system for improved passphrase reset capabilities.

• OWASP Cryptographic Storage Cheat Sheet
• NIST Password Guidelines
• Argon2 Specification

• Mozilla Web Security Guidelines
• OWASP Application Security Verification Standard

Found a security issue? Please report it responsibly:

• Email: [email protected]
• Subject: [SECURITY] Keyper Security Issue
• Include: Detailed description and reproduction steps

We take security seriously and will respond promptly to legitimate security reports.

This document is part of Keyper Self-Hosted v0.1.0
Last updated: August 2025