• Overview
• Security Architecture
  • Dual Encryption Modes
• Cryptographic Algorithms
  • Key Derivation: PBKDF2
  • Symmetric Encryption: AES-GCM
• Key Management
  • Device Key Generation
  • Password-Based Key Derivation
• Data Structure
  • Encrypted Private Key Format
• Security Properties
  • 1. Confidentiality
  • 2. Integrity
  • 3. Authenticity
  • 4. Forward Secrecy Considerations
  • 5. Salt Protection
• Security Best Practices Implemented
  • Industry Standards
  • Key Strengths
  • Implementation Security
  • Storage Security
  • User Experience
• Attack Resistance
  • Brute Force Attacks
  • Rainbow Table Attacks
  • Dictionary Attacks
  • Replay Attacks
  • Side-Channel Attacks
• Security Considerations
  • Known Limitations
  • Security Recommendations for Users
• Compliance & Standards
  • Algorithm Standards
  • Implementation Standards
• Cryptographic Parameters Summary
• Security Audit Points
  • Code Review Checklist
• Conclusion

§Overview

This document outlines the cryptographic security measures implemented for storing and protecting Nostr private keys (nsec) in PubPay. All encryption operations use the Web Crypto API, ensuring hardware-accelerated, standards-compliant cryptographic operations.

§Security Architecture

§Dual Encryption Modes

The system supports two encryption modes, providing users with flexibility based on their security requirements:

1. Device Key Mode (Default)

   • Automatic encryption/decryption using a device-specific key
   • No user interaction required
   • Suitable for single-device usage

2. Password Mode (Optional)

   • User-defined password encryption
   • Requires password entry on each session
   • Enhanced security for multi-user or shared devices

§Cryptographic Algorithms

§Key Derivation: PBKDF2

Algorithm: PBKDF2 (Password-Based Key Derivation Function 2)
Hash Function: SHA-256
Iterations: 100,000
Output Key Length: 256 bits (32 bytes)

§Why PBKDF2?

• NIST Recommended: Approved by NIST SP 800-132
• Time-Tested: Industry standard for password-based key derivation
• Resistant to Brute Force: High iteration count (100,000) significantly increases computation time
• Salt Protection: Unique salts prevent rainbow table attacks

§Implementation Details

Device Key Mode:

• Device key: 256-bit random key stored in localStorage
• Salt: Fixed application-specific salt (pubpay-device-salt)
• Key material derived from device key via PBKDF2

Password Mode:

• Salt: 128-bit (16 bytes) randomly generated per encryption
• Salt stored alongside encrypted data (not secret)
• Unique salt per encryption prevents cross-user attacks

§Symmetric Encryption: AES-GCM

Algorithm: AES (Advanced Encryption Standard)
Mode: GCM (Galois/Counter Mode)
Key Size: 256 bits
IV Length: 96 bits (12 bytes)

§Why AES-GCM?

• NIST Standard: FIPS 140-2 approved
• Authenticated Encryption: Provides both confidentiality and authenticity
• Performance: Hardware-accelerated on modern CPUs
• Security: Proven secure against various attack vectors

§GCM Mode Benefits

• Authentication: Detects tampering automatically
• No Padding Oracle Attacks: Unlike CBC mode, GCM is resistant to padding attacks
• Parallelizable: Efficient for high-performance scenarios
• Standard IV Size: 96-bit IV is NIST recommended

§Implementation Details

• IV Generation: Cryptographically secure random IV for each encryption
• IV Storage: IV stored alongside ciphertext (standard practice for GCM)
• No IV Reuse: Each encryption uses a unique random IV

§Key Management

§Device Key Generation

// Generate random 256-bit key
const keyBytes = crypto.getRandomValues(new Uint8Array(32));

• Source: crypto.getRandomValues() (cryptographically secure PRNG)
• Length: 256 bits (32 bytes)
• Storage: Base64-encoded in localStorage under key _dk
• Persistence: Survives browser sessions until explicit logout
• Isolation: Separate from encrypted data storage

§Password-Based Key Derivation

PBKDF2(password, salt, 100000 iterations, SHA-256) → 256-bit AES key

• Input: User-provided password (variable length)
• Salt: 128-bit random per encryption
• Output: 256-bit AES key suitable for encryption

§Data Structure

§Encrypted Private Key Format

interface EncryptedPrivateKey {
  encrypted: string;    // Base64-encoded ciphertext
  salt: string;         // Base64-encoded salt (128-bit)
  iv: string;           // Base64-encoded initialization vector (96-bit)
  hasPassword: boolean; // Encryption mode flag
}

Storage Format: JSON-serialized in localStorage

§Security Properties

§1. Confidentiality

• Private keys are never stored in plaintext
• Encrypted using industry-standard AES-256-GCM
• Keys derived using PBKDF2 with high iteration count

§2. Integrity

• AES-GCM provides built-in authentication
• Tampering with encrypted data is automatically detected
• Decryption fails if data is modified

§3. Authenticity

• GCM authentication tag verifies data origin
• Prevents unauthorized modifications

§4. Forward Secrecy Considerations

