ohttp

ohttp implements Oblivious HTTP (RFC 9458) in OCaml: a client encapsulates a request for a gateway and sends it through a relay, so that the relay learns who is asking and the gateway what is asked, and neither learns both. It builds on the hpke package for RFC 9180, and on bhttp for the messages that it carries.

The library is unaudited and not production-ready. It is intended for interoperability review.

Application entry points

The library performs no I/O. An encapsulated message is a string that any HTTP library can post, and everything else is a function from strings to strings.

A client reads the gateway's key configurations with Ohttp.Key_config.decode_list, picks one with Ohttp.Key_config.select_from_list, and encapsulates a request with Ohttp.Http_message.encapsulate_request. It posts the result to the relay with Ohttp.Http_binding.Client.request_headers, checks the answer with Ohttp.Http_binding.Client.check_response, and opens it with Ohttp.Http_message.decapsulate_response.

A gateway holds Ohttp.Gateway.Key values in a Ohttp.Gateway.t, serves Ohttp.Gateway.encoded_key_configs, and answers a request with Ohttp.Http_message.decapsulate_request, Ohttp.Http_message.encapsulate_response, and, when the encapsulation cannot be removed, Ohttp.Http_binding.Gateway.error_response. A gateway that serves requests that are not idempotent also checks each one with Ohttp.Replay.check.

Ohttp.Service puts these steps together for each party, as functions from the HTTP message that a client, a relay, or a gateway receives to the one that it sends. The adapter packages ohttp-cohttp-lwt, ohttp-cohttp-eio, and ohttp-piaf wrap it for their HTTP libraries.

Ohttp.Client and Ohttp.Gateway do the same for byte strings that are not Binary HTTP. Ohttp.Chunked is an experimental implementation of chunked Oblivious HTTP (draft-ietf-ohai-chunked-ohttp-08), and its interface may change.

Modules

Application interface

• Ohttp.Key_config Key configurations (RFC 9458 Section 3).
• Ohttp.Http_message Exchanges of Binary HTTP messages: Ohttp.Client and Ohttp.Gateway with the encoding and decoding of Bhttp around them, and the rules that RFC 9458 adds for what is encapsulated.
• Ohttp.Http_binding How encapsulated messages travel over HTTP (RFC 9458 Section 5, and RFC 9540 for finding a gateway).
• Ohttp.Replay Defences against replayed requests (RFC 9458 Section 6.5).
• Ohttp.Service The client, relay, and gateway of RFC 9458 Section 5, as steps from HTTP messages to HTTP messages.
• Ohttp.Client The client's side of an exchange (RFC 9458 Sections 4.3 and 4.4).
• Ohttp.Gateway The gateway's side of an exchange (RFC 9458 Sections 4.3 and 4.4).
• Ohttp.Chunked Chunked Oblivious HTTP (draft-ietf-ohai-chunked-ohttp-08).
• Ohttp.Suite HPKE algorithms as Oblivious HTTP names them (RFC 9458 Section 3.1).
• Ohttp.Media_type Media types of Oblivious HTTP (RFC 9458 Section 9) and Binary HTTP (RFC 9292 Section 7).
• Ohttp.Error Errors returned by the public API. Messages describe classes of invalid input and never contain key material or message content.

Protocol internals

• Ohttp.Encapsulation The byte layout and key schedule of encapsulated messages (RFC 9458 Sections 4.1 to 4.4).

Guides

• Getting started: installation and the runnable example.
• HTTP libraries: the adapters for cohttp-lwt, cohttp-eio, and Piaf, and carrying the messages with anything else.
• Protocol support: features, algorithms, and known gaps.
• Interoperability: how other implementations compare.
• Development: building, testing, and the module map.
• Release checklist: preparing and validating the opam packages.

These guides are also installed as Markdown under the package's documentation directory.

Security

See the repository's security policy for what the library checks, what it leaves to applications, its known limitations, and private vulnerability reporting.