PINgrid Software Development Kit Documentation

SDK Guide

PINgrid Software Development Kit for Microsoft .NET

Multi-factor authentication made simple

Revision: 2.5.3510 Published: July 2012 Applies to: PINgrid Software Development Kit for Microsoft .NET Web site: http://www.winfrasoft.com Email: support@winfrasoft.com

2006-2012 Winfrasoft Corporation. All rights reserved. This publication is for informational purposes only. Winfrasoft makes no warranties, express or implied, in this summary. Winfrasoft, AuthCentral and PINgrid are trademarks of Winfrasoft Corporation. All other trademarks are property of their respective owners.

Information in this document, including URL and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the example companies, organisations, products, domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious, and no association with any real company, organisation, product, domain name, e-mail address, logo, person, place or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Winfrasoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written licence agreement from Winfrasoft, the furnishing of this document does not give you any licence to these patents, trademarks, copyrights, or other intellectual property.

Microsoft, Active Directory, Windows and Windows Server are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. The names of actual companies and products mentioned herein may be the trademarks of their respective owners.

Copyright 2006-2012 Winfrasoft Corporation. All rights reserved.

Table of Contents 3

Table of Contents
TABLE OF CONTENTS ..................................................................................................................................... 3 INTRODUCTION .................................................................................................................................................... 4 TERMINOLOGY .................................................................................................................................................... 4 TECHNOLOGY OVERVIEW ............................................................................................................................ 5 CLASS OVERVIEW ............................................................................................................................................ 5 WINFRASOFT.PINGRID.ENGINE ........................................................................................................................... 5 WINFRASOFT.PINGRID.GRAPHICS ....................................................................................................................... 5 WINFRASOFT.PINGRID.MIPCOMPLEXITY ........................................................................................................... 5 API INTERFACE ................................................................................................................................................. 6 PREREQUISITES.................................................................................................................................................... 6 REFERENCE API .................................................................................................................................................. 6 WINFRASOFT.PINGRID.ENGINE NAMESPACE INTERFACE .................................................................................... 7 Declaration ..................................................................................................................................................... 7 Logging ........................................................................................................................................................... 7 Methods Overview .......................................................................................................................................... 7 METHODS DETAIL ................................................................................................................................................ 9 CheckPatternComplexity ................................................................................................................................ 9 GetDateTime ................................................................................................................................................. 11 GetMIPHash ................................................................................................................................................. 12 GetDeviceSeed .............................................................................................................................................. 13 GetTransactionSeed...................................................................................................................................... 14 GenerateCAP ................................................................................................................................................ 15 GetMessage .................................................................................................................................................. 16 GenerateRandomMIP ................................................................................................................................... 17 GenerateRandomPIN.................................................................................................................................... 18 GenerateUserSeed ........................................................................................................................................ 19 GenerateCodeString ..................................................................................................................................... 20 SeedStringToByteArray ................................................................................................................................ 21 ValidatePasscode.......................................................................................................................................... 22 ConvertGUIDStringtoHEXString ................................................................................................................. 24 ConvertHEXStringToByteArray ................................................................................................................... 25 ConvertByteArrayToHEXString ................................................................................................................... 26 WINFRASOFT.PINGRID.GRAPHICS NAMESPACE INTERFACE .............................................................................. 27 Declaration ................................................................................................................................................... 28 Constructors ................................................................................................................................................. 28 Methods Overview ........................................................................................................................................ 28 Properties Overview ..................................................................................................................................... 28 METHOD SPECIFICATIONS ................................................................................................................................. 29 GenerateMatrix ............................................................................................................................................ 29 SAMPLE APPLICATION ....................................................................................................................................... 30

4 Winfrasoft Technology PINgrid SDK

Introduction
The Winfrasoft PINgrid SDK is the essential reference for developers who wish to integrate PINgrid technology into Microsoft .NET projects. The SDK includes a compiled .NET 3.5 Dynamic Link Library (DLL) with ready to use class and sample code to get started. Source code is also available for the DLL. This SDK has been created to specify the coding requirements to embed Winfrasoft PINgrid matrix based authentication technologies into your own applications. This guide should be used in conjunction with the PINgrid Technology Implementation Guide. The SDK DLL has an Assembly Name and Root Namespace of Winfrasoft.PinGrid with 3 available classes: Engine Graphics MIPComplexity (Internal use only)

All sample code and SDK source code is only available in Visual Basic .NET.

Terminology
The following terms are used thought this document and have the following meanings: PIN Personal Identification Number OTP One Time PIN OTC One Time Code (same as OTP) Passcode The code entered by a user consisting of an OTP and optional static PIN MIP Memorable Identification Pattern CAP Challenge Authentication Prompt Authentication Device A physical device, either electronic or analogue, which is able to generate a CAP.

Technology Overview 5

Technology Overview
PINgrid is a system in which a user is securely authenticated by inputting a Passcode made up of a sequence of elements in the form of a One Time PIN (OTP), derived by overlaying memorable sequence positions against a larger series of pseudo-random elements generated by an Authentication Device together with an optional static PIN. The user both memorises and registers a Memorable Identification Pattern (MIP) with the authentication authority, or the user memorises a MIP that was generated on behalf of the user either automatically or manually. Each time a user needs to prove their identity to the Authentication Authority they are presented with a Challenge Authentication Prompt (CAP) generated by an Authentication Device. The user will derive their OTP by identifying the elements on the CAP that match the positions of their MIP. The key to the security of the system is that even if the OTP is intercepted in transit along with the CAP then the MIP still remains unknown. If the CAP is provided to the user via a separate physical medium to that used to enter the OTP (out-of-band) then the security of the system is strengthened further to true two factor authentication. The OTP security may be further strengthened with the addition of a static PIN. The OTP may also be calculated for the user by an Authentication Device on which the user enters their pattern, but this must only be used in out-of-band scenarios. As an additional option, the user could also be required to memorise and register a PIN with the authentication authority, or the user memorises a PIN that was generated on behalf of the user either automatically or manually, or the system can leverage an existing PIN already known to the user. When entering a Passcode, a user would need to supply both their OTP code and their PIN, in any order. By doing so further protects the MIP from being discovered. Furthermore the number of possible combinations for a correct login increases exponentially as the Passcode length is now the length of the OTP code and static PIN combined.

