mirror of
https://github.com/google/sandboxed-api.git
synced 2024-03-22 13:11:30 +08:00
63 lines
3.3 KiB
Markdown
63 lines
3.3 KiB
Markdown
|
# LibUV Sandbox
|
||
|
|
|
||
|
|
This library is a sandboxed version of [LibUV](https://libuv.org/), 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](https://developers.google.com/sandboxed-api/docs/getting-started).
|
||
|
|
|
||
|
|
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](https://docs.libuv.org/en/v1.x/guide.html). More information about each example can be found in the examples' [README](examples/README.md).
|
||
|
|
|
||
|
|
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.
|