# phpvpn v1 wire protocol This document is the normative specification of the phpvpn v1 protocol. The keywords **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT** and **MAY** are interpreted as defined in RFC 2119. The protocol is publicly known. The phpvpn software implementation is open source and published under the MIT license. ## 1. Purpose and scope phpvpn is a short-connection store-and-forward relay for transferring end-to-end encrypted IPv4 packets between clients. The server: - authenticates requests and sender permissions; - checks syntax, routing metadata, limits and queue capacity; - stores opaque encrypted records in destination clients' queues; - atomically reads and removes all pending records of the destination client when constructing a response; - records the time of clients' last successful communication. The server does not know payload keys and neither decrypts nor interprets IPv4 packet contents. Payload key distribution, virtual network adapter configuration, VPN address assignment and processing of decrypted IP traffic are responsibilities of the client layer outside this protocol. The protocol is designed for PHP 8.2+, multiple concurrent PHP workers and resource-constrained storage. It requires no persistent connection, long polling, WebSocket, cron or server session. ### 1.1 Security objectives The protocol provides: - authenticity of the time and operational fields in the `health` response for a client that knows `SERVER_SECRET`; - authentication of `info` requests through knowledge of the server secret; - authentication of `data` requests through simultaneous knowledge of the single server secret and the particular client's access key; - integrity of the authenticated request, including its exact body bytes; - end-to-end payload confidentiality and integrity using AES-256-GCM; - confidentiality and integrity of `info` response contents using AES-256-GCM; - authenticity of the `data` action result and integrity of the order, count and completeness of its data lines using HMAC-SHA-256; - separation of keys by purpose using HKDF-SHA-256. Both PHP server and PHP client implementations must always perform every AES-256-GCM operation using the bundled pure-PHP software implementation. They MUST NOT use OpenSSL, Sodium or any other cryptographic extension for AES-256-GCM, even when available. Availability of optional extensions therefore does not change the implementation's functionality or behavior. ### 1.2 Deliberately excluded properties The authentication timestamp rejects requests older than the allowed 60-second window. However, the protocol does not prevent replay of a valid message inside that window and does not provide exactly-once or guaranteed delivery, protection against message dropping or delay, or concealment of traffic metadata. A successful `data` response authenticates its `data-result` and the ordered list of `messageId`/GCM tag pairs with HMAC, allowing the client to verify the count, order and completeness of data lines without hashing their ciphertext. Each data line's contents remain protected by its own AES-GCM tag. This protection does not prevent dropping or replaying an entire valid response. The server deliberately uses an optimistic at-most-once model: it removes data from the buffer before sending the response and does not offer it again if the response is lost or not processed. Over plain HTTP, an attacker can intercept a valid `data` polling request and replay it unchanged within its 60-second window. The server authenticates this replay again, atomically drains the victim's incoming queue and returns its records to the attacker. Without `PAYLOAD_KEY`, the attacker cannot read their plaintext, but permanently removes the records from the relay before the legitimate client obtains them. By repeatedly intercepting new polling requests, the attacker can continuously steal ciphertexts and destroy the victim's incoming queue. This consequence is known, explicitly accounted for in protocol v1 and consciously accepted. Acceptance of this risk assumes that the client, transport or application layer will typically request the missing communication again or trigger a new transmission, producing new IP packets and retrying delivery. This is not a protocol guarantee: UDP or one-off traffic without its own recovery, for example, can be lost permanently, and sustained replay can prevent even repeated attempts from being delivered. V1 introduces no nonce, replay cache, acknowledged delivery or recovery of a drained queue to address this risk. Nor does the protocol guarantee availability under this attack, storage exhaustion or PHP worker exhaustion. ## 2. Normative decisions | Area | V1 decision | |---|---| | Architecture | Stateless, short HTTP requests; no server session. | | Wire format | JSON for control actions, NDJSON for the data action. | | Delivery | Optimistic at-most-once at the server buffer level, without acknowledgement. After atomic retrieval, data is removed from the server before the response is transmitted. | | Server time | The client sends unauthenticated `auth-none` with a fresh `requestId`; the server returns public `health` authenticated by a GCM tag derived from `SERVER_SECRET`. | | Replay | A timestamp limits an authenticated request's validity to ±60 s relative to server time. Replay inside the window is not detected; no deduplication or timestamp/nonce persistence. Replay of intercepted HTTP polling can drain and permanently destroy the victim's incoming queue; v1 consciously accepts this risk. | | Payload keys | Client-side per-peer or group keys distributed outside the relay; unknown to the server. | | Multiple destinations | Partial acceptance is allowed and a result is returned for each record. | | Transport | HTTP and HTTPS are equally supported; the server works directly and behind a proxy. HTTPS is not a protocol requirement. | | Storage | An abstract backend; v1 must have a `disk` driver, further drivers may be added without changing the wire format. | | Compatibility | V1 is a new protocol; old actions and wire formats are neither aliases nor fallbacks. | ## 3. Roles, identities and secrets ### 3.1 Roles - The **relay server** receives HTTP requests and manages queues. - A **client** has exactly one configured VPN IPv4 address and can be both sender and recipient. - The **administrator** configures the single server secret, client tokens, limits and storage driver. The default address space is `10.99.99.0/24`. Valid client addresses range from `10.99.99.2` to `10.99.99.254`, written without leading zeros. A different address space requires shared configuration of all participants, not a wire format change. Different client computers MAY use the same virtual IP. phpvpn neither enforces nor reserves address uniqueness across computers. The system permits collisions, correcting them is the operator's responsibility, and they are a configuration error. An `ACCESS_KEYS` entry authorizes an address, not the identity of a particular computer. ### 3.2 Keys The server and clients use three separate classes of keys: 1. `SERVER_SECRET`: exactly one constant in the PHP file's configuration header, known to the server and authorized clients. The default is the string `"CHANGE_THIS_SERVER_SECRET"`, which the administrator should replace with a secure random value. It is used for `auth-semi`, `info` encryption and derivation of the `auth-full` authentication key. 2. `ACCESS_KEY`: exactly one 32-byte key for a given VPN address. For a private setup it should be random and known only to the server and authorized clients of that address. It is the input secret for deriving the `auth-full` authentication key. The server looks it up in `ACCESS_KEYS` using VPN address `src`; neither the key nor an identifier for it is ever transmitted. 3. `PAYLOAD_KEY`: exactly one fixed 32-byte end-to-end key for each ordered pair of VPN addresses (`src`, `dst`). Only clients of that communication direction know it; the relay server MUST NOT possess it. Distribution is outside the protocol. Every server and client implementation normalizes `SERVER_SECRET` at startup, before configuration validation and before the first cryptographic operation. If the configured value is exactly an empty string of zero bytes, the implementation replaces it at runtime with `"CHANGE_THIS_SERVER_SECRET"`. Throughout the remainder of this document, `SERVER_SECRET` denotes this effective normalized value. Any nonempty value is left unchanged; in particular, the string `"0"`, 32 or 64 ASCII `0` characters and a value consisting of zero bytes `0x00` are not normalized. Cryptographic operations use the exact bytes of the effective `SERVER_SECRET`, without implicit hex or base64 decoding. An empty configured string, a value consisting solely of zero bytes `0x00` and a string consisting solely of ASCII `0` characters are valid inputs and authenticated endpoints must not reject them solely because of their contents; however, such configuration provides no practical secrecy and the public page warns about it. Each `ACCESS_KEY` is written as exactly 64 lowercase hexadecimal characters and decoded into 32 bytes for cryptography. Clients maintain a local `PAYLOAD_KEYS[src][dst]` map; each value is decoded into exactly 32 bytes for AES-256-GCM. `SERVER_SECRET`, `ACCESS_KEY` and `PAYLOAD_KEY` have no identifier transmitted by the protocol. The client selects the single `PAYLOAD_KEY` exclusively from the exact ordered pair `src`, `dst`. The default `ACCESS_KEYS` map contains addresses `10.99.99.2` through `10.99.99.15`. Each key is exactly the two-character lowercase hexadecimal representation of the last octet repeated 32 times, for example 32×`02` for `.2`, 32×`0a` for `.10` and 32×`0f` for `.15`. These publicly derivable defaults are not random secrets. A different address space requires an explicit server configuration change. There is no automatic migration, overwriting of nonempty secrets or probing of historical values. ## 4. HTTP, HTTPS and proxy transport ### 4.1 Common rules The server MUST have identical application behavior over HTTP and HTTPS. HTTP/1.1 is the minimum; a web server or proxy may terminate HTTP/2 or HTTP/3 if it preserves the method, query parameter, body and response meaning. The server: - MUST NOT derive authentication from the TCP peer's IP address; - MUST NOT include the scheme, host, port or proxy headers in cryptographic calculations; - MUST NOT trust `X-Forwarded-For`, `X-Forwarded-Proto`, `Forwarded` or similar headers for authorization or routing; - MUST accept direct connections and connections through a reverse proxy with the same result; - MUST send `Cache-Control: no-store, no-cache, must-revalidate`, `Pragma: no-cache` and `X-Content-Type-Options: nosniff`; - MUST NOT log secrets, authentication HMAC tags, ciphertext, GCM tags or entire requests. The URL contains only `?action=`. Client identity, tokens, authentication HMAC tags and encrypted contents belong exclusively in the body. The proxy must forward the body byte for byte; transforming line endings, decompressing to different contents or rewriting JSON invalidates the HMAC. ### 4.2 Protection boundaries over HTTP Local diagnostics for the first two steps of the client Configuration Wizard and the initial health/info exchanges of Connect do not change this server wire protocol. They capture a specific application request and the received response before protocol parsing so that hosting-injected contents can also be shown as plain inert text. This reconstructs information available in WinHTTP; it is not a packet or TLS capture. Sent bodies, endpoints, authentication and cryptographic verification remain unchanged. Only local IPC between the service and tray is extended. The exact byte slice, reversible `http-octets-v1`, Unicode projection, lifetime and limit are defined in [HTTP details of a failed Wizard probe in client.md](client.md#http-detail-neúspěšného-wizard-probe). Correlation of Connect by epoch and attempt UUID, state snapshots and precisely correlated detail cancellation are defined in [HTTP details of a failed Connect](client.md#http-detail-neúspěšného-connect). Diagnostics do not affect data requests or recovery exchanges, and raw contents are not logged. Plain HTTP is a valid, supported mode. Application cryptography protects secret values and authenticity to the extent described here, but does not replace secure transport. A passive observer of an HTTP connection sees the URL, method, sizes, timing, VPN addresses `src` and `dst`, message identifiers and traffic volume. They see neither payload plaintext nor `info` response plaintext. An active attacker on the HTTP path can copy, replay, delay, drop, reorder or modify requests and responses, or terminate the connection. Without the corresponding key, they cannot create a new valid request HMAC, `data` response HMAC or individual payload GCM tag. The final `data-mac` therefore detects removal, addition or reordering of data lines and any change to `data-result`; changing an individual data record's contents while retaining its GCM tag is detected by subsequent AES-GCM verification. The attacker can still drop the whole response, interrupt the connection or replay an entire previously valid response with the same currently expected `requestId`. Since the server removes records before sending them, failure to deliver a response permanently loses them at relay level. An authenticated request can be successfully replayed only within its 60-second window; a response has no separate age check. The `auth-none` request itself is unauthenticated and an attacker can read, modify or replay it. However, the `health` response binds the server's UTC time and all other operational fields to the fresh client `requestId` with a GCM tag derived from `SERVER_SECRET`. An attacker without that secret cannot substitute a future timestamp or modify a legitimate response in a way that the client accepts. The client rejects an old response for a different `requestId`. An attacker can delay or drop a request or response, causing stale time or unavailability, but cannot undetectably move client signatures into the future. To attack the polling queue, the attacker need not modify traffic in transit or know a key. Passively capturing a valid HTTP `data` request, submitting the copy to the server within the open window and repeating this with new victim requests is sufficient. Each successful copy performs the ordinary at-most-once queue drain for the attacker's connection. This can continuously take all newly pending records and leave the legitimate client an empty queue. This is the explicitly accepted plain-HTTP risk of section 1.2, not a property that v1 detects or remedies. HTTPS additionally protects transport metadata in bodies and headers, authenticates the TLS peer and protects the connection from modification. Whether to use it is an operational decision outside the protocol's mandatory requirements. ## 5. Endpoints | URL | Method | Request | Successful response | |---|---|---|---| | `/phpvpn.php` | `GET`, `HEAD` | no body | HTML operational page | | `/phpvpn.php?action=health` | `POST` | one `auth-none` JSON object | one authenticated `health` JSON object | | `/phpvpn.php?action=info` | `POST` | one `auth-semi` or extended `auth-full` JSON object | one `info` JSON object | | `/phpvpn.php?action=data` | `POST` | NDJSON beginning with `auth-full` | NDJSON with data records and result | Other methods return `405 method_not_allowed` with an `Allow` header. An unknown action returns `404 not_found`. ### 5.1 Operational page `STATUS_PAGE_ENABLED` defaults to `true`. Root GET returns standalone HTML based on `assets/index.html` with the heading `

PHPVPN server is running

`, a 32-random-byte generator using Web Crypto and copying of 64 lowercase hex characters. HTML, CSS and JavaScript are embedded directly in the script. An empty, default, zero-byte or ASCII-zero secret shows the entire red warning `aside` panel. Another secret removes it. When `false`, GET returns `404 not_found` without HTML. HEAD has the corresponding status and headers without a body. The switch does not restrict the REST API. The new data default `./phpvpn_data` neither moves nor copies old data from `./phpvpn`; the administrator performs any migration manually. The page also contains a `Show HTTP Headers` button. It opens a modal `