[Bps-public-commit] GnuPG-Interface branch, master, updated. 0.50-1-g1bda3fb
Alex Vandiver
alexmv at bestpractical.com
Tue Dec 2 17:20:18 EST 2014
The branch, master has been updated
via 1bda3fbf64d54730f649d24e35beadf3d20515c2 (commit)
from 599efbfc8750260a2b7b6e30c87848cb3b7915bd (commit)
Summary of changes:
Makefile.PL | 1 +
README | 888 +++++++++++++++++++++++++++++-------------------------------
2 files changed, 434 insertions(+), 455 deletions(-)
- Log -----------------------------------------------------------------
commit 1bda3fbf64d54730f649d24e35beadf3d20515c2
Author: Alex Vandiver <alexmv at bestpractical.com>
Date: Tue Dec 2 17:20:15 2014 -0500
Generate the README from the POD, not from `man`
This removes overstruck letters from the README, and updates it
diff --git a/Makefile.PL b/Makefile.PL
index 00b9e29..3185540 100644
--- a/Makefile.PL
+++ b/Makefile.PL
@@ -16,6 +16,7 @@ author 'Frank J. Tobin';
abstract 'supply object methods for interacting with GnuPG';
name 'GnuPG-Interface';
version_from 'lib/GnuPG/Interface.pm';
+readme_from 'lib/GnuPG/Interface.pm';
requires 'Moo' => '0.091011';
requires 'MooX::HandlesVia' => '0.001004';
requires 'MooX::late' => '0.014';
diff --git a/README b/README
index 02837bd..fcb982a 100644
--- a/README
+++ b/README
@@ -1,456 +1,434 @@
-GnuPG::Interface(3) User Contributed Perl Documentation GnuPG::Interface(3)
-
-
-
-NNAAMMEE
- GnuPG::Interface − Perl interface to GnuPG
-
-SSYYNNOOPPSSIISS
- # A simple example
- use IO::Handle;
- use GnuPG::Interface;
-
- # settting up the situation
- my $gnupg = GnuPG::Interface‐>new();
- $gnupg‐>options‐>hash_init( armor => 1,
- homedir => ’/home/foobar’ );
-
- # Note you can set the recipients even if you aren’t encrypting!
- $gnupg‐>options‐>push_recipients( ’ftobin at cpan.org’ );
- $gnupg‐>options‐>meta_interactive( 0 );
-
- # how we create some handles to interact with GnuPG
- my $input = IO::Handle‐>new();
- my $output = IO::Handle‐>new();
- my $handles = GnuPG::Handles‐>new( stdin => $input,
- stdout => $output );
-
- # Now we’ll go about encrypting with the options already set
- my @plaintext = ( ’foobar’ );
- my $pid = $gnupg‐>encrypt( handles => $handles );
-
- # Now we write to the input of GnuPG
- print $input @plaintext;
- close $input;
-
- # now we read the output
- my @ciphertext = <$output>;
- close $output;
-
- waitpid $pid, 0;
-
-DDEESSCCRRIIPPTTIIOONN
- GnuPG::Interface and its associated modules are designed to provide an
- object‐oriented method for interacting with GnuPG, being able to per‐
- form functions such as but not limited to encrypting, signing, decryp‐
- tion, verification, and key‐listing parsing.
-
- HHooww DDaattaa MMeemmbbeerr AAcccceessssoorr MMeetthhooddss aarree CCrreeaatteedd
-
- Each module in the GnuPG::Interface bundle relies on Class::MethodMaker
- to generate the get/set methods used to set the object’s data members.
- _T_h_i_s _i_s _v_e_r_y _i_m_p_o_r_t_a_n_t _t_o _r_e_a_l_i_z_e_. This means that any data member
- which is a list has special methods assigned to it for pushing, pop‐
- ping, and clearing the list.
-
- UUnnddeerrssttaannddiinngg BBiiddiirreeccttiioonnaall CCoommmmuunniiccaattiioonn
-
- It is also imperative to realize that this package uses interprocess
- communication methods similar to those used in IPC::Open3 and "Bidirec‐
- tional Communication with Another Process" in perlipc, and that users
- of this package need to understand how to use this method because this
- package does not abstract these methods for the user greatly. This
- package is not designed to abstract this away entirely (partly for
- security purposes), but rather to simply help create ’proper’, clean
- calls to GnuPG, and to implement key‐listing parsing. Please see
- "Bidirectional Communication with Another Process" in perlipc to learn
- how to deal with these methods.
-
- Using this package to do message processing generally invovlves creat‐
- ing a GnuPG::Interface object, creating a GnuPG::Handles object, set‐
- ting some options in its ooppttiioonnss data member, and then calling a method
- which invokes GnuPG, such as cclleeaarrssiiggnn. One then interacts with with
- the handles appropriately, as described in "Bidirectional Communication
- with Another Process" in perlipc.
-
-OOBBJJEECCTT MMEETTHHOODDSS
- IInniittiiaalliizzaattiioonn MMeetthhooddss
-
-
- new( _%_i_n_i_t_i_a_l_i_z_a_t_i_o_n___a_r_g_s )
- This methods creates a new object. The optional arguments are ini‐
- tialization of data members; the initialization is done in a manner
- according to the method created as described in "new_hash_init" in
- Class::MethodMaker.
-
- hash_init( _%_a_r_g_s ).
- This methods work as described in "new_hash_init" in Class::Method‐
- Maker.
-
- OObbjjeecctt MMeetthhooddss wwhhiicchh uussee aa GGnnuuPPGG::::HHaannddlleess OObbjjeecctt
-
-
- list_public_keys( % )
- list_sigs( % )
- list_secret_keys( % )
- encrypt( % )
- encrypt_symmetrically( % )
- sign( % )
- clearsign( % )
- detach_sign( % )
- sign_and_encrypt( % )
- decrypt( % )
- verify( % )
- import_keys( % )
- export_keys( % )
- recv_keys( % )
- send_keys( % )
- These methods each correspond directly to or are very similar to a
- GnuPG command described in gpg. Each of these methods takes a
- hash, which currently must contain a key of hhaannddlleess which has the
- value of a GnuPG::Handles object. Another optional key is ccoomm‐‐
- mmaanndd__aarrggss which should have the value of an array reference; these
- arguments will be passed to GnuPG as command arguments. These com‐
- mand arguments are used for such things as determining the keys to
- list in the eexxppoorrtt__kkeeyyss method. _P_l_e_a_s_e _n_o_t_e _t_h_a_t _G_n_u_P_G _c_o_m_m_a_n_d
- _a_r_g_u_m_e_n_t_s _a_r_e _n_o_t _t_h_e _s_a_m_e _a_s _G_n_u_P_G _o_p_t_i_o_n_s. To understand what
- are options and what are command arguments please read "COMMANDS"
- in gpg and "OPTIONS" in gpg.
-
- Each of these calls returns the PID for the resulting GnuPG
- process. One can use this PID in a "waitpid" call instead of a
- "wait" call if more precise process reaping is needed.
-
- These methods will attach the handles specified in the hhaannddlleess
- object to the running GnuPG object, so that bidirectional communi‐
- cation can be established. That is, the optionally‐defined ssttddiinn,
- ssttddoouutt, ssttddeerrrr, ssttaattuuss, llooggggeerr, and ppaasssspphhrraassee handles will be
- attached to GnuPG’s input, output, standard error, the handle cre‐
- ated by setting ssttaattuuss‐‐ffdd, the handle created by setting llooggggeerr‐‐ffdd,
- and the handle created by setting ppaasssspphhrraassee‐‐ffdd respectively. This
- tying of handles of similar to the process done in _I_P_C_:_:_O_p_e_n_3.
-
- If you want the GnuPG process to read or write directly to an
- already‐opened filehandle, you cannot do this via the normal
- _I_P_C_:_:_O_p_e_n_3 mechanisms. In order to accomplish this, set the appro‐
- priate hhaannddlleess data member to the already‐opened filehandle, and
- then set the option ddiirreecctt to be true for that handle, as described
- in "options" in GnuPG::Handles. For example, to have GnuPG read
- from the file _i_n_p_u_t_._t_x_t and write to _o_u_t_p_u_t_._t_x_t, the following
- snippet may do:
-
- my $infile = IO::File‐>new( ’input.txt’ );
- my $outfile = IO::File‐>new( ’>output.txt’ );
- my $handles = GnuPG::Handles‐>new( stdin => $infile,
- stdout => $outfile,
- );
- $handles‐>options( ’stdin’ )‐>{direct} = 1;
- $handles‐>options( ’stdout’ )‐>{direct} = 1;
-
- If any handle in the hhaannddlleess object is not defined, GnuPG’s input,
- output, and standard error will be tied to the running program’s
- standard error, standard output, or standard error. If the ssttaattuuss
- or llooggggeerr handle is not defined, this channel of communication is
- never established with GnuPG, and so this information is not gener‐
- ated and does not come into play. If the ppaasssspphhrraassee data member
- handle of the hhaannddlleess object is not defined, but the the ppaasssspphhrraassee
- data member handle of GnuPG::Interface object is, GnuPG::Interface
- will handle passing this information into GnuPG for the user as a
- convience. Note that this will result in GnuPG::Interface storing
- the passphrase in memory, instead of having it simply
- ’pass−through’ to GnuPG via a handle.
-
- OOtthheerr MMeetthhooddss
-
-
- get_public_keys( @search_strings )
- get_secret_keys( @search_strings )
- get_public_keys_with_sigs( @search_strings )
- These methods create and return objects of the type GnuPG::Pub‐
- licKey or GnuPG::SecretKey respectively. This is done by parsing
- the output of GnuPG with the option wwiitthh‐‐ccoolloonnss enabled. The
- objects created do or do not have signature information stored in
- them, depending if the method ends in ___s_i_g_s; this separation of
- functionality is there because of performance hits when listing
- information with signatures.
-
- _t_e_s_t___d_e_f_a_u_l_t___k_e_y___p_a_s_s_p_h_r_a_s_e_(_)
- This method will return a true or false value, depending on whether
- GnuPG reports a good passphrase was entered while signing a short
- message using the values of the ppaasssspphhrraassee data member, and the
- default key specified in the ooppttiioonnss data member.
-
-IInnvvookkiinngg GGnnuuPPGG wwiitthh aa ccuussttoomm ccaallll
- GnuPG::Interface attempts to cover a lot of the commands of GnuPG that
- one would want to perform; however, there may be a lot more calls that
- GnuPG is and will be capable of, so a generic command interface is pro‐
- vided, "wrap_call".
-
- wrap_call( %args )
- Call GnuPG with a custom command. The %args hash must contain at
- least the following keys:
-
- commands
- The value of this key in the hash must be a reference to a a
- list of commands for GnuPG, such as "[ qw( −−encrypt −−sign )
- ]".
-
- handles
- As with most other GnuPG::Interface methods, hhaannddlleess must be a
- GnuPG::Handles object.
-
- The following keys are optional.
-
- command_args
- As with other GnuPG::Interface methods, the value in hash for
- this key must be a reference to a list of arguments to be
- passed to the GnuPG command, such as which keys to list in a
- key−listing.
-
-OOBBJJEECCTT DDAATTAA MMEEMMBBEERRSS
- Note that these data members are interacted with via object methods
- created using the methods described in "get_set" in Class::MethodMaker,
- or "object" in Class::MethodMaker. Please read there for more informa‐
- tion.
-
- call
- This defines the call made to invoke GnuPG. Defaults to ’gpg’;
- this should be changed if ’gpg’ is not in your path, or there is a
- different name for the binary on your system.
-
- passphrase
- In order to lessen the burden of using handles by the user of this
- package, setting this option to one’s passphrase for a secret key
- will allow the package to enter the passphrase via a handle to
- GnuPG by itself instead of leaving this to the user. See also
- "passphrase" in GnuPG::Handles.
-
- options
- This data member, of the type GnuPG::Options; the setting stored in
- this data member are used to determine the options used when call‐
- ing GnuPG via _a_n_y of the object methods described in this package.
- See GnuPG::Options for more information.
-
-EEXXAAMMPPLLEESS
- The following setup can be done before any of the following examples:
-
- use IO::Handle;
- use GnuPG::Interface;
-
- my @original_plaintext = ( "How do you doo?" );
- my $passphrase = "Three Little Pigs";
-
- my $gnupg = GnuPG::Interface‐>new();
-
- $gnupg‐>options‐>hash_init( armor => 1,
- recipients => [ ’ftobin at uiuc.edu’,
- ’0xABCD1234’ ],
- meta_interactive( 0 ),
- );
-
- EEnnccrryyppttiinngg
-
- # We’ll let the standard error of GnuPG pass through
- # to our own standard error, by not creating
- # a stderr‐part of the $handles object.
- my ( $input, $output ) = ( IO::Handle‐>new(),
- IO::Handle‐>new() );
-
- my $handles = GnuPG::Handles‐>new( stdin => $input,
- stdout => $output );
-
- # this sets up the communication
- # Note that the recipients were specified earlier
- # in the ’options’ data member of the $gnupg object.
- my $pid = $gnupg‐>encrypt( handles => $handles );
-
- # this passes in the plaintext
- print $input @original_plaintext;
-
- # this closes the communication channel,
- # indicating we are done
- close $input;
-
- my @ciphertext = <$output>; # reading the output
-
- waitpid $pid, 0; # clean up the finished GnuPG process
-
- SSiiggnniinngg
+NAME
+ GnuPG::Interface - Perl interface to GnuPG
+
+SYNOPSIS
+ # A simple example
+ use IO::Handle;
+ use GnuPG::Interface;
+
+ # settting up the situation
+ my $gnupg = GnuPG::Interface->new();
+ $gnupg->options->hash_init( armor => 1,
+ homedir => '/home/foobar' );
+
+ # Note you can set the recipients even if you aren't encrypting!
+ $gnupg->options->push_recipients( 'ftobin at cpan.org' );
+ $gnupg->options->meta_interactive( 0 );
+
+ # how we create some handles to interact with GnuPG
+ my $input = IO::Handle->new();
+ my $output = IO::Handle->new();
+ my $handles = GnuPG::Handles->new( stdin => $input,
+ stdout => $output );
+
+ # Now we'll go about encrypting with the options already set
+ my @plaintext = ( 'foobar' );
+ my $pid = $gnupg->encrypt( handles => $handles );
+
+ # Now we write to the input of GnuPG
+ print $input @plaintext;
+ close $input;
+
+ # now we read the output
+ my @ciphertext = <$output>;
+ close $output;
+
+ waitpid $pid, 0;
+
+DESCRIPTION
+ GnuPG::Interface and its associated modules are designed to provide an
+ object-oriented method for interacting with GnuPG, being able to perform
+ functions such as but not limited to encrypting, signing, decryption,
+ verification, and key-listing parsing.
+
+ How Data Member Accessor Methods are Created
+ Each module in the GnuPG::Interface bundle relies on Moo to generate the
+ get/set methods used to set the object's data members. *This is very
+ important to realize.* This means that any data member which is a list
+ has special methods assigned to it for pushing, popping, and clearing
+ the list.
+
+ Understanding Bidirectional Communication
+ It is also imperative to realize that this package uses interprocess
+ communication methods similar to those used in IPC::Open3 and
+ "Bidirectional Communication with Another Process" in perlipc, and that
+ users of this package need to understand how to use this method because
+ this package does not abstract these methods for the user greatly. This
+ package is not designed to abstract this away entirely (partly for
+ security purposes), but rather to simply help create 'proper', clean
+ calls to GnuPG, and to implement key-listing parsing. Please see
+ "Bidirectional Communication with Another Process" in perlipc to learn
+ how to deal with these methods.
+
+ Using this package to do message processing generally invovlves creating
+ a GnuPG::Interface object, creating a GnuPG::Handles object, setting
+ some options in its options data member, and then calling a method which
+ invokes GnuPG, such as clearsign. One then interacts with with the
+ handles appropriately, as described in "Bidirectional Communication with
+ Another Process" in perlipc.
+
+OBJECT METHODS
+ Initialization Methods
+ new( *%initialization_args* )
+ This methods creates a new object. The optional arguments are
+ initialization of data members.
+
+ hash_init( *%args* ).
+
+ Object Methods which use a GnuPG::Handles Object
+ list_public_keys( % )
+ list_sigs( % )
+ list_secret_keys( % )
+ encrypt( % )
+ encrypt_symmetrically( % )
+ sign( % )
+ clearsign( % )
+ detach_sign( % )
+ sign_and_encrypt( % )
+ decrypt( % )
+ verify( % )
+ import_keys( % )
+ export_keys( % )
+ recv_keys( % )
+ send_keys( % )
+ search_keys( % )
+ These methods each correspond directly to or are very similar to a
+ GnuPG command described in gpg. Each of these methods takes a hash,
+ which currently must contain a key of handles which has the value of
+ a GnuPG::Handles object. Another optional key is command_args which
+ should have the value of an array reference; these arguments will be
+ passed to GnuPG as command arguments. These command arguments are
+ used for such things as determining the keys to list in the
+ export_keys method. *Please note that GnuPG command arguments are
+ not the same as GnuPG options*. To understand what are options and
+ what are command arguments please read "COMMANDS" in gpg and
+ "OPTIONS" in gpg.
+
+ Each of these calls returns the PID for the resulting GnuPG process.
+ One can use this PID in a "waitpid" call instead of a "wait" call if
+ more precise process reaping is needed.
+
+ These methods will attach the handles specified in the handles
+ object to the running GnuPG object, so that bidirectional
+ communication can be established. That is, the optionally-defined
+ stdin, stdout, stderr, status, logger, and passphrase handles will
+ be attached to GnuPG's input, output, standard error, the handle
+ created by setting status-fd, the handle created by setting
+ logger-fd, and the handle created by setting passphrase-fd
+ respectively. This tying of handles of similar to the process done
+ in *IPC::Open3*.
+
+ If you want the GnuPG process to read or write directly to an
+ already-opened filehandle, you cannot do this via the normal
+ *IPC::Open3* mechanisms. In order to accomplish this, set the
+ appropriate handles data member to the already-opened filehandle,
+ and then set the option direct to be true for that handle, as
+ described in "options" in GnuPG::Handles. For example, to have GnuPG
+ read from the file input.txt and write to output.txt, the following
+ snippet may do:
+
+ my $infile = IO::File->new( 'input.txt' );
+ my $outfile = IO::File->new( '>output.txt' );
+ my $handles = GnuPG::Handles->new( stdin => $infile,
+ stdout => $outfile,
+ );
+ $handles->options( 'stdin' )->{direct} = 1;
+ $handles->options( 'stdout' )->{direct} = 1;
+
+ If any handle in the handles object is not defined, GnuPG's input,
+ output, and standard error will be tied to the running program's
+ standard error, standard output, or standard error. If the status or
+ logger handle is not defined, this channel of communication is never
+ established with GnuPG, and so this information is not generated and
+ does not come into play. If the passphrase data member handle of the
+ handles object is not defined, but the the passphrase data member
+ handle of GnuPG::Interface object is, GnuPG::Interface will handle
+ passing this information into GnuPG for the user as a convience.
+ Note that this will result in GnuPG::Interface storing the
+ passphrase in memory, instead of having it simply 'pass-through' to
+ GnuPG via a handle.
+
+ Other Methods
+ get_public_keys( @search_strings )
+ get_secret_keys( @search_strings )
+ get_public_keys_with_sigs( @search_strings )
+ These methods create and return objects of the type GnuPG::PublicKey
+ or GnuPG::SecretKey respectively. This is done by parsing the output
+ of GnuPG with the option with-colons enabled. The objects created do
+ or do not have signature information stored in them, depending if
+ the method ends in *_sigs*; this separation of functionality is
+ there because of performance hits when listing information with
+ signatures.
+
+ test_default_key_passphrase()
+ This method will return a true or false value, depending on whether
+ GnuPG reports a good passphrase was entered while signing a short
+ message using the values of the passphrase data member, and the
+ default key specified in the options data member.
+
+ version()
+ Returns the version of GnuPG that GnuPG::Interface is running.
+
+Invoking GnuPG with a custom call
+ GnuPG::Interface attempts to cover a lot of the commands of GnuPG that
+ one would want to perform; however, there may be a lot more calls that
+ GnuPG is and will be capable of, so a generic command interface is
+ provided, "wrap_call".
+
+ wrap_call( %args )
+ Call GnuPG with a custom command. The %args hash must contain at
+ least the following keys:
+
+ commands
+ The value of this key in the hash must be a reference to a a
+ list of commands for GnuPG, such as "[ qw( --encrypt --sign )
+ ]".
+
+ handles
+ As with most other GnuPG::Interface methods, handles must be a
+ GnuPG::Handles object.
+
+ The following keys are optional.
+
+ command_args
+ As with other GnuPG::Interface methods, the value in hash for
+ this key must be a reference to a list of arguments to be passed
+ to the GnuPG command, such as which keys to list in a
+ key-listing.
+
+OBJECT DATA MEMBERS
+ call
+ This defines the call made to invoke GnuPG. Defaults to 'gpg'; this
+ should be changed if 'gpg' is not in your path, or there is a
+ different name for the binary on your system.
+
+ passphrase
+ In order to lessen the burden of using handles by the user of this
+ package, setting this option to one's passphrase for a secret key
+ will allow the package to enter the passphrase via a handle to GnuPG
+ by itself instead of leaving this to the user. See also "passphrase"
+ in GnuPG::Handles.
+
+ options
+ This data member, of the type GnuPG::Options; the setting stored in
+ this data member are used to determine the options used when calling
+ GnuPG via *any* of the object methods described in this package. See
+ GnuPG::Options for more information.
+
+EXAMPLES
+ The following setup can be done before any of the following examples:
+
+ use IO::Handle;
+ use GnuPG::Interface;
+
+ my @original_plaintext = ( "How do you doo?" );
+ my $passphrase = "Three Little Pigs";
+
+ my $gnupg = GnuPG::Interface->new();
+
+ $gnupg->options->hash_init( armor => 1,
+ recipients => [ 'ftobin at uiuc.edu',
+ '0xABCD1234' ],
+ meta_interactive => 0 ,
+ );
+
+ Encrypting
+ # We'll let the standard error of GnuPG pass through
+ # to our own standard error, by not creating
+ # a stderr-part of the $handles object.
+ my ( $input, $output ) = ( IO::Handle->new(),
+ IO::Handle->new() );
+
+ my $handles = GnuPG::Handles->new( stdin => $input,
+ stdout => $output );
+
+ # this sets up the communication
+ # Note that the recipients were specified earlier
+ # in the 'options' data member of the $gnupg object.
+ my $pid = $gnupg->encrypt( handles => $handles );
+
+ # this passes in the plaintext
+ print $input @original_plaintext;
+
+ # this closes the communication channel,
+ # indicating we are done
+ close $input;
+
+ my @ciphertext = <$output>; # reading the output
+
+ waitpid $pid, 0; # clean up the finished GnuPG process
+
+ Signing
+ # This time we'll catch the standard error for our perusing
+ my ( $input, $output, $error ) = ( IO::Handle->new(),
+ IO::Handle->new(),
+ IO::Handle->new(),
+ );
+
+ my $handles = GnuPG::Handles->new( stdin => $input,
+ stdout => $output,
+ stderr => $error,
+ );
+
+ # indicate our pasphrase through the
+ # convience method
+ $gnupg->passphrase( $passphrase );
+
+ # this sets up the communication
+ my $pid = $gnupg->sign( handles => $handles );
+
+ # this passes in the plaintext
+ print $input @original_plaintext;
+
+ # this closes the communication channel,
+ # indicating we are done
+ close $input;
+
+ my @ciphertext = <$output>; # reading the output
+ my @error_output = <$error>; # reading the error
+
+ close $output;
+ close $error;
+
+ waitpid $pid, 0; # clean up the finished GnuPG process
+
+ Decryption
+ # This time we'll catch the standard error for our perusing
+ # as well as passing in the passphrase manually
+ # as well as the status information given by GnuPG
+ my ( $input, $output, $error, $passphrase_fh, $status_fh )
+ = ( IO::Handle->new(),
+ IO::Handle->new(),
+ IO::Handle->new(),
+ IO::Handle->new(),
+ IO::Handle->new(),
+ );
+
+ my $handles = GnuPG::Handles->new( stdin => $input,
+ stdout => $output,
+ stderr => $error,
+ passphrase => $passphrase_fh,
+ status => $status_fh,
+ );
+
+ # this time we'll also demonstrate decrypting
+ # a file written to disk
+ # Make sure you "use IO::File" if you use this module!
+ my $cipher_file = IO::File->new( 'encrypted.gpg' );
+
+ # this sets up the communication
+ my $pid = $gnupg->decrypt( handles => $handles );
+
+ # This passes in the passphrase
+ print $passphrase_fh $passphrase;
+ close $passphrase_fh;
+
+ # this passes in the plaintext
+ print $input $_ while <$cipher_file>;
+
+ # this closes the communication channel,
+ # indicating we are done
+ close $input;
+ close $cipher_file;
+
+ my @plaintext = <$output>; # reading the output
+ my @error_output = <$error>; # reading the error
+ my @status_info = <$status_fh>; # read the status info
+
+ # clean up...
+ close $output;
+ close $error;
+ close $status_fh;
+
+ waitpid $pid, 0; # clean up the finished GnuPG process
+
+ Printing Keys
+ # This time we'll just let GnuPG print to our own output
+ # and read from our input, because no input is needed!
+ my $handles = GnuPG::Handles->new();
+
+ my @ids = ( 'ftobin', '0xABCD1234' );
+
+ # this time we need to specify something for
+ # command_args because --list-public-keys takes
+ # search ids as arguments
+ my $pid = $gnupg->list_public_keys( handles => $handles,
+ command_args => [ @ids ] );
+
+ waitpid $pid, 0;
+
+ Creating GnuPG::PublicKey Objects
+ my @ids = [ 'ftobin', '0xABCD1234' ];
+
+ my @keys = $gnupg->get_public_keys( @ids );
+
+ # no wait is required this time; it's handled internally
+ # since the entire call is encapsulated
+
+ Custom GnuPG call
+ # assuming $handles is a GnuPG::Handles object
+ my $pid = $gnupg->wrap_call
+ ( commands => [ qw( --list-packets ) ],
+ command_args => [ qw( test/key.1.asc ) ],
+ handles => $handles,
+ );
+
+ my @out = <$handles->stdout()>;
+ waitpid $pid, 0;
+
+FAQ
+ How do I get GnuPG::Interface to read/write directly from a filehandle?
+ You need to set GnuPG::Handles direct option to be true for the
+ filehandles in concern. See "options" in GnuPG::Handles and "Object
+ Methods which use a GnuPG::Handles Object" for more information.
+
+ Why do you make it so difficult to get GnuPG to write/read from a
+ filehandle? In the shell, I can just call GnuPG with the --outfile
+ option!
+ There are lots of issues when trying to tell GnuPG to read/write
+ directly from a file, such as if the file isn't there, or there is a
+ file, and you want to write over it! What do you want to happen
+ then? Having the user of this module handle these questions
+ beforehand by opening up filehandles to GnuPG lets the user know
+ fully what is going to happen in these circumstances, and makes the
+ module less error-prone.
+
+ When having GnuPG process a large message, sometimes it just hanges
+ there.
+ Your problem may be due to buffering issues; when GnuPG reads/writes
+ to non-direct filehandles (those that are sent to filehandles which
+ you read to from into memory, not that those access the disk),
+ buffering issues can mess things up. I recommend looking into
+ "options" in GnuPG::Handles.
+
+NOTES
+ This package is the successor to PGP::GPG::MessageProcessor, which I
+ found to be too inextensible to carry on further. A total redesign was
+ needed, and this is the resulting work.
+
+ After any call to a GnuPG-command method of GnuPG::Interface in which
+ one passes in the handles, one should all wait to clean up GnuPG from
+ the process table.
+
+BUGS
+ Currently there are problems when transmitting large quantities of
+ information over handles; I'm guessing this is due to buffering issues.
+ This bug does not seem specific to this package; IPC::Open3 also appears
+ affected.
+
+ I don't know yet how well this modules handles parsing OpenPGP v3 keys.
+
+SEE ALSO
+ GnuPG::Options, GnuPG::Handles, GnuPG::PublicKey, GnuPG::SecretKey, gpg,
+ "Bidirectional Communication with Another Process" in perlipc
+
+LICENSE
+ This module is free software; you can redistribute it and/or modify it
+ under the same terms as Perl itself.
+
+AUTHOR
+ GnuPg::Interface is currently maintained by Jesse Vincent
+ <jesse at cpan.org>.
+
+ Frank J. Tobin, ftobin at cpan.org was the original author of the package.
- # This time we’ll catch the standard error for our perusing
- my ( $input, $output, $error ) = ( IO::Handle‐>new(),
- IO::Handle‐>new(),
- IO::Handle‐>new(),
- );
-
- my $handles = GnuPG::Handles‐>new( stdin => $input,
- stdout => $output,
- stderr => $error,
- );
-
- # indicate our pasphrase through the
- # convience method
- $gnupg‐>passphrase( $passphrase );
-
- # this sets up the communication
- my $pid = $gnupg‐>sign( handles => $handles );
-
- # this passes in the plaintext
- print $input @original_plaintext;
-
- # this closes the communication channel,
- # indicating we are done
- close $input;
-
- my @ciphertext = <$output>; # reading the output
- my @error_output = <$error>; # reading the error
-
- close $output;
- close $error;
-
- waitpid $pid, 0; # clean up the finished GnuPG process
-
- DDeeccrryyppttiioonn
-
- # This time we’ll catch the standard error for our perusing
- # as well as passing in the passphrase manually
- # as well as the status information given by GnuPG
- my ( $input, $output, $error, $passphrase_fh, $status_fh )
- = ( IO::Handle‐>new(),
- IO::Handle‐>new(),
- IO::Handle‐>new(),
- IO::Handle‐>new(),
- IO::Handle‐>new(),
- );
-
- my $handles = GnuPG::Handles‐>new( stdin => $input,
- stdout => $output,
- stderr => $error,
- passphrase => $passphrase_fh,
- status => $status_fh,
- );
-
- # this time we’ll also demonstrate decrypting
- # a file written to disk
- # Make sure you "use IO::File" if you use this module!
- my $cipher_file = IO::File‐>new( ’encrypted.gpg’ );
-
- # this sets up the communication
- my $pid = $gnupg‐>decrypt( handles => $handles );
-
- # This passes in the passphrase
- print $passphrase_fd $passphrase;
- close $passphrase_fd;
-
- # this passes in the plaintext
- print $input $_ while <$cipher_file>
-
- # this closes the communication channel,
- # indicating we are done
- close $input;
- close $cipher_file;
-
- my @plaintext = <$output>; # reading the output
- my @error_output = <$error>; # reading the error
- my @status_info = <$status_fh> # read the status info
-
- # clean up...
- close $output;
- close $error;
- close $status_fh;
-
- waitpid $pid, 0; # clean up the finished GnuPG process
-
- PPrriinnttiinngg KKeeyyss
-
- # This time we’ll just let GnuPG print to our own output
- # and read from our input, because no input is needed!
- my $handles = GnuPG::Handles‐>new();
-
- my @ids = [ ’ftobin’, ’0xABCD1234’ ];
-
- # this time we need to specify something for
- # command_args because ‐‐list‐public‐keys takes
- # search ids as arguments
- my $pid = $gnupg‐>list_public_keys( handles => $handles,
- command_args => [ @ids ] );
-
- waitpid $pid, 0;
-
- CCrreeaattiinngg GGnnuuPPGG::::PPuubblliiccKKeeyy OObbjjeeccttss
-
- my @ids = [ ’ftobin’, ’0xABCD1234’ ];
-
- my @keys = $gnupg‐>get_public_keys( @ids );
-
- # no wait is required this time; it’s handled internally
- # since the entire call is encapsulated
-
- CCuussttoomm GGnnuuPPGG ccaallll
-
- # assuming $handles is a GnuPG::Handles object
- my $pid = $gnupg‐>wrap_call
- ( commands => [ qw( ‐‐list‐packets ) ],
- command_args => [ qw( test/key.1.asc ) ],
- handles => $handles,
- );
-
- my @out = <$handles‐>stdout()>;
- waitpid $pid, 0;
-
-FFAAQQ
- How do I get GnuPG::Interface to read/write directly from a filehandle?
- You need to set GnuPG::Handles ddiirreecctt option to be true for the
- filehandles in concern. See "options" in GnuPG::Handles and
- "Object Methods which use a GnuPG::Handles Object" for more infor‐
- mation.
-
- Why do you make it so difficult to get GnuPG to write/read from a file‐
- handle? In the shell, I can just call GnuPG with the −−outfile option!
- There are lots of issues when trying to tell GnuPG to read/write
- directly from a file, such as if the file isn’t there, or there is
- a file, and you want to write over it! What do you want to happen
- then? Having the user of this module handle these questions
- beforehand by opening up filehandles to GnuPG lets the user know
- fully what is going to happen in these circumstances, and makes the
- module less error−prone.
-
- When having GnuPG process a large message, sometimes it just hanges
- there.
- Your problem may be due to buffering issues; when GnuPG
- reads/writes to nnoonn‐‐ddiirreecctt filehandles (those that are sent to
- filehandles which you read to from into memory, not that those
- access the disk), buffering issues can mess things up. I recommend
- looking into "options" in GnuPG::Handles.
-
-NNOOTTEESS
- This package is the successor to PGP::GPG::MessageProcessor, which I
- found to be too inextensible to carry on further. A total redesign was
- needed, and this is the resulting work.
-
- After any call to a GnuPG‐command method of GnuPG::Interface in which
- one passes in the handles, one should all wwaaiitt to clean up GnuPG from
- the process table.
-
-BBUUGGSS
- Currently there are problems when transmitting large quantities of
- information over handles; I’m guessing this is due to buffering issues.
- This bug does not seem specific to this package; IPC::Open3 also
- appears affected.
-
- I don’t know yet how well this modules handles parsing OpenPGP v3 keys.
-
-SSEEEE AALLSSOO
- GnuPG::Options, GnuPG::Handles, GnuPG::PublicKey, GnuPG::SecretKey,
- gpg, Class::MethodMaker, "Bidirectional Communication with Another
- Process" in perlipc
-
-AAUUTTHHOORR
- GnuPg::Interface is currently maintained by Jesse Vincent
- <jesse at cpan.org>.
-
- Frank J. Tobin, ftobin at cpan.org was the original author of the package.
-
-
-
-perl v5.8.8 2007‐04‐24 GnuPG::Interface(3)
-----------------------------------------------------------------------
More information about the Bps-public-commit
mailing list