We’re open sourcing our privacy proxy CLI (opens in new tab)
Oblivious HTTP (OHTTP) is difficult to debug because requests pass through multiple parties, use binary HTTP encoding, and depend on several RFC-defined cryptographic steps. Cloudflare created and open-sourced `pvcli`, a CLI that simplifies testing and troubleshooting privacy protocols by exposing each stage of the process. Released under Apache-2.0, the tool is designed for production-scale debugging and community contributions. ## Why OHTTP Debugging Is Complex - OHTTP ensures that no single party can know both the client’s identity and the requested content. - It relies on two non-colluding servers: - A **relay** that sees the client but not the request contents. - A **gateway** that decrypts the request but does not see the client’s identity. - A typical request proceeds through several stages: - The client retrieves the gateway’s public key. - The client encrypts the request and sends it to the relay. - The relay forwards the anonymized request to the gateway. - The gateway decrypts it and contacts the target. - The response travels back through the gateway and relay before being decrypted by the client. - Every stage can introduce failures, making it difficult to identify whether the problem lies with the client, relay, gateway, or target. ## Why Cloudflare Built `pvcli` - Privacy products such as Privacy Proxy and Privacy Gateway introduced increasing operational complexity and customer-specific requirements. - Engineers frequently had to create one-off clients to test customer deployments. - Diagnosing failures required determining which protocol step had failed and which party was responsible. - OHTTP’s binary formats made manual inspection especially error-prone. - `pvcli` consolidates privacy-protocol functionality into one familiar CLI with support for different protocols and architectures. ## Debugging OHTTP Manually - Engineers first fetch the gateway’s public key, receiving a long hexadecimal binary payload. - They must manually parse fields according to RFC 9458, including: - The key entry length. - The public key identifier. - The asymmetric encryption method, such as DHKEM with X25519 and HKDF-SHA256. - The gateway’s public key. - Supported symmetric encryption algorithms, such as HKDF-SHA256 and AES-128-GCM. - The original HTTP request must then be converted into binary HTTP according to RFC 9292. - Engineers manually verify encoded fields such as: - The request method (`POST`). - The HTTPS scheme. - The target hostname. - The request path and headers. - The JSON body. - Finally, they need custom scripts to encrypt the binary request and construct the OHTTP wrapper request. ## Using `pvcli` - A complete OHTTP request can be issued with a single command: ```bash pvcli --ohttp \ --first-hop https://relay-cloudflare.ohttp.info \ --proxy https://gateway.ohttp.info \ -X POST \ --header "content-type: application/json" \ --data '{"test":1}' \ https://target.ohttp.info/anything ``` - The tool handles the relay, gateway, encryption, binary HTTP encoding, and target request flow. - It provides a clearer view of each protocol step, replacing manual hexadecimal parsing and bespoke scripts with a repeatable debugging workflow. `pvcli` is a practical way to test live OHTTP deployments, isolate failures across the relay and gateway chain, and reduce the risk of mistakes when inspecting binary protocol data.