Technical Documentation & Architecture

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): Hybrid post-quantum ratcheting over Tor hidden services or local sockets.
Stage 4 (Privacy): SQLCipher encrypted database, zero lockscreen leaks, and instant memory scrubbing.

2. Cryptographic Stack & Algorithms

Entangl employs state-of-the-art cryptography to ensure security against both conventional and future quantum adversaries:

Identity & Handshake Signatures: Ed25519 (Edwards-curve Digital Signature Algorithm). Used to authenticate identity keys, rolling nonces, timestamps, usernames, and profile colors.
Key Agreement: X25519 (Elliptic Curve Diffie-Hellman over Curve25519).
Post-Quantum Key Encapsulation Mechanism (PQ-KEM): ML-KEM-768 (Kyber-768). Standardized by NIST for post-quantum security (NIST Category 3 / 192-bit quantum security level).
PQXDH Ratchet: Derived via libsignal-client. The shared secret is computed as HKDF-SHA256(ECDH_Secret || ML_KEM_Secret). Even if one algorithm were completely broken in the future, the session remains secure as long as the other holds.
Symmetric Cipher: ChaCha20-Poly1305 (256-bit key authenticated encryption with associated data).
Local Database Master Key: AES-256 wrapped by the Android Keystore (backed by hardware StrongBox chip where available).

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:

Alice Generates Challenge Payload: Alice taps "Pair Device". Her device creates a fresh 32-byte rolling nonce N_A, packs her Ed25519 public key, her codename, profile color, and signs the CBOR payload with her private key. The payload renders as a QR code with a 120-second TTL.
Bob Scans Challenge: Bob opens his scanner. His device decodes the CBOR payload, verifies Alice's Ed25519 signature, extracts N_A, generates his own nonce N_B, and signs (N_A || N_B || Bob_Identity).
Bob Displays Response QR: Bob's screen renders the signed response payload.
Alice Scans Response: Alice scans Bob's QR code. Her device validates that N_A matches her issued challenge, verifies Bob's Ed25519 signature, and confirms Bob's identity.
Deterministic Safety Number: Both phones independently compute SHA-512(Alice_Pub || Bob_Pub) and format the result into 12 blocks of 5 digits (60 digits total). Both users compare this visual readout on-screen to confirm zero optical tampering.
Session Unlocked: The contact record is inserted into the SQLCipher database, and Double Ratchet state is initialized.

4. PQXDH + Double Ratchet Protocol

Once paired, conversations benefit from the Double Ratchet Protocol combined with post-quantum key encapsulation:

Forward Secrecy: Each message advances the symmetric key ratchet. Once a message key is used to decrypt a payload, it is immediately deleted from memory. An attacker who compromises a device key at time T cannot decrypt messages sent prior to T.
Post-Compromise Security (Break-in Recovery): Each DH round introduces fresh entropy into the root chain. If an attacker momentarily extracts state, they lose access as soon as an uncompromised round-trip message exchange occurs.
Quantum Immunity (SNDL Defense): Hostile intelligence services frequently intercept and archive encrypted network traffic, waiting for quantum computers capable of running Shor's algorithm. Because Entangl mixes ML-KEM-768 Kyber into the ratchet, archived traffic cannot be decrypted retroactively.

5. Dual Network Transport: LAN & Tor

Entangl messages are transported over one of two channels, depending on network locality:

A. Local Wi-Fi P2P Socket Routing

When two devices connect to the same Wi-Fi network, Entangl performs local socket discovery via encrypted UDP SCAN_PING and SCAN_ACCEPT broadcasts. Messages transfer directly over a local TCP socket with zero Internet access required and negligible latency.

B. Tor Onion Services (WAN Routing)

When devices are on disparate networks or behind firewalls, Entangl activates an embedded instance of Rust Tor (arti). Each device operates an ephemeral v3 .onion hidden service. Connections are end-to-end encrypted across Tor circuits, hiding IP addresses, geographical locations, and physical networks.

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 & Active Network Surveillance: ISPs, Tor exit nodes, and nation-state packet sniffers see only obfuscated onion traffic or local encrypted socket blobs.
Store Now, Decrypt Later (SNDL): Quantum computers cannot reverse ML-KEM-768 lattice problems.
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 cryptographic keys in native C/Rust heap memory outside the managed JVM garbage collection heap.
Immediate zeroization using sodium_memzero 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.

Get on Play Store