Crypt_GPG
[ class tree: Crypt_GPG ] [ index: Crypt_GPG ] [ all elements ]
Packages:
Crypt_GPG


Classes:
Crypt_GPG
Crypt_GPG_BadPassphraseException
Crypt_GPG_DeletePrivateKeyException
Crypt_GPG_Driver_GnuPG
Crypt_GPG_Driver_Php
Crypt_GPG_DuplicateKeyImportException
Crypt_GPG_Exception
Crypt_GPG_FileException
Crypt_GPG_Key
Crypt_GPG_KeyNotFoundException
Crypt_GPG_MissingSelfSignatureException
Crypt_GPG_NoDataException
Crypt_GPG_OpenSubprocessException
Crypt_GPG_Signature
Crypt_GPG_SubKey
Crypt_GPG_UnsignedKeyException
Crypt_GPG_UserId
Files:
Exceptions.php
GnuPG.php
GPG.php
Key.php
Php.php
Signature.php
SubKey.php
UserId.php

Class: Crypt_GPG_Driver_Php

Source Location: /Crypt_GPG-0.6.0/GPG/Driver/Php.php

Class Overview

Crypt_GPG
   |
   --Crypt_GPG_Driver_Php

Native PHP Crypt_GPG driver


Author(s):

Copyright:

  • 2005-2008 silverorange

Variables

Methods

Inherited Variables

Inherited Methods

Class: Crypt_GPG

Crypt_GPG::__construct()
Creates a new Crypt_GPG object
Crypt_GPG::decrypt()
Decrypts string data using the given passphrase
Crypt_GPG::deletePrivateKey()
Deletes a private key from the keyring
Crypt_GPG::deletePublicKey()
Deletes a public key from the keyring
Crypt_GPG::encrypt()
Encrypts string data
Crypt_GPG::exportPublicKey()
Exports a public key from the keyring
Crypt_GPG::factory()
Static factory method to create a new GPG object using the specified backend driver
Crypt_GPG::getFingerprint()
Gets a key fingerprint from the keyring
Crypt_GPG::getKeys()
Gets the available keys in the keyring
Crypt_GPG::importKey()
Imports a public or private key into the keyring
Crypt_GPG::sign()
Signs data using the given key and passphrase
Crypt_GPG::verify()
Verifies signed data

Class Details

[line 99]
Native PHP Crypt_GPG driver

This driver uses PHP's native process control functions to directly control the GPG process. The GPG executable is required to be on the system.

For most systems, all data is passed to the GPG subprocess using file descriptors. This is the most secure method of passing data to the GPG subprocess.

If the operating system is Windows, this driver will use temporary files as a fallback for file descriptors above 2. Windows cannot use file descriptors above 2 with proc_open(). The Crypt_GPG_Driver_PHP::STATUS_FD and Crypt_GPG_Driver_PHP::MESSAGE_FD file descriptors are emulated using temporary files. All temporary files are deleted when a method call finishes or when the Crypt_GPG_Driver_Php::__destruct() method is called by PHP.



[ Top ]

Class Variables

$debug =  false

[line 158]

Whether or not to use debugging mode

When set to true, every GPG command is echoed before it is run. Sensitive data is always handled using pipes and is not specified as part of the command. As a result, sensitive data is never displayed when debug is enabled. Sensitive data includes private key data and passphrases.

Debugging is off by default.

  • Access: public

Type:   boolean


[ Top ]


Method Detail

__construct (Constructor)   [line 303]

Crypt_GPG_Driver_Php __construct( [array $options = array()])

Creates a new GPG object that uses PHP's native process manipulation functions to control the GPG process

Use the Crypt_GPG::factory() method to instantiate this class.

Available options for this driver are:

  • string homedir: The directory where the GPG keyring files are stored. If not specified, GPG uses the default of $HOME/.gnupg, where $HOME is the present user's home directory. This option only needs to be specified when $HOME/.gnupg is inappropriate.
  • string gpg_binary: 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.

  • Throws: PEAR_Exception if the provided 'gpg_binary' is invalid; or if no 'gpg_binary' is provided and no suitable binary could be found.
  • Access: protected