Class Overview
Winfrasoft.PinGrid.Engine
The Engine Class contains public shared functions for the main PINgrid operations such as CAP and user seed generation, pattern complexity verification and passcode validation. As all functions are public shared an instance of this class is not required.

Winfrasoft.PinGrid.Graphics
The Graphics Class is used to generate a Challenge Matrix and return the graphic as a Bitmap image. This class will display both 6x6 and 8x8 images both Blank and CAP embedded graphics. The resolution and colours for the matrix graphic may also be specified. All bitmaps are created according to the PINgrid branding and usage guidelines and must not be modified after they are generated. And instance of the graphics object is required for use.

Winfrasoft.PinGrid.MIPComplexity
This class is designed for internal use by the Engine class. The functionality of this class is to ensure that selected patterns confirm to pattern complexity policy thus preventing the use of simplistic and easily shoulder surfed user-defined patterns. This class must not be called directly and as such is not documented.

6 Winfrasoft Technology PINgrid SDK

API Interface
Prerequisites
The PINgrid SDK for .NET requires the following software to be installed on the development PC: Microsoft .NET Framework 3.5 or later

A .NET based programming language IDE in Microsoft Windows: Visual Basic .NET, Visual C# .NET, Visual C++ .NET, Delphi .NET (and more). Visual Studio .NET 2005 / 2008 / 2010 Web Applications: ASP.NET 2.0 Borland C# Builder, Embarcadero Delphi .NET

Reference API
To add the Interface to your VB.Net or C# project, select Project-Add Reference Browse to Winfrasoft.PinGrid.dll file.

C# VB.NET -

using Winfrasoft.PinGrid; Imports Winfrasoft.PinGrid

API Interface 7

Winfrasoft.PinGrid.Engine Namespace Interface

Allows access to Public shared Engine methods.

Declaration
Dim PINgridEngine As Winfrasoft.PinGrid.Engine There is no constructor for this class. All functions are Public Shared functions.

Logging
For most Functions, an optional ByRef Log parameter can be called. This string input is available for debugging purposes and will return log information from within the function. NOTE: Optionals are not available in C# so a Null must be supplied if not required.

Methods Overview
Function CheckPatternComplexity GetDateTime GetMIPHash GenerateCAP GetMessage GenerateRandomMIP GenerateRandomPIN GenerateUserSeed Return Type Boolean String String String String String String String Description This function tests the users entered MIP to see if it is sufficiently complex depending on the administrator set complexity tests specified. Returns the Current Systems UTC time in the format yyyyMMddHHmm Convert a pattern split into sections depending on the SplitPositions Variable and return an encoded MIP. Generates a CAP based on the matrixSize, message and seed as a byte array. Builds a CAP Message based on the timeframe and lastLoginsarray. Generates a random MIP for user and return the co-ordinates encoded. e.g.1,2,3,4,5,6 Returns a Random PIN for a user. The returned PIN will only return values that are found within the Code String. Returns a random unique single or double GUID as a string for the users MIP Seed based on the specified bit length.

8 Winfrasoft Technology PINgrid SDK

GenerateCodeString

String

Generates a Code String based on the inputted 64-Bit Message and Seed (128-bit minimum to conform to OATH standards) using FIPS compliant HMACSHA256 cryptography. Receives a single or double GUID string or 128Bit or 256Bit HEX String and returns a Byte array. Runs through all the permatations attempting to check the User Entered Passcode against the multitude of potential patterns that could have been generated for that user. Includes 2FA devices and multiple time periods. Converts a GUID string to HEX string. Converts a HEX string into a Byte Array. Converts a Byte Array to HEX string.

SeedStringToByteArray

Byte()

ValidatePasscode ConvertGUIDStringtoHEXString ConvertHEXStringToByteArray ConvertByteArrayToHEXString

Boolean String Byte() String

API Interface 9

Methods detail
CheckPatternComplexity
Overloaded function allows for value parameter when ValidityTest requires additional input values to test against. Public Shared Function CheckPatternComplexity (ByVal MIP As String, ByVal matrixSize As Int32, ByVal validityCheck As Winfrasoft.PinGrid.PatternValidity.PatternValidityTests, Optional ByRef log As String = Nothing) As Boolean Public Shared Function CheckPatternComplexity (ByVal MIP As String, ByVal matrixSize As Int32, ByVal validityCheck As Winfrasoft.PinGrid.PatternValidity.PatternValidityTests, ByVal value As Int32, Optional ByRef log As String = Nothing) As Boolean Return BOOLEAN Parameters Parameter MIP matrixSize validityCheck Type String Int32 PatternValidityTests Description MIP to be validated. Input Example 1,2,4,6,8,7 Returns True or False. True when inserted MIP passes complexity checks. False when MIP fails checks.

Number of columns in patterns. 6 Select the ValidityTest to test None = 0 pattern against. BlockSequentialStraightLines = 1 BlockSinglePlane = 2 RestrictSequentialLinearAdjacencies= 4 RestrictCellRepeatUsage = 8

value (Overloaded) Log (Optional)

Int32 String

Some validity tests require a parameter values. Generates detailed logging from within function.

Builds a CAP Message based on the timeframe and lastLoginsarray

