Store::Opaque(3pm)

NAME
Store::Opaque - Opaque objects to prevent accidental Dumping or appearance in stack traces

SYNOPSIS
  package MyCreditCardInfo;
  use strict; use warnings;
  use Store::Opaque;
  our @ISA = qw(Store::Opaque);

  sub get_creditcard_number {
    $_[0]->_get("ccnumber")
  }

  sub set_creditcard_number {
    $_[0]->_set("ccnumber", $_[1])
  }

  1;
  # use this like any other object...

DESCRIPTION
Before you go any further, please do realize that this module is not directly about security in the sense of preventing malicious action! It's about preventing mistakes that could turn out to be a security or compliance issue.

Consider that you have code that handles sensitive data that should never end up in your logs.

  use Carp;
  foo("This does not belong in logs");
  sub foo {
    my $super_sensitive = shift;
    this_can_die();
  }
  sub this_can_die {
    Carp::confess("Gotcha"); # stack trace
  }

If you're logging erros, you get this in your logs:

  Gotcha at /tmp/t.pl line 8
          main::this_can_die() called at /tmp/t.pl line 5
          main::foo('This does not belong in logs') called at /tmp/t.pl line 2

Great, not! Various techniques can be used to fix this. The easiest one is simply using hash-based objects to store this info and pass it around. In general, you'd pass it around as some sort of reference to prevent this.

Alas, that is easily defeated by accident if developers write stuff like this:

  sub foo {
    warn Data::Dumper->Dump(\@_); # FIXME just for debugging
    my $super_sensitive = shift;
    this_can_die();
  }

Again, there's a myriad of ways to explicitly defeat that, but I'd bring up the more powerful Data::Dump::Streamer (in conjunction with PadWalker and B::Deparse) next. Even inside out objects can accidentally be dumped if you're using Data::Dump::Streamer to dump their methods. It's becoming progressively less easy to make a mistake like the above, but why bother?

This module implements an opaque object implementation that does not suffer from these issues. Let me repeat. This isn't about hiding anything from an attacker. It's about preventing mistakes from people who have legitimate access.

Oh, and don't use this for *all* of your objects as it comes with a small memory and moderate performance overhead.

WARNING
If you do not fully understand the previous section, look elsewhere and do not use this module.

METHODS AND USAGE
You use this module by subclassing. If that doesn't work for you, you can manually import the methods in the class. If you don't know how that works, you shouldn't be doing it.

Your subclass will inherit the following methods:

  new
Simple constructor that takes no arguments. You can override is as follows:

  sub new {
    my $class = shift;
    my $self = $class->SUPER::new;
    # initialize here
    return $self;
  }

  _set
Generic setter for the stored information:

  sub set_ccinfo {
    my $self = shift;
    my $value = shift;
    $self->_set("ccinfo", $value);
  }

where "ccinfo" is the key to store the $value under. If this feel reminiscent of a hash, then that's not coincidental as the object is a hash under the hood.

You can use any string has a key that would otherwise work in a normal hash-based object.

  _get
Generic accessor for the stored information. Works just liek "_set" without the $value.

AUTHOR
Steffen Mueller, <smueller@cpan.org>

COPYRIGHT AND LICENSE
Copyright (C) 2011 by Steffen Mueller

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.1 or, at your option, any later version of Perl 5 you may have available.