Add more examples of temporal safety (#279)

Following the recent thread with Murali on sub objects I though it would
be useful to add some more use cases to the temporal_safety example to
illustrate sub objects and also claims

examples/04.temporal_safety/README.md

@@ -1,12 +1,14 @@
 Temporal safety example
 =======================
 
-This example shows a trivial use-after-free bug.
-The code simply allocates an object and frees it, printing the value of the pointer both before and after deallocation.
+This example shows an number of use-after-free cases.
+
+The first case simply allocates an object and frees it, printing the value of the pointer both before and after deallocation.
 
 The output from this should be something roughly like this:
 
 ```
+Allocating compartment: -- Simple Case --
 Allocating compartment: Allocated: 0x80004ce0 (v:1 0x80004ce0-0x80004d0a l:0x2a o:0x0 p: G RWcgm- -- ---)
 Allocating compartment: Use after free: 0x80004ce0 (v:0 0x80004ce0-0x80004d0a l:0x2a o:0x0 p: G RWcgm- -- ---)
 ```
@@ -43,3 +45,28 @@ Any of these can be cleared from a copy of the pointer before passing it to othe
 For example, if you remove `W` and `M` permissions from a pointer that you pass as a parameter then you have a guarantee that nothing reachable from the pointer will be mutated.
 Similarly, if you remove `G` and `L` then you have the guarantee that nothing reachable from the pointer will be captured.
 If you remove `G` but not `L` then you have the weaker guarantee that the pointer that you passed will not be captured but pointers reachable from it might be.
+
+The next three use cases show the handling of a sub-object, a capability that references a sub-range of the allocation.
+
+In the first of these the sub-object is passed to free().
+As no claims have been made, free() would take action only if a cap to the entire object were passed in.
+Thus, this call to free() has no effect on the heap or on the pointers held by the client.
+(In particular, unlike many historical implementations of malloc, freeing a sub-object will not erroneously return this sub-object's memory to the free pool.)
+
+In the second use case a claim is made on the sub-object.
+This charges the claimant's quota and ensures that the sub-object (and, indeed, the entire object) remains allocated for the duration of the claim, even when the enclosing allocation is passed to free().
+Thereafter, releasing the claim on the sub-object will cause the object to be freed, invalidating the pointers to the object and sub-object alike.
+
+The third use case shows the difference between a claim and a fast claim.
+Claims are persistent, count against the compartment's quota, and last until they are explicitly released, but they are expensive as they require a cross compartment call to the allocator.
+Fast claims are ephemeral and belong to the thread rather than the compartment.
+Each thread may hold only at most one fast claim (on up to two objects).
+They do not count against a quota, but they only last until the thread makes a cross compartment call or another fast claim.
+In the example the claim on the sub-object is made with a fast claim, but when the enclosing object is now freed the fast claim is dropped (as free() is a cross compartment call) so both the enclosing and sub-objects become invalid.
+_This is a poor use of a fast claim used to illustrate the behaviour; The normal use case is to establish a claim early in the entry to a compartment to prevent an object becoming invalid while the compartment processes it, which may include making its own persistent claim._    
+
+The final use case shows how an object initially allocated in one compartment may be claimed by (and counted against the quota) of a second compartment.
+This allows, for example, a zero-copy data buffer pattern.
+Even when the allocation is freed by (and removed from the quota of) the original compartment, it remains valid, because it is now claimed by the second compartment.
+Note that the quota charge for a claim on an object is slightly larger than the size of the object itself, because a small amount of additional heap is required for the claim headers.
+

examples/04.temporal_safety/allocate.cc

@@ -5,17 +5,143 @@
 #include <debug.hh>
 #include <fail-simulator-on-error.h>
 
+#include "claimant.h"
+
 /// Expose debugging features unconditionally for this compartment.
 using Debug = ConditionalDebug<true, "Allocating compartment">;
 
 /// Thread entry point.
 void __cheri_compartment("allocate") entry()
 {
-	void *x = malloc(42);
-	// Print the allocated value:
-	Debug::log("Allocated: {}", x);
-	free(x);
-	// Print the dangling pointer, note that it is no longer a valid pointer
-	// (v:0)
-	Debug::log("Use after free: {}", x);
+	// Simple case
+	{
+		Debug::log("----- Simple Case -----");
+		void *x = malloc(42);
+		// Print the allocated value:
+		Debug::log("Allocated: {}", x);
+		free(x);
+		// Print the dangling pointer, note that it is no longer a valid pointer
+		// (v:0)
+		Debug::log("Use after free: {}", x);
+	}
+
+	// Sub object
+	{
+		Debug::log("----- Sub object -----");
+		void *x = malloc(100);
+
+		CHERI::Capability y{x};
+		y.address() += 25;
+		y.bounds() = 50;
+		Debug::log("Allocated : {}", x);
+		Debug::log("Sub Object: {}", y);
+		Debug::log("heap quota: {}", heap_quota_remaining(MALLOC_CAPABILITY));
+
+		// Free y - as it's a sub object of x both x & y remain valid
+		free(y);
+		Debug::log("After free of sub object");
+		Debug::log("Allocated : {}", x);
+		Debug::log("Sub Object: {}", y);
+		Debug::log("heap quota: {}", heap_quota_remaining(MALLOC_CAPABILITY));
+
+		// Free x - both x & y become invalid
+		free(x);
+		Debug::log("After free of allocation");
+		Debug::log("Allocated : {}", x);
+		Debug::log("Sub Object: {}", y);
+		Debug::log("heap quota: {}", heap_quota_remaining(MALLOC_CAPABILITY));
+	}
+
+	// Sub object with a claim
+	{
+		Debug::log("----- Sub object with a claim -----");
+		void *x = malloc(100);
+
+		CHERI::Capability y{x};
+		y.address() += 25;
+		y.bounds() = 50;
+		Debug::log("Allocated : {}", x);
+		Debug::log("Sub Object: {}", y);
+		Debug::log("heap quota: {}", heap_quota_remaining(MALLOC_CAPABILITY));
+
+		// Add a claim for y - the quota remaining is reduced
+		heap_claim(MALLOC_CAPABILITY, y);
+		Debug::log("heap quota after claim: {}",
+		           heap_quota_remaining(MALLOC_CAPABILITY));
+
+		// free x.  As we have a claim on y both x and y remain valid
+		free(x);
+		Debug::log("After free of allocation");
+		Debug::log("Allocated : {}", x);
+		Debug::log("Sub Object: {}", y);
+		Debug::log("heap quota: {}", heap_quota_remaining(MALLOC_CAPABILITY));
+
+		// free y - releases the claim and both x & y become invalid
+		free(y);
+		Debug::log("After free of sub object");
+		Debug::log("Allocated : {}", x);
+		Debug::log("Sub Object: {}", y);
+		Debug::log("heap quota: {}", heap_quota_remaining(MALLOC_CAPABILITY));
+	}
+
+	// Sub object with a fast claim
+	{
+		Debug::log("----- Sub object with a fast claim -----");
+		void *x = malloc(100);
+
+		CHERI::Capability y{x};
+		y.address() += 25;
+		y.bounds() = 50;
+		Debug::log("Allocated : {}", x);
+		Debug::log("Sub Object: {}", y);
+		Debug::log("heap quota: {}", heap_quota_remaining(MALLOC_CAPABILITY));
+
+		// Add a fast claim for y
+		Timeout t{10};
+		heap_claim_fast(&t, y);
+
+		// In this freeing x will invalidate both x & y because free
+		// is a cross compartment call, which releases any fast claims.
+		free(x);
+		Debug::log("After free");
+		Debug::log("Allocated : {}", x);
+		Debug::log("Sub Object: {}", y);
+		Debug::log("heap quota: {}", heap_quota_remaining(MALLOC_CAPABILITY));
+	}
+
+	// Using a claim in another compartment.
+	// Note that a claim in the same compartment would also work, but this
+	// shows the more typical use case
+	{
+		Debug::log("----- Claim in another compartment -----");
+		void *x = malloc(10);
+
+		Debug::log("Allocated : {}", x);
+		Debug::log("heap quota: {}", heap_quota_remaining(MALLOC_CAPABILITY));
+
+		// Get the claimant compartment to make a fast claim
+		make_claim(x);
+
+		// free x.  We get out quota back but x remains valid as
+		// the claimant compartment has a claim on it
+		free(x);
+		Debug::log("After free: {}", x);
+		Debug::log("heap quota: {}", heap_quota_remaining(MALLOC_CAPABILITY));
+
+		// Get the claimant compartment to show its claim
+		show_claim();
+
+		// Give the claimant another ptr so it releases the first
+		void *y = malloc(10);
+		make_claim(y);
+		Debug::log("After make claim");
+		Debug::log("x: {}", x);
+		Debug::log("y: {}", y);
+
+		// Get the claimant compartment to show its new claim
+		show_claim();
+
+		// tidy up
+		free(y);
+	}
 }

examples/04.temporal_safety/claimant.cc

@@ -0,0 +1,34 @@
+#include <compartment.h>
+#include <cstdlib>
+#include <debug.hh>
+#include <fail-simulator-on-error.h>
+
+/// Expose debugging features unconditionally for this compartment.
+using Debug = ConditionalDebug<true, "Claimant compartment">;
+
+void *x;
+
+int __cheri_compartment("claimant") make_claim(void *ptr)
+{
+	Debug::log("Initial quota: {}", heap_quota_remaining(MALLOC_CAPABILITY));
+
+	if (x != nullptr)
+	{
+		free(x);
+	}
+
+	Timeout t{10};
+	heap_claim(MALLOC_CAPABILITY, ptr);
+	x = ptr;
+
+	Debug::log("Make Claim : {}", x);
+	Debug::log("heap quota: {}", heap_quota_remaining(MALLOC_CAPABILITY));
+	return 0;
+};
+
+int __cheri_compartment("claimant") show_claim()
+{
+	Debug::log("Show Claim : {}", x);
+
+	return 0;
+}

examples/04.temporal_safety/claimant.h

@@ -0,0 +1,5 @@
+#include "compartment-macros.h"
+
+int __cheri_compartment("claimant") make_claim(void *ptr);
+
+int __cheri_compartment("claimant") show_claim();

examples/04.temporal_safety/xmake.lua

@@ -17,9 +17,14 @@ compartment("allocate")
     add_deps("freestanding", "debug")
     add_files("allocate.cc")
 
+compartment("claimant")
+    add_deps("debug")
+    add_files("claimant.cc")
+
 -- Firmware image for the example.
 firmware("temporal_safety")
     add_deps("allocate")
+    add_deps("claimant")
     on_load(function(target)
         target:values_set("board", "$(board)")
         target:values_set("threads", {
@@ -28,7 +33,7 @@ firmware("temporal_safety")
                 priority = 1,
                 entry_point = "entry",
                 stack_size = 0x400,
-                trusted_stack_frames = 2
+                trusted_stack_frames = 4
             }
         }, {expand = false})
     end)