1GnuPG::Interface(3) User Contributed Perl Documentation GnuPG::Interface(3)
2
6 GnuPG::Interface - Perl interface to GnuPG
7
9 # A simple example
10 use IO::Handle;
11 use GnuPG::Interface;
12 # settting up the situation
14 my $gnupg = GnuPG::Interface->new();
15 $gnupg->options->hash_init( armor => 1,
16 homedir => '/home/foobar' );
17 # Note you can set the recipients even if you aren't encrypting!
19 $gnupg->options->push_recipients( 'ftobin@cpan.org' );
20 $gnupg->options->meta_interactive( 0 );
21 # how we create some handles to interact with GnuPG
23 my $input = IO::Handle->new();
24 my $output = IO::Handle->new();
25 my $handles = GnuPG::Handles->new( stdin => $input,
26 stdout => $output );
27 # Now we'll go about encrypting with the options already set
29 my @plaintext = ( 'foobar' );
30 my $pid = $gnupg->encrypt( handles => $handles );
31 # Now we write to the input of GnuPG
33 print $input @plaintext;
34 close $input;
35 # now we read the output
37 my @ciphertext = <$output>;
38 close $output;
39 waitpid $pid, 0;
41
43 GnuPG::Interface and its associated modules are designed to provide an
44 object-oriented method for interacting with GnuPG, being able to
45 perform functions such as but not limited to encrypting, signing,
46 decryption, verification, and key-listing parsing.
47 How Data Member Accessor Methods are Created
49 Each module in the GnuPG::Interface bundle relies on Moo to generate
50 the get/set methods used to set the object's data members. This is
51 very important to realize. This means that any data member which is a
52 list has special methods assigned to it for pushing, popping, and
53 clearing the list.
54 Understanding Bidirectional Communication
56 It is also imperative to realize that this package uses interprocess
57 communication methods similar to those used in IPC::Open3 and
58 "Bidirectional Communication with Another Process" in perlipc, and that
59 users of this package need to understand how to use this method because
60 this package does not abstract these methods for the user greatly.
61 This package is not designed to abstract this away entirely (partly for
62 security purposes), but rather to simply help create 'proper', clean
63 calls to GnuPG, and to implement key-listing parsing. Please see
64 "Bidirectional Communication with Another Process" in perlipc to learn
65 how to deal with these methods.
66 Using this package to do message processing generally invovlves
68 creating a GnuPG::Interface object, creating a GnuPG::Handles object,
69 setting some options in its options data member, and then calling a
70 method which invokes GnuPG, such as clearsign. One then interacts with
71 with the handles appropriately, as described in "Bidirectional
72 Communication with Another Process" in perlipc.
73
75 Initialization Methods
76 new( %initialization_args )
77 This methods creates a new object. The optional arguments are
78 initialization of data members.
79 hash_init( %args ).
81 Object Methods which use a GnuPG::Handles Object
83 list_public_keys( % )
84 list_sigs( % )
85 list_secret_keys( % )
86 encrypt( % )
87 encrypt_symmetrically( % )
88 sign( % )
89 clearsign( % )
90 detach_sign( % )
91 sign_and_encrypt( % )
92 decrypt( % )
93 verify( % )
94 import_keys( % )
95 export_keys( % )
96 recv_keys( % )
97 send_keys( % )
98 search_keys( % )
99 These methods each correspond directly to or are very similar to a
100 GnuPG command described in gpg. Each of these methods takes a
101 hash, which currently must contain a key of handles which has the
102 value of a GnuPG::Handles object. Another optional key is
103 command_args which should have the value of an array reference;
104 these arguments will be passed to GnuPG as command arguments.
105 These command arguments are used for such things as determining the
106 keys to list in the export_keys method. Please note that GnuPG
107 command arguments are not the same as GnuPG options. To understand
108 what are options and what are command arguments please read
109 "COMMANDS" in gpg and "OPTIONS" in gpg.
110 Each of these calls returns the PID for the resulting GnuPG
112 process. One can use this PID in a "waitpid" call instead of a
113 "wait" call if more precise process reaping is needed.
114 These methods will attach the handles specified in the handles
116 object to the running GnuPG object, so that bidirectional
117 communication can be established. That is, the optionally-defined
118 stdin, stdout, stderr, status, logger, and passphrase handles will
119 be attached to GnuPG's input, output, standard error, the handle
120 created by setting status-fd, the handle created by setting logger-
121 fd, and the handle created by setting passphrase-fd respectively.
122 This tying of handles of similar to the process done in IPC::Open3.
123 If you want the GnuPG process to read or write directly to an
125 already-opened filehandle, you cannot do this via the normal
126 IPC::Open3 mechanisms. In order to accomplish this, set the
127 appropriate handles data member to the already-opened filehandle,
128 and then set the option direct to be true for that handle, as
129 described in "options" in GnuPG::Handles. For example, to have
130 GnuPG read from the file input.txt and write to output.txt, the
131 following snippet may do:
132 my $infile = IO::File->new( 'input.txt' );
134 my $outfile = IO::File->new( '>output.txt' );
135 my $handles = GnuPG::Handles->new( stdin => $infile,
136 stdout => $outfile,
137 );
138 $handles->options( 'stdin' )->{direct} = 1;
139 $handles->options( 'stdout' )->{direct} = 1;
140 If any handle in the handles object is not defined, GnuPG's input,
142 output, and standard error will be tied to the running program's
143 standard error, standard output, or standard error. If the status
144 or logger handle is not defined, this channel of communication is
145 never established with GnuPG, and so this information is not
146 generated and does not come into play. If the passphrase data
147 member handle of the handles object is not defined, but the the
148 passphrase data member handle of GnuPG::Interface object is,
149 GnuPG::Interface will handle passing this information into GnuPG
150 for the user as a convience. Note that this will result in
151 GnuPG::Interface storing the passphrase in memory, instead of
152 having it simply 'pass-through' to GnuPG via a handle.
153 Other Methods
155 get_public_keys( @search_strings )
156 get_secret_keys( @search_strings )
157 get_public_keys_with_sigs( @search_strings )
158 These methods create and return objects of the type
159 GnuPG::PublicKey or GnuPG::SecretKey respectively. This is done by
160 parsing the output of GnuPG with the option with-colons enabled.
161 The objects created do or do not have signature information stored
162 in them, depending if the method ends in _sigs; this separation of
163 functionality is there because of performance hits when listing
164 information with signatures.
165 test_default_key_passphrase()
167 This method will return a true or false value, depending on whether
168 GnuPG reports a good passphrase was entered while signing a short
169 message using the values of the passphrase data member, and the
170 default key specified in the options data member.
171 version()
173 Returns the version of GnuPG that GnuPG::Interface is running.
174
176 GnuPG::Interface attempts to cover a lot of the commands of GnuPG that
177 one would want to perform; however, there may be a lot more calls that
178 GnuPG is and will be capable of, so a generic command interface is
179 provided, "wrap_call".
180 wrap_call( %args )
182 Call GnuPG with a custom command. The %args hash must contain at
183 least the following keys:
184 commands
186 The value of this key in the hash must be a reference to a a
187 list of commands for GnuPG, such as "[ qw( --encrypt --sign )
188 ]".
189 handles
191 As with most other GnuPG::Interface methods, handles must be a
192 GnuPG::Handles object.
193 The following keys are optional.
195 command_args
197 As with other GnuPG::Interface methods, the value in hash for
198 this key must be a reference to a list of arguments to be
199 passed to the GnuPG command, such as which keys to list in a
200 key-listing.
201
203 call
204 This defines the call made to invoke GnuPG. Defaults to 'gpg';
205 this should be changed if 'gpg' is not in your path, or there is a
206 different name for the binary on your system.
207 passphrase
209 In order to lessen the burden of using handles by the user of this
210 package, setting this option to one's passphrase for a secret key
211 will allow the package to enter the passphrase via a handle to
212 GnuPG by itself instead of leaving this to the user. See also
213 "passphrase" in GnuPG::Handles.
214 options
216 This data member, of the type GnuPG::Options; the setting stored in
217 this data member are used to determine the options used when
218 calling GnuPG via any of the object methods described in this
219 package. See GnuPG::Options for more information.
220
222 The following setup can be done before any of the following examples:
223 use IO::Handle;
225 use GnuPG::Interface;
226 my @original_plaintext = ( "How do you doo?" );
228 my $passphrase = "Three Little Pigs";
229 my $gnupg = GnuPG::Interface->new();
231 $gnupg->options->hash_init( armor => 1,
233 recipients => [ 'ftobin@uiuc.edu',
234 '0xABCD1234' ],
235 meta_interactive => 0 ,
236 );
237 Encrypting
239 # We'll let the standard error of GnuPG pass through
240 # to our own standard error, by not creating
241 # a stderr-part of the $handles object.
242 my ( $input, $output ) = ( IO::Handle->new(),
243 IO::Handle->new() );
244 my $handles = GnuPG::Handles->new( stdin => $input,
246 stdout => $output );
247 # this sets up the communication
249 # Note that the recipients were specified earlier
250 # in the 'options' data member of the $gnupg object.
251 my $pid = $gnupg->encrypt( handles => $handles );
252 # this passes in the plaintext
254 print $input @original_plaintext;
255 # this closes the communication channel,
257 # indicating we are done
258 close $input;
259 my @ciphertext = <$output>; # reading the output
261 waitpid $pid, 0; # clean up the finished GnuPG process
263 Signing
265 # This time we'll catch the standard error for our perusing
266 my ( $input, $output, $error ) = ( IO::Handle->new(),
267 IO::Handle->new(),
268 IO::Handle->new(),
269 );
270 my $handles = GnuPG::Handles->new( stdin => $input,
272 stdout => $output,
273 stderr => $error,
274 );
275 # indicate our pasphrase through the
277 # convience method
278 $gnupg->passphrase( $passphrase );
279 # this sets up the communication
281 my $pid = $gnupg->sign( handles => $handles );
282 # this passes in the plaintext
284 print $input @original_plaintext;
285 # this closes the communication channel,
287 # indicating we are done
288 close $input;
289 my @ciphertext = <$output>; # reading the output
291 my @error_output = <$error>; # reading the error
292 close $output;
294 close $error;
295 waitpid $pid, 0; # clean up the finished GnuPG process
297 Decryption
299 # This time we'll catch the standard error for our perusing
300 # as well as passing in the passphrase manually
301 # as well as the status information given by GnuPG
302 my ( $input, $output, $error, $passphrase_fh, $status_fh )
303 = ( IO::Handle->new(),
304 IO::Handle->new(),
305 IO::Handle->new(),
306 IO::Handle->new(),
307 IO::Handle->new(),
308 );
309 my $handles = GnuPG::Handles->new( stdin => $input,
311 stdout => $output,
312 stderr => $error,
313 passphrase => $passphrase_fh,
314 status => $status_fh,
315 );
316 # this time we'll also demonstrate decrypting
318 # a file written to disk
319 # Make sure you "use IO::File" if you use this module!
320 my $cipher_file = IO::File->new( 'encrypted.gpg' );
321 # this sets up the communication
323 my $pid = $gnupg->decrypt( handles => $handles );
324 # This passes in the passphrase
326 print $passphrase_fh $passphrase;
327 close $passphrase_fh;
328 # this passes in the plaintext
330 print $input $_ while <$cipher_file>;
331 # this closes the communication channel,
333 # indicating we are done
334 close $input;
335 close $cipher_file;
336 my @plaintext = <$output>; # reading the output
338 my @error_output = <$error>; # reading the error
339 my @status_info = <$status_fh>; # read the status info
340 # clean up...
342 close $output;
343 close $error;
344 close $status_fh;
345 waitpid $pid, 0; # clean up the finished GnuPG process
347 Printing Keys
349 # This time we'll just let GnuPG print to our own output
350 # and read from our input, because no input is needed!
351 my $handles = GnuPG::Handles->new();
352 my @ids = ( 'ftobin', '0xABCD1234' );
354 # this time we need to specify something for
356 # command_args because --list-public-keys takes
357 # search ids as arguments
358 my $pid = $gnupg->list_public_keys( handles => $handles,
359 command_args => [ @ids ] );
360 waitpid $pid, 0;
362 Creating GnuPG::PublicKey Objects
364 my @ids = [ 'ftobin', '0xABCD1234' ];
365 my @keys = $gnupg->get_public_keys( @ids );
367 # no wait is required this time; it's handled internally
369 # since the entire call is encapsulated
370 Custom GnuPG call
372 # assuming $handles is a GnuPG::Handles object
373 my $pid = $gnupg->wrap_call
374 ( commands => [ qw( --list-packets ) ],
375 command_args => [ qw( test/key.1.asc ) ],
376 handles => $handles,
377 );
378 my @out = <$handles->stdout()>;
380 waitpid $pid, 0;
381
383 How do I get GnuPG::Interface to read/write directly from a filehandle?
384 You need to set GnuPG::Handles direct option to be true for the
385 filehandles in concern. See "options" in GnuPG::Handles and
386 "Object Methods which use a GnuPG::Handles Object" for more
387 information.
388 Why do you make it so difficult to get GnuPG to write/read from a
390 filehandle? In the shell, I can just call GnuPG with the --outfile
391 option!
392 There are lots of issues when trying to tell GnuPG to read/write
393 directly from a file, such as if the file isn't there, or there is
394 a file, and you want to write over it! What do you want to happen
395 then? Having the user of this module handle these questions
396 beforehand by opening up filehandles to GnuPG lets the user know
397 fully what is going to happen in these circumstances, and makes the
398 module less error-prone.
399 When having GnuPG process a large message, sometimes it just hanges
401 there.
402 Your problem may be due to buffering issues; when GnuPG
403 reads/writes to non-direct filehandles (those that are sent to
404 filehandles which you read to from into memory, not that those
405 access the disk), buffering issues can mess things up. I recommend
406 looking into "options" in GnuPG::Handles.
407
409 This package is the successor to PGP::GPG::MessageProcessor, which I
410 found to be too inextensible to carry on further. A total redesign was
411 needed, and this is the resulting work.
412 After any call to a GnuPG-command method of GnuPG::Interface in which
414 one passes in the handles, one should all wait to clean up GnuPG from
415 the process table.
416
418 Currently there are problems when transmitting large quantities of
419 information over handles; I'm guessing this is due to buffering issues.
420 This bug does not seem specific to this package; IPC::Open3 also
421 appears affected.
422 I don't know yet how well this modules handles parsing OpenPGP v3 keys.
424
426 GnuPG::Options, GnuPG::Handles, GnuPG::PublicKey, GnuPG::SecretKey,
427 gpg, "Bidirectional Communication with Another Process" in perlipc
428
430 This module is free software; you can redistribute it and/or modify it
431 under the same terms as Perl itself.
432
434 GnuPg::Interface is currently maintained by Jesse Vincent
435 <jesse@cpan.org>.
436 Frank J. Tobin, ftobin@cpan.org was the original author of the package.
438perl v5.28.0 2015-02-17 GnuPG::Interface(3)