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

Class: Crypt_GPG

Source Location: /Crypt_GPG-1.0.0/GPG.php

Class Overview


A class to use GPG from PHP


Author(s):

Copyright:

  • 2005-2008 silverorange

Variables

Methods


Inherited Variables

Inherited Methods


Class Details

[line 112]
A class to use GPG from PHP

This class provides an object oriented interface to GNU Privacy Guard (GPG).

Though GPG can support symmetric-key cryptography, this class is intended only to facilitate public-key cryptography.



[ Top ]


Class Variables

$decryptKeys = array()

[line 314]

Keys used to sign

The array is of the form:

  1.  array(
  2.    $key_id => array(
  3.      'fingerprint' => $fingerprint,
  4.      'passphrase'  => $passphrase
  5.    )
  6.  );


Type:   array


[ Top ]

$encryptKeys = array()

[line 276]

Keys used to encrypt

The array is of the form:

  1.  array(
  2.    $key_id => array(
  3.      'fingerprint' => $fingerprint,
  4.      'passphrase'  => null
  5.    )
  6.  );


Type:   array


[ Top ]

$engine =  null

[line 257]

Engine used to control the GPG subprocess
  • Access: protected

Type:   Crypt_GPG_Engine


[ Top ]

$signKeys = array()

[line 295]

Keys used to decrypt

The array is of the form:

  1.  array(
  2.    $key_id => array(
  3.      'fingerprint' => $fingerprint,
  4.      'passphrase'  => $passphrase
  5.    )
  6.  );


Type:   array


[ Top ]



Method Detail

__construct (Constructor)   [line 353]

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

Creates a new GPG object

Available options are:

  • string homedir - the directory where the GPG keyring files are stored. If not specified, Crypt_GPG uses the default of ~/.gnupg.
  • string 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. The option gpgBinary is a deprecated alias for this option.
  • boolean debug - 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 useful to diagnose errors when using Crypt_GPG.

  • Throws: PEAR_Exception if the provided binary is invalid, or if no binary is provided and no suitable binary could be found.
  • Throws: Crypt_GPG_FileException if the homedir does not exist and cannot be created. This can happen if homedir is not specified, Crypt_GPG is run as the web user, and the web user has no home directory.
  • Access: public

Parameters:

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

[ Top ]

addDecryptKey   [line 1203]

void addDecryptKey( mixed $key, [string $passphrase = null])

Adds a key to use for decryption

Parameters:

mixed   $key     the key to use. This may be a key identifier, user id, fingerprint, Crypt_GPG_Key or Crypt_GPG_SubKey. The key must be able to encrypt.
string   $passphrase     optional. The passphrase of the key required for decryption.

[ Top ]

addEncryptKey   [line 1226]

void addEncryptKey( mixed $key)

Adds a key to use for encryption

Parameters:

mixed   $key     the key to use. This may be a key identifier, user id user id, fingerprint, Crypt_GPG_Key or Crypt_GPG_SubKey. The key must be able to encrypt.

[ Top ]

addSignKey   [line 1254]

void addSignKey( mixed $key, [string $passphrase = null])

Adds a key to use for signing

Parameters:

mixed   $key     the key to use. This may be a key identifier, user id, fingerprint, Crypt_GPG_Key or Crypt_GPG_SubKey. The key must be able to sign.
string   $passphrase     optional. The passphrase of the key required for signing.

[ Top ]

clearDecryptKeys   [line 1270]

void clearDecryptKeys( )

Clears all decryption keys

[ Top ]

clearEncryptKeys   [line 1286]

void clearEncryptKeys( )

Clears all encryption keys

[ Top ]

clearSignKeys   [line 1302]

void clearSignKeys( )

Clears all signing keys

[ Top ]

decrypt   [line 967]

string decrypt( string $encryptedData)

Decrypts string data

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() or Crypt_GPG::importKeyFile() methods.

  • 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 the debug option 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 a required passphrase is incorrect or if a required passphrase is not specified. See Crypt_GPG::addDecryptKey().
  • Access: public

Parameters:

string   $encryptedData     the data to be decrypted.

[ Top ]

decryptFile   [line 1010]

void|string decryptFile( string $encryptedFile, [string $decryptedFile = null])

