Difference between revisions of "Smarty Security Policy"

From WHMCS Documentation
Line 1: Line 1:
−
<div class="docs-alert-info"><i class="fa fa-question-circle"></i> This page describes a feature available in version 7.0 and above</div>
+
<div class="docs-alert-info"><i class="fa fa-question-circle"></i> This page describes a feature available in version 7.0 and above.</div>
−
 
+
−
WHMCS 7.0 introduces a new security hardening measure called Smarty Security Policies. WHMCS utilizes a system policy for system wide use, and a mail policy specifically for stored and dynamic email based templates.
+
WHMCS 7.0 and later use Smarty Security Policies, a security-hardening measure. WHMCS uses a system policy for system wide use and a mail policy specifically for stored and dynamic email-based templates.
−
 
+
−
The settings enforced by a WHMCS Smarty Security Policy are the same as those defined by the Smarty library itself. You can learn more about about these settings from the Smarty documentation: http://www.smarty.net/docs/en/advanced.features.tpl
+
By default, WHMCS does not define any PHP functionality restrictions for the system policy (except to honor the pre-existing <tt>php</tt> tag setting as configured at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > Security''', or '''Setup > Security''' prior to WHMCS 8.0).  All templates that use this policy are file-based (for example, themes and order forms) and require file-level access. Because of this, they are automatically implicitly trusted. Because custom themes are much more likely to have additional PHP-oriented logic, any restrictions defined by WHMCS could result in website rendering issues. It is completely within your discretion to determine whether implicit trust at the file level is invalid. You may make any appropriate restrictions for this system policy.
−
 
+
−
By default, WHMCS does not define any PHP functionality restrictions for the system policy (except to honor the pre-existing {php} tag setting as configured in Setup >> Security).  All templates that use this policy are file based (for example, themes and order forms) which require file level access and therefore are automatically implicitly trusted. Because custom themes are much more likely to have additional PHP oriented logic, any restrictions defined by WHMCS could result in website rendering issues. It is completely within your discretion to determine if implicit trust at the file level is invalid and you may make any appropriate restrictions for this system policy.
+
The mail policy restricts what PHP functionality can be used in email-based templates. The default mail policy will limit the use of [http://www.smarty.net/docs/en/language.modifiers.tpl variable modifiers] to:
−
 
+
−
The mail policy restricts what PHP functionality can be used in email based templates. The default mail policy will limit the use of variable modifiers (http://www.smarty.net/docs/en/language.modifiers.tpl) to the following:  
+
*<tt>escape</tt>
−
 
+
*<tt>count</tt>
−
*escape
+
*<tt>urlencode</tt>
−
*count
+
*<tt>ucfirst</tt>
−
*urlencode
+
*<tt>date_format</tt>
−
*ucfirst
+
−
*date_format
+
The default mail policy restricts the use of native PHP functions to:
−
 
+
−
The default mail policy restricts the use of native PHP functions to the following:
+
*<tt>isset</tt>
−
 
+
*<tt>empty</tt>
−
*isset
+
*<tt>count</tt>
−
*empty
+
*<tt>sizeof</tt>
−
*count
+
*<tt>in_array</tt>
−
*sizeof
+
*<tt>is_array</tt>
−
*in_array
+
*<tt>time</tt>
−
*is_array
+
*<tt>nl2br</tt>
−
*time
+
−
*nl2br
+
Finally, the default mail policy blocks these Smarty tags:
−
 
+
−
Finally, the default mail policy blocks these smarty tags:
+
* <tt>block</tt>
−
 
+
* <tt>function</tt>
−
* block
+
* <tt>include</tt>
−
* function
+
−
* include
+
The default mail policy will not allow any calls to static classes, fetching any data from PHP streams, or accessing any super global variables.
−
 
+
−
The default mail policy will not allow for the inclusion of any calls to static classes, fetching any data from php streams, or accessing any super global variables.  
+
If you want to redefine either the system or mail policy, you can do this by adding a <tt>$smarty_security_policy</tt> setting to <tt>configuration.php</tt>. This example limits email templates (by modifying the mail policy) to <tt>ucwords</tt> as the only native PHP function allowed, while not changing the default restrictions on variable modifiers:
−
 
+
−
If you want to redefine either the system or mail policy, you can do this by adding a $smarty_security_policy setting to your configuration.php. Here's an example that limits email templates (by modifying the mail policy) to ''ucwords'' as the only native PHP function allowed, while not changing the default restrictions on variable modifiers:
+
<div class="source-cli">
−
 
 
−
<source lang="php">
 
 
// Smarty custom email based template policy:
 
// Smarty custom email based template policy:
−
$smarty_security_policy = array(
+
<br/>$smarty_security_policy = array(
−
    'mail' => array(
+
<br/>    'mail' => array(
−
        'php_functions' => array(
+
<br/>        'php_functions' => array(
−
            'ucwords',
+
<br/>            'ucwords',
−
        ),
+
<br/>        ),
−
    ),
+
<br/>    ),
−
);
+
<br/>);
−
</source>
+
</div>
−
 
+
−
Below is an example which would restrict the use of variable modifiers so that ''strpos'' was the only variable modifier permitted in an email template, while not changing the default restrictions on php functions:
+
The example below would restrict the use of variable modifiers so that <tt>strpos</tt> was the only variable modifier permitted in an email template without changing the default restrictions on PHP functions:
−
 
+
−
<source lang="php">
+
<div class="source-cli">
 
// Smarty custom email based template policy:
 
// Smarty custom email based template policy:
−
$smarty_security_policy = array(
+
<br/>$smarty_security_policy = array(
−
    'mail' => array(
+
<br/>    'mail' => array(
−
        'php_modifiers' => array(
+
<br/>        'php_modifiers' => array(
−
            'strpos',
+
<br/>            'strpos',
−
 
+
<br/>        ),
−
        ),
+
<br/>    ),
−
    ),
+
<br/>);
−
);
+
</div>
−
</source>
+
−
 
 
 
===Using {include_php} Syntax===
 
===Using {include_php} Syntax===
−
 
+
−
Smarty has deprecated the {include_php} syntax, but WHMCS currently supports this behavior via Policies. If your template invokes & includes a PHP script by using the Smarty {include_php} syntax, the full path to the directory containing that script will need to be whitelisted in the 'trusted_dir' setting of your Policy.
+
Smarty has deprecated the <tt>{include_php}</tt> syntax, but WHMCS currently supports this behavior via Policies. If your template invokes and includes a PHP script by using the Smarty <tt>{include_php}</tt> syntax, the full path to the directory containing that script will need to be whitelisted in the <tt>trusted_dir</tt> setting of your Policy.
−
 
+
−
<source lang="php">
+
<div class="source-cli">
 
// Smarty custom email based template policy:
 
// Smarty custom email based template policy:
−
$smarty_security_policy = array(
+
<br/>$smarty_security_policy = array(
−
    'system' => array(
+
<br/>    'system' => array(
−
        'trusted_dir' => array(
+
<br/>        'trusted_dir' => array(
−
            '/path/to/folder',
+
<br/>            '/path/to/folder',
−
        ),
+
<br/>        ),
−
    ),
+
<br/>    ),
−
);
+
<br/>);
−
</source>
+
</div>
−
 
+
−
Please refer to the [http://www.smarty.net/docs/en/advanced.features.tpl#advanced.features.security/ Smarty documentation] for all possible settings and what behavior to expect when assigning array and boolean values.
+
See the [http://www.smarty.net/docs/en/advanced.features.tpl#advanced.features.security/ Smarty documentation] for all possible settings and what behavior to expect when assigning array and Boolean values.
 +
 +
=== Supported Policy Settings and Values ===
 +
 +
The settings that a WHMCS Smarty Security Policy enforces are the same as those defined by the Smarty library itself. You can learn more about about these settings from [http://www.smarty.net/docs/en/advanced.features.tpl the Smarty documentation].
 +
 +
In WHMCS version 8.0 and later, WHMCS doesn't honor Smarty's <tt>disabled_special_smarty_vars</tt> parameter. Instead, policies should use <tt>enabled_special_smarty_vars</tt>. This change in behavior is an "only allow" paradigm to the most sensitive parts of the Smarty engine implementation. It establishes a stronger security posture at present and for any future engine implementations.
 +
 +
<tt>enabled_special_smarty_vars</tt>'s value should be an array using [https://www.smarty.net/docs/en/language.variables.smarty.tpl these options].

Revision as of 12:32, 4 August 2020

This page describes a feature available in version 7.0 and above.

WHMCS 7.0 and later use Smarty Security Policies, a security-hardening measure. WHMCS uses a system policy for system wide use and a mail policy specifically for stored and dynamic email-based templates.

By default, WHMCS does not define any PHP functionality restrictions for the system policy (except to honor the pre-existing php tag setting as configured at Configuration () > System Settings > Security, or Setup > Security prior to WHMCS 8.0). All templates that use this policy are file-based (for example, themes and order forms) and require file-level access. Because of this, they are automatically implicitly trusted. Because custom themes are much more likely to have additional PHP-oriented logic, any restrictions defined by WHMCS could result in website rendering issues. It is completely within your discretion to determine whether implicit trust at the file level is invalid. You may make any appropriate restrictions for this system policy.

The mail policy restricts what PHP functionality can be used in email-based templates. The default mail policy will limit the use of variable modifiers to:

  • escape
  • count
  • urlencode
  • ucfirst
  • date_format

The default mail policy restricts the use of native PHP functions to:

  • isset
  • empty
  • count
  • sizeof
  • in_array
  • is_array
  • time
  • nl2br

Finally, the default mail policy blocks these Smarty tags:

  • block
  • function
  • include

The default mail policy will not allow any calls to static classes, fetching any data from PHP streams, or accessing any super global variables.

If you want to redefine either the system or mail policy, you can do this by adding a $smarty_security_policy setting to configuration.php. This example limits email templates (by modifying the mail policy) to ucwords as the only native PHP function allowed, while not changing the default restrictions on variable modifiers:

// Smarty custom email based template policy:
$smarty_security_policy = array(
'mail' => array(
'php_functions' => array(
'ucwords',
),
),
);

The example below would restrict the use of variable modifiers so that strpos was the only variable modifier permitted in an email template without changing the default restrictions on PHP functions:

// Smarty custom email based template policy:
$smarty_security_policy = array(
'mail' => array(
'php_modifiers' => array(
'strpos',
),
),
);

Using {include_php} Syntax

Smarty has deprecated the {include_php} syntax, but WHMCS currently supports this behavior via Policies. If your template invokes and includes a PHP script by using the Smarty {include_php} syntax, the full path to the directory containing that script will need to be whitelisted in the trusted_dir setting of your Policy.

// Smarty custom email based template policy:
$smarty_security_policy = array(
'system' => array(
'trusted_dir' => array(
'/path/to/folder',
),
),
);

See the Smarty documentation for all possible settings and what behavior to expect when assigning array and Boolean values.

Supported Policy Settings and Values

The settings that a WHMCS Smarty Security Policy enforces are the same as those defined by the Smarty library itself. You can learn more about about these settings from the Smarty documentation.

In WHMCS version 8.0 and later, WHMCS doesn't honor Smarty's disabled_special_smarty_vars parameter. Instead, policies should use enabled_special_smarty_vars. This change in behavior is an "only allow" paradigm to the most sensitive parts of the Smarty engine implementation. It establishes a stronger security posture at present and for any future engine implementations.

enabled_special_smarty_vars's value should be an array using these options.

Retrieved from "http://3.17.75.209/index.php?title=Smarty_Security_Policy&oldid=28762"