ENGINEERING SPECIFICATION AGPL-3.0 VERIFIED AES-256-GCM RATCHET

System Architecture & Cryptography

In-depth technical breakdown of the Entangl Android application, mutual handshake state machine, message ratchet, relay transport, and threat model.

Application: Entangl P2P Android • Target OS: Android 8.0+ (API 26+) • Build: Deterministic Gradle
Entangl Post-Quantum P2P Android Messenger Logo

1. User Journey Architecture

Entangl is built natively for Android using Kotlin and Jetpack Compose. Centralized databases, accounts, phone numbers, and cloud mailboxes have been intentionally removed. Communication channels only exist when two humans perform an in-person optical handshake.

Entangl User Journey Flowchart showing Stage 1 Identity Setup, Stage 2 Physical In-Person Pairing, Stage 3 Direct P2P Communication, and Stage 4 On-Device Privacy Hardening
Figure 1.1: Complete End-to-End User Journey & Security Subsystems
FOUR DEFENSE STAGES

Stage 1 (Identity): Keystore-backed keypairs, no personal identifiable information (PII).
Stage 2 (Pairing): Zero network access needed; out-of-band mutual dynamic QR challenge/response.
Stage 3 (Messaging): Ratcheted per-message keys over signed relay envelopes or local transfer.
Stage 4 (Privacy): SQLCipher encrypted database, zero lockscreen leaks, and instant memory scrubbing.

Day-to-day, chats group under day dividers with delivery tags and per-message self-destruct timers; each contact offers delete, clear-history, and block/unblock from its overflow menu, and roster presence reflects fresh verified traffic only.

2. Cryptographic Stack & Algorithms

Entangl v1.0.0 ships the following primitives, exactly as implemented in code:

  • Identity & Handshake Signatures: ECDSA P-256 with SHA-256. Identity keys are generated in the Android Keystore (StrongBox preferred) and sign canonical QR bytes covering action, UID, codename, profile color, ephemeral/identity keys, routing address, nonce, and timestamp.
  • Ephemeral Keys: X25519, generated per QR and held in off-heap native buffers that are zeroized immediately after use.
  • Session & Chain Derivation: HKDF-SHA256 with domain-separated salts/infos for root, chain-advance, and per-message keys.
  • Symmetric Cipher: AES-256-GCM authenticated encryption with wire sequence binding (0x01 header).
  • Safety Numbers: 5× SHA-256 over lexicographically sorted identity keys, truncated and rendered as 12 blocks of 5 digits (60 digits total).
  • Local Database Master Key: Random 256-bit SQLCipher passphrase wrapped by AES-256-GCM in the Android Keystore (StrongBox preferred).

3. The Mutual QR Handshake Protocol

The core barrier preventing remote cyberattacks, mass surveillance, and bulk spam in Entangl is the requirement for an out-of-band visual handshake. The handshake guarantees that both nodes have authenticated each other in the physical world before any network transmission occurs.

Entangl In-Person Pairing Sequence Diagram showing Alice initiating Challenge QR, Bob scanning and rendering Response QR, Alice verifying signature, and both computing Safety Number
Figure 3.1: Sequence Diagram of the Mutual QR Handshake State Machine

Step-by-Step Handshake Protocol Flow:

  1. Alice Generates Challenge Payload: Alice opens her code. Her device creates a fresh 32-byte rolling nonce N_A, packs her P-256 public key, her codename, profile color, and signs the CBOR payload with her Keystore key. The payload renders as a QR code with a 60-second TTL.
  2. Bob Scans Challenge: Bob opens his scanner. His device decodes the CBOR payload, verifies Alice's signature, checks TTL/freshness, and records the scan. His scan proof is transmitted to Alice.
  3. Bob Displays Response QR: Bob's screen renders his own signed payload.
  4. Alice Scans Response: Alice scans Bob's QR code. Her device verifies Bob's signature and records the reciprocal scan. Either direction's surviving scan proof completes both sides automatically — no rescan required.
  5. Deterministic Safety Number: Both phones independently compute 5×SHA-256(Alice_Pub || Bob_Pub) and format the result into 12 blocks of 5 digits (60 digits total), shown at scan time and any time from the chat shield icon.
  6. Session Unlocked: The contact record is inserted into the SQLCipher database (Room schema v4), and ratchet session state is initialized.