Decrypts a file

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() or Crypt_GPG::importKeyFile() methods.

  • Return: if the $decryptedFile parameter is null, a string containing the decrypted data is returned.
  • Throws: Crypt_GPG_KeyNotFoundException if the private key needed to decrypt the data is not in the user's keyring.
  • Throws: Crypt_GPG_NoDataException if specified data does not contain GPG encrypted data.
  • Throws: Crypt_GPG_BadPassphraseException if a required passphrase is incorrect or if a required passphrase is not specified. See Crypt_GPG::addDecryptKey().
  • Throws: Crypt_GPG_Exception if an unknown or unexpected error occurs. Use the debug option and file a bug report if these exceptions occur.
  • Throws: Crypt_GPG_FileException if the output file is not writeable or if the input file is not readable.
  • Access: public

Parameters:

string   $encryptedFile     the name of the encrypted file data to decrypt.
string   $decryptedFile     optional. The name of the file to which the decrypted data should be written. If null or unspecified, the decrypted data is returned as a string.

[ Top ]

deletePrivateKey   [line 591]

void deletePrivateKey( string $keyId)

Deletes a private key from the keyring

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

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

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

Parameters:

string   $keyId     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 hexadecimal string.

[ Top ]

deletePublicKey   [line 527]

void deletePublicKey( string $keyId)

Deletes a public key from the keyring

If more than one key fingerprint is available for the specified $keyId (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().

  • Throws: Crypt_GPG_KeyNotFoundException if a public key with the given $keyId 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 the debug option and file a bug report if these exceptions occur.
  • Access: public

Parameters:

string   $keyId     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 hexadecimal string.

[ Top ]

encrypt   [line 897]

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

Encrypts string data

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

  • Return: the encrypted data.
  • Throws: Crypt_GPG_Exception if an unknown or unexpected error occurs. Use the debug option and file a bug report if these exceptions occur.
  • Throws: Crypt_GPG_KeyNotFoundException if no encryption key is specified. See Crypt_GPG::addEncryptKey().
  • Access: public

Parameters:

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 ]

encryptFile   [line 933]

void|string encryptFile( string $filename, [string $encryptedFile = null], [boolean $armor = true])

Encrypts a file

Encrypted data is ASCII armored by default but may optionally be saved as binary.

  • Return: if the $encryptedFile parameter is null, a string containing the encrypted data is returned.
  • Throws: Crypt_GPG_KeyNotFoundException if no encryption key is specified. See Crypt_GPG::addEncryptKey().
  • Throws: Crypt_GPG_FileException if the output file is not writeable or if the input file is not readable.
  • Throws: Crypt_GPG_Exception if an unknown or unexpected error occurs. Use the debug option and file a bug report if these exceptions occur.
  • Access: public

Parameters:

string   $filename     the filename of the file to encrypt.
string   $encryptedFile     optional. The filename of the file in which to store the encrypted data. If null or unspecified, the encrypted data is returned as a string.
boolean   $armor     optional. If true, ASCII armored data is returned; otherwise, binary data is returned. Defaults to true.

[ Top ]

exportPublicKey   [line 464]

