PGP - perl module to work with PGP messages

use PGP::Pipe;

    $message = new PGP $pgppath;

    The PGP module allow a perl script to work with PGP related

    * PGP::new
            $pgp = new PGP [$pgppath], [$pgpexec];

    Create the PGP encapsulation object. The standard location for
    the PGP executable is /usr/local/bin/pgp.

    * PGP::Exec
            $pid = Exec $pgp $args, $in, $out, $err, $nobatchmode;

    Execute the PGP command and attach the `$in', `$out', `$err'
    file handles. This should be fine for the moment, but need to
    look into making sure that data is not written to a temporary
    file anywhere. The `$nobatchmode' parameter causes the PGP
    command to be executed without the +batchmode parameter. This
    seems to only be necessary when a key is being signed.

    The $args variable can have several substituted strings:

            %p      PGP path variable
            %r      Path to PGP keyring
            %k      Specified user

    Note: The above substitutions may change at any time. It is not
    advised that you write applications with substitutions. Almost
    certainly, the next release will not include substitutions.

    The file handle variables--`$in', `$out' and `$err'--are send as
    normal filehandle names, but they reside in the PGP package. For
    example, the following procedure call is made:

            PGP->Exec ($args, FIN, FOUT, FERR);

    Even though the file handles were specified as `FIN', `FOUT' and
    `FERR'; they must be referred to as `PGP::FIN', `PGP::FOUT' and
    `PGP::FERR' in the orignal procedure that made the call.

    * PGP::Sign
            $signed_document = Sign $pgp %args;

    The `Sign' procedure will take a file or data and sign with a
    PGP secret key. The default behavior is to sign the data with
    the last secret key added to the keyring, but that can be
    overridden with the *Key* argument. This method always returns
    the signed document.

    The `%args' consist of a series of keys and values. Since there
    are several variations in the way data can be signed, not all
    the following options must be specified. This approach also
    makes it much easier to scale to new versions of PGP with more

            Armor           The output should be ASCII armored
            Clear           Produce a "clear" signature
            Encrypt         Encrypt the resulting signed document with
                            the given keyobj
            Detach          Create a detached signature
            File            Sign the specified file
            Key             Sign with the specified key object
            Nosave          Do not allow user to save message
            Password        The password to use for signing
            Signfile        The filename of the signed document
            Text            Data to be signed.
            Wipe            Remove the orignal file

    The only absolute argument that is always required is the


     Sign $pgp Password => 'xyz', File => '/etc/motd', Clear => 1, Armor => 1;

    This would return a signed copy of the /etc/motd file. In this
    case, we use a file as the input, but the output is returned at
    the method's termination. The orignal file remains in the clear,
    and the signature is ASCII armored (Base64).

     Sign $pgp Password => 'abc', Text => 'Important info', Armor => 1,
               Signfile => 'signed.asc', Key => $keyobj;

    This is sort of the reverse of the first example. It takes what
    is in the `Text' field and signs it. It then puts the result in
    the file signed.asc and returns it to the caller. In this case,
    the entire message is ASCII armored including the orignal text
    (i.e. `Text'). We also specify another secret key to produce the
    signature. For more information on the the key objects, please
    see the section on "PGP::Key" section.

    * PGP::Encrypt
            $encrypted_document = Encrypt $pgp %args;

    The `Encrypt' method produces an encrypted document with the
    given public keys specified by `Key'. The `Encrypt' method
    follow the same conventions as the `Sign' method. The data to be
    encrypted can be sent to the method or can reside in a file. The
    resulting encrypted data can also reside in a file or be sent
    back to the caller.

    In addition to encrypting a document, the document can also be
    signed by using the `Sign' key in the `%args' array. If the
    document is to be signed by the default secret key (last key
    added to the secret keyring), then `Sign' can be left undefined
    or contain something other than a reference to a key object.
    Otherwise the `Sign' key should contain a reference to a
    specific key object (see the section on "PGP::Key").

            Armor           The output should be ASCII armored
            Encryptfile     The filename of the encrypted document
            File            Encrypt the specified file
            Key             Encrypt with the specified key object
            Nosave          Do not allow user to save message
            Password        The password to use for signing
            Sign            In addition to encrypting, sign the document
            Text            Data to be encrypted
            Wipe            Remove orignal file

    * PGP::Info
            \%doc = Info $pgp %args;

    `Info' returns an associative array or a reference to an
    associative array to the caller. This returned structure
    contains information about the document that is sent to the
    `Info' method. The returned structure is fairly straight

            Text            The decrypted document
            Signature       PGP::Key object of the signer (if any)
            Time            Time document was signed (if any)
            Key             PGP::Key object used to decrypt document

    The `Info' method currently accepts the following arguments:

            File            File to decrypt
            Text            Document to decrypt
    At this point, we cheat with the C method. Basically
    we send the document through the C method and grab the


    The `PGP::Pipe::Keyring' object is used to perform key management

    * PGP::Pipe::Keyring::new
            $Keyring = new PGP::Pipe::Keyring $pgpkeyring;

    * PGP::Pipe::Keyring::Add_Key
            Add_Key $Keyring %args;

    Add a signature to the keyring. At this point, there is no error
    checking or verification that the key has been added.

    The `%args' associative array may contain the following:

            Text            The value is the public key
            File            File where the public key is stored

    * PGP::Pipe::Keyring::Remove_Key
            Remove_Key $Keyring $key;

    Remove a signature from a keyring.

    * PGP::Pipe::Keyring::Extract_Key
            $key = Extract_Key $Keyring $keyobj;

    Extract a key from the specified keyring. A real simple dirty
    way of extracting the key.

    * PGP::Pipe::Keyring::Sign_Key
            Sign_Key $Keyring %args;

    This method will sign a designated key with the

    * PGP::Pipe::Keyring::Generate_Key
            Generate_Key $Keyring;

    Generate a new secret and public key set. This routine will not
    be present in the first rev of code. It is also subject to

    * PGP::Pipe::Keyring::Revoke_Key
            $certificate = Revoke_Key $Keyring $Keyobj;

    Produce a revocation certificate for the given key. Revocation
    is actually a two step process. We must first mark the key as
    revoked. This is the same as the `Remove_Key' method. After
    flaging the key, the key must be extracted to produce a
    revocation certificate.

    * PGP::Pipe::Keyring::Find
            @keys = Find $keyring %criteria;
            \@keys = Find $keyring %criteria;
            $key = Find $keyring %criteria; (Single match)

    Function to locate a keys matching some criteria. This is not
    implemented as nicely as it should be (read kludge). The
    `%criteria' array is used to specify what keys are to be
    selected. The keys for the `%criteria' array are as follows:

            Keyid           Key with specifed keyid
            Owner           Name of the owner of the key
            Email           Email address of owner
            Bits            Size of the key in bits
            Date            Date that the key was generated
            Desc            Owner and Email keys combined

    The values for each specifed key (assocative array) are compared
    using a case-insensitive regular expression. This means that
    only a portion of the key data needs to be specified to have it
    selected. This also means that specifing too little criteria can
    cause several keys to be selected.


    The `PGP::Key' object is used to store the individual key
    information. It is primarily used by the `PGP::Pipe::Keyring' object
    and for passing to the various methods that accept key
    parameters to encrypt and sign documents.

    Future revisions will provide actual methods to do key
    comparison for the trust and validity factors. These methods
    will provide a standardized way to determine which keys can be
    trusted and which keys should not be used at all.

    * PGP::Key::new
            $key = new PGP::Key $keyline;

    This is the constructor for the `PGP::Key' object. This is
    primarily used by the `PGP::Pipe::Keyring' methods. The `PGP::Pipe::Keyring'
    methods keep track of the keys and maintain the Trust and
    Validity components. About the only useful method is the
    `PGP::Key::Fingerprint', which will return a string that is the
    finger print of the given key.

    + PGP::Key::Add_ID
            Add_ID $key $desc;

    The `Add_ID' method will add identification information to the
    owner and email portions of the given `PGP::Key' object. This is
    to support keys that multiple identification packets associated
    with them.

    * PGP::Key::Add_Sig
    * PGP::Key::Trust
    This will set and/or retrieve the trust factor. Currently, this
    routine will just store what is sent to it. Need to define some
    "trust" variables and provide useful routines to use them.

    * PGP::Key::Validity
    This function will set and/or return the validity factor. This
    subroutine is very much like PGP::Key::Trust. It also needs to
    be worked on quite a bit.

    * PGP::Key::Fingerprint
            $fingerprint = Fingerprint $key;

    * PGP::Key::Format
            $formatted_text = Format $key %args;

    This method will return a formatted text string for a key. It is
    essentially the same as do a 'pgp -kv' or 'pgp -kvv' for a key
    object. Currently the only argument that `Format' will recognize
    is the `Verbose' argument. The `Verbose' parameter will list the
    signatures that have certified the current key object.

  Known Bugs and Limitations

    + Hopefully none, proabably many!

            Gerard Hickey
            RR 2  Box 409
            Lower Main St.
            North Berwick, ME   03906


            Copyleft (l) 1996, by Gerard Hickey

    What this means is that this program may be copied freely given
    that there is no payment in exchange for this program, and that
    all the source is left intact with all comments and
    documentation. If you wish to modify this program to correct
    bugs or to extend it's usefullness, please coordinate such
    actions with the author.

<< Back to