Innovative Technology Ltd

Derker Street, Oldham,

OL1 4EQ.
T: +44 161 626 9999
F: +44 161 620 2090
W: www.innovative-technology.co.uk

MICROSOFT VISUAL BASIC 6 – ITL SSP DLL USAGE

This note details the structures and methods needed to communicate in SSP using the Innovative Technology DLL (ITLSSPProc.DLL).

Data Structures
The following data structures need to be declared, usually in a module. These match the data structures used in the DLL.

Public Type EightByteNumber Public Type SSP_PACKET

LoValue As Long PacketTime As Integer
Hivalue As Long PacketLength As Byte
End Type PacketData(254) As Byte
End Type
Public Type SSP_KEYS
Generator As EightByteNumber Public Type SSP_COMMAND_INFO
Modulus As EightByteNumber CommandName As String
HostInter As EightByteNumber LogFileName As String
HostRandom As EightByteNumber Encrypted As Byte
SlaveInterKey As EightByteNumber Transmit As SSP_PACKET
SlaveRandom As EightByteNumber Recieve As SSP_PACKET
KeyHost As EightByteNumber PreEncryptTransmit As SSP_PACKET
End Type PreEncryptRecieve As SSP_PACKET
End Type
Public Type SSP_FULL_KEY
FixedKeyLowValue As Long
FixedKeyHighValue As Long
EncryptKeyLowValue As Long
EncryptkeyHighValue As Long
End Type
Public Type SSP_COMMAND Public Type PORT_CONFIG
Key As SSP_FULL_KEY NumberOfPorts As Byte
BaudRate As Long PortID(1) As Byte
timeout As Long BaudRate(1) As Byte
PortNumber As Byte End Type
sspAddress As Byte
RetryLevel As Byte
EncryptionStatus As Byte
CommandDataLength As Byte
CommandData(254) As Byte
ResponseStatus As Byte
ResponseDataLength As Byte
ResponseData(254) As Byte
ignoreerror As Byte
End Type

Linking to DLL Methods

Public Declare Function TestSSPSlaveKeys Lib "ITLSSPProc.dll" (ByRef Key As SSP_KEYS) As Integer
Public Declare Function CreateSSPHostEncryptionKey Lib "ITLSSPProc.dll" (ByRef Key As SSP_KEYS) As Integer
Public Declare Function SSPSendCommand Lib "ITLSSPProc.dll" (ByRef sspc As SSP_COMMAND, _
ByRef sspInfo As SSP_COMMAND_INFO) As Integer
Public Declare Function OpenSSPMulipleComPorts Lib "ITLSSPProc.dll" (ByRef sspc As SSP_COMMAND) As Integer
Public Declare Function CloseSSPMultiplePorts Lib "ITLSSPProc.dll" () As Integer
Public Declare Function InitiateSSPHostKeys Lib "ITLSSPProc.dll" (ByRef Key As SSP_KEYS, _
ByRef sspc As SSP_COMMAND) As Integer

Initialising SSP_COMMAND
Declare a globally accessible SSP_COMMAND instance for each device. Initialise the SSP_COMMAND as follows:
Public sspHopper As SSP_COMMAND
...
sspHopper.sspAddress = 16 'example only – provide the actual address. Default Hopper = 0x10 [16], Payout = 0x00
sspHopper.PortNumber = 5 '5 is an example – provide the actual port number, however you store it
sspHopper.BaudRate = 9600
sspHopper.RetryLevel = 3
sspHopper.timeout = 1000
sspHopper.ignoreerror = 1
An SSP_COMMAND_INFO also needs to be declared to pair with SSP_COMMAND.
Public sspHopperInfo As SSP_COMMAND_INFO
Handling Ports
Create a PORT_CONFIG instance and initialise it during your program initialisation/setup. This example assumes you have a SMART
Hopper and SMART Payout connected to COM port 4 and 6 respectively. It also assumes you have a sspHopper and sspPayout instance
of SSP_COMMAND structure which contain relevant the port number. Setting up the SSP_COMMAND structure is detailed above.
Dim ports As PORT_CONFIG

ports.NumberOfPorts = 2
ports.PortID(0) = sspPayout. PortNumber
ports.BaudRate(0) = sspPayout.BaudRate
ports.PortID(1) = sspHopper. PortNumber
ports.BaudRate(1) = sspHopper.BaudRate

The DLL method to open COM ports can be called with the PORT_CONFIG instance set-up above.
Public Function OpenCommunicationPorts(p As PORT_CONFIG) As Boolean

If OpenSSPMulipleComPorts (p) = 0 Then

' Error
Exit Function
End If

OpenCommunicationPorts = True

End Function

To close all open ports, the following DLL call can be used. No arguments are required.
Public Function CloseCommunicationPorts() As Boolean

CloseSSPMultiplePorts
CloseCommunicationPorts = True

