Authentication Process

The main components involved in the authentication process are:

the application that share a challenge with the 4identity client;
the 4identity client that, using the certificate selected by the user, sign the challenge;
the smartengine that verify the signed challenge and in case of success will return to the application server an information representing the success login.

Detailing this process, the user click on a button to start the authentication process and the challenge contained on the authentication page is signed used the authentication certificate selected by the user.

Figura 7 – Choose the certificate for the authentication

The signed challenge is sent by the 4identity client to the smartengine for the verification, if the verification is successful means that the authentication is successful.

Figura 8 – Signature Process

The output of verification process done by the smartengine is some POST variables that show the results. The key information to take in account is the “result” post variable that show the verification result, the value can be ok or ko.

For example, the output for a successful authentication can be:

Result = ok: Doe/John/DOEJHN1234567890

Where the text after the two points is the certificate CN.

See the chapter 2.5 for description of all post fields.

Even if the code explained on the following chapters check only the “result” value, the below security best practice must be implemented:

the challenge need to be changed on every user session and checked on the server side on the authentication check;
the server key parameter (see the chapter 2.5 for further details) need to be checked on the server side at the authentication check;

Due that the 4Identity client do not need any custom code we will show the code for the application that run on the application server.

This application is composed of:

a login page to enable the user to click on a button to authenticate himself;
a component to read the post message and take the decision on the verification result;
a landing page that show the authentication results.

Java code

For an environment using J2EE we will use:

an application server as.example.com:8080 that expose the custom application on /4identity ;
the custom application 4identity consist of:
- login.html: containing the form ;
- a servlet called Auth that read the POST data and take a decision on them. For demo purpose the servlet redirect the session to a landing page called success.jsp printing all posted data. However a redirection to a landing page is always needed;
- a JSP page called success.jsp that show the verification results printing the POSTED value;

Figura 9 – Authentication process

LOGIN.HTML

See below the code for login.html page.

<!DOCTYPE html>
<html>
<head>
<meta charset="ISO-8859-1">
<title>4Identity Authentication</title>
</head>
<body>
<form class="bit4id-auth form-stacked" method="post" action="4identity/Auth">
<div class="bit4id-authReq" style="display: none;">
<div class="bit4id-challenge">4IDENTITYCH</div>
<div class="bit4id-certType">ANY</div>
<div class="bit4id-certInfo">CN</div>
</div>
<input type="submit" value="Authenticate" />
</form>
<script src="http://fe.example.com:8082/smartengine/bit4id-auth.min.js"></script>
</body>
</html>

This page contain the FORM element with the custom class bit4id-auth, the action configured against our servlet Auth and the method set to POST:

OTHER CODE HERE

</form>

Then we need to build the signature request with the class bit4id-authReq. The request is filled with the information for:

The challenge exchanged with the 4identity client. The challenge can be any text or number :

<div class="bit4id-challenge">4IDENTITYCH</div>

The type of certificate:

The certificate’s attribute (CN) shown on the 4identity client:

The submit button to send the post:

The script resource on the SMARTENGINE server deployed on the server fe.example.com on the port 8082 :

For the other information about the authentication request see the chapter 2.42.1.4.

Auth servlet

See below the code for the Servlet class:

package com.bit4id.identity;

import java.io.IOException;

import java.io.PrintWriter;

import java.util.Enumeration;

import javax.servlet.ServletException;

import javax.servlet.annotation.WebServlet;

import javax.servlet.http.HttpServlet;

import javax.servlet.http.HttpServletRequest;

import javax.servlet.http.HttpServletResponse;

@WebServlet("/Auth")

