PubPay Cryptographic Security Implementation Summary

Francis Mars

4. November 2025November 4, 2025 · 8 Min. Lesezeit8 min read

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?

Implementation Details

Device Key Mode:

Password Mode:

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?

GCM Mode Benefits

Implementation Details

Key Management#

Device Key Generation#

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

Password-Based Key Derivation#

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

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#

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#

  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#

Implementation Standards#

Cryptographic Parameters Summary#

Parameter Value Standard
Encryption Algorithm AES-256-GCM NIST, FIPS
Key Derivation PBKDF2 RFC 2898, NIST SP 800-132
Hash Function SHA-256 FIPS 180-4
PBKDF2 Iterations 100,000 OWASP Recommended
Key Length 256 bits NIST Approved
IV Length 96 bits (12 bytes) GCM Standard
Salt Length 128 bits (16 bytes) Industry Standard
Device Key Length 256 bits NIST Approved
Random Source crypto.getRandomValues() W3C Web Crypto API

Security Audit Points#

Code Review Checklist#

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

Written by

Francis Mars

francismars.com • chainduel.net • pubpay.me

Comments

No comments yet. Start the conversation.

Contents

13 sections

  1. Overview
  2. Security Architecture
  3. Cryptographic Algorithms
  4. Key Management
  5. Data Structure
  6. Security Properties
  7. Security Best Practices Implemented
  8. Attack Resistance
  9. Security Considerations
  10. Compliance & Standards
  11. Cryptographic Parameters Summary
  12. Security Audit Points
  13. Conclusion