Overrides Crypt_GPG::__construct() (Creates a new Crypt_GPG object)

Parameters:

array   $options   —  optional. An array of options used to create the GPG object. All options must be optional and are represented as key-value pairs.

[ Top ]

__destruct (Destructor)   [line 338]

void __destruct( )

Closes open GPG subprocesses when this object is destroyed

Subprocesses should never be left open by this class unless there is an unknown error and unexpected script termination occurs.

  • Access: public

[ Top ]

decrypt   [line 935]

string decrypt( string $encrypted_data, [string $passphrase = null])

Decrypts string data using the given passphrase

This method assumes the required private key is available in the keyring and throws an exception if the private key is not available. To add a private key to the keyring, use the Crypt_GPG::importKey() method.

Calls GPG with the --decrypt command and passes the passphrase and encrypted data.

  • Return: the decrypted data.
  • Throws: Crypt_GPG_KeyNotFoundException if the private key needed to decrypt the data is not in the user's keyring.
  • Throws: Crypt_GPG_Exception if an unknown or unexpected error occurs. Use Crypt_GPG::$debug and file a bug report if these exceptions occur.
  • Throws: Crypt_GPG_NoDataException if specified data does not contain GPG encrypted data.
  • Throws: Crypt_GPG_BadPassphraseException if specified passphrase is incorrect or if a required passphrase is not specified.
  • Access: public

Overrides Crypt_GPG::decrypt() (Decrypts string data using the given passphrase)

Parameters:

string   $encrypted_data   —  the data to be decrypted.
string   $passphrase   —  optional. The passphrase of the private key used to encrypt the data. Only required if the private key requires a passphrase.

[ Top ]

deletePrivateKey   [line 577]

void deletePrivateKey( string $key_id)

Deletes a private key from the keyring

If more than one key fingerprint is avaliable for the specified $key_id (for example, if you use a non-unique uid) only the first private key is deleted.

Calls GPG with the --delete-secret-key option.

  • Throws: Crypt_GPG_Exception if an unknown or unexpected error occurs. Use Crypt_GPG::$debug and file a bug report if these exceptions occur.
  • Throws: Crypt_GPG_KeyNotFoundException if a private key with the given $key_id is not found.
  • Access: public

Overrides Crypt_GPG::deletePrivateKey() (Deletes a private key from the keyring)

Parameters:

string   $key_id   —  either the full uid of the private key, the email part of the uid of the private key or the key id of the private key. For example, "Test User (example) <test@example.com>", "test@example.com" or a hexidecimal string.

[ Top ]

deletePublicKey   [line 517]

void deletePublicKey( string $key_id)

Deletes a public key from the keyring

If more than one key fingerprint is avaliable for the specified $key_id (for example, if you use a non-unique uid) only the first public key is deleted.

The private key must be deleted first or an exception will be thrown. See Crypt_GPG::deletePrivateKey().

Calls GPG with the --delete-key option.

  • Throws: Crypt_GPG_KeyNotFoundException if a public key with the given $key_id is not found.
  • Throws: Crypt_GPG_DeletePrivateKeyException if the specified public key has an associated private key on the keyring. The private key must be deleted first.
  • Throws: Crypt_GPG_Exception if an unknown or unexpected error occurs. Use Crypt_GPG::$debug and file a bug report if these exceptions occur.
  • Access: public

Overrides Crypt_GPG::deletePublicKey() (Deletes a public key from the keyring)

Parameters:

string   $key_id   —  either the full uid of the public key, the email part of the uid of the public key or the key id of the public key. For example, "Test User (example) <test@example.com>", "test@example.com" or a hexidecimal string.

[ Top ]

encrypt   [line 855]

string encrypt( string $key_id, string $data, [boolean $armor = true])

Encrypts string data

Data is ASCII armored by default but may optionally be returned as binary.

If this method throws a Crypt_GPG_MissingSelfSignatureException, the public key needs to be signed. Keys may be manually signed using the shell command:

  1. gpg --sign-key &lt;key-id&gt; &lt;named-user&gt;
    2.
