Difference between revisions of "Smarty Security Policy"

Revision as of 17:51, 4 May 2022

We added this feature in WHMCS 7.0.

In WHMCS 7.0 and later, WHMCS uses Smarty Security Policies, which are security hardening measures that protect the system.

Security Policies in WHMCS

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

The System Policy

By default, WHMCS does not define any PHP functionality restrictions for the system policy other than honoring the preexisting php tag 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.

The Mail Policy

The mail policy restricts the PHP functionality that email-based templates can use. 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.

Redefining Security Policies

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

This example 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 would restrict 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',
        ],
    ],
];

Using {include_php} Syntax

Smarty has deprecated the {include_php} syntax, but WHMCS currently supports this behavior in policies. If your template file invokes and includes a PHP script by using the Smarty {include_php} syntax, you must whitelist the full path to the script's directory in the trusted_dir setting for your policy.

// Smarty custom email based template 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.

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 version 8.0 and later, WHMCS doesn't honour 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. It establishes a stronger security posture at present and for any future engine implementations.

// 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 follow values are enabled in the WHMCS system policy for compatibility with older templates. 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).

@@ 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>
-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.
+In WHMCS 7.0 and later, WHMCS uses Smarty Security Policies, which are security hardening measures that protect the system.
+== Security Policies in WHMCS ==
+WHMCS applies a system policy for system-wide use and a mail policy for stored and dynamic email-based templates.
+=== The System Policy ===
-By default, WHMCS does not define any PHP functionality restrictions for the system policy (except to honor the preexisting <tt>php</tt> tag setting '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings > Security''', or '''Setup > General Settings > Security''' prior to WHMCS 8.0). All template files that use this 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. Because custom system 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 other than honoring the preexisting <tt>php</tt> tag 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.
+=== The Mail 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 the PHP functionality that email-based templates can use. The default mail policy will limit the use of [http://www.smarty.net/docs/en/language.modifiers.tpl variable modifiers] to:
 *<tt>escape</tt>
@@ Line 31: / Line 42: @@
 The default mail policy will not allow any calls to static classes, fetching any data from PHP streams, or accessing any super global variables.
+== Redefining Security Policies ==
-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 policies, add a <tt>$smarty_security_policy</tt> setting to the <tt>configuration.php</tt> file.
+This example 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:
 <div class="source-cli">
@@ Line 45: / Line 60: @@
 </div>
-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:
+The example below would restrict 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:
 <div class="source-cli">
@@ Line 58: / Line 73: @@
 </div>
-===Using {include_php} Syntax===
+== Using {include_php} Syntax ==
-Smarty has deprecated the <tt>{include_php}</tt> syntax, but WHMCS currently supports this behavior via Policies. If your template file 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.
+Smarty has deprecated the <tt>{include_php}</tt> syntax, but WHMCS currently supports this behavior in policies. If your template file invokes and includes a PHP script by using the Smarty <tt>{include_php}</tt> syntax, 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">
@@ Line 73: / Line 88: @@
 </div>
-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.
+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].
 === 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].
+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 version 8.0 and later, WHMCS doesn't honour Smarty's <tt>disabled_special_smarty_vars</tt> parameter. Instead, policies should use <tt>enabled_special_smarty_vars</tt>. This change in behaviour 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.
+In WHMCS version 8.0 and later, WHMCS doesn't honour 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. It establishes a stronger security posture at present and for any future engine implementations.
 <div class="source-cli">
@@ Line 91: / Line 106: @@
 <br/>];
 </div>
-<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].
-The follow are enabled in the WHMCS system policy for compatibility with older templates and may not be required for your current or future WHMCS templates.
+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 follow values are enabled in the WHMCS system policy for compatibility with older templates. Your current or future WHMCS templates may not require them:
 <div class="source-cli">
@@ Line 108: / Line 124: @@
 </div>
-<div class="docs-alert-info">Defining your own Smarty Security Policy requires you to include all variables used by client and admin templates, including the ones that WHMCS otherwise enables by default (as above).</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>

Documentation