1GPG(3)                User Contributed Perl Documentation               GPG(3)
2
3
4

NAME

6       Crypt::GPG - An Object Oriented Interface to GnuPG.
7

VERSION

9        $Revision: 1.64 $
10        $Date: 2007/04/02 13:34:25 $
11

SYNOPSIS

13         use Crypt::GPG;
14         my $gpg = new Crypt::GPG;
15
16         $gpg->gpgbin('/usr/bin/gpg');      # The GnuPG executable.
17         $gpg->secretkey('0x2B59D29E');     # Set ID of default secret key.
18         $gpg->passphrase('just testing');  # Set passphrase.
19
20         # Sign a message:
21
22         my $sign = $gpg->sign('testing again');
23
24         # Encrypt a message:
25
26         my @encrypted = $gpg->encrypt ('top secret', 'test@bar.com');
27
28         # Get message info:
29
30         my @recipients = $gpg->msginfo($encrypted);
31
32         # Decrypt a message.
33
34         my ($plaintext, $signature) = $gpg->verify($encrypted);
35
36         # Key generation:
37
38         $status = $gpg->keygen
39           ('Test', 'test@foo.com', 'ELG-E', 2048, 0, 'test passphrase');
40         print while (<$status>); close $status;
41
42         # Key database manipulation:
43
44         $gpg->addkey($key, @ids);
45         @keys = $gpg->keydb(@ids);
46
47         # Key manipulation:
48
49         $key = $keys[0];
50
51         $gpg->delkey($key);
52         $gpg->disablekey($key);
53         $gpg->enablekey($key);
54         $gpg->keypass($key, $oldpassphrase, $newpassphrase);
55         $keystring = $gpg->export($key);
56

DESCRIPTION

58       The Crypt::GPG module provides access to the functionality of the GnuPG
59       (www.gnupg.org) encryption tool through an object oriented interface.
60
61       It provides methods for encryption, decryption, signing, signature
62       verification, key generation, key certification, export and import.
63       Key-server access is on the todo list.
64
65       This release of the module may create compatibility issues with
66       previous versions. If you find any such problems, or any bugs or
67       documentation errors, please do report them to crypt-gpg at
68       neomailbox.com.
69

CONSTRUCTOR

71       new()
72         Creates and returns a new Crypt::GPG object.
73

DATA METHODS

75       gpgbin($path)
76         Sets the GPGBIN instance variable which gives the path to the GnuPG
77         binary.
78
79       gpgopts($opts)
80         Sets the GPGOPTS instance variable which may be used to pass
81         additional options to the GnuPG binary. For proper functioning of
82         this module, it is advisable to always include '--lock-multiple' in
83         the GPGOPTS string.
84
85       delay($seconds)
86         Sets the DELAY instance variable. This is no longer necessary (nor
87         used) in the current version of the module, but remains so existing
88         scripts don't break.
89
90       secretkey($keyid)
91         Sets the SECRETKEY instance variable which may be a KeyID or a
92         username. This is the ID of the default key to use for signing.
93
94       passphrase($passphrase)
95         Sets the PASSPHRASE instance variable, required for signing and
96         decryption.
97
98       text($boolean)
99         Sets the TEXT instance variable. If set true, GnuPG will use network-
100         compatible line endings for proper cross-platform compatibility and
101         the plaintext will gain a newline at the end, if it does not already
102         have one.
103
104       armor($boolean)
105         Sets the ARMOR instance variable, controlling the ASCII armoring of
106         output. The default is to use ascii-armoring. The module has not been
107         tested with this option turned off, and most likely will not work if
108         you switch this off.
109
110       detach($boolean)
111         Sets the DETACH instance variable. If set true, the sign method will
112         produce detached signature certificates, else it won't. The default
113         is to produce detached signatures.
114
115       encryptsafe($boolean)
116         Sets the ENCRYPTSAFE instance variable. If set true, encryption will
117         fail if trying to encrypt to a key which is not trusted. This is the
118         default. Turn this off if you want to encrypt to untrusted keys.
119
120       version($versionstring)
121         Sets the VERSION instance variable which can be used to change the
122         Version: string on the GnuPG output to whatever you like.
123
124       comment($commentstring)
125         Sets the COMMENT instance variable which can be used to change the
126         Comment: string on the GnuPG output to whatever you like.
127
128       nofork($flag)
129         Sets the NOFORK instance variable which if set to a true value will
130         cause keygen() not to fork a separate process for key generation.
131
132       debug($boolean)
133         Sets the DEBUG instance variable which causes the raw output of
134         Crypt::GPG's interaction with the GnuPG binary to be dumped to
135         STDOUT. By default, debugging is off.
136

OBJECT METHODS

