githubFork/roundcubemail.git

Move PEAR libs from plugins into main Roundcube lib directory, list them as...

Aleksander Machniak

2013-10-06 4daaa09438bc05f9d5d6cf339cc0b60b511057e9

commit \| author \| age
48e9c1	1	<?php
T	2
	3	/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */
	4
	5	/**
	6	* Crypt_GPG is a package to use GPG from PHP
	7	*
	8	* This file contains an engine that handles GPG subprocess control and I/O.
	9	* PHP's process manipulation functions are used to handle the GPG subprocess.
	10	*
	11	* PHP version 5
	12	*
	13	* LICENSE:
	14	*
	15	* This library is free software; you can redistribute it and/or modify
	16	* it under the terms of the GNU Lesser General Public License as
	17	* published by the Free Software Foundation; either version 2.1 of the
	18	* License, or (at your option) any later version.
	19	*
	20	* This library is distributed in the hope that it will be useful,
	21	* but WITHOUT ANY WARRANTY; without even the implied warranty of
	22	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
	23	* Lesser General Public License for more details.
	24	*
	25	* You should have received a copy of the GNU Lesser General Public
	26	* License along with this library; if not, write to the Free Software
	27	* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
	28	*
	29	* @category Encryption
	30	* @package Crypt_GPG
	31	* @author Nathan Fredrickson <nathan@silverorange.com>
	32	* @author Michael Gauthier <mike@silverorange.com>
	33	* @copyright 2005-2010 silverorange
	34	* @license http://www.gnu.org/copyleft/lesser.html LGPL License 2.1
	35	* @version CVS: $Id: Engine.php 302822 2010-08-26 17:30:57Z gauthierm $
	36	* @link http://pear.php.net/package/Crypt_GPG
	37	* @link http://www.gnupg.org/
	38	*/
	39
	40	/**
	41	* Crypt_GPG base class.
	42	*/
	43	require_once 'Crypt/GPG.php';
	44
	45	/**
	46	* GPG exception classes.
	47	*/
	48	require_once 'Crypt/GPG/Exceptions.php';
	49
	50	/**
	51	* Standard PEAR exception is used if GPG binary is not found.
	52	*/
	53	require_once 'PEAR/Exception.php';
	54
	55	// {{{ class Crypt_GPG_Engine
	56
	57	/**
	58	* Native PHP Crypt_GPG I/O engine
	59	*
	60	* This class is used internally by Crypt_GPG and does not need be used
	61	* directly. See the {@link Crypt_GPG} class for end-user API.
	62	*
	63	* This engine uses PHP's native process control functions to directly control
	64	* the GPG process. The GPG executable is required to be on the system.
	65	*
	66	* All data is passed to the GPG subprocess using file descriptors. This is the
	67	* most secure method of passing data to the GPG subprocess.
	68	*
	69	* @category Encryption
	70	* @package Crypt_GPG
	71	* @author Nathan Fredrickson <nathan@silverorange.com>
	72	* @author Michael Gauthier <mike@silverorange.com>
	73	* @copyright 2005-2010 silverorange
	74	* @license http://www.gnu.org/copyleft/lesser.html LGPL License 2.1
	75	* @link http://pear.php.net/package/Crypt_GPG
	76	* @link http://www.gnupg.org/
	77	*/
	78	class Crypt_GPG_Engine
	79	{
	80	// {{{ constants
	81
	82	/**
	83	* Size of data chunks that are sent to and retrieved from the IPC pipes.
	84	*
	85	* PHP reads 8192 bytes. If this is set to less than 8192, PHP reads 8192
	86	* and buffers the rest so we might as well just read 8192.
	87	*
	88	* Using values other than 8192 also triggers PHP bugs.
	89	*
	90	* @see http://bugs.php.net/bug.php?id=35224
	91	*/
	92	const CHUNK_SIZE = 8192;
	93
	94	/**
	95	* Standard input file descriptor. This is used to pass data to the GPG
	96	* process.
	97	*/
	98	const FD_INPUT = 0;
	99
	100	/**
	101	* Standard output file descriptor. This is used to receive normal output
	102	* from the GPG process.
	103	*/
	104	const FD_OUTPUT = 1;
	105
	106	/**
	107	* Standard output file descriptor. This is used to receive error output
	108	* from the GPG process.
	109	*/
	110	const FD_ERROR = 2;
	111
	112	/**
	113	* GPG status output file descriptor. The status file descriptor outputs
	114	* detailed information for many GPG commands. See the second section of
	115	* the file <b>doc/DETAILS</b> in the
	116	* {@link http://www.gnupg.org/download/ GPG package} for a detailed
	117	* description of GPG's status output.
	118	*/
	119	const FD_STATUS = 3;
	120
	121	/**
	122	* Command input file descriptor. This is used for methods requiring
	123	* passphrases.
	124	*/
	125	const FD_COMMAND = 4;
	126
	127	/**
	128	* Extra message input file descriptor. This is used for passing signed
	129	* data when verifying a detached signature.
	130	*/
	131	const FD_MESSAGE = 5;
	132
	133	/**
	134	* Minimum version of GnuPG that is supported.
	135	*/
	136	const MIN_VERSION = '1.0.2';
	137
	138	// }}}
	139	// {{{ private class properties
	140
	141	/**
	142	* Whether or not to use debugging mode
	143	*
	144	* When set to true, every GPG command is echoed before it is run. Sensitive
	145	* data is always handled using pipes and is not specified as part of the
	146	* command. As a result, sensitive data is never displayed when debug is
	147	* enabled. Sensitive data includes private key data and passphrases.
	148	*
	149	* Debugging is off by default.
	150	*
	151	* @var boolean
	152	* @see Crypt_GPG_Engine::__construct()
	153	*/
	154	private $_debug = false;
	155
	156	/**
	157	* Location of GPG binary
	158	*
	159	* @var string
	160	* @see Crypt_GPG_Engine::__construct()
	161	* @see Crypt_GPG_Engine::_getBinary()
	162	*/
	163	private $_binary = '';
	164
	165	/**
	166	* Directory containing the GPG key files
	167	*
	168	* This property only contains the path when the <i>homedir</i> option
	169	* is specified in the constructor.
	170	*
	171	* @var string
	172	* @see Crypt_GPG_Engine::__construct()
	173	*/
	174	private $_homedir = '';
	175
	176	/**
	177	* File path of the public keyring
	178	*
	179	* This property only contains the file path when the <i>public_keyring</i>
	180	* option is specified in the constructor.
	181	*
	182	* If the specified file path starts with <kbd>~/</kbd>, the path is
	183	* relative to the <i>homedir</i> if specified, otherwise to
	184	* <kbd>~/.gnupg</kbd>.
	185	*
	186	* @var string
	187	* @see Crypt_GPG_Engine::__construct()
	188	*/
	189	private $_publicKeyring = '';
	190
	191	/**
	192	* File path of the private (secret) keyring
	193	*
	194	* This property only contains the file path when the <i>private_keyring</i>
	195	* option is specified in the constructor.
	196	*
	197	* If the specified file path starts with <kbd>~/</kbd>, the path is
	198	* relative to the <i>homedir</i> if specified, otherwise to
	199	* <kbd>~/.gnupg</kbd>.
	200	*
	201	* @var string
	202	* @see Crypt_GPG_Engine::__construct()
	203	*/
	204	private $_privateKeyring = '';
	205
	206	/**
	207	* File path of the trust database
	208	*
	209	* This property only contains the file path when the <i>trust_db</i>
	210	* option is specified in the constructor.
	211	*
	212	* If the specified file path starts with <kbd>~/</kbd>, the path is
	213	* relative to the <i>homedir</i> if specified, otherwise to
	214	* <kbd>~/.gnupg</kbd>.
	215	*
	216	* @var string
	217	* @see Crypt_GPG_Engine::__construct()
	218	*/
	219	private $_trustDb = '';
	220
	221	/**
	222	* Array of pipes used for communication with the GPG binary
	223	*
	224	* This is an array of file descriptor resources.
	225	*
	226	* @var array
	227	*/
	228	private $_pipes = array();
	229
	230	/**
	231	* Array of currently opened pipes
	232	*
	233	* This array is used to keep track of remaining opened pipes so they can
	234	* be closed when the GPG subprocess is finished. This array is a subset of
	235	* the {@link Crypt_GPG_Engine::$_pipes} array and contains opened file
	236	* descriptor resources.
	237	*
	238	* @var array
	239	* @see Crypt_GPG_Engine::_closePipe()
	240	*/
	241	private $_openPipes = array();
	242
	243	/**
	244	* A handle for the GPG process
	245	*
	246	* @var resource
	247	*/
	248	private $_process = null;
	249
	250	/**
	251	* Whether or not the operating system is Darwin (OS X)
	252	*
	253	* @var boolean
	254	*/
	255	private $_isDarwin = false;
	256
	257	/**
	258	* Commands to be sent to GPG's command input stream
	259	*
	260	* @var string
	261	* @see Crypt_GPG_Engine::sendCommand()
	262	*/
	263	private $_commandBuffer = '';
	264
	265	/**
	266	* Array of status line handlers
	267	*
	268	* @var array
	269	* @see Crypt_GPG_Engine::addStatusHandler()
	270	*/
	271	private $_statusHandlers = array();
	272
	273	/**
	274	* Array of error line handlers
	275	*
	276	* @var array
	277	* @see Crypt_GPG_Engine::addErrorHandler()
	278	*/
	279	private $_errorHandlers = array();
	280
	281	/**
	282	* The error code of the current operation
	283	*
	284	* @var integer
	285	* @see Crypt_GPG_Engine::getErrorCode()
	286	*/
	287	private $_errorCode = Crypt_GPG::ERROR_NONE;
	288
	289	/**
	290	* File related to the error code of the current operation
	291	*
	292	* @var string
	293	* @see Crypt_GPG_Engine::getErrorFilename()
	294	*/
	295	private $_errorFilename = '';
	296
	297	/**
	298	* Key id related to the error code of the current operation
	299	*
	300	* @var string
	301	* @see Crypt_GPG_Engine::getErrorKeyId()
	302	*/
	303	private $_errorkeyId = '';
	304
	305	/**
	306	* The number of currently needed passphrases
	307	*
	308	* If this is not zero when the GPG command is completed, the error code is
	309	* set to {@link Crypt_GPG::ERROR_MISSING_PASSPHRASE}.
	310	*
	311	* @var integer
	312	*/
	313	private $_needPassphrase = 0;
	314
	315	/**
	316	* The input source
	317	*
	318	* This is data to send to GPG. Either a string or a stream resource.
	319	*
	320	* @var string\|resource
	321	* @see Crypt_GPG_Engine::setInput()
	322	*/
	323	private $_input = null;
	324
	325	/**
	326	* The extra message input source
	327	*
	328	* Either a string or a stream resource.
	329	*
	330	* @var string\|resource
	331	* @see Crypt_GPG_Engine::setMessage()
	332	*/
	333	private $_message = null;
	334
	335	/**
	336	* The output location
	337	*
	338	* This is where the output from GPG is sent. Either a string or a stream
	339	* resource.
	340	*
	341	* @var string\|resource
	342	* @see Crypt_GPG_Engine::setOutput()
	343	*/
	344	private $_output = '';
	345
	346	/**
	347	* The GPG operation to execute
	348	*
	349	* @var string
	350	* @see Crypt_GPG_Engine::setOperation()
	351	*/
	352	private $_operation;
	353
	354	/**
	355	* Arguments for the current operation
	356	*
	357	* @var array
	358	* @see Crypt_GPG_Engine::setOperation()
	359	*/
	360	private $_arguments = array();
	361
	362	/**
	363	* The version number of the GPG binary
	364	*
	365	* @var string
	366	* @see Crypt_GPG_Engine::getVersion()
	367	*/
	368	private $_version = '';
	369
	370	/**
	371	* Cached value indicating whether or not mbstring function overloading is
	372	* on for strlen
	373	*
	374	* This is cached for optimal performance inside the I/O loop.
	375	*
	376	* @var boolean
	377	* @see Crypt_GPG_Engine::_byteLength()
	378	* @see Crypt_GPG_Engine::_byteSubstring()
	379	*/
	380	private static $_mbStringOverload = null;
	381
	382	// }}}
	383	// {{{ __construct()
	384
	385	/**
	386	* Creates a new GPG engine
	387	*
	388	* Available options are:
	389	*
	390	* - <kbd>string homedir</kbd> - the directory where the GPG
	391	* keyring files are stored. If not
	392	* specified, Crypt_GPG uses the
	393	* default of <kbd>~/.gnupg</kbd>.
	394	* - <kbd>string publicKeyring</kbd> - the file path of the public
	395	* keyring. Use this if the public
	396	* keyring is not in the homedir, or
	397	* if the keyring is in a directory
	398	* not writable by the process
	399	* invoking GPG (like Apache). Then
	400	* you can specify the path to the
	401	* keyring with this option
	402	* (/foo/bar/pubring.gpg), and specify
	403	* a writable directory (like /tmp)
	404	* using the <i>homedir</i> option.
	405	* - <kbd>string privateKeyring</kbd> - the file path of the private
	406	* keyring. Use this if the private
	407	* keyring is not in the homedir, or
	408	* if the keyring is in a directory
	409	* not writable by the process
	410	* invoking GPG (like Apache). Then
	411	* you can specify the path to the
	412	* keyring with this option
	413	* (/foo/bar/secring.gpg), and specify
	414	* a writable directory (like /tmp)
	415	* using the <i>homedir</i> option.
	416	* - <kbd>string trustDb</kbd> - the file path of the web-of-trust
	417	* database. Use this if the trust
	418	* database is not in the homedir, or
	419	* if the database is in a directory
	420	* not writable by the process
	421	* invoking GPG (like Apache). Then
	422	* you can specify the path to the
	423	* trust database with this option
	424	* (/foo/bar/trustdb.gpg), and specify
	425	* a writable directory (like /tmp)
	426	* using the <i>homedir</i> option.
	427	* - <kbd>string binary</kbd> - the location of the GPG binary. If
	428	* not specified, the driver attempts
	429	* to auto-detect the GPG binary
	430	* location using a list of known
	431	* default locations for the current
	432	* operating system. The option
	433	* <kbd>gpgBinary</kbd> is a
	434	* deprecated alias for this option.
	435	* - <kbd>boolean debug</kbd> - whether or not to use debug mode.
	436	* When debug mode is on, all
	437	* communication to and from the GPG
	438	* subprocess is logged. This can be
	439	* useful to diagnose errors when
	440	* using Crypt_GPG.
	441	*
	442	* @param array $options optional. An array of options used to create the
	443	* GPG object. All options are optional and are
	444	* represented as key-value pairs.
	445	*
	446	* @throws Crypt_GPG_FileException if the <kbd>homedir</kbd> does not exist
	447	* and cannot be created. This can happen if <kbd>homedir</kbd> is
	448	* not specified, Crypt_GPG is run as the web user, and the web
	449	* user has no home directory. This exception is also thrown if any
	450	* of the options <kbd>publicKeyring</kbd>,
	451	* <kbd>privateKeyring</kbd> or <kbd>trustDb</kbd> options are
	452	* specified but the files do not exist or are are not readable.
	453	* This can happen if the user running the Crypt_GPG process (for
	454	* example, the Apache user) does not have permission to read the
	455	* files.
	456	*
	457	* @throws PEAR_Exception if the provided <kbd>binary</kbd> is invalid, or
	458	* if no <kbd>binary</kbd> is provided and no suitable binary could
	459	* be found.
	460	*/
	461	public function __construct(array $options = array())
	462	{
	463	$this->_isDarwin = (strncmp(strtoupper(PHP_OS), 'DARWIN', 6) === 0);
	464
	465	// populate mbstring overloading cache if not set
	466	if (self::$_mbStringOverload === null) {
	467	self::$_mbStringOverload = (extension_loaded('mbstring')
	468	&& (ini_get('mbstring.func_overload') & 0x02) === 0x02);
	469	}
	470
	471	// get homedir
	472	if (array_key_exists('homedir', $options)) {
	473	$this->_homedir = (string)$options['homedir'];
	474	} else {
	475	// note: this requires the package OS dep exclude 'windows'
	476	$info = posix_getpwuid(posix_getuid());
	477	$this->_homedir = $info['dir'].'/.gnupg';
	478	}
	479
	480	// attempt to create homedir if it does not exist
	481	if (!is_dir($this->_homedir)) {
	482	if (@mkdir($this->_homedir, 0777, true)) {
	483	// Set permissions on homedir. Parent directories are created
	484	// with 0777, homedir is set to 0700.
	485	chmod($this->_homedir, 0700);
	486	} else {
	487	throw new Crypt_GPG_FileException('The \'homedir\' "' .
	488	$this->_homedir . '" is not readable or does not exist '.
	489	'and cannot be created. This can happen if \'homedir\' '.
	490	'is not specified in the Crypt_GPG options, Crypt_GPG is '.
	491	'run as the web user, and the web user has no home '.
	492	'directory.',
	493	0, $this->_homedir);
	494	}
	495	}
	496
	497	// get binary
	498	if (array_key_exists('binary', $options)) {
	499	$this->_binary = (string)$options['binary'];
	500	} elseif (array_key_exists('gpgBinary', $options)) {
	501	// deprecated alias
	502	$this->_binary = (string)$options['gpgBinary'];
	503	} else {
	504	$this->_binary = $this->_getBinary();
	505	}
	506
	507	if ($this->_binary == '' \|\| !is_executable($this->_binary)) {
	508	throw new PEAR_Exception('GPG binary not found. If you are sure '.
	509	'the GPG binary is installed, please specify the location of '.
	510	'the GPG binary using the \'binary\' driver option.');
	511	}
	512
	513	/*
	514	* Note:
	515	*
	516	* Normally, GnuPG expects keyrings to be in the homedir and expects
	517	* to be able to write temporary files in the homedir. Sometimes,
	518	* keyrings are not in the homedir, or location of the keyrings does
	519	* not allow writing temporary files. In this case, the <i>homedir</i>
	520	* option by itself is not enough to specify the keyrings because GnuPG
	521	* can not write required temporary files. Additional options are
	522	* provided so you can specify the location of the keyrings separately
	523	* from the homedir.
	524	*/
	525
	526	// get public keyring
	527	if (array_key_exists('publicKeyring', $options)) {
	528	$this->_publicKeyring = (string)$options['publicKeyring'];
	529	if (!is_readable($this->_publicKeyring)) {
	530	throw new Crypt_GPG_FileException('The \'publicKeyring\' "' .
	531	$this->_publicKeyring . '" does not exist or is ' .
	532	'not readable. Check the location and ensure the file ' .
	533	'permissions are correct.', 0, $this->_publicKeyring);
	534	}
	535	}
	536
	537	// get private keyring
	538	if (array_key_exists('privateKeyring', $options)) {
	539	$this->_privateKeyring = (string)$options['privateKeyring'];
	540	if (!is_readable($this->_privateKeyring)) {
	541	throw new Crypt_GPG_FileException('The \'privateKeyring\' "' .
	542	$this->_privateKeyring . '" does not exist or is ' .
	543	'not readable. Check the location and ensure the file ' .
	544	'permissions are correct.', 0, $this->_privateKeyring);
	545	}
	546	}
	547
	548	// get trust database
	549	if (array_key_exists('trustDb', $options)) {
	550	$this->_trustDb = (string)$options['trustDb'];
	551	if (!is_readable($this->_trustDb)) {
	552	throw new Crypt_GPG_FileException('The \'trustDb\' "' .
	553	$this->_trustDb . '" does not exist or is not readable. ' .
	554	'Check the location and ensure the file permissions are ' .
	555	'correct.', 0, $this->_trustDb);
	556	}
	557	}
	558
	559	if (array_key_exists('debug', $options)) {
	560	$this->_debug = (boolean)$options['debug'];
	561	}
	562	}
	563
	564	// }}}
	565	// {{{ __destruct()
	566
	567	/**
	568	* Closes open GPG subprocesses when this object is destroyed
	569	*
	570	* Subprocesses should never be left open by this class unless there is
	571	* an unknown error and unexpected script termination occurs.
	572	*/
	573	public function __destruct()
	574	{
	575	$this->_closeSubprocess();
	576	}
	577
	578	// }}}
	579	// {{{ addErrorHandler()
	580
	581	/**
	582	* Adds an error handler method
	583	*
	584	* The method is run every time a new error line is received from the GPG
	585	* subprocess. The handler method must accept the error line to be handled
	586	* as its first parameter.
	587	*
	588	* @param callback $callback the callback method to use.
	589	* @param array $args optional. Additional arguments to pass as
	590	* parameters to the callback method.
	591	*
	592	* @return void
	593	*/
	594	public function addErrorHandler($callback, array $args = array())
	595	{
	596	$this->_errorHandlers[] = array(
	597	'callback' => $callback,
	598	'args' => $args
	599	);
	600	}
	601
	602	// }}}
	603	// {{{ addStatusHandler()
	604
	605	/**
	606	* Adds a status handler method
	607	*
	608	* The method is run every time a new status line is received from the
	609	* GPG subprocess. The handler method must accept the status line to be
	610	* handled as its first parameter.
	611	*
	612	* @param callback $callback the callback method to use.
	613	* @param array $args optional. Additional arguments to pass as
	614	* parameters to the callback method.
	615	*
	616	* @return void
	617	*/
	618	public function addStatusHandler($callback, array $args = array())
	619	{
	620	$this->_statusHandlers[] = array(
	621	'callback' => $callback,
	622	'args' => $args
	623	);
	624	}
	625
	626	// }}}
	627	// {{{ sendCommand()
	628
	629	/**
	630	* Sends a command to the GPG subprocess over the command file-descriptor
	631	* pipe
	632	*
	633	* @param string $command the command to send.
	634	*
	635	* @return void
	636	*
	637	* @sensitive $command
	638	*/
	639	public function sendCommand($command)
	640	{
	641	if (array_key_exists(self::FD_COMMAND, $this->_openPipes)) {
	642	$this->_commandBuffer .= $command . PHP_EOL;
	643	}
	644	}
	645
	646	// }}}
	647	// {{{ reset()
	648
	649	/**
	650	* Resets the GPG engine, preparing it for a new operation
	651	*
	652	* @return void
	653	*
	654	* @see Crypt_GPG_Engine::run()
	655	* @see Crypt_GPG_Engine::setOperation()
	656	*/
	657	public function reset()
	658	{
	659	$this->_operation = '';
	660	$this->_arguments = array();
	661	$this->_input = null;
	662	$this->_message = null;
	663	$this->_output = '';
	664	$this->_errorCode = Crypt_GPG::ERROR_NONE;
	665	$this->_needPassphrase = 0;
	666	$this->_commandBuffer = '';
	667
	668	$this->_statusHandlers = array();
	669	$this->_errorHandlers = array();
	670
	671	$this->addStatusHandler(array($this, '_handleErrorStatus'));
	672	$this->addErrorHandler(array($this, '_handleErrorError'));
	673
	674	if ($this->_debug) {
	675	$this->addStatusHandler(array($this, '_handleDebugStatus'));
	676	$this->addErrorHandler(array($this, '_handleDebugError'));
	677	}
	678	}
	679
	680	// }}}
	681	// {{{ run()
	682
	683	/**
	684	* Runs the current GPG operation
	685	*
	686	* This creates and manages the GPG subprocess.
	687	*
	688	* The operation must be set with {@link Crypt_GPG_Engine::setOperation()}
	689	* before this method is called.
	690	*
	691	* @return void
	692	*
	693	* @throws Crypt_GPG_InvalidOperationException if no operation is specified.
	694	*
	695	* @see Crypt_GPG_Engine::reset()
	696	* @see Crypt_GPG_Engine::setOperation()
	697	*/
	698	public function run()
	699	{
	700	if ($this->_operation === '') {
	701	throw new Crypt_GPG_InvalidOperationException('No GPG operation ' .
	702	'specified. Use Crypt_GPG_Engine::setOperation() before ' .
	703	'calling Crypt_GPG_Engine::run().');
	704	}
	705
	706	$this->_openSubprocess();
	707	$this->_process();
	708	$this->_closeSubprocess();
	709	}
	710
	711	// }}}
	712	// {{{ getErrorCode()
	713
	714	/**
	715	* Gets the error code of the last executed operation
	716	*
	717	* This value is only meaningful after {@link Crypt_GPG_Engine::run()} has
	718	* been executed.
	719	*
	720	* @return integer the error code of the last executed operation.
	721	*/
	722	public function getErrorCode()
	723	{
	724	return $this->_errorCode;
	725	}
	726
	727	// }}}
	728	// {{{ getErrorFilename()
	729
	730	/**
	731	* Gets the file related to the error code of the last executed operation
	732	*
	733	* This value is only meaningful after {@link Crypt_GPG_Engine::run()} has
	734	* been executed. If there is no file related to the error, an empty string
	735	* is returned.
	736	*
	737	* @return string the file related to the error code of the last executed
	738	* operation.
	739	*/
	740	public function getErrorFilename()
	741	{
	742	return $this->_errorFilename;
	743	}
	744
	745	// }}}
	746	// {{{ getErrorKeyId()
	747
	748	/**
	749	* Gets the key id related to the error code of the last executed operation
	750	*
	751	* This value is only meaningful after {@link Crypt_GPG_Engine::run()} has
	752	* been executed. If there is no key id related to the error, an empty
	753	* string is returned.
	754	*
	755	* @return string the key id related to the error code of the last executed
	756	* operation.
	757	*/
	758	public function getErrorKeyId()
	759	{
	760	return $this->_errorKeyId;
	761	}
	762
	763	// }}}
	764	// {{{ setInput()
	765
	766	/**
	767	* Sets the input source for the current GPG operation
	768	*
	769	* @param string\|resource &$input either a reference to the string
	770	* containing the input data or an open
	771	* stream resource containing the input
	772	* data.
	773	*
	774	* @return void
	775	*/
	776	public function setInput(&$input)
	777	{
	778	$this->_input =& $input;
	779	}
	780
	781	// }}}
	782	// {{{ setMessage()
	783
	784	/**
	785	* Sets the message source for the current GPG operation
	786	*
	787	* Detached signature data should be specified here.
	788	*
	789	* @param string\|resource &$message either a reference to the string
	790	* containing the message data or an open
	791	* stream resource containing the message
	792	* data.
	793	*
	794	* @return void
	795	*/
	796	public function setMessage(&$message)
	797	{
	798	$this->_message =& $message;
	799	}
	800
	801	// }}}
	802	// {{{ setOutput()
	803
	804	/**
	805	* Sets the output destination for the current GPG operation
	806	*
	807	* @param string\|resource &$output either a reference to the string in
	808	* which to store GPG output or an open
	809	* stream resource to which the output data
	810	* should be written.
	811	*
	812	* @return void
	813	*/
	814	public function setOutput(&$output)
	815	{
	816	$this->_output =& $output;
	817	}
	818
	819	// }}}
	820	// {{{ setOperation()
	821
	822	/**
	823	* Sets the operation to perform
	824	*
	825	* @param string $operation the operation to perform. This should be one
	826	* of GPG's operations. For example,
	827	* <kbd>--encrypt</kbd>, <kbd>--decrypt</kbd>,
	828	* <kbd>--sign</kbd>, etc.
	829	* @param array $arguments optional. Additional arguments for the GPG
	830	* subprocess. See the GPG manual for specific
	831	* values.
	832	*
	833	* @return void
	834	*
	835	* @see Crypt_GPG_Engine::reset()
	836	* @see Crypt_GPG_Engine::run()
	837	*/
	838	public function setOperation($operation, array $arguments = array())
	839	{
	840	$this->_operation = $operation;
	841	$this->_arguments = $arguments;
	842	}
	843
	844	// }}}
	845	// {{{ getVersion()
	846
	847	/**
	848	* Gets the version of the GnuPG binary
	849	*
	850	* @return string a version number string containing the version of GnuPG
	851	* being used. This value is suitable to use with PHP's
	852	* version_compare() function.
	853	*
	854	* @throws Crypt_GPG_Exception if an unknown or unexpected error occurs.
	855	* Use the <kbd>debug</kbd> option and file a bug report if these
	856	* exceptions occur.
	857	*
	858	* @throws Crypt_GPG_UnsupportedException if the provided binary is not
	859	* GnuPG or if the GnuPG version is less than 1.0.2.
	860	*/
	861	public function getVersion()
	862	{
	863	if ($this->_version == '') {
	864
	865	$options = array(
	866	'homedir' => $this->_homedir,
	867	'binary' => $this->_binary,
	868	'debug' => $this->_debug
	869	);
	870
	871	$engine = new self($options);
	872	$info = '';
	873
	874	// Set a garbage version so we do not end up looking up the version
	875	// recursively.
	876	$engine->_version = '1.0.0';
	877
	878	$engine->reset();
	879	$engine->setOutput($info);
	880	$engine->setOperation('--version');
	881	$engine->run();
	882
	883	$code = $this->getErrorCode();
	884
	885	if ($code !== Crypt_GPG::ERROR_NONE) {
	886	throw new Crypt_GPG_Exception(
	887	'Unknown error getting GnuPG version information. Please ' .
	888	'use the \'debug\' option when creating the Crypt_GPG ' .
	889	'object, and file a bug report at ' . Crypt_GPG::BUG_URI,
	890	$code);
	891	}
	892
	893	$matches = array();
	894	$expression = '/gpg $GnuPG$ (\S+)/';
	895
	896	if (preg_match($expression, $info, $matches) === 1) {
	897	$this->_version = $matches[1];
	898	} else {
	899	throw new Crypt_GPG_Exception(
	900	'No GnuPG version information provided by the binary "' .
	901	$this->_binary . '". Are you sure it is GnuPG?');
	902	}
	903
	904	if (version_compare($this->_version, self::MIN_VERSION, 'lt')) {
	905	throw new Crypt_GPG_Exception(
	906	'The version of GnuPG being used (' . $this->_version .
	907	') is not supported by Crypt_GPG. The minimum version ' .
	908	'required by Crypt_GPG is ' . self::MIN_VERSION);
	909	}
	910	}
	911
	912
	913	return $this->_version;
	914	}
	915
	916	// }}}
	917	// {{{ _handleErrorStatus()
	918
	919	/**
	920	* Handles error values in the status output from GPG
	921	*
	922	* This method is responsible for setting the
	923	* {@link Crypt_GPG_Engine::$_errorCode}. See <b>doc/DETAILS</b> in the
	924	* {@link http://www.gnupg.org/download/ GPG distribution} for detailed
	925	* information on GPG's status output.
	926	*
	927	* @param string $line the status line to handle.
	928	*
	929	* @return void
	930	*/
	931	private function _handleErrorStatus($line)
	932	{
	933	$tokens = explode(' ', $line);
	934	switch ($tokens[0]) {
	935	case 'BAD_PASSPHRASE':
	936	$this->_errorCode = Crypt_GPG::ERROR_BAD_PASSPHRASE;
	937	break;
	938
	939	case 'MISSING_PASSPHRASE':
	940	$this->_errorCode = Crypt_GPG::ERROR_MISSING_PASSPHRASE;
	941	break;
	942
	943	case 'NODATA':
	944	$this->_errorCode = Crypt_GPG::ERROR_NO_DATA;
	945	break;
	946
	947	case 'DELETE_PROBLEM':
	948	if ($tokens[1] == '1') {
	949	$this->_errorCode = Crypt_GPG::ERROR_KEY_NOT_FOUND;
	950	break;
	951	} elseif ($tokens[1] == '2') {
	952	$this->_errorCode = Crypt_GPG::ERROR_DELETE_PRIVATE_KEY;
	953	break;
	954	}
	955	break;
	956
	957	case 'IMPORT_RES':
	958	if ($tokens[12] > 0) {
	959	$this->_errorCode = Crypt_GPG::ERROR_DUPLICATE_KEY;
	960	}
	961	break;
	962
	963	case 'NO_PUBKEY':
	964	case 'NO_SECKEY':
	965	$this->_errorKeyId = $tokens[1];
	966	$this->_errorCode = Crypt_GPG::ERROR_KEY_NOT_FOUND;
	967	break;
	968
	969	case 'NEED_PASSPHRASE':
	970	$this->_needPassphrase++;
	971	break;
	972
	973	case 'GOOD_PASSPHRASE':
	974	$this->_needPassphrase--;
	975	break;
	976
	977	case 'EXPSIG':
	978	case 'EXPKEYSIG':
	979	case 'REVKEYSIG':
	980	case 'BADSIG':
	981	$this->_errorCode = Crypt_GPG::ERROR_BAD_SIGNATURE;
	982	break;
	983
	984	}
	985	}
	986
	987	// }}}
	988	// {{{ _handleErrorError()
	989
	990	/**
	991	* Handles error values in the error output from GPG
	992	*
	993	* This method is responsible for setting the
	994	* {@link Crypt_GPG_Engine::$_errorCode}.
	995	*
	996	* @param string $line the error line to handle.
	997	*
	998	* @return void
	999	*/
	1000	private function _handleErrorError($line)
	1001	{
	1002	if ($this->_errorCode === Crypt_GPG::ERROR_NONE) {
	1003	$pattern = '/no valid OpenPGP data found/';
	1004	if (preg_match($pattern, $line) === 1) {
	1005	$this->_errorCode = Crypt_GPG::ERROR_NO_DATA;
	1006	}
	1007	}
	1008
	1009	if ($this->_errorCode === Crypt_GPG::ERROR_NONE) {
	1010	$pattern = '/No secret key\|secret key not available/';
	1011	if (preg_match($pattern, $line) === 1) {
	1012	$this->_errorCode = Crypt_GPG::ERROR_KEY_NOT_FOUND;
	1013	}
	1014	}
	1015
	1016	if ($this->_errorCode === Crypt_GPG::ERROR_NONE) {
	1017	$pattern = '/No public key\|public key not found/';
	1018	if (preg_match($pattern, $line) === 1) {
	1019	$this->_errorCode = Crypt_GPG::ERROR_KEY_NOT_FOUND;
	1020	}
	1021	}
	1022
	1023	if ($this->_errorCode === Crypt_GPG::ERROR_NONE) {
	1024	$matches = array();
	1025	$pattern = '/can\'t (?:access\|open) `(.*?)\'/';
	1026	if (preg_match($pattern, $line, $matches) === 1) {
	1027	$this->_errorFilename = $matches[1];
	1028	$this->_errorCode = Crypt_GPG::ERROR_FILE_PERMISSIONS;
	1029	}
	1030	}
	1031	}
	1032
	1033	// }}}
	1034	// {{{ _handleDebugStatus()
	1035
	1036	/**
	1037	* Displays debug output for status lines
	1038	*
	1039	* @param string $line the status line to handle.
	1040	*
	1041	* @return void
	1042	*/
	1043	private function _handleDebugStatus($line)
	1044	{
	1045	$this->_debug('STATUS: ' . $line);
	1046	}
	1047
	1048	// }}}
	1049	// {{{ _handleDebugError()
	1050
	1051	/**
	1052	* Displays debug output for error lines
	1053	*
	1054	* @param string $line the error line to handle.
	1055	*
	1056	* @return void
	1057	*/
	1058	private function _handleDebugError($line)
	1059	{
	1060	$this->_debug('ERROR: ' . $line);
	1061	}
	1062
	1063	// }}}
	1064	// {{{ _process()
	1065
	1066	/**
	1067	* Performs internal streaming operations for the subprocess using either
	1068	* strings or streams as input / output points
	1069	*
	1070	* This is the main I/O loop for streaming to and from the GPG subprocess.
	1071	*
	1072	* The implementation of this method is verbose mainly for performance
	1073	* reasons. Adding streams to a lookup array and looping the array inside
	1074	* the main I/O loop would be siginficantly slower for large streams.
	1075	*
	1076	* @return void
	1077	*
	1078	* @throws Crypt_GPG_Exception if there is an error selecting streams for
	1079	* reading or writing. If this occurs, please file a bug report at
	1080	* http://pear.php.net/bugs/report.php?package=Crypt_GPG.
	1081	*/
	1082	private function _process()
	1083	{
	1084	$this->_debug('BEGIN PROCESSING');
	1085
	1086	$this->_commandBuffer = ''; // buffers input to GPG
	1087	$messageBuffer = ''; // buffers input to GPG
	1088	$inputBuffer = ''; // buffers input to GPG
	1089	$outputBuffer = ''; // buffers output from GPG
	1090	$statusBuffer = ''; // buffers output from GPG
	1091	$errorBuffer = ''; // buffers output from GPG
	1092	$inputComplete = false; // input stream is completely buffered
	1093	$messageComplete = false; // message stream is completely buffered
	1094
	1095	if (is_string($this->_input)) {
	1096	$inputBuffer = $this->_input;
	1097	$inputComplete = true;
	1098	}
	1099
	1100	if (is_string($this->_message)) {
	1101	$messageBuffer = $this->_message;
	1102	$messageComplete = true;
	1103	}
	1104
	1105	if (is_string($this->_output)) {
	1106	$outputBuffer =& $this->_output;
	1107	}
	1108
	1109	// convenience variables
	1110	$fdInput = $this->_pipes[self::FD_INPUT];
	1111	$fdOutput = $this->_pipes[self::FD_OUTPUT];
	1112	$fdError = $this->_pipes[self::FD_ERROR];
	1113	$fdStatus = $this->_pipes[self::FD_STATUS];
	1114	$fdCommand = $this->_pipes[self::FD_COMMAND];
	1115	$fdMessage = $this->_pipes[self::FD_MESSAGE];
	1116
	1117	while (true) {
	1118
	1119	$inputStreams = array();
	1120	$outputStreams = array();
	1121	$exceptionStreams = array();
	1122
	1123	// set up input streams
	1124	if (is_resource($this->_input) && !$inputComplete) {
	1125	if (feof($this->_input)) {
	1126	$inputComplete = true;
	1127	} else {
	1128	$inputStreams[] = $this->_input;
	1129	}
	1130	}
	1131
	1132	// close GPG input pipe if there is no more data
	1133	if ($inputBuffer == '' && $inputComplete) {
	1134	$this->_debug('=> closing GPG input pipe');
	1135	$this->_closePipe(self::FD_INPUT);
	1136	}
	1137
	1138	if (is_resource($this->_message) && !$messageComplete) {
	1139	if (feof($this->_message)) {
	1140	$messageComplete = true;
	1141	} else {
	1142	$inputStreams[] = $this->_message;
	1143	}
	1144	}
	1145
	1146	// close GPG message pipe if there is no more data
	1147	if ($messageBuffer == '' && $messageComplete) {
	1148	$this->_debug('=> closing GPG message pipe');
	1149	$this->_closePipe(self::FD_MESSAGE);
	1150	}
	1151
	1152	if (!feof($fdOutput)) {
	1153	$inputStreams[] = $fdOutput;
	1154	}
	1155
	1156	if (!feof($fdStatus)) {
	1157	$inputStreams[] = $fdStatus;
	1158	}
	1159
	1160	if (!feof($fdError)) {
	1161	$inputStreams[] = $fdError;
	1162	}
	1163
	1164	// set up output streams
	1165	if ($outputBuffer != '' && is_resource($this->_output)) {
	1166	$outputStreams[] = $this->_output;
	1167	}
	1168
	1169	if ($this->_commandBuffer != '') {
	1170	$outputStreams[] = $fdCommand;
	1171	}
	1172
	1173	if ($messageBuffer != '') {
	1174	$outputStreams[] = $fdMessage;
	1175	}
	1176
	1177	if ($inputBuffer != '') {
	1178	$outputStreams[] = $fdInput;
	1179	}
	1180
	1181	// no streams left to read or write, we're all done
	1182	if (count($inputStreams) === 0 && count($outputStreams) === 0) {
	1183	break;
	1184	}
	1185
	1186	$this->_debug('selecting streams');
	1187
	1188	$ready = stream_select(
	1189	$inputStreams,
	1190	$outputStreams,
	1191	$exceptionStreams,
	1192	null
	1193	);
	1194
	1195	$this->_debug('=> got ' . $ready);
	1196
	1197	if ($ready === false) {
	1198	throw new Crypt_GPG_Exception(
	1199	'Error selecting stream for communication with GPG ' .
	1200	'subprocess. Please file a bug report at: ' .
	1201	'http://pear.php.net/bugs/report.php?package=Crypt_GPG');
	1202	}
	1203
	1204	if ($ready === 0) {
	1205	throw new Crypt_GPG_Exception(
	1206	'stream_select() returned 0. This can not happen! Please ' .
	1207	'file a bug report at: ' .
	1208	'http://pear.php.net/bugs/report.php?package=Crypt_GPG');
	1209	}
	1210
	1211	// write input (to GPG)
	1212	if (in_array($fdInput, $outputStreams)) {
	1213	$this->_debug('GPG is ready for input');
	1214
	1215	$chunk = self::_byteSubstring(
	1216	$inputBuffer,
	1217	0,
	1218	self::CHUNK_SIZE
	1219	);
	1220
	1221	$length = self::_byteLength($chunk);
	1222
	1223	$this->_debug(
	1224	'=> about to write ' . $length . ' bytes to GPG input'
	1225	);
	1226
	1227	$length = fwrite($fdInput, $chunk, $length);
	1228
	1229	$this->_debug('=> wrote ' . $length . ' bytes');
	1230
	1231	$inputBuffer = self::_byteSubstring(
	1232	$inputBuffer,
	1233	$length
	1234	);
	1235	}
	1236
	1237	// read input (from PHP stream)
	1238	if (in_array($this->_input, $inputStreams)) {
	1239	$this->_debug('input stream is ready for reading');
	1240	$this->_debug(
	1241	'=> about to read ' . self::CHUNK_SIZE .
	1242	' bytes from input stream'
	1243	);
	1244
	1245	$chunk = fread($this->_input, self::CHUNK_SIZE);
	1246	$length = self::_byteLength($chunk);
	1247	$inputBuffer .= $chunk;
	1248
	1249	$this->_debug('=> read ' . $length . ' bytes');
	1250	}
	1251
	1252	// write message (to GPG)
	1253	if (in_array($fdMessage, $outputStreams)) {
	1254	$this->_debug('GPG is ready for message data');
	1255
	1256	$chunk = self::_byteSubstring(
	1257	$messageBuffer,
	1258	0,
	1259	self::CHUNK_SIZE
	1260	);
	1261
	1262	$length = self::_byteLength($chunk);
	1263
	1264	$this->_debug(
	1265	'=> about to write ' . $length . ' bytes to GPG message'
	1266	);
	1267
	1268	$length = fwrite($fdMessage, $chunk, $length);
	1269	$this->_debug('=> wrote ' . $length . ' bytes');
	1270
	1271	$messageBuffer = self::_byteSubstring($messageBuffer, $length);
	1272	}
	1273
	1274	// read message (from PHP stream)
	1275	if (in_array($this->_message, $inputStreams)) {
	1276	$this->_debug('message stream is ready for reading');
	1277	$this->_debug(
	1278	'=> about to read ' . self::CHUNK_SIZE .
	1279	' bytes from message stream'
	1280	);
	1281
	1282	$chunk = fread($this->_message, self::CHUNK_SIZE);
	1283	$length = self::_byteLength($chunk);
	1284	$messageBuffer .= $chunk;
	1285
	1286	$this->_debug('=> read ' . $length . ' bytes');
	1287	}
	1288
	1289	// read output (from GPG)
	1290	if (in_array($fdOutput, $inputStreams)) {
	1291	$this->_debug('GPG output stream ready for reading');
	1292	$this->_debug(
	1293	'=> about to read ' . self::CHUNK_SIZE .
	1294	' bytes from GPG output'
	1295	);
	1296
	1297	$chunk = fread($fdOutput, self::CHUNK_SIZE);
	1298	$length = self::_byteLength($chunk);
	1299	$outputBuffer .= $chunk;
	1300
	1301	$this->_debug('=> read ' . $length . ' bytes');
	1302	}
	1303
	1304	// write output (to PHP stream)
	1305	if (in_array($this->_output, $outputStreams)) {
	1306	$this->_debug('output stream is ready for data');
	1307
	1308	$chunk = self::_byteSubstring(
	1309	$outputBuffer,
	1310	0,
	1311	self::CHUNK_SIZE
	1312	);
	1313
	1314	$length = self::_byteLength($chunk);
	1315
	1316	$this->_debug(
	1317	'=> about to write ' . $length . ' bytes to output stream'
	1318	);
	1319
	1320	$length = fwrite($this->_output, $chunk, $length);
	1321
	1322	$this->_debug('=> wrote ' . $length . ' bytes');
	1323
	1324	$outputBuffer = self::_byteSubstring($outputBuffer, $length);
	1325	}
	1326
	1327	// read error (from GPG)
	1328	if (in_array($fdError, $inputStreams)) {
	1329	$this->_debug('GPG error stream ready for reading');
	1330	$this->_debug(
	1331	'=> about to read ' . self::CHUNK_SIZE .
	1332	' bytes from GPG error'
	1333	);
	1334
	1335	$chunk = fread($fdError, self::CHUNK_SIZE);
	1336	$length = self::_byteLength($chunk);
	1337	$errorBuffer .= $chunk;
	1338
	1339	$this->_debug('=> read ' . $length . ' bytes');
	1340
	1341	// pass lines to error handlers
	1342	while (($pos = strpos($errorBuffer, PHP_EOL)) !== false) {
	1343	$line = self::_byteSubstring($errorBuffer, 0, $pos);
	1344	foreach ($this->_errorHandlers as $handler) {
	1345	array_unshift($handler['args'], $line);
	1346	call_user_func_array(
	1347	$handler['callback'],
	1348	$handler['args']
	1349	);
	1350
	1351	array_shift($handler['args']);
	1352	}
	1353	$errorBuffer = self::_byteSubString(
	1354	$errorBuffer,
	1355	$pos + self::_byteLength(PHP_EOL)
	1356	);
	1357	}
	1358	}
	1359
	1360	// read status (from GPG)
	1361	if (in_array($fdStatus, $inputStreams)) {
	1362	$this->_debug('GPG status stream ready for reading');
	1363	$this->_debug(
	1364	'=> about to read ' . self::CHUNK_SIZE .
	1365	' bytes from GPG status'
	1366	);
	1367
	1368	$chunk = fread($fdStatus, self::CHUNK_SIZE);
	1369	$length = self::_byteLength($chunk);
	1370	$statusBuffer .= $chunk;
	1371
	1372	$this->_debug('=> read ' . $length . ' bytes');
	1373
	1374	// pass lines to status handlers
	1375	while (($pos = strpos($statusBuffer, PHP_EOL)) !== false) {
	1376	$line = self::_byteSubstring($statusBuffer, 0, $pos);
	1377	// only pass lines beginning with magic prefix
	1378	if (self::_byteSubstring($line, 0, 9) == '[GNUPG:] ') {
	1379	$line = self::_byteSubstring($line, 9);
	1380	foreach ($this->_statusHandlers as $handler) {
	1381	array_unshift($handler['args'], $line);
	1382	call_user_func_array(
	1383	$handler['callback'],
	1384	$handler['args']
	1385	);
	1386
	1387	array_shift($handler['args']);
	1388	}
	1389	}
	1390	$statusBuffer = self::_byteSubString(
	1391	$statusBuffer,
	1392	$pos + self::_byteLength(PHP_EOL)
	1393	);
	1394	}
	1395	}
	1396
	1397	// write command (to GPG)
	1398	if (in_array($fdCommand, $outputStreams)) {
	1399	$this->_debug('GPG is ready for command data');
	1400
	1401	// send commands
	1402	$chunk = self::_byteSubstring(
	1403	$this->_commandBuffer,
	1404	0,
	1405	self::CHUNK_SIZE
	1406	);
	1407
	1408	$length = self::_byteLength($chunk);
	1409
	1410	$this->_debug(
	1411	'=> about to write ' . $length . ' bytes to GPG command'
	1412	);
	1413
	1414	$length = fwrite($fdCommand, $chunk, $length);
	1415
	1416	$this->_debug('=> wrote ' . $length);
	1417
	1418	$this->_commandBuffer = self::_byteSubstring(
	1419	$this->_commandBuffer,
	1420	$length
	1421	);
	1422	}
	1423
	1424	} // end loop while streams are open
	1425
	1426	$this->_debug('END PROCESSING');
	1427	}
	1428
	1429	// }}}
	1430	// {{{ _openSubprocess()
	1431
	1432	/**
	1433	* Opens an internal GPG subprocess for the current operation
	1434	*
	1435	* Opens a GPG subprocess, then connects the subprocess to some pipes. Sets
	1436	* the private class property {@link Crypt_GPG_Engine::$_process} to
	1437	* the new subprocess.
	1438	*
	1439	* @return void
	1440	*
	1441	* @throws Crypt_GPG_OpenSubprocessException if the subprocess could not be
	1442	* opened.
	1443	*
	1444	* @see Crypt_GPG_Engine::setOperation()
	1445	* @see Crypt_GPG_Engine::_closeSubprocess()
	1446	* @see Crypt_GPG_Engine::$_process
	1447	*/
	1448	private function _openSubprocess()
	1449	{
	1450	$version = $this->getVersion();
	1451
	1452	$env = $_ENV;
	1453
	1454	// Newer versions of GnuPG return localized results. Crypt_GPG only
	1455	// works with English, so set the locale to 'C' for the subprocess.
	1456	$env['LC_ALL'] = 'C';
	1457
	1458	$commandLine = $this->_binary;
	1459
	1460	$defaultArguments = array(
	1461	'--status-fd ' . escapeshellarg(self::FD_STATUS),
	1462	'--command-fd ' . escapeshellarg(self::FD_COMMAND),
	1463	'--no-secmem-warning',
	1464	'--no-tty',
	1465	'--no-default-keyring', // ignored if keying files are not specified
	1466	'--no-options' // prevent creation of ~/.gnupg directory
	1467	);
	1468
	1469	if (version_compare($version, '1.0.7', 'ge')) {
	1470	if (version_compare($version, '2.0.0', 'lt')) {
	1471	$defaultArguments[] = '--no-use-agent';
	1472	}
	1473	$defaultArguments[] = '--no-permission-warning';
	1474	}
	1475
	1476	if (version_compare($version, '1.4.2', 'ge')) {
	1477	$defaultArguments[] = '--exit-on-status-write-error';
	1478	}
	1479
	1480	if (version_compare($version, '1.3.2', 'ge')) {
	1481	$defaultArguments[] = '--trust-model always';
	1482	} else {
	1483	$defaultArguments[] = '--always-trust';
	1484	}
	1485
	1486	$arguments = array_merge($defaultArguments, $this->_arguments);
	1487
	1488	if ($this->_homedir) {
	1489	$arguments[] = '--homedir ' . escapeshellarg($this->_homedir);
	1490
	1491	// the random seed file makes subsequent actions faster so only
	1492	// disable it if we have to.
	1493	if (!is_writeable($this->_homedir)) {
	1494	$arguments[] = '--no-random-seed-file';
	1495	}
	1496	}
	1497
	1498	if ($this->_publicKeyring) {
	1499	$arguments[] = '--keyring ' . escapeshellarg($this->_publicKeyring);
	1500	}
	1501
	1502	if ($this->_privateKeyring) {
	1503	$arguments[] = '--secret-keyring ' .
	1504	escapeshellarg($this->_privateKeyring);
	1505	}
	1506
	1507	if ($this->_trustDb) {
	1508	$arguments[] = '--trustdb-name ' . escapeshellarg($this->_trustDb);
	1509	}
	1510
	1511	$commandLine .= ' ' . implode(' ', $arguments) . ' ' .
	1512	$this->_operation;
	1513
	1514	// Binary operations will not work on Windows with PHP < 5.2.6. This is
	1515	// in case stream_select() ever works on Windows.
	1516	$rb = (version_compare(PHP_VERSION, '5.2.6') < 0) ? 'r' : 'rb';
	1517	$wb = (version_compare(PHP_VERSION, '5.2.6') < 0) ? 'w' : 'wb';
	1518
	1519	$descriptorSpec = array(
	1520	self::FD_INPUT => array('pipe', $rb), // stdin
	1521	self::FD_OUTPUT => array('pipe', $wb), // stdout
	1522	self::FD_ERROR => array('pipe', $wb), // stderr
	1523	self::FD_STATUS => array('pipe', $wb), // status
	1524	self::FD_COMMAND => array('pipe', $rb), // command
	1525	self::FD_MESSAGE => array('pipe', $rb) // message
	1526	);
	1527
	1528	$this->_debug('OPENING SUBPROCESS WITH THE FOLLOWING COMMAND:');
	1529	$this->_debug($commandLine);
	1530
	1531	$this->_process = proc_open(
	1532	$commandLine,
	1533	$descriptorSpec,
	1534	$this->_pipes,
	1535	null,
	1536	$env,
	1537	array('binary_pipes' => true)
	1538	);
	1539
	1540	if (!is_resource($this->_process)) {
	1541	throw new Crypt_GPG_OpenSubprocessException(
	1542	'Unable to open GPG subprocess.', 0, $commandLine);
	1543	}
	1544
	1545	$this->_openPipes = $this->_pipes;
	1546	$this->_errorCode = Crypt_GPG::ERROR_NONE;
	1547	}
	1548
	1549	// }}}
	1550	// {{{ _closeSubprocess()
	1551
	1552	/**
	1553	* Closes a the internal GPG subprocess
	1554	*
	1555	* Closes the internal GPG subprocess. Sets the private class property
	1556	* {@link Crypt_GPG_Engine::$_process} to null.
	1557	*
	1558	* @return void
	1559	*
	1560	* @see Crypt_GPG_Engine::_openSubprocess()
	1561	* @see Crypt_GPG_Engine::$_process
	1562	*/
	1563	private function _closeSubprocess()
	1564	{
	1565	if (is_resource($this->_process)) {
	1566	$this->_debug('CLOSING SUBPROCESS');
	1567
	1568	// close remaining open pipes
	1569	foreach (array_keys($this->_openPipes) as $pipeNumber) {
	1570	$this->_closePipe($pipeNumber);
	1571	}
	1572
	1573	$exitCode = proc_close($this->_process);
	1574
	1575	if ($exitCode != 0) {
	1576	$this->_debug(
	1577	'=> subprocess returned an unexpected exit code: ' .
	1578	$exitCode
	1579	);
	1580
	1581	if ($this->_errorCode === Crypt_GPG::ERROR_NONE) {
	1582	if ($this->_needPassphrase > 0) {
	1583	$this->_errorCode = Crypt_GPG::ERROR_MISSING_PASSPHRASE;
	1584	} else {
	1585	$this->_errorCode = Crypt_GPG::ERROR_UNKNOWN;
	1586	}
	1587	}
	1588	}
	1589
	1590	$this->_process = null;
	1591	$this->_pipes = array();
	1592	}
	1593	}
	1594
	1595	// }}}
	1596	// {{{ _closePipe()
	1597
	1598	/**
	1599	* Closes an opened pipe used to communicate with the GPG subprocess
	1600	*
	1601	* If the pipe is already closed, it is ignored. If the pipe is open, it
	1602	* is flushed and then closed.
	1603	*
	1604	* @param integer $pipeNumber the file descriptor number of the pipe to
	1605	* close.
	1606	*
	1607	* @return void
	1608	*/
	1609	private function _closePipe($pipeNumber)
	1610	{
	1611	$pipeNumber = intval($pipeNumber);
	1612	if (array_key_exists($pipeNumber, $this->_openPipes)) {
	1613	fflush($this->_openPipes[$pipeNumber]);
	1614	fclose($this->_openPipes[$pipeNumber]);
	1615	unset($this->_openPipes[$pipeNumber]);
	1616	}
	1617	}
	1618
	1619	// }}}
	1620	// {{{ _getBinary()
	1621
	1622	/**
	1623	* Gets the name of the GPG binary for the current operating system
	1624	*
	1625	* This method is called if the '<kbd>binary</kbd>' option is <i>not</i>
	1626	* specified when creating this driver.
	1627	*
	1628	* @return string the name of the GPG binary for the current operating
	1629	* system. If no suitable binary could be found, an empty
	1630	* string is returned.
	1631	*/
	1632	private function _getBinary()
	1633	{
	1634	$binary = '';
	1635
	1636	if ($this->_isDarwin) {
	1637	$binaryFiles = array(
	1638	'/opt/local/bin/gpg', // MacPorts
	1639	'/usr/local/bin/gpg', // Mac GPG
	1640	'/sw/bin/gpg', // Fink
	1641	'/usr/bin/gpg'
	1642	);
	1643	} else {
	1644	$binaryFiles = array(
	1645	'/usr/bin/gpg',
	1646	'/usr/local/bin/gpg'
	1647	);
	1648	}
	1649
	1650	foreach ($binaryFiles as $binaryFile) {
	1651	if (is_executable($binaryFile)) {
	1652	$binary = $binaryFile;
	1653	break;
	1654	}
	1655	}
	1656
	1657	return $binary;
	1658	}
	1659
	1660	// }}}
	1661	// {{{ _debug()
	1662
	1663	/**
	1664	* Displays debug text if debugging is turned on
	1665	*
	1666	* Debugging text is prepended with a debug identifier and echoed to stdout.
	1667	*
	1668	* @param string $text the debugging text to display.
	1669	*
	1670	* @return void
	1671	*/
	1672	private function _debug($text)
	1673	{
	1674	if ($this->_debug) {
	1675	if (array_key_exists('SHELL', $_ENV)) {
	1676	foreach (explode(PHP_EOL, $text) as $line) {
	1677	echo "Crypt_GPG DEBUG: ", $line, PHP_EOL;
	1678	}
	1679	} else {
	1680	// running on a web server, format debug output nicely
	1681	foreach (explode(PHP_EOL, $text) as $line) {
	1682	echo "Crypt_GPG DEBUG: <strong>", $line,
	1683	'</strong><br />', PHP_EOL;
	1684	}
	1685	}
	1686	}
	1687	}
	1688
	1689	// }}}
	1690	// {{{ _byteLength()
	1691
	1692	/**
	1693	* Gets the length of a string in bytes even if mbstring function
	1694	* overloading is turned on
	1695	*
	1696	* This is used for stream-based communication with the GPG subprocess.
	1697	*
	1698	* @param string $string the string for which to get the length.
	1699	*
	1700	* @return integer the length of the string in bytes.
	1701	*
	1702	* @see Crypt_GPG_Engine::$_mbStringOverload
	1703	*/
	1704	private static function _byteLength($string)
	1705	{
	1706	if (self::$_mbStringOverload) {
	1707	return mb_strlen($string, '8bit');
	1708	}
	1709
	1710	return strlen((binary)$string);
	1711	}
	1712
	1713	// }}}
	1714	// {{{ _byteSubstring()
	1715
	1716	/**
	1717	* Gets the substring of a string in bytes even if mbstring function
	1718	* overloading is turned on
	1719	*
	1720	* This is used for stream-based communication with the GPG subprocess.
	1721	*
	1722	* @param string $string the input string.
	1723	* @param integer $start the starting point at which to get the substring.
	1724	* @param integer $length optional. The length of the substring.
	1725	*
	1726	* @return string the extracted part of the string. Unlike the default PHP
	1727	* <kbd>substr()</kbd> function, the returned value is
	1728	* always a string and never false.
	1729	*
	1730	* @see Crypt_GPG_Engine::$_mbStringOverload
	1731	*/
	1732	private static function _byteSubstring($string, $start, $length = null)
	1733	{
	1734	if (self::$_mbStringOverload) {
	1735	if ($length === null) {
	1736	return mb_substr(
	1737	$string,
	1738	$start,
	1739	self::_byteLength($string) - $start, '8bit'
	1740	);
	1741	}
	1742
	1743	return mb_substr($string, $start, $length, '8bit');
	1744	}
	1745
	1746	if ($length === null) {
	1747	return (string)substr((binary)$string, $start);
	1748	}
	1749
	1750	return (string)substr((binary)$string, $start, $length);
	1751	}
	1752
	1753	// }}}
	1754	}
	1755
	1756	// }}}
	1757
	1758	?>