Encrypts data

Calls GPG with the --encrypt command.

  • Return: the encrypted data.
  • Throws: Crypt_GPG_Exception if an unknown or unexpected error occurs. Use Crypt_GPG::$debug and file a bug report if these exceptions occur.
  • Throws: Crypt_GPG_KeyNotFoundException if the a key with the given $key_id is not found.
  • Access: public

Overrides Crypt_GPG::encrypt() (Encrypts string data)

Parameters:

string   $key_id   —  the full uid of the public key to use for encryption. For example, "Test User (example) <test@example.com>".
string   $data   —  the data to be encrypted.
boolean   $armor   —  optional. If true, ASCII armored data is returned; otherwise, binary data is returned. Defaults to true.

[ Top ]

exportPublicKey   [line 449]

string exportPublicKey( string $key_id, [boolean $armor = true])

Exports a public key from the keyring

The exported key remains on the keyring. To delete the public key, use Crypt_GPG::deletePublicKey().

If more than one key fingerprint is avaliable for the specified $key_id (for example, if you use a non-unique uid) only the first public key is exported.

Calls GPG with the --export option.

  • Return: the public key data.
  • Throws: Crypt_GPG_Exception if an unknown or unexpected error occurs. Use Crypt_GPG::$debug and file a bug report if these exceptions occur.
  • Throws: Crypt_GPG_KeyNotFoundException if a public key with the given $key_id is not found.
  • Access: public

Overrides Crypt_GPG::exportPublicKey() (Exports a public key from the keyring)

Parameters:

string   $key_id   —  either the full uid of the public key, the email part of the uid of the public key or the key id of the public key. For example, "Test User (example) <test@example.com>", "test@example.com" or a hexidecimal string.
boolean   $armor   —  optional. If true, ASCII armored data is returned; otherwise, binary data is returned. Defaults to true.

[ Top ]

getFingerprint   [line 773]

string getFingerprint( string $key_id, [integer $format = Crypt_GPG::FORMAT_NONE])

Gets a key fingerprint from the keyring

If more than one key fingerprint is avaliable (for example, if you use a non-unique user id) only the first key fingerprint is returned.

Calls the GPG --list-keys command with the --with-fingerprint option to retrieve a public key fingerprint.

  • Return: the fingerprint of the key, or null if no fingerprint is found for the given $key_id.
  • Throws: Crypt_GPG_Exception if an unknown or unexpected error occurs. Use Crypt_GPG::$debug and file a bug report if these exceptions occur.
  • Access: public

Overrides Crypt_GPG::getFingerprint() (Gets a key fingerprint from the keyring)

Parameters:

string   $key_id   —  either the full user id of the key, the email part of the user id of the key, or the key id of the key. For example, "Test User (example) <test@example.com>", "test@example.com" or a hexidecimal string.
integer   $format   —  optional. How the fingerprint should be formatted. Use Crypt_GPG::FORMAT_X509 for X.509 certificate format, Crypt_GPG::FORMAT_CANONICAL for the format used by GnuPG output and Crypt_GPG::FORMAT_NONE for no formatting. Defaults to Crypt_GPG::FORMAT_NONE.

[ Top ]

getKeys   [line 634]

array getKeys( [string $key_id = ''])

Gets the available keys in the keyring

Calls GPG with the --list-keys option and grabs keys. See the first section of doc/DETAILS in the GPG package for a detailed description of how the GPG command output is parsed.

  • Return: an array of Crypt_GPG_Key objects.
  • See: Crypt_GPG_Key
  • Throws: Crypt_GPG_Exception if an unknown or unexpected error occurs. Use Crypt_GPG::$debug and file a bug report if these exceptions occur.
  • Access: public

Overrides Crypt_GPG::getKeys() (Gets the available keys in the keyring)

Parameters:

string   $key_id   —  optional. Only keys with that match the specified pattern are returned. The pattern may be part of a user id, a key id or a key fingerprint. If not specified, all keys are returned.

