Provided by: libgnupg-perl_0.19-5_all bug

NAME

       GnuPG - Perl module interface to the GNU Privacy Guard (v1.x.x series)

SYNOPSIS

           use GnuPG qw( :algo );

           my $gpg = new GnuPG();

           $gpg->encrypt(  plaintext    => "file.txt",    output        => "file.gpg",
                   armor    => 1,         sign    => 1,
                   passphrase  => $secret );

           $gpg->decrypt( ciphertext    => "file.gpg",    output        => "file.txt" );

           $gpg->clearsign( plaintext => "file.txt", output => "file.txt.asc",
                    passphrase => $secret,   armor => 1,
                   );

           $gpg->verify( signature => "file.txt.asc", file => "file.txt" );

           $gpg->gen_key( name => "Joe Blow",        comment => "My GnuPG key",
                  passphrase => $secret,
                   );

DESCRIPTION

       GnuPG is a perl interface to the GNU Privacy Guard. It uses the shared memory coprocess
       interface that gpg provides for its wrappers. It tries its best to map the interactive
       interface of the gpg to a more programmatic model.

API OVERVIEW

       The API is accessed through methods on a GnuPG object which is a wrapper around the gpg
       program.  All methods take their argument using named parameters, and errors are returned
       by throwing an exception (using croak).  If you want to catch errors you will have to use
       eval.

       When handed in a file handle for input or output parameters on many of the functions, the
       API attempts to tie that handle to STDIN and STDOUT. In certain persistent environments
       (particularly a web environment), this will not work. This problem can be avoided by
       passing in file names to all relevant parameters rather than a Perl file handle.

       There is also a tied file handle interface which you may find more convenient for
       encryption and decryption. See GnuPG::Tie(3) for details.

CONSTRUCTOR

   new ( [params] )
       You create a new GnuPG wrapper object by invoking its new method.  (How original !).  The
       module will try to finds the gpg program in your path and will croak if it can't find it.
       Here are the parameters that it accepts :

       gnupg_path
           Path to the gpg program.

       options
           Path to the options file for gpg. If not specified, it will use the default one
           (usually ~/.gnupg/options).

       homedir
           Path to the gpg home directory. This is the directory that contains the default
           options file, the public and private key rings as well as the trust database.

       trace
           If this variable is set to true, gpg debugging output will be sent to stderr.

           Example: my $gpg = new GnuPG();