138       sign(@message)
139         Signs @message with the secret key specified with secretkey() and
140         returns the result as a string.
141
142       decrypt(\@message, [\@signature])
143         This is just an alias for verify()
144
145       verify(\@message, [\@signature])
146         Decrypts and/or verifies the message in @message, optionally using
147         the detached signature in @signature, and returns a list whose first
148         element is plaintext message as a string. If the message was signed,
149         a Crypt::GPG::Signature object is returned as the second element of
150         the list.
151
152         The Crypt::GPG::Signature object can be queried with the following
153         methods:
154
155            $sig->validity();    # 'GOOD', 'BAD', or 'UNKNOWN'
156            $sig->keyid();       # ID of signing key
157            $sig->time();        # Time the signature was made
158            $sig->trusted();     # Signature trust level
159
160       msginfo(@ciphertext)
161         Returns a list of the recipient key IDs that @ciphertext is encrypted
162         to.
163
164       encrypt($plaintext, $keylist, [-sign] )
165         Encrypts $plaintext with the public keys of the recipients listed in
166         $keylist and returns the result in a string, or undef if there was an
167         error while processing. Returns undef if any of the keys are not
168         found.
169
170         Either $plaintext or $keylist may be specified as either an arrayref
171         or a simple scalar.
172
173         If $plaintext is a an arrayref, it will be join()ed without newlines.
174
175         If you want to encrypt to multiple recipients, you must use the
176         arrayref version of $keylist. A scalar $keylist works for only a
177         single key ID.
178
179         If the -sign option is provided, the message will be signed before
180         encryption. The secret key and passphrase must be set for signing to
181         work. They can be set with the secretkey() and passphrase() methods.
182
183       addkey($key, $pretend, @keyids)
184         Adds the keys given in $key to the user's key ring and returns a list
185         of Crypt::GPG::Key objects corresponding to the keys that were added.
186         $key may be a string or an array reference.
187
188         If $pretend is true, it pretends to add the key and creates the key
189         object, but doesn't actually perform the key addition.
190
191         Optionally, a list of key IDs may be specified. If a list of key IDs
192         is specified, only keys that match those IDs will be imported. The
193         rest will be ignored.
194
195       export($key)
196         Exports the key specified by the Crypt::GPG::Key object $key and
197         returns the result as a string.
198
199       keygen($name, $email, $keytype, $keysize, $expire, $passphrase)
200         Creates a new keypair with the parameters specified. The only
201         supported $keytype currently is 'ELG-E'. $keysize can be any of 1024,
202         2048, 3072 or 4096. Returns undef if there was an error, otherwise
203         returns a filehandle that reports the progress of the key generation
204         process similar to the way GnuPG does. The key generation is not
205         complete till you read an EOF from the returned filehandle.
206
207       certify($keyid, $local, @uids)
208         Certifies to the authenticity of UIDs of the key with ID $keyid. If
209         $local is true, the certification will be non-exportable. The @uids
210         parameter should contain the list of UIDs to certify (the first UID
211         of a key is 0).
212
213       keydb(@keyids)
214         Returns an array of Crypt::GPG::Key objects corresponding to the Key
215         IDs listed in @keyids. This method used to be called keyinfo and that
216         is still an alias to this method.
217
218       parsekeys(@keylist)
219         Parses a raw GnuPG formatted key listing in @keylist and returns an
220         array of Crypt::GPG::Key objects.
221
222       keypass($key, $oldpass, $newpass)
223         Change the passphrase for a key. Returns true if the passphrase
224         change succeeded, false if not, or undef if there was an error.
225
226       delkey($keyid)
227         Deletes the key specified by the Crypt::GPG::Key object $key from the
228         user's key ring. Returns undef if there was an error, or 1 if the key
229         was successfully deleted.
230
231       disablekey($keyid)
232         Disables the key specified by the Crypt::GPG::Key object $key.
233
234       enablekey($keyid)
235         Enables the key specified by the Crypt::GPG::Key object $key.
236

Crypt::GPG::Signature

238         Documentation coming soon.
239

Crypt::GPG::Key

241         Documentation coming soon.
242

TODO

244       • Key server access.
245
246       • More complete key manipulation interface.
247
248       • Filehandle interface to handle large messages.
249

BUGS

251       • Error checking needs work.
252
253       • Some key manipulation functions are missing.
254
255       • The method call interface is subject to change in future versions.
256
257       • The current implementation will probably eat up all your RAM if you
258         try to operate on huge messages. In future versions, this will be
259         addressed by reading from and returning filehandles, rather than
260         using in-core data.
261
262       • Methods may break if you don't use ASCII armoring.
263

CHANGELOG

