APIs for dealing with type-safe opaque handles (sealed objects). More...
Go to the source code of this file.
Classes | |
| class | Sealed< T > |
| Helper template for representing a sealed capability created by the allocator's token API. More... | |
Typedefs | |
| typedef struct TokenKeyType * | TokenKey |
| Sealing keys in CHERI are represented as capabilities. | |
| typedef TokenKey | SKey |
| The old name for TokenKey, do not use in new code. | |
Functions | |
| TokenKey | token_key_new (void) |
| Create a new sealing key. | |
| token_sealed_unsealed_alloc (TimeoutArgument timeout, AllocatorCapability heapCapability, TokenKey key, size_t sz, void **unsealed) | |
| Allocate a new object with size sz. | |
| token_sealed_alloc (TimeoutArgument timeout, AllocatorCapability heapCapability, TokenKey, size_t) | |
| Same as token_sealed_unsealed_alloc() without getting the unsealed capability. | |
| void *__cheri_libcall | token_obj_unseal (TokenKey, CHERI_SEALED(void *)) |
| Unseal the object given the key. | |
| void *__cheri_libcall | token_obj_unseal_static (TokenKey, CHERI_SEALED(void *)) |
| Unseal the object given the key. | |
| void *__cheri_libcall | token_obj_unseal_dynamic (TokenKey, CHERI_SEALED(void *)) |
| Unseal the object given the key. | |
| template<typename T> | |
| token_permissions_and (CHERI_SEALED(T *) object, int permissions) | |
| Mask the user permissions of a sealed object. | |
| static int | token_permissions_get (CHERI_SEALED(void *) object) |
| Returns the user permissions bitmap for the sealed object. | |
| int | token_obj_destroy (AllocatorCapability heapCapability, TokenKey, CHERI_SEALED(void *)) |
| Destroy the object given its key, freeing memory. | |
| int | token_obj_can_destroy (AllocatorCapability heapCapability, TokenKey key, CHERI_SEALED(void *) object) |
| Check whether the pair of a sealing key and a heap capability can free a sealed object. | |
| template<typename T> | |
| std::pair< T *, Sealed< T > > | token_allocate (TimeoutArgument timeout, AllocatorCapability heapCapability, TokenKey key) |
| Type-safe helper to allocate a sealed T*. | |
| template<typename T> | |
| T * | token_unseal (TokenKey key, Sealed< T > sealed) |
| Type-safe helper that unseal a Sealed<T> and returns a T*. | |
Detailed Description
APIs for dealing with type-safe opaque handles (sealed objects).
Definition in file token.h.
Typedef Documentation
◆ SKey
◆ TokenKey
| typedef struct TokenKeyType* TokenKey |
Sealing keys in CHERI are represented as capabilities.
They have the same representation as pointers but have permissions that allow their address to refer to an abstract space of types, rather than a space of addresses on the memory bus. CHERIoT uses a pointer to a specific opaque type to expose this in the C/C++ type systems. Sealing keys should be created with the STATIC_SEALING_TYPE macro or the token_key_new function. Although they appear to be pointers, there is no way to dereference them that will not trap.
Function Documentation
◆ token_allocate()
template<typename T>
| std::pair< T *, Sealed< T > > token_allocate | ( | TimeoutArgument | timeout, |
| AllocatorCapability | heapCapability, | ||
| TokenKey | key ) |
Type-safe helper to allocate a sealed T*.
Returns the sealed and unsealed pointers.
Callers should check the sealed capability's tag to determine success.
Definition at line 259 of file token.h.
References token_sealed_unsealed_alloc().
◆ token_key_new()
| TokenKey token_key_new | ( | void | ) |
Create a new sealing key.
This function is guaranteed to complete unless the allocator has exhausted the total number of sealing keys possible (2^32 - 2^24). After this point, it will never succeed. A compartment that is granted access to this entry point is trusted not to exhaust this resource. If you wish to allow a compartment to seal objects, but do not wish to allow it to allocate new sealing keys, then you should insert a proxy compartment that guarantees that it will call this API once and return a single key to the caller.
The return value from this is a capability with the permit-seal and permit-unseal permissions. Callers may remove one or both of these permissions and delegate the resulting capability to allow other compartments to either seal or unseal the capabilities with this key.
If the sealing keys have been exhausted then this will return null. This API is guaranteed never to block.
References token_key_new().
Referenced by thread_pool::detail::sealing_key_for_type(), and token_key_new().
◆ token_obj_can_destroy()
| int token_obj_can_destroy | ( | AllocatorCapability | heapCapability, |
| TokenKey | key, | ||
| CHERI_SEALED(void *) | object ) |
Check whether the pair of a sealing key and a heap capability can free a sealed object.
Returns 0 on success, -EINVAL if the key or object is not valid, or one of the errors from heap_can_free if the free would fail for other reasons.
References token_obj_can_destroy().
Referenced by token_obj_can_destroy().
◆ token_obj_destroy()
| int token_obj_destroy | ( | AllocatorCapability | heapCapability, |
| TokenKey | , | ||
| CHERI_SEALED(void *) | ) |
Destroy the object given its key, freeing memory.
The key must have the permit-unseal permission.
Returns 0 on success. -EINVAL if key or obj are not valid, or they don't match, or if obj has already been destroyed.
References token_obj_destroy().
Referenced by token_obj_destroy(), and thread_pool::detail::wrap_callback_lambda().
◆ token_obj_unseal()
| void *__cheri_libcall token_obj_unseal | ( | TokenKey | , |
| CHERI_SEALED(void *) | ) |
Unseal the object given the key.
The key may be either a static or dynamic key (i.e. one created with the STATIC_SEALING_TYPE macro or with token_key_new) and the object may be either allocated dynamically (via the token APIs) or statically (via the DEFINE_STATIC_SEALED_VALUE macro).
Returns the unsealed object if the key and object are valid and of the correct type, null otherwise.
This function is equivalent to calling both token_obj_unseal_static and token_obj_unseal_dynamic and returning the result of the first one that succeeds, or null if both fail.
References token_obj_unseal().
Referenced by token_obj_unseal(), and token_unseal().
◆ token_obj_unseal_dynamic()
| void *__cheri_libcall token_obj_unseal_dynamic | ( | TokenKey | , |
| CHERI_SEALED(void *) | ) |
Unseal the object given the key.
The key may be either a static or dynamic key (i.e. one created with the STATIC_SEALING_TYPE macro or with token_key_new) and the object must be allocated dynamically with token_sealed_alloc or token_sealed_unsealed_alloc.
Returns the unsealed object if the key and object are valid and of the correct type, null otherwise.
References token_obj_unseal_dynamic().
Referenced by token_obj_unseal_dynamic().
◆ token_obj_unseal_static()
| void *__cheri_libcall token_obj_unseal_static | ( | TokenKey | , |
| CHERI_SEALED(void *) | ) |
Unseal the object given the key.
The key must be a static sealing key (i.e. one created with the STATIC_SEALING_TYPE macro) and the object must be a statically sealed object (i.e. one created with the DEFINE_STATIC_SEALED_VALUE macro).
Returns the unsealed object if the key and object are valid and of the correct type, null otherwise.
References token_obj_unseal_static().
Referenced by token_obj_unseal_static().
◆ token_permissions_and()
template<typename T>
| token_permissions_and | ( | CHERI_SEALED(T *) | object, |
| int | permissions ) |
Mask the user permissions of a sealed object.
The first argument is the sealed capability, the second is a permission mask to apply.
Definition at line 148 of file token.h.
References token_permissions_and().
Referenced by allocator_permissions_and(), CHERI_SEALED(), and token_permissions_and().
◆ token_permissions_get()
|
inlinestatic |
Returns the user permissions bitmap for the sealed object.
Definition at line 160 of file token.h.
Referenced by allocator_permissions(), and queue_permissions().
◆ token_sealed_alloc()
| token_sealed_alloc | ( | TimeoutArgument | timeout, |
| AllocatorCapability | heapCapability, | ||
| TokenKey | , | ||
| size_t | ) |
Same as token_sealed_unsealed_alloc() without getting the unsealed capability.
The key must have the permit-seal permission.
References token_sealed_alloc().
Referenced by token_sealed_alloc().
◆ token_sealed_unsealed_alloc()
| token_sealed_unsealed_alloc | ( | TimeoutArgument | timeout, |
| AllocatorCapability | heapCapability, | ||
| TokenKey | key, | ||
| size_t | sz, | ||
| void ** | unsealed ) |
Allocate a new object with size sz.
An unsealed pointer to the newly allocated object is returned in *unsealed, the sealed pointer is returned as the return value. An invalid unsealed pointer does not constitute an error; the caller will still be given the sealed return value, assuming allocation was otherwise successful.
The key parameter must have both the permit-seal and permit-unseal permissions.
On error, this returns null.
References token_sealed_unsealed_alloc().
Referenced by thread_pool::async(), token_allocate(), and token_sealed_unsealed_alloc().
◆ token_unseal()
Type-safe helper that unseal a Sealed<T> and returns a T*.
If key matches the type used for sealing sealed, this returns the unsealed value, otherwise it returns NULL / nullptr.
Definition at line 287 of file token.h.
References token_obj_unseal().
Referenced by thread_pool::detail::wrap_callback_lambda().
Generated by
1.18.0