Entrixy — End-to-End Encryption

A zero-knowledge architecture: the server holds decryption keys for nothing but technical identifiers. Every meaningful field — phone numbers, URLs, coordinates, webhook secrets, Wi-Fi BSSIDs, greetings — is encrypted on the owner's device and sits on the server as an opaque blob. The decryption key reaches the guest inside the invitation link, in the URL fragment, which the browser never sends to the server.

Decided on 2026-04-19. The work proceeds in stages — see the "Phases" section.

1. Goals and boundaries

Confidentiality of content. The server knows neither the barrier's address nor the phone number, nor the webhook URL, the coordinates, the Wi-Fi BSSID or the greeting text.
Verifiable integrity. Any tampering with a blob on the server breaks decryption (AES-GCM), and the client reports corrupted data.
Forward compatibility of keys. A guest gets access only to the objects granted to that guest. Compromising one guest key reveals nothing about the others.
The limit of zero knowledge. The server does see that a key exists, activity timestamps and object identifiers — it needs them for routing. Hiding metadata (onion schemes) is out of scope.

2. Cryptographic primitive

Algorithm: AES-256-GCM. Available out of the box on the JVM (through javax.crypto), and supported by the Android Keystore. It gives confidentiality and authentication at once.

Ciphertext format

v1:<base64url(nonce || ciphertext || tag)>

v1: — a version prefix, for rotating the format later.
nonce — 12 random bytes, fresh for every encryption.
ciphertext+tag — everything returned by Cipher.doFinal; the 128-bit tag is included.
base64url without padding — safe in a URL and in JSON alike.

Source of entropy

SecureRandom() (the system one). On Android that is /dev/urandom + Linux prng.

3. Key hierarchy

K_master — the owner's master key

32 random bytes, generated on first launch.
Stored in EncryptedSharedPreferences under the name master_key and never leaves the device in the clear.
Used solely to wrap K_obj for local storage.

K_obj — the object key

32 random bytes, generated when each object is created.
Stored locally as encrypt_k_master(K_obj) under the key obj_key_{id}.
It encrypts the JSON of every sensitive field of the object (data_cipher on the server).
Rotation means a new K_obj_new → re-encrypt data_cipher and every bundle that carried it.

K_guest — the guest bundle key

32 random bytes, generated when a guest key is created.
It encrypts the bundle — a small JSON {obj_id: K_obj} for the objects the guest is allowed.
What reaches the server is only bundle_cipher. The K_guest itself is never seen by the server.
K_guest reaches the guest in the URL fragment: entrixy.com/key#<user_key><base64url(K_guest)> — a single 75-character block. The fragment is not sent to the server with the HTTP request; that is a basic browser guarantee.

Changing K_guest is only possible by issuing a new link. Revocation is built on exactly that: the server deletes the key record and the guest no longer receives a current bundle_cipher.

4. What is stored where

On the owner's device (EncryptedSharedPreferences)

Key	Value
`master_key`	32 bytes in the clear (SharedPreferences encrypts them anyway).
`obj_key_{id}`	The object's K_obj, wrapped with K_master.
`obj_plain_{id}`	(optional) a cache of the decrypted JSON, so the UI draws quickly.

On the server

Table / field	Contents
`numbers.data_cipher`	JSON encrypted with K_obj: `{phone, url, secret, geo_lat, geo_lon, share_lat, share_lon, snapshot, welcome, label}`.
`numbers.id / type`	In the clear — needed for routing and for showing the icon type.
`keys.bundle_cipher`	JSON encrypted with K_guest: `{obj_ids: [1,2,3], obj_keys: {1: K_obj1, 2: K_obj2, ...}, welcome_cipher: ..., ...}`.
`keys.user_key / mode / force_when_busy`	In the clear — for routing and a quick access check.

The greeting to the guest is encrypted separately inside the bundle, so the server cannot see it either.

5. Invitation link format

https://entrixy.com/key#<user_key(32)><K_guest_base64url(43)>

