path: root/README

   ffff  
  ff    firma -  
  ffff  encrypted mailing list manager
  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 - Caveats
 9 - Contact

The concept
-----------

 In portuguese, "firma" means for signature, signature and trust checking and
 is a slang for strength and enterprise.

 All this together just can be one thing: an encrypted mailing list manager :P

 In the streets, the expression "a firma cai mas nao quebra" (the enterprise
 falls but does not breaks) is commonly used to talk about the strength of a
 group that operates in secrecy. To our list manager, this concept says that
 your encrypted mailing list can stops to work -- if the server goes offline
 or abducted by aliens -- but the system can never be broken. With firma, we
 are trying to follow this philosophy.

 Firma is based on the gpgmailalias.pl perl script, hosted at
 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 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 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
 in all steps of the process.

Everyone has the private key X The server has the private key
-------------------------------------------------------------

 When using a encrypted mailing list software, one must choose between
 keeping the private key in the server or send it to each of the
 subscribers. We'll not consider the case where every subscribers encrypt
 the message to all recipients cause this has none automation in the
 process we are looking for.

 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 decentralized vulnerability.

 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 compromised.

 These two approaches has a similar 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 decentralized 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.

  3 - use a public-key and all info stored onto it as the subscriber info.

Why Bash
--------

 You may ask why we choose bash. Its really strange a crypto project using
 shell scripting language. But bash has many advantages:

 - Bash is found in almost all unix-like systems

 - Small dependencies: firma needs just tools like sed, awk, grep, cut and
   gpg itself. Look at the file "GUIDELINES" to see a complete list of all
   unix commands needed to run firma.

 - You can easily put all the tools, scripts and config files in a read-only
   media to protect against cracks such as rootkits.

 - Keeping your encrypted list manager out from a huge and sometimes bugged
   mail software prevents insecure use of your mailing list by an excess of
   unwanted functions and routines.

 - Firma has a total KISS design, and bash helps to keep it simple.

 - Firma adopted the style suggested 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
-----

 Note for Debian users: you'll need the packages "metamail" and "expect" to
 run firma.

 Firma installation is quite simple:

 1 - Create a folder to store lists; by default firma use /usr/local/etc/lists
     but you can use anything, just edit firma and change FIRMA_LIST_PATH
     variable.
 
 2 - Copy firma script to whatever you like, e.g. /usr/local/bin and check that
     it has no write permission 

 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 those 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. If you run postfix, the user is specified by the
     main.cf parameter "default_privs".

     We suggest you to use

       MAIL_AGENT=/usr/sbin/sendmail
       MAIL_AGENT_ARGS=-t

     As optional parameters, you can also set

       USER= user that runs firma (usually the same as your MTA user);
             defaults to "nobody"; you can also specify this parameter
             in each mailing list config file if you plan to have one
             user per mailing list

       GROUP= group that runs firma (usually the same as your MTA group);
              defaults to "nogroup"; you can also specify this parameter
              in each mailing list config file if you plan to have one
              group per mailing list

       LOG_TO_SYSLOG= set to "1" to log errors and warnings to syslog, else firma
                      will print errors to STDERR

       LOGGER_BINARY= if logging to syslog, set the path to logger's binary

       SYSLOG_PRIORITY= if logging to syslog, set a priority for the error messages
                        (defaults to "user.err")

       USE_GPG_HIDDEN_RECIPIENT_OPTION= set to '1' to use GnuPG's --hidden-recipient
                                        option, available from version 1.4.0 onwards
                                        (try 'man gpg' for more information)

       REMOVE_THESE_HEADERS_ON_ALL_LISTS= headers that should be stripped from list
                                          messages on all lists running under firma
                                          (space separated case-insensitive entries)
                                          (may include regexps (e.g., X-.*)

       KEYSERVER= default keyserver to import/export keys
                  (defaults to keyserver.noreply.org)

     For a list of all config parameters, type

       firma --help config

 4 - Then create your lists with the command

       firma -c your-list

     Then firma will ask some questions and create a gpg keyring and a config
     file with the following variables:

       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 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.

     After that you can add some optional parameters on this list config file:

       SUBJECT_PREFIX= prefix to be included in the subject of list messages

       REMOVE_THESE_HEADERS= headers that should be stripped from list messages
                             (space separated case-insensitive entries)
                             (may include regexps (e.g., X-.*)

       REPLIES_SHOULD_GO_TO_LIST= set to '1' to add a Reply-To header containing the
                                  list address

       SILENTLY_DISCARD_INVALID_MESSAGES= set to '1' to silently discard invalid
                                          messages (message not signed/encrypted,
                                          sender not subscribed to the list, etc.)
                                          instead of sending bounces back to sender

       KEYSERVER= default keyserver to import/export keys
                  (defaults to keyserver.noreply.org)

       REQUIRE_SIGNATURE= wheter messages sent to the list should be (yes) or dont
                          need to be signed to be processed (no); defaults to yes;
                          this doesnt affect the way email administration works,
                          when signature is mandatory

     For a list of all config parameters, type

       firma --help config

 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"
       your-list-request: "| /usr/local/bin/firma -e your-list"

     and then run the command

       newaliases

     alternatively, you can use a virtual mailbox table if you want
     to easily host a lot of encrypted mailing lists.

 6 - Admin tasks are performed through aliases like 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)

       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
----

 - Use an encrypted swap memory
 - Use a read-only media to store firma and its needed apps
 - Use ramdisk to FIRMA_LIST_PATH so all keys and passwords vanishes if the server friezes
 - Use a big PASSPHRASE, 25+ chars with alpha-numeric and special ascii keys

Design and features
-------------------

 Firma is simple but its simplicity doesn't reflect in lack of design.

 - Uses a gpg keyring to store both the keys and the subscribers options
 
 - Command line is simple to avoid admin tasks resting in some .bash_history

 - Non-pgp blocks in a message are discarded since we don't want to deal with
   unencrypted content

 - All unwanted email headers are striped as a privacy measure for who sends
   the message

 - Firma doesn't use any disk write when processing a message; no temp files
   that may rest in the system; everything goes in memory (but take care, 
   sometimes it will use the swap and then is best to make it encrypted) 

 - By default it doesn't archive messages in the server

 - 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 
  
 Major features are:

 - Keyring support

 - Administration through email or command-line

8 - Caveats

 People that uses Sylpheed should config the list to accept messages that
 arent signed. Thats because currently firma depends that the encrypted
 and signed parts come in the same PGP block and Sylpheed splits the
 encrypted message and the signature in two separate blocks. Thats a
 firma and not Sylpheed issue. The PGP/MIME spec allows one to send
 the PGP/MIME encrypted message in two separate blocks. We hope to fix
 this soon :)

9 - Contact

 Contact: firma (@) sarava.org

 Messages should be encrypted with the list pubkey 0xD68AFEDC found
 at keyserver.noreply.org.