View of /trunk/uia/vx32/README

			VX32 Virtual Environment
			   Quick Start Guide

Introduction
~~~~~~~~~~~~

VX32 is a user-mode library that can be linked into arbitrary applications
that wish to create secure, isolated execution environments in which to run
untrusted extensions or plug-ins implemented as native x86 code.  VX32 is
thus conceptually comparable in purpose to a Java virtual machine or a C#
language runtime, except that since it runs arbitrary x86 code, VX32-based
application extensions can be written in ANY language, including C and C++,
not just type-safe languages such as Java or C#.

The VX32 distribution comes with a "sample application", vxrun, that may be
useful in its own right.  The vxrun utility runs an arbitrary x86
executable compiled for VX32 in an extremely simple "Unix filter"
environment, which gives the program the ability to read stdin and write
stdout and stderr, but not to do _anything_ else (such as opening other
files, accessing the network, or even determining the current time or host
OS type).  This sample VX32 environment provides a safe and very simple
native code extension mechanism that can be used easily from shell scripts
or other programs.  The Unix filter environment vxrun implements, while
rudimentary, may be sufficient for many practical purposes such as
transcoding data streams on demand.

This library is still in a very EXPERIMENTAL state.  In particular,
although it is designed to run untrusted code safely, the current
implementation has neither been tested extensively nor run through any kind
of rigorous security analysis, so USE AT YOUR OWN RISK.  The author takes
no responsibility whatsoever for what the VX32 library, or any code you run
within the VX32 environment, might do to your system.


System Compatibility
~~~~~~~~~~~~~~~~~~~~

The VX32 virtual machine currently runs on Linux for x86-32 and x86-64, and
on FreeBSD for x86-32.  Ports to other operating systems will follow as I
or other people get around to making and testing them.  In general, porting
VX32 to other operating systems running on x86 processors is fairly
trivial; it's just a matter of adapting to the OS's particular method of
providing applications with control over their LDT (Local Descriptor
Table), and tweaking the descriptor setup code to avoid conflicting with
any uses the OS itself makes of LDT segments or the fs/gs segment registers
- typically for Thread Local Storage (TLS).

Porting VX32 to non-x86 host systems is of course fundamentally more
challenging because it involves instruction set interpretation or binary
translation of native x86 code to the host architecture.  A slow but highly
portable instruction interpreter is under development, as is a binary
translator to run x86-based VX32 code on PowerPC platforms (e.g., pre-Intel
versions of Mac OS X).  The eventual goal is to make VX32 capable of
running native x86 code _really_ efficiently on x86 processors (which it
already does), with _usable_ efficiency on the most popular non-x86
processors, and at least run reliably on just about any 32-bit host
processor, making it a true cross-platform environment for safe extensions
written in arbitrary programming languages.


Installation
~~~~~~~~~~~~

To build VX32, you will first need a GCC cross-compiler tool suite
configured for the target 'vx32', which we use to compile code intended to
run _within_ the OS-independent VX32 execution environment.  The easiest
way to get this tool suite is to use one of the binary distributions
available at http://pdos.csail.mit.edu/~baford/vm/ for certain operating
systems.  Just download the appropriate tarball and extract it into your
system's root directory, and everything will go into a directory called
'/opt/vx32'.  If you want or need to build your own cross-compiler tool
suite, you'll need to download, patch, and build one of the standard
GCC/binutils distributions as described in the section "Building Your
Own Cross-Compiler" below.

Once you've installed the necessary cross-compiler tool suite, you can
configure, build, and optionally install VX32:

$ cd VXADIR
$ ./configure
$ make
$ make install


Using VX32
~~~~~~~~~~

The 'vxrun' utility, whose source code lives in the 'util' directory,
serves as a trivial sample application that uses the VX32 library to run
VX32 code in an isolated environment.  The vxrun environment only
provides applications with three "parent-calls" (system calls to the host
environment): read, write, and exit.  Programs that vxrun executes
therefore act as class Unix filters, taking input from stdin and producing
output on stdout and/or stderr, but they cannot open any other files or
otherwise affect the host environment.  For example:

