From 169a5f024737043f57d66da28fdf0848acd17dba Mon Sep 17 00:00:00 2001 From: Dapeng Gao Date: Mon, 25 Mar 2024 16:15:08 +0000 Subject: [PATCH] c18n: Update man page for ubiquitous c18n --- share/man/man7/compartmentalization.7 | 127 +++++++++++++------------- 1 file changed, 65 insertions(+), 62 deletions(-) diff --git a/share/man/man7/compartmentalization.7 b/share/man/man7/compartmentalization.7 index 239616e1ab4d..da3879a08000 100644 --- a/share/man/man7/compartmentalization.7 +++ b/share/man/man7/compartmentalization.7 @@ -23,7 +23,7 @@ .\" .\" $FreeBSD$ .\" -.Dd October 26 2022 +.Dd March 22 2024 .Dt COMPARTMENTALIZATION 7 .Os .Sh NAME @@ -34,53 +34,48 @@ This document contains instructions for using the library-based compartmentalization (c18n) prototype. .Pp -To launch a dynamically-linked pure-capability application with library-based -compartmentalization, use the special runtime linker located at -.Pa /libexec/ld-elf-c18n.so.1 . -This can be done either explicitly, by invoking -.Pp -.Dl /libexec/ld-elf-c18n.so.1 Ar executable -.Pp -or implicitly, by setting the -.Sy INTERP -field of the program header of the target executable to the special linker's -path. -Said -.Sy INTERP -field can be inspected by invoking -.Pp -.Dl readelf -l Ar executable +Library-based compartmentalization contains a set of features provided by +.Xr rtld 1 +and other system libraries that enhances the security of existing +dynamically-linked pure-capability programs. .Pp -and can be set during the linking phase of compilation, typically by supplying -the following option +A new process inherits the compartmentalization setting of its parent. +To enable c18n for all new processes across the entire system, run +.Dl sysctl security.cheri.lib_based_c18n_default=1 .Pp -.Dl -Wl,--dynamic-linker=/libexec/ld-elf-c18n.so.1 +To override this and permanently enable or disable c18n for a particular +executable, use the +.Xr elfctl 1 +tool to write the setting into the executable. .Pp -to the compiler. -Alternatively, use the -.Sy patchelf -utility to directly modify the -.Sy INTERP -field of an executable, although it is reportedly unreliable at times. +To override this and temporarily enable or disable c18n for a particular +executable, run +.Dl proccontrol -m cheric18n -s enable Ar executable +or +.Dl proccontrol -m cheric18n -s disable Ar executable +as appropriate. .Pp -Environment variables recognized by -.Xr rtld 1 -adopt the prefix LD_C18N_ when compartmentalization is enabled. -For example, LD_LIBRARY_PATH becomes LD_C18N_LIBRARY_PATH. +Overriding this still are the environment variables +.Ev LD_COMPARTMENT_ENABLE +and +.Ev LD_COMPARTMENT_DISABLE . +If both environtment variables are set, c18n is disabled. +Note that environment variables are not reliable inherited when processes fork. .Pp -Compartmentalization currently depends on modified versions of +Compartmentalization depends on modified versions of .Lb libc and .Lb libthr . These are located in .Pa /usr/lib/c18n . -The modified runtime linker automatically searches from these paths first so -that modified libraries are used. +.Xr rtld 1 +automatically searches from this path first when c18n is enabled. .Ss COMPARTMENT TRANSITION TRACING Compartment transitions can be traced with the .Xr ktrace 1 facility. -To generate a trace, set the environment variable LD_C18N_UTRACE_COMPARTMENT +To generate a trace, set the environment variable +.Ev LD_UTRACE_COMPARTMENT and invoke the executable with .Xr ktrace 1 . .Pp @@ -90,8 +85,9 @@ purposes. Turning it on will reduce security. .Ss COMPARTMENT TRANSITION OVERHEAD SIMULATION To simulate the overhead of making a system call during each compartment -transition, set the environment variable LD_C18N_COMPARTMENT_OVERHEAD and invoke -the executable. +transition, set the environment variable +.Ev LD_COMPARTMENT_OVERHEAD +and invoke the executable. Each compartment transition will then make a .Xr getpid 2 system call. @@ -101,37 +97,34 @@ Compartment transition overhead simulation is only intended for performance analysis purposes. Turning it on will reduce security. .Ss BENCHMARK ABI VARIANT -A variant of the runtime linker that uses the benchmark ABI is provided at -.Pa /libexec/ld-elf64cb-c18n.so.1 . -Environment variables recognized by this variant need to be prefixed with -LD_64CB_C18N_. +The benchmark ABI variant of the runtime linker also supports c18n. +Note that environment variables recognized by this variant need to be prefixed +with LD_64CB_ instead of LD_. .Pp .Sy NOTE: Because the purecap variant uses some of Morello's architectural features that -are unavailable under the benchmark ABI, the benchmark ABI variant is not a mere -translation of the purecap variant but has a slightly different implementation. -The best effort has been made to ensure that such a divergence does not bias -performance estimates under almost all circumstances. -.Sh LIMITATIONS -This work is of an experimental nature. -The author has tested it on applications such as -.Xr tmux 1 , -but instabilities might occur when running complex pieces of software. -.Pp -Importantly, this prototype -.Em does not -provide complete isolation between compartments. -For example, they are allowed to make arbitrary system calls to obtain -privileges. -.Pp -Below is a list of known limitations and problems. -For more up-to-date information, visit -.Lk https://github.com/CTSRD-CHERI/cheripedia/wiki/Library-based-Compartmentalisation . +are unavailable under the benchmark ABI, the benchmark ABI variant is not a +mere translation of the purecap variant but has a slightly different +implementation. +The best effort has been made to ensure that such a divergence +does not bias performance estimates under almost all circumstances. +.Sh COMPATIBILITY .Bl -bullet .It -Stack unwinding is not expected to work. -This includes C++ exceptions, stack tracing in debuggers, and usage of -.Lb libunwind . +Calling +.Xr vfork 2 +is identical to calling +.Xr fork 2 , +that is, no memory sharing will take place between the parent and child +processes. +.It +Calling +.Xr rfork 2 +with flags +.Dv RFMEM +or +.Dv RFSIGSHARE +will return -1. .It .Xr sigaltstack 2 does not work as expected. @@ -143,5 +136,15 @@ stack-overflow exceptions. and related functions do not work as expected. This impacts certain threading and coroutine libraries. .El +.Sh SECURITY +This work is of an experimental nature. +It +.Em does not +provide complete isolation between compartments. +For example, they are allowed to make arbitrary system calls to obtain +privileges and access other compartments' thread local data even when said data +has static linkage. +Calling function pointers in other compartments may also unexpectedly leak +capabilities. .Sh AUTHORS .An Dapeng Gao Aq Mt dapeng.gao@cl.cam.ac.uk