Difference between revisions of "Smarty Security Policy"

From WHMCS Documentation
 
(13 intermediate revisions by 8 users not shown)
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"> We added this feature in WHMCS 7.0.</div>
 +
 
 +
Smarty Security Policies are security hardening measures that protect a system.
 +
 +
== System and Mail Policies ==
 +
 +
WHMCS applies a Smarty Security Policy for system-wide use and a mail policy for stored and dynamic email-based templates.
 +
 +
=== The System Policy ===
 +
 +
The system policy does not restrict PHP beyond the version-specific behaviors in the sections below.
 +
 +
=== The Mail Policy ===
 +
 +
The mail policy restricts the use of [http://www.smarty.net/docs/en/language.modifiers.tpl variable modifiers] in email-based templates. Additionally, the policy will not allow any calls to static classes, fetching any data from PHP streams, or accessing any super global variables.
 +
 +
By default, the mail policy:
 +
 +
* Allows the following variable modifiers:
 +
**<tt>escape</tt>
 +
**<tt>count</tt>
 +
**<tt>urlencode</tt>
 +
**<tt>ucfirst</tt>
 +
**<tt>date_format</tt>
 +
 +
* Restricts the use of native PHP functions to:
 +
**<tt>isset</tt>
 +
**<tt>empty</tt>
 +
**<tt>count</tt>
 +
**<tt>sizeof</tt>
 +
**<tt>in_array</tt>
 +
**<tt>is_array</tt>
 +
**<tt>time</tt>
 +
**<tt>nl2br</tt>
 +
 +
* Blocks the following Smarty tags:
 +
**<tt>block</tt>
 +
**<tt>function</tt>
 +
**<tt>include</tt>
 +
 +
=== Version-Specific Smarty Tag Support ===
 +
 +
In WHMCS 9.0, we plan to remove all backwards compatibility for legacy Smarty <tt>{php}</tt>, <tt>{include_php}</tt>, and <tt>{insert}</tt> tags. This will also remove the related '''Allow Smarty PHP Tags''' setting in the '''[[Security Tab|Security]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''', or, prior to WHMCS 8.0, '''Setup > General Settings'''.
 +
 +
* WHMCS 8.7 introduced reports and warnings to help admins find and eliminate these tags in their custom themes and templates.
 +
* For more information, see [[Eliminating Legacy Smarty Tags]].
 +
 +
==== Allow Smarty PHP Tags ====
 +
 +
In WHMCS 8.7 and earlier, WHMCS honors the '''Allow Smarty PHP Tags''' setting in the '''[[Security Tab|Security]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''', or, prior to WHMCS 8.0, '''Setup > General Settings'''.
 +
 +
* All template files that use the system policy are file-based (for example, system themes and order form templates) and require file-level access. Because of this, they are automatically implicitly trusted.
 +
* Custom system themes are much more likely to have additional PHP-oriented logic, and so any restrictions on them from 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.
 +
 +
==== {include_php} Tag Use ====
 +
 +
In WHMCS 8.7 and earlier, you can use the deprecated <tt>{include_php}</tt> syntax. To do this, you must whitelist the full path to the script's directory in the <tt>trusted_dir</tt> setting for your policy:
 +
 
 +
<div class="source-cli">
 +
// System policy:
 +
<br/>$smarty_security_policy = [
 +
<br/>    'system' => [
 +
<br/>        'trusted_dir' => [
 +
<br/>            '/path/to/folder',
 +
<br/>        ],
 +
<br/>    ],
 +
<br/>];
 +
</div>
 +
 
 +
For a list of possible settings and their behavior with arrays and Boolean values, see [http://www.smarty.net/docs/en/advanced.features.tpl#advanced.features.security/ Smarty documentation].
  
−
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.
+
== Redefining Security Policies in WHMCS 8.7 and Earlier ==
−
 
+
 
−
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
+
If you want to redefine either the system or mail policies, add a <tt>$smarty_security_policy</tt> setting to the <tt>configuration.php</tt> file.
−
 
+
−
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 example below limits email templates by modifying the mail policy to only allow the native <tt>ucwords</tt> PHP function. It does not change the default restrictions on variable modifiers:
−
 
+
 
−
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:
+
<div class="source-cli">
−
 
+
// Smarty custom email based template policy:
−
*escape
+
<br/>$smarty_security_policy = [
−
*count
+
<br/>    'mail' => [
−
*urlencode
+
<br/>        'php_functions' => [
−
*ucfirst
+
<br/>            'ucwords',
−
*date_format
+
<br/>        ],
−
 
+
<br/>    ],
−
The default mail policy restricts the use of native PHP functions to the following:
+
<br/>];
−
 
+
</div>
−
*isset
+
 
−
*empty
+
The example below restricts the use of variable modifiers to only permit the <tt>strpos</tt> variable modifier in an email template without changing the default restrictions on PHP functions:
−
*count
+
 
−
*sizeof
+
<div class="source-cli">
−
*in_array
 
−
*is_array
 
−
*time
 
−
*nl2br
 
−
 
 
−
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 $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:
 
−
 
 
−
<source lang="php">
 
 
// Smarty custom email based template policy:
 
// Smarty custom email based template policy:
−
$smarty_security_policy => array(
+
<br/>$smarty_security_policy = [
−
    'mail' => array(
+
<br/>   'mail' => [
−
        'php_functions' => array(
+
<br/>        'php_modifiers' => [
−
            'ucwords',
+
<br/>            'strpos',
−
        ),
+
<br/>        ],
−
    ),
+
<br/>    ],
−
);
+
<br/>];
−
</source>
+
</div>
−
 
+
 
−
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 directory of that script will need to be whitelisted in the 'trusted_dir' setting of your Policy.
+
=== Supported Policy Settings and Values ===
−
 
+
 
−
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.
+
The settings that a WHMCS Smarty Security Policy enforces are the same as the settings that the Smarty library itself defines. For more information, see [http://www.smarty.net/docs/en/advanced.features.tpl the Smarty documentation].
 +
 
 +
In WHMCS 8.0 and later, to improve security, WHMCS doesn't honor Smarty's <tt>disabled_special_smarty_vars</tt> parameter. Instead, policies should use the <tt>enabled_special_smarty_vars</tt> parameter. This change in behaviour is an "only allow" paradigm to the most sensitive parts of the Smarty engine implementation.
 +
 
 +
<div class="source-cli">
 +
// Smarty enable special variables policy:
 +
<br/>$smarty_security_policy = [
 +
<br/>        'system' => [
 +
<br/>            'enabled_special_smarty_vars' => [
 +
<br/>                'cookies',
 +
<br/>            ],
 +
<br/>        ],
 +
<br/>];
 +
</div>
 +
 +
The <tt>enabled_special_smarty_vars</tt> value must be an array using [https://www.smarty.net/docs/en/language.variables.smarty.tpl Smarty's options].
 +
The WHMCS system policy enables the following values for compatibility with older templates, but your current or future WHMCS templates may not require them:
 +
 +
<div class="source-cli">
 +
'foreach',
 +
<br/>'section',
 +
<br/>'block',
 +
<br/>'capture',
 +
<br/>'now',
 +
<br/>'get',
 +
<br/>'post',
 +
<br/>'server',
 +
<br/>'request',
 +
<br/>'template',
 +
<br/>'const',
 +
</div>
 +
 +
<div class="docs-alert-info">
 +
Defining your own Smarty Security Policy requires you to include all of the variables that client and admin templates use, including the ones that WHMCS otherwise enables by default (as above).
 +
</div>

Latest revision as of 21:49, 26 January 2023

We added this feature in WHMCS 7.0.

Smarty Security Policies are security hardening measures that protect a system.

System and Mail Policies

WHMCS applies a Smarty Security Policy for system-wide use and a mail policy for stored and dynamic email-based templates.

The System Policy

The system policy does not restrict PHP beyond the version-specific behaviors in the sections below.

The Mail Policy

The mail policy restricts the use of variable modifiers in email-based templates. Additionally, the policy will not allow any calls to static classes, fetching any data from PHP streams, or accessing any super global variables.

By default, the mail policy:

  • Allows the following variable modifiers:
    • escape
    • count
    • urlencode
    • ucfirst
    • date_format
  • Restricts the use of native PHP functions to:
    • isset
    • empty
    • count
    • sizeof
    • in_array
    • is_array
    • time
    • nl2br
  • Blocks the following Smarty tags:
    • block
    • function
    • include

Version-Specific Smarty Tag Support

In WHMCS 9.0, we plan to remove all backwards compatibility for legacy Smarty {php}, {include_php}, and {insert} tags. This will also remove the related Allow Smarty PHP Tags setting in the Security tab at Configuration () > System Settings > General Settings, or, prior to WHMCS 8.0, Setup > General Settings.

  • WHMCS 8.7 introduced reports and warnings to help admins find and eliminate these tags in their custom themes and templates.
  • For more information, see Eliminating Legacy Smarty Tags.

Allow Smarty PHP Tags

In WHMCS 8.7 and earlier, WHMCS honors the Allow Smarty PHP Tags setting in the Security tab at Configuration () > System Settings > General Settings, or, prior to WHMCS 8.0, Setup > General Settings.

  • All template files that use the system policy are file-based (for example, system themes and order form templates) and require file-level access. Because of this, they are automatically implicitly trusted.
  • Custom system themes are much more likely to have additional PHP-oriented logic, and so any restrictions on them from 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.

{include_php} Tag Use

In WHMCS 8.7 and earlier, you can use the deprecated {include_php} syntax. To do this, you must whitelist the full path to the script's directory in the trusted_dir setting for your policy:

// System policy:
$smarty_security_policy = [
'system' => [
'trusted_dir' => [
'/path/to/folder',
],
],
];

For a list of possible settings and their behavior with arrays and Boolean values, see Smarty documentation.

Redefining Security Policies in WHMCS 8.7 and Earlier

If you want to redefine either the system or mail policies, add a $smarty_security_policy setting to the configuration.php file.

The example below limits email templates by modifying the mail policy to only allow the native ucwords PHP function. It does not change the default restrictions on variable modifiers:

// Smarty custom email based template policy:
$smarty_security_policy = [
'mail' => [
'php_functions' => [
'ucwords',
],
],
];

The example below restricts the use of variable modifiers to only permit the strpos variable modifier in an email template without changing the default restrictions on PHP functions:

// Smarty custom email based template policy:
$smarty_security_policy = [
'mail' => [
'php_modifiers' => [
'strpos',
],
],
];

Supported Policy Settings and Values

The settings that a WHMCS Smarty Security Policy enforces are the same as the settings that the Smarty library itself defines. For more information, see the Smarty documentation.

In WHMCS 8.0 and later, to improve security, WHMCS doesn't honor Smarty's disabled_special_smarty_vars parameter. Instead, policies should use the enabled_special_smarty_vars parameter. This change in behaviour is an "only allow" paradigm to the most sensitive parts of the Smarty engine implementation.

// Smarty enable special variables policy:
$smarty_security_policy = [
'system' => [
'enabled_special_smarty_vars' => [
'cookies',
],
],
];

The enabled_special_smarty_vars value must be an array using Smarty's options. The WHMCS system policy enables the following values for compatibility with older templates, but your current or future WHMCS templates may not require them:

'foreach',
'section',
'block',
'capture',
'now',
'get',
'post',
'server',
'request',
'template',
'const',

Defining your own Smarty Security Policy requires you to include all of the variables that client and admin templates use, including the ones that WHMCS otherwise enables by default (as above).

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