Revision as of 13:16, 26 August 2014

Summary

Prior to v5.3.9 (5.3.9-release.1), WHMCS admin passwords used a hashing mechanism that did not leverage the more secure algorithms and routines afforded by most web server environments of today.

If you update a previous installation to 5.3.9, each admin user will have their password automatically rehashed on their next successful login post upgrading. The rehash will occur for either an API authentication or an Admin Area authentication. The WHMCS admin(s) does not need to do anything in order to benefit from this low-level change in the product.

If you are performing a fresh install of WHMCS 5.3.9 (or beyond), your admin passwords will simply be hashed with the latest cryptographically secure mechanism available to your web server environment from the start.

What You Need To Know

• This security refinement occurs at a low-level and will typically go unobserved in a standard WHMCS installation.
• Only 3rd-Party Integration Developers that read/write admin authentication details directly from the database will be affected by this change. The specifics of what they’re doing in their code will determine the complexity of change required to make their integration functional again.
• Password hashes are only updated upon successful login; it is only then that the application has the raw password and is able to establish a new hash. Because the admin password are stored as one-way hashes, there is no way to perform a batch operation.

Public Documentation for Developers

Below is the minimum amount of code; it is far from adequate, assumes a lot, but demos the relevant class and methods.

A more thorough example script can be found here Admin First Factor Verification Demo

<?php
$authAdmin = new WHMCS_Auth();
if ($authAdmin->getInfobyUsername($username)
    && $authAdmin->comparePassword($password)
) {
   $isValid = true;
} else  {
   $isValid = false;
}

This is valid for WHMCS versions 5.3.0 and later.

Hash Schema

WHMCS 5.3.9 introduces application-level support and usage of two hash algorithms using cryptographically secure hashing routines.

Both the Bcrypt and SHA256-HMAC algorithms and hashing routines are supported. If the PHP version of the web server is 5.3.7 or greater, then Bcrypt will be used. Otherwise, if the web server is using a version of PHP that is less than 5.3.7, SHA256-HMAC will be used.