Add some code for S/MIME signatures verification, update Crypt_GPG package

1 files changed, 790 insertions, 0 deletions

diff --git a/program/lib/Crypt/GPG/KeyGenerator.php b/program/lib/Crypt/GPG/KeyGenerator.php
new file mode 100644
index 000000000..f59c0ee3a
--- /dev/null
+++ b/program/lib/Crypt/GPG/KeyGenerator.php
@@ -0,0 +1,790 @@
+<?php
+
+/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */
+
+/**
+ * Crypt_GPG is a package to use GPG from PHP
+ *
+ * This file contains an object that handles GnuPG key generation.
+ *
+ * PHP version 5
+ *
+ * LICENSE:
+ *
+ * This library is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2.1 of the
+ * License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ *
+ * @category  Encryption
+ * @package   Crypt_GPG
+ * @author    Michael Gauthier <mike@silverorange.com>
+ * @copyright 2011-2013 silverorange
+ * @license   http://www.gnu.org/copyleft/lesser.html LGPL License 2.1
+ * @version   CVS: $Id:$
+ * @link      http://pear.php.net/package/Crypt_GPG
+ * @link      http://www.gnupg.org/
+ */
+
+/**
+ * Base class for GPG methods
+ */
+require_once 'Crypt/GPGAbstract.php';
+
+/**
+ * Status output handler for key generation
+ */
+require_once 'Crypt/GPG/KeyGeneratorStatusHandler.php';
+
+/**
+ * Error output handler for key generation
+ */
+require_once 'Crypt/GPG/KeyGeneratorErrorHandler.php';
+
+// {{{ class Crypt_GPG_KeyGenerator
+
+/**
+ * GnuPG key generator
+ *
+ * This class provides an object oriented interface for generating keys with
+ * the GNU Privacy Guard (GPG).
+ *
+ * Secure key generation requires true random numbers, and as such can be slow.
+ * If the operating system runs out of entropy, key generation will block until
+ * more entropy is available.
+ *
+ * If quick key generation is important, a hardware entropy generator, or an
+ * entropy gathering daemon may be installed. For example, administrators of
+ * Debian systems may want to install the 'randomsound' package.
+ *
+ * This class uses the experimental automated key generation support available
+ * in GnuPG. See <b>doc/DETAILS</b> in the
+ * {@link http://www.gnupg.org/download/ GPG distribution} for detailed
+ * information on the key generation format.
+ *
+ * @category  Encryption
+ * @package   Crypt_GPG
+ * @author    Nathan Fredrickson <nathan@silverorange.com>
+ * @author    Michael Gauthier <mike@silverorange.com>
+ * @copyright 2005-2013 silverorange
+ * @license   http://www.gnu.org/copyleft/lesser.html LGPL License 2.1
+ * @link      http://pear.php.net/package/Crypt_GPG
+ * @link      http://www.gnupg.org/
+ */
+class Crypt_GPG_KeyGenerator extends Crypt_GPGAbstract
+{
+    // {{{ protected properties
+
+    /**
+     * The expiration date of generated keys
+     *
+     * @var integer
+     *
+     * @see Crypt_GPG_KeyGenerator::setExpirationDate()
+     */
+    protected $expirationDate = 0;
+
+    /**
+     * The passphrase of generated keys
+     *
+     * @var string
+     *
+     * @see Crypt_GPG_KeyGenerator::setPassphrase()
+     */
+    protected $passphrase = '';
+
+    /**
+     * The algorithm for generated primary keys
+     *
+     * @var integer
+     *
+     * @see Crypt_GPG_KeyGenerator::setKeyParams()
+     */
+    protected $keyAlgorithm = Crypt_GPG_SubKey::ALGORITHM_DSA;
+
+    /**
+     * The size of generated primary keys
+     *
+     * @var integer
+     *
+     * @see Crypt_GPG_KeyGenerator::setKeyParams()
+     */
+    protected $keySize = 1024;
+
+    /**
+     * The usages of generated primary keys
+     *
+     * This is a bitwise combination of the usage constants in
+     * {@link Crypt_GPG_SubKey}.
+     *
+     * @var integer
+     *
+     * @see Crypt_GPG_KeyGenerator::setKeyParams()
+     */
+    protected $keyUsage = 6; // USAGE_SIGN | USAGE_CERTIFY
+
+    /**
+     * The algorithm for generated sub-keys
+     *
+     * @var integer
+     *
+     * @see Crypt_GPG_KeyGenerator::setSubKeyParams()
+     */
+    protected $subKeyAlgorithm = Crypt_GPG_SubKey::ALGORITHM_ELGAMAL_ENC;
+
+    /**
+     * The size of generated sub-keys
+     *
+     * @var integer
+     *
+     * @see Crypt_GPG_KeyGenerator::setSubKeyParams()
+     */
+    protected $subKeySize = 2048;
+
+    /**
+     * The usages of generated sub-keys
+     *
+     * This is a bitwise combination of the usage constants in
+     * {@link Crypt_GPG_SubKey}.
+     *
+     * @var integer
+     *
+     * @see Crypt_GPG_KeyGenerator::setSubKeyParams()
+     */
+    protected $subKeyUsage = Crypt_GPG_SubKey::USAGE_ENCRYPT;
+
+    /**
+     * The GnuPG status handler to use for key generation
+     *
+     * @var Crypt_GPG_KeyGeneratorStatusHandler
+     *
+     * @see Crypt_GPG_KeyGenerator::setStatusHandler()
+     */
+    protected $statusHandler = null;
+
+    /**
+     * The GnuPG error handler to use for key generation
+     *
+     * @var Crypt_GPG_KeyGeneratorErrorHandler
+     *
+     * @see Crypt_GPG_KeyGenerator::setErrorHandler()
+     */
+    protected $errorHandler = null;
+
+    // }}}
+    // {{{ __construct()
+
+    /**
+     * Creates a new GnuPG key generator
+     *
+     * Available options are:
+     *
+     * - <kbd>string  homedir</kbd>        - the directory where the GPG
+     *                                       keyring files are stored. If not
+     *                                       specified, Crypt_GPG uses the
+     *                                       default of <kbd>~/.gnupg</kbd>.
+     * - <kbd>string  publicKeyring</kbd>  - the file path of the public
+     *                                       keyring. Use this if the public
+     *                                       keyring is not in the homedir, or
+     *                                       if the keyring is in a directory
+     *                                       not writable by the process
+     *                                       invoking GPG (like Apache). Then
+     *                                       you can specify the path to the
+     *                                       keyring with this option
+     *                                       (/foo/bar/pubring.gpg), and specify
+     *                                       a writable directory (like /tmp)
+     *                                       using the <i>homedir</i> option.
+     * - <kbd>string  privateKeyring</kbd> - the file path of the private
+     *                                       keyring. Use this if the private
+     *                                       keyring is not in the homedir, or
+     *                                       if the keyring is in a directory
+     *                                       not writable by the process
+     *                                       invoking GPG (like Apache). Then
+     *                                       you can specify the path to the
+     *                                       keyring with this option
+     *                                       (/foo/bar/secring.gpg), and specify
+     *                                       a writable directory (like /tmp)
+     *                                       using the <i>homedir</i> option.
+     * - <kbd>string  trustDb</kbd>        - the file path of the web-of-trust
+     *                                       database. Use this if the trust
+     *                                       database is not in the homedir, or
+     *                                       if the database is in a directory
+     *                                       not writable by the process
+     *                                       invoking GPG (like Apache). Then
+     *                                       you can specify the path to the
+     *                                       trust database with this option
+     *                                       (/foo/bar/trustdb.gpg), and specify
+     *                                       a writable directory (like /tmp)
+     *                                       using the <i>homedir</i> option.
+     * - <kbd>string  binary</kbd>         - the location of the GPG binary. If
+     *                                       not specified, the driver attempts
+     *                                       to auto-detect the GPG binary
+     *                                       location using a list of known
+     *                                       default locations for the current
+     *                                       operating system. The option
+     *                                       <kbd>gpgBinary</kbd> is a
+     *                                       deprecated alias for this option.
+     * - <kbd>string  agent</kbd>          - the location of the GnuPG agent
+     *                                       binary. The gpg-agent is only
+     *                                       used for GnuPG 2.x. If not
+     *                                       specified, the engine attempts
+     *                                       to auto-detect the gpg-agent
+     *                                       binary location using a list of
+     *                                       know default locations for the
+     *                                       current operating system.
+     * - <kbd>boolean debug</kbd>          - whether or not to use debug mode.
+     *                                       When debug mode is on, all
+     *                                       communication to and from the GPG
+     *                                       subprocess is logged. This can be
+     *
+     * @param array $options optional. An array of options used to create the
+     *                       GPG object. All options are optional and are
+     *                       represented as key-value pairs.
+     *
+     * @throws Crypt_GPG_FileException if the <kbd>homedir</kbd> does not exist
+     *         and cannot be created. This can happen if <kbd>homedir</kbd> is
+     *         not specified, Crypt_GPG is run as the web user, and the web
+     *         user has no home directory. This exception is also thrown if any
+     *         of the options <kbd>publicKeyring</kbd>,
+     *         <kbd>privateKeyring</kbd> or <kbd>trustDb</kbd> options are
+     *         specified but the files do not exist or are are not readable.
+     *         This can happen if the user running the Crypt_GPG process (for
+     *         example, the Apache user) does not have permission to read the
+     *         files.
+     *
+     * @throws PEAR_Exception if the provided <kbd>binary</kbd> is invalid, or
+     *         if no <kbd>binary</kbd> is provided and no suitable binary could
+     *         be found.
+     *
+     * @throws PEAR_Exception if the provided <kbd>agent</kbd> is invalid, or
+     *         if no <kbd>agent</kbd> is provided and no suitable gpg-agent
+     *         cound be found.
+     */
+    public function __construct(array $options = array())
+    {
+        parent::__construct($options);
+
+        $this->statusHandler = new Crypt_GPG_KeyGeneratorStatusHandler();
+        $this->errorHandler  = new Crypt_GPG_KeyGeneratorErrorHandler();
+    }
+
+    // }}}
+    // {{{ setExpirationDate()
+
+    /**
+     * Sets the expiration date of generated keys
+     *
+     * @param string|integer $date either a string that may be parsed by
+     *                             PHP's strtotime() function, or an integer
+     *                             timestamp representing the number of seconds
+     *                             since the UNIX epoch. This date must be at
+     *                             least one date in the future. Keys that
+     *                             expire in the past may not be generated. Use
+     *                             an expiration date of 0 for keys that do not
+     *                             expire.
+     *
+     * @throws InvalidArgumentException if the date is not a valid format, or
+     *                                  if the date is not at least one day in
+     *                                  the future, or if the date is greater
+     *                                  than 2038-01-19T03:14:07.
+     *
+     * @return Crypt_GPG_KeyGenerator the current object, for fluent interface.
+     */
+    public function setExpirationDate($date)
+    {
+        if (is_int($date) || ctype_digit(strval($date))) {
+            $expirationDate = intval($date);
+        } else {
+            $expirationDate = strtotime($date);
+        }
+
+        if ($expirationDate === false) {
+            throw new InvalidArgumentException(
+                sprintf(
+                    'Invalid expiration date format: "%s". Please use a ' .
+                    'format compatible with PHP\'s strtotime().',
+                    $date
+                )
+            );
+        }
+
+        if ($expirationDate !== 0 && $expirationDate < time() + 86400) {
+            throw new InvalidArgumentException(
+                'Expiration date must be at least a day in the future.'
+            );
+        }
+
+        // GnuPG suffers from the 2038 bug
+        if ($expirationDate > 2147483647) {
+            throw new InvalidArgumentException(
+                'Expiration date must not be greater than 2038-01-19T03:14:07.'
+            );
+        }
+
+        $this->expirationDate = $expirationDate;
+
+        return $this;
+    }
+
+    // }}}
+    // {{{ setPassphrase()
+
+    /**
+     * Sets the passphrase of generated keys
+     *
+     * @param string $passphrase the passphrase to use for generated keys. Use
+     *                           null or an empty string for no passphrase.
+     *
+     * @return Crypt_GPG_KeyGenerator the current object, for fluent interface.
+     */
+    public function setPassphrase($passphrase)
+    {
+        $this->passphrase = strval($passphrase);
+        return $this;
+    }
+
+    // }}}
+    // {{{ setKeyParams()
+
+    /**
+     * Sets the parameters for the primary key of generated key-pairs
+     *
+     * @param integer $algorithm the algorithm used by the key. This should be
+     *                           one of the Crypt_GPG_SubKey::ALGORITHM_*
+     *                           constants.
+     * @param integer $size      optional. The size of the key. Different
+     *                           algorithms have different size requirements.
+     *                           If not specified, the default size for the
+     *                           specified algorithm will be used. If an
+     *                           invalid key size is used, GnuPG will do its
+     *                           best to round it to a valid size.
+     * @param integer $usage     optional. A bitwise combination of key usages.
+     *                           If not specified, the primary key will be used
+     *                           only to sign and certify. This is the default
+     *                           behavior of GnuPG in interactive mode. Use
+     *                           the Crypt_GPG_SubKey::USAGE_* constants here.
+     *                           The primary key may be used to certify even
+     *                           if the certify usage is not specified.
+     *
+     * @return Crypt_GPG_KeyGenerator the current object, for fluent interface.
+     */
+    public function setKeyParams($algorithm, $size = 0, $usage = 0)
+    {
+        $apgorithm = intval($algorithm);
+
+        if ($algorithm === Crypt_GPG_SubKey::ALGORITHM_ELGAMAL_ENC) {
+            throw new Crypt_GPG_InvalidKeyParamsException(
+                'Primary key algorithm must be capable of signing. The ' .
+                'Elgamal algorithm can only encrypt.',
+                0,
+                $algorithm,
+                $size,
+                $usage
+            );
+        }
+
+        if ($size != 0) {
+            $size = intval($size);
+        }
+
+        if ($usage != 0) {
+            $usage = intval($usage);
+        }
+
+        $usageEncrypt = Crypt_GPG_SubKey::USAGE_ENCRYPT;
+
+        if (   $algorithm === Crypt_GPG_SubKey::ALGORITHM_DSA
+            && ($usage & $usageEncrypt) === $usageEncrypt
+        ) {
+            throw new Crypt_GPG_InvalidKeyParamsException(
+                'The DSA algorithm is not capable of encrypting. Please ' .
+                'specify a different algorithm or do not include encryption ' .
+                'as a usage for the primary key.',
+                0,
+                $algorithm,
+                $size,
+                $usage
+            );
+        }
+
+        $this->keyAlgorithm = $algorithm;
+
+        if ($size != 0) {
+            $this->keySize = $size;
+        }
+
+        if ($usage != 0) {
+            $this->keyUsage = $usage;
+        }
+
+        return $this;
+    }
+
+    // }}}
+    // {{{ setSubKeyParams()
+
+    /**
+     * Sets the parameters for the sub-key of generated key-pairs
+     *
+     * @param integer $algorithm the algorithm used by the key. This should be
+     *                           one of the Crypt_GPG_SubKey::ALGORITHM_*
+     *                           constants.
+     * @param integer $size      optional. The size of the key. Different
+     *                           algorithms have different size requirements.
+     *                           If not specified, the default size for the
+     *                           specified algorithm will be used. If an
+     *                           invalid key size is used, GnuPG will do its
+     *                           best to round it to a valid size.
+     * @param integer $usage     optional. A bitwise combination of key usages.
+     *                           If not specified, the sub-key will be used
+     *                           only to encrypt. This is the default behavior
+     *                           of GnuPG in interactive mode. Use the
+     *                           Crypt_GPG_SubKey::USAGE_* constants here.
+     *
+     * @return Crypt_GPG_KeyGenerator the current object, for fluent interface.
+     */
+    public function setSubKeyParams($algorithm, $size = '', $usage = 0)
+    {
+        $apgorithm = intval($algorithm);
+
+        if ($size != 0) {
+            $size = intval($size);
+        }
+
+        if ($usage != 0) {
+            $usage = intval($usage);
+        }
+
+        $usageSign = Crypt_GPG_SubKey::USAGE_SIGN;
+
+        if (   $algorithm === Crypt_GPG_SubKey::ALGORITHM_ELGAMAL_ENC
+            && ($usage & $usageSign) === $usageSign
+        ) {
+            throw new Crypt_GPG_InvalidKeyParamsException(
+                'The Elgamal algorithm is not capable of signing. Please ' .
+                'specify a different algorithm or do not include signing ' .
+                'as a usage for the sub-key.',
+                0,
+                $algorithm,
+                $size,
+                $usage
+            );
+        }
+
+        $usageEncrypt = Crypt_GPG_SubKey::USAGE_ENCRYPT;
+
+        if (   $algorithm === Crypt_GPG_SubKey::ALGORITHM_DSA
+            && ($usage & $usageEncrypt) === $usageEncrypt
+        ) {
+            throw new Crypt_GPG_InvalidKeyParamsException(
+                'The DSA algorithm is not capable of encrypting. Please ' .
+                'specify a different algorithm or do not include encryption ' .
+                'as a usage for the sub-key.',
+                0,
+                $algorithm,
+                $size,
+                $usage
+            );
+        }
+
+        $this->subKeyAlgorithm = $algorithm;
+
+        if ($size != 0) {
+            $this->subKeySize = $size;
+        }
+
+        if ($usage != 0) {
+            $this->subKeyUsage = $usage;
+        }
+
+        return $this;
+    }
+
+    // }}}
+    // {{{ setStatusHandler()
+
+    /**
+     * Sets the status handler to use for key generation
+     *
+     * Normally this method does not need to be used. It provides a means for
+     * dependency injection.
+     *
+     * @param Crypt_GPG_KeyStatusHandler $handler the key status handler to
+     *                                            use.
+     *
+     * @return Crypt_GPG_KeyGenerator the current object, for fluent interface.
+     */
+    public function setStatusHandler(
+        Crypt_GPG_KeyGeneratorStatusHandler $handler
+    ) {
+        $this->statusHandler = $handler;
+        return $this;
+    }
+
+    // }}}
+    // {{{ setErrorHandler()
+
+    /**
+     * Sets the error handler to use for key generation
+     *
+     * Normally this method does not need to be used. It provides a means for
+     * dependency injection.
+     *
+     * @param Crypt_GPG_KeyErrorHandler $handler the key error handler to
+     *                                           use.
+     *
+     * @return Crypt_GPG_KeyGenerator the current object, for fluent interface.
+     */
+    public function setErrorHandler(
+        Crypt_GPG_KeyGeneratorErrorHandler $handler
+    ) {
+        $this->errorHandler = $handler;
+        return $this;
+    }
+
+    // }}}
+    // {{{ generateKey()
+
+    /**
+     * Generates a new key-pair in the current keyring
+     *
+     * Secure key generation requires true random numbers, and as such can be
+     * solw. If the operating system runs out of entropy, key generation will
+     * block until more entropy is available.
+     *
+     * If quick key generation is important, a hardware entropy generator, or
+     * an entropy gathering daemon may be installed. For example,
+     * administrators of Debian systems may want to install the 'randomsound'
+     * package.
+     *
+     * @param string|Crypt_GPG_UserId $name    either a {@link Crypt_GPG_UserId}
+     *                                         object, or a string containing
+     *                                         the name of the user id.
+     * @param string                  $email   optional. If <i>$name</i> is
+     *                                         specified as a string, this is
+     *                                         the email address of the user id.
+     * @param string                  $comment optional. If <i>$name</i> is
+     *                                         specified as a string, this is
+     *                                         the comment of the user id.
+     *
+     * @return Crypt_GPG_Key the newly generated key.
+     *
+     * @throws Crypt_GPG_KeyNotCreatedException if the key parameters are
+     *         incorrect, if an unknown error occurs during key generation, or
+     *         if the newly generated key is not found in the keyring.
+     *
+     * @throws Crypt_GPG_Exception if an unknown or unexpected error occurs.
+     *         Use the <kbd>debug</kbd> option and file a bug report if these
+     *         exceptions occur.
+     */
+    public function generateKey($name, $email = '', $comment = '')
+    {
+        $handle = uniqid('key', true);
+
+        $userId = $this->getUserId($name, $email, $comment);
+
+        $keyParams = array(
+            'Key-Type'      => $this->keyAlgorithm,
+            'Key-Length'    => $this->keySize,
+            'Key-Usage'     => $this->getUsage($this->keyUsage),
+            'Subkey-Type'   => $this->subKeyAlgorithm,
+            'Subkey-Length' => $this->subKeySize,
+            'Subkey-Usage'  => $this->getUsage($this->subKeyUsage),
+            'Name-Real'     => $userId->getName(),
+            'Handle'        => $handle,
+        );
+
+        if ($this->expirationDate != 0) {
+            // GnuPG only accepts granularity of days
+            $expirationDate = date('Y-m-d', $this->expirationDate);
+            $keyParams['Expire-Date'] = $expirationDate;
+        }
+
+        if ($this->passphrase != '') {
+            $keyParams['Passphrase'] = $this->passphrase;
+        }
+
+        if ($userId->getEmail() != '') {
+            $keyParams['Name-Email'] = $userId->getEmail();
+        }
+
+        if ($userId->getComment() != '') {
+            $keyParams['Name-Comment'] = $userId->getComment();
+        }
+
+
+        $keyParamsFormatted = array();
+        foreach ($keyParams as $name => $value) {
+            $keyParamsFormatted[] = $name . ': ' . $value;
+        }
+
+        $input = implode("\n", $keyParamsFormatted) . "\n%commit\n";
+
+        $statusHandler = clone $this->statusHandler;
+        $statusHandler->setHandle($handle);
+
+        $errorHandler = clone $this->errorHandler;
+
+        $this->engine->reset();
+        $this->engine->addStatusHandler(array($statusHandler, 'handle'));
+        $this->engine->addErrorHandler(array($errorHandler, 'handle'));
+        $this->engine->setInput($input);
+        $this->engine->setOutput($output);
+        $this->engine->setOperation('--gen-key', array('--batch'));
+        $this->engine->run();
+
+        $code = $errorHandler->getErrorCode();
+        switch ($code) {
+        case self::ERROR_BAD_KEY_PARAMS:
+            switch ($errorHandler->getLineNumber()) {
+            case 1:
+                throw new Crypt_GPG_InvalidKeyParamsException(
+                    'Invalid primary key algorithm specified.',
+                    0,
+                    $this->keyAlgorithm,
+                    $this->keySize,
+                    $this->keyUsage
+                );
+            case 4:
+                throw new Crypt_GPG_InvalidKeyParamsException(
+                    'Invalid sub-key algorithm specified.',
+                    0,
+                    $this->subKeyAlgorithm,
+                    $this->subKeySize,
+                    $this->subKeyUsage
+                );
+            default:
+                throw new Crypt_GPG_InvalidKeyParamsException(
+                    'Invalid key algorithm specified.'
+                );
+            }
+        }
+
+        $code = $this->engine->getErrorCode();
+
+        switch ($code) {
+        case self::ERROR_NONE:
+            break;
+        default:
+            throw new Crypt_GPG_Exception(
+                'Unknown error generating key-pair. Please use the \'debug\' ' .
+                'option when creating the Crypt_GPG object, and file a bug ' .
+                'report at ' . self::BUG_URI,
+                $code
+            );
+        }
+
+        $code = $statusHandler->getErrorCode();
+
+        switch ($code) {
+        case self::ERROR_NONE:
+            break;
+        case self::ERROR_KEY_NOT_CREATED:
+            throw new Crypt_GPG_KeyNotCreatedException(
+                'Unable to create new key-pair. Invalid key parameters. ' .
+                'Make sure the specified key algorithms and sizes are ' .
+                'correct.',
+                $code
+            );
+        }
+
+        $fingerprint = $statusHandler->getKeyFingerprint();
+        $keys        = $this->_getKeys($fingerprint);
+
+        if (count($keys) === 0) {
+            throw new Crypt_GPG_KeyNotCreatedException(
+                sprintf(
+                    'Newly created key "%s" not found in keyring.',
+                    $fingerprint
+                )
+            );
+        }
+
+        return $keys[0];
+    }
+
+    // }}}
+    // {{{ getUsage()
+
+    /**
+     * Builds a GnuPG key usage string suitable for key generation
+     *
+     * See <b>doc/DETAILS</b> in the
+     * {@link http://www.gnupg.org/download/ GPG distribution} for detailed
+     * information on the key usage format.
+     *
+     * @param integer $usage a bitwise combination of the key usages. This is
+     *                       a combination of the Crypt_GPG_SubKey::USAGE_*
+     *                       constants.
+     *
+     * @return string the key usage string.
+     */
+    protected function getUsage($usage)
+    {
+        $map = array(
+            Crypt_GPG_SubKey::USAGE_ENCRYPT        => 'encrypt',
+            Crypt_GPG_SubKey::USAGE_SIGN           => 'sign',
+            Crypt_GPG_SubKey::USAGE_CERTIFY        => 'cert',
+            Crypt_GPG_SubKey::USAGE_AUTHENTICATION => 'auth',
+        );
+
+        // cert is always used for primary keys and does not need to be
+        // specified
+        $usage &= ~Crypt_GPG_SubKey::USAGE_CERTIFY;
+
+        $usageArray = array();
+
+        foreach ($map as $key => $value) {
+            if (($usage & $key) === $key) {
+                $usageArray[] = $value;
+            }
+        }
+
+        return implode(',', $usageArray);
+    }
+
+    // }}}
+    // {{{ getUserId()
+
+    /**
+     * Gets a user id object from parameters
+     *
+     * @param string|Crypt_GPG_UserId $name    either a {@link Crypt_GPG_UserId}
+     *                                         object, or a string containing
+     *                                         the name of the user id.
+     * @param string                  $email   optional. If <i>$name</i> is
+     *                                         specified as a string, this is
+     *                                         the email address of the user id.
+     * @param string                  $comment optional. If <i>$name</i> is
+     *                                         specified as a string, this is
+     *                                         the comment of the user id.
+     *
+     * @return Crypt_GPG_UserId a user id object for the specified parameters.
+     */
+    protected function getUserId($name, $email = '', $comment = '')
+    {
+        if ($name instanceof Crypt_GPG_UserId) {
+            $userId = $name;
+        } else {
+            $userId = new Crypt_GPG_UserId();
+            $userId->setName($name)->setEmail($email)->setComment($comment);
+        }
+
+        return $userId;
+    }
+
+    // }}}
+}
+
+// }}}
+
+?>