Geph5 Documentation

The geph5-exit component is a server that terminates client tunnels and forwards traffic to the open Internet.

Key behaviors include:

• Registration: Exits register with the broker to allow clients to discover them.
• Traffic Control: Each exit enforces rate limits and can restrict access based on account levels or geographic location (country).
• Configuration: Settings are provided via a YAML file following the ConfigFile struct.

The geph5-client is the primary user-facing daemon for the Geph network. Its main responsibilities include:

• Session Management: Establishing and maintaining sessions with the broker and selected exit nodes.
• Traffic Tunneling: Exposing local proxy endpoints (SOCKS5 and HTTP) to tunnel user traffic through the Geph network.
• VPN Mode: Optionally operating in VPN mode by tunneling packets directly.
• Control Interface: Exposing a control RPC interface designed for use by GUI front-ends.

Geph5 is organized as a Cargo workspace (monorepo). The repository is divided into two main directories:

• libraries/: Contains library crates that may have interdependencies. These crates are also released individually to crates.io.
• binaries/: Contains the primary executable crates for the Geph5 ecosystem:
  • geph5-client: The user-facing client application.
  • geph5-exit: The exit node component.
  • geph5-bridge: The bridge component.
  • geph5-broker: The central authentication and routing server.

Geph uses an open-source architecture to tunnel traffic through recognition-resistant protocols, masking user IP addresses with Geph's IP addresses.

Traffic Restrictions:

• Port 25 is blocked to prevent email spam.
• Geph does not block or filter domains unless requested by an IP owner or due to botnet activity causing null-routing.
• Geph does not modify, redirect, or inject data into user traffic.

Forbidden Activities:

• Unauthorized reselling of Geph services.
• Email and other spam.
• Activities illegal in the jurisdiction of the selected exit server.
• Automated registration of accounts.

Mizaru is the anonymous authentication system used in Geph5. It allows Geph to verify that a user has a valid account without the Broker (login server) learning which Exit (VPN server) the user is connecting to, and without the Exit learning the user's identity.

It achieves this by using RSA full-domain-hash (FDH) blind signatures. The core mechanism involves a client generating a secret token, "blinding" it with a random factor, having the Broker sign the blinded version, and then "unblinding" the signature to obtain a valid signature on the original token. This ensures the Broker never sees the raw token and the Exit only sees a token and a signature with no link to the user's account.

Geph5 uses a Remote Procedure Call (RPC) mechanism to facilitate communication between the GUI and the steady-state business logic. This separation is maintained even on desktop platforms where Geph may run as a single process, ensuring compatibility with mobile platforms (like iOS) where running logic in a separate process is standard.

Key distinction in communication patterns:

• Steady-state logic: Uses RPC to communicate with the GUI.
• One-off business logic: (e.g., retrieving exit node lists, logging in) is called directly from the GUI code rather than through RPC.

Communication is implemented using nanorpc-sillad to provide a type-safe interface.

Geph maintains a strict privacy policy regarding user data and legal requests:

• Non-cooperation Policy: Geph will not disclose non-public information to third parties unless legally compelled under the laws of the Republic of Estonia. Geph does not allow third-party "backdoor" access to servers.
• No-logging Policy: Geph does not keep user activity details. The following data is never stored for more than 24 hours:
  • User traffic
  • DNS requests
  • Detailed statistics
  • IP addresses
• Aggregate Statistics: Geph collects and stores aggregate statistics, which are publicly viewable at https://is.gd/gephdash2.

To prevent linking tokens across different days, Mizaru uses a different RSA-2048 signing key for every calendar day. There are 65,536 pre-generated keys, one for each day since the Unix epoch.

Key Verification via Merkle Tree

Instead of distributing all keys, Geph uses a blake3 Merkle tree to organize the public keys.

• The Merkle root is a single fingerprint that commits to the entire set of 65,536 keys and is hardcoded into the Geph client to prevent tampering.
• When a client needs the current day's key, the Broker provides the key along with a Merkle proof (a compact chain of hashes).
• The client uses this proof to verify that the provided key is a legitimate leaf in the tree under the hardcoded root.
• The Exit node performs a similar verification of the key before accepting the token.

When emitting stats using geph5-stats, the behavior in Telegraf and Postgres depends on the kind of event used:

Note on Timers: Timers are the preferred way to track both rates (via count) and latencies (via mean, p90, etc.) in a single call.

During the transition from InfluxDB to Postgres, the system uses dual-writing and legacy shims to maintain data continuity:

• Legacy RPCs: Unauthenticated set_stat and incr_stat RPCs are forwarded by the broker as classic dot-path statsd lines, which are parsed by templates in telegraf.conf and written to InfluxDB.
• Bridge Data: Old bridges write bridge_bytes directly to InfluxDB. Note that this data will stop appearing in Grafana once panels are switched to read from Postgres. To prevent data gaps, you must re-run the backfill after the bridge fleet has been upgraded.
• Data Granularity:
  • Per-ASN history is only available in the hourly tier.
  • Backfilled bridge_bytes_minutely rows in the minutely tier will have an empty ASN (asn = '').