manualshive.com logo in svg

SG Intec Ltd & Co KG SG-Lock, Developer'S Manual

Share
Download
SG Intec Ltd & Co KG SG-Lock Developer'S Manual Download Page 42

36

Chapter 4: SG-Lock API

4.6 Return Values

Every SG-Lock API function gives a return value back to the caller, to check if
the function was executed without errors. In the case that an error occured the
return value is unequal to 0. A detailed explanation of the error can be obtained
from the table below.

Name

Value

Description

SGL_SUCCESS

0

Execution without errors

SGL_DGL_NOT_FOUND

1

SG-Lock not found

SGL_AUTHENTICATION

-

_REQUIRED

5

Authentication with SglAuthent()
not or not errorfree processed

SGL_AUTHENTICATION

-

_FAILED

6

Authentification with SglAuthent
failed

SGL_FUNCTION_NOT

-

_SUPPORTED

7

The called function is not sup-
ported by the found SG-Lock.

SGL_PARAMETERS

-

_INVALID

8

Parameter of the called function is
out of the vaild value range.

SGL_SIGNATURE_INVALID

9

Signature invalid

SGL_USB_BUSY

10

Another application is claming
the SG-Lock for more than 5 sec-
onds.

Table 4.1: Return values and description of the SG-Lock-API.

Summary of Contents for SG-Lock

Page 1: ...Copy Protection System Developer Manual for Microsoft Windows XP to 10 all 32 64 bit CE Linux X86 A64 ARM and Mac OS X ...

Page 2: ......

Page 3: ...Copy Protection System Developer Manual for Microsoft Windows XP to 10 all 32 64 bit CE Linux X86 A64 ARM and Mac OS X ...

Page 4: ...mail info sg intec de WEE Reg ID DE 43502119 All information in this manaul are subject to change without notice All trademarks are the prop erties of their respective owners All rights reserved No part of the contents of this book may be reproduced or transmitted in any form or by any means without the written permission of SG Intec Ltd Co KG ...

Page 5: ...Lock Product ID what is it good for 12 3 4 Encryption and Challenge Response Authentication of SG Lock 14 4 SG Lock API 17 4 1 Function summary 17 4 2 Basic functions 19 4 2 1 Function SglAuthent 19 4 2 2 Function SglSearchLock 20 4 2 3 Function SglReadSerialNumber 21 4 3 Extended Function 22 4 3 1 Function SglReadData 22 4 3 2 Function SglWriteData 23 4 3 3 Function SglReadCounter 24 4 3 4 Functi...

Page 6: ...39 6 1 1 C C 39 6 1 2 Delphi 39 6 1 3 Visual Basic 40 6 2 Function SglSearchLock 42 6 2 1 C C 42 6 2 2 Delphi 42 6 2 3 Visual Basic 43 6 3 Function SglReadSerialNumber 44 6 3 1 C C 44 6 3 2 Delphi 44 6 3 3 Visual Basic 45 6 4 Function SglReadData 46 6 4 1 C C 46 6 4 2 Delphi 46 6 4 3 Visual Basic 47 6 5 Function SglWriteData 49 6 5 1 C C 49 6 5 2 Delphi 49 6 5 3 Visual Basic 50 6 6 Challenge Respo...

Page 7: ...whole SG Lock internal memory is transparent for the user encrypted and signed with a unique 128 bit key Hardware attacks like manipulation of single data values or exchange of the whole memory will be detected and prevented Simple and efficient challenge resonse authentication mechanism between protected application and SG Lock API The SG Lock API is not like of ten implemented immediately useabl...

Page 8: ... se cure encryption algorithm is the basis for various implementations of data and code protection as well as authentiction strategies The single SG Lock models are offered in two different shapes which are however functional identical and therefore fully exchangeable The S series is because of the small size espacially suiteable for notebook and tablet computers The U series is approved by its er...

Page 9: ... application has to be protected 2 2 Windows XP to 10 To install SG Lock USB keys process the following 2 steps 1 Copy the SG Lock library SGLW32 DLL 32 or 64 bit version in the Windows system directory for example C WINDOWS SYSTEM32 or into the installation directory of the protected application 2 Plug the SG Lock USB key into the USB port A small window will show up for a short time giving the i...