$ echo 'main() { printf("Hello world!\n"); }' >hello.c
$ vx32-gcc hello.c
$ vxrun a.out

Other applications that utilize the VX32 library will probably want to
customize the extension environment with different or additional
parent-calls appropriate to the application and its security model.  More
documentation on how to do this will hopefully be written before long, but
for now the 'pcallhandler' code in util/vxrun.c should serve as a basic
example of how it's done.


Building Your Own Cross-Compiler
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you want or need to build your own cross-compiler tool suite for vx32
instead of using the binaries provided, then you will need to download,
patch, and compile GCC and GNU binutils as follows.  Note that if you don't
follow these instructions exactly, including using PRECISELY the specified
versions of GCC and binutils, then the process is likely to break somewhere
and you'll have to do a little manual tweaking.  Not necessarily difficult,
but annoying - so beware.

The 'vx32' target isn't yet integrated into the main GCC/binutils
distributions, but appropriate patches are supplied in the top-level
directory of the vx32 source tree for certain versions of GCC and binutils;
these instructions assume GCC 4.1.2 and binutils 2.17.  You only need the
smaller 'gcc-core' distribution to get the parts of GCC you need to build
vx32; if you get the full GCC distribution you'll need to configure it with
'--enable-languages=c' for now so that it only tries to build the C
compiler and runtime.  You can get the correct source trees from here:

$ wget ftp://ftp.gnu.org/gnu/gcc/gcc-4.1.2/gcc-core-4.1.2.tar.bz2
$ wget ftp://ftp.gnu.org/gnu/binutils/binutils-2.17.tar.bz2

To configure and install the cross-development tools in the default
location of /usr/local, for example...

First install binutils:

$ tar xvjf binutils-2.17.tar.bz2
$ cd binutils-2.17
$ patch -p1 <VXADIR/patch-binutils-2.17
$ ./configure --target=vx32
$ make
$ make install
$ cd ..

Then install GCC:

$ tar xvjf gcc-core-4.1.2.tar.bz2
$ cd gcc-4.1.2
$ patch -p1 <VXADIR/patch-gcc-4.1.2
$ ./configure --target=vx32 --enable-languages=c
$ make
$ make install
$ cd ../..

You should now be able to type 'vx32-gcc --help' for example.


Source Tree Overview
~~~~~~~~~~~~~~~~~~~~

(VX32 Library)
vx		Public header files for accessing the vx32 library
env		Host-independent library code for the vx32 environment
x86		Instruction scanning/translation for vx32-on-x86 execution
x86/32		Code specific to x86-32 platforms
x86/64		Code specific to x86-64 platforms
interp		Slow but portable instruction interpeter (not yet working)
ppc		Binary translator for vx32-on-PowerPC (not yet working)

(VX32 runtime environment)
cinc		C/POSIX includes for the minimal VX32 runtime environment
clib		Minimal C and math library for VX32 environment

(Miscellaneous)
util		VX32-related utility programs (e.g., 'vxrun')
test		Test/benchmarking code for the VX32 environment

(Documentation)
doc/vx32	Draft specification for the vx32 environment architecture


License
~~~~~~~

I'm initially releasing VX32 under the GNU General Public License, at least
until I decide what kind of license I really want to release it under.  I
will probably liberalize the license in the future; please contact me if
you want to use VX32 but have problems with the license.

Substantial parts of VX32's minimal C library is based on the FreeBSD C
library and Sun's math library, which carry different open-source
copyrights as indicated in the appropriate source files.


Version History
~~~~~~~~~~~~~~~

0.01	21-Dec-05	Initial experimental public release


Contact Info
~~~~~~~~~~~~

Bryan Ford
Computer Science and Artificial Intelligence Laboratory
Massachusetts Institute of Technology
baford@mit.edu

VX32 home page: http://pdos.csail.mit.edu/~baford/vxa/