1GnuPG::Interface(3)   User Contributed Perl Documentation  GnuPG::Interface(3)
2
3
4

NAME

6       GnuPG::Interface - Perl interface to GnuPG
7

SYNOPSIS

9         # A simple example
10         use IO::Handle;
11         use GnuPG::Interface;
12
13         # setting up the situation
14         my $gnupg = GnuPG::Interface->new();
15         $gnupg->options->hash_init( armor   => 1,
16                                     homedir => '/home/foobar' );
17
18         # 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
22         # 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
28         # Now we'll go about encrypting with the options already set
29         my @plaintext = ( 'foobar' );
30         my $pid = $gnupg->encrypt( handles => $handles );
31
32         # Now we write to the input of GnuPG
33         print $input @plaintext;
34         close $input;
35
36         # now we read the output
37         my @ciphertext = <$output>;
38         close $output;
39
40         waitpid $pid, 0;
41

DESCRIPTION

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
48   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
55   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
67       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

GnuPG Versions

75       As of this version of GnuPG::Interface, there are two supported
76       versions of GnuPG: 1.4.x and 2.2.x. The GnuPG download page
77       <https://gnupg.org/download/index.html> has updated information on the
78       currently supported versions.
79
80       GnuPG released 2.0 and 2.1 versions in the past and some packaging
81       systems may still provide these if you install the default "gpg",
82       "gnupg", "gnupg2", etc. packages. This modules supports only version
83       2.2.x, so you may need to find additional package repositories or build
84       from source to get the updated version.
85

OBJECT METHODS

87   Initialization Methods
88       new( %initialization_args )
89           This methods creates a new object.  The optional arguments are
90           initialization of data members.
91
92       hash_init( %args ).
93
94   Object Methods which use a GnuPG::Handles Object
95       list_public_keys( % )
96       list_sigs( % )
97       list_secret_keys( % )
98       encrypt( % )
99       encrypt_symmetrically( % )
100       sign( % )
101       clearsign( % )
102       detach_sign( % )
103       sign_and_encrypt( % )
104       decrypt( % )
105       verify( % )
106       import_keys( % )
107       export_keys( % )
108       recv_keys( % )
109       send_keys( % )
110       search_keys( % )
111           These methods each correspond directly to or are very similar to a
112           GnuPG command described in gpg.  Each of these methods takes a
113           hash, which currently must contain a key of handles which has the
114           value of a GnuPG::Handles object.  Another optional key is
115           command_args which should have the value of an array reference;
116           these arguments will be passed to GnuPG as command arguments.
117           These command arguments are used for such things as determining the
118           keys to list in the export_keys method.  Please note that GnuPG
119           command arguments are not the same as GnuPG options.  To understand
120           what are options and what are command arguments please read
121           "COMMANDS" in gpg and "OPTIONS" in gpg.
122
123           Each of these calls returns the PID for the resulting GnuPG
124           process.  One can use this PID in a "waitpid" call instead of a
125           "wait" call if more precise process reaping is needed.
126
127           These methods will attach the handles specified in the handles
128           object to the running GnuPG object, so that bidirectional
129           communication can be established.  That is, the optionally-defined
130           stdin, stdout, stderr, status, logger, and passphrase handles will
131           be attached to GnuPG's input, output, standard error, the handle
132           created by setting status-fd, the handle created by setting logger-
133           fd, and the handle created by setting passphrase-fd respectively.
134           This tying of handles of similar to the process done in IPC::Open3.
135
136           If you want the GnuPG process to read or write directly to an
137           already-opened filehandle, you cannot do this via the normal
138           IPC::Open3 mechanisms.  In order to accomplish this, set the
139           appropriate handles data member to the already-opened filehandle,
140           and then set the option direct to be true for that handle, as
141           described in "options" in GnuPG::Handles.  For example, to have
142           GnuPG read from the file input.txt and write to output.txt, the
143           following snippet may do:
144
145             my $infile  = IO::File->new( 'input.txt' );
146             my $outfile = IO::File->new( '>output.txt' );
147             my $handles = GnuPG::Handles->new( stdin  => $infile,
148                                                stdout => $outfile,
149                                              );
150             $handles->options( 'stdin'  )->{direct} = 1;
151             $handles->options( 'stdout' )->{direct} = 1;
152
153           If any handle in the handles object is not defined, GnuPG's input,
154           output, and standard error will be tied to the running program's
155           standard error, standard output, or standard error.  If the status
156           or logger handle is not defined, this channel of communication is
157           never established with GnuPG, and so this information is not
158           generated and does not come into play.
159
160           If the passphrase data member handle of the handles object is not
161           defined, but the the passphrase data member handle of
162           GnuPG::Interface object is, GnuPG::Interface will handle passing
163           this information into GnuPG for the user as a convenience.  Note
164           that this will result in GnuPG::Interface storing the passphrase in
165           memory, instead of having it simply 'pass-through' to GnuPG via a
166           handle.
167
168           If neither the passphrase data member of the GnuPG::Interface nor
169           the passphrase data member of the handles object is defined, then
170           GnuPG::Interface assumes that access and control over the secret
171           key will be handled by the running gpg-agent process.  This
172           represents the simplest mode of operation with the GnuPG "stable"
173           suite (version 2.2 and later).  It is also the preferred mode for
174           tools intended to be user-facing, since the user will be prompted
175           directly by gpg-agent for use of the secret key material.  Note
176           that for programmatic use, this mode requires the gpg-agent and
177           pinentry to already be correctly configured.
178
179   Other Methods
180       get_public_keys( @search_strings )
181       get_secret_keys( @search_strings )
182       get_public_keys_with_sigs( @search_strings )
183           These methods create and return objects of the type
184           GnuPG::PublicKey or GnuPG::SecretKey respectively.  This is done by
185           parsing the output of GnuPG with the option with-colons enabled.
186           The objects created do or do not have signature information stored
187           in them, depending if the method ends in _sigs; this separation of
188           functionality is there because of performance hits when listing
189           information with signatures.
190
191       test_default_key_passphrase()
192           This method will return a true or false value, depending on whether
193           GnuPG reports a good passphrase was entered while signing a short
194           message using the values of the passphrase data member, and the
195           default key specified in the options data member.
196
197       version()
198           Returns the version of GnuPG that GnuPG::Interface is running.
199

