/ 
Tie-SecureHash-1.10
River stage one • 1 direct dependent • 1 total dependent
/ Tie::SecureHash

NAME

Tie::SecureHash - A tied hash that supports namespace-based encapsulation

VERSION

This document describes version 1.00 of Tie::SecureHash, released December 3, 1998

CAVEAT

The original author of this module doesn't use it any more and it's not recommended for new code. Use Moo or Moose instead. Newer (2015) releases of this module are here to deal with unintended consequences of the original implementation, and code that's not easily moved away to more modern constructs.

SYNOPSIS

    use Tie::SecureHash;

    # CREATE A SECURE HASH

	my %hash;
	tie %hash, Tie::SecureHash;

    # CREATE A REFERENCE TO A SECURE HASH (BLESSED INTO Tie::SecureHash!)

	my $hashref = Tie::SecureHash->new();

    # CREATE A REFERENCE TO A SECURE HASH (BLESSED INTO $some_other_class)

	my $hashref = Tie::SecureHash->new($some_other_class);

    # CREATE NEW ENTRIES IN THE HASH

	package MyClass;

	sub new
	{
		my ($class, %args) = @_
		my $self = Tie::SecureHash->new($class);

		$self->{MyClass::public}     = $args{public};
		$self->{MyClass::_protected} = $args{protected};
		$self->{MyClass::__private}  = $args{private};

		return $self;
	}

    # SAME EFFECT, EASIER SYNTAX...

	package MyClass;

	sub new
	{
		my ($class, %args) = @_
		my $self = Tie::SecureHash->new($class,
				public     => $args{public},
				_protected => $args{protected},
				__private  => $args{private},
				);

		return $self;
	}


    # ACCESS RESTRICTIONS ON ENTRIES

	package MyClass;

	sub print_attributes
	{
	    my $self = $_[0];
					# OKAY? (ACCESSIBLE WHERE?)

	    print $self->{public};	#  YES  (ANYWHERE)
	    print $self->{_protected};	#  YES  (ONLY IN MyClass HIERARCHY)
	    print $self->{__private};	#  YES  (ONLY IN MyClass)
	}


	package SonOfMyClass; @ISA = qw( MyClass );

	sub print_attributes
	{
	    my $self = $_[0];
					# OKAY? (ACCESSIBLE WHERE?)

	    print $self->{public};	#  YES  (ANYWHERE)
	    print $self->{_protected};	#  YES  (ONLY IN MyClass HIERARCHY)
	    print $self->{__private};	#  NO!  (ONLY IN MyClass)
	}


	package main;

	my $object = MyClass->new();
					# OKAY? (ACCESSIBLE WHERE?)

	print $object->{public};	#  YES  (ANYWHERE)
	print $object->{_protected};	#  NO!  (ONLY IN MyClass HIERARCHY)
	print $object->{__private};	#  NO!  (ONLY IN MyClass)


    # DEBUGGING

	$object->Tie::SecureHash::debug();

DESCRIPTION

The problem

In Perl objects are just variables that have been associated with a particular package. Typically they're blessed hashes, or arrays, or scalars; occasionally they're darker mysteries, like typeglobs or closures. And because they are usually just standard variables, the attribute values they store are freely accessible everywhere in a program.

So, even if the object has accessor methods to control how the object's attributes are manipulated:

$obj->set_name("ob1");
print $obj->get_name();

it's still possible to access the data directly:

$obj->{_name} = "ob1";
print $obj->{_name};

But if the get_name and set_name methods do anything other than simply retrieve and set the underlying hash entryfor example, checking the assigned value's validity, or logging retrievalsthen directly accessing the data in this way may introduce subtle bugs into the program.

In practice, this lack of a built-in encapsulation mechanism rarely seems to be a problem in Perl. Most object-oriented Perl programmers use hashes as the basis of their objects, and get by quite happily with the principle of "encapsulation by good manners". The lack of protection for attribute values doesn't matter because users of a class either respect the official interface of its objects (i.e. their methods), or they're smart enough to get away with poking around inside an object without breaking anything.