Page 10: ...Tools SG Lock Application Space Operating System USB Sub System SG Lock API 010111 000110 0101010 110101 Figure 2 1 The SG Lock API the file SGLW32 DLL establishes the connec tion between protected application and SG Lock hardware ...

Page 11: ...egistry script SGLUSB REG ac cording the path of SGLUSB DLL if e g your SGLUSB DLL resides in Storage change the values of both keys to Storage SGLUSB DLL Do not use a preceding backslash Leave the keys PREFIX unchanged 4 Execute the adjusted registry script and save the registry e g with the AP CONFIG MANAGER in file card APSystem button STORAGE REG ISTRY SAVE to keep the configuration for furthe...

Page 12: ...ock moduls Run the SGLMGR by starting the file SglMgr Exe in the directory Test The index card Options offers to change the language with Select Language Ad ditionally the number radix can be changed between decimal and hexadecimal representaton This has also to be taken into account when entering numbers All functions that the SGLMGR offers are part of the SG Lock API and can ...

Page 13: ...d version numbers of the attached SG Lock With the push button Write Product ID the value can be altered between 0 and 65535 dec The function of the product id is described in detail in chapter 3 3 The index card Memory makes it possible to read and write the modul internal memory when existing For changing one or more data values they have to be entered into the table and by pushing the push butt...

Page 14: ...are not located in the data memory area but use additional memory which excludes side effects Index card Cryptography offers the possibilty to use the cryptographic functions of SG Lock SG Lock uses a modul internal symmetric i e the keys for encryp tion and decryption are identical 128 bit encryption The data block length is 64 bit and the algorithm is TEA The SG Lock series 3 and 4 have multiple...

Page 15: ... Generate Random Key a 128 bit key can be generated automaticly It can be proccessed further over the clipboard e g for documentation purposes this is recommended because the key can not be read for security reasons For testing the encryption engine two 32 bit values which are equivalent to one 64 bit block can be entered into the fields Input Data By pressing Encrypt or Decrypt Data the 64 bits i...

Page 16: ... also hexadecimal without leading or trailing special characters Attention The input of an authent code AC is necessary when not demo re tail SG Lock moduls are used Without entering a authent code only demo moduls will be detected Every software manufacturer that uses SG Lock gets ones with the first dilivery his individual AC The AC is presented in hexadec imal style the number radix has to be a...

Page 17: ...d 3 2 Protection Strategies The most frequently applied type of protection of software against illegal use is the simple run or run not copy protection that avoids that the software runs on more PCs than paid for In this case the repeatedly test whether the copy protection key is installed on the PC or not is the main task Other protection strategies shall allow the software to run only a limited ...

Page 18: ...otection key the programmer has to regard that an installed copy protection key is valid for the software just running and not for some of the other products they are also selling That is additional administrative work and an additional source of error SG Lock solves this with the Product ID Every software product and the be longing SG Locks get their own Product ID e g software A gets Product ID ...

Page 19: ...C X PID 1 AC X PID 3 AC X PID 2 Company Y AC Y AC X SG Lock SG Lock AC X SG Lock SG Lock AC Y SG Lock SG Lock AC X SG Lock SG Lock SG Lock API 010111 000110 0101010 110101 Figure 3 1 The SG Lock ProductId allows an easy separation of different prod ucts of a manufacturer The Authentcode separates manufactures strictly from each other ...

Page 20: ...n through the SG Lock library through the operations system and the physical interface e g USB bus to the internals of the SG Lock copy protection key The procedure is based on the 128 bit TEA Tiny Encryption Algorithm en cryption engine implemented in the SG Lock hardware and big random numbers that have to be encrypted A simple example how to implement that feature can be found in the chapter Pr...

Page 21: ...12 83A1 77E9 2E57 C112 83A1 77E9 157B 4B14 89F3 C261 157B 4B14 89F3 C261 157B 4B14 89F3 C261 128 Bit Key X random no 64 Bit OK SglCryptLock 010111 000110 0101010 110101 Figure 3 2 The SG Lock Challenge Response Authentication provides a secure connection from the protected application EXE file through the whole operating system over the USB bus to the SG Lock token itself ...

