update for 0.2.5 release

1 files changed, 116 insertions, 25 deletions

diff --git a/README b/README
index 1ba80f4..caf1e7c 100755
--- a/README
+++ b/README
@@ -5,6 +5,18 @@
   ff    - a firma cai mas nao quebra 
   ff    
 
+Index
+-----
+
+ 1 - The concept
+ 2 - Everyone has the private key X The server has the private key
+ 3 - Why bash
+ 4 - Development Guidelines
+ 5 - Setup
+ 6 - Tips
+ 7 - Design and features
+ 8 - Contact
+
 The concept
 -----------
 
@@ -24,12 +36,12 @@ The concept
  http://www.rediris.es/app/pgplist/index.en.html, but completely rewritten
  in bash.
 
- Firma works as a command line and MTA pipe alias tool that receives a
- email message in its input, grab the encrypted and signed message and
- re-encrypt and send it to each subscriber.
+ Firma works as a command line and MTA pipe alias tool that receives an
+ email message in its input, grab the encrypted/signed message, re-encrypt
+ and send it to each subscriber.
 
  In the server you just need the script, a keyring with the list keypair
- and a config file. When mail arrives, it is redirected by the MTA to the
+ and two config files. When mail arrives, it is redirected by the MTA to the
  script and it process the message if its properly encrypted and signed.
  No temporary files are written during a message processing and no default
  message archive, so no messages -- encrypted or not -- rest on your system
@@ -44,18 +56,42 @@ Everyone has the private key X The server has the private key
  the message to all recipients cause this has none automation in the
  process we are looking for.
 
- For the second option we have the NAH6 Mailman patch,
- http://mail.python.org/pipermail/mailman-coders/2003-June/000506.html
-
  For the first we have GPG Mailman,
  http://medien.informatik.uni-ulm.de/~stefan/gpg-mailman.xhtml
 
+ and Crypt-ML, http://www.synacklabs.net/projects/crypt-ml/
+
+ For the second option we have the NAH6 Mailman patch,
+ http://mail.python.org/pipermail/mailman-coders/2003-June/000506.html
+
+ For the firsts releases of Firma, we choose to use just the first option.
+ In the future the code should contain support for an one-keypair list,
+ but this is not the main behavior we want in an encrypted mailing list.
  This is a question of centralized versus descentralized vulnerability.
 
- - descentralized means just an alias for incoming encrypted email
+ An one-keypair list is more or less just like a mail alias: someone
+ send an encrypted email to the list address and the manager just forwards
+ that encrypted email to the lists subscribers, optionally removing some
+ headers and performing some security auditing. Every user has the list
+ private key, so if someone lost it to the world then one must regenerate
+ a keypair and send again to every subscriber.
+
+ In the case of a keypair stored in the server, where subscribers has just
+ the list pubkey, the list admin just need to remove the correspondent pubkey
+ from the list's keyring with in case some user has its keypair compromissed.
+
+ These two approaches has a similiar external hole of some private key turned
+ public. Designing Firma, we decided for the centralized model, for three main
+ reasons:
+
+  1 - a server can be safer than any user's ordinary computer.
+
+  2 - automation: when some user is removed from the list, we just remove their
+      key from the list keyring; in the descentralized approach, the list admin
+      needs to regenerate a new list keypair, otherwise the unsubscribed user
+      can still decrypt list messages if he can sniff the mail server traffic.
 
- - if some user has its keypair compromissed, the list admin just need
-   to remove the correspondent pubkey from the list's keyring
+  3 - use a public-key and all info stored onto it as the subscriber info.
 
 Why Bash
 --------
@@ -78,6 +114,17 @@ Why Bash
 
  - Firma has a total KISS design, and bash helps to keep it simple.
 
+ - Firma adopted the style sugested in the Advanced Bash-Scripting Guide,
+   http://www.tldp.org/LDP/abs/html/scrstyle.html
+
+Development Guidelines
+----------------------
+
+ As a security project we made a restricted set of guidelines / design policy,
+ attempting to get a clean, bug-free and high quality code. We choose a slow
+ development rather than sit-and-code. These rules are detailed in the file
+ GUIDELINES.
+
 Setup
 -----
 
