1NAME
2 GnuPG::Interface - Perl interface to GnuPG
3
4SYNOPSIS
5 # A simple example
6 use IO::Handle;
7 use GnuPG::Interface;
8
9 # setting up the situation
10 my $gnupg = GnuPG::Interface->new();
11 $gnupg->options->hash_init( armor => 1,
12 homedir => '/home/foobar' );
13
14 # Note you can set the recipients even if you aren't encrypting!
15 $gnupg->options->push_recipients( 'ftobin@cpan.org' );
16 $gnupg->options->meta_interactive( 0 );
17
18 # how we create some handles to interact with GnuPG
19 my $input = IO::Handle->new();
20 my $output = IO::Handle->new();
21 my $handles = GnuPG::Handles->new( stdin => $input,
22 stdout => $output );
23
24 # Now we'll go about encrypting with the options already set
25 my @plaintext = ( 'foobar' );
26 my $pid = $gnupg->encrypt( handles => $handles );
27
28 # Now we write to the input of GnuPG
29 print $input @plaintext;
30 close $input;
31
32 # now we read the output
33 my @ciphertext = <$output>;
34 close $output;
35
36 waitpid $pid, 0;
37
38DESCRIPTION
39 GnuPG::Interface and its associated modules are designed to provide an
40 object-oriented method for interacting with GnuPG, being able to perform
41 functions such as but not limited to encrypting, signing, decryption,
42 verification, and key-listing parsing.
43
44 How Data Member Accessor Methods are Created
45 Each module in the GnuPG::Interface bundle relies on Moo to generate the
46 get/set methods used to set the object's data members. *This is very
47 important to realize.* This means that any data member which is a list
48 has special methods assigned to it for pushing, popping, and clearing
49 the list.
50
51 Understanding Bidirectional Communication
52 It is also imperative to realize that this package uses interprocess
53 communication methods similar to those used in IPC::Open3 and
54 "Bidirectional Communication with Another Process" in perlipc, and that
55 users of this package need to understand how to use this method because
56 this package does not abstract these methods for the user greatly. This
57 package is not designed to abstract this away entirely (partly for
58 security purposes), but rather to simply help create 'proper', clean
59 calls to GnuPG, and to implement key-listing parsing. Please see
60 "Bidirectional Communication with Another Process" in perlipc to learn
61 how to deal with these methods.
62
63 Using this package to do message processing generally invovlves creating
64 a GnuPG::Interface object, creating a GnuPG::Handles object, setting
65 some options in its options data member, and then calling a method which
66 invokes GnuPG, such as clearsign. One then interacts with with the
67 handles appropriately, as described in "Bidirectional Communication with
68 Another Process" in perlipc.
69
70GnuPG Versions
71 As of this version of GnuPG::Interface, there are two supported versions
72 of GnuPG: 1.4.x and 2.2.x. The GnuPG download page
73 <https://gnupg.org/download/index.html> has updated information on the
74 currently supported versions.
75
76 GnuPG released 2.0 and 2.1 versions in the past and some packaging
77 systems may still provide these if you install the default "gpg",
78 "gnupg", "gnupg2", etc. packages. This modules supports only version
79 2.2.x, so you may need to find additional package repositories or build
80 from source to get the updated version.
81
82OBJECT METHODS
83 Initialization Methods
84 new( *%initialization_args* )
85 This methods creates a new object. The optional arguments are
86 initialization of data members.
87
88 hash_init( *%args* ).
89
90 Object Methods which use a GnuPG::Handles Object
91 list_public_keys( % )
92 list_sigs( % )
93 list_secret_keys( % )
94 encrypt( % )
95 encrypt_symmetrically( % )
96 sign( % )
97 clearsign( % )
98 detach_sign( % )
99 sign_and_encrypt( % )
100 decrypt( % )
101 verify( % )
102 import_keys( % )
103 export_keys( % )
104 recv_keys( % )
105 send_keys( % )
106 search_keys( % )
107 These methods each correspond directly to or are very similar to a
108 GnuPG command described in gpg. Each of these methods takes a hash,
109 which currently must contain a key of handles which has the value of
110 a GnuPG::Handles object. Another optional key is command_args which
111 should have the value of an array reference; these arguments will be
112 passed to GnuPG as command arguments. These command arguments are
113 used for such things as determining the keys to list in the
114 export_keys method. *Please note that GnuPG command arguments are
115 not the same as GnuPG options*. To understand what are options and
116 what are command arguments please read "COMMANDS" in gpg and
117 "OPTIONS" in gpg.
118
119 Each of these calls returns the PID for the resulting GnuPG process.
120 One can use this PID in a "waitpid" call instead of a "wait" call if
121 more precise process reaping is needed.
122
123 These methods will attach the handles specified in the handles
124 object to the running GnuPG object, so that bidirectional
125 communication can be established. That is, the optionally-defined
126 stdin, stdout, stderr, status, logger, and passphrase handles will
127 be attached to GnuPG's input, output, standard error, the handle
128 created by setting status-fd, the handle created by setting
129 logger-fd, and the handle created by setting passphrase-fd
130 respectively. This tying of handles of similar to the process done
131 in *IPC::Open3*.
132
133 If you want the GnuPG process to read or write directly to an
134 already-opened filehandle, you cannot do this via the normal
135 *IPC::Open3* mechanisms. In order to accomplish this, set the
136 appropriate handles data member to the already-opened filehandle,
137 and then set the option direct to be true for that handle, as
138 described in "options" in GnuPG::Handles. For example, to have GnuPG
139 read from the file input.txt and write to output.txt, the following
140 snippet may do:
141
142 my $infile = IO::File->new( 'input.txt' );
143 my $outfile = IO::File->new( '>output.txt' );
144 my $handles = GnuPG::Handles->new( stdin => $infile,
145 stdout => $outfile,
146 );
147 $handles->options( 'stdin' )->{direct} = 1;
148 $handles->options( 'stdout' )->{direct} = 1;
149
150 If any handle in the handles object is not defined, GnuPG's input,
151 output, and standard error will be tied to the running program's
152 standard error, standard output, or standard error. If the status or
153 logger handle is not defined, this channel of communication is never
154 established with GnuPG, and so this information is not generated and
155 does not come into play.
156
157 If the passphrase data member handle of the handles object is not
158 defined, but the the passphrase data member handle of
159 GnuPG::Interface object is, GnuPG::Interface will handle passing
160 this information into GnuPG for the user as a convenience. Note that
161 this will result in GnuPG::Interface storing the passphrase in
162 memory, instead of having it simply 'pass-through' to GnuPG via a
163 handle.
164
165 If neither the passphrase data member of the GnuPG::Interface nor
166 the passphrase data member of the handles object is defined, then
167 GnuPG::Interface assumes that access and control over the secret key
168 will be handled by the running gpg-agent process. This represents
169 the simplest mode of operation with the GnuPG "stable" suite
170 (version 2.2 and later). It is also the preferred mode for tools
171 intended to be user-facing, since the user will be prompted directly
172 by gpg-agent for use of the secret key material. Note that for
173 programmatic use, this mode requires the gpg-agent and pinentry to
174 already be correctly configured.
175
176 Other Methods
177 get_public_keys( @search_strings )
178 get_secret_keys( @search_strings )
179 get_public_keys_with_sigs( @search_strings )
180 These methods create and return objects of the type GnuPG::PublicKey
181 or GnuPG::SecretKey respectively. This is done by parsing the output
182 of GnuPG with the option with-colons enabled. The objects created do
183 or do not have signature information stored in them, depending if
184 the method ends in *_sigs*; this separation of functionality is
185 there because of performance hits when listing information with
186 signatures.
187
188 test_default_key_passphrase()
189 This method will return a true or false value, depending on whether
190 GnuPG reports a good passphrase was entered while signing a short
191 message using the values of the passphrase data member, and the
192 default key specified in the options data member.
193
194 version()
195 Returns the version of GnuPG that GnuPG::Interface is running.
196
197Invoking GnuPG with a custom call
198 GnuPG::Interface attempts to cover a lot of the commands of GnuPG that
199 one would want to perform; however, there may be a lot more calls that
200 GnuPG is and will be capable of, so a generic command interface is
201 provided, "wrap_call".
202
203 wrap_call( %args )
204 Call GnuPG with a custom command. The %args hash must contain at
205 least the following keys:
206
207 commands
208 The value of this key in the hash must be a reference to a a
209 list of commands for GnuPG, such as "[ qw( --encrypt --sign )
210 ]".
211
212 handles
213 As with most other GnuPG::Interface methods, handles must be a
214 GnuPG::Handles object.
215
216 The following keys are optional.
217
218 command_args
219 As with other GnuPG::Interface methods, the value in hash for
220 this key must be a reference to a list of arguments to be passed
221 to the GnuPG command, such as which keys to list in a
222 key-listing.
223
224OBJECT DATA MEMBERS
225 call
226 This defines the call made to invoke GnuPG. Defaults to 'gpg'; this
227 should be changed if 'gpg' is not in your path, or there is a
228 different name for the binary on your system.
229
230 passphrase
231 In order to lessen the burden of using handles by the user of this
232 package, setting this option to one's passphrase for a secret key
233 will allow the package to enter the passphrase via a handle to GnuPG
234 by itself instead of leaving this to the user. See also "passphrase"
235 in GnuPG::Handles.
236
237 options
238 This data member, of the type GnuPG::Options; the setting stored in
239 this data member are used to determine the options used when calling
240 GnuPG via *any* of the object methods described in this package. See
241 GnuPG::Options for more information.
242
243EXAMPLES
244 The following setup can be done before any of the following examples:
245
246 use IO::Handle;
247 use GnuPG::Interface;
248
249 my @original_plaintext = ( "How do you doo?" );
250 my $passphrase = "Three Little Pigs";
251
252 my $gnupg = GnuPG::Interface->new();
253
254 $gnupg->options->hash_init( armor => 1,
255 recipients => [ 'ftobin@uiuc.edu',
256 '0xABCD1234ABCD1234ABCD1234ABCD1234ABCD1234' ],
257 meta_interactive => 0 ,
258 );
259
260 $gnupg->options->debug_level(4);
261
262 $gnupg->options->logger_file("/tmp/gnupg-$$-decrypt-".time().".log");
263
264 Encrypting
265 # We'll let the standard error of GnuPG pass through
266 # to our own standard error, by not creating
267 # a stderr-part of the $handles object.
268 my ( $input, $output ) = ( IO::Handle->new(),
269 IO::Handle->new() );
270
271 my $handles = GnuPG::Handles->new( stdin => $input,
272 stdout => $output );
273
274 # this sets up the communication
275 # Note that the recipients were specified earlier
276 # in the 'options' data member of the $gnupg object.
277 my $pid = $gnupg->encrypt( handles => $handles );
278
279 # this passes in the plaintext
280 print $input @original_plaintext;
281
282 # this closes the communication channel,
283 # indicating we are done
284 close $input;
285
286 my @ciphertext = <$output>; # reading the output
287
288 waitpid $pid, 0; # clean up the finished GnuPG process
289
290 Signing
291 # This time we'll catch the standard error for our perusing
292 my ( $input, $output, $error ) = ( IO::Handle->new(),
293 IO::Handle->new(),
294 IO::Handle->new(),
295 );
296
297 my $handles = GnuPG::Handles->new( stdin => $input,
298 stdout => $output,
299 stderr => $error,
300 );
301
302 # indicate our pasphrase through the
303 # convenience method
304 $gnupg->passphrase( $passphrase );
305
306 # this sets up the communication
307 my $pid = $gnupg->sign( handles => $handles );
308
309 # this passes in the plaintext
310 print $input @original_plaintext;
311
312 # this closes the communication channel,
313 # indicating we are done
314 close $input;
315
316 my @ciphertext = <$output>; # reading the output
317 my @error_output = <$error>; # reading the error
318
319 close $output;
320 close $error;
321
322 waitpid $pid, 0; # clean up the finished GnuPG process
323
324 Decryption
325 # This time we'll catch the standard error for our perusing
326 # as well as passing in the passphrase manually
327 # as well as the status information given by GnuPG
328 my ( $input, $output, $error, $passphrase_fh, $status_fh )
329 = ( IO::Handle->new(),
330 IO::Handle->new(),
331 IO::Handle->new(),
332 IO::Handle->new(),
333 IO::Handle->new(),
334 );
335
336 my $handles = GnuPG::Handles->new( stdin => $input,
337 stdout => $output,
338 stderr => $error,
339 passphrase => $passphrase_fh,
340 status => $status_fh,
341 );
342
343 # this time we'll also demonstrate decrypting
344 # a file written to disk
345 # Make sure you "use IO::File" if you use this module!
346 my $cipher_file = IO::File->new( 'encrypted.gpg' );
347
348 # this sets up the communication
349 my $pid = $gnupg->decrypt( handles => $handles );
350
351 # This passes in the passphrase
352 print $passphrase_fh $passphrase;
353 close $passphrase_fh;
354
355 # this passes in the plaintext
356 print $input $_ while <$cipher_file>;
357
358 # this closes the communication channel,
359 # indicating we are done
360 close $input;
361 close $cipher_file;
362
363 my @plaintext = <$output>; # reading the output
364 my @error_output = <$error>; # reading the error
365 my @status_info = <$status_fh>; # read the status info
366
367 # clean up...
368 close $output;
369 close $error;
370 close $status_fh;
371
372 waitpid $pid, 0; # clean up the finished GnuPG process
373
374 Printing Keys
375 # This time we'll just let GnuPG print to our own output
376 # and read from our input, because no input is needed!
377 my $handles = GnuPG::Handles->new();
378
379 my @ids = ( 'ftobin', '0xABCD1234ABCD1234ABCD1234ABCD1234ABCD1234' );
380
381 # this time we need to specify something for
382 # command_args because --list-public-keys takes
383 # search ids as arguments
384 my $pid = $gnupg->list_public_keys( handles => $handles,
385 command_args => [ @ids ] );
386
387 waitpid $pid, 0;
388
389 Creating GnuPG::PublicKey Objects
390 my @ids = [ 'ftobin', '0xABCD1234ABCD1234ABCD1234ABCD1234ABCD1234' ];
391
392 my @keys = $gnupg->get_public_keys( @ids );
393
394 # no wait is required this time; it's handled internally
395 # since the entire call is encapsulated
396
397 Custom GnuPG call
398 # assuming $handles is a GnuPG::Handles object
399 my $pid = $gnupg->wrap_call
400 ( commands => [ qw( --list-packets ) ],
401 command_args => [ qw( test/key.1.asc ) ],
402 handles => $handles,
403 );
404
405 my @out = <$handles->stdout()>;
406 waitpid $pid, 0;
407
408FAQ
409 How do I get GnuPG::Interface to read/write directly from a filehandle?
410 You need to set GnuPG::Handles direct option to be true for the
411 filehandles in concern. See "options" in GnuPG::Handles and "Object
412 Methods which use a GnuPG::Handles Object" for more information.
413
414 Why do you make it so difficult to get GnuPG to write/read from a
415 filehandle? In the shell, I can just call GnuPG with the --outfile
416 option!
417 There are lots of issues when trying to tell GnuPG to read/write
418 directly from a file, such as if the file isn't there, or there is a
419 file, and you want to write over it! What do you want to happen
420 then? Having the user of this module handle these questions
421 beforehand by opening up filehandles to GnuPG lets the user know
422 fully what is going to happen in these circumstances, and makes the
423 module less error-prone.
424
425 When having GnuPG process a large message, sometimes it just hanges
426 there.
427 Your problem may be due to buffering issues; when GnuPG reads/writes
428 to non-direct filehandles (those that are sent to filehandles which
429 you read to from into memory, not that those access the disk),
430 buffering issues can mess things up. I recommend looking into
431 "options" in GnuPG::Handles.
432
433NOTES
434 This package is the successor to PGP::GPG::MessageProcessor, which I
435 found to be too inextensible to carry on further. A total redesign was
436 needed, and this is the resulting work.
437
438 After any call to a GnuPG-command method of GnuPG::Interface in which
439 one passes in the handles, one should all wait to clean up GnuPG from
440 the process table.
441
442BUGS
443 Large Amounts of Data
444 Currently there are problems when transmitting large quantities of
445 information over handles; I'm guessing this is due to buffering issues.
446 This bug does not seem specific to this package; IPC::Open3 also appears
447 affected.
448
449 OpenPGP v3 Keys
450 I don't know yet how well this module handles parsing OpenPGP v3 keys.
451
452 RHEL 7 Test Failures
453 Testing with the updates for version 1.00 we saw intermittent test
454 failures on RHEL 7 with GnuPG version 2.2.20. In some cases the tests
455 would all pass for several runs, then one would fail. We're unable to
456 reliably reproduce this so we would be interested in feedback from other
457 users.
458
459SEE ALSO
460 GnuPG::Options, GnuPG::Handles, GnuPG::PublicKey, GnuPG::SecretKey, gpg,
461 "Bidirectional Communication with Another Process" in perlipc
462
463LICENSE
464 This module is free software; you can redistribute it and/or modify it
465 under the same terms as Perl itself.
466
467AUTHOR
468 GnuPG::Interface is currently maintained by Best Practical Solutions
469 <BPS@cpan.org>.
470
471 Frank J. Tobin, ftobin@cpan.org was the original author of the package.
472
473