Security Documentation

This extension implements a multi-layered security system for storing sensitive API keys (OpenAI, Anthropic, OpenRouter) using industry best practices and OWASP 2024/2025 guidelines.

High-Level Architecture

+------------------------------------------------------------------+
|                        User Interface                             |
+--------------------------------+---------------------------------+
                                 |
                                 v
+------------------------------------------------------------------+
|                      API Key Manager                              |
|  +--------------+  +---------------+  +----------------------+    |
|  |  Password    |  |    Rate       |  |    API Key           |    |
|  |  Validator   |  |   Limiter     |  |    Validator         |    |
|  +--------------+  +---------------+  +----------------------+    |
+--------------------------------+---------------------------------+
                                 |
            +--------------------+--------------------+
            v                    v                    v
+-------------------+ +--------------+ +----------------------+
|  Crypto Service   | |   Device     | |   Session Cache      |
|  (AES-GCM +       | |   Binding    | |   (chrome.storage    |
|   PBKDF2 800k)    | |   Service    | |    .session)         |
+---------+---------+ +------+-------+ +----------------------+
          |                  |
          v                  v
+------------------------------------------------------------------+
|              Secure Storage (chrome.storage.local)                |
|                    [Encrypted API Keys]                           |
+------------------------------------------------------------------+

Security Layers

Security Features

Timing Attack Protection

All decryption operations enforce a minimum execution time of 400ms to prevent timing-based password guessing attacks, even when keys don't exist.

Error Message Safety

• No distinction between "key not found" and "wrong password" timing
• Generic error codes instead of detailed failure reasons
• No API key content in logs or error messages

External Communication Blocking

• All external messages from other extensions are blocked via onMessageExternal
• All external connections are blocked via onConnectExternal
• API key operations are never exposed externally

Session Management

• Uses chrome.alarms API for reliable timeout handling (survives service worker restarts)
• Automatic session clearing on extension suspend
• SESSION_LOCKED messages notify UI when timeout occurs
• Configurable Settings: Session expiry (5 min to 6 hours), inactivity timeout (5 to 60 min)
• Validation Enforcement: Settings limits are enforced at multiple levels (UI, storage, retrieval)

Password Security

Validation Rules

1. Length: 12-128 characters
2. Character Types: Must contain at least 3 of:
   • Uppercase letters (A-Z)
   • Lowercase letters (a-z)
   • Numbers (0-9)
   • Special characters (!@#$%^&*)
3. Quality Checks:
   • Not in common password list
   • No more than 3 consecutive identical characters
   • No sequential patterns (keyboard walks, alphabetical sequences)

Password Strength Scoring

API Key Validation

Supported Providers

Display Masking

API keys are masked when displayed: sk-pro********abc1

• Shows first 6 characters
• Shows last 4 characters
• Masks middle with 8 asterisks

Content Security Policy

The extension enforces strict CSP to prevent injection attacks:

script-src 'self';              // Only allow scripts from extension
object-src 'none';              // Block plugins
base-uri 'none';                // Prevent base tag hijacking
connect-src 'self' [APIs];      // Restrict network requests
form-action 'none';             // Prevent form submissions
frame-ancestors 'none';         // Prevent framing

Cryptographic Implementation

Encryption Process

1. Generate random 256-bit salt
2. Generate random 96-bit IV
3. Derive encryption key using PBKDF2:
   • Input: compound password (user password + device secret)
   • Salt: random salt
   • Iterations: 800,000
   • Hash: SHA-256
   • Output: 256-bit AES key
4. Encrypt plaintext using AES-256-GCM
5. Combine: salt || iv || ciphertext || auth_tag
6. Encode as base64 for storage

Decryption Process

1. Decode base64 ciphertext
2. Extract: salt, IV, ciphertext, auth tag
3. Derive decryption key using same PBKDF2 parameters
4. Decrypt and verify authentication tag
5. Return plaintext or throw DECRYPTION_ERROR

Threat Model & Mitigations

Compliance & Standards

This implementation follows:

• OWASP 2024/2025 cryptographic recommendations
• NIST SP 800-132 password-based key derivation guidelines
• Chrome Extension MV3 security best practices
• OWASP Top 10 vulnerability prevention

Security Audit Checklist

• AES-256-GCM with 128-bit authentication tag
• PBKDF2 with 800,000 iterations
• Random IV generation (96 bits)
• Random salt generation (256 bits)
• HKDF for device binding
• Rate limiting with exponential backoff
• Session timeout (configurable: 5 min to 6 hours, default 30 min)
• Inactivity timeout (configurable: 5 to 60 min, default 15 min)
• Session persistence with encrypted key storage
• Multi-level validation enforcement (UI, storage, retrieval)
• 6-hour maximum limit with security warning
• Password strength validation
• Common password rejection
• Timing attack protection
• External message blocking
• Strict Content Security Policy
• TRUSTED_CONTEXTS session storage
• Ephemeral session key encryption
• Chrome alarms for timeout persistence

Known Limitations

1. JavaScript Memory: Cannot guarantee secure memory clearing due to language limitations. Garbage collector may leave traces of decrypted keys in memory.
2. Browser Extensions: Extension storage can be accessed by users with physical access to the machine through browser developer tools (though keys are encrypted).
3. Key Recovery: If a user forgets their password, there is no recovery mechanism. This is by design - no backdoors.
4. Device Reinstall: Reinstalling the extension makes old encrypted keys permanently unrecoverable.
5. Session Persistence Trade-off: When session persistence is enabled, the ephemeral session key is stored (encrypted) in session storage rather than memory-only. While still protected by encryption and device binding, this slightly reduces security in exchange for convenience.

Reporting Security Issues

If you discover a security vulnerability in this implementation, please report it via:

• GitHub Security Advisories

Please do not disclose security issues publicly until they have been addressed.

References

• OWASP Key Management Cheat Sheet
• NIST SP 800-132: Recommendation for Password-Based Key Derivation
• Chrome Extension Security Best Practices
• Web Crypto API Documentation