Kleidos Security Overview#

Kleidos is a hardware BLE password manager. This document is the entry point for two audiences: a user who wants a plain-language answer to "how safe is this?", and an auditor or developer who needs to navigate the full set of technical security documents.

How safe is Kleidos, and why?#

Your passwords never leave the device as plain text. The vault — the encrypted database on the device — can only be opened with your PIN, and the PIN never travels over any radio or wire.

Encryption on the device. Every credential is encrypted with AES-256 before being written to storage. A wrong PIN produces a completely different key, so there is no way to guess whether a PIN attempt was "close". Every encrypted file also carries an authentication tag that is checked before any decryption happens, so a physically tampered device is detected and rejected.

PIN and escalating lockout. PIN failures are counted in persistent storage so they survive power cycles and deep sleep. After four consecutive wrong PINs the device locks for 30 seconds. From the seventh wrong attempt the lockout extends to 5 minutes. After ten wrong PINs the vault is permanently wiped. There is no way to bypass these lockouts without physically re-flashing the device — and a re-flash wipes the vault too.

BLE that types, not broadcasts. The device does not permanently broadcast over Bluetooth. BLE is activated only after you unlock the device and select a credential. Pairing requires Numeric Comparison — you confirm a six-digit code on both sides — so a nearby attacker cannot intercept the link silently. After typing the credential, BLE shuts down.

Admin WiFi when you need it. WiFi is only active in admin mode, which you enter deliberately. The admin WiFi access point uses WPA3 and requires PMF (Protected Management Frames); the password is random and exists only for the duration of the session. BLE is always turned off before admin WiFi starts.

Production hardware locks down further. Devices built with the _secure build target add Secure Boot v2 (the bootloader is signed and verified on every power-on), Flash Encryption (storage is encrypted at the chip level), and NVS encryption. On ESP32-S3 boards the vault key is also bound to a secret burned into the chip's eFuse — even if someone reads the flash chips off the board, they cannot guess PINs offline without that chip. JTAG debug access is disabled.

Deep sleep by default. When the device is not in use it enters deep sleep, drawing less than 20 µA. Every subsystem — BLE, WiFi, display backlight — must be fully shut down before sleep. Missing a shutdown path is treated as a bug, not a warning.

Security controls at a glance#

Navigation map#

Crypto and vault#

PIN and lockout#

BLE#

WiFi and admin portal#

OTA and boot#

Key material and logging#

Production and flash#

Audit log#

Threat model#

CVE register#

Release checklist#

Audit dossier#

For auditors#

Start with threat-model.md to understand the asset inventory, trust boundaries, and the complete threat taxonomy (T1–T17). Each subordinate document maps back to one or more threat IDs and contains an Auditor Checklist section with mechanically verifiable assertions and file:line anchors.

The Audit Dossier — audit-dossier.md — is the companion control matrix: it maps every threat ID to code evidence (file:line), the governing standard, and the specific test/QA command that verifies the control is active.

Architecture diagram#

flowchart LR
    User[User] -->|Timing Arc PIN| PinEntry[PIN entry]
    PinEntry -->|PBKDF2-SHA256| MasterKey[Master key in RAM]
    MasterKey --> Vault[Encrypted LittleFS vault\nAES-256-CBC + HMAC-SHA256]
    MasterKey --> AdminMode[Admin mode]
    Vault -->|selected credential| BLE[BLE HID session\nLE SC + Numeric Comparison]
    BLE --> Host[Paired host]
    AdminMode -->|WPA3 SoftAP| Portal[Admin portal\nWPA3 + session token]
    Portal -->|esp_ota_ops| OTA[App OTA + rollback guard]

    classDef sensitive fill:#ffe8e8,stroke:#b00020,color:#111;
    class MasterKey,Vault sensitive;

The key rule is that sensitive material is accessible only in a narrow unlocked session. BLE, WiFi, display backlight, LittleFS, and key buffers each have an explicit shutdown or wipe path before lock or deep sleep. Missing a shutdown path is a bug, not a warning.