[ Top ]

importKey   [line 377]

array importKey( string $data)

Imports a public or private key into the keyring

Keys may be removed from the keyring using Crypt_GPG::deletePublicKey() or Crypt_GPG::deletePrivateKey().

Calls GPG with the --import option and provides GPG the key data to be imported.

  • Return: an associative array containing the following elements:
    • fingerprint: the key fingerprint of the imported key,
    • public_imported: the number of public keys imported,
    • public_unchanged: the number of unchanged public keys,
    • private_imported: the number of private keys imported,
    • private_unchanged: the number of unchanged private keys.
  • Throws: Crypt_GPG_Exception if an unknown or unexpected error occurs. Use Crypt_GPG::$debug and file a bug report if these exceptions occur.
  • Throws: Crypt_GPG_NoDataException if the key data is missing or if the data is is not valid key data.
  • Access: public

Overrides Crypt_GPG::importKey() (Imports a public or private key into the keyring)

Parameters:

string   $data   —  the key data to be imported.

[ Top ]

sign   [line 1043]

string sign( string $key_id, string $data, [string $passphrase = null], [boolean $mode = Crypt_GPG::SIGN_MODE_NORMAL], [boolean $armor = true])

Signs data using the given key and passphrase

Data may be signed using any one of the three available signing modes:

Calls GPGP with the --sign, --clearsign or --detach-sign commands.

  • Return: the signed data, or the signature data if a detached signature is requested.
  • Throws: Crypt_GPG_KeyNotFoundException if the private key is not in the user's keyring. Signing data requires the private key.
  • Throws: Crypt_GPG_BadPassphraseException if specified passphrase is incorrect or if a required passphrase is not specified.
  • Throws: Crypt_GPG_Exception if an unknown or unexpected error occurs. Use Crypt_GPG::$debug and file a bug report if these exceptions occur.
  • Access: public

Overrides Crypt_GPG::sign() (Signs data using the given key and passphrase)

Parameters:

string   $key_id   —  either the full uid of the private key, the email part of the uid of the private key or the key id of the private key. For example, "Test User (example) <test@example.com>", "test@example.com" or a hexidecimal string.
string   $data   —  the data to be signed.
string   $passphrase   —  optional. The passphrase of the private key used to sign the data. Only required if the private key requires a passphrase. Specify null for no passphrase.
boolean   $mode   —  otional. The data signing mode to use. Should be one of Crypt_GPG::SIGN_MODE_NORMAL, Crypt_GPG::SIGN_MODE_CLEAR or Crypt_GPG::SIGN_MODE_DETACHED. If not specified, defaults to Crypt_GPG::SIGN_MODE_NORMAL.
boolean   $armor   —  optional. If true, ASCII armored data is returned; otherwise, binary data is returned. Defaults to true. This has no effect if the mode Crypt_GPG::SIGN_MODE_CLEAR is used.

[ Top ]

verify   [line 1145]

Crypt_GPG_Signature verify( string $signed_data, [string $signature = ''])

Verifies signed data

The Crypt_GPG::decrypt() method may be used to get the original message if the signed data is not clearsigned and does not have a detached signature.

Calls GPG with the --verify option to verify signature data.

  • Return: the signature details of the signed data. If the signature is valid, the $valid property of the returned object will be true.
  • See: Crypt_GPG_Signature
  • Throws: Crypt_GPG_NoDataException if the provided data is not signed data.
  • Throws: Crypt_GPG_Exception if an unknown or unexpected error occurs. Use Crypt_GPG::$debug and file a bug report if these exceptions occur.
  • Access: public

Overrides Crypt_GPG::verify() (Verifies signed data)

Parameters:

string   $signed_data   —  the signed data to be verified.
string   $signature   —  optional. If verifying data signed using a detached signature, this must be the detached signature data. The data that was signed is specified in $signed_data.

[ Top ]
Documentation generated on Mon, 11 Mar 2019 15:19:34 -0400 by phpDocumentor 1.4.4. PEAR Logo Copyright © PHP Group 2004.