Forem: makepkg

SecureGen v2.0 + v2.1 — What We Built Over the Last Few Months

makepkg — Sat, 21 Mar 2026 17:25:20 +0000

If you haven't seen SecureGen before — it's an open-source hardware security device on the LILYGO T-Display ESP32. TOTP/HOTP authenticator, encrypted password manager, BLE HID keyboard, and a web management cabinet with 8 layers of application-level security. No cloud, no app, no trust required.

Two major releases dropped since the last post. Here's what changed and why it was technically interesting.

v2.0.0 — The Security Rewrite

AES-256-GCM Transport Encryption

The original web transport used XOR — fast to implement, completely wrong for production. v2.0 replaced it with a full ECDH P-256 key exchange + HKDF-derived AES-256-GCM session key. Every request and response body is now encrypted end-to-end, with GCM providing authenticated encryption — tampered data is rejected, not just unreadable.

This runs without TLS certificates. The device has no CA infrastructure, no HTTPS, and works in AP mode with no internet. The encrypted channel is entirely application-layer.

PIN-Encrypted Device Key

Before v2.0, the master device key was derived from hardware parameters only (MAC, chip ID, flash ID). Useful but insufficient — physical access to the chip meant access to the key material.

Now the key is encrypted with the user's PIN via PBKDF2-HMAC-SHA256 at 25,000 iterations. The PIN never leaves the device. Without it, the encrypted key file on LittleFS is useless even if the flash is extracted.

Persistent PIN Lockout

Five failed PIN attempts across reboots locks the device permanently. The attempt counter survives power cycles — stored encrypted in LittleFS. No soft resets to bypass it.

Secure Memory Wipe Before Deep Sleep

Before entering deep sleep, the device zeroes device key, TOTP secrets, passwords, and session keys from RAM. On wake, everything requires re-authentication. This prevents cold boot attacks on battery-powered devices.

HOTP Support

Counter-based OTP (RFC 4226) added alongside TOTP. HOTP works in Offline and AP modes — no time sync required. Hold both buttons on the HOTP screen to generate the next code. The counter increments atomically and is written to flash after button release, preventing desync on battery power.

QR Code Import / Export

Add TOTP keys by scanning a QR code (camera or file upload) directly in the web cabinet. Export any key as a QR code displayed on the TFT screen. The offline decrypt_export.html tool lets you decrypt, inspect, and edit key files without the device connected.

v2.1.0 — Stability, Hardware, and UX

DS3231 RTC Module Support

TOTP requires accurate time. Without WiFi there's no NTP. The solution: a DS3231 hardware clock module (I2C, SDA=21/SCL=22, ~$2 on AliExpress) that maintains ±2ppm accuracy independently of network connectivity.

With RTC connected, TOTP works correctly in AP mode and fully air-gapped Offline mode. The module is configured once via the web cabinet — it keeps time even when the device is off.

Light Sleep Crash Fix

This one was subtle. On battery power, esp_light_sleep_start() caused a crash-on-wake via GPIO0 hardware interaction. The fix: pseudo-sleep — CPU clocked down to 40 MHz, display suspended, peripherals held. Functionally identical sleep behavior, no crash.

Boot Mode System

Three network modes are now first-class: WiFi, AP, and Offline. The default is saved to config and applied on boot. A 2-second prompt at startup lets you override with button presses.

"Reboot with Web Server" button in the web cabinet now works correctly even when boot mode is set to Offline — it sets a one-shot flag that bypasses the mode prompt entirely and forces WiFi on next boot.

Navigation Guard

The web cabinet fires ~4 encrypted requests during initialization (keys, PIN settings, theme, battery). Switching tabs before these complete broke the UI state.

Fix: async IIFE runs all init requests sequentially, sets appInitialized = true when done. Tab switching is blocked with a localized toast until initialization completes. No parallel requests — ESP32 async web server doesn't handle simultaneous encrypted sessions well under memory pressure.

Multilingual Interfac

Web cabinet now supports English, Russian, German, Chinese (Simplified), and Spanish. Language selection persists via localStorage. All UI strings go through tr() — adding a new language is one object in the i18n map.

Bug Fixes Worth Noting

HOTP display corruption. When switching from a TOTP key to an HOTP key, the old progress bar rendered on top of "HOTP - Static Code" text. Root cause: drawLayout() set lastTimeRemaining = -999 as a sentinel, but updateTOTPCode(-1) saw -1 != -999 as true only once — after that -1 == -1 skipped the redraw. Fix: eraseLoaderArea() also resets lastTimeRemaining = -999, forcing a full redraw after the loader completes.

HOTP notification showed "TOTP code copied". The copy handler checked keysData[index].type === 'hotp' — but the actual field is keysData[index].t === 'H'. One character difference, wrong notification for every HOTP copy.

Password reorder endpoint. The /api/passwords/reorder endpoint was registered in 4 of the required 6 locations — missing from both tunnel dispatchers. Requests tunneled through the obfuscated endpoint silently failed. Added to both dispatchers following the existing pattern.

