Ubuntu Manpage: Text::MicroMason::Safe - Compile all Templates in a Safe Compartment

Provided by: libtext-micromason-perl_2.23-5_all

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 evaluate 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.

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO