CHERIoT Programmers' Guide

The memory allocator uses a capability model. Every caller of a memory allocation or deallocation function must present a capability that authorises allocation. This is a sealed capability to an AllocatorCapabilityState structure. Sealed capabilities were introduced in Section 1.4.

This uses the static sealing mechanism described in Section 4.11. There is no limit to the number of allocator capabilities that a compartment can hold. Each allocation capability holds an independent quota.

There is no requirement that the sum of all allocation quotas is less than the total available heap space. You can over-commit memory if you know that it will not all be needed at the same time. The quota mechanism gives you a way of limiting the total memory consumption of individual compartments (or groups of compartments) and of cleaning up after failure.

A compartment may hold different allocation capabilities for different purposes. The heap_free_all function allows you to free all memory allocated with a specified capability and so using multiple allocation quotas can be useful for error recovery.

You can forward-declare an allocator capability with the DECLARE_ALLOCATOR_CAPABILITY macro. This takes a single argument: the name of the allocator capability. You can then define the allocator capability with the DEFINE_ALLOCATOR_CAPABILITY macro, which takes the name and the quota size as arguments. These can be combined with the DECLARE_AND_DEFINE_ALLOCATOR_CAPABILITY macro.

In future versions of CHERIoT RTOS, allocator capabilities are likely to gain additional restrictions (for example, separating the ability to allocate from the ability to claim).

Every pointer to a new allocation provided by memory allocator is derived from a capability to a large heap region and bounded. The monotonicity guarantees in a CHERI system ensure that a caller cannot expand the bounds of the returned pointer.

The CHERIoT platform provides two additional features for temporal safety. These both depend on a revocation bitmap, a shadow memory space that stores one bit per eight bytes of heap memory. When an object is freed, the allocator paints the bits associated with it.

The load filter then ensures that any pointer to the object will have its tag cleared when it is loaded. This gives deterministic use-after-free protection; any attempt to use a pointer to a deallocated object will trap. The object is then placed in quarantine.

The revoker periodically scans all memory and invalidates any pointers whose base address points to a deallocated object. The monotonicity of bounds ensures that the base of a capability always points either somewhere within the allocation or, if the length is zero, to the word immediately after it.

The load filter ensures that no new pointers to deallocated objects can appear in memory and so the revocation sweep can proceed asynchronously. Any object that is in quarantine at the start of a sweep is safe to remove from quarantine at the end.

This combination of features allows the allocator to provide complete spatial and temporal safety for heap objects.

The heap_allocate and heap_free functions take a capability, as described above, that authorises allocation and deallocation. When an object is allocated with an explicit capability, it may be freed only by presenting the same capability. This means that, if you pass a heap-allocated buffer to another compartment, that compartment cannot free it unless you also pass the authorising capability.

If you need to clean up all memory allocated by a particular capability, heap_free_all will walk the heap and deallocate everything owned by that capability. This is useful when a compartment has crashed, to reclaim all of its heap memory.

If you are porting existing C/C++ code then it is likely that it uses malloc / free or the C++ new / delete operators. These are implemented as wrappers around heap_allocate and heap_free that pass MALLOC_CAPABILITY as the authorising capability. You can also pass this capability explicitly to allocate things from the same quota as the standard allocation routines.

You can control the amount of memory provided by this capability by defining the MALLOC_QUOTA for your compartment. If a compartment is not supposed to allocate memory on its own behalf, you can define CHERIOT_NO_AMBIENT_MALLOC. This will disable C’s malloc and free and C++'s global new and delete operators. Defining CHERIOT_NO_NEW_DELETE will disable the global C++ operator new and delete, but leave malloc and free available.

Defining these does not prevent memory allocation, you can still define non-default allocator capabilities and use them directly, but it prevents accidental allocation.

If you simply wish to change the quota that is available to malloc and free then you can define MALLOC_QUOTA when compiling your compartment. If you require more control, such as controlling the compilation unit that contains the definition of the allocator capability, then you can define CHERIOT_CUSTOM_DEFAULT_MALLOC_CAPABILITY. This macro will cause stdlib.h to provide a forward declaration of the default allocator capability, but not to define it. You must define it as described in Section 6.2.

This is most useful for C compartments with multiple compilation units. These will need to define the malloc capability in a single compilation unit.

Sometimes a compartment needs to be able to allocate memory but that memory is not logically owned by the compartment. This pattern appears even in the core of the RTOS. The compartment that provides message queues, for example, allocates memory on behalf of a caller, it does not hold the right to allocate memory on its own behalf. It does this by taking an allocator capability as an argument and forwarding it to the allocator.

Often, if a compartment is allocating on behalf of a caller, it needs to ensure that the caller doesn’t tamper with the object. The token APIs provide a lightweight mechanism for doing this.

When you call token_sealed_unsealed_alloc, you must provide two capabilities:

The first of these authorises memory allocation, the second authorises sealing. The CHERIoT ISA includes only three bits of object type space in the capability encoding and so the allocator provides a virtualised sealing mechanism. This allocates an object with a small header containing the sealing type and returns a sealed capability to the entire allocation and an unsealed capability to all except the header.

The unsealed capability can be used just like any other pointer to heap memory. The sealed capability can be used with token_obj_unseal to retrieve a copy of the unsealed capability. The token_obj_unseal function requires a permit-unseal capability whose value matches the permit-seal capability passed to token_sealed_unsealed_alloc.

An object allocated in this way can be deallocated only by presenting both the allocator capability and the sealing capability that match the original allocation. This is very convenient for compartments that expose services because the memory cannot go away while they are using it and can be reclaimed only when the same caller (or something acting on its behalf) authorises the deallocation.

If malicious caller passes a compartment a buffer and then frees it, then the callee can be induced to trap. There are some situations where this is acceptable. In some cases, compartments exist in a hierarchical trust relationship and it’s fine for a more-trusted compartment to be able to crash a less-trusted one. In other cases, the compartment is fault tolerant. For example, the scheduler ensures that its data structures are in a consistent state before performing any operations on user-provided data that may trap. As such, it can unwind to the caller and, at worst, leak memory owned by the caller.

In situations involving mutual distrust, the callee needs to claim the memory to prevent its deallocation. The heap_claim function allows you to place a claim on an object. The claim is dropped by calling heap_free.

While you have a claim on an object, that object counts towards your quota. You can claim the same object multiple times, each time adds a new claim to the object but (if it is already claimed with that quota) does not consume quota.