Invoking GnuPG with a custom call

201       GnuPG::Interface attempts to cover a lot of the commands of GnuPG that
202       one would want to perform; however, there may be a lot more calls that
203       GnuPG is and will be capable of, so a generic command interface is
204       provided, "wrap_call".
205
206       wrap_call( %args )
207           Call GnuPG with a custom command.  The %args hash must contain at
208           least the following keys:
209
210           commands
211               The value of this key in the hash must be a reference to a a
212               list of commands for GnuPG, such as "[ qw( --encrypt --sign )
213               ]".
214
215           handles
216               As with most other GnuPG::Interface methods, handles must be a
217               GnuPG::Handles object.
218
219           The following keys are optional.
220
221           command_args
222               As with other GnuPG::Interface methods, the value in hash for
223               this key must be a reference to a list of arguments to be
224               passed to the GnuPG command, such as which keys to list in a
225               key-listing.
226

OBJECT DATA MEMBERS

228       call
229           This defines the call made to invoke GnuPG.  Defaults to 'gpg';
230           this should be changed if 'gpg' is not in your path, or there is a
231           different name for the binary on your system.
232
233       passphrase
234           In order to lessen the burden of using handles by the user of this
235           package, setting this option to one's passphrase for a secret key
236           will allow the package to enter the passphrase via a handle to
237           GnuPG by itself instead of leaving this to the user.  See also
238           "passphrase" in GnuPG::Handles.
239
240       options
241           This data member, of the type GnuPG::Options; the setting stored in
242           this data member are used to determine the options used when
243           calling GnuPG via any of the object methods described in this
244           package.  See GnuPG::Options for more information.
245

EXAMPLES