10 Winfrasoft Technology PINgrid SDK

Sample Code Dim booReturn As Boolean booReturn = Winfrasoft.PinGrid.Engine.CheckPatternValidity("1,2,3,4,5,6", 6, Winfrasoft.PinGrid.PatternValidity.PatternValidityTests.BlockSinglePlane) 'booReturn = false

API Interface 11

GetDateTime
Overloaded function that allows user to specify the Date and time frame or utilise UTC.Now when no Date and Time is specified. This function produces the required date and time formatting for the first 12 digits of the Message portion of a CAP. Public Shared Function GetDateTime (Optional ByRef log As String = Nothing) As String Public Shared Function GetDateTime (ByVal timeFrame As Date, Optional ByRef log As String = Nothing) As String Return STRING Parameters Parameter timeFrame (Overloaded) Log (Optional) Type Date String Description Date and time which will be translate to yyyyMMddHHmm format. Generates detailed logging from within function. Input Example 23-05-2011 16:08:02 Returns UTC in yyyyMMddHHmm format i.e. 201105231608

Sample Code Dim strReturn As String strReturn = Winfrasoft.PinGrid.Engine.GetDateTime() 'strReturn = "201106101022"

12 Winfrasoft Technology PINgrid SDK

GetMIPHash
This function generates a HASH of the MIP. Public Shared Function GetMIPHash(ByVal MIP As String, ByVal salt As String, ByVal splitPositions As Int32, Optional ByRef log As String = Nothing) As String Return STRING Parameters Parameter MIP salt splitPositions Log (Optional) Sample Code Dim strReturn As String strReturn = Winfrasoft.PinGrid.Engine.GetMIPHash("1,2,3,4,5,6", "ThisIsSaltforMIPHashing", 5) 'strReturn = "gxOh7TIXERVO9rwRdq/BKs5BrjY=6dcfXufJLW3J6S/9rRe4vUlBj5g=" Type String String Int32 String Description MIP to be hashed. Salt value used for MIP hash. This value can be empty. Input Example 1,2,4,6,8,7 ThisIsSalt forMIPHashing Returns the hash of the MIP using FIPS compliant algorithms.

Number of MIP positions to separated into subsections for 5 speed of computation. Generates detailed logging from within function.

API Interface 13

GetDeviceSeed
This function produces a 2 Factor authentication device seed using device specific information. The overload can receive an optional remote seed. Public Shared Function GetDeviceSeed(ByVal deviceTypeSeed As String, ByVal hardwareInfo As String) As Byte() Public Shared Function GetDeviceSeed(ByVal deviceTypeSeed As String, ByVal hardwareInfo As String, ByVal remoteSeed As String) As Byte()

Return Byte() Parameters Parameter deviceTypeSeed

Returns the device seed as a byte array based on device type and unique hardware information.

Type String

Description Device specific seed.

Input Example Aabc789a-99bd-5cb2904d-22d720ef6450 Bb23e2bc-d5a8-4a7f8e6e-13dc47c06e9c

hardwareInfo remoteSeed Sample Code

String String

The unique hardware information i.e. Serial Number

51HLP3G

Optional 10 char value to bi-directionally link the user and 1234567890 the token

Dim bytReturn As Byte() bytReturn = Winfrasoft.PinGrid.Engine.GetDeviceSeed("Aabc789a-99bd-5cb2-904d-22d720ef6450Bb23e2bc-d5a8-4a7f8e6e-13dc47c06e9c", "51HLP3G", "1234567890") 'bytReturn = 154, 120, 188, 170, 189 , 112, 248, 87, 172

14 Winfrasoft Technology PINgrid SDK

GetTransactionSeed
This function produces a 2 Factor authentication device seed using a device seed and transaction specific information. Public Shared Function GetTransactionSeed(ByVal deviceSeed() As Byte, ByVal transactionData As String) As Byte()

Return Byte() Parameters Parameter deviceSeed transactionData Sample Code

Returns the device seed as a byte array based on device type and unique hardware information.

Type Byte() String

Description 256bit Device seed, e.g. result from GetDeviceSeed(). Information specific to a transaction or workflow process. NB: Only the first 32 characters will be processed, anything further will be truncated.

Input Example {23,64,26,45,132} Acc:59761486486224

Dim bytReturn As Byte() bytReturn = Winfrasoft.PinGrid.Engine.GetTransactionSeed({23,64,26,45,132}, " Acc:59761486486224") 'bytReturn = 124, 110, 18, 10, 186 , 116, 244, 47, 152

API Interface 15

GenerateCAP
This function produces a valid CAP value ready for presentation to a user. This includes running the cryptographic HMACSHA256 function and abstracting the code string to produce a CAP. The overloads can receive the seed as either a String or a Byte array. Public Shared Function GenerateCAP(ByVal matrixSize As Integer, ByVal message As String, ByVal seed() As Byte, Optional ByRef log As String = Nothing) As String Public Shared Function GenerateCAP(ByVal matrixSize As Integer, ByVal message As String, ByVal seed As String, Optional ByRef log As String = Nothing) As String Return STRING Parameters Parameter matrixSize message seed Log (Optional) Sample Code Dim strReturn As String Dim message As String = Winfrasoft.PinGrid.Engine.GetMessage(Now, Nothing) Dim userSeed As String = Winfrasoft.PinGrid.Engine.GenerateUserSeed(Winfrasoft.PinGrid.Engine.SeedLength.Bits128) Dim strReturn As String = Winfrasoft.PinGrid.Engine.GenerateCAP(6, message, userSeed) 'strReturn = "124424124004133123520255553005103143" Type Integer String Byte() or String String Description Size of the matrix for the CAP. HMACSHA256 message used for encryption. User/Device seed as Byte array or String to used for the CAP generation. The seed may be represented as as two GUIDs or a hexidecimal string. Generates detailed logging from within function. Input Example 6 or 8 2011052316080000 Byte Array [32] Returns valid digits for a CAP.