Drag-and-drop key reorder mixed up timer/progress elements. DOM rows were physically moved but element IDs (timer-0, progress-0) stayed bound to old positions. Fix: call updateKeysTable(keysData) after every drag-drop to rebuild the table with correct IDs.

What's Next

ECDH P-256 → X25519 migration (~400ms → ~80ms key exchange)
Port to T-Display S3 (PSRAM, USB HID, larger screen)
Flash encryption and secure boot via sdkconfig
ATECC608 secure element support

Flash from browser (Chrome/Edge): https://makepkg.github.io/SecureGen/flash

GitHub: https://github.com/makepkg/SecureGen

Hackster.io: https://www.hackster.io/makepkg/securegen-open-source-totp-authenticator-password-manager-c350d6

Building an 8-Layer Security Architecture for a $15 Hardware Device

makepkg — Sun, 15 Feb 2026 20:29:05 +0000

Building an 8-Layer Security Architecture for a $15 Hardware Device

When you're building a hardware password manager, security isn't optional—it's the entire point.

But how do you secure a $15 ESP32 device that stores sensitive data? The answer: defense in depth.

In this post, I'll break down the 8-layer security architecture I built for SecureGen, a hardware TOTP authenticator and password manager. Each layer defends against different attack types, ensuring that breaching one layer doesn't compromise the system.

