HVX: HERBIVORE-EXTENSIONS 
=========================

A proposal for Herbivore Extensions.
By Philip Hunt, last altered 27-Nov-2001


Abstract
~~~~~~~~

HVX is a protocol for sending encrypted remote procedure calls
over the Herbivore protocol. HVX also specifies how HVX-handlers
are written in Herbrip (the reference implementation of
Herbivore).


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

Herbivore is a format for encrypted email. Of course, email
can carry any information, for example HTTP requests and
responses, or remote procedure calls (RPCs) in protocols such
as SOAP.

Why would anyone want to send this data as email and not using
the native protocols available? There are two reasons:

(1) Herbivore encrypts the data, so it might be an attractive
alternative to inventing an encrypted version of another
protocol.

(2) An adversary would see it as email, and not as the underlying
protocol, thus preventing the adversary from using traffic
analysis to find out about the user.

(Of course, there are disadvantages too; wrapping the protocol
in Herbivore might be too inefficient. Implementors will have
to decide what's practical for them.)

Given that using Herbivore as a wrapper for another protocol
may be useful, Herbivore Extensions (from now on "HVX") are
a way of making such wrappers easier to write.


How HVX works
~~~~~~~~~~~~~

At the sender's end, the mail message must contain the following
encrypted header:

   X-Hvx-Function: <module>.<function>
   
Where <module> and <function> are valid Python identifiers.
Note that the header name ("X-Hvx-Function") isn't case
sensitive but the value of the header is. This is because
RFC2822 headers aren't case sensitive, but Python identifiers
are.
   
Other HVX headers are optional, and of the form:

   X-Hvx-Para-<n>: <value>
   
Here, <n> is an integer from 1 upwards. <value> is a string.

At the reciever's end, there should be a hvx/ directory under
the main Herbrip directory. In this dorectory with be python
module files. When the HVX-enabled email is read in the function
<function> in the module hvx/<module>.py will be executed,
with the parameters specified in the X-Hvx-Para-<n>: headers.
(There may well be other parameters giving details of the
Herbrip environment, such as a mailheader. Mail object containing
the received email).


Executing this function (depending on what action the function
specifies) may well cause other emails to be sent, especially
back to the sender of the original email.


Example: http over Herbivore
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In this example, a user views websites using a web browser.
When the user clicks on the URL <http://www.python.org/>, the
browser sends an http GET request to the Internet. Software on
the user's machine intercepts this request and turns it into an
HVX-format email.

The email goes to a Herbivore-http server, and contains these
headers:

   X-Hvx-Function: httpserver.get
   X-Hvx-Para-1: http://www.python.org/

At the recieving end, there is a Python module with the filename
hvx/httpserver.py. It has a function get(). The Herbrip system
at the receiving end reads the HVX headers and executes this
function, with the parameter "http://www.python.org/". 

The get() function uses the functions in the standard Python
library to get the web page for the URL in the parameter. This
web page is then sent back to the sender of the original email.

It is sent back as an HVX message, with the headers:

   X-Hvx-Function: httpclient.data
   X-Hvx-Para-1: http://www.python.org/

The body of the message contains the actual web page received.

At the reciving end, there is an HVX module httpclient.py. The
data() function of this module is called, which gets the web page
to the web browser.


The hvx module
~~~~~~~~~~~~~~

As well as a module for each separate HVX, there is one module to
support HVXs in general. Its methods include:

   hvx.sendHvx(recipient, hvxModule, hvxFunction, *parameters)

Which (obviously) sends an HVX mail.


HVXs that come with Herbrip
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Sometimes a Herbrip system will want to know the public key of
another Herbrip system. This will be implemented by a HVX. The
first system will send a mail with the encrypted header:

   X-Hvx-Function: ping.getPublicKey

And the response will be a mail with the public key in the mail
header. The response will have in the encrypted header:

   X-Hvx-Function: ping.ignoreMe

Which means the message will by default not be shown to the user
(though the user can override this behaviour if desired).

The "ping" HVX will come with the Herbrip distribution, and as
well as containing useful functionality will act as an example of
how to write HVXs.


Perhaps also there could be a HVX that performs ftp-like
functionality, "file transfer over Herbivore". There would be two
calls: 

   X-Hvx-Function: getfiles.getFile 
   X-Hvx-Para-1: pathname-of-file

and:

   X-Hvx-Function: getfiles.listFiles
   X-Hvx-Para-1: directory-to-list   

The returns for these would be, respectively:

   X-Hvx-Function: getfiles.receiveFile
   X-Hvx-Para-1: pathname-of-file
   <body contains file>

and:

   X-Hvx-Function: getfiles.receiveFileList
   X-Hvx-Para-1: directory-to-list
   <body contains list of files and subdirectories in
   that directory>


Unresolved Issues
~~~~~~~~~~~~~~~~~

How are escape-sequences and characters encoded when sent in
X-Hvx-Para-<n>: headers? This needs to be defined.


Maybe it would be nice in a future version of HVX to have a
mechanism for getting the return value of a function call back to
the original sender. Possibly this could be done by having an ID
in the original call:

   X-Hvx-Call-Id: 2305
    
And in the return, match the same ID:

   X-Hvx-Return-Id: 2305
   X-Hvx-Return-Value: true
       
Or maybe this would be an unnecessary complication.       
       



;end.

