sandboxed-api/oss-internship-2020/libuv

LibUV Sandbox

This library is a sandboxed version of LibUV, implemented using Sandboxed API.

Setup

The repository can be cloned using:

git clone --recursive [URL to this repo]

The --recursive flag ensures that submodules are also cloned.

Alternatively, if the repository has already been cloned but the submodules have not, these can be cloned using:

git submodule update --init --recursive

The full list of Sandboxed API dependencies can be found on Sandboxed API Getting Started page.

The following commands, used from the current libuv/ directory, build the library:

mkdir -p build
cd build
cmake .. -G Ninja -D SAPI_ROOT=[path to sandboxed-api]
cmake --build .

Implementation details

LibUV can't be directly sandboxed by Sandboxed API. Because of the size and complexity of the library, doing so creates some compilation errors and does not create the correct APIs for all methods. The solution for this issue is creating a wrapper library, whose methods (which can be sandboxed properly) internally call the original LibUV's methods.

Using these wrapper methods is extremely simple, the only relevant difference is that they have a sapi_ prefix before their names (e.g. uv_loop_init becomes sapi_uv_loop_init). The only exception is the variadic method uv_loop_configure. This has two wrappers, sapi_uv_loop_configure (with no additional parameters) and sapi_uv_loop_configure_int (with an additional int parameter). Currently, these are the only valid calls to the method in LibUV.

Wrapper generator

The wrapper is generated automatically by a Python script that is called by CMake at build time. This script can be found in the generator folder.

Function pointers

The functions whose pointers will be passed to the library's methods (callbacks) can't be implemented in the files making use of the library, but must be in other files. These files must be compiled together with the library, and this is done by adding their absolute path to the CMake variable UV_SAPI_CALLBACKS.

The pointers can then be obtained using an RPCChannel object, as shown in the example idle-basic.cc.

Examples

The examples directory contains the sandboxed versions of example source codes taken from from LibUV's User Guide. More information about each example can be found in the examples' README.

To build these examples when building the library, the CMake variable UV_SAPI_ENABLE_EXAMPLES must be set to ON. This enables Sandboxed API examples as well.

Testing

The tests folder contains some test cases created using Google Test.

To build these tests when building the library, the CMake variable UV_SAPI_ENABLE_TESTS must be set to ON. This enables Sandboxed API tests as well.

Policies

Each example and test has an ad-hoc policy implemented on its own file. These policies can be used as references for pieces of code that perform similar operations. For example, the helloworld.cc example has a policy that only allows the strictly necessary syscalls for running a loop.

Callbacks

The callbacks.h and callbacks.cc files in the callbacks folder implement all the callbacks used by examples and tests.

Performance

A LibUV program looks like this:

• Setup the loop
• Run the loop
• Close the loop

And the second step (running the loop) is the only performance critical part, because this is were actual I/0 and events handling happens. But since this only involves a single call (to sapi_uv_run), the overhead from Sandboxed API is constant with respect to the number of handles and requests. In other words, after Sandboxed API has called the uv_run method on the sandboxed process, whatever happens there is the same as what would have happened in a regular process running LibUV with no sandbox.

This means that, because of LibUV's nature, Sandboxed API has a totally negligible impact on performance. However, there is and overhead caused by seccomp-bpf for each syscall.