<meta http-equiv="Content-Type" content="text/plain; charset=ansi">
<!--
  * $Id: INSTALL.txt,v 1.9 2006/01/08 02:47:20 ke Exp $
-->

Pre-Installation Requirements

	Using this plugin requires gpg, the GNU Privacy Guard.  gpg is the
	OpenPGP implementation of the popular PGP protocol, now made public in
	the OpenPGP protocol.

	gpg may be obtained in source and binary from:

	http://www.gnupg.org/

	This document will not talk about installing and configuring gpg, except 
	in passing, so please read the gpg documentation for more information.

	GnuPG should be installed and tested on your server, and you will need 
	to know the path to the gpg binary for the install configuration 
	of the plugin. If you need help doing this, try the GnuPG mini-HOWTO:
	
	http://webber.dewinter.com/gnupg_howto/
	
	If you wish to store private keys on the server, see the section below for 
	additional requirements.

Installation

	If you are upgrading from a previous version of the plugin using the 
	tarball, make sure that you make a copy of your gpg_local_prefs.txt, 
	and merge your local changes after expanding the new version.
	
	Several files have been removed from previous versions, so if you are 
	upgrading, we recommend that you move your existing installation out of 
	the way first.

	If you are upgrading to 2.0 from a previous version and you are using the hashed 
	user preference directory setting in Squirrelmail, you will need to
	move your old user.gnupg directory from /path/to/squirrelmail/data/ into the 
	correct hashed directory to see your keys.  The directory hash level
	is set in /path/to/squirrelmail/config/conf.pl, under General Options. 

	Installation is the same as for any other Squirrelmail plugin.
	Untar the plugin into your SM plugins directory.
	
	For example:
	tar -zxvf gpg.2.0-1.4.2.tar.gz
	
	Check the options files in the gpg plugin directory:
	
		gpg_system_defaults.txt and
		gpg_local_prefs.txt 
		
		Make any necessary changes for your environment in the 
		gpg_local_prefs.txt file.
		Leave the gpg_system_defaults.txt file alone, 
		so you can roll back to a 'clean' install at any time.
		
	Glenn Powers recommends checking the file permissions to make sure 
	everything is world-readable (or setting umask 022 before untarring).
	Some security scripts such as Bastille set the permissions very 
	restrictively.
	
	Start the SM conf.pl script from the SM config directory, select Plugins,
	and select the 'gpg' plugin.


	Double check that file_uploads = On in php.ini, 
	and edit php.ini and restart your web server if necessary.
	(see Troubleshooting in the plugin help for more on this)
	
