GPG - a Perl2GnuPG interface

- NAME
- DESCRIPTION
- SYNOPSIS
- INSTALLATION
- METHODS
- FAQ
- KNOWN BUGS
- TODO
- SUPPORT
- DOWNLOAD
- DEVELOPPEMENT
- SEE ALSO
- AUTHOR

# 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