## **Debugging Privacy-Preserving Protocols Is Hard — Meet pvcli**
Debugging privacy-preserving protocols can be a daunting task. Oblivious HTTP (OHTTP), for instance, involves multiple steps across different parties, binary HTTP encoding, and specifications spread across numerous draft RFCs. At Cloudflare, we’ve operated protocols like Oblivious HTTP at the scale of millions of requests per second. From this experience, we built **pvcli** — a clean, open-source CLI tool designed to simplify the testing and debugging of privacy protocols.
—
## **Why Privacy Protocols Are Difficult to Debug**
Many of our products — including Privacy Proxy, Privacy Gateway, Private Relay, and others — rely on OHTTP to ensure that no single party can both see who made a request and what the request was. While this provides strong privacy guarantees, it also introduces complexity.
A typical OHTTP flow involves:
1. The client fetching a public key from the gateway.
2. Encrypting and sending the request to the relay.
3. The relay stripping client identification and forwarding to the gateway.
4. The gateway decrypting and forwarding to the target.
5. The response following a similar path back to the client.
Each step is a potential point of failure, and determining whether an issue originates from the client, relay, gateway, or target can be time-consuming. In the past, testing required piecing together custom scripts, manually parsing binary HTTP, and referencing multiple RFCs — a process that was both fragile and error-prone.
—
## **Debugging Without pvcli**
Earlier approaches involved writing one-off clients, manually handling binary encoding, and painstakingly comparing logs. For example, a simple POST request could require:
– Manually parsing public keys and asymmetric encryption parameters.
– Building binary HTTP by hand, referencing RFC 9292.
– Encrypting payloads according to OHTTP specifications.
– Verifying every byte to ensure correctness.
A misplaced space or incorrect header could cause failures, and distinguishing between client, relay, or gateway issues often meant long back-and-forth with customers or diving deep into raw packet data.
—
## **Debugging With pvcli**
With pvcli, all of this is simplified into a single command. For example:
“`bash
pvcli –ohttp
–first-hop
–proxy
-X POST
–header “content-type: application/json”
–data ‘{“test”:1}’
“`
Behind the scenes, pvcli:
– Handles key retrieval and encryption.
– Builds and encodes binary HTTP requests.
– Logs every step of the process, from configuration to encrypted payloads.
– Supports verbose logging for deep debugging (`-v`, `-vv`, `-vvv`).
The output includes structured logs showing:
– Client configuration (keys, algorithms).
– HTTP request details (method, headers, body).
– Encrypted payloads in both binary and hex formats.
– Cloudflare-specific diagnostic data (country, ASN, etc.).
This makes it easy to see exactly where a failure occurs without manual packet inspection or custom scripts.
—
## **What pvcli Can Do**
Beyond OHTTP, pvcli is designed to support a wide range of privacy-preserving protocols. Current features include:
– **OHTTP**: Full request/response lifecycle with relay and gateway support.
– **Custom Headers**: Add headers at both the target and relay stages.
– **Mutual TLS**: Authenticate to relays using client certificates.
– **Verbose Logging**: Step-by-step insights into every operation.
Installation is straightforward:
“`bash
curl -sSf https://raw.githubusercontent.com/cloudflareresearch/pvcli/main/install.sh | sh
“`
It’s built with the “principle of least surprise” in mind, so if you’ve used `curl`, you’ll feel right at home.
—
## **FAQ**
**What is pvcli?**
pvcli is an open-source CLI tool developed by Cloudflare to simplify debugging and testing of privacy-preserving protocols like Oblivious HTTP.
**What protocols does pvcli support?**
Currently, pvcli supports Oblivious HTTP (OHTTP), with plans to add support for MASQUE, HTTP/3, UDP, IP-based protocols, and post-quantum cryptography.
**How do I install pvcli?**
You can install it using the install script provided in the repository or via `cargo install` if you have Rust installed.
**Can pvcli test mTLS authentication?**
Yes, pvcli supports mutual TLS authentication for the first-hop relay using client certificates and keys.
**Is pvcli open source?**
Yes, pvcli is released under the Apache-2.0 License and is open for contributions.
—
## **Conclusion**
pvcli transforms the debugging experience for privacy-preserving protocols by combining multiple capabilities into one intuitive tool. Whether you need to test an OHTTP request, inspect encrypted payloads, or troubleshoot relay-gateway communication, pvcli provides the visibility and simplicity required for modern privacy infrastructure.
We invite the community to try it out, contribute, and help shape the future of privacy-preserving protocol testing. Clone the repo at [https://github.com/cloudflareresearch/pvcli](https://github.com/cloudflareresearch/pvcli) and join us in building a more private internet.