The fragment is one 75-character block: 32 characters of user_key and 43 characters of the guest key.
user_key — the identifier on the server side. Without it the server will not hand over the bundle.
The fragment (#...) never reaches the server log — that is a browser guarantee.
The page /key — plain JS: it reads location.hash, parses the block and hands the key either to the app or to the web version /app/. The server never sees the key.
If the app is not installed, the page copies the link to the clipboard and sends you to /download/android, from where the app picks the key up by itself.

6. Main flows

Creating an object

The owner presses Add — this generates K_obj.
The fields are packed into JSON and encrypted with K_obj → data_cipher.
POST /api/number_add with data_cipher plus the type. The server returns an id.
Stored locally: obj_key_{id} = encrypt_k_master(K_obj).

Updating an object

Build the new JSON locally, encrypt it with the existing K_obj → POST /api/number_update. K_obj does not change.

Creating a guest key

The owner has chosen [obj1, obj2, obj3]. This generates K_guest.
The bundle JSON is assembled: {obj_ids: [...], obj_keys: {1: K_obj1, ...}, welcome_cipher: ...}.
Encrypted with K_guest → bundle_cipher.
POST /api/key_create with bundle_cipher, obj_ids (in the clear — for the access matrix).
The server returns user_key.
The owner is shown a QR code with the link entrixy.com/key#{user_key}{base64url(K_guest)}.

A guest accepting the key

The guest opens the QR code or the link. The page /key reads location.hash and hands the key to the app or the web version.
The client requests POST /api/key_bundle.php with user_key → receives bundle_cipher and the list of obj_ids.
Decrypts the bundle with K_guest→ obtaining {obj_keys, welcome}.
K_guest and the decrypted obj_keys are stored in the EncryptedSharedPreferences of the guest client.
From then on, on every call: GET the encrypted data_cipher of the object → decrypt with the local obj_key_{id}.

Revoking a guest key

The owner presses Delete → POST /api/key_revoke.php → the server deletes the key record. On the next bundle request the guest is refused and loses access.

Rotating an object key

The owner presses "Regenerate key" in the object settings. This generates K_obj_new, and every bundle_cipher containing that object is re-encrypted. The client does not know them offhand, so the owner's client rebuilds the bundles: it fetches the bundle_cipher of each of its keys, decrypts it, inserts K_obj_newand re-encrypts. The new blobs go to the server in one batch.

7. Backup and restore

This section describes a plan that has not been implemented yet: there is no master key export in the app today.

Losing K_master means losing access to every object and key, which is why an export is essential.

The owner sets a passphrase (at least 8 characters).
KDF: Argon2id (64 MB memory, 3 iterations, 1 thread) → derived 32-byte key.
The derived key encrypts K_master → producing master_backup_blob.
The blob is shown as a QR code and saved to Downloads. It can be printed and locked in a safe.
Restoring on a new device: scan the QR code, enter the passphrase, K_master is recovered, and the client pre-downloads every obj_keys from the server — they are there in the bundle of the owner's own keys — and re-encrypts them locally.

Without a passphrase the backup QR code is a plain K_master, so the passphrase is mandatory.

8. Rollout phases

Phase 1 — the client-side crypto store

Add Crypto.kt: an AES-256-GCM wrapper, generation and storage of K_master, helpers for K_obj, serialisation of the format v1:<base64url>. Unit tests: encrypt → decrypt → compare. Nothing goes to the server yet — the plumbing is simply ready.

Phase 2 — server schema migration (done)

Every sensitive field has moved into numbers.data_cipher and user_keys.bundle_cipher. The old plaintext columns (phone, label, radius, time_*, geo_*, wifi_*, share_*, has_avatar, security_level, user_keys.label, hosts.label, pending_actions.phone, hosts.last_ip) have been dropped from the database (phase 7). webhook_url and webhook_secret stay in the clear ONLY when webhook_mode='server' — without them the server cannot send the HTTP request. For webhook_mode='phone' they are encrypted into data_cipher.

Phase 3 — the client reads and writes the blob

On create or update the client encrypts the JSON and sends data_cipher. On sync it reads the blob and decrypts it. New objects live entirely in the blob; old ones without a K_obj keep using the plaintext fields for backward compatibility.

Phase 4 — the guest bundle

Creating a key generates K_guest, assembles the bundle and sends bundle_cipherto the server. The link carries the key in its fragment; the page /key reads the hash and passes the key to the app.

Phase 5 — backup and restore

A settings screen with "Export master key": passphrase → Argon2id → QR code. Restoring through the scanner, plus tests of moving between devices. Not implemented.

Phase 6 — migrating existing data

A one-off routine in the client on the first launch of the new version:

Read all of its objects from the server (the old plaintext fields).
Generate a K_obj for each of them.
Encrypt the fields and send data_cipher.
The server clears the old columns (phone=NULL, …) — but only after confirmation.

Once the migration succeeds, the deprecated fields are dropped with an ALTER.

Phase 7 — audit

A security audit, external or our own. We check that the server really cannot see sensitive data: a database dump must contain nothing but blobs.

9. Risks and measures

Risk	Measure
Loss of K_master	A mandatory backup flow (phase 5). Until a copy exists, a warning banner is shown.
Compromise of the owner's device	Not fully preventable: entry to the app is guarded by a PIN or biometrics, with EncryptedSharedPreferences and the Android Keystore.
Rotating an object key requires rebuilding every bundle	The owner's client takes every bundle_cipher, locally or from the server, rebuilds them and sends them in one batch. A rare operation.
The server tampers with a bundle	The AES-GCM tag will not match and the client reports a corrupted key.
K_guest leaking through a screenshot of the QR code	Not technically preventable: the key is in the code itself. Show the QR code only to a guest you trust.
The URL fragment stays in browser history	The page `/key` calls, right after reading the hash, `history.replaceState(..., '#')`, which wipes the fragment.

Last updated: 19 April 2026