\section{User Interfaces}
\label{sec:design-ui}

\subsection{Design}

\footnote{This section was originally drafted by Todd Kamin.}
Interacting with the core Free Haven process, the user interface has
three substantial goals: to provide users with the ability to
anonymously insert documents into the Free Haven system, to provide
users with the ability to anonymously retrieve documents from the Free
Haven system, and to allow internet-literate users to easily perform
these two operations.

Upon first inspection, the ability of the user interface to insert and
retrieve documents may appear to be a trivial extension of the core
trading protocols of Free Haven.  The challenges facing the insertion
and retrieval of files from the user interface perspective are
somewhat different from those facing the designers of the core
infrastructure, however.  The trading of shares in the servnet
requires a two-way transfer and assurance of success, but the user
interface -- servnet interaction is only concerned with the transfer
of documents in one direction.  The user interface must by definition,
however, provide sufficient anonymity to users of Free Haven.

In the case of retrieving a document from the servnet, a user needs
only the ability to make an adequate request
of one of the servnet nodes to find shares of the document: a request is
considered adequate if the user provides a hash of a public key of a document
that matches a hash stored in the system
In this request, the user also
provides the servnet with a reply address.  The servnet nodes with a
share of the document, theoretically, simply make a copy of the share
and send it off to the reply block included.  If the user has the
public key of the file, then the servnet assumes that the user's
request is valid.

Similarly, in order to insert a document into the network, the user
must only find a servnet node willing to accept his document shares.
One option is to have servnet nodes who are always willing to accept
new documents and publish them into the Free Haven system.  This
option is currently in use with {\tt http://freehaven.net} being the servnet
node willing to accept new documents.  Unfortunately, this option does
not provide the highest level of anonymity.  Another option would be
to simply query servnet nodes about their willingness to accept a
document.  This option would provide slight more anonymity at the
expensive of having to iterate through all of the known nodes.

For the first pass user interface, more consideration was given toward
creating an interface that was easy to use and relatively simple to
build than toward providing maximum anonymity.

\subsection{Implementation}
% \label{sec:impl-ui}

Currently, the Free Haven user interface must reside on a Free Haven
node.  The user interface consists of a perl script, called
{\tt handler.pl}, which is invoked through CGI.  An HTML document contains
the appropriate form syntax and information necessary to invoke the
user interface on a particular Free Haven node.  The remote execution
of the user interface perl script is made possible through a web
server that allows CGI execution.  The Free Haven node must be running
a web server configured to allow CGI requests in order for users to
access Free Haven.

The two necessary user interface operations are the ability to insert
a document into the Free Haven system and the ability to retrieve that
document from the system.  These two operations require completely
different actions to be taken, and thus are implemented somewhat
independently of each other.

\subsubsection{Inserting a Document}

In order to insert a document into the Free Haven system, a user first
brings up the appropriate form. An example form can be found at
{\tt http://web.mit.edu/www/tkamin/form.html}. Using the bottom of this
form, the user selects a document for upload.
Note that the current implementation only allows for insertion of text files into Free Haven.
The user also has the option of setting the time to expiration of the
document. (The default time to expiration is 4 weeks.) By
choosing the time to expiration of the document, the user is
given a promise that the document will not be deleted for that
amount of time.  Pressing the submit button causes the time to expiration
and the document to be delivered to the CGI program. The current version of
this CGI program can be found at {\tt http://freehaven.net/freehaven-cgi/handler.pl}. This
CGI program is a perl script running on a Free Haven node; it effectively
represents the ``user interface.''

With the information provided in this ``insert'' request, the user
interface perl script produces shares for insertion into Free Haven.
The user interface first proceeds to split the document using
Rabin's Information Dispersal Algorithm \cite{rabin-ida} into a specified number $n$
pieces with $k$ ($k < n$) being required to recreate the
document. The values of $k$ and $n$ are specified in the file
{\tt cgi.conf} and can be easily changed.  The user interface then
converts the output from the IDA program into
shares according to the ``composition of
shares'' specification.  The expiration date is determined by adding
the time to expiration and the current GMT time.  Once the share is
built up to the $</data>$ tag, the user interface uses the Simplified
Wrapper and Interface Generator (SWIG) \cite{swig} to invoke
a method in the cryptography module that provides a unique signature.
The user interface appends the signature and closes the share.  Each
share is placed in a separate file.

By making the assumption that {\tt handler.pl} will reside on a Free Haven
node, the user interface script is able to communicate with the haven
module through files placed in a prespecified directory.  The share files
built by the user interface contain sufficient information to be uploaded directly
into Free
Haven.  The user interface moves the files containing shares to the
preconfigured directory.  The haven process eventually (more precisely, each
time a trade is offered) comes along and
uploads these shares into the servnet.  Lastly, the user interface
returns to the user an HTML page containing the public key of the
document and the hash of the public key of the document. (For security
and anonymity purposes, we may wish to configure this script later to never
notify the user of the actual public key which was used to create his shares.)
The user will need to keep the hash of the public key of the document in order
to retrieve the document.

\subsubsection{Retrieving a Document}

The functionality for retrieving a document is provided through the
same form and perl script that is used for inserting a file.  The form
provides input fields for whatever information it may need to retrieve the
shares of a document and deliver them to the user. In particular, the
user must provide the hash of the
public key of the document, some remailer reply block, and optionally some
public key with which the shares can be encrypted.  This
information is then sent using {\tt post} to the user interface.

After receiving the public hash of the file and the remailer reply
block from the CGI request, the user interface script builds a message
for broadcast to all of the Free Haven servnet nodes.  This message
includes the hash of the public key of the document and requests that
all shares having matching hashes be sent to the reply block.  The
user interface arranges for the message to be sent to all the nodes
through the comm module.  The Free Haven nodes that have the requested
shares are encouraged, but not required, to send their shares to the
included reply block.  Because shares of the document (instead of the
document itself) are sent to the reply block, Free Haven will provide
a script for the user to recombine a document's shares.