Kettlecorn.ETF (kettlecorn v0.1.0)

Copy Markdown View Source

A strict decoder for terms produced by the (untrusted) guest VM.

:erlang.binary_to_term/2 with [:safe] is unsuitable for guest data:

  • it decodes pids, ports and references into live host terms: a guest pid with the host's node name can identify a host process;
  • it decodes local funs referencing host modules;
  • it fails on any atom the host doesn't know.

This decoder only produces plain data. Atoms are returned when they already exist on the host and as {:unknown_atom, name} tuples otherwise, so a guest can never grow the host's atom table. Pids become Kettlecorn.Pid handles for addressing the guest. Ports and references become Kettlecorn.Opaque placeholders with no usable identity. Funs are rejected.

A map whose :__struct__ is an atom would be a struct of that module on the host, and protocols dispatch on it: a guest could send a %File.Stream{} with a path of its choice, and host code enumerating it would read that file. Such maps decode as Kettlecorn.Struct, which holds the module and the other fields as data.

Nesting depth and element counts are bounded. The :max_bytes budget (default 64 MiB) charges retained binary data in full and estimates the heap space for each decoded node; exceeding it returns :too_large. Input slices are copied so decoded binaries cannot retain unrelated data. PID handle copies and retained UTF-8 conversions of Latin-1 atom names are charged separately. For compressed terms, the budget counts the inflated data, and terms larger than :max_bytes are rejected. A list of empty lists, for instance, takes 16 bytes of heap per byte of input on a 64-bit host.

Summary

Functions

Decodes binary. Option :max_bytes sets the budget for retained binary data and estimated heap space (default 64 MiB). Option :vm binds PID handles to their originating VM; the default produces unbound handles.

Types

decode_error()

@type decode_error() :: :badarg | :too_deep | :too_large | {:unsupported, atom()}

Functions

decode(binary, opts \\ [])

@spec decode(binary(), keyword()) :: {:ok, term()} | {:error, decode_error()}

Decodes binary. Option :max_bytes sets the budget for retained binary data and estimated heap space (default 64 MiB). Option :vm binds PID handles to their originating VM; the default produces unbound handles.