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:
open_in or Sys.remove;Unix.gettimeofday;Unix.socket;print_endline;Random.self_init;Domain.spawn or Sys.command.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:
Hermetic.Unsafe gives back the whole standard library.external declaration binds a C function, which can reach the system directly.$ opam install hermetichermetic 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.
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:
open!. A plain open raises warning 33 when the file uses nothing from the prelude, and warning 44, under -w +a, when it shadows a standard library name.hermetic.ocamllex, ocamlyacc or menhir in a library of their own. The code they generate calls Lexing.engine, Parsing.yyparse or Obj.magic, which the prelude refuses.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)))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.
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 igrep -w Unsafe finds every such use, unless a module alias such as module S = Unsafe hides the uses that follow it.
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.
open_in, open_out and the openers of In_channel and Out_channel), the file functions of Sys and Unix, the current directory and temporary files are refused. Reading and writing a channel the code is handed still works.Unix.time, Unix.gettimeofday, Unix.sleep, the timers, Thread.delay and the waits with a timeout are refused. The processor time, Sys.time, stays.Unix.socket, bind, connect, listen and the name resolvers are refused. I/O on a socket the code is handed stays, and so does accept on a listening socket it is handed.stdin, stdout, stderr, print_*, read_*, Printf.printf, the standard formatters of Format and Printexc.print are refused, and so is Arg.parse, which prints its usage message and can exit. A formatter, a buffer or a channel the code is handed stays.Random.self_init and Random.State.make_self_init are refused. Hashtbl.create and the other create functions that take ?random lose that argument, and every table is made with ~random:false. Passing ~random is then a type error with no alert.Domain.spawn, Sys.command and the Unix functions that spawn, wait for or signal a process are refused. Thread.create stays.Obj, the readers of Marshal and input_value, the unsafe_ accessors, Lexing.engine and the internals of Parsing are refused as unsafe. The writers of Marshal stay.Eio_main, Eio_unix and Eio's backends, Mtime_clock, Ptime_clock, Fmt_tty, Dynlink and Runtime_events. Some units of Base and ocamlformat that re-export the standard library without refusals are declared empty as well.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.
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.
Fmt.pr does, is not caught. Base re-exports Obj.magic and other refused values, and the prelude cannot declare Base itself empty.Sys.getenv), the command line (Sys.argv), exit and the signals stay. Eio's env does not provide them, so there is no capability to take instead.open! Hermetic hides any module of your own library named Unsafe, or named like a standard library module.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.
ISC. See LICENSE.md.