Smarty Security Policies are security hardening measures that protect a system. WHMCS applies a Smarty Security Policy for system-wide use and a mail policy for stored and dynamic email-based templates.

Policies #

WHMCS includes security policies for the system and for mail.

• The system policy does not restrict PHP beyond the version-specific behaviors in the sections below.
• The mail policy restricts the use of variable modifiers in email-based templates.
  • The policy will not allow any calls to static classes, fetching any data from PHP streams, or accessing any super global variables.
  • The mail policy allows the escape, count, urlencode, ucfirst, and date_format variable modifiers by default.
  • The mail policy restricts the use of native PHP functions to the isset, empty, count, sizeof, in_array, is_array, time, and nl2br functions by default.
  • The mail policy blocks the block, function, and include Smarty tags by default.

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

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.
• WHMCS 8.7 introduced reports and warnings to help admins find and eliminate these tags in their custom themes and templates.

{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',
  ],
  ],
  ];

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.

WHMCS doesn’t honor Smarty’s disabled_special_smarty_vars parameter. Instead, policies should use the enabled_special_smarty_vars parameter. For example:

  // 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 (above).

Last modified: October 10, 2024