SecureBox - Hardware Password Manager

Secure hardware password manager based on ESP32-S3 with external encrypted storage.

---

Quick Start

IMPORTANT: First read → GETTING_STARTED.md

Step by Step:

1. Upload firmware:

   • Open Arduino IDE
   • Upload: SecureBox_Internal/SecureBox_Internal.ino

2. Test connection:

   cd SecureBoxApps
   python test_securebox.py

3. Run application:

   # GUI
   python gui-tkinter/securebox_gui.py
   
   # OR Web
   python web-flask/app.py

---

Documentation

Document	Purpose
GETTING_STARTED.md	START HERE! Complete setup guide
SECURITY_ANALYSIS.md	Complete security analysis
QUICK_REFERENCE.md	Quick reference guide

---

What is SecureBox?

SecureBox is a hardware password manager that:

• Stores up to 100 passwords offline
• Encrypts using AES-256-GCM
• Works without cloud (100% offline)
• Connects via USB, Bluetooth, WiFi
• Has GUI and Web applications

---

Security

Encryption:

• AES-256-GCM (military-grade standard)
• PBKDF2 (100,000 iterations against brute-force)
• Two-layer encryption: KEK → DEK → Database

Storage:

• External flash chip W25Q128 (16 MB)
• Encrypted database on 8 MB partition
• No backdoors - open-source code

Resilience:

• Brute-force: practically impossible (with strong password)
• Dictionary attack: slowed down by PBKDF2
• Physical access: encrypted, but depends on password strength

Details: SECURITY_ANALYSIS.md

---

Hardware Requirements

Hardware:

• ESP32-S3 (Mini / DevKit)
• W25Q128 SPI Flash chip (16 MB)
• USB cable

Software:

• Arduino IDE 2.x
• Python 3.8+
• Libraries: pyserial, tkinter, flask

---

Project Structure

PasswordBox/
├── SecureBox/                    # Production firmware (clean)
├── SecureBox_Internal/          # Internal firmware (USE THIS!)
├── SecureBoxWebServer/          # WiFi-only firmware (optional)
├── SecureBoxApps/
│   ├── gui-tkinter/             # GUI application (Python)
│   ├── web-flask/               # Web application (Flask)
│   ├── shared/                  # API library
│   └── test_securebox.py        # Universal test
├── GETTING_STARTED.md           # START HERE!
├── SECURITY_ANALYSIS.md         # Security analysis
├── QUICK_REFERENCE.md           # Quick reference
└── README.md                    # This file

---

Features

Applications (2):

1. GUI (Tkinter):

• Clean password table
• Device info panel (entries, memory, used space)
• Password statistics (strong/weak)
• Password generator
• Copy to clipboard

2. Web (Flask):

• Modern Bootstrap UI
• Runs locally: http://localhost:5000
• All features like GUI
• API for custom integrations

For Each Entry:

• Service name (64 characters)
• Username (128 characters)
• Password (128 characters)
• Note (256 characters)

---

Security Recommendations

YOU MUST:

1. Use STRONG master password (12+ chars, mixed)
2. Always LOCK before disconnecting USB
3. Keep device in a secure place

NEVER:

1. Don't use weak passwords (1234, password...)
2. Don't leave unlocked unattended
3. Don't share master password

Example STRONG password:

Tr0mb0n#2024!Secure
MyP@ssw0rd$2024$
Qwerty!12#Uiop$34

---

How to Wipe Data

Via Application:

Connect → Unlock → Wipe Database

Complete Erase:

1. Chip Erase (erases entire flash)
2. Physical destruction of flash chip (100% certain)

Details: SECURITY_ANALYSIS.md

---

Troubleshooting

Problem	Solution
Password doesn't work	Upload fixed firmware, run test
Application doesn't connect	Close other apps, check COM port
INFO doesn't display	Must be UNLOCKED, check firmware

Complete guide: GETTING_STARTED.md

---

Technical Details

Encryption:

• Algorithm: AES-256-GCM
• Key derivation: PBKDF2-HMAC-SHA256
• Iterations: 100,000
• Salt: 32 bytes (random, unique)
• KEK: 256 bits (derived from password)
• DEK: 256 bits (random, encrypted by KEK)

Storage:

• Flash chip: W25Q128 (16 MB)
• Partition table:
  • 0x000000-0x7FFFFF: MSC Image (8 MB) - unused
  • 0x800000-0xFFFFFF: Encrypted DB (8 MB)
• Max. entries: 100
• Entry size: 513 bytes
• Total DB: ~51 KB

Communication:

• USB CDC: Serial (115200 baud)
• BLE: Nordic UART Service
• WiFi: HTTP API (192.168.4.1)

---

Security Analysis

No Backdoors:

• Reviewed entire codebase
• No hardcoded passwords
• No telemetry/cloud
• 100% offline

Risks:

1. Weak password → brute-force possible
2. Physical access → can extract flash
3. RAM persistence → disconnect USB to reset

Protection:

• Strong master password (12+ chars)
• Always LOCK before disconnecting
• Physical security of device

Complete analysis: SECURITY_ANALYSIS.md

---

License

MIT License - See LICENSE file for details.

Use at your own risk. For critical use, I recommend certified solutions.

---

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details.

---

Support

Documentation:

• GETTING_STARTED.md - Complete guide
• SECURITY_ANALYSIS.md - Security
• QUICK_REFERENCE.md - Quick reference

Test:

python SecureBoxApps/test_securebox.py

---

Start here: GETTING_STARTED.md