<meta http-equiv="Content-Type" content="text/plain; charset=ansi">
<!--
  * $Id: README.txt,v 1.58 2004/01/06 19:26:33 brian Exp $
-->

Readme file for Squirrelmail GPG Plugin code

Last Minute Stuff
	The plugin has evolved significantly since it's last incarnation.
	
	We have changed the SM requirement to 1.4.2.  Most of the functionality still 
	works as far back as early versions of SM 1.2, but some of the newest 
	functionality for handling detached signatures and decrypting attachments
	depends on changes to the Message class and Deliver class that are dependent 
	on SM 1.4.2
	
	One of the biggest features in GPG Plugin v. 2.0 is complete support  
	for translation of the plugin.  The Plugin is shipping with complete 
	translations for Lithuanian, Italian, German, French, and Brazilian 
	Portuguese.  Our sincere thanks to the translators for the work involved 
	in translating something as complex as user documentation for encryption.
	If you are reading this and your native language is not English, we 
	would love to integrate support for your language into the next release.
	The gpg.pot file is in the locales directory.  Please contact the 
	GPG Plugin development team with any questions, and we will be happy to
	help you with the format and testing.
	
	There is a bug in SM's handling of multi-part MIME messages, which 
	affects our ability to do attachments with detached signatures.  
	The bug has been corrected in the SM core CVS, but if you want to use 
	this functionality, check out:
	http://www.braverock.com/bugzilla/show_bug.cgi?id=99
	for an updated version of the Deliver class that resolves this bug 
	(patch available there as well)

	The Plugin team would like to thank the Cryptorights Foundation for their 
	generous support. CRF has supported the development of the GPG Plugin, 
	and will be including the plugin in their upcoming HighFire Product.
	Please support a worthy cause: http://www.cryptorights.org/
	
New Features
	- Key Generation
 		We have enabled functionality to allow a user to generate 
 		a keypair on the server.
 		http://www.braverock.com/bugzilla/show_bug.cgi?id=14
 		
	- Encrypt&Sign Functionality
 	    	- added 'Encrypt & Sign Now' button
 	    	This functionality also works for encrypting attachments. (see below)
 	    	http://www.braverock.com/bugzilla/show_bug.cgi?id=11
 
	- Major improvements to Decrypted Message functionality
		Too numerous to list.  It probably suffices to say that you will
		be much happier with decryption support.  We have tried to make 
		the decrypted message view pretty seamless with SM's own 
		message viewing experience.
		http://www.braverock.com/bugzilla/show_bug.cgi?id=38
		http://www.braverock.com/bugzilla/show_bug.cgi?id=51
		http://www.braverock.com/bugzilla/show_bug.cgi?id=71
		http://www.braverock.com/bugzilla/show_bug.cgi?id=76
		http://www.braverock.com/bugzilla/show_bug.cgi?id=85
 		
	- Encrypt and Decrypt Attachments
		http://www.braverock.com/bugzilla/show_bug.cgi?id=12
		http://www.braverock.com/bugzilla/show_bug.cgi?id=56
		http://www.braverock.com/bugzilla/show_bug.cgi?id=74
		
	- Encrypt on Send, Sign on Send and Encrypt&Sign on Send
		http://www.braverock.com/bugzilla/show_bug.cgi?id=26
		Intertwined with Encryption of attachments, above.
		
 	- Keyring Management
 		- list keys on your keyring
 		- disable or remove keys from your keyring
 		- choose signing key and trusted key from consolidated interface
 		- view public key block on the screen
 		http://www.braverock.com/bugzilla/show_bug.cgi?id=27
 		http://www.braverock.com/bugzilla/show_bug.cgi?id=122
 		
 	- Import Keys from email
 		http://www.braverock.com/bugzilla/show_bug.cgi?id=46
 		
 	- Export Keys to email
 		http://www.braverock.com/bugzilla/show_bug.cgi?id=41
 		
	- Generated/Exported keys are PGP compatible 
		http://www.braverock.com/bugzilla/show_bug.cgi?id=54
		This is surprisingly difficult to do in gpg, and poorly 
		documented.  Now, all generated keys are DSA/ElGamal-E, 
		with TripleDES as the preferred cipher.  PGP likes these
		settings, and can import, encrypt to, sign with, 
		decrypt, and verify from these keys.  Finally.
		
	- Show strength of entered passphrase in key edit functions 
		http://www.braverock.com/bugzilla/show_bug.cgi?id=62
		
	- Add system defaults for key generation
		http://www.braverock.com/bugzilla/show_bug.cgi?id=61
		
	- Re-Enabled and Enhanced Shared System Keyring Functionality
		The shared keyring functionality is useful if your users 
		share a set of keys, as in a corporate environment.  
		The system has preferences for whether or not the 
		system keyring exists, where to find the keyring file, 
		and what key should be considered as a trusted key 
		for the shared system keyring.

		The user maintains ultimate control over whether to trust/use 
		the shared keyring at all.  The General Options page of 
		the GPG Plugin Options will display instructions for the 
		user indicating that the system administrator has enabled 
		the shared system keyring, and asking the user if they wish 
		to trust this keyring.  
		
		This option is only displayed if a shared keyring is present and enabled.
		http://www.braverock.com/bugzilla/show_bug.cgi?id=32
		http://www.braverock.com/bugzilla/show_bug.cgi?id=28

 	- Detached Signature Support
 		This feature allows the plugin to recognize and verify detached
 		signature files of mime type application/pgp-signature.
 		- requires SM with Message class (1.2.9? or higher)
 		- also verifies multipart/signed messages 
 		- detached signatures may take many forms, so if we missed one, 
 		  and you find a message that cannot be verified, please let us 
 		  know, so we can work with you to add support.
 		http://www.braverock.com/bugzilla/show_bug.cgi?id=33

	The usual Bug fixes and minor Enhancements
		Details available at http://www.braverock.com/bugzilla/

