Skip to content

PRIVATE_KEY_SECURITY.md

Latest commit

 

History

History
199 lines (136 loc) · 7.51 KB

PRIVATE_KEY_SECURITY.md

File metadata and controls

199 lines (136 loc) · 7.51 KB

Private Key Import/Export Security Documentation

Overview

This document outlines the security measures implemented for the private key import/export functionality in QryptChat. The implementation follows industry best practices for secure key management and cryptographic operations.

Security Features Implemented

1. Password-Based Key Derivation (PBKDF)

  • Implementation: Uses HKDF (HMAC-based Key Derivation Function) with SHA-256
  • Salt: Each export uses a unique, cryptographically secure random salt (32 bytes)
  • Purpose: Derives a strong encryption key from user-provided passwords
  • Protection: Prevents rainbow table attacks and ensures unique keys even with identical passwords

2. Authenticated Encryption

  • Algorithm: ChaCha20-Poly1305 (quantum-resistant symmetric encryption)
  • Nonce: Each export uses a unique, cryptographically secure random nonce (12 bytes)
  • Authentication: Built-in authentication prevents tampering with encrypted data
  • Benefits: Provides both confidentiality and integrity protection

3. Secure Random Number Generation

  • Source: Uses crypto.getRandomValues() for all random data generation
  • Applications:
    • Salt generation (32 bytes)
    • Nonce generation (12 bytes)
    • Key generation (32 bytes)
  • Quality: Cryptographically secure pseudorandom number generator (CSPRNG)

4. Memory Security

  • Secure Clearing: Sensitive data is cleared from memory using CryptoUtils.secureClear()
  • Scope: Applied to:
    • Derived encryption keys
    • Password bytes
    • Decrypted key material
  • Purpose: Prevents sensitive data from lingering in memory

5. Input Validation and Sanitization

  • Password Requirements: Minimum 8 characters (enforced in UI)
  • File Format Validation: Strict JSON schema validation for import files
  • Version Compatibility: Checks export format version to prevent incompatible imports
  • Error Handling: Secure error messages that don't leak sensitive information

6. Export Format Security

{
  "version": "1.0",
  "timestamp": 1693123456789,
  "encryptedKeys": "base64-encoded-encrypted-data",
  "salt": "base64-encoded-salt",
  "nonce": "base64-encoded-nonce"
}
  • Versioning: Allows for future format upgrades while maintaining compatibility
  • Timestamp: Helps with key lifecycle management
  • Base64 Encoding: Safe transport encoding for binary data

7. Client-Side Only Operations

  • Local Processing: All encryption/decryption happens in the browser
  • No Server Storage: Private keys never leave the user's device during export/import
  • Zero-Knowledge: Server has no access to user's private keys or passwords

Security Best Practices Followed

1. Defense in Depth

  • Multiple layers of security (encryption, authentication, validation)
  • Fail-safe defaults (secure by default configuration)
  • Principle of least privilege (minimal required permissions)

2. Cryptographic Standards

  • NIST Approved: ChaCha20-Poly1305 is NIST-approved for government use
  • Quantum Resistant: ChaCha20-Poly1305 provides post-quantum security
  • Key Sizes: Uses appropriate key sizes (256-bit keys, 96-bit nonces)

3. Error Handling

  • Information Disclosure: Error messages don't reveal sensitive information
  • Graceful Degradation: Failures don't compromise security
  • Logging: Security events are logged without exposing sensitive data

4. User Experience Security

  • Password Visibility Toggle: Allows users to verify password entry
  • Confirmation Fields: Prevents typos in critical operations
  • Clear Warnings: Users are informed about security implications
  • File Validation: Immediate feedback on invalid import files

Threat Model Coverage

1. Passive Attacks

  • Eavesdropping: Encrypted exports are safe even if intercepted
  • Traffic Analysis: No network traffic contains sensitive key material
  • Storage Analysis: Exported files are encrypted and authenticated

2. Active Attacks

  • Man-in-the-Middle: Not applicable (client-side only operations)
  • Tampering: ChaCha20-Poly1305 authentication prevents modification
  • Replay Attacks: Unique nonces prevent replay of encrypted data

3. Offline Attacks

  • Brute Force: HKDF with salt makes password cracking computationally expensive
  • Dictionary Attacks: Salt prevents precomputed dictionary attacks
  • Rainbow Tables: Unique salts make rainbow tables ineffective

4. Implementation Attacks

  • Side Channel: Uses constant-time operations where possible
  • Memory Disclosure: Sensitive data is cleared from memory
  • Timing Attacks: Validation uses constant-time comparison

Compliance and Standards

1. Industry Standards

  • OWASP: Follows OWASP cryptographic storage guidelines
  • NIST: Uses NIST-approved cryptographic algorithms
  • RFC Standards: Implements RFC-compliant HKDF and ChaCha20-Poly1305

2. Regulatory Considerations

  • GDPR: User controls their own key export/import (data portability)
  • Privacy: No sensitive data is transmitted to servers
  • Audit Trail: Operations are logged for security monitoring

Testing and Validation

1. Unit Tests

  • Cryptographic Functions: All crypto operations are thoroughly tested
  • Edge Cases: Tests cover error conditions and boundary cases
  • Security Properties: Tests verify encryption, authentication, and key derivation

2. Integration Tests

  • End-to-End: Complete export/import workflows are tested
  • Cross-Platform: Tests ensure compatibility across different environments
  • Error Scenarios: Tests verify secure error handling

3. Security Testing

  • Fuzzing: Input validation is tested with malformed data
  • Negative Testing: Tests verify rejection of invalid inputs
  • Timing Analysis: Operations are tested for timing consistency

Recommendations for Users

1. Password Security

  • Use strong, unique passwords for key exports
  • Consider using a password manager
  • Don't reuse passwords from other services
  • Store passwords securely and separately from exported files

2. File Security

  • Store exported key files in secure locations
  • Consider additional encryption for long-term storage
  • Regularly rotate and re-export keys
  • Securely delete old export files

3. Operational Security

  • Verify file integrity before importing
  • Use trusted devices for key operations
  • Keep software updated
  • Monitor for unauthorized access attempts

Future Enhancements

1. Potential Improvements

  • Hardware Security: Integration with hardware security modules (HSMs)
  • Multi-Factor: Additional authentication factors for key operations
  • Key Escrow: Optional secure key backup services
  • Audit Logging: Enhanced security event logging

2. Cryptographic Upgrades

  • Post-Quantum: Migration to post-quantum key exchange algorithms
  • Algorithm Agility: Support for multiple encryption algorithms
  • Key Rotation: Automated key rotation capabilities

Conclusion

The private key import/export functionality implements robust security measures that protect user keys throughout the export/import process. The implementation follows industry best practices and provides strong protection against both passive and active attacks while maintaining usability for end users.

All cryptographic operations use well-established, secure algorithms and are implemented following security best practices. The client-side-only approach ensures that sensitive key material never leaves the user's control, providing maximum security and privacy.