247       The following setup can be done before any of the following examples:
248
249         use IO::Handle;
250         use GnuPG::Interface;
251
252         my @original_plaintext = ( "How do you doo?" );
253         my $passphrase = "Three Little Pigs";
254
255         my $gnupg = GnuPG::Interface->new();
256
257         $gnupg->options->hash_init( armor    => 1,
258                                     recipients => [ 'ftobin@uiuc.edu',
259                                                     '0xABCD1234ABCD1234ABCD1234ABCD1234ABCD1234' ],
260                                     meta_interactive => 0 ,
261                                   );
262
263          $gnupg->options->debug_level(4);
264
265          $gnupg->options->logger_file("/tmp/gnupg-$$-decrypt-".time().".log");
266
267   Encrypting
268         # We'll let the standard error of GnuPG pass through
269         # to our own standard error, by not creating
270         # a stderr-part of the $handles object.
271         my ( $input, $output ) = ( IO::Handle->new(),
272                                    IO::Handle->new() );
273
274         my $handles = GnuPG::Handles->new( stdin    => $input,
275                                            stdout   => $output );
276
277         # this sets up the communication
278         # Note that the recipients were specified earlier
279         # in the 'options' data member of the $gnupg object.
280         my $pid = $gnupg->encrypt( handles => $handles );
281
282         # this passes in the plaintext
283         print $input @original_plaintext;
284
285         # this closes the communication channel,
286         # indicating we are done
287         close $input;
288
289         my @ciphertext = <$output>;  # reading the output
290
291         waitpid $pid, 0;  # clean up the finished GnuPG process
292
293   Signing
294         # This time we'll catch the standard error for our perusing
295         my ( $input, $output, $error ) = ( IO::Handle->new(),
296                                            IO::Handle->new(),
297                                            IO::Handle->new(),
298                                          );
299
300         my $handles = GnuPG::Handles->new( stdin    => $input,
301                                            stdout   => $output,
302                                            stderr   => $error,
303                                          );
304
305         # indicate our pasphrase through the
306         # convenience method
307         $gnupg->passphrase( $passphrase );
308
309         # this sets up the communication
310         my $pid = $gnupg->sign( handles => $handles );
311
312         # this passes in the plaintext
313         print $input @original_plaintext;
314
315         # this closes the communication channel,
316         # indicating we are done
317         close $input;
318
319         my @ciphertext   = <$output>;  # reading the output
320         my @error_output = <$error>;   # reading the error
321
322         close $output;
323         close $error;
324
325         waitpid $pid, 0;  # clean up the finished GnuPG process
326
327   Decryption
328         # This time we'll catch the standard error for our perusing
329         # as well as passing in the passphrase manually
330         # as well as the status information given by GnuPG
331         my ( $input, $output, $error, $passphrase_fh, $status_fh )
332           = ( IO::Handle->new(),
333               IO::Handle->new(),
334               IO::Handle->new(),
335               IO::Handle->new(),
336               IO::Handle->new(),
337             );
338
339         my $handles = GnuPG::Handles->new( stdin      => $input,
340                                            stdout     => $output,
341                                            stderr     => $error,
342                                            passphrase => $passphrase_fh,
343                                            status     => $status_fh,
344                                          );
345
346         # this time we'll also demonstrate decrypting
347         # a file written to disk
348         # Make sure you "use IO::File" if you use this module!
349         my $cipher_file = IO::File->new( 'encrypted.gpg' );
350
351         # this sets up the communication
352         my $pid = $gnupg->decrypt( handles => $handles );
353
354         # This passes in the passphrase
355         print $passphrase_fh $passphrase;
356         close $passphrase_fh;
357
358         # this passes in the plaintext
359         print $input $_ while <$cipher_file>;
360
361         # this closes the communication channel,
362         # indicating we are done
363         close $input;
364         close $cipher_file;
365
366         my @plaintext    = <$output>;    # reading the output
367         my @error_output = <$error>;     # reading the error
368         my @status_info  = <$status_fh>; # read the status info
369
370         # clean up...
371         close $output;
372         close $error;
373         close $status_fh;
374
375         waitpid $pid, 0;  # clean up the finished GnuPG process
376
377   Printing Keys
378         # This time we'll just let GnuPG print to our own output
379         # and read from our input, because no input is needed!
380         my $handles = GnuPG::Handles->new();
381
382         my @ids = ( 'ftobin', '0xABCD1234ABCD1234ABCD1234ABCD1234ABCD1234' );
383
384         # this time we need to specify something for
385         # command_args because --list-public-keys takes
386         # search ids as arguments
387         my $pid = $gnupg->list_public_keys( handles      => $handles,
388                                             command_args => [ @ids ] );
389
390          waitpid $pid, 0;
391
392   Creating GnuPG::PublicKey Objects
393         my @ids = [ 'ftobin', '0xABCD1234ABCD1234ABCD1234ABCD1234ABCD1234' ];
394
395         my @keys = $gnupg->get_public_keys( @ids );
396
397         # no wait is required this time; it's handled internally
398         # since the entire call is encapsulated
399
400   Custom GnuPG call
401         # assuming $handles is a GnuPG::Handles object
402         my $pid = $gnupg->wrap_call
403           ( commands     => [ qw( --list-packets ) ],
404             command_args => [ qw( test/key.1.asc ) ],
405             handles      => $handles,
406           );
407
408           my @out = <$handles->stdout()>;
409           waitpid $pid, 0;
410

