NAME

Crypt::PGP5 - A module for accessing PGP 5 functionality.

SYNOPSIS

  use Crypt::PGP5;
  $pgp = new Crypt::PGP5;

  $pgp->secretkey ($keyid);              # Set numeric or symbolic ID of default secret key.
  $pgp->passphrase ($passphrase);        # Set passphrase.
  $pgp->armor ($boolean);                # Switch ASCII armoring on or off.
  $pgp->detach ($boolean);               # Switch detached signatures on or off.
  $pgp->version ($versionstring);        # Set version string
  $pgp->debug ($boolean);                # Switch debugging output on or off.

  @signed = $pgp->sign (@message);

  @recipients = $pgp->msginfo (@ciphertext);

  @ciphertext = $pgp->encrypt ([@recipients], @plaintext);

  @plaintext = $pgp->verify (@ciphertext);

  ($validity, $userid, $keyid, $signtime, $keytime, $keysize,
   $trusted, @plaintext) = $pgp->verify (@signedmessage);

  ($validity, $userid, $keyid, $signtime, $keytime, $keysize,
   $trusted, @plaintext) = $pgp->dverify (@signature, @message);

  $pgp->keygen ($name, $email, $keytype, $keysize, $expire, $ringdir);
  $pgp->keypass ($keyid, $oldpasswd, $newpasswd);
  $pgp->addkey ($keyring, @key);
  $pgp->delkey ($keyid);
  $pgp->disablekey ($keyid);
  $pgp->enablekey ($keyid);
  @keylist = $pgp->keylist ();
  @key = $pgp->extractkey ($userid, $keyring);

DESCRIPTION

The Crypt::PGP5 module provides near complete access to PGP 5 functionality through an object oriented interface. It provides methods for encryption, decryption, signing, signature verification, key generation, key export and import, and most other key management functions.

CONSTRUCTOR

new ()

Creates and returns a new Crypt::PGP5 object.

DATA METHODS

secretkey ()

Sets the SECRETKEY instance variable which may be a KeyID or a username. This is the ID of the default key which will be used for signing.

passphrase ()

Sets the PASSPHRASE instance variable which is required for signing and decryption.

armor ()

Sets the ARMOR instance variable. If set to 0, Crypt::PGP doesn't ASCII armor its output. Else, it does. Default is to use ascii-armoring. I haven't tested this without ASCII armoring yet.

detach ()

Sets the DETACH instance variable. If set to 1, the sign method will produce detached signature certificates, else it won't.

version ()

Sets the VERSION instance variable which can be used to change the Version: string on the PGP output to whatever you like.

debug ()

Sets the DEBUG instance variable which causes the raw output of Crypt::PGP's interaction with the PGP binary to display.

OBJECT METHODS

sign (@message)

Signs @message with the secret key specified with secretkey () and returns the result as an array of lines.

verify (@message)

Verifies or decrypts the message in @message and returns the decrypted message. If the message was signed it returns (in this order) the status of the signature, the signer's username, the signing key ID, the time the signature was made, the time the signing key was created, the signing key size, and a boolean value indicating whether the signing key is trusted or not. Returns undef if the signature could not be verified.

dverify ([@message], [@signature])

Verifies the detactched signature @signature on @message and returns (in this order) the signer's username, the signing key ID, the time the signature was made, the time the signing key was created, the signing key size, and a boolean value indicating whether the signing key is trusted or not, along with an array containing the plaintext message. Returns undef if the signature could not be verified.

msginfo (@ciphertext)

Returns a list of the recipient key IDs that @ciphertext is encrypted to.

encrypt ([$keyid1, $keyid2...], @plaintext)

Encrypts @plaintext with the public keys of the recipients in the arrayref passed as the first argument and returns the result. undef if there was an error while processing. Returns ciphertext if the message could be encrypted to at least one of the recipients.

addkey ($key)

Adds the keys given in $key to the user's key ring and returns a list of Crypt::PGP::Key objects corresponding to the keys that were added.

delkey ($keyid)

Deletes the key with $keyid from the user's key ring.

disablekey ($keyid)

Disables the key with $keyid.

enablekey ($keyid)

Enables the key with $keyid.

keypass ($keyid, $oldpass, $newpass)

Change the passphrase for a key. Returns true if the passphrase change succeeded, false if not.

keylist ($ringdir)

Returns an array of Crypt::PGP5::Key objects corresponding to the user's keyfiles.

parsekeys (@keylist)

Parses a raw PGP formatted key listing and returns a list of Crypt::PGP5::Key objects.

extractkey ($userid, $keyring)

Extracts the key for $userid from $keyring and returns the result. The $keyring argument is optional and defaults to the public keyring set with pubring ().

keygen ($name, $email, $keytype, $keysize, $expire, $ringdir)

Creates a new keypair with the parameters specified. $keytype may be one of 'RSA' or 'DSS'. $keysize can be any of 768, 1024, 2048, 3072 or 4096 for DSS keys, and 768, 1024 or 2048 for RSA type keys. Returns undef if there was an error, otherwise returns the Key ID of the new key.

BUGS

Error checking needs work. Some keyring functions are missing. May not work with versions of PGP other than PGPfreeware 5.0i. The method call interface is subject to change in future versions.

AUTHOR

Crypt::PGP5 is Copyright (c) 1999-2000 Ashish Gulhati. All Rights Reserved.

ACKNOWLEDGEMENTS

Thanks to my wife, Barkha, for support and inspiration; to Raj Mathur, my Unix mentor; to Rex Rogers at Laissez Faire City (www.lfcity.com) for putting together a great environment to hack on freedom technologies; and of-course, to Phil Zimmerman, Larry Wall, Richard Stallman, and Linus Torvalds.

LICENSE

You may use, modify and redistribute this module under the same terms as Perl itself. It would be nice if you would mail your patches to me at hash@netropolis.org and I would love to hear about projects that make use of this module.

DISCLAIMER

This is free software. If it breaks, you own both parts.