Installation

	See the file INSTALL.txt
	
	Upgrade instructions are also in the INSTALL.txt file.
	
Troubleshooting
	Forgive us if this isn't complete, we've made every attempt to list
	the most common problems and solutions. 
	
	This section is organized with the error you see on the screen at the
	beginning of each TroubleShooting section, and the workaround or other
	information indented under the applicable error message(s).
	
	We also welcome additions to this section.
	
	Most of the Troubleshooting information may be found in the section 
	called 'Troubleshooting' in the GPG Plugin Help from within the Squirrelmail 
	interface.
	
	I installed the Plugin, and it doesn't work!
	
		You will need to provide more information than this.
		
		First, check the "Tested On:" section, below, and see
		if your configuration looks like it should work (focus on
		PHP Version, SM version). 
		
		Often, installation problems have been resolved by upgrading SM, 
		PHP, Apache, etc.  There are good security and functionality reasons 
		to upgrade to more modern version in most cases as well.
		
		Next, take a look at the specific error messages the plugin is 
		giving you.  The development team has made an effort to provide error 
		messages that can assist you in diagnosing your problem.
		
		If you still can't figure it out, see the contact information below.
		If you write to the development team about a problem, please include
		as much information about your configuration and the exact error you 
		are receiving as possible.
	

About Keyservers, firewalls, and LDAP

        The GPG Plugin uses an HTTP interface to retrieve a list of keys 
        for import to the user's keyring.  Most of the Keyservers that offer an
        HTTP interface put it on port 11371.  If your Squirrelmail server is 
        behind a firewall or on an ipchains/iptables machine that blocks outgoing
        connections, you will need to open up connections from the server the gpg 
        plugin runs on to the keyservers that are defined in your config files.
        
        There are only three interfaces that we know of to a keyserver, the HTTP 
        interface currently used by the gpg plugin, the HKP interface, and an 
        LDAP interface.  We believe that it would be nice to support the LDAP 
        and HKP interfaces, and would welcome any code contributions that 
        implement such an interface for key lookup.  The HKP and LDAP interfaces
        will probably be supported via the --search-keys functionality, 
        although this is an interactive interface, and may not be suitable for
        use in the plugin.

About Decryption
	Once you have uploaded a secret key or keyring, the decryption part of the 
	plugin will be activated.  The plugin will try to automatically determine 
	when a message contains P/GPG encrypted content.  When the plugin detects 
	a message that appears to have encrypted content, the 'Decrypt Message Now'
	button will be displayed.  because of the complexity of this feature,
	it is possible that the plugin may not always correctly identify a message 
	that contains encrypted content.  Please report any unusual behavior,
	so that we can work with you to resolve your issue and patch the plugin.
	