public class Auth extends HttpServlet {

private static final long serialVersionUID = 1L;

public Auth() {

super();

}

protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {

PrintWriter out = response.getWriter();

out.println("AUTH MANAGEMENT SERVLET");

out.close();

}

protected void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {

Enumeration<String> parameterNames = request.getParameterNames();

String htmlout="";

response.setContentType("text/html");

while (parameterNames.hasMoreElements()) {

String paramName = parameterNames.nextElement();

if ("result".equals(paramName))

{

String prmRes = request.getParameter(paramName);

String result = prmRes.substring(0, 2);

htmlout = "<p></p>AUTHENTICATION: " + result + "<p></p>";

// INSERT SERVER CODE HERE TO MANAGE THE AUTHENTICATION RESULTS

// USING THE VARIABLE result:

// ok -> AUTHENTICATION SUCCESSFULL

// ko -> AUTHENTICATION FAILED

}

htmlout= htmlout + "<br>" + paramName;

String[] paramValues = request.getParameterValues(paramName);

for (int i = 0; i < paramValues.length; i++) {

String paramValue = paramValues[i];

htmlout= htmlout + "(" + paramValue + ")";

}

response.sendRedirect("success.jsp?outprint=" + htmlout);

}

As shown above is a Servlet standard that manage a POST message and take a decision evaluating the value of the post variablecalled “result”.

The main code is composed of an extraction of the value for the posted variable “result”. The first two character of this variable can be “ok” or “ko “ and after this can be added a server code to manage this result for the authentication process. This piece of server code need to be built on the requirements of the application to integrate, for example can be inserted the code to set a session variable that enable the user to login to an application.

As a best practice also the posted values sk and challenge need to be managed. The sk value is decided as a server code on a configuration file while the challenge need to be random for every page request and compared at the server side level.

if ("result".equals(paramName))

{

String prmRes = request.getParameter(paramName);

String result = prmRes.substring(0, 2);

htmlout = "<p></p>AUTHENTICATION: " + result + "<p></p>";

// INSERT SERVER CODE HERE TO MANAGE THE AUTHENTICATION RESULTS

// USING THE VARIABLE result, sk and challenge:

// ok -> AUTHENTICATION SUCCESSFULL

// ko -> AUTHENTICATION FAILED

}

After this, the code will fill the variable “htmlout” with all the posted data with this syntax: POSTED_VARIABLE_NAME(POSTED_VARIABLE_VALUE)

At the end the code will redirect the user to the page success.jsp sending the variable htmlout :

response.sendRedirect("success.jsp?outprint=" + htmlout);

success.jsp

See below the code for page success.jsp:

<%@ page language="java" contentType="text/html; charset=ISO-8859-1"

pageEncoding="ISO-8859-1"%>

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

<html>

<head>

<title>Signature Process</title>

</head>

<body>

if (request.getParameter( "link" ) != null) {

String link = request.getParameter("link");

out.println("<a href=" + link.toString() + ">SIGNED FILE</a>") ;

}

if (request.getParameter( "outprint" ) != null) {

String outprint = request.getParameter("outprint");

out.println("REQUEST PRINT:" + outprint.toString());

}

</body>

</html>

The code above read the parameter “outprint” sent by the servlet and print its value :

if (request.getParameter( "outprint" ) != null) {

String outprint = request.getParameter("outprint");

out.println("REQUEST PRINT:" + outprint.toString());

}

.Net code

For an environment using .NET we will use:

an application server as.example.com:9090 that expose the custom application on /4identity ;
the custom application 4identity consist of:
- login.aspx: containing the form ;
- an aspx page AuthOK.aspx that read the POST data and take a decision on them. This page redirect the session to a landing page called landingauth.aspx printing the most important data;
- an aspx page called landingauth.aspx that show the verification results printing the POSTED value:

Output: ok

User: Doe/John/DOEJHN1234567890

Secret Server Code: 5787237843

Challenge: 4IDENTITYCH

Figura 10 – Authentication process

LOGIN.ASPX

See below the code for login.aspx page.

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="login.aspx.cs" Inherits="SmartEngineDemo.login" %>

<!DOCTYPE html>

<html>

<head>

<title>4Identity Authentication</title>

</head>

<body>

<div class="bit4id-challenge">4IDENTITYCH</div>

</div>

</form>

</body>

</html>

This page contain the FORM element with the custom class bit4id-auth, the action configured against our servlet Auth and the method set to POST:

OTHER CODE HERE

</form>

Then we need to build the Authentication request with the class bit4id-authReq. The request is filled with the information for:

The challenge exchanged with the 4identity client. The challenge can be any text or number :

<div class="bit4id-challenge">4IDENTITYCH</div>

The type of certificate:

The certificate’s attribute (CN) shown on the 4identity client:

The submit button to send the post:

The script resource on the SMARTENGINE server deployed on the server fe.example.com on the port 8082 :

For the other information about the authentication request, see the chapter 2.2.3.

AuthOK.aspx page

The page AuthOk.aspx has a frontend and some code to run on the Page_Load event.

Front end Code:

%@ Page Language="C#" AutoEventWireup="true" CodeBehind="AuthOK.aspx.cs" Inherits="SmartEngineDemo.AuthOK" %>

<!DOCTYPE html>

<html>

<head>

<title>process page</title>

</head>

<body>

</body>

</html>

The behind code:

using System;

using System.Collections.Generic;

using System.Linq;

using System.Web;

using System.Web.UI;

using System.Web.UI.WebControls;

namespace SmartEngineDemo

{

public partial class AuthOK : System.Web.UI.Page

{

protected void Page_Load(object sender, EventArgs e)

{

String authres = Request.Form["result"].Substring(0, 2);

int lenres = Request.Form["result"].ToString().Length;

String userId = Request.Form["result"].Substring(3, lenres - 3);

String secretCode = Request.Form["sk"];

String challenge = Request.Form["challenge"];

// INSERT SERVER CODE HERE TO MANAGE THE AUTHENTICATION RESULTS

// USING THE POST VARIABLE result, sk and challenge:

// ok -> AUTHENTICATION SUCCESSFULL

// ko -> AUTHENTICATION FAILED

Response.Redirect("landingauth.aspx?Auth=" + authres + "&User=" + userId + "&sk=" + secretCode + "&challenge=" + challenge);

}

As shown in the behind code above, this page manage the POST message and take a decision evaluating the value of the post variablecalled “result”.

As a best practice also the posted values sk and challenge need to be managed. The sk value is decided as a server code on a configuration file, while the challenge need to be random for every page request and compared at the server side level.

String authres = Request.Form["result"].Substring(0, 2);

int lenres = Request.Form["result"].ToString().Length;

String userId = Request.Form["result"].Substring(3, lenres - 3);

String secretCode = Request.Form["sk"];

String challenge = Request.Form["challenge"];

// INSERT SERVER CODE HERE TO MANAGE THE AUTHENTICATION RESULTS

// USING THE POST VARIABLE result, sk and challenge:

// ok -> AUTHENTICATION SUCCESSFULL

// ko -> AUTHENTICATION FAILED

Response.Redirect("landingauth.aspx?Auth=" + authres + "&User=" + userId + "&sk=" + secretCode + "&challenge=" + challenge);

After this, the code will redirect the core information to the page landingauth.aspx:

Response.Redirect("landingauth.aspx?Auth=" + authres + "&User=" + userId + "&sk=" + secretCode + "&challenge=" + challenge);

Landingauth.aspx

The page landingauth.aspx has only frontend code. This page take the data passed from the page AuthOK.aspx page and print them for demo purpose.

Front end Code:

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="landingauth.aspx.cs" Inherits="SmartEngineDemo.landingauth" %>

<!DOCTYPE html>

<html>

<head>

<title>4Identity Authentication</title>

</head>

<body>

<h2>

Landing Page for authentication

</h2>

User status for Authentication:

<BR />Output: <%=Request.QueryString["Auth"] %>

<BR />Secret Server Code: <%=Request.QueryString["sk"] %>

<BR />Challenge: <%=Request.QueryString["challenge"] %>

</body>

</html>

Authentication Parameter

Below are detailed the parameter for the authentication functionality.

This section describes the Authentication parameters to be included within the form class: bit4id-authReq.

Parameter	Values	Default
bit4id-challenge	“challenge to sign”	NO DEFAULT
bit4id-signingAlgorithm	“RSASHA256”, “RSASHA1”, “RSAMD5”	“RSASHA256”
bit4id-issuerFilter	“CN=..., OU=..., T=..., ecc.”	“”
bit4id-certType	“ANY”, “SIG”, “AUT”	“ANY”

bit4id-challenge: Define a value to use as a challenge value.

bit4id-signingAlgorithm: Defines the algorithm that will be used to sign.

bit4id-issuerFilter: Defines the signing certificate filter as a sub-string of the certificate issuer distinguished name.

bit4id-certType: Defines the signing certificate filter as a string describing the type of certificate.

Posted Value

Listed below are all the parameter sent from the smartengine to the Application Server. (see the Java example), the format for the posted value is:

POSTED_PARAMETER_NAME (POSTED_PARAMETER_VALUE)

REQUEST PRINT:

AUTHENTICATION: ok

result(ok: Doe/John/DOEJHN1234567890)sk(5787237843)not_before(Mon, 03 Sep 2012 15:30:28GMT)certificate(MIID1jCCAz gAwIBAgICAkQwDQYJKoZIhvcNAQELBQAwVzEPMA0GA1UEChMGQml0NElEMQ8wDQYDVQQHEwZOYXBvbGkxCzAJBgNVBAgTAk5BMQswCQYDVQQGEwJJVDEZMBcGA1UEAxMQQml0NElEIC0gVEVTVCBDQTAeFw0xMjA5MDMxNTMwMjhaFw0yMjA5MDExNTMwMjhaMHwxCzAJBgNVBAYTAklUMQ8wDQYDVQQKEwZCaXQ0aWQxIjAgBgNVBAMTGURvZS9Kb2huL0RPRUpITjEyMzQ1Njc4OTAxDTALBgNVBCoTBEpvaG4xDDAKBgNVBAQTA0RvZTEbMBkGCSqGSIb3DQEJARYMamRvZUB0ZXN0Lml0MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvE6LA1SAdKNUTEd3z4hTXkAz8hikcWGEyXKpKqC4eegSPYXxhBDRfGES8xa/TG0UCQk t2j0Bzh595aUwMr4EavtqsEy03NOI0yY5ROTI4Oxcv5HwV QAmd34z9mcIVILO1dgichEyj1hKchdZ1UguLTnUcnIrw Jl5sKTVWufUpyxIy EQQs22 AdEjU40bU6jQFFADF4ks30ch3DAFF4tKPBVbha1OObb43hxM6a3p5AmWJAYj/LOJ8v2WYyr9lyUemRWyuANQUaWXVgj4rPiUqN6fx79G5rRvOoSvhwIeSXEsVRvdsvEccqXZ17HRwPbQup1CjlJzQmjVHFPNfwIDAQABo4IBBjCCAQIwKQYJKwYBBAGCNxQCBBweGgBTAG0AYQByAHQAYwBhAHIAZABVAHMAZQByMA4GA1UdDwEB/wQEAwIFoDApBgNVHSUEIjAgBggrBgEFBQcDAgYIKwYBBQUHAwQGCisGAQQBgjcUAgIwCQYDVR0SBAIwADAfBgNVHSMEGDAWgBTmZwDoKVcTR9QJAoNl82/yq4LrszA2BglghkgBhvhCAQ0EKRYnQml0NGlkIC0gQXV0aGVudGljYXRpb24gVGVzdCBDcnRpZmljYXRlMB0GA1UdDgQWBBQXEK5XIGYE9/SopVLv1hqScP/i9zAXBgNVHREEEDAOgQxqZG9lQHRlc3QuaXQwDQYJKoZIhvcNAQELBQADgYEAtUgvrMyv5YeAIevt3r51XNsPtXX5JK6A7YV9sjGovECox 82VfBsfedg2qoijNtGbjlBJ1Jxil5fi3Ppcc3DOLEW73jtRVibqSjWqvU3IAA1SvLayFGTgtEAEuu7zRSs7pK1rOqpoadHLNC1 djU7C6HjN9FTT4DW1 T1C/z0xA=)challenge(4IDENTITYCH)issuer(CN=Bit4ID - TEST CA, C=IT, S=NA, L=Napoli, O=Bit4ID)subject([email protected], 2.5.4.4=Doe, 2.5.4.42=John, CN=Doe/John/DOEJHN1234567890, O=Bit4id, C=IT)signed_challenge(c29 uJLyViof Zg8O6QEpnLou28mkCt0Hut5rOGEUAHdI3Hkkf0ABsVKgYDX 4g0Q9rt n DzNWzmNER2i1W7QeQjTHuUd yg7I59uJp6hiqRHRqrXBzgo9sp6nQlgFyDjwoYmNpx2PZKlZSewvIF5dkS21Toy B3OoY4obK2Aq7QQ2NlGsKOhnmTM4gUJlBYiHrJx1Tz39ATT3yAAQ9brKlCTVwkEtIrvA/GpQndzEisikQtYum/pFe9entZ0FB6kNwW3mjfOxcuc5CjQ8YD3MA13T4MssIw47NQnWuvKxN35dcyDH/tNix Dg6IcFE3TXkfn/SUSylh5GLkaOrPQ==)serial(0244)not_after(Thu, 01 Sep 2022 15:30:28GMT)

Parameter Name	Parameter Value	Example
result	This parameter has the output of the challenge verification.	result(ok: Doe/John/DOEJHN1234567890)
sk	The value of a secret key defined on the smartengine in the configuration file config.ini stored in this path:	sk(5787237843)
not_before	The start date for the certificate validity.	not_before(Mon, 03 Sep 2012 15:30:28GMT)
certificate	The user’s certificate in base64 enconding.
challenge	The challenge used in the authentication phase	challenge(4IDENTITYCH)
Issuer	The CN of certificate’s issuer	issuer(CN=Bit4ID - TEST CA, C=IT, S=NA, L=Napoli, O=Bit4ID)
subject	The value of the subject attribute into the user’s certifcate	subject([email protected], 2.5.4.4=Doe, 2.5.4.42=John, CN=Doe/John/DOEJHN1234567890, O=Bit4id, C=IT)
signed_challenge	The value of the signed challenge
serial	The certificate’s serial	serial(0244)
not_after	The end date for the certificate validity.	not_after(Thu, 01 Sep 2022 15:30:28GMT)

NOTE: The issuers of the certificates used for the authentication need to be stored in the folder in DER format:

<<SMARTENGINE INSTALLATION FOLDER>>/smartengine/etc/smartengine/certificates/

Into the same folder written above, it must be present a file called tags.txt with the following content: chain

See an example below.

Authentication Process