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