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 OOP style, PHP 5 is required

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

-	It is now possible to specify multiple keys.
	see "addsignkey", "addencryptkey" and "adddecryptkey"

-	Verify can now handle all signature-types

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

-	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.

		SIG_MODE_NORMAL
		SIG_MODE_DETACH
		SIG_MODE_CLEAR

		VALIDITY_UNKNOWN
		VALIDITY_UNDEFINED
		VALIDITY_NEVER
		VALIDITY_MARGINAL
		VALIDITY_FULL
		VALIDITY_ULTIMATE

		PROTOCOL_OpenPGP
		PROTOCOL_CMS
    
		SIGSUM_VALID
		SIGSUM_GREEN
		SIGSUM_RED
		SIGSUM_KEY_REVOKED
		SIGSUM_KEY_EXPIRED
		SIGSUM_SIG_EXPIRED
		SIGSUM_KEY_MISSING
		SIGSUM_CRL_MISSING
		SIGSUM_CRL_TOO_OLD
		SIGSUM_BAD_POLICY
		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 SIG_MODE_* constants
		default is SIG_MODE_CLEAR

-		string geterror(void)
		returns the last errormessage

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

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

-		bool addsignkey(string key [,string passphrase])
		adds a key for signing. 

-		bool addencryptkey(string key)
		adds a key for encrypting.

-		bool adddecryptkey(string key (,string passphrase])	
		adds a key for decrypting

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

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

-		bool cleardecryptkeys(void)
		removes all key which are set for decryption

-		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 signature [, string &plaintext])
		verifies the given text with the signature.
		To verify a clearsigned text, pass false as signature.
		if plaintext is passed, it is filled with the plaintext (the text without signature).
		This only makes sense for a clearsigned text

-		string decrypt(string enctext)
		decrypts the given enctext
		see adddecryptkey

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

-		array decryptverify(string text, string &plaintext)
		decrypts and verifies the given 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

-		array listsignatures(string key)
		returns an array of informations about the keysignatures

-		array deletekey(string key)
		deletes a key from the keyring. use with caution!

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