NAME

POE::Wheel::GnuPG - offer GnuPG interaction through POE

VERSION

Version 0.01

DESCRIPTION

POE-Wheel-GnuPG provides a GPG interface to your POE Session. Its main benefits are that it allows asynchronous encryption and decryption, and allow you to encrypt or decrypt on the fly, without having to store data in a file, even when the data is huge.

I recommend using this module :

• when you use POE and want to use GPG.

• for security reason, when you have huge data to decrypt and you don't want it to be stored in a file

POE-Wheel-GnuPG inherits from GnuPG::Interface, and uses it for GPG actions. It has a different constructor, but apart from that, you can use POE-Wheel-GnuPG as you would use GnuPG::Interface, except for the POE signals of course.

SYNOPSIS

  # Example 0 :
  # Quickly encrypt some text

  use POE qw(Wheel::GnuPG);

  POE::Session->create(
    inline_states => {
      _start => sub {

        my $gnupg = POE::Wheel::GnuPG->new(
          ready_to_input_data => 'ready_to_input_data',
          something_on_stdout => 'something_on_stdout',
          end_of_process => 'the_end',
        );
        $_[HEAP]{gnupg} = $gnupg;

        $gnupg->options->hash_init( armor   => 1,
                                    homedir => '/home/dams/.gnupg' );
                $gnupg->options->push_recipients( 'foo@bar.org' );
        $gnupg->options->meta_interactive( 0 );

        $gnupg->encrypt();
      },

      ready_to_input_data => sub {
        my $input_fh = $_[ARG0];
        print $input_fh "This is the secret data!";

        $_[HEAP]{gnupg}->finished_writing_input();
      },

      something_on_stdout => sub {
                  my $stdout_fh = $_[ARG0];
          return if eof $stdout_fh;
          my @output = <$stdout_fh>;
          print "Received crypted data : @output\n";
      },
      the_end => sub {
          # clean up
          $_[HEAP]{gnupg}->destroy();
          exit();
      },
    }
  );

  POE::Kernel->run();
  exit;


  # Example 1 :
  # decrypt a file bits by bits asynchronously
  # without storing decrypted data on the filesystem.
  # Display decrypted data uppercased on the fly.

  use POE qw(Wheel::GnuPG);

  POE::Session->create(
    inline_states => {
      _start => sub {

        # Let's say we have a file we want to decrypt
        use IO::File;
        $_[HEAP]{encrypted_fh} = IO::File->new('encrypted_file.asc', 'r');

        # Initialize the gnupg object.
        # stdout, status, error, logger are optional
        my $gnupg = POE::Wheel::GnuPG->new(
          ready_to_input_data => 'ready_to_input_data',
          ready_to_input_passphrase => 'ready_to_input_passphrase',
          something_on_stdout => 'something_on_stdout',
          something_on_status => 'something_on_status',
          something_on_error => 'something_on_error',
          something_on_logger => 'something_on_logger',
          end_of_process => 'the_end',
        );
        # save the gnupg object
        $_[HEAP]{gnupg} = $gnupg;
        # Set some options (see GnuPG::Interface). All options are supported,
        # except 'direct'.
        $gnupg->options->hash_init( armor   => 1,
                                    homedir => '/Users/dams/.gnupg' );
        $gnupg->options->meta_interactive( 0 );
        $gnupg->decrypt();
      },

      # This is called when you can input the passphrase
      ready_to_input_passphrase => sub {
        my $passphrase_fh = $_[ARG0];
        print $passphrase_fh "my passphrase";

        # this is important to let the decryption start. It means you have
        # finished entering the passphrase.
                $_[HEAP]{gnupg}->finished_writing_passphrase();
      },

      # This is called when you can feed input data
      ready_to_input_data => sub {
        my $input_fh = $_[ARG0];
        # In our case, we get the encrypted file handle,
        # read from it and feed the gpg input with it
        my $encrypted_fh = $_[HEAP]{encrypted_fh};
        if (eof($encrypted_fh)) {
          # if it's the end of the encrypted file, we signify to the gnupg object
          # that it's the end of input
          $_[HEAP]{gnupg}->finished_writing_input();
        } else {
          # otherwise we feed the input
                  my $line = <$encrypted_fh>;
          print $input_fh $line;
        }
      },
      # gnupg returned decrypted data, do something with it
      something_on_stdout => sub {
                  my $stdout_fh = $_[ARG0];
          return if eof $stdout_fh;
          my @output = <$stdout_fh>;
          my @uppercased_output = map { uc } @output;
          print "got some bits of decrypted data, I uppercased it : @uppercased_output\n";
      },
      the_end => sub {
          # clean up
          $_[HEAP]{gnupg}->destroy();
          exit();
      },

      ### These are optional but useful for diagnostic
      something_on_status => sub {
          my $status_fh = $_[ARG0];
          return if eof $status_fh; # nothing to report
          my @status = <$status_fh>;
          print STDERR "got status : @status\n";
      },
      something_on_error => sub {
          my $err_fh = $_[ARG0];
          return if eof $err_fh; # nothing to report
          my @errors = <$err_fh>;
          print STDERR "got errors : @errors\n";
      },
      something_on_logger => sub {
                  my $logger_fh = $_[ARG0];
          return if eof $logger_fh; # nothing to report
          my @logger = <$logger_fh>;
          print STDERR "got logger : : @logger\n";
      },
    }
  );

  POE::Kernel->run();
  exit;



  # Example 2 :
  # encrypt a file bits by bits asynchronously

  use POE qw(Wheel::GnuPG);

  POE::Session->create(
    inline_states => {
      _start => sub {

        # let's say we have a file we want to crypt
        use IO::File;
        $_[HEAP]{unencrypted_fh} = IO::File->new('file.txt', 'r');

        my $gnupg = POE::Wheel::GnuPG->new(
          ready_to_input_data => 'ready_to_input_data',
          something_on_stdout => 'something_on_stdout',
          something_on_status => 'something_on_status',
          something_on_error => 'something_on_error',
          something_on_logger => 'something_on_logger',
                  end_of_process => 'the_end',
        );
        $_[HEAP]{gnupg} = $gnupg;
        $gnupg->options->hash_init( armor   => 1,
                                    homedir => '/Users/dams/.gnupg' );
        # we are encrypting against this GPG key
                $gnupg->options->push_recipients( 'foo@bar.org' );
        $gnupg->options->meta_interactive( 0 );
        $gnupg->encrypt();
      },
      ready_to_input_data => sub {
        my $input_fh = $_[ARG0];
        my $unencrypted_fh = $_[HEAP]{unencrypted_fh};
        if (eof($unencrypted_fh)) {
          # it's the end of the unencrypted file
          $_[HEAP]{gnupg}->finished_writing_input();
        } else {
                  my $line = <$unencrypted_fh>;
          print $input_fh $line;
        }
      },
      something_on_stdout => sub {
                  my $stdout_fh = $_[ARG0];
          return if eof $stdout_fh;
          my @output = <$stdout_fh>;
          print "got some bits of encrypted output : @output\n";
      },
      the_end => sub {
          $_[HEAP]{gnupg}->destroy();
                  exit();
      },

      ### These are optional but useful for diagnostic
      something_on_status => sub {
          my $status_fh = $_[ARG0];
          return if eof $status_fh; # nothing to report
          my @status = <$status_fh>;
          print STDERR " got status : @status\n";
      },
      something_on_error => sub {
          my $err_fh = $_[ARG0];
          return if eof $err_fh; # nothing to report
          my @errors = <$err_fh>;
          print STDERR " got errors : @errors\n";
      },
      something_on_logger => sub {
                  my $logger_fh = $_[ARG0];
          return if eof $logger_fh; # nothing to report
          my @logger = <$logger_fh>;
          print STDERR "got logger : : @logger\n";
      },
    }
  );

POE::Kernel->run();

DESCRIPTION