README - gpg_encrypt v1.3

* v1.04	13 Jan 2004	first public release(?)
* v1.2	21 Aug 2004	previous versions required gpg "--homedir" to 
			be writable by the web server. this version
			allows (and recommends) that the "--homedir"
			and it's contents are readable, but NOT writable 
			by the web server. see below for details on
			preparing the "--homedir".
* v1.3	17 Feb 2006	there have been reports of the "is_executable"
			sanity check causing problems on some older
			versions of php. the only fix is to comment out
			(or remove) that check. this version will give
			instructions to do that, if the check fails.
			i've also updated the code from shell style
			comments to C style comments.

* PREPARING THE KEYRING AND DIRECTORY

let's assume that you're using "/home/www/.gnupg" as your keyring
directory. let's also assume that you're using a unix-type system.

1) create a directory:
	mkdir /home/www/.gnupg

2) import a PUBLIC key into that directory:
	gpg --homedir /home/www/.gnupg/ --import pubkey_file.asc

3) create a "trustdb" in the keyring:
	gpg --homedir /home/www/.gnupg/ --update-trustdb

4) allow the keyring and it's contents to be world readable:
	chmod 744 /home/www/.gnupg/
	chmod 644 /home/www/.gnupg/*


what follows is available at: http://Business-PHP.com/opensource/gpg_encrypt/

gpg_encrypt() v1.3

   gpg_encrypt() is a PHP function that will allow you to easily use
   GnuPG to encrypt data to your public PGP key and mail that encrypted
   data to yourself, where it can be securely decrypted with your private
   key. This is designed primarily for use with web-based forms but can
   be used to encrypt any data.

   Requires PHP >=4.3.0

   Typical usage:
       $gpg = gpg_encrypt($secret_message, /usr/local/bin/gpg, /home/www/.gnupg, 0x123456)
   The 4 required arguments are:
    1. $secret_message The data to be encrypted
    2. /path/to/gpg The full path to your gpg program
    3. /path/to/.gnupg The full path to the GnuPG home directory
       (keyring)
    4. 0x123456 Key ID to encrypt the message to

     * /path/to/.gnupg needs to be readable by your web server, and
       should NOT contain any secret keys. The ONLY keys that should be
       stored there are the public keys you are encrypting to.
     * You can specify multiple key IDs - make sure each one is listed as
       a separate argument after the first key ID.

       Returned to the $gpg array:

    1. $gpg[0] = PGP encrypted message (standard out from GnuPG)
    2. $gpg[1] = Notices and warnings (standard error from GnuPG)
    3. $gpg[2] = Exit status from gpg command (GnuPG exit status)

   The example code will email an encrypted message if GnuPG succeeds
   or display gpg diagnostic warnings and notices if GnuPG fails. It is
   intended to be easy to modify for your own needs, without any need to
   modify the gpg_encrypt() function.

   Unlike quick and dirty methods of PGP encryption in PHP this function
   provides these benefits:
     * no sniffing of sensitive data though `ps`
     * escaping or filtering of special characters is not required*
       * but may be done automatically - check your "magic_quotes_gpc"
       setting
     * encrypt to as many keys as you want
     * standard out, standard error and exit status are all available
       from gpg

   Security is only as strong as it's weakest link. This is not intended
   to provide ultimate security (whatever that is). Bear these things in
   mind:
     * How is the data getting to your form? SSL? TLS?
     * Are your web-server, PHP, GnuPG and operating system secure?
     * Can the secret message be written to disk cache?
     * Is your secret-key stored on the server?
     * Are the permissions for www's keyring set right?

   If your web server is running as user "www", your keyring directory
   will have to be readable by www. If your web server is running as your
   UID then you have a different list of concerns.

   Note that this function bypasses the trust checking that GnuPG
   normally uses, and assumes that any key it's told to use is trusted.
   This might not make sense at first, but it doesn't open up any
   security holes that don't already exist when your gpg home directory
   (keyring) lives on a web server. If you're concerned that an attacker
   might add their key without you knowing about it, consider including
   the function file, any scripts that use it, and your public keyring in
   a list of files to be checked by a file integrity application, such as
   [3]Samhain, [4]Osiris, [5]AIDE, or [6]tripwire.

   It is not the intent of this function to sign any data. Signing data
   on auto-pilot would require either 1) your signing key to be stored
   without a pass-phrase or 2) your secret pass-phrase to be stored
   unencrypted. In the event that your web server were to be compromised,
   an attacker could easily get your signing key. With that in mind,
   signing data under such conditions provides no real security, but it
   does provide a real chance that your secret key may be compromised.
   Keeping any secret key on a web server, especially if it's readable by
   the web server, is a bad idea. Keeping such a key without a
   pass-phrase or with a pass-phrase stored in clear text is an
   incredibly bad idea. That's why this function is only meant to
   encrypt, not sign. With OpenPGP an encryption key can be public, so if
   an attacker gets their hands on your encryption key, all they can do
   with it is encrypt messages that only you can decrypt: If an attacker
   gets their hands on your secret key, they can ruin your day.

   See also: [12]The GNU Privacy Guard

References

   3. http://samhain.sourceforge.net/
   4. http://osiris.shmoo.com/
   5. http://aide.sourceforge.net/
   6. http://www.tripwire.org/
  12. http://gnupg.org/

###