Page 22: ......

Page 23: ...ties for special intended aims e g memory and counters which can be used to store strings or counters to limit program starts Functions of that group are used when certain protection strate gies are pursued The group of administrative functions is primarily used for the preparation purposes of the SG Lock hardware prior delivery to the software users They are normally not implemented in the source...

Page 24: ...ter value to a SG Lock device Cryptographic functions SglCryptLock En or decrypts one or more data blocks with the SG Lock device using a SG Lock device internal key SglSignDataApp Sign or verify data with the PC SglSignDataLock Sign or verify data with a SG Lock device SglSignDataComb Sign or verify data with a combination of PC and SG Lock device Administrative functions SglReadProductId Reads t...

Page 25: ...ESS Authentification successfull SGL_AUTHENTICATION_FAILED Authentification failed The full list of return codes is listed in chapter 4 6 Comments This function of the SG Lock API has to be called once first and successfully to enable all other API functions In the case of dynamic linking the authentication is required after every link procedure LoadLibrary call Every customer get his unique Authe...

Page 26: ... Lock device Types U2 U3 U4 Declaration ULONG SglSearchLock ULONG P r o d u c t I d Parameters ProductId Indicates the ProductId of the SG Lock looked for Return values SGL_SUCCESS SG Lock found SGL_DGL_NOT_FOUND SG Lock not found The full list of return codes is listed in chapter 4 6 ...

Page 27: ... ProductId Indicates the ProductId of the SG Lock SerialNumber Points to variable in which the serial number will be given back to the calling application Return values SGL_SUCCESS SG Lock serial number success fully read SGL_DGL_NOT_FOUND SG Lock not found The full list of return codes is listed in chapter 4 6 Comments Every SG Lock has a serial number that is unique which is also not depending o...

Page 28: ...es the ProductId of the SG Lock Address Startadress of data value block 0 to 63 SG Lock U3 0 to 255 SG Lock U4 Count Number of data values Data Pointer to data array in which the data values will be givenback to the calling application The de veloper is responsible to provide an array with a sufficient size Return values SGL_SUCCESS Data values successfully read SGL_DGL_NOT_FOUND SG Lock not found...

Page 29: ...es the ProductId of the SG Lock Address Startaddress of data value block 0 to 63 SG Lock U3 0 to 255 SG Lock U4 Count Number of data values Data Pointer to data array where data values be copied from The developer is responsible to provide an array with a sufficient size Return values SGL_SUCCESS Data values succesfully written to SG Lock memory SGL_DGL_NOT_FOUND SG Lock not found The full list of...

Page 30: ...r 0 to 15 SG Lock U3 0 to 63 SG Lock U4 Data Pointer to variable that the counter value is as signed to Return values SGL_SUCCESS Count value successfully read SGL_DGL_NOT_FOUND SG Lock not found The full list of return codes is listed in chapter 4 6 Comments Counters are simple 32 bit data values in the SG Lock memory If desired they can also be used for everything a 32 bit read write variable is...

Page 31: ...ONG ProductId ULONG CntNum ULONG Data Parameters ProductId Indicates the ProductId of the SG Lock CntNum Number of counter 0 to 63 SG Lock U3 0 to 255 SG Lock U4 Data Counter value to be written Return values SGL_SUCCESS Count value succesfully written SGL_DGL_NOT_FOUND SG Lock not found The full list of return codes is listed in chapter 4 6 Comments See SglReadCounter ...

Page 32: ...ONG SglCryptLock ULONG ProductId ULONG KeyNum ULONG CryptMode ULONG BlockCnt ULONG Data Parameters ProductId Indicates the ProductId of the SG Lock KeyNum Number of key to use 0 to 1 SG Lock U3 0 to 15 SG Lock U4 CryptMode Working mode 0 Encrypt 1 Decrypt BlockCnt Number of data blocks to en or decrypt Data Pointer to data array where values shall be copied to The developer is responsible to pro v...

Page 33: ...ccessfully fin ished SGL_DGL_NOT_FOUND SG Lock not found The full list of return codes is listed in chapter 4 6 Comments The function uses destructive data proccessing mode That meens the input of the parameter Data will be overwritten during execution of the function ...