16 Winfrasoft Technology PINgrid SDK

GetMessage
This function determines the next valid Message which can then be used to generate a CAP. The function will evaluate the Messages of prior login attempts and the given timeframe to determine if a Message has been previously generated during the current timeframe, and if so it will increment the Identifier to produce a unique Message. This function internally calls the GetDateTime function. Public Shared Function GetMessage(ByVal timeFrame As Date, ByVal lastLoginsAttempts() As String, Optional ByRef log As String = Nothing) As String Return STRING Parameters Parameter timeFrame lastLoginsAttempts Log (Optional) Sample Code Dim strReturn As String strReturn = Winfrasoft.PinGrid.Engine.GetMessage(Now, Nothing) 'return = "2011061010320000" Type Date String() String Description Date and time. Array of Messages used for previous valid login attempts. Generates detailed logging from within function. Input Example 23-05-2011 16:08:02 2011052316080000 Returns CAP Message to be used as input for GenerateCAP function , message parameter.

API Interface 17

GenerateRandomMIP
This funciton will randomly generate a MIP. This is usefull for automatically provisioning a user with a pattern or if a user forgets their pattern and requires it to be reset. The overloaded function allows for a MIP to be generated which will conform to the specified complexity requirements. Public Shared Function GenerateRandomMIP(ByVal matrixSize As Int32, ByVal MIPLength As Int32, Optional ByRef log As String = Nothing) As String Public Shared Function GenerateRandomMIP(ByVal matrixSize As Int32, ByVal MIPLength As Int32, ByVal blockSequentialLines As Boolean, ByVal blockSinglePlane As Boolean, ByVal restrictCellRepeatUsage As Boolean, ByVal restrictSequentialLinearAdjacencies As Boolean, ByVal restrictCellRepeatParam As Int32, ByVal restrictSequentialLinearAdjParam As Int32, Optional ByRef log As String = Nothing) As String Return STRING Parameters Parameter matrixSize MIPLength blockSequentialLines blockSinglePlane restrictCellRepeatUsage restrictSequentialLinearAdjacencies restrictCellRepeatParam restrictSequentialLinearAdjParam Log (Optional) Sample Code Dim strReturn As String strReturn = Winfrasoft.PinGrid.Engine.GenerateRandomMIP(6, 6) 'strReturn = "26,9,32,8,2,3" Type Int32 Int32 Boolean Boolean Boolean Boolean Int32 Int32 String Description Number of rows in Matrix. Length of MIP to generate. Enforce policy for restriction. Enforce policy for restriction. Enforce policy for restriction. Enforce policy for restriction. Parameter for Cell Repeats restriction. Parameter for Seq linear adj restriction. Generates detailed logging from within function. Input Example 6 6 True True True True 2 3 Returns a randomly Generated MIP.

18 Winfrasoft Technology PINgrid SDK

GenerateRandomPIN
This funciton will randomly generate a PIN. This is usefull for automatically provisioning a user with a PIN or if a user forgets their PIN and requires it to be reset. The PIN generation requires knowledge of the matrix size and if the user is required to use 2FA to ensure that the generated PIN only uses a valid range of digits. Public Shared Function GenerateRandomPIN(ByVal matrixSize As Int32, ByVal PINLength As Int32, ByVal require2FA As Boolean, Optional ByRef log As String = Nothing) As String Return STRING Parameters Parameter matrixSize PINLength require2FA Log (Optional) Sample Code Dim strReturn As String strReturn = Winfrasoft.PinGrid.Engine.GenerateRandomPIN(6, 4, False) 'strReturn = "0411" Type Int32 Int32 Boolean String Description Number of columns or rows in Matrix. Length of PIN to generate. 2FA pins are not limited to values that exist with matrix range. Generates detailed logging from within function. Input Example 6 4 False Returns a randomly generated PIN.

API Interface 19

GenerateUserSeed
The function randomly generates a user seed in the format of a GUID string. Either a 128bit (single GUID) or 256bit (double GUID) seeds can be created however it is recommended that only 256bit seeds are used. Public Shared Function GenerateUserSeed(ByVal seedLength As SeedLength) As String Return STRING Parameters Parameter seedLength Log (Optional) Sample Code Dim strReturn As String strReturn = Winfrasoft.PinGrid.Engine.GenerateUserSeed(Winfrasoft.PinGrid.Engine.SeedLength.Bits256) 'strReturn = "eb3be655-71ed-4a83-a2ac-ba105e138ae5b2abd837-c47f-4bed-8c1c-13825beffb35" Type Engine.SeedLength String Description 128 Bit or 256 Bit seed. Generates detailed logging from within function. Input Example Engine.SeedLength.Bits128 Engine.SeedLength.Bits256 Returns randomly generated user seed in ether 128 Bit or 256 Bit.

20 Winfrasoft Technology PINgrid SDK

GenerateCodeString
This function constructs a Code String from the output of the HMACSHA256 algorithm. The Code String at this stage must be abstracted to produce a CAP. The overloaded functions allow for seed inputs as string, GUID or Byte array. Public Shared Function GenerateCodeString(ByVal Message As String, ByVal Seed As String) As String Public Shared Function GenerateCodeString(ByVal Message As String, ByVal GUID As Guid) As String Public Shared Function GenerateCodeString(ByVal Message As String, ByVal arrByte As Byte()) As String Return STRING Parameters Parameter message seed Log (Optional) Sample Code Dim strReturn As String Dim message As String = Winfrasoft.PinGrid.Engine.GenerateCAPMessage(Now, Nothing) Dim userSeed As String = Winfrasoft.PinGrid.Engine.GenerateUserSeed(Winfrasoft.PinGrid.Engine.SeedLength.Bits128) strReturn = Winfrasoft.PinGrid.Engine.GenerateCodeString(message, userSeed) 'strReturn = "197722411431421132366712110502541021937716022170159128181602122418219011019836125134" Type String String/GUID/Byte() String Description Message for HMAC function Seed for HMAC function Generates detailed logging from within function. Input Example 2011052316080000 Byte Array [32] Code String.