@@ -90,26 +137,35 @@ Setup
  2 - copy firma script to whatever you like, eg. /usr/local/bin and check that
      it has no write permission 
 
- 3 - then create your lists with the command
+ 3 - create a list-wide config file (default is /usr/local/etc/firma.conf) with
+     the common definitions for all lists,
+
+       GPG_BINARY= path to the gnupg binary
+       MAIL_AGENT= path to the mail transport agent to be used (e.g., sendmail)
+       MAIL_AGENT_ARGS= command-line arguments to be passed to the command above
+       LISTS_DIR= path to the mailing lists directory
+
+      all thos variables can be overwritten at each list's own config file;
+      firma.conf should be chmoded as 600, chowned nobody.nobdy or whatever
+      user your MTA runs.
+
+ 4 - then create your lists with the command
 
        firma -c your-list
 
      this will ask some questions and create a gpg keyring and a config file
      with the following variables:
 
-       MAIL= path for sendmail or any smtp wrapper (eg, /usr/lib/sendmail)
-       MAIL_ARGS= command line arguments to the smtp wrapper
-       GPG= path for gnupg binary (eg, /usr/bin/gpg)
-       LISTNAME= list email (eg, firma@domain.tld)
-       LISTADMIN= list administrator email addresses (space separated)
-       GPGDIR= gpg dir for the lists' keyring
-       PASSWD= passwd for the lists' keyring
+       LIST_ADDRESS= list's email address
+       LIST_ADMIN= list's administrators email addresses (space separated)
+       LIST_HOMEDIR= list's gnupg homedir, where the list's keyrings are located
+       PASSPHRASE= passphrase for the list's private keyring
 
-     then a gpg keypair and a config file are created. the owner of the config
-     file and keyring should be nobody.nobody (or the user your MTA run as) and its
-     permissions must be 600.
+     then a gpg keypair and a config file are automatically generated;
+     the owner of the config file and keyring should be nobody.nobody
+     (or the user your MTA run as) and its permissions must be 600.
 
- 4 - create an alias to the list at your MTA; on sendmail or postfix,
+ 5 - create an alias to the list at your MTA; on sendmail or postfix,
      add this to your aliases file:
 
        your-list: "| /usr/local/bin/firma -p your-list"
@@ -119,9 +175,39 @@ Setup
 
        newaliases
 
- 5 - to subscribe the users and the list admins on the list, use ...
+     alternativelly, you can use a virtual ...
+
+ 6 - admin tasks are performed through your-list-request@yourmachine or
+     via command-line:
+
+       firma -a your-list
+
+     inside this command or encrypted in your mailing list request, use the
+     following commands:
+
+       sub keyserver|keyfile key-id
+
+         subscribe key-id pubkey from file or keyserver (currently not
+         implemented)
+
+       unsub email-address
+
+          unsubscribe all keys with email-address IDs (currently not
+          implemented)
 
- 6 - send encrypted AND signed messages to your-list@yourmachine and look
+       use email-address    
+
+          uses the given address for message delivery instead
+          of the primary address of a subscribed key
+
+ 7 - to subscribe and unsubscribe manually the users and the list admins on, use
+     a command line like
+
+       gpg --homedir [path-to-your-list-keyring] --import < file
+
+     and be sure that after this command the list keyring is owned by nobody.nobody.
+
+ 8 - send encrypted AND signed messages to your-list@yourmachine and look
      what happens :)
 
 Tips
@@ -153,7 +239,7 @@ Design and features
 
  - by default it doesn't archive messages in the server
 
- - by default it remove the Subject header and put it inside the encrypted
+ - by default it removes the Subject header and put it inside the encrypted
    message, as Subject are outside the PGP/MIME context
 
  - messages appear to be sent To: Undisclosed Recipients 
@@ -163,3 +249,8 @@ Design and features
  - keyring support
 
  - administration through email or command-line
+
+8 - Contact
+
+ Contact: firma (@) sarava.org
+