Page 34: ...U to accelerate the signing process combined mode Important condition for combined mode Both keys application and SG Lock internal have to be different to ensure highest security The signature is 64 bit long Types U2 U3 U4 Declaration ULONG SglSignData ULONG ProductId ULONG AppSignKey ULONG LockSignKeyNum ULONG Mode ULONG L o c k S i g n I n t e r v a l ULONG DataLen ULONG Data ULONG S i g n a t u...

Page 35: ...ly If 0 the value is used as the power of 2 where the result of that determines which block index is signed or verified by the SG Lock E g value 8 28 256 that means the first and after that every 256th block is processed by the SG Lock and all others by the application PC CPU That means 1 256 0 4 of the task is done by the SG Lock and 99 6 by the PC CPU The result is a very high acceleration of th...

Page 36: ... in the SG Lock and application highly recommended for highest security The reasons is that the 128 bit key in the application is less safe than the 128 bit key in the SG Lock When a hacker succeeds to investigate the 128 bit key in the ap plication which is in principle possible then he will try that also first for the SG Lock That will fail if a differnt 128 bit key is used in the SG Lock For a ...

Page 37: ...mments The ProductId is an identifier that eases to distinguish between different pro tected applications of SG Lock users For example company X protects its appli cation A and B with SG Lock and gives all keys for application A the ProductId 1 and the keys for application B the ProductId 2 then all keys of application B are hidden for application A and vice versa This simple mechanism offers an e...

Page 38: ... e P r o d u c t I d ULONG OldProductId ULONG NewProductId Parameters OldProductId Indicates the actual ProductId of the SG Lock NewProductId Indicates the new ProductId of the SG Lock Return values SGL_SUCCESS ProductId successfully written SGL_DGL_NOT_FOUND SG Lock not found The full list of return codes is listed in chapter 4 6 Comments See SglReadProductId ...

Page 39: ...e ProductId of the SG Lock KeyNum Number of the key to be written 0 to 1 SG Lock U3 0 to 15 SG Lock U4 Key 128 bit Key to be written Pointer to data array of 4 integer values of 32 bit that form the 128 bit key Return values SGL_SUCCESS Key successfully written to SG Lock SGL_DGL_NOT_FOUND SG Lock not found The full list of return codes is listed in chapter 4 6 Comments The 128 bit key of the U2 i...

Page 40: ...equested information 0 Information about SG Lock modul Data Pointer to Data array of 8 integers of 32 bit The meaning of the single values are Index 0 Type Index 1 Interface Index 2 Software Version Index 3 Hardware Version Index 4 Serial number Index 5 Memory size in Dwords Index 6 Number of counters Index 7 Number of 128 Bit Keys Return values SGL_SUCCESS Information successfully read SGL_DGL_NO...

Page 41: ...Chapter 4 SG Lock API 35 Comments Further information to certain values can be found in the include and include header files of the SG Lock API ...

Page 42: ... SGL_DGL_NOT_FOUND 1 SG Lock not found SGL_AUTHENTICATION _REQUIRED 5 Authentication with SglAuthent not or not errorfree processed SGL_AUTHENTICATION _FAILED 6 Authentification with SglAuthent failed SGL_FUNCTION_NOT _SUPPORTED 7 The called function is not sup ported by the found SG Lock SGL_PARAMETERS _INVALID 8 Parameter of the called function is out of the vaild value range SGL_SIGNATURE_INVAL...

Page 43: ...f reading the key in the memory with help of special tools The advantage of this method is a fast encryption rate of more than 10MB sec Also exists a possibility of combine the internal encryption by SG Lock and encryption by PC CPU to gain both advantages high security provided by SG Lock and fast encryption by PC CPU in a single procedure The encryption rate is nearly as high as the internal enc...

Page 44: ...396 9B6EFB5F 41354633 3 4 97CCAFDC 1EB606E7 5CB83119 9F7F457C 4 4 F8BA5A4D 1C1BCBD0 61140A39 49507A3F 5 4 326FD7E8 E6C39F3A CBA04A4B 37804850 6 4 554E5BA7 81665744 8F747F62 E0EE72F9 7 4 BAD58985 238BF49B C97B1173 D3A28313 8 4 98940499 D20EDC71 68388EB6 B5DF3D1C 9 4 0FC6EC5F EBD20065 093984EF F52F415F 10 4 8DC071AA 668477BE 095C0CBE 3545E855 11 4 CBC15944 155BF5E3 88D9C8D3 E7142A18 12 4 F0D76719 43...

