hermetic

Enforce Eio's capabilities at compile time.

Eio gives an application its access to the outside world as ordinary values. The env that Eio_main.run passes to the application holds the file system, the clocks and the network. The application hands each function only the part it needs, such as Eio.Stdenv.fs env. Eio calls these values capabilities. A function can then do I/O, but only on what it was given. A test can give it a mock clock or an in-memory file system, and a reviewer can see what it touches from its arguments.

OCaml does not enforce this. The standard library lets any function call open_in, Unix.gettimeofday or Sys.command without being given anything, so code can bypass Eio. Eio's design note says so, and the discussions on the OCaml forum come back to it: without the compiler's help, passing capabilities is only a convention.

hermetic aims to solve this issue. It replaces the standard library in each source file that starts with open! Hermetic. In that file, a call that reaches one of these resources without being given it no longer compiles:

The compiler also rejects unsafe operations that could forge a capability, such as Obj.magic and the Marshal readers. Each error names the Eio.Stdenv capability to use instead.

hermetic catches mistakes, such as an open_in written out of habit. It does not stop an author who wants to cheat, and its protection is still partial:

Installation

$ opam install hermetic

hermetic depends on the standard library only, so it links wherever OCaml does, js_of_ocaml and wasm_of_ocaml included. It does not depend on Eio. Its restated Unix and UnixLabels are the library hermetic.unix, and its restated Thread is hermetic.threads; see Unix and threads.

Usage

Add hermetic to the library's dependencies:

(library
 (name model)
 (libraries hermetic))

Then open the prelude on the first line of each source file. A call to open_in no longer builds:

# open! Hermetic;;
# let load () = open_in "model.bin";;
Line 1, characters 15-22:
Alert ambient: Hermetic.open_in
Opens a file by name: take Eio.Stdenv.fs or Eio.Stdenv.cwd (an Eio.Path) as an argument, or the file's contents.

Line 1, characters 15-22:
Error: This expression has type ambient
       This is not a function; it cannot be applied.

A refused value keeps its name but gets one of three abstract types. The type ambient marks a value that reaches an Eio capability without being handed it. The type unsafe marks a value that can forge memory or a value of any type. The type unreviewed marks a value this version of hermetic has not reviewed yet. Nothing in the prelude consumes these types, so using such a value is an error in every build profile. Silencing the alert hides the message but not the error.

A few rules make this work:

Applying it to a whole library

A compiler flag opens the prelude in every file of a library:

(library
 (name model)
 (libraries hermetic)
 (flags (:standard -open Hermetic)))

The flag also opens it in the interfaces. A type an interface then names through a module the prelude restates, such as Digest.t, is the prelude's, and the library's consumers need hermetic in their path. This is why the open! at the top of each file is the recommended setup.

A library can also ship without hermetic and be checked in a separate directory. There, a library stanza compiles a copy of each source file with the flag. copy_files# keeps the line directives, so errors point at the original files:

(copy_files# (files ../lib/*.ml))

(library
 (name model_hermetic)
 (libraries hermetic)
 (flags (:standard -open Hermetic)))

Unix and threads

The prelude restates Unix, UnixLabels and Thread as well, in the libraries hermetic.unix and hermetic.threads, which depend on unix and threads. A library whose files use them through the prelude names the sub-library too:

(library
 (name server)
 (libraries hermetic hermetic.unix))

hermetic itself depends on the standard library only, so a program that uses neither links neither unix nor threads, even with -linkall. The prelude names Unix all the same: in a file that opens it, without hermetic.unix, Unix.getpid fails with The module Unix is an alias for module Hermetic__Unix, which is missing and never reaches the unix library's own Unix.

Escaping the prelude

Hermetic.Unsafe is the standard library without refusals. Use it only where you have checked the call:

open! Hermetic

let get b i = Unsafe.Bytes.unsafe_get b i

grep -w Unsafe finds every such use, unless a module alias such as module S = Unsafe hides the uses that follow it.

What it refuses

The prelude refuses values by the capability they reach, and keeps everything that works on what the code is handed. The Unix and Thread values below are kept or refused in a library that names hermetic.unix or hermetic.threads; without it, none of them is reachable.

The generated documentation of the Hermetic module (dune build @doc) gives each refused value with its message. test/refusals/hermetic.txt lists every refusal, one per line.

Supported compilers

hermetic supports OCaml 4.14 and 5.0 to 5.5, and an older compiler fails the build. Eio itself needs OCaml 5.2. Compilers before 5.3 name the type of a refused value by its unit in the error, as in Hermetic__Refused.ambient.

The prelude is generated at build time from the installed compiler's standard library and a policy that names every value it has reviewed. The upper bound moves only after a review of each new compiler, because until then its new values are refused as unreviewed.

Limits

Emily is a capability-secure subset of OCaml checked by a verifier. hermetic uses the stock compiler and keeps mutable globals. Joe-E does the same for Java, and cap-std is a capability-based standard library for Rust.

Licence

ISC. See LICENSE.md.