Configuration Options

	The GPG Plugin has many options that you can set to customize how it works
	for your installation.  The plugin sets common default values in 
	gpg_system_defaults.txt.  You should not change the gpg_system_defaults.txt
	file under most circumstances.  Change any preferences that you want in the 
	gpg_local_prefs.txt file.  Changes in the gpg_local_prefs.txt will override 
	the system defaults.  You may put any of the options below into your 
	gpg_local_prefs.txt file, if the defaults in gpg_system_defaults.txt don't 
	work well for your needs.
	
	We have attempted to document all of the configuration preferences below.  
	If we missed one, please contact us so that we can add it to the documentation.

	path_to_gpg=/usr/bin/gpg 
	This sets the fully qualified path to the gpg binary.  On many unix systems,
	gpg will be in the /usr/bin directory, so this defaults to /usr/bin/gpg. 
	Other options include settings like /bin/gpg and C:\gpg\gpg.exe
	
	allowprivatekeys=true 
        Do you want to allow your users to use private keys on your system? If you
        set this to false then signing and decryption will be unavailable as these
        features require private keys.

	allowkeygeneration=true 
	If this option is set to false, your users will not be allowed to generate 
	keys on the server.

	requirepassphraseonkeydelete=true
	Requires the user to enter a passphrase when deleting a secret key or
	keypair.  When set to true it adds an extra level of security and
	ensures the user actually meant to delete this key.  Set to false to
	allow a user to delete keys without entering the passphrase for the key.
	
	systemkeyring=false 
	systemtrustedkey=<long key id>
	systemkeyringfile=<path from $data_dir to keyring>
	If the plugin is to be installed on a corporate mail server, you may
	wish to collect and sign keys for each employee.  You may then upload 
	a public keyring and set a trusted key id for the entire company or 
	web mail server user community.
	Each user will have the option in their individual preferences whether
	to trust your corporate keyring and signing key.
	To figure out the long key ID of your system trusted key, do:
	gpg --list-sigs --with-colons --homedir ../../data/gpgsystemkeys/

	keyservers=3
	keyserver0=pgp.mit.edu:11371
	keyserver1=wwwkeys.pgp.net:11371
	keyserver2=wwwkeys.eu.pgp.net:11371
	We define some keyservers by default.  The system administrator
	may change these in the gpg_local_prefs.txt file.  Make sure to
	define all of the keyservers you want in the gpg_local_prefs file,
	because this file takes precedence over the gpg_system_defaults file.

	keystrengths=4
	keystrength0=1024
	keystrength1=2048
	keystrength2=3072
	keystrength3=4096
	We define some keystrengths by default.  These are a sensible number
	of common keystrengths.  This option provides the list of keystrengths
	available to the user during key generation.

	default_keystrength=1024
	This sets the default key strength shown to the user during key
	generation.  This value should also exist as one of the key strengths
	available to the user, currently 1024,2048,3072 or 4096.
	
	default_keyexpires=1y
	This sets the default duration for the expiration of a key during key
	generation.  Possible values are an integer number of days or #y for
	number of years.

	default_comment=Key generated on public web mail server
	This is the comment value placed on a key during key generation.

	maxfilesize=100000
	This sets the maximum size of key file the plugin will allow to be uploaded.
	This setting is complimentary to the upload_max_filesize directive 
	set in php.ini.
	This setting will determine the largest key file that your users may 
	upload in one time.  
	The user will see an error if this file size is exceeded.

	allowpassphrasecaching=false
	This flag sets the system-wide preference to enable passphrase
	caching.  We set passphrase caching to false by default.  
	Passphrase caching is very convenient, but requires that an encrypted
	copy of the passphrase be stored in the PHP session.  This may be less 
	secure than forcing the user to retype their passphrase every time it
	is needed.
	To enable passphrase caching, set this option to true in 
	gpg_local_prefs.txt.

	insecure_mem_warning=1
	When set to 1, shows gpg's warnings about the use of insecure memory.
	See the Troubleshooting section for more details on the cause and
	fixes of this error.  To hide these errors, set this option to 0.

	systemsign_on_send=false
	This setting controls the system-wide preference to show the compose
	window with sign on send checked upon loading.  This is set to false
	by default, but can be overridden by setting to true in gpg_local_prefs.txt. 
	Each user also has the ability to indicate this in their personal 
	preferences.

	systemencrypt_on_send=false
	This setting controls the system-wide preference to show the compose
	window with Encrypt on Send checked by default.  This is set to false
	by default, but can be overridden by setting to true in
	gpg_local_prefs.txt or by user preferences.

	expose_compose_buttons=true
	This setting controls whether or not the "Encrypt Now" and the
	"Encrypt&Sign Now" buttons are displayed when a user is composing an 
	email. The "Encrypt on Send" and "Sign on Send" checkboxes are not
	affected by this option.

	force_sign_on_send=false
	force_encrypt_on_send=false
	These settings force all users to encrypt or sign all messages.
	This option should only be used if you are completely certain
	that you need this feature. If you set force_encrypt_on_send to true,
	users will not be able to send email to addresses for which they do
	not have a public key. If you set force_sign_on_send to true, the
	"Encrypt Now" button will be hidden since that button does not sign
	the message. If you really want to make sure that a user never sends
	unencrypted or unsigned content then you should set expose_compose_buttons to
	false. The reason for this is that once a user encrypts a message using
	the "Encrypt Now" or "Encrypt&Sign Now" buttons, the message will not
	be encrypted again. However, a user could add text or attachments to a
	message after using the "Encrypt Now" or "Encrypt&Sign Now" buttons.

	systemparse_openpgp_header=true
	systemgenerate_openpgp_header=true
	The OpenPGP header allows users the oppportunity to advertise their key
	id and optionally a url where their key may be fetched.  If you want to
	prevent users from generating a header set
	systemgenerate_openpgp_header=false.  If you want to prevent the system
	from parsing headers set systemparse_openpgp_header=false.  There is a
	per-user option for disabling this too.

	debug=0
	This sets the debug level for the entire plugin.  
	Currently, only debug=0 (off) and any positive debug level (on) are 
	supported.  Setting debug=1 (or any positive number) will give you a 
	lot of output to help you understand what is going on inside the plugin.
	The developers do not recommend turning on debug on a production install of
	Squirrelmail.  It doesn't break anything, but it may make the output very ugly, 
	and could be expected to confuse users.
	
	Also, if you do turn debug on, use debug=1, as additional, finer-grained debug 
	mechanisms may be added in future plugin releases.
	
	The way the developers test the plugin is on a parallel installation of 
	Squirrelmail.  Copy your Squirrelmail directories to another directory
	that is accessible from the web server.  This will share your preferences
	and user files across the two installs, but let you set SM and gpg options 
	separately on your parallel installation, and test the plugin or other code.
	
	
<!--
 /**
  * $Log: INSTALL.txt,v $
  * Revision 1.9  2006/01/08 02:47:20  ke
  * - committed patch from Evan <umul@riseup.net> for OpenPGP header support in squirrelmail
  * - adds system preferences and user options to control parsing and adding of OpenPGP Headers on emails
  * - slightly tweaked to use the key associated with the identity, when identities with signing keys are enabled
  *
  * Revision 1.8  2004/08/16 13:44:29  joelm
  * -added two config options to allow a sys admin to force users to always sign
  * or encrypt email
  * Bug 83
  *
  * Revision 1.7  2004/07/17 21:13:44  joelm
  * Fix three typos
  *
  * Revision 1.6  2004/01/06 19:26:44  brian
  * - spell check
  * - update to reflect current
  *
  * Revision 1.5  2004/01/05 14:36:16  brian
  * updated description of allowkeygeneration option.
  *
  * Revision 1.4  2004/01/03 22:46:06  ke
  * -added blurb for option requirepassphraseonkeydelete just added
  *
  * Revision 1.3  2003/12/01 19:33:41  ke
  * -added section on upgrading using a hashed directory level
  *
  * Revision 1.2  2003/11/23 12:03:09  brian
  * - added description to the configuration options section
  *   defining the files, and where to make changes,
  *   per a suggestion by pdontthink
  *
  * Revision 1.1  2003/11/22 15:46:41  brian
  * Changed name to INSTALL.txt so it will displaay better on browsers
  *
  * Revision 1.1  2003/11/22 15:29:58  brian
  * - Added file INSTALL
  * Bug 70
  *
  */
-->
