Mercurial > hg > rc1

comparison vendor/pear/crypt_gpg/Crypt/GPG.php @ 0:1e000243b222

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
vanilla 1.3.3 distro, I hope
author Charlie Root
date Thu, 04 Jan 2018 15:50:29 -0500
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:1e000243b222
1 <?php
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 package provides an object oriented interface to GNU Privacy
9 * Guard (GPG). It requires the GPG executable to be on the system.
10 *
11 * Though GPG can support symmetric-key cryptography, this package is intended
12 * only to facilitate public-key cryptography.
13 *
14 * This file contains the main GPG class. The class in this file lets you
15 * encrypt, decrypt, sign and verify data; import and delete keys; and perform
16 * other useful GPG tasks.
17 *
18 * Example usage:
19 * <code>
20 * <?php
21 * // encrypt some data
22 * $gpg = new Crypt_GPG();
23 * $gpg->addEncryptKey($mySecretKeyId);
24 * $encryptedData = $gpg->encrypt($data);
25 * ?>
26 * </code>
27 *
28 * PHP version 5
29 *
30 * LICENSE:
31 *
32 * This library is free software; you can redistribute it and/or modify
33 * it under the terms of the GNU Lesser General Public License as
34 * published by the Free Software Foundation; either version 2.1 of the
35 * License, or (at your option) any later version.
36 *
37 * This library is distributed in the hope that it will be useful,
38 * but WITHOUT ANY WARRANTY; without even the implied warranty of
39 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
40 * Lesser General Public License for more details.
41 *
42 * You should have received a copy of the GNU Lesser General Public
43 * License along with this library; if not, see
44 * <http://www.gnu.org/licenses/>
45 *
46 * @category Encryption
47 * @package Crypt_GPG
48 * @author Nathan Fredrickson <nathan@silverorange.com>
49 * @author Michael Gauthier <mike@silverorange.com>
50 * @copyright 2005-2013 silverorange
51 * @license http://www.gnu.org/copyleft/lesser.html LGPL License 2.1
52 * @link http://pear.php.net/package/Crypt_GPG
53 * @link http://pear.php.net/manual/en/package.encryption.crypt-gpg.php
54 * @link http://www.gnupg.org/
55 */
56
57 /**
58 * Base class for GPG methods
59 */
60 require_once 'Crypt/GPGAbstract.php';
61
62 /**
63 * GPG exception classes.
64 */
65 require_once 'Crypt/GPG/Exceptions.php';
66
67 // {{{ class Crypt_GPG
68
69 /**
70 * A class to use GPG from PHP
71 *
72 * This class provides an object oriented interface to GNU Privacy Guard (GPG).
73 *
74 * Though GPG can support symmetric-key cryptography, this class is intended
75 * only to facilitate public-key cryptography.
76 *
77 * @category Encryption
78 * @package Crypt_GPG
79 * @author Nathan Fredrickson <nathan@silverorange.com>
80 * @author Michael Gauthier <mike@silverorange.com>
81 * @copyright 2005-2013 silverorange
82 * @license http://www.gnu.org/copyleft/lesser.html LGPL License 2.1
83 * @link http://pear.php.net/package/Crypt_GPG
84 * @link http://www.gnupg.org/
85 */
86 class Crypt_GPG extends Crypt_GPGAbstract
87 {
88 // {{{ class constants for data signing modes
89
90 /**
91 * Signing mode for normal signing of data. The signed message will not
92 * be readable without special software.
93 *
94 * This is the default signing mode.
95 *
96 * @see Crypt_GPG::sign()
97 * @see Crypt_GPG::signFile()
98 */
99 const SIGN_MODE_NORMAL = 1;
100
101 /**
102 * Signing mode for clearsigning data. Clearsigned signatures are ASCII
103 * armored data and are readable without special software. If the signed
104 * message is unencrypted, the message will still be readable. The message
105 * text will be in the original encoding.
106 *
107 * @see Crypt_GPG::sign()
108 * @see Crypt_GPG::signFile()
109 */
110 const SIGN_MODE_CLEAR = 2;
111
112 /**
113 * Signing mode for creating a detached signature. When using detached
114 * signatures, only the signature data is returned. The original message
115 * text may be distributed separately from the signature data. This is
116 * useful for miltipart/signed email messages as per
117 * {@link http://www.ietf.org/rfc/rfc3156.txt RFC 3156}.
118 *
119 * @see Crypt_GPG::sign()
120 * @see Crypt_GPG::signFile()
121 */
122 const SIGN_MODE_DETACHED = 3;
123
124 // }}}
125 // {{{ class constants for fingerprint formats
126
127 /**
128 * No formatting is performed.
129 *
130 * Example: C3BC615AD9C766E5A85C1F2716D27458B1BBA1C4
131 *
132 * @see Crypt_GPG::getFingerprint()
133 */
134 const FORMAT_NONE = 1;
135
136 /**
137 * Fingerprint is formatted in the format used by the GnuPG gpg command's
138 * default output.
139 *
140 * Example: C3BC 615A D9C7 66E5 A85C 1F27 16D2 7458 B1BB A1C4
141 *
142 * @see Crypt_GPG::getFingerprint()
143 */
144 const FORMAT_CANONICAL = 2;
145
146 /**
147 * Fingerprint is formatted in the format used when displaying X.509
148 * certificates
149 *
150 * Example: C3:BC:61:5A:D9:C7:66:E5:A8:5C:1F:27:16:D2:74:58:B1:BB:A1:C4
151 *
152 * @see Crypt_GPG::getFingerprint()
153 */
154 const FORMAT_X509 = 3;
155
156 // }}}
157 // {{{ class constants for boolean options
158
159 /**
160 * Use to specify ASCII armored mode for returned data
161 */
162 const ARMOR_ASCII = true;
163
164 /**
165 * Use to specify binary mode for returned data
166 */
167 const ARMOR_BINARY = false;
168
169 /**
170 * Use to specify that line breaks in signed text should be normalized
171 */
172 const TEXT_NORMALIZED = true;
173
174 /**
175 * Use to specify that line breaks in signed text should not be normalized
176 */
177 const TEXT_RAW = false;
178
179 // }}}
180 // {{{ protected class properties
181
182 /**
183 * Keys used to encrypt
184 *
185 * The array is of the form:
186 * <code>
187 * array(
188 * $key_id => array(
189 * 'fingerprint' => $fingerprint,
190 * 'passphrase' => null
191 * )
192 * );
193 * </code>
194 *
195 * @var array
196 * @see Crypt_GPG::addEncryptKey()
197 * @see Crypt_GPG::clearEncryptKeys()
198 */
199 protected $encryptKeys = array();
200
201 /**
202 * Keys used to decrypt
203 *
204 * The array is of the form:
205 * <code>
206 * array(
207 * $key_id => array(
208 * 'fingerprint' => $fingerprint,
209 * 'passphrase' => $passphrase
210 * )
211 * );
212 * </code>
213 *
214 * @var array
215 * @see Crypt_GPG::addSignKey()
216 * @see Crypt_GPG::clearSignKeys()
217 */
218 protected $signKeys = array();
219
220 /**
221 * Keys used to sign
222 *
223 * The array is of the form:
224 * <code>
225 * array(
226 * $key_id => array(
227 * 'fingerprint' => $fingerprint,
228 * 'passphrase' => $passphrase
229 * )
230 * );
231 * </code>
232 *
233 * @var array
234 * @see Crypt_GPG::addDecryptKey()
235 * @see Crypt_GPG::clearDecryptKeys()
236 */
237 protected $decryptKeys = array();
238
239 /**
240 * Passphrases used on import/export of private keys in GnuPG 2.1
241 *
242 * The array is of the form:
243 * <code>
244 * array($key_id => $passphrase);
245 * </code>
246 *
247 * @var array
248 * @see Crypt_GPG::addPassphrase()
249 * @see Crypt_GPG::clearPassphrases()
250 */
251 protected $passphrases = array();
252
253 // }}}
254 // {{{ importKey()
255
256 /**
257 * Imports a public or private key into the keyring
258 *
259 * Keys may be removed from the keyring using
260 * {@link Crypt_GPG::deletePublicKey()} or
261 * {@link Crypt_GPG::deletePrivateKey()}.
262 *
263 * @param string $data the key data to be imported.
264 *
265 * @return array an associative array containing the following elements:
266 * - <kbd>fingerprint</kbd> - the fingerprint of the
267 * imported key,
268 * - <kbd>public_imported</kbd> - the number of public
269 * keys imported,
270 * - <kbd>public_unchanged</kbd> - the number of unchanged
271 * public keys,
272 * - <kbd>private_imported</kbd> - the number of private
273 * keys imported,
274 * - <kbd>private_unchanged</kbd> - the number of unchanged
275 * private keys.
276 *
277 * @throws Crypt_GPG_NoDataException if the key data is missing or if the
278 * data is is not valid key data.
279 *
280 * @throws Crypt_GPG_BadPassphraseException if a required passphrase is
281 * incorrect or if a required passphrase is not specified. See
282 * {@link Crypt_GPG::addPassphrase()}.
283 *
284 * @throws Crypt_GPG_Exception if an unknown or unexpected error occurs.
285 * Use the <kbd>debug</kbd> option and file a bug report if these
286 * exceptions occur.
287 *
288 * @see Crypt_GPG::addPassphrase()
289 * @see Crypt_GPG::clearPassphrases()
290 */
291 public function importKey($data)
292 {
293 return $this->_importKey($data, false);
294 }
295
296 // }}}
297 // {{{ importKeyFile()
298
299 /**
300 * Imports a public or private key file into the keyring
301 *
302 * Keys may be removed from the keyring using
303 * {@link Crypt_GPG::deletePublicKey()} or
304 * {@link Crypt_GPG::deletePrivateKey()}.
305 *
306 * @param string $filename the key file to be imported.
307 *
308 * @return array an associative array containing the following elements:
309 * - <kbd>fingerprint</kbd> - the fingerprint of the
310 * imported key,
311 * - <kbd>public_imported</kbd> - the number of public
312 * keys imported,
313 * - <kbd>public_unchanged</kbd> - the number of unchanged
314 * public keys,
315 * - <kbd>private_imported</kbd> - the number of private
316 * keys imported,
317 * - <kbd>private_unchanged</kbd> - the number of unchanged
318 * private keys.
319 * private keys.
320 *
321 * @throws Crypt_GPG_NoDataException if the key data is missing or if the
322 * data is is not valid key data.
323 *
324 * @throws Crypt_GPG_FileException if the key file is not readable.
325 *
326 * @throws Crypt_GPG_BadPassphraseException if a required passphrase is
327 * incorrect or if a required passphrase is not specified. See
328 * {@link Crypt_GPG::addPassphrase()}.
329 *
330 * @throws Crypt_GPG_Exception if an unknown or unexpected error occurs.
331 * Use the <kbd>debug</kbd> option and file a bug report if these
332 * exceptions occur.
333 */
334 public function importKeyFile($filename)
335 {
336 return $this->_importKey($filename, true);
337 }
338
339 // }}}
340 // {{{ exportPrivateKey()
341
342 /**
343 * Exports a private key from the keyring
344 *
345 * The exported key remains on the keyring. To delete the key, use
346 * {@link Crypt_GPG::deletePrivateKey()}.
347 *
348 * If more than one key fingerprint is available for the specified
349 * <kbd>$keyId</kbd> (for example, if you use a non-unique uid) only the
350 * first private key is exported.
351 *
352 * @param string $keyId either the full uid of the private key, the email
353 * part of the uid of the private key or the key id of
354 * the private key. For example,
355 * "Test User (example) <test@example.com>",
356 * "test@example.com" or a hexadecimal string.
357 * @param boolean $armor optional. If true, ASCII armored data is returned;
358 * otherwise, binary data is returned. Defaults to
359 * true.
360 *
361 * @return string the private key data.
362 *
363 * @throws Crypt_GPG_KeyNotFoundException if a private key with the given
364 * <kbd>$keyId</kbd> is not found.
365 *
366 * @throws Crypt_GPG_BadPassphraseException if a required passphrase is
367 * incorrect or if a required passphrase is not specified. See
368 * {@link Crypt_GPG::addPassphrase()}.
369 *
370 * @throws Crypt_GPG_Exception if an unknown or unexpected error occurs.
371 * Use the <kbd>debug</kbd> option and file a bug report if these
372 * exceptions occur.
373 */
374 public function exportPrivateKey($keyId, $armor = true)
375 {
376 return $this->_exportKey($keyId, $armor, true);
377 }
378
379 // }}}
380 // {{{ exportPublicKey()
381
382 /**
383 * Exports a public key from the keyring
384 *
385 * The exported key remains on the keyring. To delete the public key, use
386 * {@link Crypt_GPG::deletePublicKey()}.
387 *
388 * If more than one key fingerprint is available for the specified
389 * <kbd>$keyId</kbd> (for example, if you use a non-unique uid) only the
390 * first public key is exported.
391 *
392 * @param string $keyId either the full uid of the public key, the email
393 * part of the uid of the public key or the key id of
394 * the public key. For example,
395 * "Test User (example) <test@example.com>",
396 * "test@example.com" or a hexadecimal string.
397 * @param boolean $armor optional. If true, ASCII armored data is returned;
398 * otherwise, binary data is returned. Defaults to
399 * true.
400 *
401 * @return string the public key data.
402 *
403 * @throws Crypt_GPG_KeyNotFoundException if a public key with the given
404 * <kbd>$keyId</kbd> is not found.
405 *
406 * @throws Crypt_GPG_Exception if an unknown or unexpected error occurs.
407 * Use the <kbd>debug</kbd> option and file a bug report if these
408 * exceptions occur.
409 */
410 public function exportPublicKey($keyId, $armor = true)
411 {
412 return $this->_exportKey($keyId, $armor, false);
413 }
414
415 // }}}
416 // {{{ deletePublicKey()
417
418 /**
419 * Deletes a public key from the keyring
420 *
421 * If more than one key fingerprint is available for the specified
422 * <kbd>$keyId</kbd> (for example, if you use a non-unique uid) only the
423 * first public key is deleted.
424 *
425 * The private key must be deleted first or an exception will be thrown.
426 * In GnuPG >= 2.1 this limitation does not exist.
427 * See {@link Crypt_GPG::deletePrivateKey()}.
428 *
429 * @param string $keyId either the full uid of the public key, the email
430 * part of the uid of the public key or the key id of
431 * the public key. For example,
432 * "Test User (example) <test@example.com>",
433 * "test@example.com" or a hexadecimal string.
434 *
435 * @return void
436 *
437 * @throws Crypt_GPG_KeyNotFoundException if a public key with the given
438 * <kbd>$keyId</kbd> is not found.
439 *
440 * @throws Crypt_GPG_DeletePrivateKeyException if the specified public key
441 * has an associated private key on the keyring. The private key
442 * must be deleted first (when using GnuPG < 2.1).
443 *
444 * @throws Crypt_GPG_Exception if an unknown or unexpected error occurs.
445 * Use the <kbd>debug</kbd> option and file a bug report if these
446 * exceptions occur.
447 */
448 public function deletePublicKey($keyId)
449 {
450 $fingerprint = $this->getFingerprint($keyId);
451
452 if ($fingerprint === null) {
453 throw new Crypt_GPG_KeyNotFoundException(
454 'Public key not found: ' . $keyId,
455 self::ERROR_KEY_NOT_FOUND,
456 $keyId
457 );
458 }
459
460 $operation = '--delete-key ' . escapeshellarg($fingerprint);
461 $arguments = array(
462 '--batch',
463 '--yes'
464 );
465
466 $this->engine->reset();
467 $this->engine->setOperation($operation, $arguments);
468 $this->engine->run();
469 }
470
471 // }}}
472 // {{{ deletePrivateKey()
473
474 /**
475 * Deletes a private key from the keyring
476 *
477 * If more than one key fingerprint is available for the specified
478 * <kbd>$keyId</kbd> (for example, if you use a non-unique uid) only the
479 * first private key is deleted.
480 *
481 * Calls GPG with the <kbd>--delete-secret-key</kbd> command.
482 *
483 * @param string $keyId either the full uid of the private key, the email
484 * part of the uid of the private key or the key id of
485 * the private key. For example,
486 * "Test User (example) <test@example.com>",
487 * "test@example.com" or a hexadecimal string.
488 *
489 * @return void
490 *
491 * @throws Crypt_GPG_KeyNotFoundException if a private key with the given
492 * <kbd>$keyId</kbd> is not found.
493 *
494 * @throws Crypt_GPG_Exception if an unknown or unexpected error occurs.
495 * Use the <kbd>debug</kbd> option and file a bug report if these
496 * exceptions occur.
497 */
498 public function deletePrivateKey($keyId)
499 {
500 $fingerprint = $this->getFingerprint($keyId);
501
502 if ($fingerprint === null) {
503 throw new Crypt_GPG_KeyNotFoundException(
504 'Private key not found: ' . $keyId,
505 self::ERROR_KEY_NOT_FOUND,
506 $keyId
507 );
508 }
509
510 $operation = '--delete-secret-key ' . escapeshellarg($fingerprint);
511 $arguments = array(
512 '--batch',
513 '--yes'
514 );
515
516 $this->engine->reset();
517 $this->engine->setOperation($operation, $arguments);
518 $this->engine->run();
519 }
520
521 // }}}
522 // {{{ getKeys()
523
524 /**
525 * Gets the available keys in the keyring
526 *
527 * Calls GPG with the <kbd>--list-keys</kbd> command and grabs keys. See
528 * the first section of <b>doc/DETAILS</b> in the
529 * {@link http://www.gnupg.org/download/ GPG package} for a detailed
530 * description of how the GPG command output is parsed.
531 *
532 * @param string $keyId optional. Only keys with that match the specified
533 * pattern are returned. The pattern may be part of
534 * a user id, a key id or a key fingerprint. If not
535 * specified, all keys are returned.
536 *
537 * @return array an array of {@link Crypt_GPG_Key} objects. If no keys
538 * match the specified <kbd>$keyId</kbd> an empty array is
539 * returned.
540 *
541 * @throws Crypt_GPG_Exception if an unknown or unexpected error occurs.
542 * Use the <kbd>debug</kbd> option and file a bug report if these
543 * exceptions occur.
544 *
545 * @see Crypt_GPG_Key
546 */
547 public function getKeys($keyId = '')
548 {
549 return parent::_getKeys($keyId);
550 }
551
552 // }}}
553 // {{{ getFingerprint()
554
555 /**
556 * Gets a key fingerprint from the keyring
557 *
558 * If more than one key fingerprint is available (for example, if you use
559 * a non-unique user id) only the first key fingerprint is returned.
560 *
561 * Calls the GPG <kbd>--list-keys</kbd> command with the
562 * <kbd>--with-fingerprint</kbd> option to retrieve a public key
563 * fingerprint.
564 *
565 * @param string $keyId either the full user id of the key, the email
566 * part of the user id of the key, or the key id of
567 * the key. For example,
568 * "Test User (example) <test@example.com>",
569 * "test@example.com" or a hexadecimal string.
570 * @param integer $format optional. How the fingerprint should be formatted.
571 * Use {@link Crypt_GPG::FORMAT_X509} for X.509
572 * certificate format,
573 * {@link Crypt_GPG::FORMAT_CANONICAL} for the format
574 * used by GnuPG output and
575 * {@link Crypt_GPG::FORMAT_NONE} for no formatting.
576 * Defaults to <code>Crypt_GPG::FORMAT_NONE</code>.
577 *
578 * @return string the fingerprint of the key, or null if no fingerprint
579 * is found for the given <kbd>$keyId</kbd>.
580 *
581 * @throws Crypt_GPG_Exception if an unknown or unexpected error occurs.
582 * Use the <kbd>debug</kbd> option and file a bug report if these
583 * exceptions occur.
584 */
585 public function getFingerprint($keyId, $format = self::FORMAT_NONE)
586 {
587 $output = '';
588 $operation = '--list-keys ' . escapeshellarg($keyId);
589 $arguments = array(
590 '--with-colons',
591 '--with-fingerprint'
592 );
593
594 $this->engine->reset();
595 $this->engine->setOutput($output);
596 $this->engine->setOperation($operation, $arguments);
597 $this->engine->run();
598
599 $fingerprint = null;
600
601 foreach (explode(PHP_EOL, $output) as $line) {
602 if (mb_substr($line, 0, 3, '8bit') == 'fpr') {
603 $lineExp = explode(':', $line);
604 $fingerprint = $lineExp[9];
605
606 switch ($format) {
607 case self::FORMAT_CANONICAL:
608 $fingerprintExp = str_split($fingerprint, 4);
609 $format = '%s %s %s %s %s %s %s %s %s %s';
610 $fingerprint = vsprintf($format, $fingerprintExp);
611 break;
612
613 case self::FORMAT_X509:
614 $fingerprintExp = str_split($fingerprint, 2);
615 $fingerprint = implode(':', $fingerprintExp);
616 break;
617 }
618
619 break;
620 }
621 }
622
623 return $fingerprint;
624 }
625
626 // }}}
627 // {{{ getLastSignatureInfo()
628
629 /**
630 * Get information about the last signature that was created.
631 *
632 * @return Crypt_GPG_SignatureCreationInfo
633 */
634 public function getLastSignatureInfo()
635 {
636 return $this->engine->getProcessData('SignatureInfo');
637 }
638
639 // }}}
640 // {{{ encrypt()
641
642 /**
643 * Encrypts string data
644 *
645 * Data is ASCII armored by default but may optionally be returned as
646 * binary.
647 *
648 * @param string $data the data to be encrypted.
649 * @param boolean $armor optional. If true, ASCII armored data is returned;
650 * otherwise, binary data is returned. Defaults to
651 * true.
652 *
653 * @return string the encrypted data.
654 *
655 * @throws Crypt_GPG_KeyNotFoundException if no encryption key is specified.
656 * See {@link Crypt_GPG::addEncryptKey()}.
657 *
658 * @throws Crypt_GPG_Exception if an unknown or unexpected error occurs.
659 * Use the <kbd>debug</kbd> option and file a bug report if these
660 * exceptions occur.
661 *
662 * @sensitive $data
663 */
664 public function encrypt($data, $armor = self::ARMOR_ASCII)
665 {
666 return $this->_encrypt($data, false, null, $armor);
667 }
668
669 // }}}
670 // {{{ encryptFile()
671
672 /**
673 * Encrypts a file
674 *
675 * Encrypted data is ASCII armored by default but may optionally be saved
676 * as binary.
677 *
678 * @param string $filename the filename of the file to encrypt.
679 * @param string $encryptedFile optional. The filename of the file in
680 * which to store the encrypted data. If null
681 * or unspecified, the encrypted data is
682 * returned as a string.
683 * @param boolean $armor optional. If true, ASCII armored data is
684 * returned; otherwise, binary data is
685 * returned. Defaults to true.
686 *
687 * @return void|string if the <kbd>$encryptedFile</kbd> parameter is null,
688 * a string containing the encrypted data is returned.
689 *
690 * @throws Crypt_GPG_KeyNotFoundException if no encryption key is specified.
691 * See {@link Crypt_GPG::addEncryptKey()}.
692 *
693 * @throws Crypt_GPG_FileException if the output file is not writeable or
694 * if the input file is not readable.
695 *
696 * @throws Crypt_GPG_Exception if an unknown or unexpected error occurs.
697 * Use the <kbd>debug</kbd> option and file a bug report if these
698 * exceptions occur.
699 */
700 public function encryptFile(
701 $filename,
702 $encryptedFile = null,
703 $armor = self::ARMOR_ASCII
704 ) {
705 return $this->_encrypt($filename, true, $encryptedFile, $armor);
706 }
707
708 // }}}
709 // {{{ encryptAndSign()
710
711 /**
712 * Encrypts and signs data
713 *
714 * Data is encrypted and signed in a single pass.
715 *
716 * NOTE: Until GnuPG version 1.4.10, it was not possible to verify
717 * encrypted-signed data without decrypting it at the same time. If you try
718 * to use {@link Crypt_GPG::verify()} method on encrypted-signed data with
719 * earlier GnuPG versions, you will get an error. Please use
720 * {@link Crypt_GPG::decryptAndVerify()} to verify encrypted-signed data.
721 *
722 * @param string $data the data to be encrypted and signed.
723 * @param boolean $armor optional. If true, ASCII armored data is returned;
724 * otherwise, binary data is returned. Defaults to
725 * true.
726 *
727 * @return string the encrypted signed data.
728 *
729 * @throws Crypt_GPG_KeyNotFoundException if no encryption key is specified
730 * or if no signing key is specified. See
731 * {@link Crypt_GPG::addEncryptKey()} and
732 * {@link Crypt_GPG::addSignKey()}.
733 *
734 * @throws Crypt_GPG_BadPassphraseException if a specified passphrase is
735 * incorrect or if a required passphrase is not specified.
736 *
737 * @throws Crypt_GPG_Exception if an unknown or unexpected error occurs.
738 * Use the <kbd>debug</kbd> option and file a bug report if these
739 * exceptions occur.
740 *
741 * @see Crypt_GPG::decryptAndVerify()
742 */
743 public function encryptAndSign($data, $armor = self::ARMOR_ASCII)
744 {
745 return $this->_encryptAndSign($data, false, null, $armor);
746 }
747
748 // }}}
749 // {{{ encryptAndSignFile()
750
751 /**
752 * Encrypts and signs a file
753 *
754 * The file is encrypted and signed in a single pass.
755 *
756 * NOTE: Until GnuPG version 1.4.10, it was not possible to verify
757 * encrypted-signed files without decrypting them at the same time. If you
758 * try to use {@link Crypt_GPG::verify()} method on encrypted-signed files
759 * with earlier GnuPG versions, you will get an error. Please use
760 * {@link Crypt_GPG::decryptAndVerifyFile()} to verify encrypted-signed
761 * files.
762 *
763 * @param string $filename the name of the file containing the data to
764 * be encrypted and signed.
765 * @param string $signedFile optional. The name of the file in which the
766 * encrypted, signed data should be stored. If
767 * null or unspecified, the encrypted, signed
768 * data is returned as a string.
769 * @param boolean $armor optional. If true, ASCII armored data is
770 * returned; otherwise, binary data is returned.
771 * Defaults to true.
772 *
773 * @return void|string if the <kbd>$signedFile</kbd> parameter is null, a
774 * string containing the encrypted, signed data is
775 * returned.
776 *
777 * @throws Crypt_GPG_KeyNotFoundException if no encryption key is specified
778 * or if no signing key is specified. See
779 * {@link Crypt_GPG::addEncryptKey()} and
780 * {@link Crypt_GPG::addSignKey()}.
781 *
782 * @throws Crypt_GPG_BadPassphraseException if a specified passphrase is
783 * incorrect or if a required passphrase is not specified.
784 *
785 * @throws Crypt_GPG_FileException if the output file is not writeable or
786 * if the input file is not readable.
787 *
788 * @throws Crypt_GPG_Exception if an unknown or unexpected error occurs.
789 * Use the <kbd>debug</kbd> option and file a bug report if these
790 * exceptions occur.
791 *
792 * @see Crypt_GPG::decryptAndVerifyFile()
793 */
794 public function encryptAndSignFile(
795 $filename,
796 $signedFile = null,
797 $armor = self::ARMOR_ASCII
798 ) {
799 return $this->_encryptAndSign($filename, true, $signedFile, $armor);
800 }
801
802 // }}}
803 // {{{ decrypt()
804
805 /**
806 * Decrypts string data
807 *
808 * This method assumes the required private key is available in the keyring
809 * and throws an exception if the private key is not available. To add a
810 * private key to the keyring, use the {@link Crypt_GPG::importKey()} or
811 * {@link Crypt_GPG::importKeyFile()} methods.
812 *
813 * @param string $encryptedData the data to be decrypted.
814 *
815 * @return string the decrypted data.
816 *
817 * @throws Crypt_GPG_KeyNotFoundException if the private key needed to
818 * decrypt the data is not in the user's keyring.
819 *
820 * @throws Crypt_GPG_NoDataException if specified data does not contain
821 * GPG encrypted data.
822 *
823 * @throws Crypt_GPG_BadPassphraseException if a required passphrase is
824 * incorrect or if a required passphrase is not specified. See
825 * {@link Crypt_GPG::addDecryptKey()}.
826 *
827 * @throws Crypt_GPG_Exception if an unknown or unexpected error occurs.
828 * Use the <kbd>debug</kbd> option and file a bug report if these
829 * exceptions occur.
830 */
831 public function decrypt($encryptedData)
832 {
833 return $this->_decrypt($encryptedData, false, null);
834 }
835
836 // }}}
837 // {{{ decryptFile()
838
839 /**
840 * Decrypts a file
841 *
842 * This method assumes the required private key is available in the keyring
843 * and throws an exception if the private key is not available. To add a
844 * private key to the keyring, use the {@link Crypt_GPG::importKey()} or
845 * {@link Crypt_GPG::importKeyFile()} methods.
846 *
847 * @param string $encryptedFile the name of the encrypted file data to
848 * decrypt.
849 * @param string $decryptedFile optional. The name of the file to which the
850 * decrypted data should be written. If null
851 * or unspecified, the decrypted data is
852 * returned as a string.
853 *
854 * @return void|string if the <kbd>$decryptedFile</kbd> parameter is null,
855 * a string containing the decrypted data is returned.
856 *
857 * @throws Crypt_GPG_KeyNotFoundException if the private key needed to
858 * decrypt the data is not in the user's keyring.
859 *
860 * @throws Crypt_GPG_NoDataException if specified data does not contain
861 * GPG encrypted data.
862 *
863 * @throws Crypt_GPG_BadPassphraseException if a required passphrase is
864 * incorrect or if a required passphrase is not specified. See
865 * {@link Crypt_GPG::addDecryptKey()}.
866 *
867 * @throws Crypt_GPG_FileException if the output file is not writeable or
868 * if the input file is not readable.
869 *
870 * @throws Crypt_GPG_Exception if an unknown or unexpected error occurs.
871 * Use the <kbd>debug</kbd> option and file a bug report if these
872 * exceptions occur.
873 */
874 public function decryptFile($encryptedFile, $decryptedFile = null)
875 {
876 return $this->_decrypt($encryptedFile, true, $decryptedFile);
877 }
878
879 // }}}
880 // {{{ decryptAndVerify()
881
882 /**
883 * Decrypts and verifies string data
884 *
885 * This method assumes the required private key is available in the keyring
886 * and throws an exception if the private key is not available. To add a
887 * private key to the keyring, use the {@link Crypt_GPG::importKey()} or
888 * {@link Crypt_GPG::importKeyFile()} methods.
889 *
890 * @param string $encryptedData the encrypted, signed data to be decrypted
891 * and verified.
892 * @param boolean $ignoreVerifyErrors enables ignoring of signature
893 * verification errors caused by missing public key
894 * When enabled Crypt_GPG_KeyNotFoundException
895 * will not be thrown.
896 *
897 * @return array two element array. The array has an element 'data'
898 * containing the decrypted data and an element
899 * 'signatures' containing an array of
900 * {@link Crypt_GPG_Signature} objects for the signed data.
901 *
902 * @throws Crypt_GPG_KeyNotFoundException if the private key needed to
903 * decrypt the data or the public key to verify the signature
904 * is not in the user's keyring.
905 *
906 * @throws Crypt_GPG_NoDataException if specified data does not contain
907 * GPG encrypted data.
908 *
909 * @throws Crypt_GPG_BadPassphraseException if a required passphrase is
910 * incorrect or if a required passphrase is not specified. See
911 * {@link Crypt_GPG::addDecryptKey()}.
912 *
913 * @throws Crypt_GPG_Exception if an unknown or unexpected error occurs.
914 * Use the <kbd>debug</kbd> option and file a bug report if these
915 * exceptions occur.
916 */
917 public function decryptAndVerify($encryptedData, $ignoreVerifyErrors = false)
918 {
919 return $this->_decryptAndVerify($encryptedData, false, null, $ignoreVerifyErrors);
920 }
921
922 // }}}
923 // {{{ decryptAndVerifyFile()
924
925 /**
926 * Decrypts and verifies a signed, encrypted file
927 *
928 * This method assumes the required private key is available in the keyring
929 * and throws an exception if the private key is not available. To add a
930 * private key to the keyring, use the {@link Crypt_GPG::importKey()} or
931 * {@link Crypt_GPG::importKeyFile()} methods.
932 *
933 * @param string $encryptedFile the name of the signed, encrypted file to
934 * to decrypt and verify.
935 * @param string $decryptedFile optional. The name of the file to which the
936 * decrypted data should be written. If null
937 * or unspecified, the decrypted data is
938 * returned in the results array.
939 * @param boolean $ignoreVerifyErrors enables ignoring of signature
940 * verification errors caused by missing public key
941 * When enabled Crypt_GPG_KeyNotFoundException
942 * will not be thrown.
943 *
944 * @return array two element array. The array has an element 'data'
945 * containing the decrypted data and an element
946 * 'signatures' containing an array of
947 * {@link Crypt_GPG_Signature} objects for the signed data.
948 * If the decrypted data is written to a file, the 'data'
949 * element is null.
950 *
951 * @throws Crypt_GPG_KeyNotFoundException if the private key needed to
952 * decrypt the data or the public key to verify the signature
953 * is not in the user's keyring.
954 *
955 * @throws Crypt_GPG_NoDataException if specified data does not contain
956 * GPG encrypted data.
957 *
958 * @throws Crypt_GPG_BadPassphraseException if a required passphrase is
959 * incorrect or if a required passphrase is not specified. See
960 * {@link Crypt_GPG::addDecryptKey()}.
961 *
962 * @throws Crypt_GPG_FileException if the output file is not writeable or
963 * if the input file is not readable.
964 *
965 * @throws Crypt_GPG_Exception if an unknown or unexpected error occurs.
966 * Use the <kbd>debug</kbd> option and file a bug report if these
967 * exceptions occur.
968 */
969 public function decryptAndVerifyFile($encryptedFile, $decryptedFile = null, $ignoreVerifyErrors = false)
970 {
971 return $this->_decryptAndVerify($encryptedFile, true, $decryptedFile, $ignoreVerifyErrors);
972 }
973
974 // }}}
975 // {{{ sign()
976
977 /**
978 * Signs data
979 *
980 * Data may be signed using any one of the three available signing modes:
981 * - {@link Crypt_GPG::SIGN_MODE_NORMAL}
982 * - {@link Crypt_GPG::SIGN_MODE_CLEAR}
983 * - {@link Crypt_GPG::SIGN_MODE_DETACHED}
984 *
985 * @param string $data the data to be signed.
986 * @param boolean $mode optional. The data signing mode to use. Should
987 * be one of {@link Crypt_GPG::SIGN_MODE_NORMAL},
988 * {@link Crypt_GPG::SIGN_MODE_CLEAR} or
989 * {@link Crypt_GPG::SIGN_MODE_DETACHED}. If not
990 * specified, defaults to
991 * <kbd>Crypt_GPG::SIGN_MODE_NORMAL</kbd>.
992 * @param boolean $armor optional. If true, ASCII armored data is
993 * returned; otherwise, binary data is returned.
994 * Defaults to true. This has no effect if the
995 * mode <kbd>Crypt_GPG::SIGN_MODE_CLEAR</kbd> is
996 * used.
997 * @param boolean $textmode optional. If true, line-breaks in signed data
998 * are normalized. Use this option when signing
999 * e-mail, or for greater compatibility between
1000 * systems with different line-break formats.
1001 * Defaults to false. This has no effect if the
1002 * mode <kbd>Crypt_GPG::SIGN_MODE_CLEAR</kbd> is
1003 * used as clear-signing always uses textmode.
1004 *
1005 * @return string the signed data, or the signature data if a detached
1006 * signature is requested.
1007 *
1008 * @throws Crypt_GPG_KeyNotFoundException if no signing key is specified.
1009 * See {@link Crypt_GPG::addSignKey()}.
1010 *
1011 * @throws Crypt_GPG_BadPassphraseException if a specified passphrase is
1012 * incorrect or if a required passphrase is not specified.
1013 *
1014 * @throws Crypt_GPG_Exception if an unknown or unexpected error occurs.
1015 * Use the <kbd>debug</kbd> option and file a bug report if these
1016 * exceptions occur.
1017 */
1018 public function sign(
1019 $data,
1020 $mode = self::SIGN_MODE_NORMAL,
1021 $armor = self::ARMOR_ASCII,
1022 $textmode = self::TEXT_RAW
1023 ) {
1024 return $this->_sign($data, false, null, $mode, $armor, $textmode);
1025 }
1026
1027 // }}}
1028 // {{{ signFile()
1029
1030 /**
1031 * Signs a file
1032 *
1033 * The file may be signed using any one of the three available signing
1034 * modes:
1035 * - {@link Crypt_GPG::SIGN_MODE_NORMAL}
1036 * - {@link Crypt_GPG::SIGN_MODE_CLEAR}
1037 * - {@link Crypt_GPG::SIGN_MODE_DETACHED}
1038 *
1039 * @param string $filename the name of the file containing the data to
1040 * be signed.
1041 * @param string $signedFile optional. The name of the file in which the
1042 * signed data should be stored. If null or
1043 * unspecified, the signed data is returned as a
1044 * string.
1045 * @param boolean $mode optional. The data signing mode to use. Should
1046 * be one of {@link Crypt_GPG::SIGN_MODE_NORMAL},
1047 * {@link Crypt_GPG::SIGN_MODE_CLEAR} or
1048 * {@link Crypt_GPG::SIGN_MODE_DETACHED}. If not
1049 * specified, defaults to
1050 * <kbd>Crypt_GPG::SIGN_MODE_NORMAL</kbd>.
1051 * @param boolean $armor optional. If true, ASCII armored data is
1052 * returned; otherwise, binary data is returned.
1053 * Defaults to true. This has no effect if the
1054 * mode <kbd>Crypt_GPG::SIGN_MODE_CLEAR</kbd> is
1055 * used.
1056 * @param boolean $textmode optional. If true, line-breaks in signed data
1057 * are normalized. Use this option when signing
1058 * e-mail, or for greater compatibility between
1059 * systems with different line-break formats.
1060 * Defaults to false. This has no effect if the
1061 * mode <kbd>Crypt_GPG::SIGN_MODE_CLEAR</kbd> is
1062 * used as clear-signing always uses textmode.
1063 *
1064 * @return void|string if the <kbd>$signedFile</kbd> parameter is null, a
1065 * string containing the signed data (or the signature
1066 * data if a detached signature is requested) is
1067 * returned.
1068 *
1069 * @throws Crypt_GPG_KeyNotFoundException if no signing key is specified.
1070 * See {@link Crypt_GPG::addSignKey()}.
1071 *
1072 * @throws Crypt_GPG_BadPassphraseException if a specified passphrase is
1073 * incorrect or if a required passphrase is not specified.
1074 *
1075 * @throws Crypt_GPG_FileException if the output file is not writeable or
1076 * if the input file is not readable.
1077 *
1078 * @throws Crypt_GPG_Exception if an unknown or unexpected error occurs.
1079 * Use the <kbd>debug</kbd> option and file a bug report if these
1080 * exceptions occur.
1081 */
1082 public function signFile(
1083 $filename,
1084 $signedFile = null,
1085 $mode = self::SIGN_MODE_NORMAL,
1086 $armor = self::ARMOR_ASCII,
1087 $textmode = self::TEXT_RAW
1088 ) {
1089 return $this->_sign(
1090 $filename,
1091 true,
1092 $signedFile,
1093 $mode,
1094 $armor,
1095 $textmode
1096 );
1097 }
1098
1099 // }}}
1100 // {{{ verify()
1101
1102 /**
1103 * Verifies signed data
1104 *
1105 * The {@link Crypt_GPG::decrypt()} method may be used to get the original
1106 * message if the signed data is not clearsigned and does not use a
1107 * detached signature.
1108 *
1109 * @param string $signedData the signed data to be verified.
1110 * @param string $signature optional. If verifying data signed using a
1111 * detached signature, this must be the detached
1112 * signature data. The data that was signed is
1113 * specified in <kbd>$signedData</kbd>.
1114 *
1115 * @return array an array of {@link Crypt_GPG_Signature} objects for the
1116 * signed data. For each signature that is valid, the
1117 * {@link Crypt_GPG_Signature::isValid()} will return true.
1118 *
1119 * @throws Crypt_GPG_KeyNotFoundException if the public key needed for
1120 * signature verification is not in the user's keyring.
1121 *
1122 * @throws Crypt_GPG_NoDataException if the provided data is not signed
1123 * data.
1124 *
1125 * @throws Crypt_GPG_Exception if an unknown or unexpected error occurs.
1126 * Use the <kbd>debug</kbd> option and file a bug report if these
1127 * exceptions occur.
1128 *
1129 * @see Crypt_GPG_Signature
1130 */
1131 public function verify($signedData, $signature = '')
1132 {
1133 return $this->_verify($signedData, false, $signature);
1134 }
1135
1136 // }}}
1137 // {{{ verifyFile()
1138
1139 /**
1140 * Verifies a signed file
1141 *
1142 * The {@link Crypt_GPG::decryptFile()} method may be used to get the
1143 * original message if the signed data is not clearsigned and does not use
1144 * a detached signature.
1145 *
1146 * @param string $filename the signed file to be verified.
1147 * @param string $signature optional. If verifying a file signed using a
1148 * detached signature, this must be the detached
1149 * signature data. The file that was signed is
1150 * specified in <kbd>$filename</kbd>.
1151 *
1152 * @return array an array of {@link Crypt_GPG_Signature} objects for the
1153 * signed data. For each signature that is valid, the
1154 * {@link Crypt_GPG_Signature::isValid()} will return true.
1155 *
1156 * @throws Crypt_GPG_KeyNotFoundException if the public key needed for
1157 * signature verification is not in the user's keyring.
1158 *
1159 * @throws Crypt_GPG_NoDataException if the provided data is not signed
1160 * data.
1161 *
1162 * @throws Crypt_GPG_FileException if the input file is not readable.
1163 *
1164 * @throws Crypt_GPG_Exception if an unknown or unexpected error occurs.
1165 * Use the <kbd>debug</kbd> option and file a bug report if these
1166 * exceptions occur.
1167 *
1168 * @see Crypt_GPG_Signature
1169 */
1170 public function verifyFile($filename, $signature = '')
1171 {
1172 return $this->_verify($filename, true, $signature);
1173 }
1174
1175 // }}}
1176 // {{{ addDecryptKey()
1177
1178 /**
1179 * Adds a key to use for decryption
1180 *
1181 * @param mixed $key the key to use. This may be a key identifier,
1182 * user id, fingerprint, {@link Crypt_GPG_Key} or
1183 * {@link Crypt_GPG_SubKey}. The key must be able
1184 * to encrypt.
1185 * @param string $passphrase optional. The passphrase of the key required
1186 * for decryption.
1187 *
1188 * @return Crypt_GPG the current object, for fluent interface.
1189 *
1190 * @see Crypt_GPG::decrypt()
1191 * @see Crypt_GPG::decryptFile()
1192 * @see Crypt_GPG::clearDecryptKeys()
1193 * @see Crypt_GPG::_addKey()
1194 *
1195 * @sensitive $passphrase
1196 */
1197 public function addDecryptKey($key, $passphrase = null)
1198 {
1199 $this->_addKey($this->decryptKeys, false, false, $key, $passphrase);
1200 return $this;
1201 }
1202
1203 // }}}
1204 // {{{ addEncryptKey()
1205
1206 /**
1207 * Adds a key to use for encryption
1208 *
1209 * @param mixed $key the key to use. This may be a key identifier, user id
1210 * user id, fingerprint, {@link Crypt_GPG_Key} or
1211 * {@link Crypt_GPG_SubKey}. The key must be able to
1212 * encrypt.
1213 *
1214 * @return Crypt_GPG the current object, for fluent interface.
1215 *
1216 * @see Crypt_GPG::encrypt()
1217 * @see Crypt_GPG::encryptFile()
1218 * @see Crypt_GPG::clearEncryptKeys()
1219 * @see Crypt_GPG::_addKey()
1220 */
1221 public function addEncryptKey($key)
1222 {
1223 $this->_addKey($this->encryptKeys, true, false, $key);
1224 return $this;
1225 }
1226
1227 // }}}
1228 // {{{ addSignKey()
1229
1230 /**
1231 * Adds a key to use for signing
1232 *
1233 * @param mixed $key the key to use. This may be a key identifier,
1234 * user id, fingerprint, {@link Crypt_GPG_Key} or
1235 * {@link Crypt_GPG_SubKey}. The key must be able
1236 * to sign.
1237 * @param string $passphrase optional. The passphrase of the key required
1238 * for signing.
1239 *
1240 * @return Crypt_GPG the current object, for fluent interface.
1241 *
1242 * @see Crypt_GPG::sign()
1243 * @see Crypt_GPG::signFile()
1244 * @see Crypt_GPG::clearSignKeys()
1245 * @see Crypt_GPG::_addKey()
1246 *
1247 * @sensitive $passphrase
1248 */
1249 public function addSignKey($key, $passphrase = null)
1250 {
1251 $this->_addKey($this->signKeys, false, true, $key, $passphrase);
1252 return $this;
1253 }
1254
1255 // }}}
1256 // {{{ addPassphrase()
1257
1258 /**
1259 * Register a private key passphrase for import/export (GnuPG 2.1)
1260 *
1261 * @param mixed $key The key to use. This must be a key identifier,
1262 * or fingerprint.
1263 * @param string $passphrase The passphrase of the key.
1264 *
1265 * @return Crypt_GPG the current object, for fluent interface.
1266 *
1267 * @see Crypt_GPG::clearPassphrases()
1268 * @see Crypt_GPG::importKey()
1269 * @see Crypt_GPG::exportKey()
1270 *
1271 * @sensitive $passphrase
1272 */
1273 public function addPassphrase($key, $passphrase)
1274 {
1275 $this->passphrases[$key] = $passphrase;
1276 return $this;
1277 }
1278
1279 // }}}
1280 // {{{ clearDecryptKeys()
1281
1282 /**
1283 * Clears all decryption keys
1284 *
1285 * @return Crypt_GPG the current object, for fluent interface.
1286 *
1287 * @see Crypt_GPG::decrypt()
1288 * @see Crypt_GPG::addDecryptKey()
1289 */
1290 public function clearDecryptKeys()
1291 {
1292 $this->decryptKeys = array();
1293 return $this;
1294 }
1295
1296 // }}}
1297 // {{{ clearEncryptKeys()
1298
1299 /**
1300 * Clears all encryption keys
1301 *
1302 * @return Crypt_GPG the current object, for fluent interface.
1303 *
1304 * @see Crypt_GPG::encrypt()
1305 * @see Crypt_GPG::addEncryptKey()
1306 */
1307 public function clearEncryptKeys()
1308 {
1309 $this->encryptKeys = array();
1310 return $this;
1311 }
1312
1313 // }}}
1314 // {{{ clearSignKeys()
1315
1316 /**
1317 * Clears all signing keys
1318 *
1319 * @return Crypt_GPG the current object, for fluent interface.
1320 *
1321 * @see Crypt_GPG::sign()
1322 * @see Crypt_GPG::addSignKey()
1323 */
1324 public function clearSignKeys()
1325 {
1326 $this->signKeys = array();
1327 return $this;
1328 }
1329
1330 // }}}
1331 // {{{ clearPassphrases()
1332
1333 /**
1334 * Clears all private key passphrases
1335 *
1336 * @return Crypt_GPG the current object, for fluent interface.
1337 *
1338 * @see Crypt_GPG::importKey()
1339 * @see Crypt_GPG::exportKey()
1340 * @see Crypt_GPG::addPassphrase()
1341 */
1342 public function clearPassphrases()
1343 {
1344 $this->passphrases = array();
1345 return $this;
1346 }
1347
1348 // }}}
1349 // {{{ hasEncryptKeys()
1350
1351 /**
1352 * Tell if there are encryption keys registered
1353 *
1354 * @return boolean True if the data shall be encrypted
1355 */
1356 public function hasEncryptKeys()
1357 {
1358 return count($this->encryptKeys) > 0;
1359 }
1360
1361 // }}}
1362 // {{{ hasSignKeys()
1363
1364 /**
1365 * Tell if there are signing keys registered
1366 *
1367 * @return boolean True if the data shall be signed
1368 */
1369 public function hasSignKeys()
1370 {
1371 return count($this->signKeys) > 0;
1372 }
1373
1374 // }}}
1375 // {{{ _addKey()
1376
1377 /**
1378 * Adds a key to one of the internal key arrays
1379 *
1380 * This handles resolving full key objects from the provided
1381 * <kbd>$key</kbd> value.
1382 *
1383 * @param array &$array the array to which the key should be added.
1384 * @param boolean $encrypt whether or not the key must be able to
1385 * encrypt.
1386 * @param boolean $sign whether or not the key must be able to sign.
1387 * @param mixed $key the key to add. This may be a key identifier,
1388 * user id, fingerprint, {@link Crypt_GPG_Key} or
1389 * {@link Crypt_GPG_SubKey}.
1390 * @param string $passphrase optional. The passphrase associated with the
1391 * key.
1392 *
1393 * @return void
1394 *
1395 * @sensitive $passphrase
1396 */
1397 protected function _addKey(array &$array, $encrypt, $sign, $key,
1398 $passphrase = null
1399 ) {
1400 $subKeys = array();
1401
1402 if (is_scalar($key)) {
1403 $keys = $this->getKeys($key);
1404 if (count($keys) == 0) {
1405 throw new Crypt_GPG_KeyNotFoundException(
1406 'Key not found: ' . $key,
1407 self::ERROR_KEY_NOT_FOUND,
1408 $key
1409 );
1410 }
1411 $key = $keys[0];
1412 }
1413
1414 if ($key instanceof Crypt_GPG_Key) {
1415 if ($encrypt && !$key->canEncrypt()) {
1416 throw new InvalidArgumentException(
1417 'Key "' . $key . '" cannot encrypt.'
1418 );
1419 }
1420
1421 if ($sign && !$key->canSign()) {
1422 throw new InvalidArgumentException(
1423 'Key "' . $key . '" cannot sign.'
1424 );
1425 }
1426
1427 foreach ($key->getSubKeys() as $subKey) {
1428 $canEncrypt = $subKey->canEncrypt();
1429 $canSign = $subKey->canSign();
1430 if (($encrypt && $sign && $canEncrypt && $canSign)
1431 || ($encrypt && !$sign && $canEncrypt)
1432 || (!$encrypt && $sign && $canSign)
1433 || (!$encrypt && !$sign)
1434 ) {
1435 // We add all subkeys that meet the requirements because we
1436 // were not told which subkey is required.
1437 $subKeys[] = $subKey;
1438 }
1439 }
1440 } elseif ($key instanceof Crypt_GPG_SubKey) {
1441 $subKeys[] = $key;
1442 }
1443
1444 if (count($subKeys) === 0) {
1445 throw new InvalidArgumentException(
1446 'Key "' . $key . '" is not in a recognized format.'
1447 );
1448 }
1449
1450 foreach ($subKeys as $subKey) {
1451 if ($encrypt && !$subKey->canEncrypt()) {
1452 throw new InvalidArgumentException(
1453 'Key "' . $key . '" cannot encrypt.'
1454 );
1455 }
1456
1457 if ($sign && !$subKey->canSign()) {
1458 throw new InvalidArgumentException(
1459 'Key "' . $key . '" cannot sign.'
1460 );
1461 }
1462
1463 $array[$subKey->getId()] = array(
1464 'fingerprint' => $subKey->getFingerprint(),
1465 'passphrase' => $passphrase
1466 );
1467 }
1468 }
1469
1470 // }}}
1471 // {{{ _importKey()
1472
1473 /**
1474 * Imports a public or private key into the keyring
1475 *
1476 * @param string $key the key to be imported.
1477 * @param boolean $isFile whether or not the input is a filename.
1478 *
1479 * @return array an associative array containing the following elements:
1480 * - <kbd>fingerprint</kbd> - the fingerprint of the
1481 * imported key,
1482 * - <kbd>public_imported</kbd> - the number of public
1483 * keys imported,
1484 * - <kbd>public_unchanged</kbd> - the number of unchanged
1485 * public keys,
1486 * - <kbd>private_imported</kbd> - the number of private
1487 * keys imported,
1488 * - <kbd>private_unchanged</kbd> - the number of unchanged
1489 * private keys.
1490 *
1491 * @throws Crypt_GPG_NoDataException if the key data is missing or if the
1492 * data is is not valid key data.
1493 *
1494 * @throws Crypt_GPG_FileException if the key file is not readable.
1495 *
1496 * @throws Crypt_GPG_BadPassphraseException if a required passphrase is
1497 * incorrect or if a required passphrase is not specified. See
1498 * {@link Crypt_GPG::addPassphrase()}.
1499 *
1500 * @throws Crypt_GPG_Exception if an unknown or unexpected error occurs.
1501 * Use the <kbd>debug</kbd> option and file a bug report if these
1502 * exceptions occur.
1503 */
1504 protected function _importKey($key, $isFile)
1505 {
1506 $result = array();
1507 $arguments = array();
1508 $input = $this->_prepareInput($key, $isFile, false);
1509 $version = $this->engine->getVersion();
1510
1511 if (version_compare($version, '1.0.5', 'ge')
1512 && version_compare($version, '1.0.7', 'lt')
1513 ) {
1514 $arguments[] = '--allow-secret-key-import';
1515 }
1516
1517 if (empty($this->passphrases)) {
1518 $arguments[] = '--batch';
1519 }
1520
1521 $this->engine->reset();
1522 $this->engine->setPins($this->passphrases);
1523 $this->engine->setOperation('--import', $arguments);
1524 $this->engine->setInput($input);
1525 $this->engine->run();
1526
1527 return $this->engine->getProcessData('Import');
1528 }
1529
1530 // }}}
1531 // {{{ _exportKey()
1532
1533 /**
1534 * Exports a private or public key from the keyring
1535 *
1536 * If more than one key fingerprint is available for the specified
1537 * <kbd>$keyId</kbd> (for example, if you use a non-unique uid) only the
1538 * first key is exported.
1539 *
1540 * @param string $keyId either the full uid of the key, the email
1541 * part of the uid of the key or the key id.
1542 * @param boolean $armor optional. If true, ASCII armored data is returned;
1543 * otherwise, binary data is returned. Defaults to
1544 * true.
1545 * @param boolean $private return private instead of public key
1546 *
1547 * @return string the key data.
1548 *
1549 * @throws Crypt_GPG_KeyNotFoundException if a key with the given
1550 * <kbd>$keyId</kbd> is not found.
1551 *
1552 * @throws Crypt_GPG_BadPassphraseException if a required passphrase is
1553 * incorrect or if a required passphrase is not specified. See
1554 * {@link Crypt_GPG::addPassphrase()}.
1555 *
1556 * @throws Crypt_GPG_Exception if an unknown or unexpected error occurs.
1557 * Use the <kbd>debug</kbd> option and file a bug report if these
1558 * exceptions occur.
1559 */
1560 protected function _exportKey($keyId, $armor = true, $private = false)
1561 {
1562 $fingerprint = $this->getFingerprint($keyId);
1563
1564 if ($fingerprint === null) {
1565 throw new Crypt_GPG_KeyNotFoundException(
1566 'Key not found: ' . $keyId,
1567 self::ERROR_KEY_NOT_FOUND,
1568 $keyId
1569 );
1570 }
1571
1572 $keyData = '';
1573 $operation = $private ? '--export-secret-keys' : '--export';
1574 $operation .= ' ' . escapeshellarg($fingerprint);
1575 $arguments = $armor ? array('--armor') : array();
1576
1577 $this->engine->reset();
1578 $this->engine->setPins($this->passphrases);
1579 $this->engine->setOutput($keyData);
1580 $this->engine->setOperation($operation, $arguments);
1581 $this->engine->run();
1582
1583 return $keyData;
1584 }
1585
1586 // }}}
1587 // {{{ _encrypt()
1588
1589 /**
1590 * Encrypts data
1591 *
1592 * @param string $data the data to encrypt.
1593 * @param boolean $isFile whether or not the data is a filename.
1594 * @param string $outputFile the filename of the file in which to store
1595 * the encrypted data. If null, the encrypted
1596 * data is returned as a string.
1597 * @param boolean $armor if true, ASCII armored data is returned;
1598 * otherwise, binary data is returned.
1599 *
1600 * @return void|string if the <kbd>$outputFile</kbd> parameter is null, a
1601 * string containing the encrypted data is returned.
1602 *
1603 * @throws Crypt_GPG_KeyNotFoundException if no encryption key is specified.
1604 * See {@link Crypt_GPG::addEncryptKey()}.
1605 *
1606 * @throws Crypt_GPG_FileException if the output file is not writeable or
1607 * if the input file is not readable.
1608 *
1609 * @throws Crypt_GPG_Exception if an unknown or unexpected error occurs.
1610 * Use the <kbd>debug</kbd> option and file a bug report if these
1611 * exceptions occur.
1612 */
1613 protected function _encrypt($data, $isFile, $outputFile, $armor)
1614 {
1615 if (!$this->hasEncryptKeys()) {
1616 throw new Crypt_GPG_KeyNotFoundException(
1617 'No encryption keys specified.'
1618 );
1619 }
1620
1621 $input = $this->_prepareInput($data, $isFile);
1622 $output = $this->_prepareOutput($outputFile, $input);
1623 $arguments = $armor ? array('--armor') : array();
1624
1625 foreach ($this->encryptKeys as $key) {
1626 $arguments[] = '--recipient ' . escapeshellarg($key['fingerprint']);
1627 }
1628
1629 $this->engine->reset();
1630 $this->engine->setInput($input);
1631 $this->engine->setOutput($output);
1632 $this->engine->setOperation('--encrypt', $arguments);
1633 $this->engine->run();
1634
1635 if ($outputFile === null) {
1636 return $output;
1637 }
1638 }
1639
1640 // }}}
1641 // {{{ _decrypt()
1642
1643 /**
1644 * Decrypts data
1645 *
1646 * @param string $data the data to be decrypted.
1647 * @param boolean $isFile whether or not the data is a filename.
1648 * @param string $outputFile the name of the file to which the decrypted
1649 * data should be written. If null, the decrypted
1650 * data is returned as a string.
1651 *
1652 * @return void|string if the <kbd>$outputFile</kbd> parameter is null, a
1653 * string containing the decrypted data is returned.
1654 *
1655 * @throws Crypt_GPG_KeyNotFoundException if the private key needed to
1656 * decrypt the data is not in the user's keyring.
1657 *
1658 * @throws Crypt_GPG_NoDataException if specified data does not contain
1659 * GPG encrypted data.
1660 *
1661 * @throws Crypt_GPG_BadPassphraseException if a required passphrase is
1662 * incorrect or if a required passphrase is not specified. See
1663 * {@link Crypt_GPG::addDecryptKey()}.
1664 *
1665 * @throws Crypt_GPG_FileException if the output file is not writeable or
1666 * if the input file is not readable.
1667 *
1668 * @throws Crypt_GPG_Exception if an unknown or unexpected error occurs.
1669 * Use the <kbd>debug</kbd> option and file a bug report if these
1670 * exceptions occur.
1671 */
1672 protected function _decrypt($data, $isFile, $outputFile)
1673 {
1674 $input = $this->_prepareInput($data, $isFile, false);
1675 $output = $this->_prepareOutput($outputFile, $input);
1676
1677 $this->engine->reset();
1678 $this->engine->setPins($this->decryptKeys);
1679 $this->engine->setOperation('--decrypt --skip-verify');
1680 $this->engine->setInput($input);
1681 $this->engine->setOutput($output);
1682 $this->engine->run();
1683
1684 if ($outputFile === null) {
1685 return $output;
1686 }
1687 }
1688
1689 // }}}
1690 // {{{ _sign()
1691
1692 /**
1693 * Signs data
1694 *
1695 * @param string $data the data to be signed.
1696 * @param boolean $isFile whether or not the data is a filename.
1697 * @param string $outputFile the name of the file in which the signed data
1698 * should be stored. If null, the signed data is
1699 * returned as a string.
1700 * @param boolean $mode the data signing mode to use. Should be one of
1701 * {@link Crypt_GPG::SIGN_MODE_NORMAL},
1702 * {@link Crypt_GPG::SIGN_MODE_CLEAR} or
1703 * {@link Crypt_GPG::SIGN_MODE_DETACHED}.
1704 * @param boolean $armor if true, ASCII armored data is returned;
1705 * otherwise, binary data is returned. This has
1706 * no effect if the mode
1707 * <kbd>Crypt_GPG::SIGN_MODE_CLEAR</kbd> is
1708 * used.
1709 * @param boolean $textmode if true, line-breaks in signed data be
1710 * normalized. Use this option when signing
1711 * e-mail, or for greater compatibility between
1712 * systems with different line-break formats.
1713 * Defaults to false. This has no effect if the
1714 * mode <kbd>Crypt_GPG::SIGN_MODE_CLEAR</kbd> is
1715 * used as clear-signing always uses textmode.
1716 *
1717 * @return void|string if the <kbd>$outputFile</kbd> parameter is null, a
1718 * string containing the signed data (or the signature
1719 * data if a detached signature is requested) is
1720 * returned.
1721 *
1722 * @throws Crypt_GPG_KeyNotFoundException if no signing key is specified.
1723 * See {@link Crypt_GPG::addSignKey()}.
1724 *
1725 * @throws Crypt_GPG_BadPassphraseException if a specified passphrase is
1726 * incorrect or if a required passphrase is not specified.
1727 *
1728 * @throws Crypt_GPG_FileException if the output file is not writeable or
1729 * if the input file is not readable.
1730 *
1731 * @throws Crypt_GPG_Exception if an unknown or unexpected error occurs.
1732 * Use the <kbd>debug</kbd> option and file a bug report if these
1733 * exceptions occur.
1734 */
1735 protected function _sign($data, $isFile, $outputFile, $mode, $armor,
1736 $textmode
1737 ) {
1738 if (!$this->hasSignKeys()) {
1739 throw new Crypt_GPG_KeyNotFoundException(
1740 'No signing keys specified.'
1741 );
1742 }
1743
1744 $input = $this->_prepareInput($data, $isFile);
1745 $output = $this->_prepareOutput($outputFile, $input);
1746
1747 switch ($mode) {
1748 case self::SIGN_MODE_DETACHED:
1749 $operation = '--detach-sign';
1750 break;
1751 case self::SIGN_MODE_CLEAR:
1752 $operation = '--clearsign';
1753 break;
1754 case self::SIGN_MODE_NORMAL:
1755 default:
1756 $operation = '--sign';
1757 break;
1758 }
1759
1760 $arguments = array();
1761
1762 if ($armor) {
1763 $arguments[] = '--armor';
1764 }
1765 if ($textmode) {
1766 $arguments[] = '--textmode';
1767 }
1768
1769 foreach ($this->signKeys as $key) {
1770 $arguments[] = '--local-user ' .
1771 escapeshellarg($key['fingerprint']);
1772 }
1773
1774 $this->engine->reset();
1775 $this->engine->setPins($this->signKeys);
1776 $this->engine->setInput($input);
1777 $this->engine->setOutput($output);
1778 $this->engine->setOperation($operation, $arguments);
1779 $this->engine->run();
1780
1781 if ($outputFile === null) {
1782 return $output;
1783 }
1784 }
1785
1786 // }}}
1787 // {{{ _encryptAndSign()
1788
1789 /**
1790 * Encrypts and signs data
1791 *
1792 * @param string $data the data to be encrypted and signed.
1793 * @param boolean $isFile whether or not the data is a filename.
1794 * @param string $outputFile the name of the file in which the encrypted,
1795 * signed data should be stored. If null, the
1796 * encrypted, signed data is returned as a
1797 * string.
1798 * @param boolean $armor if true, ASCII armored data is returned;
1799 * otherwise, binary data is returned.
1800 *
1801 * @return void|string if the <kbd>$outputFile</kbd> parameter is null, a
1802 * string containing the encrypted, signed data is
1803 * returned.
1804 *
1805 * @throws Crypt_GPG_KeyNotFoundException if no encryption key is specified
1806 * or if no signing key is specified. See
1807 * {@link Crypt_GPG::addEncryptKey()} and
1808 * {@link Crypt_GPG::addSignKey()}.
1809 *
1810 * @throws Crypt_GPG_BadPassphraseException if a specified passphrase is
1811 * incorrect or if a required passphrase is not specified.
1812 *
1813 * @throws Crypt_GPG_FileException if the output file is not writeable or
1814 * if the input file is not readable.
1815 *
1816 * @throws Crypt_GPG_Exception if an unknown or unexpected error occurs.
1817 * Use the <kbd>debug</kbd> option and file a bug report if these
1818 * exceptions occur.
1819 */
1820 protected function _encryptAndSign($data, $isFile, $outputFile, $armor)
1821 {
1822 if (!$this->hasSignKeys()) {
1823 throw new Crypt_GPG_KeyNotFoundException(
1824 'No signing keys specified.'
1825 );
1826 }
1827
1828 if (!$this->hasEncryptKeys()) {
1829 throw new Crypt_GPG_KeyNotFoundException(
1830 'No encryption keys specified.'
1831 );
1832 }
1833
1834 $input = $this->_prepareInput($data, $isFile);
1835 $output = $this->_prepareOutput($outputFile, $input);
1836 $arguments = $armor ? array('--armor') : array();
1837
1838 foreach ($this->signKeys as $key) {
1839 $arguments[] = '--local-user ' .
1840 escapeshellarg($key['fingerprint']);
1841 }
1842
1843 foreach ($this->encryptKeys as $key) {
1844 $arguments[] = '--recipient ' . escapeshellarg($key['fingerprint']);
1845 }
1846
1847 $this->engine->reset();
1848 $this->engine->setPins($this->signKeys);
1849 $this->engine->setInput($input);
1850 $this->engine->setOutput($output);
1851 $this->engine->setOperation('--encrypt --sign', $arguments);
1852 $this->engine->run();
1853
1854 if ($outputFile === null) {
1855 return $output;
1856 }
1857 }
1858
1859 // }}}
1860 // {{{ _verify()
1861
1862 /**
1863 * Verifies data
1864 *
1865 * @param string $data the signed data to be verified.
1866 * @param boolean $isFile whether or not the data is a filename.
1867 * @param string $signature if verifying a file signed using a detached
1868 * signature, this must be the detached signature
1869 * data. Otherwise, specify ''.
1870 *
1871 * @return array an array of {@link Crypt_GPG_Signature} objects for the
1872 * signed data.
1873 *
1874 * @throws Crypt_GPG_KeyNotFoundException if the public key needed for
1875 * signature verification is not in the user's keyring.
1876 *
1877 * @throws Crypt_GPG_NoDataException if the provided data is not signed
1878 * data.
1879 *
1880 * @throws Crypt_GPG_FileException if the input file is not readable.
1881 *
1882 * @throws Crypt_GPG_Exception if an unknown or unexpected error occurs.
1883 * Use the <kbd>debug</kbd> option and file a bug report if these
1884 * exceptions occur.
1885 *
1886 * @see Crypt_GPG_Signature
1887 */
1888 protected function _verify($data, $isFile, $signature)
1889 {
1890 if ($signature == '') {
1891 $operation = '--verify';
1892 $arguments = array();
1893 } else {
1894 // Signed data goes in FD_MESSAGE, detached signature data goes in
1895 // FD_INPUT.
1896 $operation = '--verify - "-&' . Crypt_GPG_Engine::FD_MESSAGE. '"';
1897 $arguments = array('--enable-special-filenames');
1898 }
1899
1900 $input = $this->_prepareInput($data, $isFile, false);
1901
1902 $this->engine->reset();
1903
1904 if ($signature == '') {
1905 // signed or clearsigned data
1906 $this->engine->setInput($input);
1907 } else {
1908 // detached signature
1909 $this->engine->setInput($signature);
1910 $this->engine->setMessage($input);
1911 }
1912
1913 $this->engine->setOperation($operation, $arguments);
1914 $this->engine->run();
1915
1916 return $this->engine->getProcessData('Signatures');
1917 }
1918
1919 // }}}
1920 // {{{ _decryptAndVerify()
1921
1922 /**
1923 * Decrypts and verifies encrypted, signed data
1924 *
1925 * @param string $data the encrypted signed data to be decrypted and
1926 * verified.
1927 * @param boolean $isFile whether or not the data is a filename.
1928 * @param string $outputFile the name of the file to which the decrypted
1929 * data should be written. If null, the decrypted
1930 * data is returned in the results array.
1931 * @param boolean $ignoreVerifyErrors enables ignoring of signature verification
1932 * errors caused by missing public key.
1933 * When enabled Crypt_GPG_KeyNotFoundException
1934 * will not be thrown.
1935 *
1936 * @return array two element array. The array has an element 'data'
1937 * containing the decrypted data and an element
1938 * 'signatures' containing an array of
1939 * {@link Crypt_GPG_Signature} objects for the signed data.
1940 * If the decrypted data is written to a file, the 'data'
1941 * element is null.
1942 *
1943 * @throws Crypt_GPG_KeyNotFoundException if the private key needed to
1944 * decrypt the data is not in the user's keyring or if the public
1945 * key needed for verification is not in the user's keyring.
1946 *
1947 * @throws Crypt_GPG_NoDataException if specified data does not contain
1948 * GPG signed, encrypted data.
1949 *
1950 * @throws Crypt_GPG_BadPassphraseException if a required passphrase is
1951 * incorrect or if a required passphrase is not specified. See
1952 * {@link Crypt_GPG::addDecryptKey()}.
1953 *
1954 * @throws Crypt_GPG_FileException if the output file is not writeable or
1955 * if the input file is not readable.
1956 *
1957 * @throws Crypt_GPG_Exception if an unknown or unexpected error occurs.
1958 * Use the <kbd>debug</kbd> option and file a bug report if these
1959 * exceptions occur.
1960 *
1961 * @see Crypt_GPG_Signature
1962 */
1963 protected function _decryptAndVerify($data, $isFile, $outputFile, $ignoreVerifyErrors = false)
1964 {
1965 $input = $this->_prepareInput($data, $isFile, false);
1966 $output = $this->_prepareOutput($outputFile, $input);
1967
1968 $this->engine->reset();
1969 $this->engine->setPins($this->decryptKeys);
1970 $this->engine->setInput($input);
1971 $this->engine->setOutput($output);
1972 $this->engine->setOperation('--decrypt');
1973 $this->engine->setProcessData('IgnoreVerifyErrors', $ignoreVerifyErrors);
1974 $this->engine->run();
1975
1976 $return = array(
1977 'data' => null,
1978 'signatures' => $this->engine->getProcessData('Signatures')
1979 );
1980
1981 if ($outputFile === null) {
1982 $return['data'] = $output;
1983 }
1984
1985 return $return;
1986 }
1987
1988 // }}}
1989 // {{{ _prepareInput()
1990
1991 /**
1992 * Prepares command input
1993 *
1994 * @param string $data the input data.
1995 * @param boolean $isFile whether or not the input is a filename.
1996 * @param boolean $allowEmpty whether to check if the input is not empty.
1997 *
1998 * @throws Crypt_GPG_NoDataException if the key data is missing.
1999 * @throws Crypt_GPG_FileException if the file is not readable.
2000 */
2001 protected function _prepareInput($data, $isFile = false, $allowEmpty = true)
2002 {
2003 if ($isFile) {
2004 $input = @fopen($data, 'rb');
2005 if ($input === false) {
2006 throw new Crypt_GPG_FileException(
2007 'Could not open input file "' . $data . '"',
2008 0,
2009 $data
2010 );
2011 }
2012 } else {
2013 $input = strval($data);
2014 if (!$allowEmpty && $input === '') {
2015 throw new Crypt_GPG_NoDataException(
2016 'No valid input data found.',
2017 self::ERROR_NO_DATA
2018 );
2019 }
2020 }
2021
2022 return $input;
2023 }
2024
2025 // }}}
2026 // {{{ _prepareOutput()
2027
2028 /**
2029 * Prepares command output
2030 *
2031 * @param string $outputFile the name of the file in which the output
2032 * data should be stored. If null, the output
2033 * data is returned as a string.
2034 * @param boolean $input the input resource, in case it would need
2035 * to be released (closed) on exception.
2036 *
2037 * @throws Crypt_GPG_FileException if the file is not writeable.
2038 */
2039 protected function _prepareOutput($outputFile, $input = null)
2040 {
2041 if ($outputFile === null) {
2042 $output = '';
2043 } else {
2044 $output = @fopen($outputFile, 'wb');
2045 if ($output === false) {
2046 if (is_resource($input)) {
2047 fclose($input);
2048 }
2049 throw new Crypt_GPG_FileException(
2050 'Could not open output file "' . $outputFile . '"',
2051 0,
2052 $outputFile
2053 );
2054 }
2055 }
2056
2057 return $output;
2058 }
2059
2060 // }}}
2061 }
2062
2063 // }}}
2064
2065 ?>