1NAME
2 Crypt::GPG - An Object Oriented Interface to GnuPG.
3
4VERSION
5 $Revision: 1.64 $
6 $Date: 2007/04/02 13:34:25 $
7
8SYNOPSIS
9 use Crypt::GPG;
10 my $gpg = new Crypt::GPG;
11
12 $gpg->gpgbin('/usr/bin/gpg'); # The GnuPG executable.
13 $gpg->secretkey('0x2B59D29E'); # Set ID of default secret key.
14 $gpg->passphrase('just testing'); # Set passphrase.
15
16 # Sign a message:
17
18 my $sign = $gpg->sign('testing again');
19
20 # Encrypt a message:
21
22 my @encrypted = $gpg->encrypt ('top secret', 'test@bar.com');
23
24 # Get message info:
25
26 my @recipients = $gpg->msginfo($encrypted);
27
28 # Decrypt a message.
29
30 my ($plaintext, $signature) = $gpg->verify($encrypted);
31
32 # Key generation:
33
34 $status = $gpg->keygen
35 ('Test', 'test@foo.com', 'ELG-E', 2048, 0, 'test passphrase');
36 print while (<$status>); close $status;
37
38 # Key database manipulation:
39
40 $gpg->addkey($key, @ids);
41 @keys = $gpg->keydb(@ids);
42
43 # Key manipulation:
44
45 $key = $keys[0];
46
47 $gpg->delkey($key);
48 $gpg->disablekey($key);
49 $gpg->enablekey($key);
50 $gpg->keypass($key, $oldpassphrase, $newpassphrase);
51 $keystring = $gpg->export($key);
52
53DESCRIPTION
54 The Crypt::GPG module provides access to the functionality of the GnuPG
55 (www.gnupg.org) encryption tool through an object oriented interface.
56
57 It provides methods for encryption, decryption, signing, signature
58 verification, key generation, key certification, export and import.
59 Key-server access is on the todo list.
60
61 This release of the module may create compatibility issues with previous
62 versions. If you find any such problems, or any bugs or documentation
63 errors, please do report them to crypt-gpg at neomailbox.com.
64
65CONSTRUCTOR
66 new()
67 Creates and returns a new Crypt::GPG object.
68
69DATA METHODS
70 gpgbin($path)
71 Sets the GPGBIN instance variable which gives the path to the GnuPG
72 binary.
73
74 gpgopts($opts)
75 Sets the GPGOPTS instance variable which may be used to pass
76 additional options to the GnuPG binary. For proper functioning of this
77 module, it is advisable to always include '--lock-multiple' in the
78 GPGOPTS string.
79
80 delay($seconds)
81 Sets the DELAY instance variable. This is no longer necessary (nor
82 used) in the current version of the module, but remains so existing
83 scripts don't break.
84
85 secretkey($keyid)
86 Sets the SECRETKEY instance variable which may be a KeyID or a
87 username. This is the ID of the default key to use for signing.
88
89 passphrase($passphrase)
90 Sets the PASSPHRASE instance variable, required for signing and
91 decryption.
92
93 text($boolean)
94 Sets the TEXT instance variable. If set true, GnuPG will use
95 network-compatible line endings for proper cross-platform
96 compatibility and the plaintext will gain a newline at the end, if it
97 does not already have one.
98
99 armor($boolean)
100 Sets the ARMOR instance variable, controlling the ASCII armoring of
101 output. The default is to use ascii-armoring. The module has not been
102 tested with this option turned off, and most likely will not work if
103 you switch this off.
104
105 detach($boolean)
106 Sets the DETACH instance variable. If set true, the sign method will
107 produce detached signature certificates, else it won't. The default is
108 to produce detached signatures.
109
110 encryptsafe($boolean)
111 Sets the ENCRYPTSAFE instance variable. If set true, encryption will
112 fail if trying to encrypt to a key which is not trusted. This is the
113 default. Turn this off if you want to encrypt to untrusted keys.
114
115 version($versionstring)
116 Sets the VERSION instance variable which can be used to change the
117 Version: string on the GnuPG output to whatever you like.
118
119 comment($commentstring)
120 Sets the COMMENT instance variable which can be used to change the
121 Comment: string on the GnuPG output to whatever you like.
122
123 nofork($flag)
124 Sets the NOFORK instance variable which if set to a true value will
125 cause keygen() not to fork a separate process for key generation.
126
127 debug($boolean)
128 Sets the DEBUG instance variable which causes the raw output of
129 Crypt::GPG's interaction with the GnuPG binary to be dumped to STDOUT.
130 By default, debugging is off.
131
132OBJECT METHODS
133 sign(@message)
134 Signs @message with the secret key specified with secretkey() and
135 returns the result as a string.
136
137 decrypt(\@message, [\@signature])
138 This is just an alias for verify()
139
140 verify(\@message, [\@signature])
141 Decrypts and/or verifies the message in @message, optionally using the
142 detached signature in @signature, and returns a list whose first
143 element is plaintext message as a string. If the message was signed, a
144 Crypt::GPG::Signature object is returned as the second element of the
145 list.
146
147 The Crypt::GPG::Signature object can be queried with the following
148 methods:
149
150 $sig->validity(); # 'GOOD', 'BAD', or 'UNKNOWN'
151 $sig->keyid(); # ID of signing key
152 $sig->time(); # Time the signature was made
153 $sig->trusted(); # Signature trust level
154
155 msginfo(@ciphertext)
156 Returns a list of the recipient key IDs that @ciphertext is encrypted
157 to.
158
159 encrypt($plaintext, $keylist, [-sign] )
160 Encrypts $plaintext with the public keys of the recipients listed in
161 $keylist and returns the result in a string, or undef if there was an
162 error while processing. Returns undef if any of the keys are not
163 found.
164
165 Either $plaintext or $keylist may be specified as either an arrayref
166 or a simple scalar.
167
168 If $plaintext is a an arrayref, it will be join()ed without newlines.
169
170 If you want to encrypt to multiple recipients, you must use the
171 arrayref version of $keylist. A scalar $keylist works for only a
172 single key ID.
173
174 If the -sign option is provided, the message will be signed before
175 encryption. The secret key and passphrase must be set for signing to
176 work. They can be set with the secretkey() and passphrase() methods.
177
178 addkey($key, $pretend, @keyids)
179 Adds the keys given in $key to the user's key ring and returns a list
180 of Crypt::GPG::Key objects corresponding to the keys that were added.
181 $key may be a string or an array reference.
182
183 If $pretend is true, it pretends to add the key and creates the key
184 object, but doesn't actually perform the key addition.
185
186 Optionally, a list of key IDs may be specified. If a list of key IDs
187 is specified, only keys that match those IDs will be imported. The
188 rest will be ignored.
189
190 export($key)
191 Exports the key specified by the Crypt::GPG::Key object $key and
192 returns the result as a string.
193
194 keygen($name, $email, $keytype, $keysize, $expire, $passphrase)
195 Creates a new keypair with the parameters specified. The only
196 supported $keytype currently is 'ELG-E'. $keysize can be any of 1024,
197 2048, 3072 or 4096. Returns undef if there was an error, otherwise
198 returns a filehandle that reports the progress of the key generation
199 process similar to the way GnuPG does. The key generation is not
200 complete till you read an EOF from the returned filehandle.
201
202 certify($keyid, $local, @uids)
203 Certifies to the authenticity of UIDs of the key with ID $keyid. If
204 $local is true, the certification will be non-exportable. The @uids
205 parameter should contain the list of UIDs to certify (the first UID of
206 a key is 0).
207
208 keydb(@keyids)
209 Returns an array of Crypt::GPG::Key objects corresponding to the Key
210 IDs listed in @keyids. This method used to be called keyinfo and that
211 is still an alias to this method.
212
213 parsekeys(@keylist)
214 Parses a raw GnuPG formatted key listing in @keylist and returns an
215 array of Crypt::GPG::Key objects.
216
217 keypass($key, $oldpass, $newpass)
218 Change the passphrase for a key. Returns true if the passphrase change
219 succeeded, false if not, or undef if there was an error.
220
221 delkey($keyid)
222 Deletes the key specified by the Crypt::GPG::Key object $key from the
223 user's key ring. Returns undef if there was an error, or 1 if the key
224 was successfully deleted.
225
226 disablekey($keyid)
227 Disables the key specified by the Crypt::GPG::Key object $key.
228
229 enablekey($keyid)
230 Enables the key specified by the Crypt::GPG::Key object $key.
231
232Crypt::GPG::Signature
233 Documentation coming soon.
234
235Crypt::GPG::Key
236 Documentation coming soon.
237
238TODO
239 * Key server access.
240
241 * More complete key manipulation interface.
242
243 * Filehandle interface to handle large messages.
244
245BUGS
246 * Error checking needs work.
247
248 * Some key manipulation functions are missing.
249
250 * The method call interface is subject to change in future versions.
251
252 * The current implementation will probably eat up all your RAM if you
253 try to operate on huge messages. In future versions, this will be
254 addressed by reading from and returning filehandles, rather than using
255 in-core data.
256
257 * Methods may break if you don't use ASCII armoring.
258
259CHANGELOG
260 $Log: GPG.pm,v $
261
262 Revision 1.64 2014/09/18 12:21:25 ashish
263
264 - Applied Fix for RT 68339 (thanks to Todd Rinaldo)
265
266 Revision 1.63 2007/04/02 13:34:25 ashish
267
268 - Fixed a bug introduced by the changes in 1.62 wrt default signing key
269
270 Revision 1.62 2007/03/31 11:28:12 ashish
271
272 - Fixed debug()
273
274 - Fixed regex for signature line
275
276 - Non-forking version of keygen() (thanks to Greg Hill)
277
278 - Enabled use of default Key ID for signing
279
280 - Allow for GPG returning 8 or 16 bit KeyIDs (thanks to Roberto Jimenoca)
281
282 - Fixed tempfiles being left around after decrypt()
283
284 - Changed exit() to CORE::exit() (suggested by Jonathan R. Baker)
285
286 Revision 1.61 2006/12/21 12:36:28 ashish
287
288 - Skip tests if gpg not found.
289
290 - Use File::Spec to determine tmpdir. Suggested by Craig Manley.
291
292 Revision 1.59 2006/12/19 12:51:54 ashish
293
294 - Documentation fixes.
295
296 - Removed tests for obsolete 768 bit keys.
297
298 - Bugfixes.
299
300 - Tested with gpg 1.4.6.
301
302 Revision 1.57 2005/12/15 17:09:17 ashish
303
304 - Fixed bug in decrypt
305
306 - Fixed small key certification bugs.
307
308 Revision 1.50 2005/02/10 12:32:51 cvs
309
310 - Overhauled to use IPC::Run instead of Expect.
311
312 - Test suite split up into multiple scripts.
313
314 Revision 1.42 2002/12/11 03:33:19 cvs
315
316 - Fixed bug in certify() when trying to certify revoked a key.
317
318 - Applied dharris\x40drh.net's patch to allow for varying date formats
319 between gpg versions, and fix time parsing and the
320 Crypt::GPG::Signature autoloaded accessor functions.
321
322 Revision 1.40 2002/09/23 23:01:53 cvs
323
324 - Fixed a bug in keypass()
325
326 - Documentation fixes.
327
328 Revision 1.37 2002/09/21 02:37:49 cvs
329
330 - Fixed signing option in encrypt.
331
332 Revision 1.36 2002/09/21 00:03:29 cvs
333
334 - Added many tests and fixed a bunch of bugs.
335
336 Revision 1.34 2002/09/20 19:07:11 cvs
337
338 - Extensively modified formatting to make the code easier to
339 read. All lines are now < 80 chars.
340
341 - Removed all instances of invoking a shell.
342
343 - Misc. other stuff.
344
345 Revision 1.31 2002/09/20 16:38:45 cvs
346
347 - Cleaned up export and addkey. Fixed(?) addkey clobbering trustdb
348 problem (thanks to jrray\x40spacemeat.com for the patch). Added
349 support for signature verification on addkey pretend.
350
351 - No calls to POSIX::tmpnam remain (thanks to radek\x40karnet.pl and
352 jrray\x40spacemeat.com for suggesting File::Temp).
353
354 Revision 1.30 2002/09/20 15:25:47 cvs
355
356 - Fixed up tempfile handling and eliminated calls to the shell in
357 encrypt(), sign() and msginfo(). Passing all currently defined
358 tests.
359
360 - Hopefully also fixed signing during encryption and verification of
361 detached signatures. Not tested this yet.
362
363 Revision 1.29 2002/09/20 11:19:02 cvs
364
365 - Removed hack to Version: string. Only the Comment: string in GPG
366 output is now modified by Crypt::GPG. (Thanks to
367 eisen\x40schlund.de for pointing out the bug here)
368
369 - Removed code that incorrectly replaced 'PGP MESSAGE' with 'PGP
370 SIGNATURE' on detached signatures. (Thanks to ddcc\x40mit.edu for
371 pointing this out).
372
373 - Fixed up addkey() to properly handle pretend mode and to
374 selectively import only requested key IDs from a key block.
375
376 - parsekeys() now also figures out which keyring a key belongs to.
377
378 - Added certify() method, to enable certifying keys.
379
380 - Added Crypt::GPG::Signature methods - validity(), keyid(), time()
381 and trusted().
382
383AUTHOR
384 Crypt::GPG is Copyright (c) 2000-2007 Ashish Gulhati <crypt-gpg at
385 neomailbox.com>. All Rights Reserved.
386
387ACKNOWLEDGEMENTS
388 Thanks to Barkha, for inspiration; to the GnuPG team; and to everyone
389 who writes free software.
390
391LICENSE
392 This code is free software; you can redistribute it and/or modify it
393 under the same terms as Perl itself.
394
395BUGS REPORTS, PATCHES, FEATURE REQUESTS
396 Are very welcome. Email crypt-gpg at neomailbox.com.
397
398