NAME
App::CamelPKI::RestrictedClassMethod - Application of the "brand" capability discipline pattern to sensitive constructors and classes.
SYNOPSIS
package App::CamelPKI::Foo;
use App::CamelPKI::RestrictedClassMethod ":Restricted";
sub new : Restricted {
my ($class) = @_;
# ...
}
App::CamelPKI::RestrictedClassMethod->lockdown(__PACKAGE__);
# Meanwhile, in a nearby piece of privileged code...
my $brand = grab App::CamelPKI::RestrictedClassMethod("App::CamelPKI::Foo");
my $object = $brand->invoke("new", @args);DESCRIPTION
App::CamelPKI::RestrictedClassMethod is an implementation of the "brand" pattern, which is of general use in capability discipline (see "Capability discipline" in App::CamelPKI::CodingStyle). It is used to ascertain that the security-sensitive class methods, especially the construction of objects that use the ambiant autority of the process, are kept secure in capability discipline style.
CAPABILITY DISCIPLINE
An instance of App::CamelPKI::RestrictedClassMethod represents the right to invoke methods marked as Restricted in an given Perl class.
"use" form
The "SYNOPSIS" formula
use App::CamelPKI::RestrictedClassMethod ":Restricted";indicates that the calling package wants to use the Restricted attribute for its methods. When affixed the Restricted on a method class (again as shown in the synopsis) prevents the execution of this method to all excepted to holder of the corresponding App::CamelPKI::RestrictedClassMethod object (see "METHODS").
CONSTRUCTORS
grab($classname)
Commences an hostile takeover on $classname. grab will only succeed once on any given $classname during the lifetime of the Perl interpreter; when it succeeds, it returns an instance of the App::CamelPKI::RestrictedClassMethod class which represents the right to invoke methods marked as Restricted in $classname.
fake_grab($classname)
Returns an object of class "App::CamelPKI::RestrictedClassMethod::FakeBrand". Unlike the real "grab", a fake_grab() has no security consequences: restricted methods are not locked down (see "lockdown"), and fake_grab() may succeed several times for the same $classname.
CLASS METHODS
grab_all
grab_all(@classnames)
Performs a call to "grab" on all classes which have not yet been grabbed; returns an associative array ("flat hash") alternating class names and the corresponding brands. This method is meant to be called at the end of the application's initialization sequence, so as to guarantee that there are no restricted constructors lingering out unprotected. It is also possible for said initialization sequence to make use of the return value, and distribute all brands by itself to the appropriate places; in this case, "grab" will not be called at all by application code.
lockdown($classname)
Prevents the restricted class methods in $classname from being called, but don't "grab" them just yet. This is optional, as grab() performs a lockdown anyway. This class method is idempotent.
METHODS
is_fake()
Returns false. See also "App::CamelPKI::RestrictedClassMethod::FakeBrand".
invoke($methname, @args)
Invokes the restricted class method named $methname with @args arguments in the package guarded by this object (that is, the $classname that was passed as an argument to "grab").
App::CamelPKI::RestrictedClassMethod::FakeBrand
This ancillary class is for fake brand objects created with "fake_grab". Instances of the class act somewhat like brands (that is, they also implement "invoke"); they are intended for testability purposes, so that code that uses App::CamelPKI::RestrictedClassMethod can use fake brands for tests, and real ones for production.
invoke($method, @args)
Invokes $method with arguments @args directly from the package the brand was constructed from (ie the $class parameter to "fake_grab").
is_fake
Returns true.