• Each encryption uses unique IV
• Device key can be cleared to invalidate all encrypted data
• Password changes require re-encryption

§5. Salt Protection

• Password Mode: Unique 128-bit salt per encryption
  • Prevents rainbow table attacks
  • Prevents cross-user key derivation attacks
  • Even identical passwords produce different ciphertexts
• Device Key Mode: Application-specific fixed salt
  • Appropriate for device-bound encryption
  • Prevents key derivation from device key alone

§Security Best Practices Implemented

§Industry Standards

• NIST-approved algorithms: AES-256, PBKDF2, SHA-256
• Web Crypto API: Browser-native, hardware-accelerated
• No custom crypto: Uses only standardized, reviewed algorithms

§Key Strengths

• 256-bit keys: Meets current security requirements (128-bit considered minimum)
• 100,000 PBKDF2 iterations: Significantly above minimum recommendations
• Random IVs: Cryptographically secure random generation

§Implementation Security

• No key material in code: All keys derived or randomly generated
• Secure random generation: Uses crypto.getRandomValues() (CSPRNG)
• No key logging: Keys never logged or exposed in error messages
• Error handling: Cryptographically safe error messages (no information leakage)

§Storage Security

• Local storage only: Data never transmitted to servers
• Encrypted at rest: All private keys encrypted before storage
• Metadata separation: Encryption mode flag stored separately from sensitive data

§User Experience

• Optional password: Users choose security level
• Automatic device key mode: Seamless for single-device users
• Password validation: Clear feedback on incorrect passwords
• Legacy migration: Automatic upgrade from plaintext to encrypted format

§Attack Resistance

§Brute Force Attacks

• Password Mode: 100,000 PBKDF2 iterations + unique salts
  • Estimated time: ~milliseconds per attempt (on modern hardware)
  • 128-bit salt space: 2^128 possible salt values
  • Practical brute force: Computationally infeasible
• Device Key Mode: 256-bit key space
  • Brute force: 2^256 operations (computationally infeasible)

§Rainbow Table Attacks

• Prevented: Unique salts per encryption
• Effect: Even identical passwords produce different ciphertexts

§Dictionary Attacks

• Mitigated: High iteration count (100,000)
• Mitigated: Unique salts prevent pre-computation
• User Responsibility: Strong passwords recommended

§Replay Attacks

• Prevented: Unique IVs per encryption
• GCM Authentication: Detects reused IVs

§Side-Channel Attacks

• Mitigated: Web Crypto API uses hardware-accelerated, constant-time operations
• Browser Security: Implementation details hidden from JavaScript

§Security Considerations

§Known Limitations

1. Browser Storage Security

   • Data stored in localStorage (not encrypted filesystem)
   • Vulnerable to XSS attacks if application is compromised
   • Mitigated by: Content Security Policy, input sanitization

2. Device Key Persistence

   • Device key survives browser clear data (unless explicitly cleared)
   • User can manually clear _dk to invalidate all encrypted data
   • Design choice: Balance security vs. user experience

3. Password Strength

   • No enforced password complexity requirements
   • User responsibility to choose strong passwords
   • Recommended: 12+ characters, mix of character types

4. Memory Security

   • Decrypted keys briefly in JavaScript memory
   • Memory may be accessible to browser extensions
   • Standard limitation of browser-based cryptography

§Security Recommendations for Users

1. Use Password Mode for:

   • Shared devices
   • High-value accounts
   • Multi-user environments

2. Use Device Key Mode for:

   • Personal devices
   • Single-user scenarios
   • Convenience-focused usage

3. Best Practices:

   • Use strong, unique passwords (12+ characters)
   • Enable password mode on shared devices
   • Regularly clear browser data if device is compromised
   • Log out explicitly when finished

§Compliance & Standards

§Algorithm Standards

• AES: FIPS 197, ISO/IEC 18033-3
• PBKDF2: RFC 2898, NIST SP 800-132
• SHA-256: FIPS 180-4, NIST approved
• AES-GCM: NIST SP 800-38D

§Implementation Standards

• Web Crypto API: W3C Web Cryptography API
• Key Derivation: OWASP recommendations followed
• IV Generation: NIST guidelines (96-bit for GCM)

§Cryptographic Parameters Summary

§Security Audit Points

§Code Review Checklist

• No hardcoded keys or secrets
• No key material in logs or error messages
• Proper error handling (no information leakage)
• Secure random number generation
• Proper key derivation (PBKDF2 with high iterations)
• Authenticated encryption (AES-GCM)
• Unique IVs per encryption
• Unique salts per password encryption
• No key reuse across different encryptions

§Conclusion

This implementation follows industry-standard cryptographic practices, using NIST-approved algorithms and the Web Crypto API for hardware-accelerated, secure operations. The dual-mode approach provides flexibility while maintaining strong security guarantees. All encryption operations are performed client-side, ensuring private keys never leave the user’s device in decrypted form.

Security Level: Production-Ready
Algorithm Maturity: Industry Standard
Compliance: NIST, FIPS, RFC Standards

Last Updated: Nov 2025

Built with 💜 by the @PUBPAY.me team