From 602a97304de9789cb838e8dbd261b7bacd0bc23c Mon Sep 17 00:00:00 2001 From: wrv Date: Fri, 29 Sep 2023 15:46:43 -0500 Subject: [PATCH 1/3] Fix typos --- src/chapters/api.md | 10 +++++----- src/chapters/api/sandbox.md | 2 +- src/chapters/api/stdlib.md | 2 +- src/chapters/appendix.md | 4 ++-- src/chapters/noop-sandbox.md | 12 ++++++------ src/chapters/rlbox-install.md | 6 +++--- src/chapters/wasm-sandbox.md | 8 ++++---- src/coreapi-draft.md | 2 +- src/overview.md | 18 +++++++++--------- src/tutorial.md | 8 ++++---- 10 files changed, 36 insertions(+), 36 deletions(-) diff --git a/src/chapters/api.md b/src/chapters/api.md index 35f5082..b73af88 100644 --- a/src/chapters/api.md +++ b/src/chapters/api.md @@ -97,7 +97,7 @@ application from using tainted values unsafely. .. doxygenclass:: rlbox::tainted RLBox has several kinds of tainted values, beyond `tainted `. -Thse, however, are slightly less pervasive in the surface API. +These, however, are slightly less pervasive in the surface API. .. _tainted_volatile: .. doxygenclass:: rlbox::tainted_volatile @@ -166,10 +166,10 @@ These functions are also available for `callback ` Operating on tainted values ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Unwrapping tainted values requires care -- getting a verifier wrong could lead +Unwrapping tainted values requires care - getting a verifier wrong could lead to a security vulnerability. It's also not cheap: we need to copy data to the application memory to ensure that the sandboxed code cannot modify the data -we're tyring to verify. Lucikly, it's not always necessary to copy and verify: +we're trying to verify. Luckily, it's not always necessary to copy and verify: sometimes we can compute on tainted values directly. To this end, RLBox defines different kinds of operators on tainted values, which produce tainted values. This allows you to perform some computations on tainted values, pass the values @@ -203,7 +203,7 @@ unwrap the result: * Operators ``==``, ``!=`` on tainted pointers is allowed if the rhs is ``nullptr_t`` and return unwrapped ``bool``. -* Operator ``!`` on tainted pointers retruns an unwrapped ``bool``. +* Operator ``!`` on tainted pointers returns an unwrapped ``bool``. * Operators ``==``, ``!=``, ``!`` on non-pointer tainted values return a ``tainted`` @@ -214,7 +214,7 @@ unwrap the result: * Operators ``&&`` and ``||`` on booleans are only permitted when arguments are variables (not expressions). This is because C++ does not permit safe overloading of && and || operations with expression arguments as this affects - the short circuiting behaviour of these operations. + the short circuiting behavior of these operations. Application-sandbox shared memory --------------------------------- diff --git a/src/chapters/api/sandbox.md b/src/chapters/api/sandbox.md index ff750ba..70acbbd 100644 --- a/src/chapters/api/sandbox.md +++ b/src/chapters/api/sandbox.md @@ -1 +1 @@ -# Creating, managing, and destroying sandboxe +# Creating, managing, and destroying sandboxes diff --git a/src/chapters/api/stdlib.md b/src/chapters/api/stdlib.md index 81b422e..8b2a63e 100644 --- a/src/chapters/api/stdlib.md +++ b/src/chapters/api/stdlib.md @@ -1,7 +1,7 @@ # Standard library RLBox provides several helper functions to application for handling tainted data -(memory influenced by or located in sandoxed regions) similar to the C/C++ +(memory influenced by or located in sandboxed regions) similar to the C/C++ standard library. We list a few of these below; they operate similar to the standard library equivalents, but they accept tainted data. diff --git a/src/chapters/appendix.md b/src/chapters/appendix.md index aea4408..1ae7e64 100644 --- a/src/chapters/appendix.md +++ b/src/chapters/appendix.md @@ -1,6 +1,6 @@ # Additional material -* The best example of how to user RLBox is to see its use in Firefox. The +* The best example of how to use RLBox is to see its use in Firefox. The [Firefox code search](https://searchfox.org/mozilla-central/search?q=create_sandbox&path=) is a great way to do this. @@ -18,7 +18,7 @@ * The [RLBox test suite](https://github.com/PLSysSec/rlbox_sandboxing_api/tree/master/code/tests) itself has a number of examples. -* Finally, the original academic paper explaning the RLBox and its use in +* Finally, the original academic paper explaining RLBox and its use in Firefox [RLBoxPaper](https://www.usenix.org/conference/usenixsecurity20/presentation/narayan) at the USENIX Security 2020 and the accompanying [video diff --git a/src/chapters/noop-sandbox.md b/src/chapters/noop-sandbox.md index c559d94..2a96c73 100644 --- a/src/chapters/noop-sandbox.md +++ b/src/chapters/noop-sandbox.md @@ -57,7 +57,7 @@ typically generic in the sandbox type (e.g., `rlbox::tainted`); macros like `RLBOX_DEFINE_BASE_TYPES_FOR` define simpler types for us (e.g., we can use `tainted_mylib`). In this simple example we only use the noop sandbox; we walk through how you modify this code to use Wasm [in -the next chaper](/chapters/wasm-sandbox.md). +the next chapter](/chapters/wasm-sandbox.md). ### Creating sandboxes and calling sandboxed functions @@ -132,7 +132,7 @@ it.[^note-1] > (2) accessing `helloSize` bytes off the pointer would stay within the sandbox > boundary. -It's worth mentionig that the string `"writing to region"` does not have any +It's worth mentioning that the string `"writing to region"` does not have any special meaning in the code. Rather the RLBox API asks you to provide a free-form string that acts as documentation. Essentially you are providing a string that says _it is safe to remove the tainting from this type because..._ @@ -172,12 +172,12 @@ string we need to verify it. To do this, we use the string verification function }); ``` -This verifier moves the string is not null and if it's length is less than 1KB. +This verifier moves the string if it is not null and if its length is less than 1KB. In the callback we simply print this string. -Let's now continue back in `main`. To `call_cb` with the callback with first -need to register the callback -- otherwise RLBox will disallow the -library-application call -- and pass the callback to the `call_cb` function: +Let's now continue back in `main`. To `call_cb` with the callback we first +need to register the callback - otherwise RLBox will disallow the +library-application call - and pass the callback to the `call_cb` function: ```cpp {{#include examples/noop-hello-example/main.cpp:call_cb}} diff --git a/src/chapters/rlbox-install.md b/src/chapters/rlbox-install.md index 2c610de..039fd50 100644 --- a/src/chapters/rlbox-install.md +++ b/src/chapters/rlbox-install.md @@ -1,6 +1,6 @@ # Setting up your RLBox environment. -RLBox current spans two repositories. One that contains just the RLBox C++ framework +RLBox currently spans two repositories. One that contains just the RLBox C++ framework which you can grab with: ```bash @@ -9,7 +9,7 @@ git clone git@github.com:PLSysSec/rlbox.git The other, which contains the RLBox plugin for Wasm files compiled with the `wasm2c` compiler (which converts your C library to an isolated and sandboxed -version) can be grabbed with: +version), can be grabbed with: ```bash git clone https://github.com/PLSysSec/rlbox_wasm2c_sandbox @@ -20,7 +20,7 @@ and pulls down a copy of the wasi-sdk, the wasm2c compiler, and the rlbox framework as part of its build process, providing a single location for all our tools, which is handy for example purposes and getting started. -Many folks perfer to do a system wide or per-user install of the wasi-sdk and +Many folks prefer to do a system wide or per-user install of the wasi-sdk and RLBox. The latest releases of the wasi-sdk (which will given you everything you need to compile your library from C to wasm) be found [here](https://github.com/WebAssembly/wasi-sdk/releases). diff --git a/src/chapters/wasm-sandbox.md b/src/chapters/wasm-sandbox.md index da95920..f808bdd 100644 --- a/src/chapters/wasm-sandbox.md +++ b/src/chapters/wasm-sandbox.md @@ -6,11 +6,11 @@ isolation. To finish sandboxing your library, we will need to. 1. Update the application `main.cpp` to use the `wasm2c` sandbox backend instead of `noop`. -2. Compile our library e.g. `mylib.c` to wasm i.e. `mylib.wasm` -- adding +2. Compile our library e.g. `mylib.c` to wasm i.e. `mylib.wasm` - adding isolation to your library. 3. Compile that resulting `mylib.wasm` file to C (`mylib.wasm.c` and `mylib.wasm.h`) - with the `wasm2c` compiler -- allow it to be compiled and linked with our + with the `wasm2c` compiler - allow it to be compiled and linked with our application. 4. Compile and link the sandboxed library and our application. @@ -58,7 +58,7 @@ To start we can see our Makefile begins with RLBOX_ROOT: {{#include examples/wasm-hello-example/Makefile:0}} ``` -Which just specificies where our `rlbox_wasm2c_sandbox` repo's root directory +Which just specifies where our `rlbox_wasm2c_sandbox` repo's root directory lives. This repo contains all the tools we will need build our sandboxed library e.g. `wasm2c`, wasi-sdk (which CMake downloads), RLBox, etc. @@ -114,6 +114,6 @@ system and network. ``` - + diff --git a/src/coreapi-draft.md b/src/coreapi-draft.md index 0661df3..32e0565 100644 --- a/src/coreapi-draft.md +++ b/src/coreapi-draft.md @@ -1,6 +1,6 @@ - [Core RLBox API]() - - [Creating, managing, and destroying sandboxe]() + - [Creating, managing, and destroying sandboxes]() - [Calling sandboxed functions]() - [Creating, manipulating, and verifying tainted values]() - [Allocating and managing sandbox memory]() diff --git a/src/overview.md b/src/overview.md index 2c32f67..3c1e2c6 100644 --- a/src/overview.md +++ b/src/overview.md @@ -22,19 +22,19 @@ example of applying RLBox to a simple application. ### Why RLBox Work on RLBox began several years ago while attempting to add fine grain -isolation third party libraries in the Firefox renderer. Initially we attempted -this process without any support from a framwork like RLBox, instead attempting -to manually deal with all the details sandboxing such as sanitizing untrusted +isolation to third party libraries in the Firefox renderer. Initially we attempted +this process without any support from a framework like RLBox, instead attempting +to manually deal with all the details of sandboxing such as sanitizing untrusted inputs, and reconciling ABI differences between the sandbox and host application. -This went poorly, it was tedious, error prone, and did nothing to abstract the +This went poorly; it was tedious, error prone, and did nothing to abstract the details of the underlying sandbox from the developer. We had basically no hope that this would result in code that was maintainable, or that normal Mozilla developers who were unfamiliar with the gory details of our system would be able -to sandbox new library, let alone maintain existing ones. +to sandbox a new library, let alone maintain existing ones. -So we scrapped this manual approach and build RLBox[^RLBoxPaper]. +So we scrapped this manual approach and built RLBox[^RLBoxPaper]. RLBox automates many of the low level details of sandboxing and allows you, as a security engineer or application developer, to instead focus just on what you @@ -87,13 +87,13 @@ structures, however, must (again) be passed by *sandbox-reference*, i.e., via a reference/pointer to sandbox memory. To ensure that application code doesn't unsafely use values that originate in -the sandbox -- and may thus be under the control of an attacker -- RLBox +the sandbox - and may thus be under the control of an attacker - RLBox considers all such values as untrusted and [taints](https://shravanrn.com/oldrlboxdocs/#tainted-values) them. Tainted values are essentially opaque values (though RLBox does provide some basic operators on tainted values). To use a tainted value, you must unwrap it by -(typically) copying the value into application memory -- and thus out of the -reach of the attacker -- and *verifying* it. Indeed, RLBox forces application +(typically) copying the value into application memory - and thus out of the +reach of the attacker - and *verifying* it. Indeed, RLBox forces application code to perform the copy and verification in sync using verification functions (see [this](https://shravanrn.com/oldrlboxdocs/#id15)). diff --git a/src/tutorial.md b/src/tutorial.md index da7e409..c8c6967 100644 --- a/src/tutorial.md +++ b/src/tutorial.md @@ -4,17 +4,17 @@ In this tutorial we will walk you through the steps of adding sandboxing to a very simple application and library. However, all the basic step generalize to more complex examples. -We have broken the tutorial into two parts, in the [first +We have broken the tutorial into two parts. In the [first part](./chapters/noop-sandbox.md), we will look at how to use RLBox to retrofit -sandboxing in an existing application, taking all the steps to that control flow +sandboxing in an existing application, taking all the steps to ensure that control flow and data flow across the application library boundary are secure. In the [second part](/chapters/wasm-sandbox.md), we will look at how to -re-build our library with wasm and link this into our applciation, so our +re-build our library with wasm and link this into our application, so our library is isolated. Once we complete these two steps, our library is now securely isolated -from our application +from our application. If you would like to download and run the examples yourself, follow the instructions [here](/chapters/tutorial-install.md). From 7f913cfc7507c441ed29052e0b9515b1c13f1b23 Mon Sep 17 00:00:00 2001 From: wrv Date: Fri, 29 Sep 2023 15:49:31 -0500 Subject: [PATCH 2/3] Consistent git clone --- src/chapters/noop-sandbox.md | 2 +- src/chapters/rlbox-install.md | 4 ++-- src/chapters/tutorial-install.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/chapters/noop-sandbox.md b/src/chapters/noop-sandbox.md index 2a96c73..843156a 100644 --- a/src/chapters/noop-sandbox.md +++ b/src/chapters/noop-sandbox.md @@ -191,7 +191,7 @@ chapter. Clone this books' repository: ```bash -git clone git@github.com:PLSysSec/rlbox-book.git +git clone https://github.com/PLSysSec/rlbox-book cd rlbox-book/src/chapters/examples/noop-hello-example ``` diff --git a/src/chapters/rlbox-install.md b/src/chapters/rlbox-install.md index 039fd50..b69a676 100644 --- a/src/chapters/rlbox-install.md +++ b/src/chapters/rlbox-install.md @@ -4,7 +4,7 @@ RLBox currently spans two repositories. One that contains just the RLBox C++ fra which you can grab with: ```bash -git clone git@github.com:PLSysSec/rlbox.git +git clone https://github.com/PLSysSec/rlbox ``` The other, which contains the RLBox plugin for Wasm files compiled with the @@ -32,7 +32,7 @@ need to compile your library from C to wasm) be found To quickly install the RLBox repo, you can run the following: ```bash -git clone git@github.com:PLSysSec/rlbox.git +git clone https://github.com/PLSysSec/rlbox cd rlbox cmake -S . -B ./build -DCMAKE_BUILD_TYPE=Release cmake --build ./build --config Release --parallel diff --git a/src/chapters/tutorial-install.md b/src/chapters/tutorial-install.md index 46d980a..06f7f28 100644 --- a/src/chapters/tutorial-install.md +++ b/src/chapters/tutorial-install.md @@ -18,7 +18,7 @@ Next, clone the repo for this book, which contains our example code, and copy it to its own directory, and build the example code. ```bash -git clone git@github.com:PLSysSec/rlbox-book.git +git clone https://github.com/PLSysSec/rlbox-book mkdir myapp cp -r rlbox-book/src/chapters/examples/noop-hello-example/* myapp cd myapp From 117400a618b3a394a65ecbe4884a16c39dcf435e Mon Sep 17 00:00:00 2001 From: wrv Date: Sat, 30 Sep 2023 08:49:09 -0500 Subject: [PATCH 3/3] Update WASM example --- .../examples/wasm-hello-example/Makefile | 9 ++-- .../examples/wasm-hello-example/main-diff.txt | 41 ++++++++++--------- .../examples/wasm-hello-example/main.cpp | 3 ++ src/chapters/wasm-sandbox.md | 18 ++++---- 4 files changed, 41 insertions(+), 30 deletions(-) diff --git a/src/chapters/examples/wasm-hello-example/Makefile b/src/chapters/examples/wasm-hello-example/Makefile index ab509f6..980fbf4 100644 --- a/src/chapters/examples/wasm-hello-example/Makefile +++ b/src/chapters/examples/wasm-hello-example/Makefile @@ -9,14 +9,17 @@ WASI_SDK_ROOT=$(RLBOX_ROOT)/build/_deps/wasiclang-src/ #location of our wasi/wasm runtime WASM2C_RUNTIME_PATH=$(RLBOX_ROOT)/build/_deps/mod_wasm2c-src/wasm2c -WASI_RUNTIME_FILES=$(addprefix $(WASM2C_RUNTIME_PATH), /wasm-rt-impl.c /wasm-rt-os-win.c /wasm-rt-os-unix.c /wasm-rt-wasi.c) +WASI_RUNTIME_FILES=$(addprefix $(WASM2C_RUNTIME_PATH), /wasm-rt-impl.c) + +#Some more wasi/wasm runtime files +WASM2C_RUNTIME_FILES=$(addprefix $(RLBOX_ROOT)/src, /wasm2c_rt_minwasi.c /wasm2c_rt_mem.c) WASI_CLANG=$(WASI_SDK_ROOT)/bin/clang WASI_SYSROOT=$(WASI_SDK_ROOT)/share/wasi-sysroot WASM2C=$(RLBOX_ROOT)/build/_deps/mod_wasm2c-src/bin/wasm2c #CFLAGS for compiling files to place nice with wasm2c -WASM_CFLAGS=-Wl,--export-all -Wl,--no-entry -Wl,--growable-table -Wl,--stack-first -Wl,-z,stack-size=1048576 +WASM_CFLAGS=-Wl,--export-all -Wl,--stack-first -Wl,-z,stack-size=262144 -Wl,--no-entry -Wl,--growable-table -Wl,--import-memory -Wl,--import-table all: mylib.wasm mylib.wasm.c myapp @@ -33,5 +36,5 @@ mylib.wasm.c: mylib.wasm #Step 3: compiling and linking our application with our library myapp: mylib.wasm.c - $(CC) -c $(WASI_RUNTIME_FILES) -I$(RLBOX_INCLUDE) -I$(RLBOX_ROOT)/include -I$(WASM2C_RUNTIME_PATH) mylib.wasm.c + $(CC) -c $(WASI_RUNTIME_FILES) $(WASM2C_RUNTIME_FILES) -I$(RLBOX_INCLUDE) -I$(RLBOX_ROOT)/include -I$(WASM2C_RUNTIME_PATH) mylib.wasm.c $(CXX) -std=c++17 main.cpp -o myapp -I$(RLBOX_INCLUDE) -I$(RLBOX_ROOT)/include -I$(WASM2C_RUNTIME_PATH) *.o -lpthread diff --git a/src/chapters/examples/wasm-hello-example/main-diff.txt b/src/chapters/examples/wasm-hello-example/main-diff.txt index cedbf28..1ca967f 100644 --- a/src/chapters/examples/wasm-hello-example/main-diff.txt +++ b/src/chapters/examples/wasm-hello-example/main-diff.txt @@ -1,20 +1,23 @@ 1 $diff ../noop-hello-example/main.cpp main.cpp -2 3a4 -3 > -4 5c6 -5 < #define RLBOX_USE_STATIC_CALLS() rlbox_noop_sandbox_lookup_symbol -6 --- -7 > #define RLBOX_USE_STATIC_CALLS() rlbox_wasm2c_sandbox_lookup_symbol -8 9,11d9 -9 < #include -10 < #include -11 < -12 12a11,14 -13 > #include "mylib.wasm.h" -14 > #include "rlbox.hpp" -15 > #include "rlbox_wasm2c_sandbox.hpp" -16 > -17 18c20 -18 < RLBOX_DEFINE_BASE_TYPES_FOR(mylib, noop); -19 --- -20 > RLBOX_DEFINE_BASE_TYPES_FOR(mylib, wasm2c); +2 3a4,7 +3 > +4 > // Provide the sandbox a name +5 > #define RLBOX_WASM2C_MODULE_NAME mylib +6 > +7 5c9 +8 < #define RLBOX_USE_STATIC_CALLS() rlbox_noop_sandbox_lookup_symbol +9 --- +10 > #define RLBOX_USE_STATIC_CALLS() rlbox_wasm2c_sandbox_lookup_symbol +11 9,11d12 +12 < #include +13 < #include +14 < +15 12a14,17 +16 > #include "mylib.wasm.h" +17 > #include "rlbox.hpp" +18 > #include "rlbox_wasm2c_sandbox.hpp" +19 > +20 18c23 +21 < RLBOX_DEFINE_BASE_TYPES_FOR(mylib, noop); +22 --- +23 > RLBOX_DEFINE_BASE_TYPES_FOR(mylib, wasm2c); \ No newline at end of file diff --git a/src/chapters/examples/wasm-hello-example/main.cpp b/src/chapters/examples/wasm-hello-example/main.cpp index 054f216..8d8abd4 100644 --- a/src/chapters/examples/wasm-hello-example/main.cpp +++ b/src/chapters/examples/wasm-hello-example/main.cpp @@ -5,6 +5,9 @@ // All calls into the sandbox are resolved statically. #define RLBOX_USE_STATIC_CALLS() rlbox_wasm2c_sandbox_lookup_symbol +// Provide the wasm2c module a name +#define RLBOX_WASM2C_MODULE_NAME mylib + #include #include #include "mylib.h" diff --git a/src/chapters/wasm-sandbox.md b/src/chapters/wasm-sandbox.md index f808bdd..563dc5b 100644 --- a/src/chapters/wasm-sandbox.md +++ b/src/chapters/wasm-sandbox.md @@ -27,15 +27,17 @@ sandbox backend) and in our current example (using the `wasm2c` backend). ``` As you can see, most of what has changed is renaming a few key instances of -`noop` to `wasm2c`, most notably to change our backend type on line 10. +`noop` to `wasm2c`, most notably to change the backend type that we include. The only other changes are ```#include "mylib.wasm.h"``` on line 13, which -brings in the new header for our sandboxed library generated by `wasm2c`. +brings in the new header for our sandboxed library generated by `wasm2c`, and +```#define RLBOX_WASM2C_MODULE_NAME mylib``` which will provide a unique name +for this sandbox. These are essentially all the changes you will need to make to your application to switch wasm backends. -The changes to how rlbox is included on lines 14 and 15 are just an artifact of +The changes to how rlbox is included on lines 17 and 18 are just an artifact of differences how our examples are built. @@ -65,7 +67,7 @@ e.g. `wasm2c`, wasi-sdk (which CMake downloads), RLBox, etc. ### Step 1: Compiling our library to Wasm ```Makefile -{{#include examples/wasm-hello-example/Makefile:27:28}} +{{#include examples/wasm-hello-example/Makefile:30:31}} ``` Here we are building our library to wasm. Typically you will just want to update @@ -79,8 +81,8 @@ our output plays nicely with the rest of the toolchain. -Notice the `dummy_main.c` file to keep wasi-clang happy, you can find a copy -`rlbox_wasm2c_sandbox/_src/wasm2c_sandbox_wrapper.c` +Notice the `dummy_main.c` file to keep wasi-clang happy. You can +find a copy of this file at `rlbox_wasm2c_sandbox/c_src/wasm2c_sandbox_wrapper.c`. wasi-libc at the moment has a variety of limitations such as lack of pthread support (though this should be fixed soon!). Anything platform specific such as @@ -91,7 +93,7 @@ platform specific code e.g. inline assembly will also fail at this stage. ### Step 2: Using `wasm2c` to generate our sandboxed library ```Makefile -{{#include examples/wasm-hello-example/Makefile:31:32}} +{{#include examples/wasm-hello-example/Makefile:34:35}} ``` @@ -110,7 +112,7 @@ system and network. ### Step 3: Compiling and linking our application with our library ```Makefile -{{#include examples/wasm-hello-example/Makefile:35:37}} +{{#include examples/wasm-hello-example/Makefile:38:40}} ```