Page 45: ...A94628EE 0xF2857A8F 0x69346B4A 0x4136E8F2 0x89ADC688 0x80C2C1D4 0xA8C6327C 0x1A72699A 0x574B7CA0 0x1E8D3E98 0xD7DEFDC5 do a u t h e n t i c a t i o n of SGLW32 Dll ReturnCode SglAuthent MyAuthentCode i f ReturnCode SGL_SUCCESS a u t h e n t i c a t i o n f a i l e d p r i n t f SglAuthent E r r o r code 0x X n ReturnCode a u t h e n t i c a t i o n succeeded do t h e n e x t r e g u l a r t h i n ...

Page 46: ... end a u t h e n t i c a t i o n succeeded do t h e n e x t r e g u l a r t h i n g end 6 1 3 Visual Basic The f i l e SGLW32 BAS has to be i n c l u d e d in t h e p r o j e c t to ensure t h a t a l l SG Lock f u n c t i o n s and c o n s t a n t s are d e c l a r e d This i s t h e DEMO a u t h e n t i c a t i o n code every r e g u l a r SG Lock user g e t s i t s own unique a u t h e n t i c ...

Page 47: ...Code do a u t h e n t i c a t i o n of SGLW32 Dll Rc SglAuthent AuthentCode I f Rc SGL_SUCCESS Then Text1 Caption SglAuthent succeeded Else Text1 Caption SglAuthent f a i l e d Exit Sub End I f SG Lock found do t h e n e x t r e g u l a r t h i n g End Sub ...

Page 48: ..._SUCCESS no SG Lock found p r i n t f SglSearchLock E r r o r code 0x X n ReturnCode SG Lock found do t h e n e x t r e g u l a r t h i n g 6 2 2 Delphi i n t e r f a c e uses INCLUDE SGLW32IF PAS implementation INCLUDE SGLW32IP PAS In t h e case a SG Lock user p r o t e c t s more than 1 a p p l i c a t i o n product he should g i v e each of i t a unique product ID Then i t s very easy to d i s ...

Page 49: ...product he should g i v e each of i t a unique product ID Then i t s very easy to d i s t i n g u i s h t h e SG Locks f o r each product Public Const MY_PRODUCT_ABC_ID As Long 1 Public Const MY_PRODUCT_XYZ_ID As Long 2 Private Sub ButtonSearchSGLock_Click Dim Rc As Long ReturnCode Search SG Lock f o r product ABC Rc SglSearchLock MY_PRODUCT_ABC_ID S e l e c t Case Rc Case SGL_SUCCESS Text1 Captio...

Page 50: ...rnCode SG Lock s e r i a l number read do t h e n e x t r e g u l a r t h i n g 6 3 2 Delphi i n t e r f a c e uses INCLUDE SGLW32IF PAS implementation INCLUDE SGLW32IP PAS procedure TForm1 Button1Click Sender TObject const PROD_ABC_ID 1 var ReturnCode LongWord SerialNumber LongWord Read s e r i a l number of SG Lock with product ABC ReturnCode SglReadSerialNumber PROD_ABC_ID Addr SerialNumber i f...

Page 51: ...ry easy to d i s t i n g u i s h t h e SG Locks f o r each product Public Const PROD_ABC_ID As Long 1 Private Sub ButtonSearchSGLock_Click Dim Rc As Long ReturnCode Dim SerialNumber As Long Read s e r i a l number of SG Lock f o r product ABC Rc SglReadSerialNumber PROD_ABC_ID SerialNumber S e l e c t Case Rc Case SGL_SUCCESS Text1 Caption SerialNumber Case SGL_DGL_NOT_FOUND Text1 Caption SG Lock ...