Tested On:

	This plugin was developed on a Red Hat Linux 8.0 server, and tested with:

	Linux:
		Red Hat 7.0
		Red Hat 7.2
		Red Hat 7.3
		Red Hat 8.0
		Red Hat 9.0
		Debian - stable
		Debian - testing
		Trustix Secure Linux 1.5
		Gentoo Linux 1.4 (Intel and Sparc)
		
	Other:
		Windows 2000 (please contact the development team for help setting up Windows)
		Windows XP
		OpenBSD 3.3
		FreeBSD
		Solaris 8
		HPUX

	Squirrelmail versions:
		1.2.5 (requires small patch to SM)
		1.2.7 (requires small patch to SM)
		1.2.8
		1.2.9
		1.2.10
		1.2.11
		1.3.1
		1.3.2 Debian testing
		1.4.0rc2a
		1.4.0
		1.4.1
		1.4.2
		1.4.3 CVS (SM_Stable branch)
		1.5.0 dev (December 2003)
		
	GnuPG versions:
		1.0.6
		1.0.7
		1.2.0
		1.2.1
		1.2.2
		1.2.3

	PHP version:
		4.1.2
		4.2.0
		4.2.2
		4.2.3
		4.3.1
		4.3.3

	Apache:
		1.3.22 (security risk in most builds!)
		1.3.27
		2.0.40
	
	Browsers:
		Galeon 1.2.9
		IE 5/6
		Konqueror 3.0.x
		Mozilla 1.0.x - 1.4
		NS 6/7
		Opera 7.x
		Safari

	As you use this plugin successfully on other platforms, please let us know,
	both to satisfy our curiosity, and so that we may add it to this README for 
	future releases. 
	
	The list above was compiled from several reports over several versions of 
	the plugin and does not constitute an endorsement of any single platform 
	choice, or a guarantee that things will work in your environment.  
	The development team will be happy to help you work through compatibility 
	issues, after you have exhausted your own troubleshooting capacity.

CVS (source code) Access:

	Web browser access to the repository is available at:
	
	http://www.braverock.com/gpg/cvs/
	
	if you want the daily snapshot of our development code, it is rebuilt in 
	the wee hours of the morning and is available at:
	
	http://www.braverock.com/gpg/dailybuild/

	I've also configured anonymous cvs access to the cvs repository.

	You will need to set the CVS_RSH environment variable to 'ssh'.

	On unix, in  bash, you can do this by adding the following commands 
	to your .bashrc or .profile

	CVS_RSH=ssh
	export CVS_RSH

	In t/csh, you would use 'setenv CVS_RSH=ssh'

	Then, you can checkout the code using the following command 
	from the command line:

	cvs -d :ext:anoncvs@braverock.com:/cvs co gpg

	passwd:anoncvs

	Mac/WinCVS configuration should be similar.  Select SSH as the
	server type, instead of pserver.

Reporting Bugs

	We want to hear about your Bug Reports, Enhancement Requests, and Patches.
	
	Please submit bug reports at:
	http://www.braverock.com/bugzilla/index.cgi
	
	Please search the bug list for your bug before posting, 
	and add additional detail as appropriate.
	
	Enhancements should be marked with a severity of 'enhancement'.
	
	Please read the Bug writing guidelines at:
	http://www.mozilla.org/quality/bug-writing-guidelines.html
	for assistance in how to write a bug report that 
	will get the results you want.

Development Team
	List:		gpg@braverock.com
			(subscribe by sending a message to 
			 gpg-request@braverock.com with body 'subscribe')

	Team Lead:	Brian Peterson
			brian@braverock.com
	
	Coding/Testing:	Aaron Van Meerten (ke)
			Walter Torres
			Tyler Allison 
	   		Joel Mawhorter
	   		Joshua Vermette
	   		Kipp Spanbauer
	   		Ryan
	
	Design/Coding 
	Assistance:	John Nanninga (Design & Testing)
			Vinay
			Greg Winston
			Julian Dobson
			
	