API Interface 21

SeedStringToByteArray
Converts a seed (GUID or HEX format) to a byte array. If the seed length is 36 or 72 characters then it shall be processed as a single or double GUID will return a 128bit or 256bit Byte array respectively. If the seed is 32 or 64 characters then is shall be processed as a HEX string and will return a 128bit or 256bit Byte array respectively. If any other seed lengh is provided an exception will occure. Public Shared Function SeedStringToByteArray(ByVal seed As String, Optional ByRef log As String = Nothing) As Byte() Return BYTE() Parameters Parameter seed Log (Optional) Sample Code Dim bytReturn As Byte() Dim message As String = Winfrasoft.PinGrid.Engine.GenerateCAPMessage(Now, Nothing) Dim userSeed As String = Winfrasoft.PinGrid.Engine.GenerateUserSeed(Winfrasoft.PinGrid.Engine.SeedLength.Bits256) bytReturn = Winfrasoft.PinGrid.Engine.SeedStringToByteArray(userSeed) 'bytReturn = "byte{32}" Type String String Description Seed string to convert to byte array Generates detailed logging from within function. Input Example {B46A972A-97A1-479b-9088F7B659784799} Returns seed string as Byte array.

22 Winfrasoft Technology PINgrid SDK

ValidatePasscode
This function tests the validity of a username and passcode and would typically be used to verify an authentication request. The function takes many elements into account to cater for all the scenarios and states that a user account could be in at the point of validation. Overload allows for different formats of seeds to be specified, allow for processing of pre-sent tokens and their lifespan and to validate a transaction. The seed can be specified as a string to validate against a single seed or an array of seeds (as byte arrays) for processing multiple seeds at once. When processing multiple seeds, as soon as a positive result is found then no further processing occurs. When no preSendToken exists, set this field to Nothing and tokenLifeSpanInMinutes to 0. When processing a ValidatePasscode, if the preSendToken field is populated, the function will first attempt to validate the passcode using the provided preSendToken message. The tokenLifespanInMinutes determines whether or not the preSendToken is still valid. An expired preSendToken will not be successfully validated. Upon preSendToken validation failure, the function then will continue to validate the passcode against any provided array of tokenSeeds. To only validate against a preSendToken, set the array of tokenSeeds to Nothing. Public Shared Function ValidatePasscode(ByVal matrixSize As Integer, ByVal MIP As String, ByVal passcode As String, ByRef lastLogins() As String, ByVal PIN As String, ByVal pinPosition As PinPositions, ByVal MIPToleranceLevel As Integer, ByVal MIPTolerancePeriod As Integer, ByVal tokenSeed As String, ByVal salt As String, ByVal splitPositions As Int32, Optional ByRef log As String = Nothing) As Boolean Public Shared Function ValidatePasscode(ByVal matrixSize As Integer, ByVal MIP As String, ByVal passcode As String, ByRef lastLogins() As String, ByVal PIN As String, ByVal pinPosition As PinPositions, ByVal MIPToleranceLevel As Integer, ByVal MIPTolerancePeriod As Integer, ByVal tokenSeeds()() As Byte, ByVal salt As String, ByVal splitPositions As Int32, ByRef preSendToken As String, ByVal tokenLifeSpanInMinutes As Integer,Optional ByRef log As String = Nothing) As Boolean Return BOOLEAN Parameters Parameter matrixSize MIP passcode lastLogins Type Int32 String String String() Description Number of rows or columns in matrix. Stored hash of MIP. User entered passcode. Array of last known good login messages. Input Example 6 {} 123234513120 {} Returns True if validation was successful, otherwise returns False.

API Interface 23

PIN pinPosition MIPToleranceLevel MIPTolerancePeriod tokenSeed salt

String Engine.PinPositions Int32 Int32 String/Byte()() String

Stored PIN. Enum specifying where PIN must be entered. Defined MIP tolerance level. This is used in 2FA scenarios to cater for time offsets. Defined MIP tolerance period (Minutes). Seed / seeds. Salt value used for MIP hash. This value can be empty. Number of MIP entries to be used in each stored HASH. Large values can increase processing time. 4 is a recommeded value. The CAP Message used when the Pre-send token was originally generated. Lifespan in minutes of pre-send token. Generates detailed logging from within function.

1234 Any = 0, Left = 1 Middle = 2, Right =3 3 2

ThisIsASalt forMIPHashing 4

splitPositions

Int32

preSendToken

String

2012061616510000 1440

tokenLifeSpanInMinutes Int32 Log (Optional) Sample Code Dim booReturn As Boolean String

