Smarty Security Policy
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 preexisting php tag setting Configuration () > System Settings > Security, or Setup > 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.
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 = [
'mail' => [
'php_functions' => [
'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 = [
'mail' => [
'php_modifiers' => [
'strpos',
],
],
];
Using {include_php} Syntax
Smarty has deprecated the {include_php} syntax, but WHMCS currently supports this behavior via Policies. If your template file 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 = [
'system' => [
'trusted_dir' => [
'/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 honour Smarty's disabled_special_smarty_vars parameter. Instead, policies should use enabled_special_smarty_vars. 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',
],
],
];
enabled_special_smarty_vars's value should be an array using 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.
'foreach',
'section',
'block',
'capture',
'now',
'get',
'post',
'server',
'request',
'template',
'const',