LIBCHERI(3)

NAME
libcheri, sandbox_class_new, sandbox_class_method_declare, sandbox_class_getbase, sandbox_class_getlength, sandbox_class_destroy, sandbox_object_new, sandbox_object_reset, sandbox_object_getbase, sandbox_object_getlength, sandbox_object_getobject, sandbox_object_getsystemobject, sandbox_object_cinvoke, sandbox_object_invoke, sandbox_object_destroy - Library interface for CHERI sandboxing

LIBRARY
libcheri

SYNOPSIS
#include <machine/cheri.h>
#include <machine/cheric.h>
#include <sandbox.h>
int
sandbox_class_new(const char *path, size_t sandboxlen, struct sandbox_class **sbcpp);
int
sandbox_class_method_declare(struct sandbox_class *sbcp, u_int methodnum, const char *methodname);
size_t
sandbox_class_getbase(struct sandbox_class *sbcp);
size_t
sandbox_class_getlength(struct sandbox_class *sbcp);
void
sandbox_class_destroy(struct sandbox_class *sbcp);
int
sandbox_object_new(struct sandbox_class *sbcp, size_t heaplen, struct sandbox_object **sbopp);
int
sandbox_object_reset(struct sandbox_object *sbop);
void *
sandbox_object_getbase(struct sandbox_object *sbop);
void *
sandbox_object_getlength(struct sandbox_object *sbop);
struct cheri_object
sandbox_object_getobject(struct sandbox_object *sbop);
struct cheri_object
sandbox_object_getsystemobject(struct sandbox_object *sbop);
#if __has_feature(capabilities)
register_t
sandbox_object_cinvoke(struct sandbox_object *sbop, u_int methodnum, register_t a1, register_t a2, register_t a3, register_t a4, register_t a5, register_t a6, register_t a7, __capability void *c3, __capability void *c4, __capability void *c5, __capability void *c6, __capability void *c7, __capability void *c8, __capability void *c9, __capability void *c10);
#else
register_t
sandbox_object_invoke(struct sandbox_object *sbop, u_int methodnum, register_t a1, register_t a2, register_t a3, register_t a4, register_t a5, register_t a6, register_t a7, struct chericap *c3p, struct chericap *c4p, struct chericap *c5p, struct chericap *c6p, struct chericap *c7p, struct chericap *c8p, struct chericap *c9p, struct chericap *c10p);
#endif
void
sandbox_object_destroy(struct sandbox_object *sbop);
sandbox_object_getsystemobject(struct sandbox_object *sbop);

DESCRIPTION
libcheri provides a programmer-friendly interface to CHERI in-process sandboxing using the object-capability security model. The programming interface requires programmers to define sandboxes in terms of classes (particular pieces of code that will run in sandboxes) and objects (in-execution instances of sandboxed code). In libcheri, classes are statically linked memory images (in the future to be ELF binaries).

  Sandbox classes
A new class may be created using sandbox_class_new(), which accepts path, a pathname to the class's memory image and sandboxlen, an address-space size in bytes. If successful, a pointer to the class will be stored in sbcpp. Classes implement a single invocation entry point, which can then fan out to multiple methods courtesy a method argument.

Optionally, sandbox_class_method_declare() may be used to associate descriptive strings with method numbers, which will then be visible via procstat(1). The method number is passed via methodnum and string via methodname. sandbox_class_getbase() returns the base address for a sandbox's code micro-address space in virtual memory; use of this function is discouraged as the underlying implementation of sandbox objects may change over time. sandbox_class_getlength() can be used to query the length of the code micro-address space shared between all sandbox objects in the class; use of this function is discouraged as the underlying implementation of sandbox objects may change over time.

Classes may be destroyed, once all its sandbox objects have been freed, using sandbox_class_destroy().

  Sandbox objects
Sandbox instances may be created using sandbox_object_new(), which accepts a previously created class passed via sbcp, with a heap size specified by heaplen, and on success returns a sandbox object via sbopp. When a sandbox object is no longer required, it can be destroyed by passing it to sandbox_object_destroy(). A sandbox object may be restored to a pristine state by passing it to sandbox_object_reset(). sandbox_object_getbase() returns the base address for a sandbox's micro-address space in virtual memory; use of this function is discouraged as the underlying implementation of sandbox objects may change over time. sandbox_class_getlength() can be used to query the default length of the data micro-address spaces use for all sandbox objects in the class; use of this function is discouraged as the underlying implementation of sandbox objects may change over time.

sandbox_object_getobject() returns the sandbox object's underlying CHERI object. sandbox_object_getsystemobject() returns the CHERI system-class instance suitable for passing into the sandbox object.

  Object invocation
Sandbox methods may be invoked using sandbox_object_cinvoke() if CHERI compiler support is present (allowing use of __capability), or sandbox_object_invoke() (which can be used without compiler support). Both interfaces accept a sandbox object pointer, sbop, method number via methodnum, and general-purpose and capability register arguments. These functions are implemented as wrappers around cheri_invoke(3).

  Sandbox monitoring

Sandboxes within a libcheri process may be monitored using procstat(1), or programmatically using libprocstat(3) APIs. Various stastics are maintained, including object counts, method invocation counts, and sandbox fault information.

RETURN VALUES

sandbox_class_destroy() and sandbox_object_destroy() do not have return values as they cannot fail.

sandbox_object_cinvoke() and sandbox_object_invoke() return the value returned by the invoked object method unless a sandbox fault occurs, in which case -1 will be returned. As a method returning -1 cannot be distinguished from a fault in the caller, use of negative return values for method return values is discouraged.

SEE ALSO
cheri_invoke(3), libprocstat(3), procstat(1)

AUTHORS
This software and this manual page were written by Robert N. M. Watson, and developed by SRI International and the University of Cambridge Computer Laboratory under DARPA/AFRL contract (FA8750-10-C-0237) (“CTSRD”), as part of the DARPA CRASH research programme.

BUGS
libcheri relies on classes being statically linked memory images rather than ELF binaries; this should be corrected by adding a small run-time ELF loader to the library.

The sandbox_object_cinvoke() and sandbox_object_invoke() APIs cannot distinguish the invoked object returning a negative value and a sandbox fault causing a negative value to be returned.

It is not clear how programmers should select a suitable sandboxlen value to pass to sandbox_class_new().

This man page should include information on how to structure and link code intended to run within sandboxes.

This man page does not document the CHERI system class.