From 4c9224653fd121debe9f08848e34270df09cacb4 Mon Sep 17 00:00:00 2001 From: David Anekstein <agile.tree8208@fastmail.com> Date: Mon, 21 Aug 2023 13:50:49 -0400 Subject: [PATCH] Documentation (#263) * documentation: add patchelf dependency to README.md * documentation: fix 404 when linking to `INIT_COMPARTMENT` macro * documentation: update usage of `IA2_COMPARTMENT`, which replaced `INIT_COMPARTMENT` * fix documentation for assigning a protection key Co-authored-by: Stephen Crane <sjc@immunant.com> --------- Co-authored-by: Stephen Crane <sjc@immunant.com> --- README.md | 15 +++++++++++---- docs/usage.md | 6 +++--- 2 files changed, 14 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index ceafb7c2d0..8054b1abbc 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ Ubuntu 20.04 is used for testing. Other Linux distributions may or may not work. ``` sudo apt install -y libusb-1.0-0-dev libclang-dev llvm-dev \ ninja-build zlib1g-dev python3-pip cmake \ - libavformat-dev libavutil-dev pcregrep + libavformat-dev libavutil-dev pcregrep patchelf pip install lit rustup install nightly ``` @@ -41,9 +41,16 @@ ninja check-ia2 ### Defining compartments -First invoke the [`INIT_RUNTIME`](https://github.com/immunant/IA2-Phase2/blob/main/include/ia2.h) macro once in any binary or shared library to define the number of protection keys that need to be allocated. The argument passed to `INIT_RUNTIME` must be a number between 1 and 15. Then the [`INIT_COMPARTMENT`](https://github.com/immunant/IA2-Phase2/blob/main/include/ia2.h) macro is used to define trusted compartments at the shared object level. This can be the main executable ELF or any dynamically-linked shared libraries. Memory belonging to a trusted compartment is assigned one of the [15 protection keys](https://man7.org/linux/man-pages/man7/pkeys.7.html) and can only be accessed by the shared object itself. Objects that don't explicitly define a compartment are treated as untrusted by default. +First invoke the [`INIT_RUNTIME`](https://github.com/immunant/IA2-Phase2/blob/5cdb743d3a42e8df8e4d8cf61fb3551656001c73/libia2/include/ia2.h#L204) macro once in any binary or shared library to define the number of protection keys that need to be allocated. The argument passed to `INIT_RUNTIME` must be a number between 1 and 15. Then the [`IA2_COMPARTMENT`](https://github.com/immunant/IA2-Phase2/blob/4a3a0c8d2a2b1881e0e41c89db070db3da187f9e/libia2/include/ia2_compartment_init.inc#L3) `#define` is used to define trusted compartments at the shared object level. This can be the main executable ELF or any dynamically-linked shared libraries. Memory belonging to a trusted compartment is assigned one of the [15 protection keys](https://man7.org/linux/man-pages/man7/pkeys.7.html) and can only be accessed by the shared object itself. Objects that don't explicitly define a compartment are treated as untrusted by default. -To assign a protection key to a trusted compartment insert `INIT_COMPARTMENT(n)` with an argument between 1-15 specifying the index of the protection key. This argument must differ from the other trusted compartments. Trusted compartments must also be aligned and padded properly by using the `padding.ld` script in `libia2/`. In CMake this is done automatically for executables built with `define_test` while libraries built with `define_shared_lib` must add `LINK_OPTS "-Wl,-T${libia2_BINARY_DIR}/padding.ld"`. To use in manual builds just include `-Wl,-T/path/to/padding.ld` in the final compilation step. Manual builds also require disabling lazy binding with `-Wl,-z,now`. +To assign a protection key to a trusted compartment, insert `#define IA2_COMPARTMENT n` with an argument between 1-15 specifying the index of the protection key, and include `ia2_compartment_init.inc`: + +```c +#define IA2_COMPARTMENT 1 +#include <ia2_compartment_init.inc> +``` + +This argument must differ from the other trusted compartments. Trusted compartments must also be aligned and padded properly by using the `padding.ld` script in `libia2/`. In CMake this is done automatically for executables built with `define_test` while libraries built with `define_shared_lib` must add `LINK_OPTS "-Wl,-T${libia2_BINARY_DIR}/padding.ld"`. To use in manual builds just include `-Wl,-T/path/to/padding.ld` in the final compilation step. Manual builds also require disabling lazy binding with `-Wl,-z,now`. ### Wrapping calls @@ -67,7 +74,7 @@ We provide a CMake rule to wrap a library or the main executable. This rule buil +target_link_libraries(my_prog PRIVATE my_wrapper_target) ``` -Wrapped libraries are treated as untrusted by default. If the library being wrapped defined a trusted compartment, `COMPARTMENT_PKEY n` must be specified in define_ia2_wrapper. Here `n` is the argument used in `INIT_COMPARTMENT` to define the compartment. If the caller is an untrusted compartment, set `CALLER_PKEY UNTRUSTED`. To create a wrapper for the main binary (i.e. if shared libraries call it directly) the `WRAP_MAIN` option must be specified. +Wrapped libraries are treated as untrusted by default. If the library being wrapped defined a trusted compartment, `COMPARTMENT_PKEY n` must be specified in define_ia2_wrapper. Here `n` is the argument used in `IA2_COMPARTMENT` to define the compartment. If the caller is an untrusted compartment, set `CALLER_PKEY UNTRUSTED`. To create a wrapper for the main binary (i.e. if shared libraries call it directly) the `WRAP_MAIN` option must be specified. #### Manual usage diff --git a/docs/usage.md b/docs/usage.md index 7b4b83c5fd..da5373d68e 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -79,14 +79,14 @@ gcc -shared libbar_shim.c -Wl,-z,now -Wl,--version-script,libbar_shim.c.syms \ ``` We now modify the main binary's source to initialize our runtime using -`INIT_RUNTIME` and assign it a protection key with `INIT_COMPARTMENT`. +`INIT_RUNTIME` and assign it a protection key with `IA2_COMPARTMENT`. `INIT_RUNTIME` must be invoked once in the main binary. To assign a protection -key to another shared object, only `INIT_COMPARTMENT` must be added to one of +key to another shared object, only `IA2_COMPARTMENT` must be added to one of the object's source files. ``` // main.c -// This header defines INIT_RUNTIME and INIT_COMPARTMENT +// This header defines INIT_RUNTIME and IA2_COMPARTMENT #include <ia2.h> // Initialize the runtime and allocate 1 protection key.