How to use WiKID in a JSP application

This has been tested on Tomcat, but the wAuth protocol can be used to add two-factor authentication to any JSP application, not matter what application server you use.

First, import the WiKID client:

<%@ page contentType="text/html; charset=UTF-8" %>
<%@ page import="com.wikidsystems.client.*" %>

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 within 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
• caStore - The certificate authority store for validating the WAS server certificate <-- DO NOT USE Java's cacerts file
• caStorePass - The passphrase securing the caStore file

<%
	String status="";
      	String chall="";
	wClient wc = new wClient("127.0.0.1", 8388, "Config.getValue("BASEPATH")/private/localhost.p12", "p12_passphrase", Config.getValue("BASEPATH")+"private/caStore", "caStore_passphrase" ) ;

%>

Registration

The registration process associates a device that has resitered it's 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.

<%
	int res = -1;
	if(request.getParameter("action") != null && request.getParameter("action").equalsIgnoreCase("register")){
          res = wc.registerUsername(request.getParameter("user"), request.getParameter("regcode"), request.getParameter("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

<%
	boolean isValid = false;
	if(request.getParameter("action") != null && request.getParameter("action").equalsIgnoreCase("Check Online")){
          isValid = wc.CheckCredentials(request.getParameter("user"), request.getParameter("passcode"), request.getParameter("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 for
• 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

<%

	if(request.getParameter("action") != null && request.getParameter("action").equalsIgnoreCase("Check Offline")){
          isValid = false;
          isValid = wc.CheckCredentials(request.getParameter("user"), request.getParameter("challenge"), request.getParameter("response"), request.getParameter("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(request.getParameter("action") != null && request.getParameter("action").equalsIgnoreCase("Add device")){
          res = -1;
          res = wc.registerUsername(request.getParameter("user"), request.getParameter("regcode"), request.getParameter("servercode"), request.getParameter("passcode"));
          if (res==0){
          	status="Success";
          } else {
          	status="Failed ("+res+")";
          }
	}
%>

You will also need some code to generate the random challenge for the challenge-response mechanism.

<%
	if(request.getParameter("action")==null){

          	//generate a random number for the offline challenge
        	java.security.SecureRandom sr = java.security.SecureRandom.getInstance("SHA1PRNG");
                long num = sr.nextLong();
                while (num <= 1000000000l){
                  num=sr.nextLong();
                }
                chall = num+"";
                chall = chall.substring(0,8);



            %>

And here is the HTML for the page:

<title>WiKID Commercial Open Source Strong Authentication</title>

<link rel="authenticator" type="application/WiKID" title="WiKID Authentication" href="wikid://127000000001">

<link rel="authRegistrar" type="application/WiKID" title="WiKID Authentication" href="http://127000000001/example.jsp">

<link rel="authForm" type="application/WiKID" title="WiKID Authentication" href="http://127000000001/example.jsp">

	<!-- Registration -->

           	<hr /> <h2>Registration:</h2><form action="./example.jsp" method="POST" >

        		UserID: <input type="text" size="25" name="user" value=""/><br />

        		Registration code: <input type="text" size="12" name="regcode" id="WiKID_Regcode" value=""/><br />

        		Domain code: <input type="text" size="16" name="servercode" value="127000000001"/><p></p>

        		<input type="submit" name="action" value="Register"><br />

         	</form>

	<!-- Online Login -->

          	<hr /><h2>Online Login:</h2><form action="./example.jsp" method="POST" >

        		UserID: <input type="text" size="25" name="user" value=""/><br />

        		Passcode: <input type="text" size="12" name="passcode"  id="WiKID_Passcode" value=""/><br />

        		Domain code: <input type="text" size="16" name="servercode" value="127000000001"/><p></p>

        		<input type="submit" name="action" value="Check Online"><br />

         	</form>

	<!-- Offline Login -->

          	<hr /><h2>Offline Login:</h2><form action="./example.jsp" 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="127000000001"/><p></p>

       		<input type="submit" name="action" value="Check Online"><br />

         	</form>

	<!-- Add device -->

         	<hr /><h2>Add device:</h2><form action="./example.jsp" method="POST" >

        		UserID: <input type="text" size="25" name="user" value=""/><br />

        		Registration code: <input type="text" size="12" name="regcode" id="WiKID_Regcode" value=""/><br />

            Passcode: <input type="text" size="12" name="passcode" id="WiKID_Passcode" value=""/><br />

        		Domain code: <input type="text" size="16" name="servercode" value="127000000001"/><p></p>

        		<input type="submit" name="action" value="Add device"><br />

          	</form>

<%

	} else {

          %>

          	<h1>

          		 <%=status%>

          	</h1>

          <%

	}

        wc.close();

        wc=null;

%>

</body></html>

Note that link "link rel=..." at the top of the page and the "id="WiKID_Passcode" code in the form are for the WiKID Firefox extension's semantic web capabilities of auto-populating the passcode and registration code fields.

You can download the complete example.jsp page here Right Click, Save As.