NAME

GPG - a Perl2GnuPG interface

DESCRIPTION

GPG.pm is a Perl5 interface for using GnuPG. GPG works with $scalar (string), as opposed to the existing Perl5 modules (GnuPG.pm and GnuPG::Interface, which communicate with gnupg through filehandles or filenames)

SYNOPSIS

  use GPG;

    my ($passphrase,$key_id) = ("1234567890123456",'');

  my $gpg = new GPG(homedir  => './test'); # Creation

  die $gpg->error() if $gpg->error(); # Error handling

  my ($pubring,$secring) = $gpg->gen_key(key_size => "512",
                                        real_name  => "Joe Test",
                                        email      => 'nobody@yahoo.com',
                                        comment    => "",
                                        passphrase => $passphrase);

  my $pubkey = $gpg->list_packets($pubring);
  my $seckey = $gpg->list_packets($secring);
  $key_id = $pubkey->[0]{'key_id'};


  $gpg->import_keys($secring);
  $gpg->import_keys($pubring);

  my $signed = $gpg->clearsign($key_id,$passphrase,"TEST_TEXT");
  my $verify = $gpg->verify($signed);

  my $TEST_TEXT = $gpg->encrypt("TEST_TEXT",$key_id);
     $TEST_TEXT = $gpg->decrypt($passphrase,$TEST_TEXT);

     $TEST_TEXT = $gpg->sign_encrypt($key_id,$passphrase,$TEST_TEXT,$key_id);
  my $decrypt_verify = $gpg->decrypt_verify($passphrase,$TEST_TEXT);

  my $keys = $gpg->list_keys();
  my $sigd = $gpg->list_sig();

INSTALLATION

 % perl Makefile.PL
 % make
 % make test
 % make install

  Tips :
  - if you want secure memory, do not forget :
    % chown root /usr/local/bin/gpg ; chmod 4755 /usr/local/bin/gpg

METHODS

Look at the "test.pl" and "quick_test.pl" for examples and futher explanations.

You can set "VERBOSE" in "test.pl" to "1" and restart the test, to see more extensive output.

new %params

 Parameters are :
 - gnupg_path (most of time, 'gpg' stand inside /usr/local/bin)
 - homedir (gnupg homedir, default is $HOME/.gnupg)
 - config (gnupg config file)
 - armor (armored if 1, DEFAULT IS *1* !)
 - debug (1 for debugging, default is 0)

gen_key %params

 Parameters are :
 - key_size (see gnupg doc)
 - real_name (usually first name and last name, must not be empty)
 - email (email address, must not be empty)
 - comment (may be empty)
 - passphrase (*SHOULD* be at least 16 chars long...)

Please note that the keys are not imported after creation, please read "test.pl" for an example, or read the description of the "list_packets" method.

list_packets $packet

Output a packet description for public and secret keys, run "test.pl" with "VERBOSE=1" for a better description.

import_keys $key

Import the key(s) into the current keyring.

clearsign $key_id, $passphrase, $text

Clearsign the current text.

detach_sign $key_id, $passphrase, $text

Make a detached signature of the current text.

verify $signed_text

Verify a signature.

verify_files $signed_text

Verify signature of a all files from stdin, faster than verify() method.

encrypt $text, ($dest_1, ...)

Encrypt.

decrypt $passphrase, $text

Decrypt (yes, really).

sign_encrypt $key_id, $passphrase, $text, ($dest_1, ...)

Sign and Encrypt.

decrypt_verify $passphrase, $text

Decrypt and verify signature.

list_keys()

List all keys from your standard pubring

list_sig()

List all keys and signatures from your standard pubring

delete_secret_key $key_id

No yet implemented, gnupg doesn't accpt this in batch mode.

delete_key $key_id

No yet implemented, gnupg doesn't accept this in batch mode.

FAQ

 Q: How does it work ?
 A: it uses IPC::Open3 to connect the 'gpg' program. 
IPC::Open3 is executing the fork and managing the filehandles for you.

  Q: How secure is GPG ?
  A: As secure as you want... Be carefull. First, GPG is no 
more securer than 'gpg'. 
Second, all passphrases are stored in non-secure memory, unless
you "chown root" and "chmod 4755" your script first. Third, your
script probably store passpharses somewhere on the disk, and 
this is *not* secure.

  Q: Why using GPG, and not GnuPG or GnuPG::Interface ??
  A: Because of their input/output facilities, 
GnuPG.pm only works on filenames. 
GnuPG::Interface works with fileshandles, but is hard to use - all filehandle
management is left up to the user. GPG is working with $scalar only for both
input and output. Since I am developing for a web interface, I don't want to
write new files each time I need to communicate with gnupg.

KNOWN BUGS

Currently known bugs are caused by gnupg (www.gnupg.org) and *not* by GPG.pm :

 - the methods "delete_key" and "delete_secret_key" do not work, 
   Not because of a bug but because gnupg cannot do that in batch mode.
 - sign_key() and lsign_key() : "gpg: can't do that in batchmode"
 - verify() and verify_files() output only the wrong file, even only one has
   a wrong signature. Other files are ignored.

I hope a later version of gnupg will correct this issues...

TODO

 see CHANGES.txt.

 most of awaiting changes cannot be done until gnupg itself
 get an extented batch mode (currently very limited)

SUPPORT

Feel free to send me your questions and comments.

Feedback is ALWAYS welcome !

Commercial support on demand, but for most problems read the "Support" section on http://www.gnupg.org.

DOWNLOAD

CPAN : ${CPAN}/authors/id/M/MI/MILES/

sourceforge : https://sourceforge.net/project/filelist.php?group_id=8630

developpers info at https://sourceforge.net/projects/gpg

doc and home-page at http://gpg.sourceforge.net/ (this document)

DEVELOPPEMENT

 CVS access :
 
 look at http://acity.sourceforge.net/devel.html
 ... and replace "agora" or "acity" by "gpg".

SEE ALSO

 GnuPG            - http://www.gnupg.org
 GnuPG.pm         - input/output only through file_names
 GnuPG::Interface - input/output only through file_handles
                    see http://GnuPG-Interface.sourceforge.net/ or CPAN
 IPC::Open3       - communication with 'gpg', see "perldoc perlipc"

AUTHOR

 miles@_REMOVE_THIS_users.sourceforge.net, pf@_REMOVE_THIS_spin.ch
 extra thanks to tpo_at_spin

cpanm GPG

perl -MCPAN -e shell
install GPG