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 # setting 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.
147 If the passphrase data member handle of the handles object is not
149 defined, but the the passphrase data member handle of
150 GnuPG::Interface object is, GnuPG::Interface will handle passing
151 this information into GnuPG for the user as a convenience. Note
152 that this will result in GnuPG::Interface storing the passphrase in
153 memory, instead of having it simply 'pass-through' to GnuPG via a
154 handle.
155 If neither the passphrase data member of the GnuPG::Interface nor
157 the passphrase data member of the handles object is defined, then
158 GnuPG::Interface assumes that access and control over the secret
159 key will be handled by the running gpg-agent process. This
160 represents the simplest mode of operation with the GnuPG "modern"
161 suite (version 2.1 and later). It is also the preferred mode for
162 tools intended to be user-facing, since the user will be prompted
163 directly by gpg-agent for use of the secret key material. Note
164 that for programmatic use, this mode requires the gpg-agent and
165 pinentry to already be correctly configured.
166 Other Methods
168 get_public_keys( @search_strings )
169 get_secret_keys( @search_strings )
170 get_public_keys_with_sigs( @search_strings )
171 These methods create and return objects of the type
172 GnuPG::PublicKey or GnuPG::SecretKey respectively. This is done by
173 parsing the output of GnuPG with the option with-colons enabled.
174 The objects created do or do not have signature information stored
175 in them, depending if the method ends in _sigs; this separation of
176 functionality is there because of performance hits when listing
177 information with signatures.
178 test_default_key_passphrase()
180 This method will return a true or false value, depending on whether
181 GnuPG reports a good passphrase was entered while signing a short
182 message using the values of the passphrase data member, and the
183 default key specified in the options data member.
184 version()
186 Returns the version of GnuPG that GnuPG::Interface is running.
187
189 GnuPG::Interface attempts to cover a lot of the commands of GnuPG that
190 one would want to perform; however, there may be a lot more calls that
191 GnuPG is and will be capable of, so a generic command interface is
192 provided, "wrap_call".
193 wrap_call( %args )
195 Call GnuPG with a custom command. The %args hash must contain at
196 least the following keys:
197 commands
199 The value of this key in the hash must be a reference to a a
200 list of commands for GnuPG, such as "[ qw( --encrypt --sign )
201 ]".
202 handles
204 As with most other GnuPG::Interface methods, handles must be a
205 GnuPG::Handles object.
206 The following keys are optional.
208 command_args
210 As with other GnuPG::Interface methods, the value in hash for
211 this key must be a reference to a list of arguments to be
212 passed to the GnuPG command, such as which keys to list in a
213 key-listing.
214
216 call
217 This defines the call made to invoke GnuPG. Defaults to 'gpg';
218 this should be changed if 'gpg' is not in your path, or there is a
219 different name for the binary on your system.
220 passphrase
222 In order to lessen the burden of using handles by the user of this
223 package, setting this option to one's passphrase for a secret key
224 will allow the package to enter the passphrase via a handle to
225 GnuPG by itself instead of leaving this to the user. See also
226 "passphrase" in GnuPG::Handles.
227 options
229 This data member, of the type GnuPG::Options; the setting stored in
230 this data member are used to determine the options used when
231 calling GnuPG via any of the object methods described in this
232 package. See GnuPG::Options for more information.
233
235 The following setup can be done before any of the following examples:
236 use IO::Handle;
238 use GnuPG::Interface;
239 my @original_plaintext = ( "How do you doo?" );
241 my $passphrase = "Three Little Pigs";
242 my $gnupg = GnuPG::Interface->new();
244 $gnupg->options->hash_init( armor => 1,
246 recipients => [ 'ftobin@uiuc.edu',
247 '0xABCD1234ABCD1234ABCD1234ABCD1234ABCD1234' ],
248 meta_interactive => 0 ,
249 );
250 Encrypting
252 # We'll let the standard error of GnuPG pass through
253 # to our own standard error, by not creating
254 # a stderr-part of the $handles object.
255 my ( $input, $output ) = ( IO::Handle->new(),
256 IO::Handle->new() );
257 my $handles = GnuPG::Handles->new( stdin => $input,
259 stdout => $output );
260 # this sets up the communication
262 # Note that the recipients were specified earlier
263 # in the 'options' data member of the $gnupg object.
264 my $pid = $gnupg->encrypt( handles => $handles );
265 # this passes in the plaintext
267 print $input @original_plaintext;
268 # this closes the communication channel,
270 # indicating we are done
271 close $input;
272 my @ciphertext = <$output>; # reading the output
274 waitpid $pid, 0; # clean up the finished GnuPG process
276 Signing
278 # This time we'll catch the standard error for our perusing
279 my ( $input, $output, $error ) = ( IO::Handle->new(),
280 IO::Handle->new(),
281 IO::Handle->new(),
282 );
283 my $handles = GnuPG::Handles->new( stdin => $input,
285 stdout => $output,
286 stderr => $error,
287 );
288 # indicate our pasphrase through the
290 # convenience method
291 $gnupg->passphrase( $passphrase );
292 # this sets up the communication
294 my $pid = $gnupg->sign( handles => $handles );
295 # this passes in the plaintext
297 print $input @original_plaintext;
298 # this closes the communication channel,
300 # indicating we are done
301 close $input;
302 my @ciphertext = <$output>; # reading the output
304 my @error_output = <$error>; # reading the error
305 close $output;
307 close $error;
308 waitpid $pid, 0; # clean up the finished GnuPG process
310 Decryption
312 # This time we'll catch the standard error for our perusing
313 # as well as passing in the passphrase manually
314 # as well as the status information given by GnuPG
315 my ( $input, $output, $error, $passphrase_fh, $status_fh )
316 = ( IO::Handle->new(),
317 IO::Handle->new(),
318 IO::Handle->new(),
319 IO::Handle->new(),
320 IO::Handle->new(),
321 );
322 my $handles = GnuPG::Handles->new( stdin => $input,
324 stdout => $output,
325 stderr => $error,
326 passphrase => $passphrase_fh,
327 status => $status_fh,
328 );
329 # this time we'll also demonstrate decrypting
331 # a file written to disk
332 # Make sure you "use IO::File" if you use this module!
333 my $cipher_file = IO::File->new( 'encrypted.gpg' );
334 # this sets up the communication
336 my $pid = $gnupg->decrypt( handles => $handles );
337 # This passes in the passphrase
339 print $passphrase_fh $passphrase;
340 close $passphrase_fh;
341 # this passes in the plaintext
343 print $input $_ while <$cipher_file>;
344 # this closes the communication channel,
346 # indicating we are done
347 close $input;
348 close $cipher_file;
349 my @plaintext = <$output>; # reading the output
351 my @error_output = <$error>; # reading the error
352 my @status_info = <$status_fh>; # read the status info
353 # clean up...
355 close $output;
356 close $error;
357 close $status_fh;
358 waitpid $pid, 0; # clean up the finished GnuPG process
360 Printing Keys
362 # This time we'll just let GnuPG print to our own output
363 # and read from our input, because no input is needed!
364 my $handles = GnuPG::Handles->new();
365 my @ids = ( 'ftobin', '0xABCD1234ABCD1234ABCD1234ABCD1234ABCD1234' );
367 # this time we need to specify something for
369 # command_args because --list-public-keys takes
370 # search ids as arguments
371 my $pid = $gnupg->list_public_keys( handles => $handles,
372 command_args => [ @ids ] );
373 waitpid $pid, 0;
375 Creating GnuPG::PublicKey Objects
377 my @ids = [ 'ftobin', '0xABCD1234ABCD1234ABCD1234ABCD1234ABCD1234' ];
378 my @keys = $gnupg->get_public_keys( @ids );
380 # no wait is required this time; it's handled internally
382 # since the entire call is encapsulated
383 Custom GnuPG call
385 # assuming $handles is a GnuPG::Handles object
386 my $pid = $gnupg->wrap_call
387 ( commands => [ qw( --list-packets ) ],
388 command_args => [ qw( test/key.1.asc ) ],
389 handles => $handles,
390 );
391 my @out = <$handles->stdout()>;
393 waitpid $pid, 0;
394
396 How do I get GnuPG::Interface to read/write directly from a filehandle?
397 You need to set GnuPG::Handles direct option to be true for the
398 filehandles in concern. See "options" in GnuPG::Handles and
399 "Object Methods which use a GnuPG::Handles Object" for more
400 information.
401 Why do you make it so difficult to get GnuPG to write/read from a
403 filehandle? In the shell, I can just call GnuPG with the --outfile
404 option!
405 There are lots of issues when trying to tell GnuPG to read/write
406 directly from a file, such as if the file isn't there, or there is
407 a file, and you want to write over it! What do you want to happen
408 then? Having the user of this module handle these questions
409 beforehand by opening up filehandles to GnuPG lets the user know
410 fully what is going to happen in these circumstances, and makes the
411 module less error-prone.
412 When having GnuPG process a large message, sometimes it just hanges
414 there.
415 Your problem may be due to buffering issues; when GnuPG
416 reads/writes to non-direct filehandles (those that are sent to
417 filehandles which you read to from into memory, not that those
418 access the disk), buffering issues can mess things up. I recommend
419 looking into "options" in GnuPG::Handles.
420
422 This package is the successor to PGP::GPG::MessageProcessor, which I
423 found to be too inextensible to carry on further. A total redesign was
424 needed, and this is the resulting work.
425 After any call to a GnuPG-command method of GnuPG::Interface in which
427 one passes in the handles, one should all wait to clean up GnuPG from
428 the process table.
429
431 Currently there are problems when transmitting large quantities of
432 information over handles; I'm guessing this is due to buffering issues.
433 This bug does not seem specific to this package; IPC::Open3 also
434 appears affected.
435 I don't know yet how well this modules handles parsing OpenPGP v3 keys.
437
439 GnuPG::Options, GnuPG::Handles, GnuPG::PublicKey, GnuPG::SecretKey,
440 gpg, "Bidirectional Communication with Another Process" in perlipc
441
443 This module is free software; you can redistribute it and/or modify it
444 under the same terms as Perl itself.
445
447 GnuPG::Interface is currently maintained by Jesse Vincent
448 <jesse@cpan.org>.
449 Frank J. Tobin, ftobin@cpan.org was the original author of the package.
451perl v5.30.1 2020-01-30 GnuPG::Interface(3)