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

By Philip Hunt, last altered 28-Jan-2002.
For herbrip version 0.4.0

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.

Full installation instructions are in the file doc/INSTALL


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

Herbrip normally rund in the background without the user being aware 
of it. But you can run it manually from the command line, as well.
This section explains how to do this.


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

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 the --out command only deals with mail sent to
one recipient address; to send a message with more than one 
recipient, multiple output emails are sent, and each email must
be dealt with separately; this is what --outd does, where the
destination of the meails is determined by the 'dest' config
variable. The file doc/NOTES-0.3.2 contains a fuller discussion of
how 'dest' works.

(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/INSTALL - installing Herbrip
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
test/perftest.py - a performance test


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.
