SecureGen - Open-Source TOTP Authenticator, Password Manager

# The Story

## What Started This Project

I wanted a physical 2FA device that I could trust completely. Most authenticator apps live on my phone - which means they're connected to the internet, running closed-source code, and vulnerable to remote attacks. Hardware tokens like YubiKey are great, but they're expensive and you can't see your codes or manage passwords.

So I built SecureGen: an open-source hardware security device on the ESP32 T-Display that combines a TOTP authenticator with a password manager, and can type passwords directly into your computer via Bluetooth.

## How It Works

### Hardware Foundation

The device is built on the LILYGO T-Display ESP32 board, which gives us:

• Dual-core ESP32 processor with hardware AES encryption
• 1.14" color display (135x240 ST7789)
• Two physical buttons for navigation
• Built-in battery charging circuit
• WiFi and Bluetooth 5.0 LE

### Core Functionality

**TOTP Authenticator Mode:**

The device generates time-based one-time passwords (TOTP) just like Google Authenticator. After initial NTP time sync via WiFi, it works completely offline. Each code rotates every 30 seconds with a visual countdown timer.

**Password Manager Mode:**

Stores encrypted passwords locally. When you need to log in somewhere, press both buttons and the device connects via BLE HID keyboard to type your password automatically - no clipboard, no typing, no shoulder surfing.

### The Technical Challenges

**1. BLE HID Keyboard Implementation**

Getting the ESP32 to act as a Bluetooth keyboard was harder than expected. The BLE HID descriptor needed manual configuration to support all special characters (!, @, #, $, etc.). Different keyboard layouts handle symbols differently - for example, @ is Shift+2 on US layout but Shift+' on UK layout.

I implemented configurable layout mapping so users can select thei

r keyboard layout in the web interface. The device then translates each character to the correct key combination for that layout.

**2. BLE Security with LE Secure Connections**

Standard Bluetooth is not secure enough for transmitting passwords. I implemented LE Secure Connections with MITM (Man-in-the-Middle) protection using Numeric Comparison pairing.

When you pair the device, a 6-digit PIN appears on both screens (device and computer). You verify they match before confirming. This prevents anyone from intercepting the pairing process. Once paired, all communication uses AES-128 encryption at the BLE layer.

The tricky part was iOS compatibility - Apple enforces stricter security requirements than Android. I had to implement adaptive bonding parameters that detect the connecting device type and adjust security settings accordingly.

**3. Memory Management: BLE + WiFi Simultaneously**

The ESP32's BLE stack alone consumes about 70KB of RAM. When you enable WiFi, heap memory becomes critically tight. Running both simultaneously would cause random crashes.

My solution: strict mode separation. TOTP mode uses WiFi only for initial NTP sync, then disables it completely. Password manager mode runs pure offline with only BLE active. When transmitting passwords via BLE, WiFi is always off.

**4. Secure Storage on ESP32**

The ESP32's built-in NVS (Non-Volatile Storage) provides basic flash storage, but it's not encrypted by default. I added an additional AES-256 encryption layer on top of NVS.

The encryption key is generated from hardware-specific parameters (MAC address, chip ID, flash ID) combined with user's master password using PBKDF2 key derivation. This means even if someone extracts the flash chip, they can't decrypt the data without the master password.

Flash memory has limited write cycles, so I implemented wear leveling on top of the standard NVS wear leveling to extend lifespan.

**5. Web Interface Security**

The device runs a web server for configuration and management. To protect against network attacks, I implemented multiple security layers:

• **ECDH Key Exchange:** Establishes session encryption keys using elliptic curve cryptography
• **Dynamic API Endpoints:** URL paths are obfuscated using SHA-256 hashes and rotate on each reboot
• **Header Obfuscation:** HTTP headers are dynamically mapped to hide sensitive metadata
• **CSRF Protection:** Tokens prevent cross-site request forgery
• **Rate Limiting:** Prevents brute force attacks

**6. Power Optimization**

Battery life was crucial. The display is the biggest power consumer, so after 30 seconds of inactivity, the device enters light sleep mode with the display off. Button 2 wakes it instantly.

WiFi is disabled by default and only enabled when needed for time sync or web management. The ADC for battery monitoring required calibration - ESP32's ADC is quite non-linear, so I created a lookup table mapping voltage to percentage.

**7. Display After Deep Sleep**

The TFT_eSPI library had a bug where the ST7789 display wouldn't reinitialize properly after deep sleep. The GPIO states weren't being reset correctly. I had to implement a full hardware reset sequence with specific delays to reliably wake the display.

## Operating Modes

The device supports multiple modes depending on your security needs:

**Offline Mode (Air-Gapped):**

Maximum security. WiFi completely disabled, password manager works independently. Perfect for storing highly sensitive credentials.

**WiFi Client Mode (Self-Hosted):**

Connect to your home network and the device becomes an always-accessible password server - like self-hosted Bitwarden but with dedicated hardware. Access the web interface from any device on your network.

**Access Point Mode:**

Device creates its own WiFi hotspot for isolated configuration. Great for initial setup or managing the device when traveling.

## Security Philosophy

This project follows the principle of **verifiable security**. Everything is open source - you can audit the code, build it yourself, and verify there are no backdoors. The device works offline, so your secrets never touch the internet unless you explicitly connect it.

Multiple encryption layers protect your data:

• AES-256 for data at rest
• Hardware-unique device keys
• BLE encryption for wireless transmission
• Session encryption for web interface
• PIN protection for device startup

## What's Next

Current plans include:

• U2F/FIDO2 support for hardware security keys
• OTP backup to encrypted SD card
• Multi-device sync via encrypted protocol
• Custom mechanical enclosure design

The entire project is MIT licensed and available on GitHub. Pre-compiled binaries are ready to flash if you want to try it without setting up a build environment.

## Try It Yourself

You only need:

• LILYGO T-Display ESP32 board (~$5 on AliExpress)
• USB-C cable
• Optional: 3.7V LiPo battery with JST connector

Flash the firmware, set up your master password, and you have a hardware security device you can trust because you can see exactly how it works.

**GitHub:** https://github.com/Unix-like-SoN/SecureGen