Welcome to Rainbow
==================
:Author: Michael Stone
:Date: August 28, 2007

Rainbow is the privileged security daemon described by the OLPC Bitfrost
security platform.

As such, its purpose is to referee the interactions of essentially all of the
activities and underlying system services on the XO.

It performs this "referee" role primarily by isolating related groups of
processes from one another and from relevant system resources such as the
kernel, the filesystem, the network, &etc. Technically, this isolation is
accomplished by manipulating a kernel-interface virtualization technology
called Linux-VServer and by gating attempts to use user-level resources with
a combination of OLPC-inserted authorization hooks (currently in DBus,
eventually in DBus, X, ALSA, &etc) and file-system synthesis.

Design Overview
---------------

Rainbow's current implementation is based on a three orthogonal concepts:

  1) An active, stateful daemon that responds to requests to start activities,
     to make resources available, &etc. and that responds to notifications of
     other state changes provided by the rest of the system (e.g. the user
     switching between activity instances).

  2) A small collection of mostly-declarative "stages" that can be sequenced by
     the Daemon in order to "activate" a given launch target (e.g. "legacy
     Sugar activity", or "Updater").

  3) A variety of small libraries for interpreting and manipulating relevant
     chunks of the overall system state; e.g. the VServer kernel-interface
     virtualization system, Sugar bundles, upgrade manifests, a file-system
     library, &etc.

Currently missing from this design are a good analysis of resource
finalization, an ACID state-manipulation library, and a evidence-collection
infrastructure for determining the software's correctness.

Please see docs/DESIGN for a more detailed discussion of Rainbow's design.

Contributing
------------

There are several basic ways you can participate in Rainbow's development. In
no particular order,

  1) You can help us search for a design that performs correctly and robustly
     in the face of interference. You can also review our code and suggest (or
     implement) clarifications, redesigns, cleanups.

  2) You can help develop Rainbow by using it on your own XO (ask for help on
     devel@laptop.org), and then reporting, diagnosing, and fixing things
     (particularly activities) that break.

The public fora that we frequent are:
  
  devel@lists.laptop.org
  sugar@lists.laptop.org
  security@lists.laptop.org

  #olpc on irc.freenode.org

  Trac tickets with keyword 'security' and CC including 'mstone', 'coderanger',
    and 'mburns' on the Trac instance at dev.laptop.org

If you need to synchronize an action with us please contact us personally at:

  Michael Stone <michael@laptop.org>     (irc: Ashsong,    trac: mstone)
  Noah Kantrowitz <noah@laptop.org>      (irc: coderanger, trac: coderanger)
  Michael Burns <mburns@laptop.org>      (irc: mburns,     trac: mburns)

Our build tree is located at three different URLs, depending on the purpose of
access:

  http://dev.laptop.org/git/security               (browse)
  git://dev.laptop.org/security                    (clone)
  git+ssh://$username@dev.laptop.org/git/security  (commit)

and individual security developers maintain personal trees at locations like:

  http://dev.laptop.org/git/users/mstone/security
  http://dev.laptop.org/git/users/coderanger/security
  http://dev.laptop.org/git/users/mburns/security

Since we use a distributed development model, you can send us your work in
several ways. We are happy to receive:

  1) a link to your clone of the security repository and a summary of what
     you'd like us to examine in it

  2) an emailed patch, preferably indicating the commit to which the patch
     should be applied 

  3) general comments, questions, and reviews in any medium

Finally, since security is a property of a complete organic system and not of
any single component thereof, we are most interested in hearing suggestions on
how we can work more closely with you to reach our mutual end goals.