![8 Security Layers Architecture](

Why 8 Layers?

Single-layer security is a single point of failure.

If your only protection is encryption and the key gets leaked, game over. If your only protection is authentication and credentials get phished, you're done.

Defense in depth means attackers need to bypass multiple independent layers. Each layer:

Targets different attack vectors
Uses different techniques
Fails independently
Slows down attackers

Let's break down each layer.

Layer 1: ECDH Key Exchange 🔐

The Problem

Passwords and TOTP secrets need to be encrypted. But if you hardcode encryption keys, anyone with the source code can decrypt your data.

The Solution

Generate unique encryption keys dynamically using Elliptic Curve Diffie-Hellman (ECDH) with the P-256 curve.

How It Works

// Generate ephemeral key pair
mbedtls_ecdh_context ctx;
mbedtls_ecdh_setup(&ctx, MBEDTLS_ECP_DP_SECP256R1);  // P-256
mbedtls_ecdh_gen_public(&ctx, &olen, public_key, 65, 
                        mbedtls_ctr_drbg_random, &ctr_drbg);

// Compute shared secret
mbedtls_ecdh_calc_secret(&ctx, &olen, shared_secret, 32,
                         mbedtls_ctr_drbg_random, &ctr_drbg);

// Derive encryption key
mbedtls_sha256(shared_secret, 32, encryption_key, 0);

What this prevents: Man-in-the-middle (MITM) attacks

Even if someone intercepts the traffic during key exchange, they can't compute the shared secret without the private keys. And since keys are ephemeral (generated per session), they can't be reused.

Real-World Impact

Before ECDH:

[Attacker intercepts traffic]
→ Attacker sees: Encrypted data with static key
→ Attacker bruteforces key offline
→ Game over

After ECDH:

[Attacker intercepts traffic]
→ Attacker sees: Public keys (useless without private)
→ Attacker can't compute shared secret
→ Encrypted data remains secure

Layer 2: Session Encryption 🔒

The Problem

Bluetooth (BLE) has built-in encryption, but it's not enough for sensitive data like passwords.

The Solution

Double encryption: AES-128 at the BLE layer + AES-256 at the application layer.

How It Works

// BLE layer (automatic)
esp_ble_gap_set_security_param(ESP_BLE_SM_AUTHEN_REQ_MODE, 
                                &auth_req, sizeof(uint8_t));
auth_req = ESP_LE_AUTH_REQ_SC_MITM_BOND;  // AES-128

// Application layer (manual)
void encrypt_password(const char* password, uint8_t* output) {
    mbedtls_aes_context aes;
    mbedtls_aes_setkey_enc(&aes, session_key, 256);  // AES-256

    uint8_t iv[16];
    esp_fill_random(iv, 16);  // Random IV per encryption

    mbedtls_aes_crypt_cbc(&aes, MBEDTLS_AES_ENCRYPT, 
                          strlen(password), iv, 
                          (uint8_t*)password, output);
}

What this prevents: Eavesdropping and packet sniffing

Even if an attacker breaks BLE encryption (unlikely but possible), they still face AES-256 application-layer encryption.

Real-World Impact

Single encryption:

[BLE vulnerability discovered]
→ Attacker breaks BLE encryption
→ Passwords visible in plaintext
→ Total compromise

Double encryption:

[BLE vulnerability discovered]
→ Attacker breaks BLE encryption
→ Attacker sees: More encrypted data (AES-256)
→ Passwords still secure

Layer 3: Dynamic API Endpoints 🎲

The Problem

Static API endpoints are easy targets for automated scanners. Tools like dirb, gobuster, and nikto can discover them in seconds.

The Solution

Obfuscate endpoint URLs using SHA-256 and change them on every device boot.

How It Works

// Generate dynamic endpoint
String generate_endpoint(const char* base, uint32_t seed) {
    char hash_input[64];
    snprintf(hash_input, sizeof(hash_input), "%s-%u", base, seed);

    uint8_t hash[32];
    mbedtls_sha256((uint8_t*)hash_input, strlen(hash_input), hash, 0);

    char endpoint[65];
    for(int i = 0; i < 32; i++) {
        sprintf(&endpoint[i*2], "%02x", hash[i]);
    }

    return String("/") + String(endpoint);
}

// Real endpoint on device
uint32_t boot_seed = esp_random();
String totp_endpoint = generate_endpoint("totp", boot_seed);
// Result: /a7f3c9e8b2d4f1a6c8e5d7f9b3a1c5e8d2f4a6b8c0e2d4f6a8b0c2e4f6a8b0c2

What this prevents: Automated API discovery and vulnerability scanning

Scanners expect endpoints like /api/totp or /passwords. When they get /a7f3c9e8b2d4f1a6..., they don't know what it does without manual analysis.

Real-World Impact

Before (static endpoints):

$ gobuster dir -u http://device.local -w wordlist.txt
Found: /api/totp
Found: /api/passwords
Found: /api/admin

[Automated exploit tools target these]

After (dynamic endpoints):

$ gobuster dir -u http://device.local -w wordlist.txt
No matches found

[Attacker needs to reverse-engineer endpoint generation]

Layer 4: Header Obfuscation 🎭

The Problem

HTTP headers reveal your tech stack. Headers like Server: nginx/1.18.0 or X-Powered-By: Express 4.17.1 tell attackers exactly which vulnerabilities to target.

The Solution

Dynamically map and obfuscate all HTTP headers. Hide metadata.

How It Works

// Header mapping (changes per session)
std::map header_map;

void init_header_obfuscation() {
    header_map["Content-Type"] = "X-" + random_string(8);
    header_map["Authorization"] = "X-" + random_string(8);
    header_map["Server"] = "X-" + random_string(8);
}

void send_response(AsyncWebServerRequest *request, String content) {
    AsyncWebServerResponse *response = request->beginResponse(200, 
        header_map["Content-Type"], content);

    // Remove revealing headers
    response->addHeader(header_map["Server"], "Unknown");

    // Add fake misleading headers
    response->addHeader("X-AspNetMvc-Version", "5.2.7");  // Not using ASP.NET
    response->addHeader("X-Powered-By", "PHP/7.4.3");     // Not using PHP

    request->send(response);
}

What this prevents: Tech stack fingerprinting and targeted exploits

Real-World Impact

Before:

HTTP/1.1 200 OK
Server: ESP-AsyncWebServer/1.2.3
Content-Type: application/json
X-ESP32-Chip: ESP32-D0WDQ6

[Attacker knows: ESP32, specific library versions]
[Searches for CVEs in those versions]

After:

HTTP/1.1 200 OK
X-k8f3a2: application/json
X-9e4c7: Unknown
X-AspNetMvc-Version: 5.2.7
X-Powered-By: PHP/7.4.3

[Attacker sees: Conflicting information]
[Wastes time targeting wrong stack]

Layer 5: Anti-Fingerprinting 👻

The Problem

Even without obvious headers, devices can be fingerprinted by response patterns, timing, and behaviors.

The Solution

Inject fake headers, randomize response patterns, and make the device appear different on each request.

How It Works

void add_fingerprint_confusion(AsyncWebServerResponse *response) {
    // Random fake headers
    const char* fake_frameworks[] = {
        "Django/3.2.4", "Rails/6.1.3", "Laravel/8.40.0", 
        "Express/4.17.1", "Spring/5.3.8"
    };

    response->addHeader("X-Framework", 
        fake_frameworks[esp_random() % 5]);

    // Randomize response time (within reason)
    delay(esp_random() % 50 + 10);  // 10-60ms

    // Vary content encoding
    if(esp_random() % 2) {
        response->addHeader("Content-Encoding", "gzip");
    }

    // Change protocol hints
    response->addHeader("Vary", "Accept-Encoding, User-Agent, Accept-Language");
}

What this prevents: Device fingerprinting and traffic analysis

Real-World Impact

Before:

Request 1: Response in 45ms, Server: ESP32
Request 2: Response in 44ms, Server: ESP32
Request 3: Response in 46ms, Server: ESP32

[Pattern: ESP32 device, consistent timing]
[Attacker: "I know what this is"]

After:

Request 1: Response in 23ms, Framework: Django
Request 2: Response in 51ms, Framework: Rails  
Request 3: Response in 18ms, Framework: Laravel

[Pattern: Inconsistent, conflicting data]
[Attacker: "What the hell is this thing?"]

Layer 6: Honey Pot 🍯

The Problem

You want to know if someone is trying to break in. Passive defenses are invisible.

The Solution

Create fake "vulnerable" endpoints that look tempting but are actually traps. Log all access attempts.

How It Works

// Honey pot endpoints
server.on("/admin", HTTP_GET, [](AsyncWebServerRequest *request){
    log_intrusion_attempt(request->client()->remoteIP().toString(), 
                          "/admin", "Unauthorized access attempt");

    // Return realistic fake data
    String fake_response = R"({
        "users": [
            {"username": "admin", "role": "superuser"},
            {"username": "root", "role": "admin"}
        ],
        "version": "2.4.1",
        "debug": true
    })";

    request->send(200, "application/json", fake_response);
});

