1# LibCurl Sandbox 2 3This library is a sandboxed version of curl's C API, 4[libcurl](https://curl.haxx.se/libcurl/c/), implemented using Sandboxed API. 5 6## Setup 7 8The repository can be cloned using: `git clone --recursive <URL to this repo>` 9The `--recursive` flag ensures that submodules are also cloned. 10 11Alternatively, if the repository has already been cloned but the submodules have 12not, these can be cloned using: `git submodule update --init --recursive` 13 14The full list of Sandboxed API dependencies can be found on 15[Sandboxed API Getting Started page](https://developers.google.com/code-sandboxing/sandboxed-api/getting-started). 16 17The following commands, used from the current `curl/` directory, build the 18library: 19 20```bash 21mkdir -p build && cd build 22cmake .. -G Ninja -D SAPI_ROOT=<path to sandboxed-api> 23cmake --build . 24``` 25 26## Implementation details 27 28All of libcurl's methods are supported by the library. However, a few of these 29have different signatures defined in the sandboxed header `custom_curl.h`, which 30wraps and extends libcurl. 31 32This is necessary because Sandboxed API sandboxes most of libcurl correctly, but 33encounters some issues when sandboxing a few methods. The simplest solution is 34wrapping these methods into wrapper methods that accomplish the same tasks but 35can also be sandboxed. 36 37The next sections describe the issues encountered and contain some information 38on the signatures of the wrapper methods solving these issues. 39 40#### Variadic methods 41 42Variadic methods are currently not supported by Sandboxed API. To solve this, 43these methods are defined with an additional explicit parameter in 44`custom_curl.h`. 45 46The methods are: 47 48- `curl_easy_setopt`. Use `curl_easy_setopt_ptr`, `curl_easy_setopt_long` or 49 `curl_easy_setopt_curl_off_t` instead. 50- `curl_easy_getinfo`. Use `curl_easy_getinfo_ptr` instead. 51- `curl_multi_setopt`. Use `curl_multi_setopt_ptr`, `curl_multi_setopt_long` 52 or `curl_multi_setopt_curl_off_t` instead. 53- `curl_share_setopt`. Use `curl_share_setopt_ptr` or `curl_share_setopt_long` 54 instead 55 56#### Methods with incomplete array arguments 57 58Incomplete array arguments are currently not supported by Sandboxed API. To 59solve this, methods taking an incomplete array argument have a wrapper in 60`custom_curl.h`, and take a pointer as the argument. 61 62The methods are: 63 64- `curl_multi_poll`. Use `curl_multi_poll_sapi` instead. 65- `curl_multi_wait`. Use `curl_multi_wait_sapi` instead. 66 67#### Methods with conflicts on the generated header 68 69Some methods create conflicts on the generated header because of redefined 70`#define` directives from files included by the header. To solve this, the 71conflicting types and methods are redefined in `custom_curl.h`. 72 73The types are: 74 75- `time_t`. Use `time_t_sapi` instead. 76- `fd_set`. Use `fd_set_sapi` instead. 77 78The methods are: 79 80- `curl_getdate`. Use `curl_getdate_sapi` instead. 81- `curl_multi_fdset`. Use `curl_multi_fdset_sapi` instead. 82 83#### Function pointers 84 85The functions whose pointers will be passed to the library's methods 86(*callbacks*) can't be implemented in the files making use of the library, but 87must be in other files. These files must be compiled together with the library, 88and this is done by adding their absolute path to the cmake variable 89`CURL_SAPI_CALLBACKS`. 90 91The pointers can then be obtained using an `RPCChannel` object, as shown in 92`example2.cc`. 93 94## Examples 95 96The `examples` directory contains the sandboxed versions of example source codes 97taken from [this page](https://curl.haxx.se/libcurl/c/example.html) on curl's 98website. More information about each example can be found in the examples' 99[README](examples/README.md). 100 101To build these examples when building the library, the cmake variable 102`CURL_SAPI_BUILD_EXAMPLES` must be set to `ON`. This enables Sandboxed API 103examples as well. 104 105## Policy 106 107The `sandbox.h` file contains a policy allowing all is necessary for libcurl to 108perform simple requests. It is used by all the examples, except by example3. 109This example needs some additional policies and files in its namespace (since it 110uses HTTPS), and the file `example3.cc` shows how to easily extend an existing 111policy. 112 113## Testing 114 115The `tests` folder contains some test cases created using Google Test. The class 116`CurlTestUtils` is used to facilitate some tasks that all test cases need, 117including the setup of a mock local server on which test requests are performed. 118 119To build these tests when building the library, the cmake variable 120`CURL_SAPI_BUILD_TESTING` must be set to `ON`. This enables Sandboxed API tests 121as well. 122 123## Callbacks 124 125The `callbacks.h` and `callbacks.cc` files implement all the callbacks used by 126examples and tests. 127