What is govm?
======================================================================
govm is an experimental/educational VM + compiler.

I've written a small bytecode interpreter along with a custom bytecode
for CIPHER 5 [1], originally based on an idea by Sascha Müller, who
also wrote a little assembler for his vm, which I extended.

When I tried to write bytecode with his assembler, I had to repeat the
same instruction sequences over and over again. Because I hate to
repeat myself more often than never, I decided I need to write a
compiler.

The idea of using the VM in a Capture the Flag contest was to force
teams to write their own shellcode, to write their own buffer overflow
protection, and to write their own disassembler. Thus, teams who
cannot afford a commercial disassembler (or who are unwilling to buy
one) are not at a disadvantage.

The VM supports execution of arbitrary bytecode on its stack, provided
the originally executed bytecode is vulnerable to stack overflows.

The VM is written in C; the current version is implemented as a python
module. It supports three syscalls: getc, putc and halt. getc and putc
are redirected to python functions to allow for easy integration.


COMPILING
======================================================================
You need:

For compiling the compiler:
    sun java 1.5 sdk or later.

For compiling the VM:
    python2.5, and python2.5 headers

Simply issue 'make' to make both. The compiler will be stored in the
project's root dir as govmc.jar. The VM can be invoked by doing
    cd pygovm && python rungovm.py $(BYTECODE)

Some examples can be found in the examples/ directory.

USAGE
======================================================================
The compiler is invoked like this:
    java -jar govmc.jar $INPUT $OUTPUT

For a short language description, do
    man ./govmc.1

If invoked without arguments, the compiler is started up as a network
service and can then subsequently be used over the net by doing:
    python cwrapper.py $INPUT $OUTPUT $HOST

Check the pygovm/ subdirectory for the government vm, which interprets
the generated bytecode.

Why the government compiler? Because it is the reference
implementation of the government bytecode, to be run on the government
vm (govm). Why? Because it was originally written for CIPHER 5, and
CIPHER 5's theme was "corrupt government". And a corrupt government
needs its own vm.


DOCUMENTATION
======================================================================
The original man page for the compiler is included. It can be a little
confusing because the manpage is written with the assumption that the
compiler is used over a web interface.

QUESTIONS
======================================================================
hc-govm@hcesperer.org