booReturn = Winfrasoft.PinGrid.Engine.ValidatePasscode(6, "ymwIRbaF0KM1f7TTetZyPZvGYJ8=", "123123", Nothing, "123123", Winfrasoft.PinGrid.Engine.PinPositions.Any, 3, 1, "eb3be655-71ed-4a83-a2ac-ba105e138ae5b2abd837-c47f4bed-8c1c-13825beffb35", "ThisIsSaltforMIPHashing, 4)

'booReturn = False

24 Winfrasoft Technology PINgrid SDK

ConvertGUIDStringtoHEXString
This is primarily an internally used function but may be used externally to support format conversions. Public Shared Function ConvertGUIDStringtoHEXString(ByVal GUIDString As String) As String Return String Parameters Parameter GUIDString Sample Code Dim strReturn As String strReturn = Winfrasoft.PinGrid.Engine.ConvertGUIDStringtoHEXString("eb3be655-71ed-4a83-a2ac-ba105e138ae5b2abd837c47f-4bed-8c1c-13825beffb35") ' ret = "5C6DFBCABD72A34C904D22D720EF6450CAE953ECA8D57F4A8E6E13DC47C06E9C" Type String Description GUID string to convert to byte array. Input Example B46A972A-97A1-479b-9088F7B659784799 Returns GUID string as a HEX string.

API Interface 25

ConvertHEXStringToByteArray
This is primarily an internally used function but may be used externally to support format conversions. Public Shared Function ConvertHEXStringToByteArray(ByVal HEXString As String) As Byte() Return Byte() Parameters Parameter HEXString Sample Code Dim bytReturn() As Byte bytReturn = Winfrasoft.PinGrid.Engine.ConvertHEXStringToByteArray("5C6DFBCABD72A34C904D22D720EF6450CAE953ECA 8D57F4A8E6E13DC47C06E9C") ' bytReturn = byte(32) Type String Description HEX string to convert to byte array. Input Example 5C6DFBCABD72A34C904D22 D720EF6450CAE953ECA8D5 7F4A8E6E13DC47C06E9C Returns HEX string as a Byte array.

26 Winfrasoft Technology PINgrid SDK

ConvertByteArrayToHEXString
This is primarily an internally used function but may be used externally to support format conversions. Private Shared Function ConvertByteArrayToHEXString(ByVal arrByte() As Byte) As String Return String Parameters Parameter HEXString Sample Code Dim strReturn As String Dim bytTemp() As Byte bytTemp = Winfrasoft.PinGrid.Engine.ConvertHEXStringToByteArray("5C6DFBCABD72A34C904D22D720EF6450CAE953ECA 8D57F4A8E6E13DC47C06E9C") strReturn = Winfrasoft.PinGrid.Engine.ConvertByteArrayToHEXString(bytTemp) ' strReturn = "5C6DFBCABD72A34C904D22D720EF6450CAE953ECA8D57F4A8E6E13DC47C06E9C" Type String Description HEX string to convert to byte array. Input Example {}{}{}{} Returns HEX string from Byte Array.

API Interface 27

Winfrasoft.PinGrid.Graphics Namespace Interface

The Graphics class produces a Blank Matrix or a populated Challenge Matrix and returns a System.Drawing.Bitmap image with transparency to a size based on received values. The following information details the inputs to produce a .NET function that generates a populated Challenge Matrix similar to IMAGE1. IMAGE2 shows a Blank Matrix. IMAGE 1 IMAGE 2

This image is an example of a 6 by 6 matrix, however the generated matrix may also be 8 by 8. Matrix 6x6 Challenge Matrix 8x8 Challenge Matrix 6x6 Blank Matrix 8x8 Blank Matrix Description 4 quadrants consisting of 3 by 3 matrix. Cells are populated with CAP. 4 quadrants consisting of 4 by 4 matrix. Cells are populated with CAP. 4 quadrants consisting of 3 by 3 matrix. Cells are blank. 4 quadrants consisting of 4 by 4 matrix. Cells are blank.

The aspect ratio of the generate graphic is 1:1, i.e. a square.

28 Winfrasoft Technology PINgrid SDK

Declaration
Dim PINgridGraphics As Winfrasoft.PinGrid.Graphics PINgridGraphics = New Winfrasoft.PinGrid.Graphics(. . .)

Constructors
Using the Properties, a user can declare the Image DPI and set the colours dynamically. If custom colours are not specified then the PINgrid default matrix theme and colours are used. Public Sub New(ByVal matrixSizeDPI As Integer) Public Sub New(ByVal matrixTheme As MatrixThemes, ByVal matrixSizeDPI As Integer, ByVal matrixColourQuadrant1 As Integer, ByVal matrixColourQuadrant2 As Integer, ByVal matrixColourQuadrant3 As Integer, ByVal matrixColourQuadrant4 As Integer)

Methods Overview
Function GenerateMatrix Return Type System.Drawing.Bitmap Description This function generates a Challenge Matrix as seen in Image1 and Image2.

Properties Overview
All exposed Properties are both Read and Write. These properties determine the characteristics of the Matrix displayed.
Function matrixTheme matrixSizeDPI matrixColourQuadrant1 matrixColourQuadrant2 matrixColourQuadrant3 matrixColourQuadrant4 Type Description

MatrixThemes Enum setting the background graphic to be Black, Translucent or Clear. Default = Black
Integer Integer Integer Integer Integer Set the Horizontal and Vertical Dots Per Inch for image. Set the colour for Matrix Quadrant 1 top left. Set the colour for Matrix Quadrant 2 top right. Set the colour for Matrix Quadrant 3 bottom left. Set the colour for Matrix Quadrant 4 bottom right.

API Interface 29

Method Specifications
GenerateMatrix
Overloaded function that generates the Challenge Matrix. Public Function GenerateMatrix(ByVal matrixSize As Integer) As System.Drawing.Bitmap Public Function GenerateMatrix(ByVal CAP As String) As System.Drawing.Bitmap Return SYSTEM.DRAWING.BITMAP Parameters Parameter matrixSize CAP Sample Code Dim PINgridGraph As Winfrasoft.PinGrid.Graphics Dim imageMatrix As System.Drawing.Bitmap PINgridGraph = New Winfrasoft.PinGrid.Graphics(200) imageMatrix = PINgridGraph.GenerateMatrix("210125201125143520235040513434504433") 'see Image1 PINgridGraph = New Winfrasoft.PinGrid.Graphics(200) imageMatrix = PINgridGraph.GenerateMatrix(6) 'see Image2 Type Integer String Description Input Example Returns Challenge Matrix or Blank Matrix.

Number of rows in Matrix. By setting a size for 6 Matrix, you will receive a Blank Matrix. See IMAGE 2 Challenge Authentication Prompt to be plotted 21012520112514352023 within the Matrix. Starting at top left. See IMAGE 1 5040513434504433

30 Winfrasoft Technology PINgrid SDK

Sample Application
Provided below is a sample application that details the minimum requirements required to utilise the PINgrid SDK and generate Challenge matrices for users and validate their responses. The code for this sample is provided as is within the SDK and is written in VB.NET using Visual Studio 2008. Project Settings: Create a Windows Application solution with a single Windows Form called Form1. On the Form - add: Reference to Winfrasoft.PinGrid.dll Buttons for Generate Challenge Matrix btnChallenge and Validate Username btnValidate 2 text boxes txtUsername and txtPasscode Picturebox picImage

For the purposes of this sample application, we do not have a repository or directory that stores User details and PINgrid settings, instead we utilise some basic structures to mimic that of a user as well as configurable options used to govern the PINgrid challenge image. The matrices we are displaying are all 6x6 with a 6 digit OTP and a 4 digit static PIN. Within the Public class Form1, we declare our public and private variables and structures. Constant We declare an InvalidUserMask based on a double GUID that we XOR with the username to generate a seed for invalid users. By performing this operation and generating a matrix, invalid usernames that do not have a seed will still appear to operate as if they were valid user accounts. This means that hackers would not be able to distinguish between valid and invalid accounts. Const InvalidUserMask As String = "F8BAC04A-6C1F-4e49-835B-D7612076E82B7E3DCECF-EB1A-4ca3-8620-DE379B9A2008" Global Structures and variables The 2 structures below mimic the settings stores User repository and PINgrid application settings which control the matrix display and usage characteristics. Const Const Const Const FakeDeviceTypeSeed As String = "A3E1FE93-04C9-48A1-9E99-F3255BE5054E6D33CF18-E758-4BBE-B586-57A04B00C95D" InvalidUserMask As String = "F8BAC04A-6C1F-4e49-835B-D7612076E82B7E3DCECF-EB1A-4ca3-8620-DE379B9A2008" Salt As String = "PINgridSDKMIPHashSaltValue" SplitPositions As Integer = 4

Structure User Dim userName As String Dim matrixSize As Integer Dim seed As String

API Interface 31

Dim pinCode As String Dim MIP As String Dim lastLoginAttempt() As String End Structure Structure GlobalSettings Dim matrixTheme As MatrixThemes Dim matrixSize As Integer Dim matrixSizeHDPI As Integer Dim colourQuadrant1 As Integer Dim colourQuadrant2 As Integer Dim colourQuadrant3 As Integer Dim colourQuadrant4 As Integer Dim ToleranceLevel As Integer Dim TolerancePeriod As Integer End Structure Private Private Private Private _PinGridImage As Winfrasoft.PinGrid.Graphics _myGlobals As GlobalSettings _validUserBob As User _validUserFred As User

Public Enum MatrixThemes Black = 0 Translucent = 1 Clear = 2 End Enum Form Load and User Initialisation Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load ' Configure the PINgrid shield settings _myGlobals.matrixTheme = MatrixThemes.Black ' Configure the PINgrid background image theme _myGlobals.matrixSizeHDPI = 250 _myGlobals.colourQuadrant1 = -65536 _myGlobals.colourQuadrant2 = -16711936

32 Winfrasoft Technology PINgrid SDK

_myGlobals.colourQuadrant3 = -16744193 _myGlobals.colourQuadrant4 = -256 _myGlobals.matrixSize = 6 _myGlobals.ToleranceLevel = 3 _myGlobals.TolerancePeriod = 1 InitialiseUsers() ' Display a blank image using the settings provided above _PinGridImage = New Winfrasoft.PinGrid.Graphics(_myGlobals.matrixTheme, _myGlobals.matrixSizeHDPI, _myGlobals.colourQuadrant1, _myGlobals.colourQuadrant2, _ _myGlobals.colourQuadrant3, _myGlobals.colourQuadrant4) picImage.Image = _PinGridImage.GenerateMatrix(_myGlobals.matrixSize) End Sub

API Interface 33

Private Sub InitialiseUsers() Dim mip As String ' This is the original mip pattern co-ordinates. This is the top line and second line of the 1st quadrant in a 6x6 matrix Dim lastLogins(100) As String ' Create an empty list of lastLogins For i As Integer = 0 To lastLogins.Count - 1 lastLogins(i) = "" Next ' Initialise a Valid user mip = "1,2,3,7,8,9" _validUserBob.userName = "bob" _validUserBob.MIP = Winfrasoft.PinGrid.Engine.GetMIPHash(mip, Salt, SplitPositions) _validUserBob.matrixSize = 6 _validUserBob.pinCode = "1234" _validUserBob.seed = Winfrasoft.PinGrid.Engine.GenerateUserSeed(Winfrasoft.PinGrid.Engine.SeedLength.Bits256) _validUserBob.lastLoginAttempt = lastLogins ' Initialise a Valid user mip = "4,5,6,10,11,12" _validUserFred.userName = "fred" _validUserFred.MIP = Winfrasoft.PinGrid.Engine.GetMIPHash(mip, Salt, SplitPositions) _validUserFred.matrixSize = 6 _validUserFred.pinCode = "4321" _validUserFred.seed = Winfrasoft.PinGrid.Engine.GenerateUserSeed(Winfrasoft.PinGrid.Engine.SeedLength.Bits256) _validUserFred.lastLoginAttempt = lastLogins End Sub

34 Winfrasoft Technology PINgrid SDK

Generate User Challenge Matrix Private Sub btnChallenge_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles btnChallenge.Click Dim CAP As String Dim message As String Dim tSeed As Byte() ' For the purposes of this sample, bob and fred are valid users. Anyone else in invalid. If txtUsername.Text = "bob" Then ' We utilise the settings for bob generating the matrix message = Winfrasoft.PinGrid.Engine.GetMessage(Now(), _validUserBob.lastLoginAttempt) ' Determine the message for CAP generation If String.IsNullOrEmpty(txtTransactionData.Text) Then CAP = Winfrasoft.PinGrid.Engine.GenerateCAP(_myGlobals.matrixSize, message, _validUserBob.seed) 'Create CAP using message and users seed Else ' As there is some transaction data we must calculate the seed to be used. tSeed = Winfrasoft.PinGrid.Engine.GetDeviceSeed(FakeDeviceTypeSeed, "DemoHardwareID") tSeed = Winfrasoft.PinGrid.Engine.GetTransactionSeed(tSeed, txtTransactionData.Text) CAP = Winfrasoft.PinGrid.Engine.GenerateCAP(_myGlobals.matrixSize, message, tSeed) End If ElseIf txtUsername.Text = "fred" Then ' We utilise the settings for bob generating the matrix message = Winfrasoft.PinGrid.Engine.GetMessage(Now(), _validUserFred.lastLoginAttempt) If String.IsNullOrEmpty(txtTransactionData.Text) Then CAP = Winfrasoft.PinGrid.Engine.GenerateCAP(_myGlobals.matrixSize, message, _validUserFred.seed) Else ' As there is some transaction data we must calculate the seed to be used. tSeed = Winfrasoft.PinGrid.Engine.GetDeviceSeed(FakeDeviceTypeSeed, "DemoHardwareID") tSeed = Winfrasoft.PinGrid.Engine.GetTransactionSeed(tSeed, txtTransactionData.Text) CAP = Winfrasoft.PinGrid.Engine.GenerateCAP(_myGlobals.matrixSize, message, tSeed) End If ElseIf txtUsername.Text <> "" Then Dim lastLogins As String()

API Interface 35

' This is an invalid account so we will reject the settings, however we must mimic the input to appear that the user is valid and to do so ' we will need a fake seed message = Winfrasoft.PinGrid.Engine.GetMessage(Now(), lastLogins) ' tSeed = GetFakeSeed(txtUsername.Text) CAP = Winfrasoft.PinGrid.Engine.GenerateCAP(_myGlobals.matrixSize, message, tSeed) End If ' If we have user information, show the CAP If txtUsername.Text = "" Then picImage.Image = _PinGridImage.GenerateMatrix(_myGlobals.matrixSize) Else ' Display the generated CAP picImage.Image = _PinGridImage.GenerateMatrix(CAP) End If End Sub Validate Passcode Private Sub btnValidate_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles btnValidate.Click Dim currentUser As User Dim validUser As Boolean Dim tSeed As Byte() ' We now try validate the passcode. If empty then respond as failure If txtPasscode.Text = "" Then MsgBox("No passcode entered. Authentication failed.", MsgBoxStyle.Exclamation, "PINgrid Authentication failure") Exit Sub End If ' Load the appropriate user information into the current user package for Evaulation If txtUsername.Text = "bob" Then currentUser = _validUserBob ElseIf txtUsername.Text = "fred" Then currentUser = _validUserFred Else

36 Winfrasoft Technology PINgrid SDK

' User doesnt exist so exit MsgBox("No username entered. Authentication failed.", MsgBoxStyle.Exclamation, "PINgrid Authentication failure") Exit Sub End If If String.IsNullOrEmpty(txtTransactionData.Text) Then ' A valid user has been entered. Attempt passcode validation. validUser = Winfrasoft.PinGrid.Engine.ValidatePasscode(currentUser.matrixSize, currentUser.MIP, txtPasscode.Text, currentUser.lastLoginAttempt, _ currentUser.pinCode, Winfrasoft.PinGrid.Engine.PinPositions.Any, _myGlobals.ToleranceLevel, _ _myGlobals.TolerancePeriod, currentUser.seed, Salt, SplitPositions) Else ' As there is some transaction data we must calculate the seed to be used. tSeed = Winfrasoft.PinGrid.Engine.GetDeviceSeed(FakeDeviceTypeSeed, "DemoHardwareID") tSeed = Winfrasoft.PinGrid.Engine.GetTransactionSeed(tSeed, txtTransactionData.Text) ' Create a new array of byte array containing a single seed Dim tokenSeeds()() As Byte = {tSeed} ' A valid user has been entered. Attempt passcode validation using the device and transaction based seed. validUser = Winfrasoft.PinGrid.Engine.ValidatePasscode(currentUser.matrixSize, currentUser.MIP, txtPasscode.Text, currentUser.lastLoginAttempt, _ currentUser.pinCode, Winfrasoft.PinGrid.Engine.PinPositions.Any, _myGlobals.ToleranceLevel, _ _myGlobals.TolerancePeriod, tokenSeeds, Salt, SplitPositions, "", 0) End If

' When passed, the lastLoginAttempt will now have the last message showing as a valid login. Typically we would save the changes to the repository ' that stores your user accounts. If validUser Then

API Interface 37

If txtUsername.Text = "bob" Then _validUserBob = currentUser ElseIf txtUsername.Text = "fred" Then _validUserFred = currentUser End If MsgBox("Your passcode entered is correct.") Else MsgBox("The passcode entered is incorrect. Validation FAILED!") End If End Sub