Skip to main content

This document describes and provides detailed example code on how to add WIKID strong authentication to a PHP application.

Instantiation

This section instantiates the connection between the network client application and the WiKID server. For this to succeed, the network client must have been issued a certificate from the WiKID server. The certificate is contained withing a PKCS12 certificate store and requires a passphrase to access.

When the wClient object is instantiated it will load the cert and establish a persistent authenticated SSL connection. This is normally done once per server or application and shared by multiple threads. In this example the object is created and destroyed each page request. This greatly (1000 times) increases overhead of the process but allows all the functions to be shown in this single example page.

Parameters are: wClient(String host, int port, String keyfile, String pass)

  • host = IP address of WIKID server
  • port = TCP port number to connect to (default 8388)
  • keyfile = Path to the PKCS12 certificate file
  • pass = Passphrase to open the PKCS12 file
$servercode_default = "127000000001";
$server_host = "wikid-server.example.com";
$server_port = 8388;
$client_key_file = "issued-client-cert-and-key.pem";
$client_key_pass = "changeme";

$status = '';

$clean = array();
$valid_params = array('action','user','regcode','passcode','servercode');
foreach ($valid_params as $k) {
    $v = $_REQUEST[$k];
    // pull out the first word-chunk, and drop the rest
    $v = preg_replace('/^\W(\w+)./', '$1', $v);
    $clean[$k] = $v;
}
if (!empty($clean['action']))
{
    $clean['action'] = strtolower($clean['action']);
}


$wc = new wClient($server_host, $server_port, $client_key_file, $client_key_pass);
//print_r($wc);
if (!$wc)
{
    echo "Unable to load wClient!!";
}

Registration

The registration process associates a device that has regitered its key with the WiKID server to a userid that represents a individual with rights in the network. Devices can register with the server at will but have no access rights until registered to a userid. Inactive registrations are purged from the system automatically.

The registration process should be completed only after validating that the user is not an imposter. This may be done in various ways according to local security policy. It is assumed that whatever validation is required has been completed successfully before callint the registerUsername function.

Parameters are: registerUsername(String user, String regcode, String servercode)

  • user = userid with which to associate device
  • regcode = the registration code provided to the device
  • servercode = the 12-digit code that represents the server/domain
This method returns an integer representing the result of the registration.
$res = -1;
if (isset($clean['action']) && ($clean['action'] == "register"))
{
    $res = $wc->registerUsername($clean['username'], $clean['regcode'], $clean['servercode']);
    if ($res == 0)
    {
        $status = "Success";
    } 
    else 
    {
        $status = "Failed ("+res+")";
    }
}

Login Online

This function is the normal-state login for users. This is called when the users device is connected to the network and able to directly request a passcode for access.

Parameters are:

  • checkCredentials(String user, String passcode, String servercode)
  • user = userid to validate credentials
  • passcode = time-bounded, 1 use passcode
  • servercode = 12-digit code that represents the server/domain

This method returns a boolean representing sucessful or unsuccessful authentication

$isValid = false;
if (isset($clean['action']) && ($clean['action'] == "check online"))
{
    $isValid = $wc->checkCredentials($clean['username'], $clean['passcode'], $clean['servercode']);
    if ($isValid)
    {
        $status = "Success";
    } 
    else 
    {
        $status = "Authentication Failed";
    }
}

Login Offline

This function implements the challenge-reponse authentication for offline devices. Users are given a random challenge and the signed response is returned and validated.

Parameters are: checkCredentials(String user, String challenge, String response, String servercode)

  • user = userid to validate credentials
  • challenge = the challeng value provided to the user
  • response = the hashed/signed responss from the device
  • servercode = 12-digit code that represents the server/domain
This functions is not needed by the Open Source release.
 

$r_challenge = $_REQUEST["challenge"];
$r_response = $_REQUEST["response"];

if (isset($clean['action']) && ($clean['action'] == "check offline"))
{
    $isValid = false;
    $isValid = $wc->checkCredentials($clean['username'], $r_challenge, 
                                     $r_response, $clean['servercode']);
    if ($isValid)
    {
        $status = "Success";
    } 
    else 
    {
        $status = "Authentication Failed";
    }
}

Add additional device to existing userid

This method is used to add an additional device to the users account. It follows the same process as a normal registration but requires a passcode from a device already registered to the userid. This method will authenticate the user with the passcode provided prior to registering the new device.

Parameters are: registerUsername(String user, String regcode, String servercode, String passcode)

  • user = userid with which to associate device
  • regcode = the registration code provided to the device
  • servercode = the 12-digit code that represents the server/domain
  • passcode = time-bounded, 1 use passcode from a device already registered to this user
This method returns an integer representing the result of the registration. /
if (isset($clean['action']) && ($clean['action'] == "add device"))
{
    $res = -1;
    $res = $wc->registerUsername($clean['username'], $clean['regcode'], 
                                 $clean['servercode'], $clean['passcode']);
    if ($res==0)
    {
        $status = "Success";
    } 
    else 
    {
        $status = "Failed ("+$res+")";
    }
}


if (!empty($clean['action']))
{
    echo "

$status

"; } else { $chall = ''; //generate a random number for the offline challenge $min = 1000000000; $max = mt_getrandmax(); $num = $min + (($max-$min) mt_rand(0, 32767)/32767); $chall = $num+""; $chall = substr($chall, 0, 8); ?>

The required HTML

    
<h1> This page demonstrates the general usage of the wClient component.  </h1>

     <!-- Registration -->
     <hr />
     <h2>Registration</h2>
     <form action=\"<?php echo $PHP_SELF ?>\" method=\"POST\" >
             UserID: <input type=\"text\" size=\"25\" name=\"user\" value=\"\"/><br />
             Registration code: <input type=\"text\" size=\"12\" name=\"regcode\" value=\"\"/><br />
             Domain code: <input type=\"text\" size=\"16\" name=\"servercode\" value=\"<?= $servercode_default ?>\"/><br />
             <input type=\"submit\" name=\"action\" value=\"Register\"><br />
     </form>

     <!-- Online Login -->
     <hr />
     <h2>Online Login:
     </h2>
     <form action=\"<?php echo $PHP_SELF ?>\" method=\"POST\" >
             UserID: <input type=\"text\" size=\"25\" name=\"user\" value=\"\"/><br />
             Passcode: <input type=\"text\" size=\"12\" name=\"passcode\" value=\"\"/><br />
             Domain code: <input type=\"text\" size=\"16\" name=\"servercode\" value=\"<?= $servercode_default ?>\"/><br />
             <input type=\"submit\" name=\"action\" value=\"Check Online\"><br />
     </form>

    <?php 
    /  Not currently supported by the Open Source release
        
     <!-- Offline Login -->
     <hr />
     <h2>Offline Login:
     </h2>
     <form action=\"<?php echo $PHP_SELF ?>\" method=\"POST\" >
             UserID: <input type=\"text\" size=\"25\" name=\"user\" value=\"\"/><br />
             Challenge: <?= $chall ?> <input type=\"hidden\" name=\"challenge\" value=\"<?= $chall ?>\"/><br />
             Response: <input type=\"text\" size=\"12\" name=\"response\" value=\"\"/><br />
             Domain code: <input type=\"text\" size=\"16\" name=\"servercode\" value=\"<?= $servercode_default ?>\"/><br />
             <input type=\"submit\" name=\"action\" value=\"Check Offline\"><br />
     </form>

    / 
    ?>
        
     <!-- Add device -->
     <hr />
     <h2>Add device:
     </h2>
     <form action=\"<?php echo $PHP_SELF ?>\" method=\"POST\" >
             UserID: <input type=\"text\" size=\"25\" name=\"user\" value=\"\"/><br />
             Registration code: <input type=\"text\" size=\"12\" name=\"regcode\" value=\"\"/><br />
             Passcode: <input type=\"text\" size=\"12\" name=\"passcode\" value=\"\"/><br />
             Domain code: <input type=\"text\" size=\"16\" name=\"servercode\" value=\"<?= $servercode_default ?>\"/><br />
             <input type=\"submit\" name=\"action\" value=\"Add device\"><br />
     </form>

<?php
} 
$wc->close();
unset($wc);
?>


 

Copyright © WiKID Systems, Inc. 2019 | Two-factor Authentication