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/pgp.
PGP::Exec
$pid = Exec $pgp $args, $in, $out, $err;
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 $args variable can have several substituted strings:
%p PGP path variable %r Path to PGP keyring %k Specified user
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
andFERR
; they must be referred to asPGP::FIN
,PGP::FOUT
andPGP::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 byKey
. TheEncrypt
method follow the same conventions as theSign
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), thenSign
can be left undefined or contain something other than a reference to a key object. Otherwise theSign
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. TheDecrypt
method follows the same conventions for data transfer thatSign
andEncrypt
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 Plainfile File to put the data in Text Document to decrypt Wipe Remove original file
PGP::Document_Info
%doc = Document_Info $pgp %args; \%doc = Document_Info $pgp %args;
Document_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 theDocument_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
Document_Info
method currently accepts the following arguments:File File to decrypt Text Document to decrypt
At this point, we cheat with the
Document_Info
method. Basically we send the document through theDecrypt
method and grab the results.
PGP::Keyring
PGP::Keyring::new
$Keyring = new PGP::Keyring $pgpkeyring, $pgp;
PGP::Keyring::Add_Key
$signature = Add_Key $Keyring $signature;
Add a signature to the keyring. At this point, there is no error checking or verification that the key has been added.
PGP::Remove_Key
Remove_Key $Keyring $keyid;
Remove a signature from a keyring.
PGP::Extract_Key
$key = Extract_Key $Keyring $keyobj;
Extract a key from the specified keyring. A real simple dirty way of extracting the key.
PGP::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::Revoke_Key
$certificate = Revoke_Key $Keyring $Keyobj;
Produce a revocation certificate for the given key.
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 single key.
PGP::Key
PGP Signature Object.
PGP::Key::new
$key = new PGP::Key $pgp, $keyline;
This is the constructor for the
PGP::Key
object. This is primarily used by thePGP::Keyring
methods. ThePGP::Keyring
methods keep track of the keys and maintain the Trust and Validity components. About the only useful method is thePGP::Key::Fingerprint
, which will return a string that is the finger print of the given key.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;
Known Bugs and Limitations
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.
9 POD Errors
The following errors were encountered while parsing the POD:
- Around line 15:
You forgot a '=back' before '=head1'
- Around line 35:
'=item' outside of any '=over'
- Around line 436:
You forgot a '=back' before '=head2'
- Around line 445:
'=item' outside of any '=over'
- Around line 662:
You forgot a '=back' before '=head2'
- Around line 668:
'=item' outside of any '=over'
- Around line 790:
You forgot a '=back' before '=head2'
- Around line 792:
'=item' outside of any '=over'
- Around line 794:
You forgot a '=back' before '=head2'