More tainting APIs use

Author: shravanrn

src/chapters/advanced/raw-sandbox-pointers.md

@@ -6,19 +6,7 @@ pointers of the form `char*`. Rather the pointers will be wrapped as
 raw pointer into sandbox memory.
 
 You can do this with the `unverified_safe_pointer_because` API. This converts a
-`tainted` pointer to a raw pointer with only minimal verification.
+`tainted` pointer to a raw pointer with only minimal verification of checking
+that the pointer is within the sandbox boundary.
 
-`unverified_safe_pointer_because` takes two parameters. The first is the number
-of bytes in this pointer that you will be accessing. RLBox needs this to ensure
-that these many bytes of the pointer stay within the sandbox boundary. The
-second is a string, that allows the developer to document why they are doing
-this and why its safe. This string 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..._ . Such documentation may be
-useful to other developers who read your code.
-
-```cpp
-tainted<char*> a = sandbox.malloc_in_sandbox(12);
-char* raw = a.unverified_safe_pointer_because(10, "Demo of a raw pointer");
-```
+The details of how to use this API are provided [here](/chapters/advanced/untainting-apis.md).

src/chapters/advanced/untainting-apis.md

@@ -17,13 +17,13 @@ gives some flexibility to how you want to manage your data. So for example, you
 may be untainting an `int`, but can return an `unsigned int` or an `int*`, or
 `void` etc.
 