The only problem is that this culturally enforced encapsulation doesn't scale very well. It's fine for a few hundred lines of code written by a single programmer, but is less successful when the code is tens of thousands of lines long and developed by a group of people. Even if the entire team can be trusted to maintain sufficient programming discipline and to consistently respect the notional encapsulation of attributes (a dubious proposition), accidents and mistakes will happen. Especially in rarely used parts of the system.

Moreover, deliberate decisions to circumvent the conventions of encapsulation are rarely documented adequately, leading to problems much later in the development cycle. For example, consider a notionally "private" attribute of an object, which for efficiency reasons is accessed directly in an obscure part of a large system. If the implementation of the object's class changes, that attribute may cease to exist. In a more static language, this would cause an error message to be generated when next some external code attempts to access the (now non-existent) attribute. However, Perl's autovivification of hash entries will silently "recreate" the former attribute whenever it's accessed. The direct access operation proceeds, but now it retrieves or modifies a "phantom" attribute. Bugs such as this can be painfully difficult to diagnose and track down, especially if the original programmer has moved on by the time the problem is discovered.

Most object-oriented languages provide encapsulation that comes in varying strengths. For example, in C++ and Java, object and class data members can be declared as "public", "protected", or "private". "Public" attributes are available everywhere, "protected" attributes are restricted to a particular class hierarchy, and "private" attributes are only visible to the current class. Likewise, attributes in Eiffel can be given an export list to control which other classes can access them.

In contrast, other Perl encapsulation techniques (encapsulation via closures, and the "Flyweight" patter -- see perltoot and Object Oriented Perl) are inherently "all-or-nothing" propositions. Every attribute is completely encapsulated from the rest of the program. In C++/Java terms, they're all "private"; in Eiffel terms, none of them is "exported". It's up to the accessor subroutines to provide the necessary logic (i.e. die unless $public{$attr} || caller eq $class) to grant different levels of access. And, of course, this logic has to be manually coded in each encapsulating closure.

A more significant drawback is that these techniques are moderately hard to understand and to code correctly, particularly by beginners, who probably benefit most from proper encapsulation. Both techniques are based on the closure properties of Perl subroutines, which are not well understood by many programmers. Both are most efficiently implemented using relatively obscure code, which reduces the maintainability of the resulting classes.

All in all, the costs of building encapsulated classes seem to outweigh the benefits. It's hardly surprising that, as elegant as they are, such classes are used so rarely. What's really needed is a mechanism that will allow objects to be implemented in the usual way (i.e. by blessing hashes) and yet enable the implementer to designate some of the attributes of the resulting objects as "protected" or "private".

A limited-access hash

The Tie::SecureHash module does just that. Hashes that are tied to it continue to provide most of the behaviours of a normal hash, but also allow their keys to be fully qualifiedas if they were independent package variables. The module then uses these key qualifiers to restrict the accessibility of the corresponding entries in a tied hash.

A Tie::SecureHash object (or securehash) can be created by explicitly tie'ing an existing hash:

my %securehash;
tie %securehash, Tie::SecureHash;

or by calling the module's constructor method:

my $securehash_ref = Tie::SecureHash->new();

The constructor version returns a reference to an anonymous hash that has been tied to the Tie::SecureHash package, and which has also been blessed into the Tie::SecureHash class.

Either way, a securehash acts like a regular hash, and provides:

  • access to individual entries using the normal hash access syntaxes: $securehash{$key} or $securehash_ref->{$key},

  • iteration through the entire hash: each %securehash,

  • lists of keys and values that it currently contains: keys %securehash}, values %{$securehash_ref},

  • existence checks for entries: exists $securehash_ref->{$key},

The module provides object methods corresponding to each of these operations: $securehash_ref->values(), $securehash_ref->each(), $securehash_ref->exists($key), etc.

Securehashes also support deletion of individual entries and direct assignment, with some limitations.

Building objects from securehashes