Page 52: ...ROD_ABC_ID RUN_DATE_ADR RUN_DATE_CNT RunDate i f RC SGL_SUCCESS no SG Lock found p r i n t f SglReadData E r r o r code d n ReturnCode read date from system compare with RunDate and decide what to do 6 4 2 Delphi i n t e r f a c e uses INCLUDE SGLW32IF PAS implementation INCLUDE SGLW32IP PAS procedure TForm1 Button1Click Sender TObject const PROD_ABC_ID 1 RUN_DATE_ADR 10 address where date i s s t...

Page 53: ... a t i o n product he should g i v e each of i t a unique product ID Then i t s very easy to d i s t i n g u i s h t h e SG Locks f o r each product Public Const PROD_ABC_ID As Long 1 addresse where date i s s t o r e d in SG Lock Public Const RUN_DATE_ADR As Long 10 date s t o r e d as year month day 3 DWords Public Const RUN_DATE_CNT As Long 3 Private Sub ButtonSearchSGLock_Click Dim Rc As Long ...

Page 54: ...48 Chapter 6 Programming Examples Case Else Text1 Caption E r r o r Rc occured Exit Sub End S e l e c t read date from system compare with RunDate and decide what to do End Sub ...

Page 55: ...with product ABC RC SglWriteData PROD_ABC_ID RUN_DATE_ADR RUN_DATE_CNT RunDate i f RC SGL_SUCCESS no SG Lock found p r i n t f SglWriteData E r r o r code d n RC new date s u c c e s s f u l l y w r i t t e n l e t s do t h e n e x t t h i n g 6 5 2 Delphi i n t e r f a c e uses INCLUDE SGLW32IF PAS implementation INCLUDE SGLW32IP PAS procedure TForm1 Button1Click Sender TObject const PROD_ABC_ID ...

Page 56: ...re d e c l a r e d In t h e case a SG Lock user p r o t e c t s more than 1 a p p l i c a t i o n product he should g i v e each of i t a unique product ID Then i t s very easy to d i s t i n g u i s h t h e SG Locks f o r each product Public Const PROD_ABC_ID As Long 1 addresse where date i s s t o r e d in SG Lock Public Const RUN_DATE_ADR As Long 10 date s t o r e d as year month day 3 DWords P...

Page 57: ...aption RunDate 0 RunDate 1 RunDate 2 Case SGL_DGL_NOT_FOUND Text1 Caption SG Lock not found Exit Sub Case Else Text1 Caption E r r o r Rc occured Exit Sub End S e l e c t new date s u c c e s s f u l l y w r i t t e n l e t s do t h e n e x t t h i n g End Sub ...

Page 58: ...gned long i n t TEA_Key 4 0x238A3F10 0x61EAB67A 0x092E1CD2 0x832FAEC3 ATTENTION ATTENTION ATTENTION ATTENTION Do t h i s only once when i n i t i a l i s i n g t h e key p r i o r to d e l i v e r y of t h e dongle and NOT in t h e p r o t e c t e d a p p l i c a t i o n Writing t h e key i n t o t h e SG Lock modul RC SglWriteKey PROD_ABC_ID TEA_KEY_NUM TEA_Key i f RC SGL_SUCCESS p r i n t f SglW...

Page 59: ... d a p p l i c a t i o n SglTeaEncipher RandomNumber RanAppResult TEA_key 5 Step compare both r e s u l t s i f RanSglResult 0 RanAppResult 0 RanSglResult 1 RanAppResult 1 a u t h e n t i c a t i o n f a i l e d p r i n t f SG Lock Modul a u t h e n t i c a t i o n E r r o r n a u t h e n t i c a t i o n s u c c e s s f u l More programming examples and the necessary include files can be found on ...

Page 60: ......

Page 61: ...Bytes 32 Bit Counter no Counter 16 64 128 Bit Key 1 fixed 2 free writable 16 free writable Algorithm TEA Read Cycles unlimited Write Cycles 1 000 000 Data Storage 128 Bit encrypted Data Retention 20 Years Power Consump 50 mA Working Temp 0 to 70 C Storage Temp 30 to 70 C Size 47 16 8 mm L B H Weight 5 g Standard Color blue 55 ...

Page 62: ...56 Chapter 7 Technical Data Notes ...

Page 63: ...Chapter 7 Technical Data 57 ...

Reviews:

No comments

Brands by name

Popular brands

Load more brands