-
-## Tainted primitive/fundamental types
-
-C/C++ defines the fundamental types as the types [built-in to the
+3. We will refer to the term fundamental types frequently. C/C++ defines the
+fundamental types as the types [built-in to the
 language](https://en.cppreference.com/w/cpp/language/types.html), such as `int`,
 `float` etc.
 
+## Untainting fundamental types
+
 These types can be untainted with a verifier of the following form
 
 ```cpp
@@ -34,13 +34,46 @@ These types can be untainted with a verifier of the following form
   });
 ```
 
-## Tainted byte buffers
+There maybe some scenarios where the application can handle any possible integer
+from the sandbox, i.e., the `<insert security checks here>` can be left empty.
+
+- An example of this could be when you are calling an sandboxed library function
+that returns an integer 0 on success and a non-zero error code otherwise. From
+the host application perspective, you may do something if the returned value is
+0, and exit otherwise.
+
+
+In this scenario, RLBox provides a shorthand API called
+`unverified_safe_because` which can be used as follows.
+
+```cpp
+  tainted<int> a = ... ; //
+  int a_verified = a.unverified_safe_because("Error code. App is robust to all values of error code");
+```
+
+The `unverified_safe_because` API takes a string argument that allows the
+developer to document why they are doing this and why its safe. This string 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..._ . Such documentation may be useful to other developers who read your
+code. The above is equivalent to:
+
+```cpp
+  tainted<int> a = ... ; //
+  int a_verified = a.copy_and_verify([](int val){
+    // Error code. App is robust to all values of error code
+    return val;
+  });
+```
+
+## Untainting byte buffers
 
 Sometimes the sandbox returns a buffer that you want to untaint. For example,
 you may use a sandboxed XML parse to parse jpeg images. In this example, after
 the sandboxed library parses th image, it will produce a byte buffer with image
 pixels, probably of the type `tainted<char*>` or some other tainted pointer to a
-[fundamental type](https://en.cppreference.com/w/cpp/language/types.html).
+fundamental type.
 
 These types can be untainted with a verifier of the following form
 
@@ -52,8 +85,8 @@ These types can be untainted with a verifier of the following form
   }, size);
 ```
 
-This API copies `size` bytes out of the sandbox and applies the necessary checks
-like ensuring the entire buffer is coming from the sandbox memory.
+This API **copies** `size` bytes out of the sandbox and applies the necessary
+checks like ensuring the entire buffer is coming from the sandbox memory.
 
 In the example of a sandboxed image decoder, the buffer may hold completely
 random data instead of pixels of the image. It is up to you to figure out what
@@ -63,7 +96,40 @@ sensible way to check that decoding has occurred correctly, and rather the rest
 of your program should be robust to showing an incorrect image on the screen. In
 this case, there would be no security check in place.
 
-## Tainted C-strings
+
+## Untainting byte buffers without copying
+
+
+There maybe some scenarios where the application can handle any possible byte
+buffer from the sandbox, i.e., the `<insert security checks here>` can be left
+empty.
+
+- An example of this, would be if the image being displayed to the app in our
+  sandboxed libjpeg example is say an application background and may not really
+  matter.
+
+In this case, we may want to use the byte before **without making a copy**, to
+avoid overheads.
+
+RLBox provides aan API for this called `unverified_safe_pointer_because` which
+can be used as follows.
+
+```cpp
+tainted<char*> a = ...;
+char* raw = a.unverified_safe_pointer_because(10, "Demo of a raw pointer");
+```
+
+`unverified_safe_pointer_because` takes two parameters. The first is the number
+of bytes in this pointer that you will be accessing. RLBox needs this to ensure
+that these many bytes of the pointer stay within the sandbox boundary. The
+second is a string, that allows the developer to document why they are doing
+this and why its safe. This string 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..._ . Such documentation may be
+useful to other developers who read your code.
+
+## Untainting C-strings
 
 Untainting C-strings of type `tainted<char*>` is covered in the
 [tutorial](/chapters/tutorial/noop-sandbox/strings.md).
@@ -84,11 +150,7 @@ terminated, and makes a copy of the string that you can use.
 A useful check in `<insert security checks here>` is also to limit the size of
 the string you want to allow.
 
-## Tainted one-level pointer to a primitive/fundamental type
-
-C/C++ defines the fundamental types as the types [built-in to the
-language](https://en.cppreference.com/w/cpp/language/types.html), such as `int`,
-`float` etc.
+## Untainting one-level pointers to fundamental types
 
 If you have a tainted pointer to a fundamental type such as `tainted<int*>`,
 `tainted<float*>` etc., these types can be untainted with a verifier of the
@@ -110,21 +172,55 @@ limited to tainted pointers to fundamental types.
 
 This API is also limited to one-level pointers, i.e., things like
 `tainted<int*>` and is not allowed for `tainted<int**>`.
-<!-- 
-## Tainted array types
 
-## Tainted struct types
+## Untainting just the "address bits" of a pointer
 
-## Tainted one-level pointer to a struct types
+Your application may sometimes need just the raw bits of a tainted pointer
+without needing to look at the data being pointed to. An example of this would
+be if you want to maintain a hashmap of pointers in the class, but the pointers
+are produced by the sandbox.
 
-## Tainted primitive/fundamental types that don't need verification
+```cpp
+tainted<int*> foo = sandbox.invoke_sandbox_function(...);
+
+std::map<int*, int> my_map;
+my_map[foo] = 3; // RLBox gives a compiler error
+```
 
-`unverified_safe_because`
+For this scenario, RLBox provides an API called `copy_and_verify_address` which
+takes a verifier that accepts a `uintptr_t`. This API can be used as follows.
 
-## Tainted pointers that don't need verification
+```cpp
+tainted<int*> foo = sandbox.invoke_sandbox_function(...);
+
+std::map<int*, int> my_map;
+uintptr_t foo_verified = foo.copy_and_verify_address([&](uintptr_t addr) {
+    // <insert security checks here>
+    return addr;
+});
+my_map[foo_verified] = 3;
+```
 
-`unverified_safe_pointer_because`
+## Untainting C-arrays of fundamental types
 
-## Untainting just the ``address'' bits of a pointer
+Untainting C-arrays of fundamental types like `tainted<int[3]>` is possible
+using `copy_and_verify`. Note, however, that the API expects the verifier to
+accept an argument of `std::array`, so that the data is correctly copied.
+
+These types can be untainted with a verifier of the following form
+
+```cpp
+  tainted<int[3]> a = ... ; //
+  std::array<int, 3> a_verified = a.copy_and_verify([](std::array<int, 3> val){
+    // <insert security checks here>
+    return val;
+  });
+```
+
+<!--
+
+## Tainted struct types
+
+## Tainted one-level pointer to a struct types
 
-`copy_and_verify_address` -->
+-->