FAQ

412       How do I get GnuPG::Interface to read/write directly from a filehandle?
413           You need to set GnuPG::Handles direct option to be true for the
414           filehandles in concern.  See "options" in GnuPG::Handles and
415           "Object Methods which use a GnuPG::Handles Object" for more
416           information.
417
418       Why do you make it so difficult to get GnuPG to write/read from a
419       filehandle?  In the shell, I can just call GnuPG with the --outfile
420       option!
421           There are lots of issues when trying to tell GnuPG to read/write
422           directly from a file, such as if the file isn't there, or there is
423           a file, and you want to write over it!  What do you want to happen
424           then?  Having the user of this module handle these questions
425           beforehand by opening up filehandles to GnuPG lets the user know
426           fully what is going to happen in these circumstances, and makes the
427           module less error-prone.
428
429       When having GnuPG process a large message, sometimes it just hanges
430       there.
431           Your problem may be due to buffering issues; when GnuPG
432           reads/writes to non-direct filehandles (those that are sent to
433           filehandles which you read to from into memory, not that those
434           access the disk), buffering issues can mess things up.  I recommend
435           looking into "options" in GnuPG::Handles.
436

NOTES

438       This package is the successor to PGP::GPG::MessageProcessor, which I
439       found to be too inextensible to carry on further.  A total redesign was
440       needed, and this is the resulting work.
441
442       After any call to a GnuPG-command method of GnuPG::Interface in which
443       one passes in the handles, one should all wait to clean up GnuPG from
444       the process table.
445

BUGS

447   Large Amounts of Data
448       Currently there are problems when transmitting large quantities of
449       information over handles; I'm guessing this is due to buffering issues.
450       This bug does not seem specific to this package; IPC::Open3 also
451       appears affected.
452
453   OpenPGP v3 Keys
454       I don't know yet how well this module handles parsing OpenPGP v3 keys.
455
456   RHEL 7 Test Failures
457       Testing with the updates for version 1.00 we saw intermittent test
458       failures on RHEL 7 with GnuPG version 2.2.20. In some cases the tests
459       would all pass for several runs, then one would fail. We're unable to
460       reliably reproduce this so we would be interested in feedback from
461       other users.
462

SEE ALSO

464       GnuPG::Options, GnuPG::Handles, GnuPG::PublicKey, GnuPG::SecretKey,
465       gpg, "Bidirectional Communication with Another Process" in perlipc
466

LICENSE

468       This module is free software; you can redistribute it and/or modify it
469       under the same terms as Perl itself.
470

AUTHOR

472       GnuPG::Interface is currently maintained by Best Practical Solutions
473       <BPS@cpan.org>.
474
475       Frank J. Tobin, ftobin@cpan.org was the original author of the package.
476
477
478
479perl v5.36.0                      2023-01-20               GnuPG::Interface(3)
Impressum