[elysium-developers] Capabilities revisited

[Kasper V. L. <ve...@da...>]

Capabilities
============
Capabilities are stored in C-lists and protected by means of paging.
It's possible to map the C-list of any process read-only, but always
impossible to map read/write. Under Elysium a capability is represented
with the following data structure:

typedef struct cap_s 
{
  uint32_t obj_id;
  uint32_t obj_type;
  uint32_t obj_perm;
  pid_t obj_owner;
} cap_t;

If the obj_owner field is 0 the capability refers to kernel objects,
otherwise it refers to objects created - and managed - by the process
with the given pid. 

Kernel Objects
==============
The objects the kernel manages are:

* physical pages
* I/O ports
* CPU quanta
* ... what else?

Given access to a kernel object it's possible to create a capability
that allows access to the object. As an example of a system call
creating capabilities consider this system call that creates a
capability for a single physical page:

int
sys_create_page_cap(uint32_t pn, void *vptr, uint32_t ci)
{
  <<check that the virtual address vptr
    refers to the physical page pn in the current
    address space>>
  <<create cap c with id = pn, type = OBJ_TYPE_PAGE, 
    perm = OBJ_PERM_READ | OBJ_PERM_WRITE, and
    owner = 0>>
  <<insert cap c into current C-list at index ci>>
}

Server Objects
==============
Any process can create any (PRIVATE) capability as long as the obj_owner
field refers to the pid of the process. Consider the following system
call for doing just that:

int
sys_create_private_cap(uint32_t id, uint32_t type, uint32_t perm,
uint32_t ci)
{
  <<create cap c with id = id, type = type, perm = perm,
    and owner = current_process->pid>>
  <<insert cap c into current C-list at index ci>>
}

Transferring Capabilities
=========================
It should be possible to give a capability to another process. One way
of doing this is extending the PCT mechanism to handle transferring a
single capability. The transferred capability could be put in the CPU
context, and accessible through the following system call:

int
sys_acquire_cap(uint32_t ci)
{
  <<check the CPU context for a capability>>
  <<get capability c from CPU context>>
  <<insert cap c into current C-list at index ci>>
}

This system call only makes sense to call from a PCT handler - and only
in the situation where a capability was transferred.

Duplicating Capabilities
========================
Given a capability it should be possible to duplicate it (and maybe
restricting the access rights). The following system call should do the
trick:

int
sys_duplicate_cap(uint32_t ci, uint32_t nperm, uint32_t nci)
{
  <<check that nperm is a subset of c-list[ci].perm>>
  <<create new cap nc with id = C-list[ci].id, ..., 
    and perm = nperm>>
  <<insert cap nc into C-list at index nci>>
}

Restricting Capability Use
==========================
There might be situations where a process wants to give a capability to
another process, but wants to make sure that the capability cannot be
duplicated or transferred. By extending the capability data structure to
with a cap_perm field it's possible to handle this situation. The
sys_duplicate_cap() might be rewritten to something like:

int
sys_duplicate_cap(uint32_t ci, uint32_t nperm, uint32_t nci)
{
  <<check that (C-list[ci].cap_perm & CAP_PERM_DUPLICABLE) != 0>>
  <<.... as before ....>>
}

Exo Considerations
==================
When using capabilities for allowing access to physical resources it's
really important that the (id,type,owner) tuple doesn't hide the
physical name of the resource. In the case of physical pages - for
instance - the id should encode the physical page number. For most
resources this is quite trivial, but a capability representing a range
of I/O ports we need to make sure that the (id,type,owner) tuple reveals
the exact range of I/O ports in a simple way.

The reason for exposing physical names of resources to applications is
that the physical names typically encode vital information for efficient
management. Consider disk blocks for a moment. A disk block number
encodes the physical position - the most important disk block property
performance-wise.

/Kasper

-- 
-------------------------------------------------------------------
Kasper Verdich Lund, Computer Science Department, Aarhus University
Office: 34P.218              | Phone: (+45) 8942 5680
Email:  ve...@da...  | WWW: http://www.daimi.au.dk/~verdich