package ohttp-cohttp-lwt

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.

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

License

ISC.