php-gnupg/README

Installation
------------
tar xvzf gnupg-x.y.tgz
cd gnupg-x-y
phpize
make
make install

This extension requires the gpgme library, which is available at http://www.gnupg.org/(en)/download/index.html#gpgme


Notes
-----
-	This extension requires at least PHP 4.3.0
	To use this extension in an OO style, PHP 5 is required

-	This is a beta version.
	Don<6F>t use it on production systems.

-	Only the Open_PGP protocol is currently supported.
	This shouldn<64>t be a problem for the most people.

-	only 1 key per operation is currently supported.
	so you can<61>t add x keys for encryption.

-	Whenever you provide a key to a method, you should make sure, that your given pattern is unique.
	Otherwise it could happen, that the wrong key is selected from the keyring.
	The best would be to provide the fingerprint, whenever needed.

-	The underlying lib checks for the presence of the gpg-agent.
	If a passphrase is required for an operation, this agent is asked first.
	To avoid this, clear the enviroment-variable GPG_AGENT_INFO (see http://de3.php.net/manual/en/function.putenv.php)

-	To specify a custom location of you keyring, simply store the path in the enviroment-variable GNUPGHOME
	This should make it easy, to use this extension with the apache-user.

-	Constants:

		GNUPG_SIG_MODE_NORMAL
		GNUPG_SIG_MODE_DETACH
		GNUPG_SIG_MODE_CLEAR

		GNUPG_VALIDITY_UNKNOWN
		GNUPG_VALIDITY_UNDEFINED
		GNUPG_VALIDITY_NEVER
		GNUPG_VALIDITY_MARGINAL
		GNUPG_VALIDITY_FULL
		GNUPG_VALIDITY_ULTIMATE

		GNUPG_PROTOCOL_OpenPGP
		GNUPG_PROTOCOL_CMS
    
		GNUPG_SIGSUM_VALID
		GNUPG_SIGSUM_GREEN
		GNUPG_SIGSUM_RED
		GNUPG_SIGSUM_KEY_REVOKED
		GNUPG_SIGSUM_KEY_EXPIRED
		GNUPG_SIGSUM_SIG_EXPIRED
		GNUPG_SIGSUM_KEY_MISSING
		GNUPG_SIGSUM_CRL_MISSING
		GNUPG_SIGSUM_CRL_TOO_OLD
		GNUPG_SIGSUM_BAD_POLICY
		GNUPG_SIGSUM_SYS_ERROR


Methods
-------
Note: the following explanations are describing the usage of this extension in the OO style, which is only
available in PHP 5
To use this extension in a procedural style, simply call "gnupg_init", which returns a resource.
Pass this resource as the first parameter to each function.
In procedural style, all methods gets "gnupg_" prefixed. (setarmor becomes gnupg_setarmor)
Example:

$res = gnupg_init();
gnupg_setarmor($res,1);


-		__construct()
		sets up a new gnupg object
		( new gnupg() )

-		resource gnupg_init()
		sets up a new gnupg object for procedural use and returns a resource identifier

-		bool setarmor(int armor)
		turn on/off armor mode
		0 = off
		>0 = on	(default)

-		bool setsignmode(int signmode)
		sets the mode for signing operations
		see the GNUPG_SIG_MODE_* constants
		default is GNUPG_SIG_MODE_CLEAR

-		bool setpassphrase(string passphrase)
		sets the passphrase for all next operations

-		string geterror(void)
		returns the last errormessage

-		int getprotocol(void)
		returns the currently used pgp-protocol.
		atm only GNUPG_PROTOCOL_OpenPGP is supported

-		array keyinfo(string pattern)
		returns an array with informations about all keys, that matches the given pattern

-		bool setsignerkey(string key)
		sets the private key for the next sign operation.
		please note, that the given key must return only 1 result from the keyring
		it should be the best to provide a fingerprint here

-		bool setencryptkey(string key)
		sets the public key for next encrypt operation.
		please note, that the given key must return only 1 result from the keyring
		it should be the best to provide a fingerprint here

-		bool clearsignerkey(void)
		removes all keys which are set for signing

-		bool clearencryptkey(void)
		removes all keys which are set for encryption

-		string sign(string text)
		signs the given test with the key, which was set with setsignerkey before
		and returns the signed text
		the signmode depends on gnupg_setsignmode

-		string encrypt(string text)
		encrypts the given text with the key, which was set with setencryptkey before
		and returns the encrypted text

-		array verify(string text [, string &plaintext])
		verifies the given clearsigned text and returns information about the result in an array
		if plaintext is passed, it is filled with the plaintext (the text without signature)
		currently only cleartext-signatures are supported

-		string decrypt(string enctext)
		decrypts the given enctext

-		string encryptsign(string text)
		encrypts and signs the given text with the keys, which are set with setencryptkey and setsignerkey

-		array decryptverify(string text, string &plaintext)
		verifies the given clearsigned text and returns information about the result in an array
		the plaintext is passed into $plaintext

-		string export(string key)
		returns the given key

-		array import(string key)
		imports the given key and returns an array with informations about the import-process


gnupg_keylistiterator
---------------------
This extension comes with an iterator for looping through the keyring
see examples/keylistiterator.php
if an argument is passed in the constructor, only keys that are matching this argument gets returned