<!--
  * $Log: README.txt,v $
  * Revision 1.58  2004/01/06 19:26:33  brian
  * - spell check
  * - update to reflect current
  *
  * Revision 1.57  2003/12/03 17:24:50  brian
  * - added to New Features section
  * - removed signing section as no longer relevant
  * - updated text throughout
  * - spell check
  *
  * Revision 1.56  2003/12/01 19:18:52  ke
  * -spelling correction
  * -added section on decrypting caching logic issue
  *
  * Revision 1.55  2003/11/22 15:30:49  brian
  * Moved all the INSTALL sections to file INSTALL
  * Bug 70
  *
  * Revision 1.54  2003/11/21 22:39:48  ke
  * -added text for new configuration options
  * -fixed small typo
  *
  * Revision 1.53  2003/10/31 14:00:16  brian
  * - Updates prior to Release Candidate
  * - reviewed new features to get things
  *   closer to reality, still work to do here.
  *
  * Revision 1.52  2003/09/30 12:03:15  brian
  * - updated to reflect current
  * - paid particulary attention to the 'New Features' section
  * - added link to the dailybuild to README
  *
  * Revision 1.51  2003/06/17 00:11:23  brian
  * - update to reflect current
  * - removed mcrypt section, as it is no longer relevant
  *
  * Revision 1.50  2003/06/12 21:07:35  brian
  * minor updates
  *
  * Revision 1.49  2003/05/09 15:29:28  brian
  * - Changed "last minute" section to "New Information"
  * - added all the new features since v1.1 to 'New uinformation"
  * - Added upgrade instructions to "Installation"
  * - added additional troubleshooting sections
  * - added new options to configuration section
  *
  * Revision 1.48  2003/05/09 15:23:04  brian
  * - Changed "last minute" section to "New Information"
  * - added all the new features since v1.1 to 'New uinformation"
  * - Added upgrade instructions to "Installation"
  * - added additional troubleshooting sections
  *
  * Revision 1.47  2003/05/02 15:35:59  Brian
  * updated to reflect current
  *
  * Revision 1.46  2003/04/26 19:22:04  Brian
  * added maxfilesize to configuration options section of README
  * Bug 31
  *
  * Revision 1.45  2003/04/14 16:10:10  Brian
  * more troubleshooting, and spell check
  *
  * Revision 1.44  2003/04/08 16:04:55  Brian
  * added more detail on mcrypt installation
  *
  * Revision 1.43  2003/04/08 04:50:30  Brian
  * added report on reserved word bug to Troubleshooting section
  * Bug 24
  *
  * Revision 1.42  2003/04/04 16:00:26  Brian
  * add link to gpg mini-howto
  *
  * Revision 1.41  2003/04/04 00:11:00  Brian
  * last minute updates
  *
  * Revision 1.40  2003/04/02 22:56:40  Brian
  * - Spell Check
  * - added more detail to troubleshooting and decryption sections
  * Bug 18
  *
  * Revision 1.39  2003/04/02 16:35:59  Brian
  * - added troubleshooting sections
  * - added more information about key upload and decryption
  * - updated last minute section
  *
  * Revision 1.38  2003/04/01 06:40:18  Brian
  * added information about decryption and sm 1.4 compatibility
  *
  * Revision 1.21  2003/03/20 10:50:40  Brian
  * Added Bug Report Section
  *
  * Revision 1.20  2003/03/14 16:01:20  Brian
  * added Joel to team list
  *
  * Revision 1.19  2003/03/14 14:50:39  Brian
  * spell check and add Troubleshooting section for check_php_version
  *
  * Revision 1.18  2003/03/14 14:04:17  Brian
  * updated signing section
  *
  * Revision 1.17  2003/03/13 04:03:53  Brian
  * added troubleshooting option for IDEA
  *
  * Revision 1.16  2003/03/12 19:49:01  Tyler
  * - rewrote some of the key signing areas and added a 'What you need to know'
  * - section where we can put the status of the plugin, 
  * - like what is working and what isn't
  *
  * Revision 1.15  2003/03/12 16:47:42  Brian
  * updates to clarify things before release
  *
  * Revision 1.14  2003/03/12 04:01:06  Tyler
  * - removed the part about editing the hard coded signing key
  *
  * Revision 1.13  2003/03/11 18:28:19  Tyler
  * - Added section on how to setup gpg to allow for the use of the sign_message functions
  *
  * Revision 1.12  2003/03/11 06:44:11  Brian
  * troubleshooting section on "using insecure memory"
  *
  * Revision 1.11  2003/03/11 06:38:10  Brian
  * troubleshooting section on "using insecure memory"
  *
  * Revision 1.10  2003/03/10 18:28:13  Tyler
  * Added 'Compose problems/warning messages' section
  *
  * Revision 1.9  2003/03/10 03:59:02  Tyler
  * test Tyler
  *
  * Revision 1.8  2003/03/07 17:10:03  Brian
  * Added TroubleShooting and CVS repository sections
  *
  * Revision 1.7  2003/03/05 14:55:30  Brian
  * Public Release Notes and Credits
  *
  * Revision 1.6  2003/02/19 23:53:38  Brian
  * minor wording changes
  *
  * Revision 1.5  2003/01/07 13:10:20  Brian
  * Several additions, including more information on the config files, and spell check.
  *
  * Revision 1.4  2003/01/03 22:31:47  Brian
  * Added more information on configuration and installation, and spell check.
  *
  * Revision 1.3  2002/12/09 15:22:22  Brian
  * updated content-type and Id and Log tags
  *
-->
