README file for herbrip
=======================

By Philip Hunt, last altered 14-Jan-2002.
For herbrip version 0.3.1

Herbrip: Herbivore Reference Implementation in Python

What's Herbivore?
-----------------

It's an initiative for strong, public key, effort-free encryption
of email. Here's an example, to illustrate how Herbivore will work:

   Alice and Bob both use herbivore-compliant MUAs. 
   Alice sends a message to Bob (it's the first time they've 
   emailed each other). The message is send as plain text, but 
   the herbivore subsystem inserts some extra headers, 
   which say that Alice's MUA is herbivore-aware, and 
   what Alice's public key is. 

   Bob's MUA reads the email. The Herbivore subsystem in the MUA 
   notes that Alice's email is came from a Herbivore-aware client, 
   and remembers Alice's public key. 

   Bob decides to reply to Alice's message. He composes his reply
   as normal, and presses SEND. The Herbivore subsystem in Bob's 
   MUA automatically encrypts the email with Alice's public key, 
   before sending it to her. 

   When Alice's MUA receives the message, it is automatically 
   decoded (using Alice's private key). Alice then sees on her 
   screen the message that Bob sent her. 


So, how does Herbrip fit in?
----------------------------

Herbrip is a command-line tool that processes email in ways
appropriate for Herbivore. Note that Herbrip is not a full MUA
(i.e. email client); it is designed to be usable by an MUA to
provide a security solution (just as an MUA might today invoke
PGP or GnuPG to perform encryption).


Getting Herbrip up and running
------------------------------

You must have Python 2.0 or later and OpenSSL.
Herbrip is known to work with OpenSSL 0.9.6 and 0.9.6a.
Herbrip assumes the ``openssl'' executable is in your path; if
it isn't you must put it their, or adjust the value of the
OPENSSL_CL constant in encwrap.py.

If you download and compile OpenSSL yourself, use the default
values for compilation.

You can verify that you've set up Herbrip correctly by running
``python test_herbrip.py''. This will run some tests, and give
a commentary as it runs. It should end with a line similar to:

   ***** Test completed successfully! *****


To use Herbrip
--------------

Herbrip is, at thev moment an experimental project. It does 
encryption and decryption correctly, but it doesn't contain hooks
to connect it up to popular email clients (that will be the main 
focus of future releases). The following shows how herbrip can be
used from the command line:


(1) to set it up:
       herbrip --init

This will create a ~/.herbivore directory to store information
that Herbrip will use on subsequent invokations. it will also
create your Herbivore public/private keypair.

(2) to process outgoing email:
       herbrip --out mailo mailo_p
       
This takes as input a file <mailo> which must contain an email
message (including header and body) that you intend to send to
someone. Herbrip adds headers stating your herbivore public key.
If herbrip has a public key for the recipient of the message,
the message is encrypted with that key. The resulting output
is written to <mailo_p>.

Note that, for now, Herbrip can only deal with mail sent to
one recipient address; future versions will allow mail to be
sent to multiple addresses.

(3) to process incoming email:
       herbrip --in maili maili_p
       
This reads <maili> which must contain an incoming email that
you have received. The resulting output email is written to 
<maili_p>.      
Herbrip does two things: firstly it reads the sender's herbivore       
public key (if there is one) and adds it to Herbrip's database.
Secondly, if the mail is encrypted, Herbrip attempts to decrypt
it using your public key.

If you run herbrip without any parameters, you get usage
information.


Important files and directories in this distribution
----------------------------------------------------

README - the file you are now reading!
COPYING - the GNU General Public Licence; you may use Herbrip under
   the terms of this licence.

doc/ - documentation directory
doc/CHANGES - log of changes
doc/TODO - list of future additions to the software
doc/HVX - information about Herbivore Extensions, a way of 
   encapsulating remote procedure calls in encrypted email.

src/ - contains herbrip source code
src/herbrip - the main executable

test/ - programs to test herbrip
test/test_herbrip.py - a regression test program

testmp/ - temporary directory which may in future be used by the 
   test programs


Other information
-----------------

Herbrip's home page is 
<http://www.vision25.demon.co.uk/oss/herbivore/herbrip.html>

Information on Herbivore is at
<http://www.vision25.demon.co.uk/oss/herbivore/intro.html>

Information about OpenSSL is at
<http://www.openssl.org/>

I can be contacted at <philh@comuno.freeserve.co.uk>


end.