server.on("/api/users", HTTP_GET, [](AsyncWebServerRequest *request){
    // Check for SQL injection attempts
    String query = request->arg("id");
    if(query.indexOf("OR 1=1") != -1 || query.indexOf("'") != -1) {
        log_intrusion_attempt(request->client()->remoteIP().toString(),
                              "/api/users", "SQL injection attempt detected");
    }

    request->send(200, "application/json", "[]");  // Empty response
});

// Path traversal trap
server.on("/../../etc/passwd", HTTP_GET, [](AsyncWebServerRequest *request){
    log_intrusion_attempt(request->client()->remoteIP().toString(),
                          request->url(), "Path traversal attempt");

    // Fake passwd file
    String fake_passwd = "root:x:0:0:root:/root:/bin/bash\n"
                         "admin:x:1000:1000:Admin:/home/admin:/bin/bash\n";
    request->send(200, "text/plain", fake_passwd);
});

What this prevents: Brute force attacks and automated exploitation

Real-World Impact

[Attacker scans device]
Attacker: "/admin endpoint found! Jackpot!"
[Accesses /admin]

[Device logs]
IP: 192.168.1.100
Endpoint: /admin
Time: 2026-02-15 14:23:11
User-Agent: python-requests/2.28.1
Action: Rate limited + alerted via web interface