string exportPublicKey( string $keyId, [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 available for the specified $keyId (for example, if you use a non-unique uid) only the first public key is exported.

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

Parameters:

string   $keyId     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 hexadecimal string.
boolean   $armor     optional. If true, ASCII armored data is returned; otherwise, binary data is returned. Defaults to true.

[ Top ]

getFingerprint   [line 816]

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

Gets a key fingerprint from the keyring

If more than one key fingerprint is available (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 $keyId.
  • Throws: Crypt_GPG_Exception if an unknown or unexpected error occurs. Use the debug option and file a bug report if these exceptions occur.
  • Access: public

Parameters:

string   $keyId     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 hexadecimal 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
  1. Crypt_GPG::FORMAT_NONE
.

[ Top ]

getKeys   [line 654]

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

Gets the available keys in the keyring

Calls GPG with the --list-keys command 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. If no keys match the specified $keyId an empty array is returned.
  • See: Crypt_GPG_Key
  • Throws: Crypt_GPG_Exception if an unknown or unexpected error occurs. Use the debug option and file a bug report if these exceptions occur.
  • Access: public

Parameters:

string   $keyId     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 ]

handleImportKeyStatus   [line 1360]

void handleImportKeyStatus( string $line, &$result)

Handles the status output from GPG for the import operation

This method is responsible for building the result array that is returned from the Crypt_GPG::importKey() method. See doc/DETAILS in the GPG distribution for detailed information on GPG's status output.


Parameters:

string   $line     the status line to handle.
array   &$result     the current result array being processed.

[ Top ]

handleSignStatus   [line 1324]

void handleSignStatus( string $line)

Handles the status output from GPG for the sign operation

This method is responsible for sending the passphrase commands when required by the Crypt_GPG::sign() method. See doc/DETAILS in the GPG distribution for detailed information on GPG's status output.


Parameters:

string   $line     the status line to handle.

[ Top ]

importKey   [line 389]

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

  • Return: an associative array containing the following elements:
    • fingerprint - the 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 the debug option 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

Parameters:

string   $data     the key data to be imported.

[ Top ]

importKeyFile   [line 428]

array importKeyFile( string $filename)

Imports a public or private key file into the keyring

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

  • Return: an associative array containing the following elements:
    • fingerprint - the 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. private keys.
  • Throws: Crypt_GPG_NoDataException if the key data is missing or if the data is is not valid key data.
  • Throws: Crypt_GPG_FileException if the key file is not readable.
  • Throws: Crypt_GPG_Exception if an unknown or unexpected error occurs. Use the debug option and file a bug report if these exceptions occur.
  • Access: public

Parameters:

string   $filename     the key file to be imported.

[ Top ]

sign   [line 1051]

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

Signs data

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

  • Return: the signed data, or the signature data if a detached signature is requested.
  • Throws: Crypt_GPG_KeyNotFoundException if no signing key is specified. See Crypt_GPG::addSignKey().
  • Throws: Crypt_GPG_BadPassphraseException if a specified passphrase is incorrect or if a required passphrase is not specified.
  • Throws: Crypt_GPG_Exception if an unknown or unexpected error occurs. Use the debug option and file a bug report if these exceptions occur.
  • Access: public

Parameters:

string   $data     the data to be signed.
boolean   $mode     optional. 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 ]

signFile   [line 1104]

void|string signFile( string $filename, [string $signedFile = null], [boolean $mode = Crypt_GPG::SIGN_MODE_NORMAL], [boolean $armor = true])

Signs a file

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

  • Return: if the $signedFile parameter is null, a string containing the signed data (or the signature data if a detached signature is requested) is returned.
  • Throws: Crypt_GPG_KeyNotFoundException if no signing key is specified. See Crypt_GPG::addSignKey().
  • Throws: Crypt_GPG_Exception if an unknown or unexpected error occurs. Use the debug option and file a bug report if these exceptions occur.
  • Throws: Crypt_GPG_BadPassphraseException if a specified passphrase is incorrect or if a required passphrase is not specified.
  • Throws: Crypt_GPG_FileException if the output file is not writeable or if the input file is not readable.
  • Access: public

Parameters:

string   $filename     the data to be signed.
string   $signedFile     optional. The name of the file in which the signed data should be stored. If null or unspecified, the signed data is returned as a string.
boolean   $mode     optional. 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 1139]

array verify( string $signedData, [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 use a detached signature.

  • Return: an array of Crypt_GPG_Signature objects for the signed data. For each signature that is valid, the Crypt_GPG_Signature::isValid() will return 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 the debug option and file a bug report if these exceptions occur.
  • Access: public

Parameters:

string   $signedData     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 $signedData.

[ Top ]

verifyFile   [line 1175]

array verifyFile( string $filename, [string $signature = ''])

Verifies a signed file

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

  • Return: an array of Crypt_GPG_Signature objects for the signed data. For each signature that is valid, the Crypt_GPG_Signature::isValid() will return true.
  • See: Crypt_GPG_Signature
  • Throws: Crypt_GPG_Exception if an unknown or unexpected error occurs. Use the debug option and file a bug report if these exceptions occur.
  • Throws: Crypt_GPG_NoDataException if the provided data is not signed data.
  • Throws: Crypt_GPG_FileException if the input file is not readable.
  • Access: public

Parameters:

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

[ Top ]


Documentation generated on Thu, 22 Jan 2009 21:30:13 -0500 by phpDocumentor 1.4.0. PEAR Logo Copyright © PHP Group 2004.