When using a securehash as the basis of an object (i.e. blessing it in some class's constructor), it's tedious to have to create the hash, tie it, and then bless it as well:

sub MyClass::new {
	my $class = ref($_[0]) || $_[0];
	tie my %hash, Tie::SecureHash;
	my $self = bless \%hash, $class;

	# initialization of attrs here
		
	return $self;
}

Because securehashes are principally intended as object implementations, the Tie::SecureHash module makes process easier by providing the method Tie::SecureHash::new. When called with a single argument, this method creates a new securehash (i.e. ties an ordinary anonymous hash to the Tie::SecureHash package) and then blesses it into the class named by argument (or into the same class as the argument, if it's an object reference). That simplifies MyClass::new to this:

sub MyClass::new {
	my $self = Tie::SecureHash->new($_[0]);
		
	# initialization of attrs here
		
	return $self;
}

Declaring securehash entries

Both versions of MyClass::new shown above leave space for initialization. That's because the various entries of a securehash have to be explicitly "declared" before they can be used. In other words, securehash entries aren't autovivifying.

This may seem inconvenient at first, but it actually saves an inordinate amount of time and effort tracking down "spelling bugs" like this:

package Disk::Recovery;

sub new {
	my ($class, @files) = @_;
	bless {
		_retrieved  => [ @files ],
		_attempts   => 0,
		_wierd_data => undef,
	}, $class;
}

sub report {
	print "Made $self->{_attempts} attempts to recover:\n";
	print "\t$_\n" foreach (@{self->{retreived}})
	print "Failed (weird data)\n" if $self->{_weird_data};
}

Unlike the regular hash in the above example, the entries of a securehash can't be accessed until they've been "created". A specific entry is created by referring to it using a qualified key, which is a key string consisting of any characters except ':', preceded by a standard Perl package qualifier. The following table illustrates some typical qualified keys:

Qualified key		Actual key	Qualifier
=============		==========	=========
'Class::key		'key'		'Class::'
'Class::a key'		'a key',	'Class::'
'My::CD::_tracks'	'_tracks'	'My::CD::'
'Railway::_tracks'	'_tracks'	'Railway::'
'Crypt::__passwd'	'__passwd'	'Crypt::'
'main::key_berm'	'key_berm'	'main::'
'::key_berm'		'key_berm'	'main::'

Each qualifier indicates the package that "owns" the key. Hence, the first two keys above are owned by class Class and the last two by the main package.

Qualified keys that have the same key but different qualifiers (for example, 'Railway::_tracks' and 'My::CD::_tracks') are treated as being distinct, even if they label two entries in the same securehash.

Typically, entries in a securehash are created by referring to their fully-qualified names at some point in a class's constructor:

	sub MyClass::new {
		my $self = Tie::SecureHash->new($_[0]);
			
		$self->{MyClass::attr1}  = $_[1];
		$self->{MyClass::_attr2} = $_[2];
		$self->{MyClass::__attr3}= $_[3];
			
		return $self;
	}

In this case, the entries with the keys "attr1", "_attr2", and "__attr3" are all "owned" by the class MyClass. For reasons that will be made clear in the next section, an entry must be declared within its owner's package. In practice, that means that the qualifier for any entry declaration will always be the name of the current package, as in the example above.

Key qualifiers are only required during the creation of entries (and occasionally to resolve ambiguities). After the declarations, they can usually be ignored:

	sub MyClass::set_attr2 {
		my ($self, $newval) = @_;
		$self->{_attr2} = $newval if @_>1;
	}

though using the fully qualified key is always acceptable:

	sub MyClass::set_attr2 {
		my ($self, $newval) = @_;
		$self->{MyClass::_attr2} = $newval if @_>1;
	}

Easier initialization

It's annoying to have to repeat the same class name when declaring each attribute in the constructor, so Tie::SecureHash allows Tie::SecureHash::new to take extra parameters which declare attributes without individual qualifiers. Or rather, the qualifier for each attribute passed to new is assumed to be the class name that is passed as the first argument.

For example, the constructor for MyClass could also be written like this:

	sub MyClass::new {
		my $self = Tie::SecureHash->new($_[0],
						attr1   => $_[1],
						_attr2  => $_[2],
						__attr3 => $_[3],
		);
	}

This is the only way that entries can be declared without an explicit qualifier.

Access constraints

Securehashes use an extension of a common Perl custom -- underscoring -- to determine the accessibility of their various entries. In Perl, a leading underscore in the key of an entry suggests that the particular entry is "not for public use". Tie::SecureHash formalizes that idea by treating any entry whose key begins with a single underscore as being inaccessible outside its owner's class hierarchy. In other words, an underscored key indicates a "protected" method.

Tie::SecureHash treats keys that begin with two (or more) underscores even more carefully. The entries for such keys are only accessible from code in their owner's package and in the same file as they were originally declared. In other words, a double underscored key indicates a "private" and "pseudo-lexical" key.

The only other possibility is a key with no leading underscore. Predictably, no underscore indicates that an entry is "public" and universally accessible.

This is reasonably consistent with existing Perl conventions about key naming, but the important difference is that securehashes enforce the convention at run-time. If a doubly-underscored key is accessed outside its owner's package or its declaration file, an exception is immediately thrown. The same thing happens if a singly-underscored key is accessed outside its native class hierarchy. For example:

        package Derived::Class;
        @ISA = qw( MyClass );
        
	sub dump {
		my ($self) = @_;
		print $self->{attr1};    # okay
		print $self->{_attr2};   # okay
		print $self->{__attr3};  # error
	}

The first print is okay because the lack of a leading underscore indicates that 'attr1' is a public attribute, accessible from any package. The second print is okay too because the single leading underscore indicates that '_attr2' is a protected attribute, accessible for any package in Class's hierarchy. But the last print tries to access an attribute with two leading underscores, causing the exception:

Private key 'MyClass::__attr3' of tied SecureHash
is inaccessible from package Derived::Class.

Likewise, an access attempt such as:

package main;
my $obj = MyClass->new();
print $obj->{_attr2};

would die with the message:

Protected key 'MyClass::_attr2' of tied SecureHash
is inaccessible from package main

(unless main inherits from MyClass, of course).

Access constraints also apply to the functions each, keys, values, and delete, when applied to securehashes. A key will only be iterated, listed, or deleted if it is accessible at the point where the operation is invoked.

This also has implications for direct assignment to a securehash. A statement such as:

%securehash = ();

is equivalent to a series of delete operations, and hence will only succeed if every key in the securehash is accessible from that point. If any key is inaccessible, an exception will be thrown (and the securehash will be unchanged).

Another difficulty with reassigning a securehash is that every new key being assigned must be appropriately qualified with the name of the current package. In other words, the standard securehash entry declaration rules still apply. For example:

        package SomeClass;
	%securehash = (
		attr1 => $val1,
		attr2 => $val2,
	);

will throw an exception because the keys 'attr1' and 'attr2' don't exist in the newly-cleared %securehash. To successfully reinitialize the securehash, each new key requires a fully qualified name:

        package SomeClass;
	%securehash = (
		SomeClass::attr1 => $val1,
		SomeClass::attr2 => $val2,
	);

Ambiguous keys in a securehash

The ability to access securehash entries by unqualified keys is an important convenience. It can also be a useful programming technique when using inheritance, since it provides "polymorphic" attributes (see below). But it creates problems under some circumstances.

The convenience aspect is obvious. Requiring that securehash keys always be fully qualified would flout the cardinal virtue of Laziness. No-one would want to use a securehash if they always had to write $self->{MyClass::__attr3}, instead of just $self->{__attr3}. In most cases, each attribute of an object will be uniquely named, so each securehash will contain only a single matching unqualified key. The qualifier would be redundant and annoying.

Inheritance, however, brings a difficulty known as the "data inheritance problem". When one class inherits from another, it's all too easy to accidentally reuse the name of a base class attribute in a derived class. For example:

        package Settable;
        $VERSION = 1.00;        #uses normal hashes
        
	sub new {
		my ($class, $is_set) = @_;
		my $self = {_set => $is_set};
		bless $self, $class;
	}
        
	sub set {
		my ($self) = @_;
		# access Settable's _set attr
		$self->{_set} = 1;
	}
        
        package Set;
        @ISA = qw( Settable );
        
	sub new {
		my ($class, %items) = @_;
		my $self = $class->SUPER::new();
		$self->{_set} = { %items }
		# Oops!
	}
        
	sub list {
		my ($self) = @_;
		print keys %{$self->{_set}};
		# Err...was that Set's '_set'
		# or Settable's '_set'?
	}

The problem is both Settable and Set want to use a '_set' entry, but Set objects have to share the same hash as their Settable base parts, and hence there can be only one such entry.

The use of qualified keys in a securehash solves the problem (in fact, it's the same solution as suggested in Perl Cookbook):

        package Settable;
        $VERSION = 2.00;        #uses securehashes
        
	sub new {
		my ($class, $set) = @_;
		my $self = Tie::SecureHash->new($class);
		$self->{Settable::_set} = $set;
		return $self;
	}
        
        
	sub set {
		my ($self) = @_;
		$self->{Settable::_set} = 1;
		# Definitely Settable's _set
	}
        
        package Set;
        @ISA = qw( Settable );
        
	sub new {
		my ($class, %items) = @_;
		my $self = $class->SUPER::new();
		$self->{Set::_set} = { %items };
		# Different key so no "collision"
	}
        
	sub list {
		my ($self) = @_;
		print keys %{$self->{Set::_set}};
		# Definitely Set's _set
	}

But securehashes are even smarter than that. Any qualifier/key combination that is unique creates an entry whose unqualified key is unique within its owner's namespace. So it's also possible to write:

        package Settable;
        $VERSION = 3.00;        #uses securehashes
        
	sub new {
		my ($class, $set) = @_;
		my $self = Tie::SecureHash->new($class);
		$self->{Settable::_set} = $set;
		return $self;
	}
        
	sub set {
		my ($self) = @_;
		$self->{_set} = 1;
		# Definitely Settable's '_set' (!)
	}
        
        package Set;
        @ISA = qw( Settable );
        
	sub new {
		my ($class, %items) = @_;
		my $self = $class->SUPER::new();
		$self->{Set::_set} = { %items };
		# Different key so no "collision"
	}
        
	sub list {
		my ($self) = @_;
		print keys %{$self->{_set}};
		# Definitely Set's _set (!)
	}

The unqualified keys are unambiguous because the Tie::SecureHash module keeps track of where an access was requested, and works out which key was intended from that context. When the Set::list accesses the '_set' key, it probably wants the entry for 'Set::_set', not 'Settable::_set'. The securehash is aware of the context of the access and returns the correct attribute.

Another way of looking at it is to think of securehash entries that are defined in a base class as being "hidden" by derived class entries of the same name (just like inherited attributes are in most other object-oriented languages). Of course, if the inherited entry is needed in a derived class method, it can still be accessed by fully qualifying it:

	sub Set::list {
		my ($self) = @_;
		print keys %{$self->{_set}}
		if $self->{Settable::_set};
	}

That's not to say that a securehash can always correctly guess the intended entry for an unqualified key. Consider the following two classes:

        package Chemical;
        
	sub new {
		my ($class, $chemname) = @_;
		Tie::SecureHash->new($class, name => $chemname);
	}
        
        package Medicine;
        @ISA = qw( Chemical );
        
	sub new {
		my ($class, $medname, $chemname) = @_;
		my $self = Chemical->new($class, $chemname);
		$self->{Medicine::name} = $medname;
		return $self;
	}

Within the Chemical class, the unqualified public key 'name' will always be assumed to be referring to 'Chemical::name'. Similarly, inside any of Medicine's methods, the same key is unambiguously resolved to 'Medicine::name'. But what about accesses from the main package? For example:

package main;
my $medicine =  Medicine->new("Dydroxifen","dihydrogen oxide");
print $medicine->{name};

Since the 'name' entry isn't being accessed from a method of either class, there's no way to decide which entry was intended. Tie::SecureHash resolves the ambiguity by immediately throwing an exception.

The solution is to explicitly qualify any ambiguous case:

print $medicine->{Medicine::name};

Problems of a similar type occur with protected keys as well, whenever a class inherits from two or more classes. If both classes use a protected attribute of the same name then, in a class than derives from both, it's impossible to tell which inherited attribute was intended:

        package Dessert::Topping;
        
        sub new { Tie::SecureHash->new($_[0], _shaken => 0) }
        
        sub shake { $_[0]->{_shaken} = 1 }
        
        
        package Floor::Wax;
        
        sub new { Tie::SecureHash->new($_[0], _shaken => 0 ) }
        
        sub shake { $_[0]->{_shaken}++ }
        
        
        package Jiffy::Whip;
        @ISA = qw(Dessert::Topping Floor::Wax);
        
        sub shaken { $_[0]->{_shaken} }     # Dessert::Topping's '_shaken'
					    # orFloor::Wax's '_shaken'?

Once again, since it can't decide which of the two attributes was intended, Tie::SecureHash simply throws an exception.

Debugging a securehash

In a more complicated hierarchy than the ones shown above, ambiguities can be quite difficult to detect and defuse. The Tie::SecureHash module provides a method (named debug) that can be called to dump the contents of a securehash to STDERR. The debug method can be called on any securehash -- regardless of the class into which it's been blessed -- with an explicit method call:

	sub Jiffy::Whip::shaken {
		my ($self) = @_;
		$self->Tie::SecureHash::debug();   # Find the source...
		return $self->{_shaken};           # ...of this problem:
	}

Tie::SecureHash::debug reports the current location details (package, file, line and subroutine) and the key and value of each entry of the securehash, categorized by owner. More importantly, debug reports the accessibility of each entry at the point where it was called (either "accessible", "inaccessible", or "ambiguous") and explains why.

More Debugging

Sometimes you want to disable Tie::SecureHash's features. See the CPAN module Tie::InSecureHash for one approach.

"Fast" securehashes

Securehashes provide an easy means of controlling the accessibility of object attributes on a per-attribute basis. Unfortunately, that ease and flexibility comes at a cost. For a start, accessing the entries of any kind of tied hash is significantly slower that for untied hashes, often taking 5 to 10 times as long per access. On top of that performance hit, securehashes have to perform some moderately expensive tests (involving the Universal::isa subroutine) before they can grant access to an entry. These tests can double the cost again, so accesses to securehashes are often 10 and 20 times slower than to untied hash. That makes the use of securehashes impractical in most production code.

Fortunately, production code doesn't actually need the security of encapsulation. That's because all that checking of access restrictions is only actually required when a piece of code incorrectly attempts to violate those restrictions. Since production code is always thoroughly tested (ahem!), such bugs will have been caught and eliminated, so the checks are redundant. In other words, if no one can ever break the law, you no longer need any police to enforce it.

Thus, the solution is to develop the application using Tie::SecureHash to enforce proper encapsulation, test it thoroughly to ensure that there are no improper accesses anywhere in the code, and then optimize the final code by converting every securehash to a normal hash.

Because a securehash's interface mimics the interface of a regular hash, converting from securehashes to the regular kind is surprisingly easy. It's not necessary to change any of the code that accesses a securehash, only the code that creates it. In fact, that's exactly what encapsulation is all about: hiding implementation details behind a standard interface so that client code doesn't have to worry when those details change.

Of course, in the typical large application where encapsulation is most useful, hunting for every situation where a securehash is created and then replacing it with a regular hash could still be time-consuming and error-prone. Fortunately, even that isn't necessary.

Tie::Securehash provides a special "fast" mode, in which a call to Tie::SecureHash::new returns a reference to an ordinary hash, rather than to a securehash. Hence, in "fast" mode, there's no need to replace any code like:

$self = Tie::SecureHash->new($_[0]);

because it correctly adjusts its behaviour automatically.

Of course, that doesn't solve the problem of any "raw" tie-ing:

tie %$self, Tie::SecureHash;

but that's just another reason to use Tie::SecureHash::new instead. Indeed, in "fast" mode, Tie::SecureHash generates a warning whenever a raw tie such as this is used.

"Fast" mode is enabled by importing the entire module with an extra argument:

use Tie::SecureHash "fast";

"Strict" securehashes

This "develop-with-restrictions-then-run-without-them" approach works well, but there are two caveats: Tie::SecureHash::new must always be used to create securehashes, and unqualified keys can never be used to access them.

The need to use Tie::SecureHash::new was explained above: Tie::SecureHash::new knows about "fast" mode and can adjust for it, but the in-built tie function doesn't and can't.

The second caveat imposes a more significant restriction. One of the useful features of a securehash is that, once an entry has been declared with its full qualifier, any code can refer to it without the qualifier and expect the securehash to do the right thing in all unambiguous cases. However, when the securehash is replaced with a regular hash, that "do what I mean" intelligence disappears. That can lead to subtle bugs, because regular hashes autovivify and will happily create unrelated entries when both qualified and unqualified versions of a key are used.

These two restrictions are not particularly onerous, but they can be difficult to apply consistently in a large application. To make conversion to "fast" mode easier, Tie::SecureHash offers another mode, called "strict". Like "fast" mode, this mode can be invoked by importing the module with the appropriate argument:

use Tie::SecureHash "strict";

In "strict" mode, securehashes control access in their normal way, except that they also produce warnings whenever a hash is explicitly tied to Tie::SecureHash, and whenever an unqualified key is used to access a securehash. Thus, code that uses securehashes and runs without warnings in "strict" mode is guaranteed to have the same behaviour in "fast" mode.

'Dangerous' securehashes

Dangerous mode is an experimental mode where you get much of the speedup with safe mode but where your tests aren't good enough to make fast mode reliable. If you start in strict and dangerous mode you'll get warnings about problematic entries. I would imagine if the code is 'strict dangerous' warnings clean, then you have a good chance that fast mode will work. Dangerous will not work correctly in some multiple inheritance scenarios, it's very much up to the existing structure of your code. This mode is called 'dangerous' for a reason. Caveat emptor.

You can also pass in 'loud' as well as dangerous for the ultimate in logging your SecureHash's behaviour. 'loud' also implies 'strict'.

The formal access rules

The access rules for a securehash are designed to provide secure encapsulation with minimal inconvenience and maximal intuitiveness. However, to produce this appearance of intelligence, the formal access rules are quite complicated...

All entries

  • No entry for an unqualified key is autovivifying. Each entry must be declared before it's used. Qualified keys do autovivify their entry, so an entry may be declared as part of its initial use.

  • The key of each entry must be explicitly qualified (in the form "owner::key") when entry is declared.

  • An entry is owned by the package whose name was used as the explicit qualifier in its declaration.

  • Entries must be declared within of their owner's package.

  • An unqualified key is always interpreted as referring to the key owned by the current package, if such a key exists, no matter how many other accessible matching keys the hash may also contain.

  • Otherwise, accesses through an unqualified key throw an exception if the number of accessible matching keys in the securehash is not 1 (either "key does not exist" if the number is zero, or "key is ambiguous" if it is greater than 1).

  • A fully qualified key is never ambiguous (though it may be non-existent, or inaccessible from a particular package).

Public entries

  • Public accessibility of entries is indicated by their unqualified key beginning with a character other than an underscore.

  • Public entries may be subsequently accessed from any package in any source file.

  • A public entry's key is ambiguous if it is not explicitly qualified, and there is not a matching key owned by the current package, and there exist two or more matching unqualified keys owned by any other packages.

Protected entries

  • Protected accessibility of entries is indicated by their unqualified key beginning with a single underscore.

  • Protected entries may subsequently be accessed from any package (P) in any source file, provided that at the point of access, P is (or inherits from) the entry's owner package (<Owner>). That is, a protected entry is accessible in any package P, where P->isa("Owner").

  • Protected keys that are declared to be owned by a given package will "hide" entries with the same unqualified key that are inherited from parent classes of that package. Any inherited entry that is hidden in this way is inaccessible from the scope of the derived class (unless accessed via a qualified key).

  • A protected key is ambiguous if it's not explicitly qualified, and there is not a matching key owned by the current package, and there exist two or more accessible matching keys owned by two or more other packages, and those other packages are inherited by the current package through two distinct inheritance paths.

Private entries

  • Private accessibility of entries is indicated by their unqualified key beginning with two or more underscores.

  • Private entries can be accessed only from within their owner's package, and only from the source file in which they were originally declared.

  • Unqualified private keys are never ambiguous. Since private entries are only ever accessible from a single class, there can be at most only one accessible matching private key.

DIAGNOSTICS

Private key %s of tied securehash inaccessible from package %s

Private keys can only be accessed from their "owner" package. An attempt was made to access a private key from some other package.

Private key %s of tied securehash inaccessible from file %s

Private keys can only be accessed from the lexical scope of the file in which they were originally declared. An attempt was made to access a private key from some lexical scope (probably another file, but perhaps an eval).

Protected key %s of tied securehash inaccessible from package %s

Protected keys can only be accessed from their "owner" package and any of its subclasses. An attempt was made to access a protected key from some package not in the owner's inheritance hierarchy.

Entry for key %s of tied securehash cannot be created from package %s

Keys must be declared from within the lexical scope of their owner's package. In other words, the qualifier for a key declaration must be the same as the current package. An attempt was made to declare a key from some package other than its owner.

Private key %s does not exist in tied securehash

Securehash keys are not autovivifying; they must be declared using a fully qualified key before they can be used. An attempt was made to access or assign to an unqualified private key (one with two leading underscores), before the corresponding fully qualified key was declared.

Protected key %s does not exist in tied securehash

Securehash keys are not autovivifying; they must be declared using a fully qualified key before they can be used. An attempt was made to access or assign to an unqualified protected key (one with a single leading underscore), before the corresponding fully qualified key was declared.

Public key %s does not exist in tied securehash

Securehash keys are not autovivifying; they must be declared using a fully qualified key before they can be used. An attempt was made to access or assign to an unqualified public key (one with no leading underscore), before the corresponding fully qualified key was declared.

Ambiguous key %s (when accessed from package %s). Could be: %s

An unqualified key was used to access the securehash, but it was ambiguous in the context. The error message lists the set of fully qualified keys that might have matched.

Invalid key %s

An attempt was made to access the securehash (or declare a key) through an improperly formatted key. This almost always means that the qualifier isn't a valid package name.

%s can't be both "strict" and "fast"

Tie::SecureHash detected that both the $Tie::SecureHash::strict and

Accessing securehash via unqualified key %s will be unsafe in 'fast' mode. Use %s::%s

This warning is issued in "strict" mode if the environment variable UNSAFE_WARN is true, and points out an access attempt which will break if the code is converted to "fast" mode.

Tie'ing a securehash directly will circumvent 'fast' mode. Use Tie::SecureHash::new instead

This warning is issued in "strict" mode, and points out an explicit tie to the Tie::SecureHash module. Hashes tied in this way will not speed up under "fast" mode.

Tie'ing a securehash directly should never happen in 'fast' mode. Use Tie::SecureHash::new instead

This warning is issued in "fast" mode, and points out an explicit tie to the Tie::SecureHash module. Hashes tied in this way will still be slow. This diagnostic can be turned off by setting $Tie::SecureHash::fast to any value other than 1.

Unable to assign to securehash because the following existing keys are inaccessible from package %s and cannot be deleted: %s

An attempt was made to assign a completely new set of entries to a securehash. Typically something like this:

%securehash = ();

This doesn't work unless all the existing keys are accessible at the point of the assignment.

REPOSITORY

https://github.com/singingfish/perl-Tie-SecureHash.git

AUTHOR

Damian Conway (damian@cs.monash.edu.au)

"Dangerous mode" and 'better' test coverage Kieren Diment <zarquon@cpan.org>

BUGS AND IRRITATIONS

There are undoubtedly serious bugs lurking somewhere in this code :-) Bug reports and other feedback are most welcome.

COPYRIGHT

  Copyright (c) 1998-2000, Damian Conway. All Rights Reserved.
This module is free software. It may be used, redistributed
and/or modified under the terms of the Perl Artistic License
     (see http://www.perl.com/perl/misc/Artistic.html)

1 POD Error

The following errors were encountered while parsing the POD:

Around line 692:

Unterminated C<...> sequence