4. Message Key Ratchet Protocol

Once paired, each message encrypts under a fresh key derived from HKDF-SHA256 send/receive chains:

  • Forward-Secreting Chains: Each message advances the chain key and zeroizes the used message key. Chains are never reset per send and deterministically re-sync after peer restart or rescan.
  • Out-of-Order Tolerance: Skipped message keys are cached within a bounded gap (1,000) so reordered packets still decrypt.
  • Ephemeral TTL: Per-message self-destruct lifetimes travel inside the signed envelope to both sides, with live countdown, glitch vaporization, vault deletion, and background purge.

5. Relay Transport & Local Transfer

Entangl v1.0.0 messages are transported as signed envelopes over redundant relays, with direct encrypted transfer for device migration:

A. Redundant Relay Inbox (WAN Routing)

Signed envelopes fan out across redundant relays under blinded per-device inbox topics. Payloads are padded to fixed 2,048-byte blocks, delivery ACKs are signature-verified before flipping state, and envelopes carry 24-hour replay windows with duplicate suppression.

B. Encrypted Local Transfer (Device Migration)

Device succession runs over a direct LAN socket: X25519 ephemeral agreement, HKDF tunnel key, AES-256-GCM transfer of contacts/messages/session keys, signed succession certificates, and atomic old-device decommissioning.

6. Threat Model & Security Guarantees

Security engineering requires clear delineation of what an application defends against versus out-of-scope adversaries:

WHAT ENTANGL DEFENDS AGAINST:
  • Passive Network Surveillance: Relay observers see only fixed-size ciphertext plus routing headers — never plaintext, keys, or contact graphs.
  • Cloud Subpoenas & Honeypots: Because Entangl has zero central servers, no user accounts, no databases, and no message queues, there is no entity that can be compelled to provide user metadata.
  • Remote Contact Scraping & Spam: It is impossible to send a message without the recipient physically scanning your device in person.
  • On-Device Screenshot Leaks: FLAG_SECURE blocks third-party background apps and Android OS recents thumbnail capture.
OUT-OF-SCOPE RISKS & USER RESPONSIBILITIES:
  • Targeted Hardware Compromise (Rootkit / Pegasus-class Spyware): If the Android OS kernel itself is compromised with a root exploit, key loggers or memory dumpers can read cleartext UI buffers.
  • Shoulder Surfing / Physical Coercion: If an adversary forcibly unlocks the device with the user's PIN/biometrics while the application is active.

7. Runtime Hardening Specifications

The Android application implements strict operational security controls:

  • FLAG_SECURE enforced across all Compose Activities and Dialogs.
  • filterTouchesWhenObscured = true to prevent clickjacking and overlay attacks.
  • NativeKeyBuffer keeps ephemeral key material in off-heap direct buffers outside the managed JVM heap.
  • Immediate explicit zeroization after key usage.
  • android:allowBackup="false" preventing ADB extraction and cloud backup scraping.
  • Notification metadata suppression: NotificationCompat.VISIBILITY_SECRET ensures lockscreens show no sender names or preview text.

8. Reproducible Builds & Verification

Entangl builds deterministically so anyone can verify that the published binary matches the public source code:

verify_build.sh BASH
# 1. Clone official repository
git clone https://github.com/hkbagh/Entangl.git
cd Entangl/"Entangl Android"

# 2. Verify git release tag and commit GPG signature
git verify-tag v1.0.0

# 3. Assemble release APK using deterministic gradle flags
./gradlew assembleRelease --no-daemon

# 4. Compare SHA-256 hash with published release checksum
sha256sum app/build/outputs/apk/release/app-release-unsigned.apk
PRE-BUILT BINARIES VIA GOOGLE PLAY

Automatic background security updates and verified signatures through Google Play Protect.

Play Store Get on Play Store