Module capabilities

Special restricted capabilities.

Rust provides a mechanism for restricting certain operations to only be used by trusted code through the unsafe keyword. This is very useful, but doesn’t provide very granular access: code can either access all unsafe things, or none.

Capabilities are the mechanism in Tock that provides more granular access. For sensitive operations (e.g. operations that could violate isolation) callers must have a particular capability. The type system ensures that the caller does in fact have the capability, and unsafe is used to ensure that callers cannot create the capability type themselves.

Capabilities are passed to modules from trusted code (i.e. code that can call unsafe).

Capabilities are expressed as unsafe traits. Only code that can use unsafe mechanisms can instantiate an object that provides an unsafe trait. Functions that require certain capabilities require that they are passed an object that provides the correct capability trait. The object itself does not have to be marked unsafe.

Creating an object that expresses a capability is straightforward:

use kernel::capabilities::ProcessManagementCapability;

struct ProcessMgmtCap;
unsafe impl ProcessManagementCapability for ProcessMgmtCap {}

Now anything that has a ProcessMgmtCap can call any function that requires the ProcessManagementCapability capability.

Requiring a certain capability is also straightforward:

pub fn manage_process<C: ProcessManagementCapability>(_c: &C) {
   unsafe {
       ...
   }
}

Anything that calls manage_process must have a reference to some object that provides the ProcessManagementCapability trait, which proves that it has the correct capability.

Traits

ApplicationStorageCapability

The ApplicationStorageCapability capability allows the holder to create permissions to allow applications to have access to stored state on the system.

CreatePortTableCapability

The CreatePortTableCapability capability allows the holder to instantiate a new copy of the UdpPortTable struct.

ExternalProcessCapability

A capability that allows the holder to use the core kernel resources needed to implement the Process trait.

KerneluserStorageCapability

The KernelruserStorageCapability` capability allows the holder to create permissions to access kernel-only stored values on the system.

MainLoopCapability

The MainLoopCapability capability allows the holder to start executing as well as manage the main scheduler loop in Tock.

MemoryAllocationCapability

The MemoryAllocationCapability capability allows the holder to allocate memory, for example by creating grants.

NetworkCapabilityCreationCapability

A capability that allows the holder to instantiate NetworkCapabilitys and visibility capabilities.

ProcessManagementCapability

The ProcessManagementCapability allows the holder to control process execution, such as related to creating, restarting, and otherwise managing processes.

ProcessStartCapability

The ProcessStartCapability allows the holder to start a process.

SetDebugWriterCapability

The SetDebugWriterCapability allows the holder to set the debug writer mechanism in the kernel.

UdpDriverCapability

The UdpDriverCapability capability allows the holder to use two functions only allowed by the UDP driver.