.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "GnuPG 3"
.TH GnuPG 3 "2012-04-16" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
GnuPG \- Perl module interface to the GNU Privacy Guard (v1.x.x series)
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    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,
\&            );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
GnuPG is a perl interface to the \s-1GNU\s0 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.
.SH "API OVERVIEW"
.IX Header "API OVERVIEW"
The \s-1API\s0 is accessed through methods on a GnuPG object which is
a wrapper around the \fBgpg\fR program.  All methods takes their
argument using named parameters, and errors are returned by
throwing an exception (using croak).  If you wan't to catch
errors you will have to use eval.
.PP
When handed in a file handle for input or output parameters
on many of the functions, the \s-1API\s0 attempts to tie that 
handle to \s-1STDIN\s0 and \s-1STDOUT.\s0 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.
.PP
There is also a tied file handle interface which you may find more
convenient for encryption and decryption. See \fIGnuPG::Tie\fR\|(3) for details.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.SS "new ( [params] )"
.IX Subsection "new ( [params] )"
You create a new GnuPG wrapper object by invoking its new method.
(How original !).  The module will try to finds the \fBgpg\fR program
in your path and will croak if it can't find it. Here are the
parameters that it accepts :
.IP "gnupg_path" 4
.IX Item "gnupg_path"
Path to the \fBgpg\fR program.
.IP "options" 4
.IX Item "options"
Path to the options file for \fBgpg\fR. If not specified, it will use
the default one (usually \fI~/.gnupg/options\fR).
.IP "homedir" 4
.IX Item "homedir"
Path to the \fBgpg\fR home directory. This is the directory that contains
the default \fIoptions\fR file, the public and private key rings as well
as the trust database.
.IP "trace" 4
.IX Item "trace"
If this variable is set to true, \fBgpg\fR debugging output will be sent
to stderr.
.PP
.Vb 1
\&    Example: my $gpg = new GnuPG();
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "gen_key( [params] )"
.IX Subsection "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 :
.IP "algo" 4
.IX Item "algo"
This is the algorithm use to create the key. Can be \fI\s-1DSA_ELGAMAL\s0\fR,
\&\fI\s-1DSA\s0\fR, \fI\s-1RSA_RSA\s0\fR or \fI\s-1RSA\s0\fR.
It defaults to \fI\s-1DSA_ELGAMAL\s0\fR. To import
those constant in your name space, use the \fI:algo\fR tag.
.IP "size" 4
.IX Item "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 ;\-).
.IP "valid" 4
.IX Item "valid"
How long the key is valid. Defaults to 0 or never expire.
.IP "name" 4
.IX Item "name"
This is the only mandatory argument. This is the name that will used
to construct the user id.
.IP "email" 4
.IX Item "email"
Optional email portion of the user id.
.IP "comment" 4
.IX Item "comment"
Optional comment portion of the user id.
.IP "passphrase" 4
.IX Item "passphrase"
The passphrase that will be used to encrypt the private key. Optional
but strongly recommended.
.PP
.Vb 2
\&    Example: $gpg\->gen_key( algo => DSA_ELGAMAL, size => 1024,
\&                name => "My name" );
.Ve
.SS "import_keys( [params] )"
.IX Subsection "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 :
.IP "keys" 4
.IX Item "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.
.PP
.Vb 1
\&    Example: $gpg\->import_keys( keys => [ qw( key.pub key.sec ) ] );
.Ve
.SS "export_keys( [params] )"
.IX Subsection "export_keys( [params] )"
Exports keys from the GnuPG keyrings. The method croaks if it
encounters an error. Parameters :
.IP "keys" 4
.IX Item "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.
.IP "secret" 4
.IX Item "secret"
If this argument is to true, the secret keys rather than the public
ones will be exported.
.IP "all" 4
.IX Item "all"
If this argument is set to true, all keys (even those that aren't
OpenPGP compliant) will be exported.
.IP "output" 4
.IX Item "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.
.IP "armor" 4
.IX Item "armor"
Set this parameter to true, if you want the exported keys to be \s-1ASCII\s0
armored.
.PP
.Vb 1
\&    Example: $gpg\->export_keys( armor => 1, output => "keyring.pub" );
.Ve
.SS "encrypt( [params] )"
.IX Subsection "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:
.IP "plaintext" 4
.IX Item "plaintext"
This argument specifies what to encrypt. It can be either a filename
or a reference to a file handle. If left unspecified, \s-1STDIN\s0 will be
encrypted.
.IP "output" 4
.IX Item "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 \s-1STDOUT.\s0
.IP "armor" 4
.IX Item "armor"
If this parameter is set to true, the ciphertext will be \s-1ASCII\s0
armored.
.IP "symmetric" 4
.IX Item "symmetric"
If this parameter is set to true, symmetric cryptography will be
used to encrypt the message. You will need to provide a \fIpassphrase\fR
parameter.
.IP "recipient" 4
.IX Item "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.
.IP "sign" 4
.IX Item "sign"
If this parameter is set to true, the message will also be signed. You
will probably have to use the \fIpassphrase\fR parameter to unlock the
private key used to sign message. This option is incompatible with
the \fIsymmetric\fR one.
.IP "local-user" 4
.IX Item "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 \fIsign\fR option.
.IP "passphrase" 4
.IX Item "passphrase"
This parameter contains either the secret passphrase for the symmetric
algorithm or the passphrase that should be used to decrypt the private
key.
.PP
.Vb 3
\&    Example: $gpg\->encrypt( plaintext => file.txt, output => "file.gpg",
\&                sign => 1, passphrase => $secret
\&                );
.Ve
.SS "sign( [params] )"
.IX Subsection "sign( [params] )"
This method is used create a signature for a file or stream of data.
This method croaks on errors. Parameters :
.IP "plaintext" 4
.IX Item "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
\&\s-1STDIN\s0 will be signed.
.IP "output" 4
.IX Item "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 \s-1STDOUT.\s0
.IP "armor" 4
.IX Item "armor"
If this parameter is set to true, the signature will be \s-1ASCII\s0 armored.
.IP "passphrase" 4
.IX Item "passphrase"
This parameter contains the secret that should be used to decrypt the
private key.
.IP "local-user" 4
.IX Item "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.
.IP "detach-sign" 4
.IX Item "detach-sign"
If set to true, a digest of the data will be signed rather than
the whole file.
.PP
.Vb 3
\&    Example: $gpg\->sign( plaintext => "file.txt", output => "file.txt.asc",
\&             armor => 1,
\&             );
.Ve
.SS "clearsign( [params] )"
.IX Subsection "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 \fBsign\fR method.
.SS "verify( [params] )"
.IX Subsection "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 :
.IP "signature" 4
.IX Item "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.
.IP "file" 4
.IX Item "file"
This is a file name or a reference to an array of file names that
contains the signed data.
.PP
When the signature is valid, here are the elements of the hash
that is returned by the method :
.IP "sigid" 4
.IX Item "sigid"
The signature id. This can be used to protect against replay
attack.
.IP "date" 4
.IX Item "date"
The data at which the signature has been made.
.IP "timestamp" 4
.IX Item "timestamp"
The epoch timestamp of the signature.
.IP "keyid" 4
.IX Item "keyid"
The key id used to make the signature.
.IP "user" 4
.IX Item "user"
The userid of the signer.
.IP "fingerprint" 4
.IX Item "fingerprint"
The fingerprint of the signature.
.IP "trust" 4
.IX Item "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
(\s-1TRUST_UNDEFINED, TRUST_NEVER, TRUST_MARGINAL, TRUST_FULLY, TRUST_ULTIMATE\s0).
.PP
.Vb 2
\&    Example : my $sig = $gpg\->verify( signature => "file.txt.asc",
\&                      file => "file.txt" );
.Ve
.SS "decrypt( [params] )"
.IX Subsection "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 :
.IP "ciphertext" 4
.IX Item "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, \s-1STDIN\s0 will be decrypted.
.IP "output" 4
.IX Item "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 \s-1STDOUT.\s0
.IP "symmetric" 4
.IX Item "symmetric"
This should be set to true, if the message is encrypted using
symmetric cryptography.
.IP "passphrase" 4
.IX Item "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.
.PP
.Vb 2
\&    Example: $gpg\->decrypt( ciphertext => "file.gpg", output => "file.txt"
\&                passphrase => $secret );
.Ve
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
This module doesn't work (yet) with the v2 branch of GnuPG.
.SH "AUTHOR"
.IX Header "AUTHOR"
Francis J. Lacoste <francis.lacoste@Contre.COM>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1999,2000 iNsu Innovations. Inc.
Copyright (c) 2001 Francis J. Lacoste
.PP
This program is free software; you can redistribute it and/or modify
it under the terms of the \s-1GNU\s0 General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
GnuPG::Tie
.PP
Alternative module: GnuPG::Interface
.PP
\&\fIgpg\fR\|(1)