diff --git a/src/features/c18n.md b/src/features/c18n.md index d380508..1a63fe4 100644 --- a/src/features/c18n.md +++ b/src/features/c18n.md @@ -24,8 +24,8 @@ CHERI-enabled software compartmentalization models: CheriBSD's library compartmentalization feature (c18n) executes each dynamic library within a compartmentalization-enabled process in its own protection domain. -The non-default c18n-enabled run-time linker grants libraries capabilities -only to resources (global variables, APIs) declared in their ELF linkage. +When c18n is enabled, the run-time linker grants libraries capabilities only +to resources (global variables, APIs) declared in their ELF linkage. Function calls that cross domain boundaries are interposed on by domain-crossing shims implemented by the run-time linker. @@ -57,39 +57,62 @@ page](https://man.cheribsd.org/cgi-bin/man.cgi/releng-24.05/c18n): man c18n ``` -## Compiling applications for library compartmentalization +## Enabling library compartmentalization system-wide -To compile a main application to use library compartmentalization, add the -following flags to compilation of the program binary: +Compartmentalization can be enabled for all eligible new processes with +`sysctl`: ``` --Wl,--dynamic-linker=/libexec/ld-elf-c18n.so.1 +sysctl security.cheri.lib_based_c18n_default=1 ``` -For example, compile `helloworld.c` using: +## Enabling library compartmentalization temporarily for a particular binary +To run a particular binary with library compartmentalization enabled just for +this run, use `proccontrol`: + +`proccontrol -m cheric18n -s enable ./helloworld` + +## Enabling library compartmentalization permanently for a particular binary + +To enable library compartmentalization permanently for a particular binary, +run the following command to set a flag in the binary: + +``` +elfctl -e +cheric18n ./helloworld ``` -cc -Wall -g -o helloworld helloworld.c -Wl,--dynamic-linker=/libexec/ld-elf-c18n.so.1 + +This can be reversed by replacing `+cheric18n` with `-cheric18n`. + +You can confirm whether c18n is permanently enabled for a binary by +inspecting it using the `elfctl` command: + +``` +elfctl ./helloworld ``` -You can confirm whether a binary uses the c18n run-time linker by inspecting -it using the `file` command: +The output will contain two lines like the following indicating whether c18n is +enabled or disabled. ``` -file helloworld +cheric18n 'Force Enable CHERI library-based compartmentalisation' is set. +nocheric18n 'Force Disable CHERI library-based compartmentalisation' is unset. ``` +Note that `nocheric18n` permanently _disables_ c18n for the binary even when it +is enabled system-wide. + ## Tracing compartment-boundary crossings The BSD ktrace(1) command is able to trace compartment-boundary crossings. -To enable this feature, set the `LD_C18N_UTRACE_COMPARTMENT` environmental -variable, which will cause the c18n run-time linker to emit records using -the utrace(2) system call. +To enable this feature, set the `LD_UTRACE_COMPARTMENT` environmental +variable, which will cause the run-time linker to emit records using the +utrace(2) system call. Run the program under ktrace with the `-tu` argument to capture only those records (and not a full system-call trace): ``` -env LD_C18N_UTRACE_COMPARTMENT=1 ktrace -tu ./helloworld +env LD_UTRACE_COMPARTMENT=1 ktrace -tu ./helloworld ``` The resulting `ktrace.out` file can be viewed using the kdump(1) command: