blue_ghost

system design

Architecture Overview

blue_ghost is built as a layered, offline‑first secure communication system. Each layer is isolated, minimal, and designed to eliminate entire classes of attack.

┌─────────────────────────────────────────────────────┐
│                   Application UI                    │
│              (Jetpack Compose, MVVM)                │
├──────────────────────┬──────────────────────────────┤
│   Session Manager    │   Secure Input / Display     │
│   (BleManager.kt)    │   (Password-mode keyboard,   │
│                      │    FLAG_SECURE screenshots)  │
├──────────────────────┴──────────────────────────────┤
│             Cryptographic Protocol Layer            │
│   Ephemeral ECDH · Double Ratchet · AES-256-GCM     │
│   HKDF-SHA256 · Replay Window · Safety Number       │
├─────────────────────────────────────────────────────┤
│              Bluetooth Low Energy Transport         │
│          (GATT Server + Client, BLE Advertiser)     │
├─────────────────────────────────────────────────────┤
│            Android Keystore (TEE-backed)            │
│         P-256 identity key — never extracted        │
└─────────────────────────────────────────────────────┘

Component Breakdown

Identity Manager — hardware-backed P-256 keys in Android Keystore TEE
Handshake Engine — ephemeral ECDH (P-256) with HKDF-SHA256 key derivation
Ratchet Engine — Double Ratchet state machine (symmetric + DH ratchet)
Message Encryptor — AES-256-GCM with authenticated sequence numbers
BLE Transport — GATT server/client, BLE advertiser/scanner
Session Manager — lifecycle, reconnection, and Seal Ceremony teardown
Privacy Layer — password-mode input, FLAG_SECURE screen protection, notification redaction

ECDH Handshake Flow

Device A (initiator)                    Device B (responder)
────────────────────                    ────────────────────
Generate EKa (ephemeral)
Send EKa.public ──────────────────────▶ Generate EKb (ephemeral)
                                        shared = ECDH(EKb.priv, EKa.pub)
                                        Derive via HKDF-SHA256 →
                                          rootKey       (32 bytes)
                                          recvChainKey  (32 bytes)
                                          sendChainKey  (32 bytes)
                ◀────────────────────── Send EKb.public
shared = ECDH(EKa.priv, EKb.pub)
Derive via HKDF-SHA256 →
  rootKey       (32 bytes)
  sendChainKey  (32 bytes)
  recvChainKey  (32 bytes)

Both sides now hold identical ratchet initialisation state.
No private material was ever transmitted.

Double Ratchet Flow

┌──────────────────┐
│   Root Key (RK)  │  ← initialised from HKDF handshake output
└────────┬─────────┘
         │  (advances on each DH ratchet step)
         ▼
┌──────────────────┐
│   DH Ratchet     │  ← new ephemeral keypair generated per turn
│ (break-in recov) │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  Chain Key (CK)  │  ← HMAC-SHA256 ratchet, one step per message
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│ Message Key (MK) │  ← used once for AES-256-GCM, then wiped
└──────────────────┘

Each message uses a unique MK that is deleted immediately after use. The DH ratchet step re-derives RK and CK from a new ECDH output, ensuring that a future key compromise cannot retroactively expose past messages.

BLE Transport Model

blue_ghost uses BLE GATT characteristics as an encrypted bidirectional pipe. The advertiser broadcasts a minimal service UUID with avatar seed and busy-status bytes. Descriptions and names are fetched via GATT read on first contact.

┌──────────────────────────────────┐
│   BLE Advertisement              │
│   Service UUID + avatar seed     │
│   + busy flag (5 bytes total)    │
└──────────────┬───────────────────┘
               │ connect
               ▼
┌─────────────────────────────────────────────┐
│   GATT Service: blue_ghost       			      │
├─────────────────────────────────────────────┤
│  NAME_CHAR    (read)                        │
│  DESC_CHAR    (read)                        │
│  SHAKE_CHAR   (write) ← handshake + control │
│  MESSAGE_CHAR (write) ← encrypted payloads  │
└─────────────────────────────────────────────┘

All message payloads are uniform-length encrypted blobs. No plaintext, metadata, or identifiers are ever transmitted in the clear.

Session Lifecycle

[ Set name + description ]
         │
         ▼
[ Start scanning + advertising ]
         │
         ▼
[ Peer discovered → tap to view profile ]
         │  GATT probe reads NAME + DESC
         ▼
[ Connect dialog → send SHAKE ]
         │  SHAKE payload: ephemeral pub + avatar + name + desc
         ▼
[ Peer accepts → ACCEPT payload returned ]
         │  ACCEPT payload: ephemeral pub + avatar + name + desc
         ▼
[ HKDF derives root + chain keys ]
         │
         ▼
[ Double Ratchet active — encrypted messaging ]
         │
         ▼
[ Session end → Seal Ceremony ]
         │
         ▼
[ All keys + history destroyed ]