METHODS

   gen_key( [params] )
       This methods is used to create a new gpg key pair. The methods croaks if there is an
       error. It is a good idea to press random keys on the keyboard while running this methods
       because it consumes a lot of entropy from the computer. Here are the parameters it accepts
       :

       algo
           This is the algorithm use to create the key. Can be DSA_ELGAMAL, DSA, RSA_RSA or RSA.
           It defaults to DSA_ELGAMAL. To import those constant in your name space, use the :algo
           tag.

       size
           The size of the public key. Defaults to 1024. Cannot be less than 768 bits, and keys
           longer than 2048 are also discouraged. (You *DO* know that your monitor may be leaking
           sensitive information ;-).

       valid
           How long the key is valid. Defaults to 0 or never expire.

       name
           This is the only mandatory argument. This is the name that will used to construct the
           user id.

       email
           Optional email portion of the user id.

       comment
           Optional comment portion of the user id.

       passphrase
           The passphrase that will be used to encrypt the private key. Optional but strongly
           recommended.

           Example: $gpg->gen_key( algo => DSA_ELGAMAL, size => 1024,
                       name => "My name" );

   import_keys( [params] )
       Import keys into the GnuPG private or public keyring. The method croaks if it encounters
       an error. It returns the number of keys imported. Parameters :

       keys
           Only parameter and mandatory. It can either be a filename or a reference to an array
           containing a list of files that will be imported.

           Example: $gpg->import_keys( keys => [ qw( key.pub key.sec ) ] );

   export_keys( [params] )
       Exports keys from the GnuPG keyrings. The method croaks if it encounters an error.
       Parameters :

       keys
           Optional argument that restricts the keys that will be exported.  Can either be a user
           id or a reference to an array of userid that specifies the keys to be exported. If
           left unspecified, all keys will be exported.

       secret
           If this argument is to true, the secret keys rather than the public ones will be
           exported.

       all If this argument is set to true, all keys (even those that aren't OpenPGP compliant)
           will be exported.

       output
           This argument specifies where the keys will be exported. Can be either a file name or
           a reference to a file handle. If not specified, the keys will be exported to stdout.

       armor
           Set this parameter to true, if you want the exported keys to be ASCII armored.

           Example: $gpg->export_keys( armor => 1, output => "keyring.pub" );

   encrypt( [params] )
       This method is used to encrypt a message, either using assymetric or symmetric
       cryptography. The methods croaks if an error is encountered. Parameters:

       plaintext
           This argument specifies what to encrypt. It can be either a filename or a reference to
           a file handle. If left unspecified, STDIN will be encrypted.

       output
           This optional argument specifies where the ciphertext will be output.  It can be
           either a file name or a reference to a file handle. If left unspecified, the
           ciphertext will be sent to STDOUT.

       armor
           If this parameter is set to true, the ciphertext will be ASCII armored.

       symmetric
           If this parameter is set to true, symmetric cryptography will be used to encrypt the
           message. You will need to provide a passphrase parameter.

       recipient
           If not using symmetric cryptography, you will have to provide this parameter. It
           should contains the userid of the intended recipient of the message. It will be used
           to look up the key to use to encrypt the message. The parameter can also take an array
           ref, if you want to encrypt the message for a group of recipients.

       sign
           If this parameter is set to true, the message will also be signed. You will probably
           have to use the passphrase parameter to unlock the private key used to sign message.
           This option is incompatible with the symmetric one.

       local-user
           This parameter is used to specified the private key that will be used to sign the
           message. If left unspecified, the default user will be used. This option only makes
           sense when using the sign option.

       passphrase
           This parameter contains either the secret passphrase for the symmetric algorithm or
           the passphrase that should be used to decrypt the private key.

           Example: $gpg->encrypt( plaintext => file.txt, output => "file.gpg",
                       sign => 1, passphrase => $secret
                       );

   sign( [params] )
       This method is used create a signature for a file or stream of data.  This method croaks
       on errors. Parameters :

       plaintext
           This argument specifies what  to sign. It can be either a filename or a reference to a
           file handle. If left unspecified, the data read on STDIN will be signed.

       output
           This optional argument specifies where the signature will be output.  It can be either
           a file name or a reference to a file handle. If left unspecified, the signature will
           be sent to STDOUT.

       armor
           If this parameter is set to true, the signature will be ASCII armored.

       passphrase
           This parameter contains the secret that should be used to decrypt the private key.

       local-user
           This parameter is used to specified the private key that will be used to make the
           signature . If left unspecified, the default user will be used.

       detach-sign
           If set to true, a digest of the data will be signed rather than the whole file.

           Example: $gpg->sign( plaintext => "file.txt", output => "file.txt.asc",
                    armor => 1,
                    );

   clearsign( [params] )
       This methods clearsign a message. The output will contains the original message with a
       signature appended. It takes the same parameters as the sign method.

   verify( [params] )
       This method verifies a signature against the signed message. The methods croaks if the
       signature is invalid or an error is encountered. If the signature is valid, it returns an
       hash with the signature parameters. Here are the method's parameters :

       signature
           If the message and the signature are in the same file (i.e. a clearsigned message),
           this parameter can be either a file name or a reference to a file handle. If the
           signature doesn't follows the message, than it must be the name of the file that
           contains the signature.

       file
           This is a file name or a reference to an array of file names that contains the signed
           data.

       When the signature is valid, here are the elements of the hash that is returned by the
       method :

       sigid
           The signature id. This can be used to protect against replay attack.

       date
           The data at which the signature has been made.

       timestamp
           The epoch timestamp of the signature.

       keyid
           The key id used to make the signature.

       user
           The userid of the signer.

       fingerprint
           The fingerprint of the signature.

       trust
           The trust value of the public key of the signer. Those are values that can be imported
           in your namespace with the :trust tag. They are (TRUST_UNDEFINED, TRUST_NEVER,
           TRUST_MARGINAL, TRUST_FULLY, TRUST_ULTIMATE).

           Example : my $sig = $gpg->verify( signature => "file.txt.asc",
                             file => "file.txt" );

   decrypt( [params] )
       This method decrypts an encrypted message. It croaks, if there is an error while
       decrypting the message. If the message was signed, this method also verifies the
       signature. If decryption is sucessful, the method either returns the valid signature
       parameters if present, or true. Method parameters :

       ciphertext
           This optional parameter contains either the name of the file containing the ciphertext
           or a reference to a file handle containing the ciphertext. If not present, STDIN will
           be decrypted.

       output
           This optional parameter determines where the plaintext will be stored.  It can be
           either a file name or a reference to a file handle.  If left unspecified, the
           plaintext will be sent to STDOUT.

       symmetric
           This should be set to true, if the message is encrypted using symmetric cryptography.

       passphrase
           The passphrase that should be used to decrypt the message (in the case of a message
           encrypted using a symmetric cipher) or the secret that will unlock the private key
           that should be used to decrypt the message.

           Example: $gpg->decrypt( ciphertext => "file.gpg", output => "file.txt"
                       passphrase => $secret );

BUGS AND LIMITATIONS

       This module doesn't work (yet) with the v2 branch of GnuPG.

AUTHOR

       Francis J. Lacoste <francis.lacoste@Contre.COM>

COPYRIGHT

       Copyright (c) 1999,2000 iNsu Innovations. Inc.  Copyright (c) 2001 Francis J. Lacoste

       This program is free software; you can redistribute it and/or modify it under the terms of
       the GNU General Public License as published by the Free Software Foundation; either
       version 2 of the License, or (at your option) any later version.

SEE ALSO

       GnuPG::Tie

       Alternative module: GnuPG::Interface

       gpg(1)