Add more examples of temporal safety

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,24 @@ 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 sub object, a capability that references a sub-range of the allocation.
+
+In the first of these the sub object is passed to free(), but this has no impact until the original allocation is also freed (i.e an allocation does not become fragmented if you try to free the middle of it).
+
+In the second use case a claim is made on the sub object, which counts against the quota but now means that the sub object remains valid even if the enclosing allocation is freed.
+Both the sub object and the enclosing allocation become invalid when the claim is releases. 
+
+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 only hold 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 a persistent claim._    
+
+The final use case shows how an object initially allocated in one compartment be claimed by (add counted against the quota) of a second compartment.
+This allow, 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 remain valid because it is now claimed by the second compartment.
+Note that the quota is reduced by more when making a claim than an allocation because a small amount of additional heap is required for the claim headers.   
+

examples/04.temporal_safety/allocate.cc

@@ -5,17 +5,141 @@
 #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
+	{
+		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)