How do I configure server-side serial number validation?

Answer

The best approach for validating a serial number entered by an user is a server-side validation. Basically, the package will send some information to your server, your server will verify the information and it will return an answer.

The information is sent to the server by using the POST method (not the "GET" method).

Each piece of information retrieved from the user is stored into an installer property:

• serial number -> PIDKEY
• user name -> USERNAME
• company -> COMPANYNAME
• package version -> ProductVersion
• the ID of the system language -> it is retrieved automatically by the custom action which sends the information

The script which gets and verifies this information uses the following variables: sn (serial number), username, company, version, languageid. After this information is verified, the server will return a reply which looks like this:

AnswerCode\nMessage

AnswerCode represents the result of the server-side validation and it can be:

• 601 - the serial number is valid and the installation will continue
• 602 - the serial number is not valid and the installation will stop

Message is a string sent by the server to explain why the serial number is invalid. This message is shown to the user only if the AnswerCode is 602.

For example, a reply from the server can look like this:

602\nThe serial number is invalid.

In this case, the information provided by the user was not found in the database and the server replied for an invalid serial number.

Create the database on the server

Since the validation is performed on your server, you can use a database to keep track of your customers and their serial numbers. A sample MySQL script is this:

CREATE DATABASE IF NOT EXISTS `mydb` DEFAULT CHARACTER SET utf8 COLLATE utf8_bin;
USE `mydb`;

-- --------------------------------------------------------
--
-- Table structure for table `clients`
--

CREATE TABLE IF NOT EXISTS `clients` (
  `client_id` int(10) unsigned NOT NULL auto_increment,
  `user_name` varchar(255) collate utf8_bin NOT NULL,
  `company` varchar(255) collate utf8_bin NOT NULL,
  `email` varchar(255) collate utf8_bin NOT NULL,
  `serial_no` varchar(255) collate utf8_bin NOT NULL,
  PRIMARY KEY  (`client_id`),
  UNIQUE KEY `email` (`email`),
  UNIQUE KEY `serial` (`serial_no`)
) ENGINE=InnoDB  DEFAULT CHARSET=utf8 COLLATE=utf8_bin COMMENT='Our company clients' AUTO_INCREMENT=3 ;

--
-- Dumping data for table `clients`
--

INSERT INTO `clients` (`client_id`, `user_name`, `company`, `email`, `serial_no`) VALUES
(1, 'John Doe', 'User Comp.', 'johnd@domain.com', '233-421-752-325'),
(2, 'User Name', 'Home', 'email@domain.com', '444-555-222-243');

This database will be queried by a script in order to determine if the serial number of the user which runs the installation is valid.

Create the script which verifies the serial number

This script must be able to receive the information sent by the installer, connect to the database, verify the information and issue a response. Here is a sample PHP script:

<?php 
        
// server response codes
define('LICENSE_VALID',   '601');
define('LICENSE_INVALID', '602');

// database connection parameters
$db_host = 'localhost:3306';
$db_user = 'root';
$db_pass = 'root123';
$db_name = 'mydb';

// client information table
$clients_tbl_name = 'clients';
$sn_tbl_col       = 'serial_no';

/**
 * Server HTTP response to the query issued by Advanced Installer serial validation tool.
 */
function ServerResponse($is_valid, $posted_serial = '', $lang_id = 1033)
{
  $msg_sep = "\n";
  
  // load error messages from your database, using "$lang_id" for localization (optional)
  
  if($posted_serial == '')
    return LICENSE_INVALID . $msg_sep . "Missing Serial Number !";
  
  if($is_valid == true)
    return LICENSE_VALID;
  else
    return LICENSE_INVALID . $msg_sep . "Serial Number: " . $posted_serial . ' is invalid !';  
}

// Variables POSTed by Advanced Installer serial validation tool to this web page: "sn", "languageid".
if(isset($_POST['sn']) && trim($_POST['sn']) != '')
{
  // get the serial number entered by the installing user in the "UserRegistrationDlg" dialog 
  $sn = trim($_POST['sn']);
  
  // get the system language ID of the user's machine
  // (you can use this parameter to display a localized error message taken from your database)
  $languageid = (int) $_POST['languageid'];
  
  // connect to database
  $db_conn = @mysql_connect($db_host, $db_user, $db_pass);
  if(!$db_conn)
  {
    // issue error response
    echo ServerResponse(false, $sn, $languageid);
    die();
  }
  
  // select target database
  $db_selected = @mysql_select_db($db_name, $db_conn);
  if(!$db_selected)
  {
    // issue error response
    echo ServerResponse(false, $sn, $languageid);
    die();
  }
  
  // prepare SQL statement
  $sn_query = "SELECT `". $sn_tbl_col ."` FROM `". $clients_tbl_name ."` WHERE `". $sn_tbl_col ."` = '" . mysql_escape_string($sn) . "'";
  
  // execute query
  $result = @mysql_query($sn_query, $db_conn);
  
  // get result set size
  if(@mysql_num_rows($result) == 0)
  {
    // serial number NOT found in database => issue error response
    echo ServerResponse(false, $sn, $languageid);
    die();
  }
  else
  {
    // serial number was found in database => issue SUCCESS response
    echo ServerResponse(true, $sn, $languageid);
    die();
  }
}
else
{
  // issue error response
  echo ServerResponse(false);
  die();
}

?>

This script must be placed on your server in an URL which will be accessed by the installation package. For example, if the PHP script is named "validate.php" then the URL can be something like this:

http://www.example.com/validate.php

You can download an example which uses a PHP or JSP script over a MySQL database.

If the targeted computer for installation does not have internet connectivity, the provided URL is incorrect or the web sever does not respond in a timely fashion with the appropriate message format, the Advanced Installer validation tool will not allow the installation to continue.

Limited number of activations (serial number validations)

A common scenario would be to limit the number of successful serial validations. Suppose that each of your customers has purchased a certain number of licenses and when this number of installations is reached, future installations should fail with an appropriate error message (for instance, "Maximum number of validations exceeded" instead of "Invalid serial number").

Basically, considering the above example, you can add 2 more columns to the "clients" table:

• license_no - will hold the number of licenses each user has purchased
• validations_no - will hold the number of successful serial number validations for each user (basically, it will specify the number of times a given serial number was used)

Each time a valid serial is POST-ed to the script, the value of the "validations_no" column is incremented and compared with the value of the "license_no" column. If the number of successful validations has been exceeded, the answer code "602" is sent with an appropriate error message ("Maximum number of validations exceeded"), causing the installation to be stopped.

You will find modified PHP and MySQL scripts, implementing the approach discussed above, in the "RegLimit" folder inside the provided zip archive.

Configure the installer project

In order to configure the installation package you can follow these steps:

• go to the Serial Validation Page
• check the Use Serial Validation option
• select the Server-side validation validation method
• set the URL which points to the PHP script (http://www.example.com/validate.php)
• set the Template Value for the serial number

When enabling the serial validation feature Advanced Installer automatically adds the "UserRegistrationDlg" dialog in the Dialogs page. This dialog contains three edit box controls which set the PIDKEY, USERNAME and COMPANYNAME properties.

These properties can also be set from the command line when performing a silent (or normal) installation.