Debugging Oblivious HTTP: Open-Sourcing Our Privacy Proxy CLI

The Complexity of Debugging Privacy-Preserving Protocols

Debugging privacy-preserving protocols is inherently difficult. Oblivious HTTP (OHTTP), for instance, requires multiple discrete steps executed across four distinct parties. These protocols involve binary HTTP encoding and specification details spread across multiple draft RFCs. Operating protocols like OHTTP at a scale of millions of requests per second highlights the friction involved in development and incident response. To streamline this process, Cloudflare built and open-sourced a curl-like tool called pvcli (privacy-client) under the Apache-2.0 License.

Consider a single-line command executing a complete OHTTP request across a relay, a gateway, and an origin:

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

Why Privacy Protocols Create Debugging Friction

Cloudflare’s Privacy Proxy and Privacy Gateway products power high-profile deployments such as Apple’s Private Relay, Microsoft’s Edge Secure Network VPN, and Flo Health’s Anonymous Mode. As product suites and customer bases grow, customer-specific requirements introduce deep domain complexity.

OHTTP guarantees that no single party knows both the client’s identity and the content of their request. Achieving this requires two non-colluding servers: a relay and a gateway. The data flow requires significant back-and-forth:

• The client fetches the public key from the gateway.
• The client encrypts the request payload and transmits it to the relay.
• The relay strips identifying metadata from the encrypted request and passes it to the gateway.
• The gateway decrypts the request and forwards it to the target origin.
• The target processes the payload and returns a response to the gateway.
• The gateway encrypts the response and hands it to the relay.
• The relay routes the encrypted response back to the client for final decryption.

Every step represents a potential point of failure. Engineers traditionally faced tedious troubleshooting tasks, such as writing custom one-off client scripts, isolating whether a bug originated in local systems or customer deployments, and parsing raw binary HTTP structures manually.

Manual OHTTP Debugging vs. Binary Verification Pitfalls

To understand the value of pvcli, examine what manual debugging entails. Operating an OHTTP relay in front of a customer gateway requires executing end-to-end tests for a basic POST /anything request.

First, fetching the public key via curl returns a complex hex-encoded string. According to RFC 9458 Section 3, engineers must manually slice this payload to identify key IDs, asymmetric encryption methods (such as DHKEM with X25519 and HKDF-SHA256), and symmetric cryptographic IDs.

Next, the original HTTP request must be translated into binary HTTP (BHTTP) according to RFC 9292:

0204504f5354056874747073117461726765742e6f687474702e696e666f092f616e797468696e670c636f6e74656e742d74797065106170706c69636174696f6e2f6a736f6e0a757365722d6167656e740c6665727265742f302e312e30000a7b2274657374223a317d2000

Validating length-prefixed fields introduces severe human error risks. For instance, if a stray space character (0x20) creeps into the byte stream before the final termination bytes, the gateway will reject the payload with a generic malformed request error. Tracing this requires inspecting raw byte arrays, comparing offsets, and coordinating gateway log access with third parties.

How pvcli Streamlines Protocol Testing

The pvcli utility eliminates manual binary slicing and script gluing by consolidating multi-party protocol testing into a familiar command-line interface. Designed with the “principle of least surprise,” its syntax mirrors standard curl arguments.

To install pvcli, ensure you have Rust installed, then pull the repository directly via Cargo:

curl https://sh.rustup.rs -sSf | sh
cargo install --git https://github.com/cloudflareresearch/pvcli

Standard connectivity checks work out of the box, with verbose flags providing tiered insight into underlying operations:

pvcli https://cloudflare.com/cdn-cgi/trace
pvcli -v --http3 https://cloudflare.com/cdn-cgi/trace
pvcli -vvv --http3 https://cloudflare.com/cdn-cgi/trace

Advanced Configuration: Relays, Headers, and mTLS

Beyond basic proxying, pvcli handles advanced architectural requirements such as custom relay routing headers and mutual TLS (mTLS) authentication.

When you need to pass authorization headers specifically to the relay rather than the target origin, use the --first-hop-header flag:

pvcli -vvv --ohttp 
  --first-hop https://relay-cloudflare.ohttp.info 
  --first-hop-header "authorization: Bearer relay-token" 
  --proxy https://gateway.ohttp.info 
  -X POST 
  --header "content-type: application/json" 
  --data '{"test":1}' 
  https://target.ohttp.info/anything

For high-security environments requiring client certificate verification between the client and the relay, supply mTLS credentials using --first-hop-client and --first-hop-key:

pvcli -vvv --ohttp 
  --first-hop https://relay-cloudflare.ohttp.info 
  --first-hop-client ./relay-client.pem 
  --first-hop-key ./relay-client.key 
  --proxy https://gateway.ohttp.info 
  -X POST 
  --header "content-type: application/json" 
  --data '{"test":1}' 
  https://target.ohttp.info/anything

Architectural Scope and Future Roadmap

While standalone Rust libraries from developers like Martin Thomson and Chris Wood provided strong foundations for OHTTP implementations, they often remain protocol-specific. pvcli aims to unify multiple privacy-preserving architectures under a single utility. The current release supports OHTTP and CONNECT proxying, with upcoming support planned for MASQUE and Privacy Pass.

Contributions to the open-source repository are actively welcomed. The public roadmap includes:

• MASQUE: Support for proxying TCP over HTTP/3, alongside UDP and IP over HTTP/2 and HTTP/3.
• OHTTP Enhancements: Implementation of post-quantum cryptography, integrated timing and latency telemetry, Chunked OHTTP support, and expanded logging depth.

Primary reference: Review the original announcement for exact release details. This article is an independent explanation and does not reproduce the source text.