Winfrasoft PINgrid Software Development Kit for Microsoft .NET (2.5.3510)

© 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.

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: [email protected]

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.


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# - using Winfrasoft.PinGrid;

VB.NET - 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 Return Type Description

CheckPatternComplexity Boolean This function tests the users entered MIP to see if it is sufficiently

complex depending on the administrator set complexity tests specified.

GetDateTime String Returns the Current Systems UTC time in the format yyyyMMddHHmm

GetMIPHash String Convert a pattern split into sections depending on the SplitPositions

Variable and return an encoded MIP.

GenerateCAP String Generates a CAP based on the matrixSize, message and seed as a byte array.

GetMessage String Builds a CAP Message based on the timeframe and lastLoginsarray.

GenerateRandomMIP String Generates a random MIP for user and return the co-ordinates encoded.

e.g.1,2,3,4,5,6

GenerateRandomPIN String Returns a Random PIN for a user. The returned PIN will only return values

that are found within the Code String.

GenerateUserSeed String Returns a random unique single or double GUID as a string for the users MIP

Seed based on the specified bit length.


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.

SeedStringToByteArray Byte() Receives a single or double GUID string or 128Bit or 256Bit HEX String and

returns a Byte array.

ValidatePasscode Boolean

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.

ConvertGUIDStringtoHEXString String Converts a GUID string to HEX string.

ConvertHEXStringToByteArray Byte() Converts a HEX string into a Byte Array.

ConvertByteArrayToHEXString String Converts a Byte Array to HEX 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 Returns True or False. True when inserted MIP passes complexity checks. False when MIP fails checks.

Parameters

Parameter Type Description Input Example

MIP String MIP to be validated. 1,2,4,6,8,7

matrixSize Int32 Number of columns in pattern’s. 6

validityCheck PatternValidityTests Select the ValidityTest to test

pattern against.

None = 0

BlockSequentialStraightLines = 1

BlockSinglePlane = 2

RestrictSequentialLinearAdjacencies= 4

RestrictCellRepeatUsage = 8

value (Overloaded) Int32 Some validity tests require a

parameter values.

Builds a CAP Message based on the timeframe

and lastLoginsarray

Log (Optional) String Generates detailed logging from

within function.


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 Returns UTC in yyyyMMddHHmm format i.e. 201105231608

Parameters


timeFrame (Overloaded) Date Date and time which will be translate to

yyyyMMddHHmm format. 23-05-2011 16:08:02

Log (Optional) String Generates detailed logging from within function.

Sample Code

Dim strReturn As String

strReturn = Winfrasoft.PinGrid.Engine.GetDateTime()

'strReturn = "201106101022"


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 Returns the hash of the MIP using FIPS compliant algorithms.

Parameters


MIP String MIP to be hashed. 1,2,4,6,8,7

salt String Salt value used for MIP hash. This value can be empty. ThisIsSalt

forMIPHashing

splitPositions Int32 Number of MIP positions to separated into subsections for

speed of computation. 5


Sample Code


strReturn = Winfrasoft.PinGrid.Engine.GetMIPHash("1,2,3,4,5,6", "ThisIsSaltforMIPHashing", 5)

'strReturn = "gxOh7TIXERVO9rwRdq/BKs5BrjY=6dcfXufJLW3J6S/9rRe4vUlBj5g="

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() Returns the device seed as a byte array based on device type and unique hardware information.

Parameters


deviceTypeSeed String Device specific seed. Aabc789a-99bd-5cb2-

904d-22d720ef6450

Bb23e2bc-d5a8-4a7f-

8e6e-13dc47c06e9c

hardwareInfo String The unique hardware information i.e. Serial Number 51HLP3G

remoteSeed String Optional 10 char value to bi-directionally link the user and

the token 1234567890

Sample Code

Dim bytReturn As Byte()

