C++ helpers for operating on capabilities. More...
#include <cheri.h>#include <cstddef>#include <cstdint>#include <initializer_list>#include <magic_enum/magic_enum.hpp>Go to the source code of this file.
Classes | |
| class | CHERI::PermissionSet |
| Class encapsulating a set of permissions. More... | |
| struct | CHERI::remove_sealed< T * > |
| Specialisation to. More... | |
| struct | CHERI::is_sealed_capability< T > |
| Type trait for checking if a type is a sealed capability. More... | |
| class | CHERI::Capability< T, IsSealedT > |
| Helper class for accessing capability properties on pointers. More... | |
| class | CHERI::ErrorOr< T, IsSealed > |
| Helper for a value that encodes either a pointer or an error value in a pointer-sized value, discriminated by the tag bit. More... | |
Concepts | |
| concept | CHERI::IsPointer |
| Concept that matches pointers. | |
| concept | CHERI::IsSmartPointerLike |
| Concept that matches smart pointers, i.e., classes which implements a get method returning a pointer, and supports operator= with the return value of get. | |
Typedefs | |
| template<typename T> | |
| using | CHERI::remove_sealed_t |
| Helper that provides the type of an unsealed capability from a sealed capability. | |
Enumerations | |
| enum class | CHERI::Permission : uint32_t { Global = CheriPermissionGlobal , LoadGlobal = CheriPermissionLoadGlobal , Store = CheriPermissionStore , LoadMutable = CheriPermissionLoadMutable , StoreLocal = CheriPermissionStoreLocal , Load = CheriPermissionLoad , LoadStoreCapability = CheriPermissionLoadStoreCapability , AccessSystemRegisters = CheriPermissionAccessSystemRegisters , Execute = CheriPermissionExecute , Unseal = CheriPermissionUnseal , Seal = CheriPermissionSeal , User0 = CheriPermissionUser0 } |
| The complete set of architectural permissions. More... | |
| enum class | CHERI::CauseCode { None = CheriCauseCodeNone , BoundsViolation = CheriCauseCodeBoundsViolation , TagViolation = CheriCauseCodeTagViolation , SealViolation = CheriCauseCodeSealViolation , PermitExecuteViolation = CheriCauseCodePermitExecuteViolation , PermitLoadViolation = CheriCauseCodePermitLoadViolation , PermitStoreViolation = CheriCauseCodePermitStoreViolation , PermitStoreCapabilityViolation , PermitStoreLocalCapabilityViolation , PermitAccessSystemRegistersViolation , Invalid = CheriCauseCodeInvalid } |
| The codes used in the cause field of the mtval CSR when the processor takes a CHERI exception. More... | |
| enum class | CHERI::RegisterNumber { CZR = CheriRegisterNumberCzr , CRA = CheriRegisterNumberCra , CSP = CheriRegisterNumberCsp , CGP = CheriRegisterNumberCgp , CTP = CheriRegisterNumberCtp , CT0 = CheriRegisterNumberCT0 , CT1 = CheriRegisterNumberCT1 , CT2 = CheriRegisterNumberCT2 , CS0 = CheriRegisterNumberCS0 , CS1 = CheriRegisterNumberCS1 , CA0 = CheriRegisterNumberCA0 , CA1 = CheriRegisterNumberCA1 , CA2 = CheriRegisterNumberCA2 , CA3 = CheriRegisterNumberCA3 , CA4 = CheriRegisterNumberCA4 , CA5 = CheriRegisterNumberCA5 , PCC = CheriRegisterNumberPcc , MTCC = CheriRegisterNumberMtcc , MTDC = CheriRegisterNumberMtdc , MScratchC = CheriRegisterNumberMScratchC , MEPCC = CheriRegisterNumberMepcc , Invalid = CheriRegisterNumberInvalid } |
| Register numbers as reported in thee cap idx field of mtval CSR when a CHERI exception is taken. More... | |
Functions | |
| size_t | CHERI::representable_length (size_t length) |
| Rounds len up to a CHERI representable length for the current architecture. | |
| size_t | CHERI::representable_alignment_mask (size_t length) |
| Returns the alignment mask required for a given length. | |
| bool | CHERI::is_precise_range (ptraddr_t base, size_t size) |
| Can the range [base, base + size) be precisely covered by a capability? | |
| template<typename T> | |
| CHERI::Capability (T *) -> Capability< T, false > | |
| template<PermissionSet Permissions = PermissionSet{Permission::Load}, bool CheckStack = true, bool EnforceStrictPermissions = false> requires (std::is_pointer_v<std::remove_cvref_t<decltype(ptr)>> || IsSmartPointerLike<std::remove_cvref_t<decltype(ptr)>>) | |
| bool | CHERI::check_pointer (auto &ptr, size_t space=sizeof(std::remove_pointer< decltype(ptr)>)) |
| Checks that ptr is valid, unsealed, has at least Permissions, and has at least space bytes after the current offset. | |
| template<typename T> | |
| auto | CHERI::with_interrupts_disabled (T &&fn) |
| Invokes the passed callable object with interrupts disabled. | |
| std::pair< CauseCode, RegisterNumber > | CHERI::extract_cheri_mtval (uint32_t mtval) |
| Decompose the value reported in the mtval CSR on CHERI exception into a pair of CauseCode and RegisterNumber. | |
| template<typename T, bool IsSealed> | |
| CHERI::ErrorOr (ErrorOr< T, IsSealed >) -> ErrorOr< T, IsSealed > | |
| Explicit copy constructor deduction guide. | |
Variables | |
| template<typename T> | |
| constexpr bool | CHERI::is_sealed_capability_v |
| Helper to check that a type is a sealed capability. | |
Detailed Description
C++ helpers for operating on capabilities.
Definition in file cheri.hh.
Typedef Documentation
◆ remove_sealed_t
template<typename T>
| using CHERI::remove_sealed_t |
Initial value:
Helper that provides the type of an unsealed capability from a sealed capability.
Enumeration Type Documentation
◆ CauseCode
|
strong |
The codes used in the cause field of the mtval CSR when the processor takes a CHERI exception.
| Enumerator | |
|---|---|
| None | No exception. This value is passed to the error handler after a forced unwind in a called compartment. |
| BoundsViolation | Attempted to use a capability outside its bounds. |
| TagViolation | Attempted to use an untagged capability to authorize something. |
| SealViolation | Attempted to use a sealed capability to authorize something. |
| PermitExecuteViolation | Attempted to jump to a capability without Permission::Execute. |
| PermitLoadViolation | Attempted to load via a capability without Permission::Load. |
| PermitStoreViolation | Attempted to store via a capability without Permission::Store. |
| PermitStoreCapabilityViolation | Attempted to store a tagged capability via a capability without Permission::LoadStoreCapability. |
| PermitStoreLocalCapabilityViolation | Attempted to store a tagged capability without Permission::Global via capability without Permission::StoreLocal. |
| PermitAccessSystemRegistersViolation | Attempted to access a restricted CSR or SCR with PCC without Permission::AccessSystemRegisters. |
| Invalid | Used to represent a value that has no valid meaning in hardware. |
◆ Permission
|
strong |
The complete set of architectural permissions.
| Enumerator | |
|---|---|
| Global | Capability refers to global memory (this capability may be stored anywhere). |
| LoadGlobal | Global capabilities can be loaded through this capability. Without this permission, any capability loaded via this capability will have Global and LoadGlobal removed. |
| Store | Capability may be used to store. Any store via a capability without this permission will trap. |
| LoadMutable | Capabilities with store permission may be loaded through this capability. Without this, any loaded capability will have LoadMutable and Store removed. |
| StoreLocal | This capability may be used to store capabilities that do not have Global permission. |
| Load | This capability can be used to load. |
| LoadStoreCapability | Any load and store permissions on this capability convey the right to load or store capabilities in addition to data. |
| AccessSystemRegisters | If installed as the program counter capability, running code may access privileged system registers. |
| Execute | This capability may be used as a jump target and used to execute instructions. |
| Unseal | This capability may be used to unseal other capabilities. The 'address' range is in the sealing type namespace and not in the memory namespace. |
| Seal | This capability may be used to seal other capabilities. The 'address' range is in the sealing type namespace and not in the memory namespace. |
| User0 | Software defined permission bit, no architectural meaning. |
◆ RegisterNumber
|
strong |
Register numbers as reported in thee cap idx field of mtval CSR when a CHERI exception is taken.
Values less than 32 refer to general purpose registers and others to SCRs (of these, only PCC can actually cause an exception).
| Enumerator | |
|---|---|
| CZR | The zero register, which always contains the NULL capability. |
| CRA | $c1 / $cra used by the ABI as the return address. Not preserved across calls. |
| CSP | $c2 / $csp used by the ABI as the stack pointer. Preserved across calls. |
| CGP | $c3 / $cgp used by the ABI as the global pointer. Not allocatable by the compiler, set by the switcher on compartment entry. |
| CTP | $c4 / $ctp used by the ABI as the thread pointer. Currently unused by the compiler. Not preserved across compartment calls. |
| CT0 | $c5 / $ct0 used by the ABI as temporary register. Not preserved across calls. |
| CT1 | $c6 / $ct1 used by the ABI as temporary register. Not preserved across calls. Used by cross-compartment call as target import entry. |
| CT2 | $c7 / $ct2 used by the ABI as temporary register. Not preserved across calls. |
| CS0 | $c8 / $cs0 used by the ABI as a callee-saved register. Preserved across calls. |
| CS1 | $c9 / $cs1 used by the ABI as a callee-saved register. Preserved across calls. |
| CA0 | $c10 / $ca0 used by the ABI as an argument register. Not preserved across calls. |
| CA1 | $c11 / $ca1 used by the ABI as an argument register. Not preserved across calls. |
| CA2 | $c12 / $ca2 used by the ABI as an argument register. Not preserved across calls. |
| CA3 | $c13 / $ca3 used by the ABI as an argument register. Not preserved across calls. |
| CA4 | $c14 / $ca4 used by the ABI as an argument register. Not preserved across calls. |
| CA5 | $c15 / $ca5 used by the ABI as an argument register. Not preserved across calls. |
| PCC | The Program Counter Capability. Special capability register used to authorize instruction fetch. The address is that of the faulting instruction. Also used for accessing read-only globals. |
| MTCC | Machine-mode Trap Code Capability. Special capability register that is installed in PCC when the CPU takes a trap. The address has the same semantics as the RISC-V mtvec CSR. Only accessible when PCC has the AccessSystemRegisters permission. |
| MTDC | Machine-mode Tusted Data Capability. Special capability register that contains the memory root capability on boot. Only accessible when PCC has the AccessSystemRegisters permission. Use by the RTOS to store a capability to the trusted stack. |
| MScratchC | Machine-mode Scratch Capability. Special capabiltiy register that contains the sealing root capability on boot. Only accessible when PCC has the AccessSystemRegisters permission. |
| MEPCC | Machine-mode Exception Program Counter Capability. Special capability register that contains the PCC of the faulting instruction on trap. The address has the same semantics as the RISC-V mepc CSR. Only accessible when PCC has the AccessSystemRegisters permission. |
| Invalid | Indicates a value that is not used by the hardware to refer to a register. |
Function Documentation
◆ check_pointer()
template<PermissionSet Permissions = PermissionSet{Permission::Load}, bool CheckStack = true, bool EnforceStrictPermissions = false>
requires (std::is_pointer_v<std::remove_cvref_t<decltype(ptr)>> || IsSmartPointerLike<std::remove_cvref_t<decltype(ptr)>>)
requires (std::is_pointer_v<std::remove_cvref_t<decltype(ptr)>> || IsSmartPointerLike<std::remove_cvref_t<decltype(ptr)>>)
|
inline |
Checks that ptr is valid, unsealed, has at least Permissions, and has at least space bytes after the current offset.
ptr can be a pointer, or a smart pointer, i.e., any class that supports a get method returning a pointer, and operator=. This includes Capability and standard library smart pointers.
If the permissions do not include Global, then this will also check that the capability does not point to the current thread's stack. This behaviour can be disabled (for example, for use in a shared library) by passing false for CheckStack.
If EnforceStrictPermissions is set to true, this will also set the permissions of the passed capability reference to Permissions, and its bounds to space. This is useful for detecting cases where compartments ask for fewer permissions than they actually require and callers happen to provide the required permissions. Similarly, if you are calling check_pointer in a function that wraps untrusted code such as a third-party library, this lets you detect cases where your callers are failing to remove permissions that the untrusted code should not have.
This function is provided as a wrapper for the check_pointer C API. It is always inlined. For each call site, it materialises the constants needed before performing an indirect call to check_pointer.
Definition at line 1314 of file cheri.hh.
References CHERI::Capability< T, IsSealedT >::bounds(), check_pointer(), CHERI::Capability< T, IsSealedT >::get(), and CHERI::Capability< T, IsSealedT >::permissions().
◆ extract_cheri_mtval()
|
inline |
Decompose the value reported in the mtval CSR on CHERI exception into a pair of CauseCode and RegisterNumber.
Will return CauseCode::Invalid if the code field is not one of the defined causes and RegisterNumber::Invalid if the register number is not a valid register number. Other bits of mtval are ignored.
◆ is_precise_range()
|
inline |
◆ representable_alignment_mask()
|
inline |
◆ representable_length()
|
inline |
◆ with_interrupts_disabled()
template<typename T>
| auto CHERI::with_interrupts_disabled | ( | T && | fn | ) |
Variable Documentation
◆ is_sealed_capability_v
Generated by
1.18.0