End Function
Sending a Command
Commonly this is the basic function that should be declared in a module to send a command and do some checking of the response. In
this method any logging required can be added.
Public Function TransmitSSPCommand(sspc As SSP_COMMAND, sspInfo As SSP_COMMAND_INFO) As Boolean
If sspc.EncryptionStatus Then
If sspc.Key.EncryptkeyHighValue = 0 And sspc.Key.EncryptKeyLowValue = 0 Then
MsgBox "The host has no key set", vbExclamation, App.ProductName
Exit Function
End If
End If

Call SSPSendCommand(sspc, sspInfo)

DoEvents

If sspc.ResponseStatus <> ssp_reply_ok Then

MsgBox "SSP error", vbExclamation, App.ProductName
Exit Function
End If

If sspc.ResponseData(0) <> OK Then

MsgBox "Non OK response to command", vbExclamation, App.ProductName
Exit Function
End If

TransmitSSPCommand = True

End Function

This method is then called as follows in the main code:

sspc.CommandDataLength = 1
sspc.EncryptionStatus = 0
sspc.CommandData(0) = SYNC_CMD
If Not TransmitSSPCommand(sspc, sspInfo) Then Exit Function

Here, sspc is the SSP_COMMAND data structure for the unit being communicated to. SYNC_CMD is defined as:
Public Const SYNC_CMD = &H11
Checking Response
For some commands it is required to get information returned. This is taken from the ResponseData array in the SSP_COMMAND
instance.
Dim RejectReason As Byte
sspc.CommandDataLength = 1
sspc.CommandData(0) = cmd_GET_REJECT_REASON ' cmd_GET_REJECT_REASON is defined as 0x17
sspc.EncryptionStatus = 1
If Not TransmitSSPCommand(sspc, sspInfo) Then Exit Function
If sspc.ResponseDataLength = 1
RejectReason = sspc.ResponseData(1)
End If

Key Negotiation
Public Function NegotiateKeyExchange(sspc As SSP_COMMAND, sspInfo As SSP_COMMAND_INFO) As Boolean
Dim sspKey As SSP_KEYS
Dim i As Integer

' If not defined elsewhere, commands need to be declared

Public Const cmd_SSP_SET_GENERATOR = &H4A
Public Const cmd_SSP_SET_MODULUS = &H4B
Public Const cmd_SSP_REQ_KEY_EXCHANGE = &H4C

' DLL call to create Modulus, Generator and Host inter numbers
If InitiateSSPHostKeys(sspKey, sspc) = 0 Then
MsgBox "Error initiating host key modulus or generator values set to zero", _
vbExclamation, App.ProductName
Exit Function
End If

sspc.CommandDataLength = 1
sspc.EncryptionStatus = 0
sspc.CommandData(0) = SYNC_CMD
If Not TransmitSSPCommand(sspc, sspInfo) Then Exit Function

sspc.CommandDataLength = 9
sspc.CommandData(0) = cmd_SSP_SET_GENERATOR
For i = 0 To 3
sspc.CommandData(1 + i) = CByte(RShift(sspKey.Generator.LoValue, 8 * i) And &HFF)
sspc.CommandData(5 + i) = CByte(RShift(sspKey.Generator.Hivalue, 8 * i) And &HFF)
Next I
 If Not TransmitSSPCommand(sspc, sspInfo) Then Exit Function
sspc.CommandDataLength = 9
sspc.CommandData(0) = cmd_SSP_SET_MODULUS
For i = 0 To 3
sspc.CommandData(1 + i) = CByte(RShift(sspKey.Modulus.LoValue, 8 * i) And &HFF)
sspc.CommandData(5 + i) = CByte(RShift(sspKey.Modulus.Hivalue, 8 * i) And &HFF)
Next i
If Not TransmitSSPCommand(sspc, sspInfo) Then Exit Function

sspc.CommandDataLength = 9
sspc.CommandData(0) = cmd_SSP_REQ_KEY_EXCHANGE
For i = 0 To 3
sspc.CommandData(1 + i) = CByte(RShift(sspKey.HostInter.LoValue, 8 * i) And &HFF)
sspc.CommandData(5 + i) = CByte(RShift(sspKey.HostInter.Hivalue, 8 * i) And &HFF)
Next i
If Not TransmitSSPCommand(sspc, sspInfo) Then Exit Function

sspKey.SlaveInterKey.LoValue = 0
sspKey.SlaveInterKey.Hivalue = 0
For i = 0 To 3
sspKey.SlaveInterKey.LoValue = sspKey.SlaveInterKey.LoValue + _
(CLng(sspc.ResponseData(1 + i)) * (256 ^ i))
sspKey.SlaveInterKey.Hivalue = sspKey.SlaveInterKey.Hivalue + _
(CLng(sspc.ResponseData(5 + i)) * (256 ^ i))
Next i

' we can now calculate our host key using the DLL method
If CreateSSPHostEncryptionKey(sspKey) = 0 Then
MsgBox "Error creating host key", vbExclamation, App.ProductName
Exit Function
End If

sspc.Key.EncryptKeyLowValue = sspKey.KeyHost.LoValue
sspc.Key.EncryptkeyHighValue = sspKey.KeyHost.Hivalue

NegotiateKeyExchange = True
End Function