Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MicroMason::Safe(3)   User Contributed Perl Documentation  MicroMason::Safe(3)

NAME
       Text::MicroMason::Safe -	Compile	all Templates in a Safe	Compartment

SYNOPSIS
       Instead of using	this class directly, pass its name to be mixed in:

	 use Text::MicroMason;
	 my $mason = Text::MicroMason->new( -Safe );

       Use the standard	compile	and execute methods to parse and evalute
       templates:

	 print $mason->compile(	text=>$template	)->( @%args );
	 print $mason->execute(	text=>$template, @args );

       Safe usage restricts templates from accessing your files	or data:

	 print $mason->execute(	text=>"<% qx! cat /etc/passwd !	%>" ); # dies

	 print $mason->execute(	text=>"The time	is <% time() %>." ); # dies

DESCRIPTION
       This package adds support for Safe compartments to MicroMason, allowing
       you to  restrict	the operations that a template can perform.

       By default, these safe calls prevent the	code in	a template from
       performing any system activity or accessing any of your other Perl
       code.  Violations may result in either compile-time or run-time errors,
       so make sure you	are using an eval block	or the CatchErrors trait to
       catch exceptions.

	 use Text::MicroMason;
	 my $mason = Text::MicroMason->new( -Safe );

	 $result = eval	{ $mason->execute( text	=> $template ) };

       Caution:	Although this appears to provide a significant amount of
       security	for untrusted templates, please	take this with a grain of
       salt. A bug in either this module or in the core	Safe module could
       allow a clever attacker to defeat the protection. At least one bug in
       the Safe	module has been	found and fixed	in years past, and there could
       be others.

   Supported Attributes
       safe
	   Optional reference to a Safe	compartment. If	you do not provide
	   this, one is	generated for you.

	   To enable some operations or	share variables	or functions with the
	   template code, create a Safe	compartment and	configure it before
	   passing it in as the	value of the "safe" attribute:

	     $safe = Safe->new();
	     $safe->permit('time');
	     $safe->share('$foo');

	     $mason = Text::MicroMason->new( -Safe, safe => $safe );

	     $result = eval { $mason->execute( text => $template ) };

       safe_methods
	   IMPORTANT NOTE: The "safe_methods" parameter	is deprecated and will
	   be removed in future	versions of Text::MicroMason (unless a Safe
	   and future-proof implementation can be found).  If you use this
	   parameter, you will receive a warning via carp:

	   "* WARNING: safe_methods is deprecated; please see the pod"

	   This	parameter works	correctly with sufficiently old	versions of
	   the Safe module (prior to the release of perl 5.12.1), but modern
	   versions of Safe make it impossible for a Safe compartment to run
	   any code outside the	compartment.  Even with	the object shared
	   within the Safe compartment,	there is currently no known way	to
	   call	methods	on it without defining the whole class within the
	   compartment (which isn't safe).

	   If anyone has an appropriately safe solution	that will allow
	   "safe_methods" to work, please submit a patch to the	module
	   maintainer.	Also see t/32-safe.t for tests related to
	   "safe_methods" that are currently being skipped.

	   The following pod is	provided for legacy purposes only.  It is
	   strongly recommended	that you do not	use this method.  It is	no
	   longer allowed to call methods from within a	"Safe" template,
	   because it isn't actually safe.

	   A space-separated string of methods names to	be supported by	the
	   Safe::Facade.

	   To control which Mason methods are available	within the template,
	   pass	a "safe_methods" argument to new() followed by the method
	   names in a space-separated string.

	   For example,	to allow templates to include other templates, using
	   $m->execute or the "<& file &>" include syntax, you would need to
	   allow the execute method. We'll also	load the TemplateDir mixin
	   with	strict_root on to prevent inclusion of templates from outside
	   the current directory.

	     # safe_methods is DEPRECATED, please see above
	     $mason = Text::MicroMason->new( -Safe, safe_methods => 'execute',
					     -TemplateDir, strict_root => 1 );

	   If you're combining this with the Filters mixin, you'll also	need
	   to allow calls to the filter	method;	to allow multiple methods,
	   join	their names with spaces:

	     # safe_methods is DEPRECATED, please see above
	     $mason = Text::MicroMason->new( -Safe, safe_methods => 'execute filter',
					     -TemplateDir, strict_root => 1,
					     -Filters );

   Private Methods
       eval_sub()
	   Instead of the eval() used by the base class, this calls reval() on
	   a Safe compartment.

       safe_compartment()
	   Returns the Safe compartment	passed by the user or generates	a new
	   one.

       safe_facade()
	   Generates an	instance of the	Safe::Facade equipped with only	the
	   methods listed in the safe_methods attribute.

   Private Safe::Facade	class
       Code compiled in	a Safe compartment only	has access to a	limited
       version of the template compiler	in the $m variable, and	can not	make
       changes to the attributes of the	real MicroMason	object.	This limited
       object is an instance of	the Text::MicroMason::Safe::Facade class and
       can only	perform	certain	pre-defined methods.

       new()
	   Creates a new hash-based instance mapping method names to
	   subroutine references.

       facade_method()
	   Calls a named method	by looking up the corresponding	subroutine and
	   calling it.

       AUTOLOAD()
	   Generates wrapper methods that call the facade_method() for any
	   lowercase method name.

SEE ALSO
       For an overview of this templating framework, see Text::MicroMason.

       This is a mixin class intended for use with Text::MicroMason::Base.

       For distribution, installation, support,	copyright and license
       information, see	Text::MicroMason::Docs::ReadMe.

perl v5.32.1			  2011-01-13		   MicroMason::Safe(3)

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Text::MicroMason::Safe&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help