[Attacker wastes time on fake data]
[You get early warning + attacker's IP]

Layer 7: Method Tunneling 🔀

The Problem

Many automated scanners look for specific HTTP methods (GET, POST, DELETE) on endpoints.

The Solution

Tunnel all requests through POST with an encrypted method field. Mask the real HTTP method.

How It Works

// Client-side (JavaScript)
async function apiRequest(endpoint, method, data) {
    const encrypted_method = await encrypt(method, session_key);

    const response = await fetch(endpoint, {
        method: 'POST',  // Always POST
        headers: {
            'Content-Type': 'application/json',
            'X-Method': encrypted_method  // Real method hidden here
        },
        body: JSON.stringify(data)
    });

    return response.json();
}

// Server-side (ESP32)
server.on("/api/*", HTTP_POST, [](AsyncWebServerRequest *request){
    String encrypted_method = request->header("X-Method");
    String real_method = decrypt_method(encrypted_method);

    if(real_method == "GET") {
        handle_get(request);
    } else if(real_method == "DELETE") {
        handle_delete(request);
    } else if(real_method == "PUT") {
        handle_put(request);
    }
});

What this prevents: Pattern-based automated attacks

Real-World Impact

Before:

$ curl -X DELETE http://device.local/api/passwords/1
Password deleted

[Automated scanner detects DELETE is enabled]
[Tries to delete everything]

After:

$ curl -X DELETE http://device.local/api/passwords/1
405 Method Not Allowed

$ curl -X POST http://device.local/api/passwords/1
Missing X-Method header

[Scanner confused: POST required but doesn't work normally]
[Manual analysis needed]

Layer 8: Timing Attack Protection ⏱️

The Problem

Attackers can infer information by measuring response times. For example:

Wrong password: 5ms response
Correct password but wrong PIN: 50ms response
Correct everything: 100ms response

This leaks information without ever succeeding.

The Solution

Add random delays to all security-critical operations. Make timing unpredictable.

How It Works

bool verify_credentials(const char* password, const char* pin) {
    // Start timer
    uint32_t start_time = millis();

    // Actual verification
    bool password_valid = constant_time_compare(password, stored_password);
    bool pin_valid = constant_time_compare(pin, stored_pin);

    bool result = password_valid && pin_valid;

    // Calculate elapsed time
    uint32_t elapsed = millis() - start_time;

    // Target response time: 100-150ms
    uint32_t target_time = 100 + (esp_random() % 50);

    // Add delay to reach target (if needed)
    if(elapsed < target_time) {
        delay(target_time - elapsed);
    }

    return result;
}

// Constant-time string comparison (prevents timing leaks)
bool constant_time_compare(const char* a, const char* b) {
    size_t len_a = strlen(a);
    size_t len_b = strlen(b);

    // Always compare full length (even if lengths differ)
    size_t max_len = (len_a > len_b) ? len_a : len_b;

    int result = len_a ^ len_b;  // 0 if lengths match

    for(size_t i = 0; i < max_len; i++) {
        char char_a = (i < len_a) ? a[i] : 0;
        char char_b = (i < len_b) ? b[i] : 0;
        result |= char_a ^ char_b;
    }

    return result == 0;
}

What this prevents: Timing side-channel attacks and password length inference

Real-World Impact

Before (no timing protection):

# Attacker script
import requests
import time

passwords = ["a", "ab", "abc", "abcd", ...]

for pwd in passwords:
    start = time.time()
    response = requests.post("/auth", json={"password": pwd})
    elapsed = time.time() - start

    print(f"{pwd}: {elapsed:.3f}s")

# Output:
# a: 0.005s      ← Wrong immediately
# ab: 0.005s     ← Wrong immediately  
# abc: 0.007s    ← Took slightly longer! (closer match)
# abcd: 0.005s   ← Back to fast

# Conclusion: Real password starts with "abc"

After (with timing protection):

# Attacker script (same)
# Output:
# a: 0.123s
# ab: 0.147s
# abc: 0.108s
# abcd: 0.135s

# Conclusion: ??? (no pattern)

Putting It All Together

Here's how all 8 layers work in a real scenario:

Attack Scenario: Automated Exploitation Attempt

1. Attacker scans device
   → Layer 3: Dynamic endpoints confuse scanner
   → Layer 4: Fake headers mislead fingerprinting

2. Attacker finds /admin endpoint (honey pot)
   → Layer 6: Access logged, IP recorded
   → Fake data returned, attacker wastes time

3. Attacker tries SQL injection
   → Layer 6: Honey pot detects pattern, logs attempt
   → Layer 5: Randomized responses confuse automation

4. Attacker intercepts BLE traffic
   → Layer 1: ECDH-generated keys are useless without private key
   → Layer 2: Double encryption still protects data

5. Attacker attempts timing attack on auth
   → Layer 8: Random delays hide password validation timing
   → No information leaked

6. Attacker tries brute force via web API
   → Layer 7: Method tunneling breaks automated tools
   → Layer 8: Consistent random timing prevents optimization

Result: Attack fails, you have logs of attempt, attacker wasted hours

Lessons Learned

1. Layering isn't redundancy—it's strategy

Each layer should target different attack vectors. Having 8 encryption layers doesn't help if they all use the same algorithm and key.

Good layering:

Layer 1: Key exchange (MITM protection)
Layer 2: Encryption (eavesdropping protection)
Layer 6: Honey pot (intrusion detection)

Bad layering:

Layer 1: AES-256
Layer 2: AES-256 again
Layer 3: AES-256 again (just slower)

2. Security is about time, not impossibility

No system is unbreakable. But security can make attacks:

Take too long (months/years)
Cost too much (hardware, time, expertise)
Be too risky (early detection, logging)

For a $15 DIY device storing personal passwords, being harder to crack than a corporate server is enough deterrent.

3. Observability matters

The honey pot layer isn't about stopping attacks—it's about knowing they're happening. Early warning is invaluable.

4. Open source security works

Making the code public doesn't weaken security. The architecture still requires:

Physical access to the device
Extracting hardware-unique keys
Bypassing multiple independent layers

"Security through obscurity" is not security. Security through architecture is.

Implementation Complexity

Layer	Code Complexity	Performance Impact	Maintenance
ECDH	Medium (mbedTLS)	Low (once per session)	Low
Session Encryption	Low (built-in)	Low	Low
Dynamic Endpoints	Low	None	Low
Header Obfuscation	Low	None	Medium
Anti-Fingerprinting	Low	Low (~50ms)	Low
Honey Pot	Low	None	Low
Method Tunneling	Medium	Low	Medium
Timing Protection	Medium	Medium (~100ms)	Low

Total added overhead: ~150ms per critical operation
Memory overhead: ~15KB for security code
Development time: ~2 weeks (with testing)

What's Next?

Current architecture is strong, but there's always room for improvement:

Planned additions:

Hardware secure element (ATECC608A) for key storage
Encrypted SD card backup with versioning
Multi-device sync via encrypted mesh protocol
U2F/FIDO2 support for hardware security keys

Testing improvements:

Automated penetration testing suite
Fuzzing for API endpoints
Load testing for timing attack resistance
Third-party security audit

Conclusion

Building secure embedded systems doesn't require enterprise budgets or closed-source magic. It requires:

Understanding threat models (what attacks are likely?)
Layered defenses (multiple independent protections)
Testing and validation (verify it actually works)
Open, auditable code (trust through transparency)

The 8-layer architecture in SecureGen demonstrates that even a $15 ESP32 device can implement defense-in-depth security rivaling commercial products.

The full source code is available on GitHub: github.com/makepkg/SecureGen

Every security decision, every line of code, every trade-off is documented and auditable. Because verifiable security is the only real security.

Resources

Questions? Comments? Drop them below! I'm happy to discuss specific layers, trade-offs, or alternative approaches.

Building something similar? I'd love to hear about your security architecture!

esp32 #security #embedded #architecture #defenseinдепth #encryption #opensource

📸 Images to Include

1. Cover Image

Your 8-layers infographic (already have)

2. Code Comparison Images

Create these in VS Code with dark theme, screenshot:

BEFORE:
GET /api/totp
GET /api/passwords
DELETE /api/passwords/1

AFTER:
POST /a7f3c9e8b2d4f1a6...
POST /9e4f1b8c3a7d2f5e...
POST /c3f7a9e1b5d8f2a4...

BEFORE:
Server: ESP-AsyncWebServer/1.2.3
X-ESP32-Chip: ESP32-D0WDQ6
Content-Type: application/json

AFTER:
X-k8f3a2: application/json
X-AspNetMvc-Version: 5.2.7
X-Powered-By: PHP/7.4.3

3. Timing Attack Graph

Simple graph showing response times:

Without protection: clear pattern
With protection: random scatter

Simple graph showing response times:

Without protection: clear pattern
With protection: random scatter

Implementing BLE Security on ESP32: LE Secure Connections the Hard Way

makepkg — Sat, 14 Feb 2026 16:42:03 +0000

Implementing BLE Security on ESP32: LE Secure Connections the Hard Way

In my previous post, I talked about memory management challenges when building SecureGen. Today, let's dive into something equally painful: implementing proper BLE security.

The Problem: Passwords Over Bluetooth

My device needs to send passwords via BLE to any computer. But standard Bluetooth? Not secure enough.

If someone intercepts the pairing process, they can decrypt everything. For a password manager, that's catastrophic.

Enter LE Secure Connections

Bluetooth 4.2+ introduced LE Secure Connections - basically, proper encryption with MITM (Man-in-the-Middle) protection.

But getting it working on ESP32? That's another story.

Security Levels on ESP32

The ESP32 BLE stack has several security modes:

// BAD - No security
esp_ble_gap_set_security_param(ESP_BLE_SM_AUTHEN_REQ_MODE, 
                                &auth_req, sizeof(uint8_t));
auth_req = ESP_LE_AUTH_NO_BOND;

// BETTER - Encryption but no MITM protection
auth_req = ESP_LE_AUTH_BOND;

// BEST - LE Secure Connections with MITM
auth_req = ESP_LE_AUTH_REQ_SC_MITM_BOND;

I went with the last one. Here's why:

SC (Secure Connections) = Uses P-256 elliptic curve
MITM = Prevents man-in-the-middle attacks
BOND = Remembers paired devices

The Pairing Dance

With MITM protection, pairing requires user verification. ESP32 supports several methods:

1. Just Works - No verification (useless for security)
2. Passkey Entry - User types 6-digit code
3. Numeric Comparison - User confirms matching codes

Relevant files:

src/ble_keyboard.cpp - BLE HID implementation
src/ble_security.cpp - Security configuration
src/keyboard_layouts.h - Layout mappings I chose Numeric Comparison:

void gap_event_handler(esp_gap_ble_cb_event_t event, 
                       esp_ble_gap_cb_param_t *param) {
    switch(event) {
        case ESP_GAP_BLE_NC_REQ_EVT:
            // 6-digit PIN appears on both screens
            uint32_t passkey = param->ble_security.key_notif.passkey;

            // Display on device screen
            display_pairing_code(passkey);

            // User must confirm match on both devices
            esp_ble_confirm_reply(param->ble_security.ble_req.bd_addr, true);
            break;
    }
}

When pairing, a 6-digit code appears on both the ESP32 screen and the computer. User verifies they match. If they don't match → someone's intercepting the connection.

iOS vs Android: The Nightmare

This is where things got painful.

Android: Works perfectly with default settings.

iOS: Refuses to pair. Just... refuses.

After days of debugging, I found the issue: iOS enforces stricter bonding requirements.

The Fix: Adaptive Bonding

void configure_bonding(bool is_ios) {
    uint8_t key_size = 16;  // Maximum encryption key size
    uint8_t init_key = ESP_BLE_ENC_KEY_MASK | ESP_BLE_ID_KEY_MASK;
    uint8_t rsp_key = ESP_BLE_ENC_KEY_MASK | ESP_BLE_ID_KEY_MASK;

    if (is_ios) {
        // iOS requires these additional keys
        init_key |= ESP_BLE_CSR_KEY_MASK;
        rsp_key |= ESP_BLE_CSR_KEY_MASK;
    }

    esp_ble_gap_set_security_param(ESP_BLE_SM_MAX_KEY_SIZE, 
                                    &key_size, sizeof(uint8_t));
    esp_ble_gap_set_security_param(ESP_BLE_SM_SET_INIT_KEY, 
                                    &init_key, sizeof(uint8_t));
    esp_ble_gap_set_security_param(ESP_BLE_SM_SET_RSP_KEY, 
                                    &rsp_key, sizeof(uint8_t));
}

The CSR (Connection Signature Resolving) key is what iOS wants. Without it, pairing fails silently with no error messages.

Detecting iOS vs Android

But how do you know if the connecting device is iOS?

Turns out, you can check during the pairing process:

void gap_event_handler(esp_gap_ble_cb_event_t event, 
                       esp_ble_gap_cb_param_t *param) {
    switch(event) {
        case ESP_GAP_BLE_AUTH_CMPL_EVT:
            if (param->ble_security.auth_cmpl.success) {
                // Check device properties
                bool is_ios = check_device_capabilities(
                    param->ble_security.auth_cmpl.bd_addr
                );

                // Store for future connections
                save_device_type(param->ble_security.auth_cmpl.bd_addr, 
                                is_ios);
            }
            break;
    }
}

I check the device's BLE capabilities during the first pairing and store it. Subsequent connections use the stored info.

BLE HID Keyboard Setup

Now that we have secure pairing, let's send passwords.

BLE HID (Human Interface Device) lets the ESP32 pretend to be a keyboard:

// HID Report Descriptor for keyboard
static const uint8_t hid_keyboard_report_map[] = {
    0x05, 0x01,  // Usage Page (Generic Desktop)
    0x09, 0x06,  // Usage (Keyboard)
    0xA1, 0x01,  // Collection (Application)

    // Modifier keys (Ctrl, Shift, Alt, etc.)
    0x05, 0x07,  // Usage Page (Key Codes)
    0x19, 0xE0,  // Usage Minimum (Left Ctrl)
    0x29, 0xE7,  // Usage Maximum (Right GUI)
    0x15, 0x00,  // Logical Minimum (0)
    0x25, 0x01,  // Logical Maximum (1)
    0x75, 0x01,  // Report Size (1)
    0x95, 0x08,  // Report Count (8)
    0x81, 0x02,  // Input (Data, Variable, Absolute)

    // Regular keys
    0x95, 0x06,  // Report Count (6)
    0x75, 0x08,  // Report Size (8)
    0x15, 0x00,  // Logical Minimum (0)
    0x26, 0xFF, 0x00,  // Logical Maximum (255)
    0x05, 0x07,  // Usage Page (Key Codes)
    0x19, 0x00,  // Usage Minimum (0)
    0x2A, 0xFF, 0x00,  // Usage Maximum (255)
    0x81, 0x00,  // Input (Data, Array)

    0xC0  // End Collection
};

This descriptor tells the OS: "I'm a keyboard with modifier keys and 6 simultaneous key presses."

Keyboard Layout Hell

Here's a fun problem: Different keyboard layouts handle special characters differently.

@ symbol:
US layout:   Shift + 2
UK layout:   Shift + '
German:      AltGr + Q
French:      AltGr + à

My solution: configurable layout mapping

typedef struct {
    char character;
    uint8_t keycode;
    uint8_t modifier;
} KeyMapping;

KeyMapping us_layout[] = {
    {'@', 0x1F, SHIFT},  // @ = Shift+2
    {'#', 0x20, SHIFT},  // # = Shift+3
    {'$', 0x21, SHIFT},  // $ = Shift+4
    // ...
};

KeyMapping uk_layout[] = {
    {'@', 0x34, SHIFT},  // @ = Shift+'
    {'#', 0x32, NONE},   // # = just 3
    // ...
};

void type_character(char c, KeyMapping *layout) {
    KeyMapping *mapping = find_mapping(c, layout);
    if (mapping) {
        send_key_press(mapping->modifier, mapping->keycode);
    }
}

Users select their keyboard layout in the web interface. The device translates characters to the correct key combinations.

Security: It's Not Just Encryption

Even with encrypted BLE, you need additional protections:

1. PIN Protection Before Transmission

void send_password_via_ble() {
    // Require PIN on device screen
    if (!verify_user_pin()) {
        display_error("PIN required");
        return;
    }

    // Show which password will be sent
    display_confirm_screen(password_name);

    // Wait for button confirmation (both buttons)
    if (!wait_for_button_confirmation()) {
        return;
    }

    // Only now send via BLE
    ble_keyboard_type(password);
}

2. Bonding Management

// Store bonded devices
#define MAX_BONDED_DEVICES 5

void manage_bonding() {
    uint8_t bonded_count = esp_ble_get_bond_device_num();

    if (bonded_count >= MAX_BONDED_DEVICES) {
        // Remove oldest bonded device
        esp_ble_bond_dev_t *devices = malloc(sizeof(esp_ble_bond_dev_t) 
                                             * bonded_count);
        esp_ble_get_bond_device_list(&bonded_count, devices);
        esp_ble_remove_bond_device(devices[0].bd_addr);
        free(devices);
    }
}

3. Timeout Protection

void ble_transmission_task() {
    // Connect
    ble_connect();

    // Send password
    ble_keyboard_type(password);

    // CRITICAL: Disconnect after transmission
    vTaskDelay(pdMS_TO_TICKS(1000));  // Wait for typing to complete
    ble_disconnect();

    // Disable BLE completely after use
    ble_deinit();
}

BLE only active during password transmission. Rest of the time, it's off.

Memory Considerations

Remember from my first post: BLE stack uses ~70KB RAM.

When sending passwords:

void safe_ble_transmission() {
    // Check heap before enabling BLE
    if (ESP.getFreeHeap() < 80000) {
        display_error("Low memory");
        return;
    }

    // Disable WiFi first
    WiFi.disconnect();
    WiFi.mode(WIFI_OFF);
    delay(100);

    // Now safe to enable BLE
    init_ble_keyboard();
    send_password();
    deinit_ble_keyboard();
}

Testing BLE Security

How do you verify it's actually secure?

1. Wireshark BLE Capture:

Use an Ubertooth or nRF52840 to capture BLE packets. With proper LE Secure Connections, packets should be:

Encrypted with AES-128
Indecipherable without the pairing key
Protected by message integrity checks

2. Try MITM Attack:

Use btlejack or similar tools to attempt interception:

btlejack -f 0x9c68 -t -m 0x1fffffffff

If implemented correctly, the attack should fail because the numeric comparison prevents MITM.

3. iOS Security Check:

On iOS, check Settings → Bluetooth → Device Info. Look for:

"Encrypted" badge
"Security: High"

Lessons Learned

iOS is picky - Android will pair with almost anything, iOS won't.
Numeric Comparison is worth it - Slight UX friction for massive security gain.
Disconnect aggressively - BLE should be off when not transmitting.
Test on real devices - Emulators don't catch bonding issues.
Keyboard layouts matter - International users exist!

What's Next?

In the next post, I'll cover:

Generating hardware encryption keys from ESP32 chip parameters
Key derivation with PBKDF2
Why flash wear leveling matters for security devices

The Code

Full implementation: SecureGen GitHub

Questions? Comments? Drop them below! I'm still learning and would love to hear how others solved similar problems.

esp32 #bluetooth #security #embedded #ble #encryption

Building a Hardware TOTP Authenticator on ESP32: The Memory Management Nightmare

makepkg — Wed, 11 Feb 2026 19:05:18 +0000

Building a Hardware TOTP Authenticator on ESP32: The Memory Management Nightmare

I wanted a hardware 2FA device I could trust. Not a phone app that's always online, not a closed-source token - something open, auditable, and completely under my control.

So I built one on the ESP32 T-Display. Turns out, making a secure device on a microcontroller with 520KB RAM teaches you a lot about resource constraints.

The Problem: BLE + WiFi = Crash

My device needed to do two things:

Generate TOTP codes (requires accurate time via NTP/WiFi)
Type passwords via Bluetooth (requires BLE HID keyboard)

Sounds simple, right?

Here's what I learned the hard way:

The ESP32's BLE stack alone eats ~70KB of RAM. When you enable WiFi on top of that, heap memory becomes critically tight. Running both simultaneously? Random crashes. Memory fragmentation. Unexpected reboots.

// This will crash after a few minutes:
void bad_approach() {
    WiFi.begin(ssid, password);
    BLEDevice::init("SecureGen");
    // 💥 Heap exhausted
}

The Solution: Strict Mode Separation

Instead of trying to run everything at once, I separated the device into distinct modes:

TOTP Mode:

WiFi ON for NTP sync
Get accurate time
WiFi OFF immediately after sync
Use millis() for countdown between syncs

Password Manager Mode:

WiFi completely disabled
Only BLE active
Pure offline operation

BLE Transmission:

WiFi always OFF before connecting
BLE connects, types password, disconnects
No coexistence needed

void safe_approach() {
    if (mode == TOTP_MODE) {
        sync_time_via_ntp();
        WiFi.disconnect(true); // Force disconnect
        WiFi.mode(WIFI_OFF);
    }

    if (need_ble_transmission) {
        ensure_wifi_off(); // Double check
        init_ble_keyboard();
        send_password();
        deinit_ble_keyboard();
    }
}

Monitoring Heap Memory

I added aggressive heap monitoring to catch memory leaks early:

void check_heap() {
    Serial.printf("Free heap: %d bytes\n", ESP.getFreeHeap());
    Serial.printf("Min free heap: %d bytes\n", ESP.getMinFreeHeap());

    if (ESP.getFreeHeap() < 20000) {
        // Critical! Take action
        emergency_cleanup();
    }
}

The getMinFreeHeap() function was crucial - it shows the lowest point your heap reached, helping you spot fragmentation issues.

Other Memory Optimization Tricks

1. Stack Size Matters

BLE callbacks run in their own task. Default stack size wasn't enough:

// Increase BLE task stack
xTaskCreatePinnedToCore(
    ble_task,
    "BLE",
    8192,  // Increased from default 4096
    NULL,
    5,
    NULL,
    0
);

2. String Handling

Avoid String class on ESP32 - it fragments heap. Use char[] arrays:

// Bad (heap fragmentation):
String message = "Hello " + username + "!";

// Good (stack allocation):
char message[64];
snprintf(message, sizeof(message), "Hello %s!", username);

3. WiFi Events Cleanup

WiFi events can leak memory if not handled properly:

WiFi.disconnect(true);  // true = erase credentials
WiFi.mode(WIFI_OFF);
delay(100);  // Let it settle
esp_wifi_stop();
esp_wifi_deinit();

The Result

After these optimizations:

Stable operation for days without reboot
Min free heap stays above 50KB (safe zone)
No more random crashes
Clean mode transitions

Lessons Learned

ESP32 is powerful, but not unlimited - you're still working with embedded constraints
Measure everything - heap monitoring saved me countless hours
Mode separation works - don't try to do everything simultaneously
WiFi/BLE coexistence is hard - avoid it if you can

The Project

The full source code is available on GitHub: SecureGen

Features:

TOTP authenticator (RFC 6238)
Encrypted password manager (AES-256)
BLE HID keyboard
LE Secure Connections with MITM protection
Web management interface
Battery powered

If you're building anything with ESP32 + BLE + WiFi, I hope this saves you some debugging time!

What's Next?

In the next post, I'll cover BLE Security implementation - specifically LE Secure Connections, Numeric Comparison pairing, and why iOS is way more strict than Android.

Questions? Comments? Drop them below! I'm still learning and would love to hear how others solved similar problems.

esp32 #iot #embedded #security #bluetooth #opensource