NAME

PGP - perl module to work with PGP messages

SYNOPSIS

use PGP;

$message = new PGP $pgppath;

DESCRIPTION

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

PGP::new
```
        $pgp = new PGP [$pgppath], [$pgpexec];
    
```
Create the PGP encapsulation object. The standard location for the PGP executable is /usr/local/bin/pgpin.
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 options.
```
        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 "Password".

Examples
```
 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 "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 "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::Decrypt

        \%stats = Decrypt $pgp %args;

"Decrypt" will use a PGP secret key to decrypt a message. The secret key must reside on the secret keyring. The "Decrypt" method follows the same conventions for data transfer that "Sign" and "Encrypt" follow. The resulting associative array that is sent back contains three fields:

        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 following are the accepted arguments:

        Password        Password to use for decrypting
        File            File to decrypt
        Keyring         Needed to return info about document
        Plainfile       File to put the data in
        Text            Document to decrypt
        Wipe            Remove original file

The "Password" argument is required to perform the decryption of the document. The "Keyring" argument is also required if any document information is to be returned.

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 forward:
```
        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 "Info" method. Basically we send the document through the "Decrypt" method and grab the results.

PGP::Keyring

The "PGP::Keyring" object is used to perform key management functions.

PGP::Keyring::new

        $Keyring = new PGP::Keyring $pgpkeyring;

PGP::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::Keyring::Remove_Key
```
        Remove_Key $Keyring $key;
    
```
Remove a signature from a keyring.
PGP::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::Keyring::Sign_Key
```
        Sign_Key $Keyring %args;
    
```
This method will sign a designated key with the
PGP::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 change.
PGP::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::Keyring::List_Keys
```
        @{$keyobj} = List_Keys $Keyring;
    
```
List the keys on a given keyring. This routine simply captures the output of the command "pgp -kc $keyring" and does a quick parse on it. It takes the lines that it parses, and constructs PGP::Key objects. In the near future, this function will also pass the trust factors to the PGP::Key object. We got it in the output, so why not use it.
PGP::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.

PGP::Key

The "PGP::Key" object is used to store the individual key information. It is primarily used by the "PGP::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::Keyring" methods. The "PGP::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!

Author

        Gerard Hickey
        RR 2  Box 409
        Lower Main St.
        North Berwick, ME   03906
        hickey@ctron.com

Copyrights

        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.

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 52:: '=item' outside of any '=over'
Around line 501:: You forgot a '=back' before '=head2'
Around line 511:: '=item' outside of any '=over'
Around line 855:: You forgot a '=back' before '=head2'
Around line 869:: '=item' outside of any '=over'
Around line 907:: Expected '=item *'
Around line 1094:: You forgot a '=back' before '=head2'
Around line 1096:: '=item' outside of any '=over'
Around line 1098:: You forgot a '=back' before '=head2'