ohttp

Oblivious HTTP for OCaml. ohttp implements RFC 9458, which lets a client send an HTTP request through a relay so that no single party sees both who is asking and what is asked. bhttp implements the message format that it carries, Binary HTTP (RFC 9292), and is a package of its own.

Neither is an HTTP library, and neither depends on one. An encapsulated message is a string, and any HTTP library can post it. Adapter packages carry the messages over cohttp-lwt, cohttp-eio, and Piaf, as a client, a relay, and a gateway.

Status: unaudited and not production-ready. Intended for interoperability review. Read the security limitations before using the libraries.

Try it

You need OCaml 4.14 or later and an active opam switch:

git clone https://github.com/thevilledev/ocaml-ohttp.git
cd ocaml-ohttp
opam install . --deps-only
opam exec -- dune exec examples/basic.exe

The example runs one exchange between a client and a gateway:

gateway received GET https://example.com/hello
client received 200: hello from the target

With cohttp-lwt-unix installed, opam exec -- dune build @e2e runs a client, a relay, a gateway, and a target over real HTTP on your machine, through the ohttp-cohttp-lwt adapter. Read the example source and the getting started guide to use the libraries in your own project.

What it provides

• bhttp: requests and responses in both framings of RFC 9292, with informational responses, trailers, padding, and truncation. No dependencies.
• ohttp: key configurations in both of their encodings, and request and response encapsulation for clients and gateways, over every KEM, KDF, and AEAD of the hpke package, including X-Wing and the other post-quantum KEMs.
• Replay protection for gateways: a cache of recent requests, the date check, and the date problem through which clients correct their clocks.
• The fields, checks, and error responses of the HTTP binding (RFC 9458 Section 5), and Ohttp.Service: the client, relay, and gateway as steps from HTTP messages to HTTP messages, without I/O.
• Adapters for HTTP libraries, each a package of its own: ohttp-cohttp-lwt, ohttp-cohttp-eio, and ohttp-piaf, with ohttp-cohttp for the types that the cohttp adapters share. Each has a client that fetches key configurations and calls through a relay, a relay handler, a gateway handler with replay protection, and forwarding to an allowlist of targets, all with limits on the length of messages and on the requests in flight.
• Chunked Oblivious HTTP (draft-ietf-ohai-chunked-ohttp-08), experimental.
• The examples of both RFCs and of the draft reproduced byte for byte, and interoperability with the Go and Rust implementations of the RFC's authors, checked in both roles.

Applications authenticate key configurations, limit the rate of requests, and decide which requests to check for replay. See protocol support for the exact feature set and known gaps.

Documentation

I want to…	Start here
Install the libraries and understand the example	Getting started
Use them with cohttp, Piaf, or another HTTP library	HTTP libraries
Check supported features and algorithms	Protocol support
See how other implementations compare	Interoperability
Build, test, or find a module	Development guide
Prepare an opam release	Release checklist
Review limitations or report a vulnerability	Security
See what changed	Changelog

License

ISC.