bytReturn = Winfrasoft.PinGrid.Engine.GetDeviceSeed("Aabc789a-99bd-5cb2-904d-22d720ef6450Bb23e2bc-d5a8-4a7f-

8e6e-13dc47c06e9c", "51HLP3G", "1234567890")

'bytReturn = 154, 120, 188, 170, 189 ……, 112, 248, 87, 172


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() Returns the device seed as a byte array based on device type and unique hardware information.

Parameters


deviceSeed Byte() 256bit Device seed, e.g. result from GetDeviceSeed(). {23,64,26,…45,132}

transactionData String

Information specific to a transaction or workflow

process. NB: Only the first 32 characters will be

processed, anything further will be truncated.

Acc:59761486486224

Sample Code


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,


Public Shared Function GenerateCAP(ByVal matrixSize As Integer, ByVal message As String, ByVal seed As String,


Return STRING Returns valid digits for a CAP.

Parameters


matrixSize Integer Size of the matrix for the CAP. 6 or 8

message String HMACSHA256 message used for encryption. 2011052316080000

seed Byte() or String

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.

Byte Array [32]


Sample Code


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"


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 Returns CAP Message to be used as input for GenerateCAP function , message parameter.

Parameters


timeFrame Date Date and time. 23-05-2011 16:08:02

lastLoginsAttempts String() Array of Messages used for previous valid login

attempts. 2011052316080000


Sample Code


strReturn = Winfrasoft.PinGrid.Engine.GetMessage(Now, Nothing)

'return = "2011061010320000"

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 Returns a randomly Generated MIP.

Parameters


matrixSize Int32 Number of rows in Matrix. 6

MIPLength Int32 Length of MIP to generate. 6

blockSequentialLines Boolean Enforce policy for restriction. True

blockSinglePlane Boolean Enforce policy for restriction. True

restrictCellRepeatUsage Boolean Enforce policy for restriction. True

restrictSequentialLinearAdjacencies Boolean Enforce policy for restriction. True

restrictCellRepeatParam Int32 Parameter for Cell Repeats restriction. 2

restrictSequentialLinearAdjParam Int32 Parameter for Seq linear adj restriction. 3


Sample Code


strReturn = Winfrasoft.PinGrid.Engine.GenerateRandomMIP(6, 6)

'strReturn = "26,9,32,8,2,3"


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 Returns a randomly generated PIN.

Parameters


matrixSize Int32 Number of columns or rows in Matrix. 6

PINLength Int32 Length of PIN to generate. 4

require2FA Boolean 2FA pins are not limited to values that exist with matrix

range. False


Sample Code


strReturn = Winfrasoft.PinGrid.Engine.GenerateRandomPIN(6, 4, False)

'strReturn = "0411"

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 Returns randomly generated user seed in ether 128 Bit or 256 Bit.

Parameters


seedLength Engine.SeedLength 128 Bit or 256 Bit seed. Engine.SeedLength.Bits128

Engine.SeedLength.Bits256

Log (Optional) String Generates detailed logging from within

function.

Sample Code


strReturn = Winfrasoft.PinGrid.Engine.GenerateUserSeed(Winfrasoft.PinGrid.Engine.SeedLength.Bits256)

'strReturn = "eb3be655-71ed-4a83-a2ac-ba105e138ae5b2abd837-c47f-4bed-8c1c-13825beffb35"


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 Code String.

Parameters


message String Message for HMAC function 2011052316080000

seed String/GUID/Byte() Seed for HMAC function Byte Array [32]


Sample Code


Dim message As String = Winfrasoft.PinGrid.Engine.GenerateCAPMessage(Now, Nothing)


strReturn = Winfrasoft.PinGrid.Engine.GenerateCodeString(message, userSeed)

'strReturn = "197722411431421132366712110502541021937716022170159128181602122418219011019836125134"

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() Returns seed string as Byte array.

Parameters


seed String Seed string to convert to byte array {B46A972A-97A1-479b-9088-

F7B659784799}


Sample Code


Dim message As String = Winfrasoft.PinGrid.Engine.GenerateCAPMessage(Now, Nothing)


bytReturn = Winfrasoft.PinGrid.Engine.SeedStringToByteArray(userSeed)

'bytReturn = "byte{32}"


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 Returns True if validation was successful, otherwise returns False.

Parameters


matrixSize Int32 Number of rows or columns in matrix. 6

MIP String Stored hash of MIP. {}

passcode String User entered passcode. 123234513120

lastLogins String() Array of last known good login messages. {}

API Interface 23

PIN String Stored PIN. 1234

pinPosition Engine.PinPositions Enum specifying where PIN must be entered. Any = 0, Left = 1

Middle = 2, Right =3

MIPToleranceLevel Int32 Defined MIP tolerance level. This is used in 2FA

scenarios to cater for time offsets. 3

MIPTolerancePeriod Int32 Defined MIP tolerance period (Minutes). 2

tokenSeed String/Byte()() Seed / seeds.

salt String Salt value used for MIP hash. This value can be

empty.

ThisIsASalt

forMIPHashing

splitPositions Int32

Number of MIP entries to be used in each

stored HASH. Large values can increase processing

time. 4 is a recommeded value.

4

preSendToken String The CAP Message used when the Pre-send token was

originally generated. 2012061616510000

tokenLifeSpanInMinutes Int32 Lifespan in minutes of pre-send token. 1440


Sample Code

Dim booReturn As Boolean

booReturn = Winfrasoft.PinGrid.Engine.ValidatePasscode(6, "ymwIRbaF0KM1f7TTetZyPZvGYJ8=", "123123", Nothing,

"123123", Winfrasoft.PinGrid.Engine.PinPositions.Any, 3, 1, "eb3be655-71ed-4a83-a2ac-ba105e138ae5b2abd837-c47f-

4bed-8c1c-13825beffb35", "ThisIsSaltforMIPHashing, 4)

'booReturn = False


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 Returns GUID string as a HEX string.

Parameters


GUIDString String GUID string to convert to byte array. B46A972A-97A1-479b-9088-

F7B659784799

Sample Code


strReturn = Winfrasoft.PinGrid.Engine.ConvertGUIDStringtoHEXString("eb3be655-71ed-4a83-a2ac-ba105e138ae5b2abd837-

c47f-4bed-8c1c-13825beffb35")

' ret = "5C6DFBCABD72A34C904D22D720EF6450CAE953ECA8D57F4A8E6E13DC47C06E9C"

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() Returns HEX string as a Byte array.

Parameters


HEXString String HEX string to convert to byte array.

5C6DFBCABD72A34C904D22

D720EF6450CAE953ECA8D5

7F4A8E6E13DC47C06E9C

Sample Code

Dim bytReturn() As Byte

bytReturn = Winfrasoft.PinGrid.Engine.ConvertHEXStringToByteArray("5C6DFBCABD72A34C904D22D720EF6450CAE953ECA

8D57F4A8E6E13DC47C06E9C")

' bytReturn = byte(32)


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 Returns HEX string from Byte Array.

Parameters


HEXString String HEX string to convert to byte array. {}{}{}{}

Sample Code


Dim bytTemp() As Byte

bytTemp = Winfrasoft.PinGrid.Engine.ConvertHEXStringToByteArray("5C6DFBCABD72A34C904D22D720EF6450CAE953ECA

8D57F4A8E6E13DC47C06E9C")

strReturn = Winfrasoft.PinGrid.Engine.ConvertByteArrayToHEXString(bytTemp)

' strReturn = "5C6DFBCABD72A34C904D22D720EF6450CAE953ECA8D57F4A8E6E13DC47C06E9C"

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 Description

6x6 Challenge Matrix 4 quadrants consisting of 3 by 3 matrix. Cells are populated with CAP.

8x8 Challenge Matrix 4 quadrants consisting of 4 by 4 matrix. Cells are populated with CAP.

6x6 Blank Matrix 4 quadrants consisting of 3 by 3 matrix. Cells are blank.

8x8 Blank Matrix 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.


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 Return Type Description

GenerateMatrix System.Drawing.Bitmap 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 Type Description

matrixTheme MatrixThemes Enum setting the background graphic to be Black, Translucent or Clear. Default = Black

matrixSizeDPI Integer Set the Horizontal and Vertical Dots Per Inch for image.

matrixColourQuadrant1 Integer Set the colour for Matrix Quadrant 1 – top left.

matrixColourQuadrant2 Integer Set the colour for Matrix Quadrant 2 – top right.

matrixColourQuadrant3 Integer Set the colour for Matrix Quadrant 3 – bottom left.

matrixColourQuadrant4 Integer 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 Returns Challenge Matrix or Blank Matrix.

Parameters


matrixSize Integer Number of rows in Matrix. By setting a size for

Matrix, you will receive a Blank Matrix. See IMAGE 2 6

CAP String Challenge Authentication Prompt to be plotted

within the Matrix. Starting at top left. See IMAGE 1

21012520112514352023

5040513434504433

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


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 FakeDeviceTypeSeed As String = "A3E1FE93-04C9-48A1-9E99-F3255BE5054E6D33CF18-E758-4BBE-B586-57A04B00C95D"

Const InvalidUserMask As String = "F8BAC04A-6C1F-4e49-835B-D7612076E82B7E3DCECF-EB1A-4ca3-8620-DE379B9A2008"

Const Salt As String = "PINgridSDKMIPHashSaltValue"

Const 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 ToleranceLevel As Integer

Dim TolerancePeriod As Integer

End Structure

Private _PinGridImage As Winfrasoft.PinGrid.Graphics

Private _myGlobals As GlobalSettings

Private _validUserBob As User

Private _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.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


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)


CAP = Winfrasoft.PinGrid.Engine.GenerateCAP(_myGlobals.matrixSize, message, _validUserFred.seed)

Else





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)


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


currentUser = _validUserBob


currentUser = _validUserFred

Else


' User doesnt exist so exit

MsgBox("No username entered. Authentication failed.", MsgBoxStyle.Exclamation, "PINgrid Authentication

failure")

Exit Sub

End If


' 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




' 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


_validUserBob = currentUser


_validUserFred = currentUser

End If

MsgBox("Your passcode entered is correct.")

Else

MsgBox("The passcode entered is incorrect. Validation FAILED!")

End If

End Sub

Winfrasoft PINgrid Software Development Kit for Microsoft .NET (2.5.3510)

Documents

Transcript of Winfrasoft PINgrid Software Development Kit for Microsoft .NET (2.5.3510)