265         $Log: GPG.pm,v $
266
267         Revision 1.64  2014/09/18 12:21:25  ashish
268
269           - Applied Fix for RT 68339 (thanks to Todd Rinaldo)
270
271         Revision 1.63  2007/04/02 13:34:25  ashish
272
273           - Fixed a bug introduced by the changes in 1.62 wrt default signing key
274
275         Revision 1.62  2007/03/31 11:28:12  ashish
276
277           - Fixed debug()
278
279           - Fixed regex for signature line
280
281           - Non-forking version of keygen() (thanks to Greg Hill)
282
283           - Enabled use of default Key ID for signing
284
285           - Allow for GPG returning 8 or 16 bit KeyIDs (thanks to Roberto Jimenoca)
286
287           - Fixed tempfiles being left around after decrypt()
288
289           - Changed exit() to CORE::exit() (suggested by Jonathan R. Baker)
290
291         Revision 1.61  2006/12/21 12:36:28  ashish
292
293           - Skip tests if gpg not found.
294
295           - Use File::Spec to determine tmpdir. Suggested by Craig Manley.
296
297         Revision 1.59  2006/12/19 12:51:54  ashish
298
299           - Documentation fixes.
300
301           - Removed tests for obsolete 768 bit keys.
302
303           - Bugfixes.
304
305           - Tested with gpg 1.4.6.
306
307         Revision 1.57  2005/12/15 17:09:17  ashish
308
309           - Fixed bug in decrypt
310
311           - Fixed small key certification bugs.
312
313         Revision 1.50  2005/02/10 12:32:51  cvs
314
315          - Overhauled to use IPC::Run instead of Expect.
316
317          - Test suite split up into multiple scripts.
318
319         Revision 1.42  2002/12/11 03:33:19  cvs
320
321          - Fixed bug in certify() when trying to certify revoked a key.
322
323          - Applied dharris\x40drh.net's patch to allow for varying date formats
324            between gpg versions, and fix time parsing and the
325            Crypt::GPG::Signature autoloaded accessor functions.
326
327         Revision 1.40  2002/09/23 23:01:53  cvs
328
329          - Fixed a bug in keypass()
330
331          - Documentation fixes.
332
333         Revision 1.37  2002/09/21 02:37:49  cvs
334
335          - Fixed signing option in encrypt.
336
337         Revision 1.36  2002/09/21 00:03:29  cvs
338
339          - Added many tests and fixed a bunch of bugs.
340
341         Revision 1.34  2002/09/20 19:07:11  cvs
342
343          - Extensively modified formatting to make the code easier to
344            read. All lines are now < 80 chars.
345
346          - Removed all instances of invoking a shell.
347
348          - Misc. other stuff.
349
350         Revision 1.31  2002/09/20 16:38:45  cvs
351
352          - Cleaned up export and addkey. Fixed(?) addkey clobbering trustdb
353            problem (thanks to jrray\x40spacemeat.com for the patch). Added
354            support for signature verification on addkey pretend.
355
356          - No calls to POSIX::tmpnam remain (thanks to radek\x40karnet.pl and
357            jrray\x40spacemeat.com for suggesting File::Temp).
358
359         Revision 1.30  2002/09/20 15:25:47  cvs
360
361          - Fixed up tempfile handling and eliminated calls to the shell in
362            encrypt(), sign() and msginfo(). Passing all currently defined
363            tests.
364
365          - Hopefully also fixed signing during encryption and verification of
366            detached signatures. Not tested this yet.
367
368         Revision 1.29  2002/09/20 11:19:02  cvs
369
370          - Removed hack to Version: string. Only the Comment: string in GPG
371            output is now modified by Crypt::GPG. (Thanks to
372            eisen\x40schlund.de for pointing out the bug here)
373
374          - Removed code that incorrectly replaced 'PGP MESSAGE' with 'PGP
375            SIGNATURE' on detached signatures. (Thanks to ddcc\x40mit.edu for
376            pointing this out).
377
378          - Fixed up addkey() to properly handle pretend mode and to
379            selectively import only requested key IDs from a key block.
380
381          - parsekeys() now also figures out which keyring a key belongs to.
382
383          - Added certify() method, to enable certifying keys.
384
385          - Added Crypt::GPG::Signature methods - validity(), keyid(), time()
386            and trusted().
387

AUTHOR

389       Crypt::GPG is Copyright (c) 2000-2007 Ashish Gulhati <crypt-gpg at
390       neomailbox.com>. All Rights Reserved.
391

ACKNOWLEDGEMENTS

393       Thanks to Barkha, for inspiration; to the GnuPG team; and to everyone
394       who writes free software.
395

LICENSE

397       This code is free software; you can redistribute it and/or modify it
398       under the same terms as Perl itself.
399

BUGS REPORTS, PATCHES, FEATURE REQUESTS

401       Are very welcome. Email crypt-gpg at neomailbox.com.
402
403
404
405perl v5.34.0                      2021-07-22                            GPG(3)
Impressum