| 1 | package POE::Wheel::GnuPG; | ||
| 2 | |||
| 3 | =head1 NAME | ||
| 4 | |||
| 5 | POE::Wheel::GnuPG - offer GnuPG interaction through POE | ||
| 6 | |||
| 7 | =head1 VERSION | ||
| 8 | |||
| 9 | Version 0.01 | ||
| 10 | |||
| 11 | =cut | ||
| 12 | |||
| 13 | our $VERSION = '0.01'; | ||
| 14 | |||
| 15 | =head1 DESCRIPTION | ||
| 16 | |||
| 17 | POE-Wheel-GnuPG provides a GPG interface to your POE Session. Its main benefits | ||
| 18 | are that it allows asynchronous encryption and decryption, and allow you to | ||
| 19 | encrypt or decrypt on the fly, without having to store data in a file, even | ||
| 20 | when the data is huge. | ||
| 21 | |||
| 22 | I recommend using this module : | ||
| 23 | |||
| 24 | =over | ||
| 25 | |||
| 26 | =item * | ||
| 27 | when you use POE and want to use GPG. | ||
| 28 | |||
| 29 | =item * | ||
| 30 | for security reason, when you have huge data to decrypt and you don't want it to be stored in a file | ||
| 31 | |||
| 32 | =back | ||
| 33 | |||
| 34 | POE-Wheel-GnuPG inherits from GnuPG::Interface, and uses it for GPG actions. It | ||
| 35 | has a different constructor, but apart from that, you can use POE-Wheel-GnuPG | ||
| 36 | as you would use GnuPG::Interface, except for the POE signals of course. | ||
| 37 | |||
| 38 | =head1 SYNOPSIS | ||
| 39 | |||
| 40 | # Example 0 : | ||
| 41 | # Quickly encrypt some text | ||
| 42 | |||
| 43 | use POE qw(Wheel::GnuPG); | ||
| 44 | |||
| 45 | POE::Session->create( | ||
| 46 | inline_states => { | ||
| 47 | _start => sub { | ||
| 48 | |||
| 49 | my $gnupg = POE::Wheel::GnuPG->new( | ||
| 50 | ready_to_input_data => 'ready_to_input_data', | ||
| 51 | something_on_stdout => 'something_on_stdout', | ||
| 52 | end_of_process => 'the_end', | ||
| 53 | ); | ||
| 54 | $_[HEAP]{gnupg} = $gnupg; | ||
| 55 | |||
| 56 | $gnupg->options->hash_init( armor => 1, | ||
| 57 | homedir => '/home/dams/.gnupg' ); | ||
| 58 | $gnupg->options->push_recipients( 'foo@bar.org' ); | ||
| 59 | $gnupg->options->meta_interactive( 0 ); | ||
| 60 | |||
| 61 | $gnupg->encrypt(); | ||
| 62 | }, | ||
| 63 | |||
| 64 | ready_to_input_data => sub { | ||
| 65 | my $input_fh = $_[ARG0]; | ||
| 66 | print $input_fh "This is the secret data!"; | ||
| 67 | |||
| 68 | $_[HEAP]{gnupg}->finished_writing_input(); | ||
| 69 | }, | ||
| 70 | |||
| 71 | something_on_stdout => sub { | ||
| 72 | my $stdout_fh = $_[ARG0]; | ||
| 73 | return if eof $stdout_fh; | ||
| 74 | my @output = <$stdout_fh>; | ||
| 75 | print "Received crypted data : @output\n"; | ||
| 76 | }, | ||
| 77 | the_end => sub { | ||
| 78 | # clean up | ||
| 79 | $_[HEAP]{gnupg}->destroy(); | ||
| 80 | exit(); | ||
| 81 | }, | ||
| 82 | } | ||
| 83 | ); | ||
| 84 | |||
| 85 | POE::Kernel->run(); | ||
| 86 | exit; | ||
| 87 | |||
| 88 | |||
| 89 | # Example 1 : | ||
| 90 | # decrypt a file bits by bits asynchronously | ||
| 91 | # without storing decrypted data on the filesystem. | ||
| 92 | # Display decrypted data uppercased on the fly. | ||
| 93 | |||
| 94 | use POE qw(Wheel::GnuPG); | ||
| 95 | |||
| 96 | POE::Session->create( | ||
| 97 | inline_states => { | ||
| 98 | _start => sub { | ||
| 99 | |||
| 100 | # Let's say we have a file we want to decrypt | ||
| 101 | use IO::File; | ||
| 102 | $_[HEAP]{encrypted_fh} = IO::File->new('encrypted_file.asc', 'r'); | ||
| 103 | |||
| 104 | # Initialize the gnupg object. | ||
| 105 | # stdout, status, error, logger are optional | ||
| 106 | my $gnupg = POE::Wheel::GnuPG->new( | ||
| 107 | ready_to_input_data => 'ready_to_input_data', | ||
| 108 | ready_to_input_passphrase => 'ready_to_input_passphrase', | ||
| 109 | something_on_stdout => 'something_on_stdout', | ||
| 110 | something_on_status => 'something_on_status', | ||
| 111 | something_on_error => 'something_on_error', | ||
| 112 | something_on_logger => 'something_on_logger', | ||
| 113 | end_of_process => 'the_end', | ||
| 114 | ); | ||
| 115 | # save the gnupg object | ||
| 116 | $_[HEAP]{gnupg} = $gnupg; | ||
| 117 | # Set some options (see GnuPG::Interface). All options are supported, | ||
| 118 | # except 'direct'. | ||
| 119 | $gnupg->options->hash_init( armor => 1, | ||
| 120 | homedir => '/Users/dams/.gnupg' ); | ||
| 121 | $gnupg->options->meta_interactive( 0 ); | ||
| 122 | $gnupg->decrypt(); | ||
| 123 | }, | ||
| 124 | |||
| 125 | # This is called when you can input the passphrase | ||
| 126 | ready_to_input_passphrase => sub { | ||
| 127 | my $passphrase_fh = $_[ARG0]; | ||
| 128 | print $passphrase_fh "my passphrase"; | ||
| 129 | |||
| 130 | # this is important to let the decryption start. It means you have | ||
| 131 | # finished entering the passphrase. | ||
| 132 | $_[HEAP]{gnupg}->finished_writing_passphrase(); | ||
| 133 | }, | ||
| 134 | |||
| 135 | # This is called when you can feed input data | ||
| 136 | ready_to_input_data => sub { | ||
| 137 | my $input_fh = $_[ARG0]; | ||
| 138 | # In our case, we get the encrypted file handle, | ||
| 139 | # read from it and feed the gpg input with it | ||
| 140 | my $encrypted_fh = $_[HEAP]{encrypted_fh}; | ||
| 141 | if (eof($encrypted_fh)) { | ||
| 142 | # if it's the end of the encrypted file, we signify to the gnupg object | ||
| 143 | # that it's the end of input | ||
| 144 | $_[HEAP]{gnupg}->finished_writing_input(); | ||
| 145 | } else { | ||
| 146 | # otherwise we feed the input | ||
| 147 | my $line = <$encrypted_fh>; | ||
| 148 | print $input_fh $line; | ||
| 149 | } | ||
| 150 | }, | ||
| 151 | # gnupg returned decrypted data, do something with it | ||
| 152 | something_on_stdout => sub { | ||
| 153 | my $stdout_fh = $_[ARG0]; | ||
| 154 | return if eof $stdout_fh; | ||
| 155 | my @output = <$stdout_fh>; | ||
| 156 | my @uppercased_output = map { uc } @output; | ||
| 157 | print "got some bits of decrypted data, I uppercased it : @uppercased_output\n"; | ||
| 158 | }, | ||
| 159 | the_end => sub { | ||
| 160 | # clean up | ||
| 161 | $_[HEAP]{gnupg}->destroy(); | ||
| 162 | exit(); | ||
| 163 | }, | ||
| 164 | |||
| 165 | ### These are optional but useful for diagnostic | ||
| 166 | something_on_status => sub { | ||
| 167 | my $status_fh = $_[ARG0]; | ||
| 168 | return if eof $status_fh; # nothing to report | ||
| 169 | my @status = <$status_fh>; | ||
| 170 | print STDERR "got status : @status\n"; | ||
| 171 | }, | ||
| 172 | something_on_error => sub { | ||
| 173 | my $err_fh = $_[ARG0]; | ||
| 174 | return if eof $err_fh; # nothing to report | ||
| 175 | my @errors = <$err_fh>; | ||
| 176 | print STDERR "got errors : @errors\n"; | ||
| 177 | }, | ||
| 178 | something_on_logger => sub { | ||
| 179 | my $logger_fh = $_[ARG0]; | ||
| 180 | return if eof $logger_fh; # nothing to report | ||
| 181 | my @logger = <$logger_fh>; | ||
| 182 | print STDERR "got logger : : @logger\n"; | ||
| 183 | }, | ||
| 184 | } | ||
| 185 | ); | ||
| 186 | |||
| 187 | POE::Kernel->run(); | ||
| 188 | exit; | ||
| 189 | |||
| 190 | |||
| 191 | |||
| 192 | # Example 2 : | ||
| 193 | # encrypt a file bits by bits asynchronously | ||
| 194 | |||
| 195 | use POE qw(Wheel::GnuPG); | ||
| 196 | |||
| 197 | POE::Session->create( | ||
| 198 | inline_states => { | ||
| 199 | _start => sub { | ||
| 200 | |||
| 201 | # let's say we have a file we want to crypt | ||
| 202 | use IO::File; | ||
| 203 | $_[HEAP]{unencrypted_fh} = IO::File->new('file.txt', 'r'); | ||
| 204 | |||
| 205 | my $gnupg = POE::Wheel::GnuPG->new( | ||
| 206 | ready_to_input_data => 'ready_to_input_data', | ||
| 207 | something_on_stdout => 'something_on_stdout', | ||
| 208 | something_on_status => 'something_on_status', | ||
| 209 | something_on_error => 'something_on_error', | ||
| 210 | something_on_logger => 'something_on_logger', | ||
| 211 | end_of_process => 'the_end', | ||
| 212 | ); | ||
| 213 | $_[HEAP]{gnupg} = $gnupg; | ||
| 214 | $gnupg->options->hash_init( armor => 1, | ||
| 215 | homedir => '/Users/dams/.gnupg' ); | ||
| 216 | # we are encrypting against this GPG key | ||
| 217 | $gnupg->options->push_recipients( 'foo@bar.org' ); | ||
| 218 | $gnupg->options->meta_interactive( 0 ); | ||
| 219 | $gnupg->encrypt(); | ||
| 220 | }, | ||
| 221 | ready_to_input_data => sub { | ||
| 222 | my $input_fh = $_[ARG0]; | ||
| 223 | my $unencrypted_fh = $_[HEAP]{unencrypted_fh}; | ||
| 224 | if (eof($unencrypted_fh)) { | ||
| 225 | # it's the end of the unencrypted file | ||
| 226 | $_[HEAP]{gnupg}->finished_writing_input(); | ||
| 227 | } else { | ||
| 228 | my $line = <$unencrypted_fh>; | ||
| 229 | print $input_fh $line; | ||
| 230 | } | ||
| 231 | }, | ||
| 232 | something_on_stdout => sub { | ||
| 233 | my $stdout_fh = $_[ARG0]; | ||
| 234 | return if eof $stdout_fh; | ||
| 235 | my @output = <$stdout_fh>; | ||
| 236 | print "got some bits of encrypted output : @output\n"; | ||
| 237 | }, | ||
| 238 | the_end => sub { | ||
| 239 | $_[HEAP]{gnupg}->destroy(); | ||
| 240 | exit(); | ||
| 241 | }, | ||
| 242 | |||
| 243 | ### These are optional but useful for diagnostic | ||
| 244 | something_on_status => sub { | ||
| 245 | my $status_fh = $_[ARG0]; | ||
| 246 | return if eof $status_fh; # nothing to report | ||
| 247 | my @status = <$status_fh>; | ||
| 248 | print STDERR " got status : @status\n"; | ||
| 249 | }, | ||
| 250 | something_on_error => sub { | ||
| 251 | my $err_fh = $_[ARG0]; | ||
| 252 | return if eof $err_fh; # nothing to report | ||
| 253 | my @errors = <$err_fh>; | ||
| 254 | print STDERR " got errors : @errors\n"; | ||
| 255 | }, | ||
| 256 | something_on_logger => sub { | ||
| 257 | my $logger_fh = $_[ARG0]; | ||
| 258 | return if eof $logger_fh; # nothing to report | ||
| 259 | my @logger = <$logger_fh>; | ||
| 260 | print STDERR "got logger : : @logger\n"; | ||
| 261 | }, | ||
| 262 | } | ||
| 263 | ); | ||
| 264 | |||
| 265 | POE::Kernel->run(); | ||
| 266 | |||
| 267 | |||
| 268 | =head1 DESCRIPTION | ||
| 269 | |||
| 270 | =cut | ||
| 271 | |||
| 272 | use strict; | ||
| 273 | use warnings; | ||
| 274 | |||
| 275 | use POE; | ||
| 276 | use IO::Handle (); | ||
| 277 | |||
| 278 | use parent qw(GnuPG::Interface); | ||
| 279 | |||
| 280 | my %signal_type_to_fhname = ( | ||
| 281 | ready_to_input_data => 'stdin', | ||
| 282 | ready_to_input_passphrase => 'passphrase', | ||
| 283 | something_on_stdout => 'stdout', | ||
| 284 | something_on_status => 'status', | ||
| 285 | something_on_error => 'stderr', | ||
| 286 | something_on_logger => 'logger', | ||
| 287 | ); | ||
| 288 | |||
| 289 | sub new { | ||
| 290 | my $class = shift; | ||
| 291 | my %params = @_; | ||
| 292 | |||
| 293 | my %_struct = (); | ||
| 294 | foreach my $signal_type (keys %signal_type_to_fhname) { | ||
| 295 | if (exists $params{$signal_type}) { | ||
| 296 | my $signal_name = delete $params{$signal_type}; | ||
| 297 | my $fh_name = $signal_type_to_fhname{$signal_type}; | ||
| 298 | $_struct{$fh_name} = [ IO::Handle->new(), $signal_name ]; | ||
| 299 | } | ||
| 300 | } | ||
| 301 | |||
| 302 | my $end_signal = delete $params{end_of_process}; | ||
| 303 | |||
| 304 | my $self = $class->SUPER::new(%params); | ||
| 305 | $self->{_struct} = \%_struct; | ||
| 306 | $self->{_handles} = GnuPG::Handles->new( map { $_, $self->{_struct}->{$_}->[0] } keys %{$self->{_struct}} ); | ||
| 307 | if (defined $end_signal) { | ||
| 308 | $self->{_end_signal} = $end_signal; | ||
| 309 | } | ||
| 310 | return $self; | ||
| 311 | } | ||
| 312 | |||
| 313 | sub destroy { | ||
| 314 | my ($self) = @_; | ||
| 315 | foreach (values %{$self->{_struct}}) { | ||
| 316 | my $fh = $_->[0]; | ||
| 317 | $poe_kernel->select_read( $fh ); | ||
| 318 | close $fh; | ||
| 319 | } | ||
| 320 | return; | ||
| 321 | } | ||
| 322 | |||
| 323 | sub wrap_call { | ||
| 324 | my $self = shift; | ||
| 325 | # pass our handles, but can be overwritten | ||
| 326 | my $pid = $self->SUPER::wrap_call( | ||
| 327 | handles => $self->{_handles}, | ||
| 328 | @_, | ||
| 329 | ); | ||
| 330 | while ( my ($fh_name, $s ) = each %{$self->{_struct}}) { | ||
| 331 | my ($handle, $signal_name) = @$s; | ||
| 332 | if ($fh_name =~ /^(?:stdin|passphrase)$/) { | ||
| 333 | $poe_kernel->select_write( $handle, $signal_name ); | ||
| 334 | } else { | ||
| 335 | $poe_kernel->select_read( $handle, $signal_name ); | ||
| 336 | } | ||
| 337 | } | ||
| 338 | $poe_kernel->sig_child($pid, $self->{_end_signal}); | ||
| 339 | return $pid; | ||
| 340 | } | ||
| 341 | |||
| 342 | sub finished_writing_passphrase { shift->_finished_writing('passphrase') } | ||
| 343 | sub finished_writing_input { shift->_finished_writing('stdin') } | ||
| 344 | |||
| 345 | sub _finished_writing { | ||
| 346 | my ($self, $fh_name) = @_; | ||
| 347 | my $fh = $self->{_struct}->{$fh_name}->[0]; | ||
| 348 | $poe_kernel->select_write($fh); | ||
| 349 | close $fh; | ||
| 350 | return; | ||
| 351 | } | ||
| 352 | |||
| 353 | 1; |