CHERIC(9)

NAME
cheri_andperm cheri_clear_low_ptr_bits cheri_setbounds cheri_fromint cheri_get_low_ptr_bits cheri_getaddress cheri_getbase cheri_getdefault cheri_getlen cheri_getoffset cheri_getpcc cheri_getperm cheri_getsealed cheri_getstack cheri_gettop cheri_gettag cheri_gettype cheri_clearperm cheri_cleartag cheri_incoffset cheri_seal cheri_set_low_ptr_bits cheri_setaddress cheri_setoffset cheri_unseal - CHERI C built-in functions

SYNOPSIS
#include <cheri/cheri.h>
#include <cheri/cheric.h>
void * __capability
cheri_andperm(void * __capability c, size_t mask);
void * __capability
cheri_clear_low_ptr_bits(void * __capability c, size_t mask);
void * __capability
cheri_setbounds(void * __capability c, size_t length);
void * __capability
cheri_fromint(vaddr_t);
size_t
cheri_get_low_ptr_bits(void * __capability c, size_t mask);
vaddr_t
cheri_getaddress(void * __capability c);
vaddr_t
cheri_getbase(void * __capability c);
void * __capability
cheri_getdefault(void);
size_t
cheri_getlen(void * __capability c);
size_t
cheri_getoffset(void * __capability c);
void * __capability
cheri_getpcc(void);
size_t
cheri_getperm(void * __capability c);
_Bool
cheri_getsealed(void * __capability c);
void * __capability
cheri_getstack(void);
vaddr_t
cheri_gettop(void * __capability c);
_Bool
cheri_gettag(void * __capability c);
vaddr_t
cheri_gettype(void * __capability c);
void * __capability
cheri_clearperm(void * __capability c, size_t mask);
void * __capability
cheri_cleartag(void * __capability c);
void * __capability
cheri_incoffset(void * __capability c, size_t offset);
void * __capability
cheri_seal(void * __capability c, void * __capability typecap);
void * __capability
cheri_set_low_ptr_bits(void * __capability c, size_t mask);
void * __capability
cheri_setaddress(void * __capability c, vaddr_t address);
void * __capability
cheri_setoffset(void * __capability c, size_t offset);
void * __capability
cheri_unseal(void * __capability c, void * __capability typecap);

DESCRIPTION
The cheric(9) functions provide a C-language interface to inspect and modify capability fields. When a change is requested, a new capability is returned with the change applied.

  Querying capability fields
The following APIs allow capability fields to be queried:

cheri_getaddress(c)
    Return the address field of the capability c. This value will normally be the the same as the integer cast of a capability pointer.

cheri_getbase(c)
    Return the base (bottom) address associated with the capability c; this is its lower bound.

cheri_getoffset(c)
    Return the offset associated with capability c; this is the difference between its address and its lower bound.

cheri_getperm(c)
    Return the permissions associated with the capability c.

cheri_getsealed(c)
    Return a boolean indicating whether the capability c is sealed.

cheri_gettag(c)
    Return a boolean indicating whether the capability c has a valid tag.

cheri_gettype(c)
    Return the object type of the capability c.

  Setting capability fields
The following APIs allow capability fields to be set, with a new capability returned:

cheri_andperm(c, mask)
    Return a capability derived from c that has its permissions mask bit-wise AND'd with the value of mask.

cheri_cleartag(c)
    Return a capability derived from c that has its validity tag cleared.

cheri_setbounds(c, length)
    Return a capability derived from c that has its base set to the current address of c, and length set to length.

cheri_incoffset(c, offset)
    Return a capability derived from c that has its offset incremented by offset.

cheri_seal(c, typecap)
    Return a capability derived from c that is sealed using capability typecap.

cheri_setoffset(c, offset)
    Return a capability derived from c that has its offset field set to offset.

  Capability address low bits
The following APIs assist in getting, setting, and clearing lower bits in capabilities:

cheri_clear_low_ptr_bits(c, mask)
    Return a capability derived from c, but with the bits of the address indicated by mask cleared.

cheri_get_low_ptr_bits(c, mask)
    Return the lower bits of the address of capability c indicated by mask.

cheri_set_low_ptr_bits(c, mask)
    Return a capability derived from c, but with the bits of the address indicated by mask set.

  Capability alignment
To be added.

  Return special capabilities
The following APIs return capability pointers for certain well-defined capabilities in the run-time environment:

cheri_getdefault(void)
    Return the Default Data Capability (DDC).

cheri_getpcc(void)
    Return the Program-Counter Capability (PCC).

cheri_getstack(void)
    Return the current stack capability.

AUTHORS
This manual page was written by Robert N. M. Watson <rwatson@FreeBSD.org>.

This software and this manual page were developed by SRI International and the University of Cambridge Computer Laboratory under DARPA/AFRL contract (FA8750-10-C-0237) (“CTSRD”), as part of the DARPA CRASH research programme.