1GPG(3) User Contributed Perl Documentation GPG(3)
2
6 Crypt::GPG - An Object Oriented Interface to GnuPG.
7
9 $Revision: 1.63 $
10 $Date: 2007/04/02 13:34:25 $
11
13 use Crypt::GPG;
14 my $gpg = new Crypt::GPG;
15 $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 # Sign a message:
21 my $sign = $gpg->sign('testing again');
23 # Encrypt a message:
25 my @encrypted = $gpg->encrypt ('top secret', 'test@bar.com');
27 # Get message info:
29 my @recipients = $gpg->msginfo($encrypted);
31 # Decrypt a message.
33 my ($plaintext, $signature) = $gpg->verify($encrypted);
35 # Key generation:
37 $status = $gpg->keygen
39 ('Test', 'test@foo.com', 'ELG-E', 2048, 0, 'test passphrase');
40 print while (<$status>); close $status;
41 # Key database manipulation:
43 $gpg->addkey($key, @ids);
45 @keys = $gpg->keydb(@ids);
46 # Key manipulation:
48 $key = $keys[0];
50 $gpg->delkey($key);
52 $gpg->disablekey($key);
53 $gpg->enablekey($key);
54 $gpg->keypass($key, $oldpassphrase, $newpassphrase);
55 $keystring = $gpg->export($key);
56
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 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 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
71 new()
72 Creates and returns a new Crypt::GPG object.
73
75 gpgbin($path)
76 Sets the GPGBIN instance variable which gives the path to the GnuPG
77 binary.
78 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 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 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 passphrase($passphrase)
95 Sets the PASSPHRASE instance variable, required for signing and
96 decryption.
97 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 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 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 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 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 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 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 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
138 sign(@message)
139 Signs @message with the secret key specified with secretkey() and
140 returns the result as a string.
141 decrypt(\@message, [\@signature])
143 This is just an alias for verify()
144 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 The Crypt::GPG::Signature object can be queried with the following
153 methods:
154 $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 msginfo(@ciphertext)
161 Returns a list of the recipient key IDs that @ciphertext is encrypted
162 to.
163 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 Either $plaintext or $keylist may be specified as either an arrayref
171 or a simple scalar.
172 If $plaintext is a an arrayref, it will be join()ed without newlines.
174 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 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 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 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 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 export($key)
196 Exports the key specified by the Crypt::GPG::Key object $key and
197 returns the result as a string.
198 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 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 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 parsekeys(@keylist)
219 Parses a raw GnuPG formatted key listing in @keylist and returns an
220 array of Crypt::GPG::Key objects.
221 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 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 disablekey($keyid)
232 Disables the key specified by the Crypt::GPG::Key object $key.
233 enablekey($keyid)
235 Enables the key specified by the Crypt::GPG::Key object $key.
236
238 Documentation coming soon.
239
241 Documentation coming soon.
242
244 · Key server access.
245 · More complete key manipulation interface.
247 · Filehandle interface to handle large messages.
249
251 · Error checking needs work.
252 · Some key manipulation functions are missing.
254 · The method call interface is subject to change in future versions.
256 · 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 · Methods may break if you don't use ASCII armoring.
263
265 $Log: GPG.pm,v $
266 Revision 1.63 2007/04/02 13:34:25 ashish
268 - Fixed a bug introduced by the changes in 1.62 wrt default signing key
270 Revision 1.62 2007/03/31 11:28:12 ashish
272 - Fixed debug()
274 - Fixed regex for signature line
276 - Non-forking version of keygen() (thanks to Greg Hill)
278 - Enabled use of default Key ID for signing
280 - Allow for GPG returning 8 or 16 bit KeyIDs (thanks to Roberto Jimenoca)
282 - Fixed tempfiles being left around after decrypt()
284 - Changed exit() to CORE::exit() (suggested by Jonathan R. Baker)
286 Revision 1.61 2006/12/21 12:36:28 ashish
288 - Skip tests if gpg not found.
290 - Use File::Spec to determine tmpdir. Suggested by Craig Manley.
292 Revision 1.59 2006/12/19 12:51:54 ashish
294 - Documentation fixes.
296 - Removed tests for obsolete 768 bit keys.
298 - Bugfixes.
300 - Tested with gpg 1.4.6.
302 Revision 1.57 2005/12/15 17:09:17 ashish
304 - Fixed bug in decrypt
306 - Fixed small key certification bugs.
308 Revision 1.50 2005/02/10 12:32:51 cvs
310 - Overhauled to use IPC::Run instead of Expect.
312 - Test suite split up into multiple scripts.
314 Revision 1.42 2002/12/11 03:33:19 cvs
316 - Fixed bug in certify() when trying to certify revoked a key.
318 - Applied dharris\x40drh.net's patch to allow for varying date formats
320 between gpg versions, and fix time parsing and the
321 Crypt::GPG::Signature autoloaded accessor functions.
322 Revision 1.40 2002/09/23 23:01:53 cvs
324 - Fixed a bug in keypass()
326 - Documentation fixes.
328 Revision 1.37 2002/09/21 02:37:49 cvs
330 - Fixed signing option in encrypt.
332 Revision 1.36 2002/09/21 00:03:29 cvs
334 - Added many tests and fixed a bunch of bugs.
336 Revision 1.34 2002/09/20 19:07:11 cvs
338 - Extensively modified formatting to make the code easier to
340 read. All lines are now < 80 chars.
341 - Removed all instances of invoking a shell.
343 - Misc. other stuff.
345 Revision 1.31 2002/09/20 16:38:45 cvs
347 - Cleaned up export and addkey. Fixed(?) addkey clobbering trustdb
349 problem (thanks to jrray\x40spacemeat.com for the patch). Added
350 support for signature verification on addkey pretend.
351 - No calls to POSIX::tmpnam remain (thanks to radek\x40karnet.pl and
353 jrray\x40spacemeat.com for suggesting File::Temp).
354 Revision 1.30 2002/09/20 15:25:47 cvs
356 - Fixed up tempfile handling and eliminated calls to the shell in
358 encrypt(), sign() and msginfo(). Passing all currently defined
359 tests.
360 - Hopefully also fixed signing during encryption and verification of
362 detached signatures. Not tested this yet.
363 Revision 1.29 2002/09/20 11:19:02 cvs
365 - Removed hack to Version: string. Only the Comment: string in GPG
367 output is now modified by Crypt::GPG. (Thanks to
368 eisen\x40schlund.de for pointing out the bug here)
369 - Removed code that incorrectly replaced 'PGP MESSAGE' with 'PGP
371 SIGNATURE' on detached signatures. (Thanks to ddcc\x40mit.edu for
372 pointing this out).
373 - Fixed up addkey() to properly handle pretend mode and to
375 selectively import only requested key IDs from a key block.
376 - parsekeys() now also figures out which keyring a key belongs to.
378 - Added certify() method, to enable certifying keys.
380 - Added Crypt::GPG::Signature methods - validity(), keyid(), time()
382 and trusted().
383
385 Crypt::GPG is Copyright (c) 2000-2007 Ashish Gulhati <crypt-gpg at
386 neomailbox.com>. All Rights Reserved.
387
389 Thanks to Barkha, for inspiration; to the GnuPG team; and to everyone
390 who writes free software.
391
393 This code is free software; you can redistribute it and/or modify it
394 under the same terms as Perl itself.
395
397 Are very welcome. Email crypt-gpg at neomailbox.com.
398perl v5.12.0 2010-04-30 GPG(3)