view release on metacpan or  search on metacpan

GPG.pm  view on Meta::CPAN

  }


=head1 NAME

GPG - a Perl2GnuPG interface

=head1 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)


=head1 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();


=head1 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

=head1 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.

=over 4

=item I<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)

=item I<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.

=item I<list_packets $packet>

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

=item I<import_keys $key>

Import the key(s) into the current keyring.

=item I<clearsign $key_id, $passphrase, $text>

Clearsign the current text.

=item I<detach_sign $key_id, $passphrase, $text>

Make a detached signature of the current text.

=item I<verify $signed_text>

Verify a signature.

=item I<verify_files $signed_text>

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

=item I<encrypt $text, ($dest_1, ...)>

Encrypt.

=item I<decrypt $passphrase, $text>

Decrypt (yes, really).

=item I<sign_encrypt $key_id, $passphrase, $text, ($dest_1, ...)>

Sign and Encrypt.

=item I<decrypt_verify $passphrase, $text>

Decrypt and verify signature.

=item I<list_keys()>

List all keys from your standard pubring

=item I<list_sig()>

List all keys and signatures from your standard pubring

=item I<delete_secret_key $key_id>

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

=item I<delete_key $key_id>

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

=back

=head1 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.


=head1 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...

=head1 TODO

 see CHANGES.txt.

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

=head1 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.

=head1 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)

=head1 DEVELOPPEMENT

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


=head1 SEE ALSO