GPGMail 0.5.2 (Nov 22nd 2001)
=============================

What is it?
-----------
GPGMail is a plug-in for Mail.app (on MacOS X) and MailViewer.app (on 
MacOS X Server 1.x), providing a front-end to gpg for some operations.

GPGMail extends Apple's Mail/MailViewer application and allows you to
read and send PGP authenticated and/or encrypted messages. You can use
GPGMail for plain and MIME messages, following RFC 3156.

GPGMail does not contain any encryption code: it is a client to gpg
executable.

GPGMail is a complete hack, relying on Mail/MailViewer private internal
API. Use it at your own risks!


Requirements
------------
You need either MacOS X 10.1.x or MacOS X Server 1.x; GPGMail will not
work as-is on other OS versions, because the internals of Mail.app
changes on every revision...

For MacOS X, you can use MacGPG (http://macgpg.sourceforge.net/)
distribution, available at this address:
http://ftp1.sourceforge.net/macgpg/ezgpg1.0.6r3.tar.gz

You absolutely need a gpg version >= 1.0.6.
For MacOS X Server 1.x, you need to compile and install gnupg 1.0.6
(the version I tested) with egd.pl 0.8, modified by some patches. Read
GPGInstall.txt file (coming with GPGMail distribution).

gpg executable is expected to be located in /usr/local/bin/.
On MacOS X Server 1.x, egd.pl executable is expected to be located in
/usr/local/bin/, and entropy in ~/.gnupg/entropy.
The locations can be modified using user defaults; see
GPGMailBundle.defaults file.


Installation
------------
On MacOS X:
- Quit Mail.app
- Download and install gpg
- Create a PGP key (see gpg documentation)
- Copy GPGMail.mailbundle into ~/Library/Mail/Bundles/
- NEW: In a terminal, write:
  defaults write com.apple.mail EnableBundles YES
- Restart Mail.app

On MacOS X Server 1.x:
- Quit MailViewer.app
- Compile and install gpg and egd.pl (read GPGInstall.txt)
- Unarchive downloaded files using the excellent OpenUp.app, or type
  gnutar -xzf filename in a terminal.
- Copy GPGMail.mailbundle into ~/Library/MailViewer/
- Restart MailViewer.app


Features
--------
Once started, Mail.app has a new submenu, PGP, in its Message menu,
containing 4 items:
- Decrypt
- Authenticate
- Encrypt New Message
- Sign New Message

Mail.app also has a new Preferences panel in which you can set:
- your PGP Identity (aka userID)
- some other options like auto-decryption, auto-authentication,
  passphrase caching, etc.

In the Compose window, you can also add two toolbar items (by 
customizing the toolbar, on MacOS X), or display two popup buttons
(on MacOS X Server 1.x), to set the encryption (on/off) and add or not
your PGP signature; you can also use menu items
<PGP/Encrypt New Message> and <PGP/Sign New Message>. When you compose
a new message, you can sign it (you will be asked for your identity
passphrase), and/or you can encrypt it.
When you browse through message, GPGMail can operate automatically, or
on-demand. In automatic mode, it tries to authenticate or decrypt the
currently selected message; in manuel mode, you click on a button/menu
to decrypt or authenticate the currently selected message.

Encryption/decryption of plain text and OpenPGP-MIME messages works.
Note that there is a hidden userDefault, GPGEncryptsToSelf, which
allows you to not encrypt messages with your key: by default it is set
to YES, allowing you to re-read encrypted sent messages.

If you allow passphrase caching, passphrase is stored in cache during
a small amount of time: if it has not been used during this time, cache
is cleared.

On MacOS X Server 1.x, GPGMail.mailbundle automatically launches egd.pl,
the Entropy Gathering Daemon needed by gpg. On MacOS X, gpg does not
need egd.pl and uses /dev/random.


Current limitations
-------------------
- GPGMail accepts only one personal PGP key. 
- GPGMail always uses your default identity and all message receivers
  addresses as recipients for encryption (To and CC).
  For security considerations, BCC recipients are not - yet - taken in
  account). 
- GPGMail does not support PGP keys distribution (following RFC 3156) 
- GPGMail does not support S/MIME 
- GPGMail encrypts/signs the whole message, and can decrypt/verify only
  the whole message. You can not choose which part you want to encrypt. 
- GPGMail does not support for RFC1847 encapsulation.
- Encryption operation cannot be interrupted.
- You cannot send encrypted messages with BCC recipients yet. 
- You cannot forward encrypted messages: encrypted message is used. You
  need to copy decrypted message into new message.


Known bugs
----------
- Decryption fails if message was also signed and signer key is not
  available.
- Toolbar buttons are sometimes duplicated, when you have multiple
  viewers.
- Toolbar buttons are sometimes lost or moved.
- When customizing Compose toolbar, toolbar button states are not
  up-to-date.
- (MacOS X Server 1.x only) GPGMail fails to decrypt twice in-a-row the
  same MIME message. 
- In some circumstances, GPGMail is unable to decrypt MIME messages if
  your secret keyring contains more than one key. 
- Appearance of encrypted mail attachments changes over time.
- Annoying logs in console about toolbar items


Future developments
-------------------
- Add contextual menu
- Use a sheet when asking for passphrase
- Add full compliance with RFC 3156 
- Better filtering of gpg error messages by using GPGME
- Add support for multiple PGP identities 
- Allow recipients choice 
- Use KeyChain Manager (MacOS X only) 
- Customize display of signed/encrypted message 
- Add support for BCC recipients 
- Add support for partial encryption/signature (not the whole message) 
- Full multithreading of encryption/decryption 
- Add support for S/MIME 
- Localize it in different languages (any volunteer?) 
- Allow decrypted message forwarding
- Allow import/export of PGP keys
- [ADD YOUR REQUIREMENTS HERE]


Feedback
--------
As usual, I welcome feedback on this piece of code.
If you have bug reports, suggestions or, even better, patches for
GPGMail, please send an email to gpgmail@sente.ch


Thanks
------
Thanks to Christian for the first port to MacOS X.
Thanks to beta-testers! Dirk, Stefan, Andrew, Carl & Carl, Noah, Peter,
Dave, J.-L., TM, Graham, Markus.


History
-------
0.5.2 (v13)	Nov 22 2001	Port to MacOS X 10.1.x
                        Corrected bugs with character sets
                        Added keyboard shortcuts
                        (No release for MacOS X Server 1.x)
0.5.1 (v8)	Sep  8 2001	Port to MacOS X 10.0.x
                        Corrected bugs in the application of RFC 3156.
                        Corrected lots of other bugs...
0.5	(v4)	Feb  7 2001	First public release
                        (MacOS X Server 1.x and MacOS X Public Beta)


Stephane Corthesy
gpgmail@sente.ch


****************************
* COPYRIGHT and DISCLAIMER *
****************************

GPGMail is copyright 2000-2001 Stephane Corthesy. I reserve all
rights to this piece of software. I take no responsibility for any
damage this software, through omission or error, causes. This software
is provided as is and with no warranty.
Read also LICENSE.txt file.

"PGP" and "Pretty Good Privacy" are registered trademarks of Network
Associates, Inc.
