Guardant User Manual

Guardant
Anti piracy Protection System
Users Manual
Revision 4.7
2004 Aktiv Company
Contents
Contents
Contents ........................................................................................3 About This Book ........................................................................... 11 Conventions..............................................................................................................................13 Chapter 1. Introduction ................................................................. 15 What is Guardant? .................................................................................................................15 How does Guardant Work?.................................................................................................15 Advantages of Using Guardant...........................................................................................15 Protective Features of Guardant..........................................................................................16 Dongles of Guardant Family ................................................................................................17 Guardant Developers Kit .....................................................................................................18 Chapter 2. Installation................................................................... 19 Guardant Software.................................................................................................................19 Utilities .............................................................................................................................19 Guardant API ................................................................................................................20 Dongle Drivers ..............................................................................................................20 Service Files....................................................................................................................20 Hardware Requirements and Compatibility......................................................................20 Minimal Storage Requirements............................................................................................20 Attaching the Dongle..............................................................................................................21 LPT Dongle.....................................................................................................................21 USB Dongle ...................................................................................................................21 Attaching Multiple Dongles ........................................................................................21 Installing the Software ............................................................................................................21 Chapter 3. Getting Started............................................................. 23 Introduction to the Dongle.....................................................................................................23 Local Dongle..................................................................................................................23 Network Dongle ...........................................................................................................23 Access Codes................................................................................................................23 Demo and Operational Access Codes ...................................................................24 Dongles ID Number....................................................................................................24
Users Manual
Memory and Memory Fields......................................................................................25 Hardware Algorithms..................................................................................................26 Remote Programming Concept ................................................................................26 Searching Dongles on Your Computer....................................................................27 Checking Functionality of the Dongle.......................................................................28 Checking Computer Hardware ................................................................................28 Protection Methods ................................................................................................................29 Automatic Protection ...................................................................................................29 Guardant API based Protection................................................................................30 Which Method to Choose? ........................................................................................30 Auto Protection Wizard: Protection As Easy As ABC ......................................................31 Chapter 4. Stealth Technology....................................................... 33 Microprocessor Technology.................................................................................................33 Availability of Y=F(X) Hardware Algorithms.......................................................................33 Multiple Hardware Algorithms in One Dongle ................................................................34 Creating Your Own Hardware Algorithms .......................................................................34 Complexity of Hardware Algorithms ..................................................................................34 Using the Hardware Algorithms Properties......................................................................35 Encoding Data Using Hardware Algorithms ....................................................................36 Fast Conversion Algorithms ..................................................................................................36 Dongle Access Codes............................................................................................................37 Hardware Read/Write Locks ...............................................................................................38 Encoding the Memory of Stealth dongle ...........................................................................38 Anti debugging Hardware Features...................................................................................39 Features of the Protocol of Communication with Stealth dongle..................................39 Power Saving and Full Transparency ...............................................................................40 Special Features of Implementing Stealth Technology in Guardant Fidus..................41 Chapter 5. Structure of Stealth Dongle ........................................... 43 The Dongles Memory and Memory Addressing Methods ...........................................43 Stealth Dongles Memory Map............................................................................................44 How the Dongles Memory is to be Used..........................................................................47 Special Operations Fields...........................................................................................48 General purpose Fields ..............................................................................................49
Contents
User Fields ......................................................................................................................50 Special Purpose Fields.................................................................................................50 Chapter 6. Hardware Algorithms ................................................... 51 What are Hardware Algorithms for? ..................................................................................51 Protective Features of Hardware Algorithms ....................................................................52 Hardware Algorithms Structure ..........................................................................................53 Methods of Creating Hardware Algorithms......................................................................55 Using NSKUTIL Program .............................................................................................55 Manually, Using Guardant API Special Functions.................................................55 Hardware Algorithms Features...........................................................................................55 Dependence on the ID ................................................................................................55 Dependence on the Algorithms Counter................................................................56 An Algorithm with a Limited Number of Executions...............................................56 The Importance of the Algorithms Determinant...............................................................56 Types of Hardware Algorithms ............................................................................................57 Random ..........................................................................................................................57 Fast...................................................................................................................................58 Simple..............................................................................................................................58 Example of Hardware Algorithms Descriptors ................................................................58 Specific Features of Guardant Fidus Hardware Algorithms...........................................61 How to Use Hardware Algorithms? ....................................................................................62 How to Convert Data Using Hardware Algorithms ..............................................62 New Protection Technologies Provided by Hardware Algorithms ....................64 Chapter 7. Working with Guardant Net in LAN ................................ 69 Guardant Net Concept .........................................................................................................69 What is Guardant Net?...............................................................................................69 What is Guardant Net Server? ..................................................................................70 How does Guardant Net Work? ..............................................................................70 How are Licenses Allocated? .....................................................................................71 Guardant Net Features ...............................................................................................72 Supported Networks and Protocols....................................................................................72 Supporting Several Adapters and Network Interfaces.........................................73 Specifics of Using the NetBIOS Protocol .................................................................73 Configuring the Guardant Net Server and Client ............................................................75 General Information ....................................................................................................75
Users Manual
Configuring Guardant Net Server............................................................................75 Configuring Guardant Net Client.............................................................................82 Guardant Net Server .............................................................................................................84 Loading the Server .......................................................................................................84 Monitor Function...........................................................................................................84 Registration of a New Dongle ...................................................................................86 License Management System ....................................................................................86 Running the Server As Windows NT/2000/XP Service........................................89 Guardant Net Network Monitors........................................................................................90 How to Increase Reliability of Network Communication................................................90 Improving Protection Strength against Attacks.......................................................90 Increasing Performance of Guardant Net Server .................................................91 How to Avoid Problems of Sharing Data in the Network ....................................92 Chapter 8. Guardant API............................................................... 93 Operations...............................................................................................................................93 Built in Operations .......................................................................................................93 Service Operations ......................................................................................................94 Methods of Executing Operations.......................................................................................95 Guardant Stealth, Guardant Fidus ...........................................................................95 Guardant Net ...............................................................................................................96 Where are API Files Located? ..............................................................................................96 Guardant API Error Codes ...................................................................................................96 Functions of nskXXXX() / nnkXXXX() Types............................................................................97 Calling Functions of nskXXXX()/ nnkXXXX() Type..............................................................98 nnkDllMain Operation ..................................................................................................... 100 SetMode Operation. Specifying dongle search conditions & operation modes . 101 FindFirst Operation. Obtaining the ID of the First Dongle Found ............................ 104 FindNext Operation. Obtaining the ID of the Next Dongle Found......................... 105 Login Operation. Logging in Guardant Net Server ................................................... 106 LoginLMS Operation. Logging in Guardant Net Server............................................ 108 Check Operation. Checking for Availability of the Dongle ...................................... 110 DecGP Operation. Checking for Availability of the Dongle and Decrementing GP Executions Counter ................................................................. 111 Transform Operation. Transforming Information Using the Dongles Hardware Algorithm................................................................................. 112 LockBeg Operation. Locking Guardant Net ............................................................... 114
Contents
Read Operation. Reading a Block of Bytes from the Dongles Memory................ 115 Write Operation. Writing a Block of Bytes into the Dongles Memory ................... 116 LockEnd Operation. Unlocking Guardant Net............................................................ 117 Init Operation. Initializing the Dongles Memory......................................................... 118 Protect Operation. Implementing Locks / Specifying the Number of Hardware Algorithms........................................................ 119 ProtectLMS Operation. Implementing Locks and Specifying the Number of Hardware Algorithms ............................................... 121 CodeInit Operation. Initializing Password for Fast Reversible Conversion ............ 123 EnCode Operation. Encoding Data Using Fast Reversible Conversion................. 125 DeCode Operation. Decoding Data Using Fast Reversible Conversion............... 127 CRC Operation. Calculating 32 bit CRC of a Memory Block.................................. 129 Logout Operation. Logging out from Guardant Net Server..................................... 131 Specific Features of Using Guardant Net API.............................................................. 133 NSKCOMMAND() Function .............................................................................................. 135 Source Code Generator .................................................................................................... 149 Operating Principles ................................................................................................. 149 Procedure.................................................................................................................... 150 Hints on Usage........................................................................................................... 150 Main Window of the Source Code Generator ................................................... 152 Editor of LNG Files..................................................................................................... 160 Variables of LNG file................................................................................................. 176 Chapter 9. Programming Guardant Dongles ................................ 181 NSKUTIL. Main Programming Utility................................................................................. 181 NSKUTIL Main Window............................................................................................ 182 Using Mask ................................................................................................................. 183 Editing General purpose Fields .............................................................................. 185 Programming the Applications License Term...................................................... 185 Editing User Data Area............................................................................................. 185 Programming the Dongles Memory..................................................................... 192 Setting Read/Write Locks......................................................................................... 193 Obtaining Dongle Information ............................................................................... 195 Obtaining Responses from Hardware Algorithms ............................................. 195 Fast Reversible Conversion ...................................................................................... 197 Executing Guardant API Functions......................................................................... 199 Preparing Data for Remote Programming of the Dongle................................. 201
Users Manual
NSKUCM32. Programming in the Batch Mode............................................................ 206 NSKTUTIL. Programming the Applications License Term............................................ 207 NSKTUTIL Command Line Parameters ................................................................. 208 Writing the Time into the Local Dongle ................................................................. 209 Remote Correction of Time...................................................................................... 209 Chapter 10. Remote Programming of Guardant Dongles ............... 213 GSREMOTE. Remote Programming of the Dongle Memory and Correction of the Applications License Term......................................................... 213 Changing the Contents of the Dongle Memory.................................................. 214 Correcting the Applications License Term ........................................................... 215 NSKINST. Remote Programming of the Dongles Memory........................................ 215 Fast Correction of the Dongles Memory Contents............................................ 216 Remote Updating of the Dongles Memory Block.............................................. 217 Remote Updating of the Dongle's Entire Memory .............................................. 218 NSKTCHK. Remote Correction of the Applications License Term............................. 218 Displaying the License Term .................................................................................... 218 Correcting the License Term.................................................................................... 219 Chapter 11. Guardant Drivers...................................................... 221 Installing the Driver.................................................................................................... 222 Configuring the Driver .............................................................................................. 223 Removing the Driver.................................................................................................. 226 Using Command Line Options ............................................................................... 226 Return Codes.............................................................................................................. 227 Installing Drivers from Your Application .......................................................................... 227 API Functions to be Used with Guardant Drivers................................................ 227 Chapter 12. Automatic Protection in Every Detail.......................... 237 Automatic Protection Features .......................................................................................... 237 Automatic Protection Principles......................................................................................... 238 Automatic Protection Utilities ............................................................................................. 239 Files Required for Protection.................................................................................... 240 Protection Procedure................................................................................................ 240 Brief Description of Protection Options................................................................. 241 Error Codes ................................................................................................................ 243 Limitations.................................................................................................................... 244
Contents
Automatic Protection Options ........................................................................................... 245 Options of Binding to the Dongle........................................................................... 246 Protected Application Encoding Options............................................................. 258 Additional Application Protection Options .......................................................... 261 Data Files Protection Options ................................................................................. 263 Specifying a List of Files to Be Protected (Encoded) ............................................ 274 Using List File ............................................................................................................... 275 Chapter 13. Files to Pass to an End User ....................................... 277 Appendix A. How to Update Guardant Software ........................... 279 Updating from Guardant Software CD .......................................................................... 279 You Just Wish to Update Guardant Software...................................................... 279 You Wish to Start Using Dongles of a New Type................................................ 279 Guardant Software On line Update................................................................................ 280 Appendix B. How to Increase Protection Strength. Recommendations to a Programmer ............................................ 283 Automatic Protection of Executable Programs .............................................................. 283 API Based Protection........................................................................................................... 284 General Recommendations .................................................................................... 284 Additional Tips on Stealth dongles......................................................................... 286 Additional Tips on Network Dongles..................................................................... 288 Appendix C. Additional Devices to be Used with Dongles ............... 289 The Saver ............................................................................................................................... 289 Appendix D. Specifications .......................................................... 291 Appendix E. Hardware Algorithms Parameters ............................ 293 Appendix F. Demo Access Codes .................................................. 295 Glossary .................................................................................... 297
About This Book
About This Book

This book is a comprehensive manual on Guardant hardware software protection. Chapter 1 briefly outlines basic concepts. From this chapter you will learn what a dongle is and how it works, what dongles currently comprise Guardant family, what Guardant Developers kit is and what it is com posed of. Chapter 2 contains brief introduction to Guardant software and defines procedures for installing Guardant system. Chapter 3 contains information that is essential from your very first ses sion of working with protection. You will be given a more detailed over view of the dongle and its most important characteristics. This chapter will start introducing you to the two methods of protection: automatic protec tion and API based protection. Chapter 4 provides a more in depth study of Guardant protection capa bilities. It describes in detail the principles underlying Stealth technology and its realization. Chapter 5 covers the essential information about the internal structure of the dongles of Guardant Stealth family. You will find answers to such questions as: how the memory is allocated in the dongle; how this mem ory should be used; in what part of the dongles memory the required in formation can be found. This chapter also discusses other related issues. Chapter 6 tells about hardware algorithms, particularly, their structure, creation and utilization in protection systems based on Guardant Stealth. You will learn what is the purpose of hardware algorithms and why they are so important, and will go deeper into the details of their structure. Guidance will be provided for creating your own hardware algorithms and using them for protecting your applications. Follow the developers rec ommendations. Chapter 7 is intended for those using protection based on Guardant Net. It tells what makes the heart of Guardant network protection, in which lo cal networks it can be used, how to launch and maintain Guardant Net servers, and what are the functions of Guardant Net network monitors. Besides, you will be given useful advice on how to increase reliability of network communication and prevent overloading of Guardant Net server. Chapter 8 tells about Guardant Application Programming Interface (API). Here you will find description of the API functions for all types of dongles and examples of their usage.
11
Users Manual
Chapter 9 and 10 describe methods of programming the dongles of Guardant family. You will learn how to read from and write to memory, and be advised of the tips and tricks of programming Guardant dongles of different types, as well as of all methods of remote programming of Guardant dongles. Chapter 11 tells about Guardant drivers, particularly their installation, set ting and deinstallation. Extensive coverage of Guardant API will enable you to use it for to installing and setting up Guardant drivers directly from your application. Chapter 12 describes in detail all options of Guardant automatic protec tion. Chapter 13 contains important information about files from Guardant software kit to be used with your software product. From the Appendices you will learn how to update Guardant software, what basic means can be used to add strength to the protection against at tacks, what additional devices can be used to make operation of the don gles more convenient. Also in the Appendices you will find instructions on operating dongles, their specifications and a list of demo access codes. Glossary can be found at the back of this book.
Additional Sources of Information

Should any questions arise that remain unanswered after reading this Manual, please refer to the following additional sources of information: README File. Can be located on the distributive media or on your computer once Guardant software has been installed on it. It contains the latest information on advanced features and updates of Guardant hardware and software. WWW: http://www.guardant.com developers web site with huge amount of reference information on Guardant protection, namely: FAQ, troubleshooting, recommendations, etc. Technical Support Service: e mail: hotline@guardant.com, Telephone: +7 (095) 105 77 90. We will do our best to supply a most prompt and comprehensive reply to your query.
12
About This Book
Conventions
Conventions used in this book are intended to make understanding of the text easier. If a term supplied with a corresponding definition in the Glossary appears in the text, it is marked with symbol. Keys and their combinations are given in angle brackets, for example: <Enter>, <Alt-F>. Menu commands are presented in such a way so as to separate hierarchy levels by | symbol, for example: Edit|Add. Controls, for example buttons, are typed in bold face and enclosed in square brackets: [Determinant], [DEMO]. Program texts and messages are typed in a special typeface. Names of files and folders are typed in upper case characters: NSKUTIL.EXE, C:\GUARDANT etc. To denote the general format of Guardant API functions patterns such as nXkXXXX are used, where X in the prefix indicates the type of the dongle (s for Stealth, n for Net), and XXXX substitutes for the name of the operation, for example Transform. Thus, nXkSetMode means function that executes SetMode operation for Stealth, Fidus or Net dongles, and nnkXXXX means all operations for Guardant Net. Some important notes are emphasized by means of special insertions. Please read them carefully as they will help you to avoid many problems. Warning
Warning contains information that may be critical for proper functioning.
Important
Contains information, advice and recommendations that require your special attention.
13
Chapter 1. Introduction
Chapter 1 Introduction
What is Guardant?
Guardant is Latin for safeguarding, protecting. Guardant software hardware system has been designed to protect soft ware against computer piracy that is, against illegal copying and distri bution, and unauthorized use. In the heart of this protection scheme is a device called dongle. This is a relatively small electronic device attachable to a computer. Protected applications are bound to the information en closed within the dongle.
How does Guardant Work?

The underlying protection principles can be outlined as follows: A protected application calls the dongle that has to be attached to the computer. The dongle returns certain information to the application. Using this information the application authenticates the dongle. If the dongle has correct parameters, the application continues running. In case the dongles parameters are incorrect (a wrong dongle) or if it is not attached at all, the protected application ceases it is functioning1.
Advantages of Using Guardant

Modern Protection Technologies If you choose any of the software hardware complexes of Guardant fam ily you will obtain a protection system that makes maximal use of the up to date technologies as compared with other protection systems in the same price range group. Wide Sphere of Application Guardant protection can be built using various types of dongles, which differ in features and capabilities. If you choose Guardant technology, you are sure to develop an optimal solution for your tasks.
1
As a matter of fact, protection methods are much more sophisticated and diverse. Discussion of those makes up a good part of this book.
15
Users Manual
Simplicity of Learning and Usage To use Guardant protection effectively no special knowledge is required. Wisely designed functioning logic of protection utilities, Auto Protection Wizard, user friendly program interface, a great deal of examples and rec ommendations will help you quickly learn the tricks of using Guardant protection and achieve success in the shortest possible time. Benefits for End Users Your customers will appreciate all benefits of working with a protected application. All they need to do after installation is to attach the dongle to their computer. Ability to create back up copies of the protected product and install it on other computers; no need for special configuring of the protection system and no problems when working with peripheral devices; high level of compatibility; availability of remote programming of dongles this is but a short list of features that will make protection an easy task for the end user. Technical Support Whether you ask a question by telephone or submit it by e mail, you are certain to get a prompt and exhaustive technical advice. All technical sup port is free of charge. On Line Updating of Software Versions All users of Guardant protection will benefit by updating their software free of charge. On line downloading of software updates is available from the companys web site. Free software update system is also available al lowing users to get our latest protection technologies.
Protective Features of Guardant

Microprocessor Technology Using microcontroller as basis of the dongle makes its functioning logic more sophisticated, flexible and intelligent. As a result, the dongles fea tures enhance, a gain in reliability and compatibility is attained, and im munity from attacks increases. Y=F(X) Hardware Algorithms Appropriate usage of hardware algorithms of Guardant Stealth, Guardant Fidus and Guardant Net dongles enables reliable protection against emu lation, which currently appears as the most powerful way of protection cracking. Hardware algorithms also provide an opportunity to signifi cantly increase the level of protection of the application by means of in troducing into the application of a data encoding element.
16
Chapter 1. Introduction
Secured Protocol of Communication with the Dongle Usage of such methods of protocol security as encoding, noise genera tion, chaotic data exchange, random change of parameters makes the protocol of communication with dongles especially resistant to attacks. Protected Application Encoding You can encode the body of the protected application. The latter is a most effective way of fighting against decompilation and disassembly.
Dongles of Guardant Family

At the time of compilation of this Manual, Guardant family comprises three types of dongles: Guardant Stealth This is a microcontroller based dongle to be attached to the parallel or USB port of an IBM compatible computer. The dongle uses Stealth technology and contains 256 bytes of non volatile memory for storing user data. It can contain up to 18 different Y=F(X)* hardware algorithms, including those created by the user. The dongle supports hardware based memory read/write locks and hardware based protection against debug gers. The dongle is dynamically transparent to any peripheral devices that use any communication protocols. Guardant Fidus This microcontroller based dongle uses subset of Stealth technology and is to be attached to the parallel port of an IBM compatible computer. State of the art chipset technology is used in Guardant Fidus. This don gle presents an optimal solution while combining lower pricing with the common features of Guardant Stealth family. The dongle contains 256 bytes of non volatile memory for storing user data. It contains 8 prede fined Y=F(X)* hardware algorithms. The dongle supports hardware based memory read/write lock and hardware based protection against de buggers. The dongle is dynamically transparent to any peripheral devices that use any communication protocols. It is recommended to use this dongle for protection of inexpensive software. Guardant Net This is a microcontroller based dongle to be attached to the parallel or USB port of an IBM compatible computer. It uses Stealth technology and supports all features of Guardant Stealth. The dongle enables protec tion and licensing of network software in any local area networks (LAN) with TCP/IP protocol or NetBIOS interface. The dongle requires no spe cial configuration of the network. To run protected network software, one Guardant Net dongle is sufficient for the entire LAN.
17
Users Manual
Guardant Developers Kit

Guardant Developers kit allows you, as a software developer, to protect software products by following the procedures described in this Manual. Guardant Developers kit comprises the following items: Guardant dongle. The Developers kit includes one dongle of the type you choose (Guardant Stealth, Guardant Fidus or Guardant Net). Usually a demo dongle* is supplied with the Developers kit. Guardant software. This comprehensive software package for working with Guardant dongles is aimed at protecting any DOS and Windows ap plications. Supplied on CD. Documentation and information papers. These include this printed Users Manual, access codes sheet, a list of supported programming languages, an instruction on operating dongles as well as related information and ad vertising matter.
18
Chapter 2. Installation
Chapter 2 Installation
Important
Please pay special attention to how dongle access codes are to be assigned during the installation of Guardant software.
Guardant Software
Functionally Guardant software is divided into several items: Utilities Guardant Integrator. A convenient to use shell providing quick access to most often used utilities of the Developers kit. All Integrator components are supplied with pop up help that allows you to immediately identify the purpose of an element. Dongle search utilities. A set of utilities allowing you to scan all parallel and USB ports of the computer, to locate all Guardant dongles attached to those and display information about their parameters on the screen. Dongles functionality tests. A set of DOS, Win16 and Win32 test applica tions for each type of Guardant dongles. By using them, you can check how the dongle works in all of its basic modes on any specific computer. Automatic protection utilities. A set of utilities for automatic protection of executable DOS, Win16 and Win32 applications. Each utility has two auxiliary files: external vaccine* file and a file containing a list of most common protection error messages. Auto Protection Wizard. This utility allows you to specify necessary op tions in a most quick and easy manner and implement automatic protec tion of the applications. Dongles programming utilities. A set of utilities for programming the memory of Guardant dongles in standard mode as well as in modes with limited license term of protected applications. Dongles remote programming* utilities. A set of utilities for remote pro gramming of dongles memory in standard mode as well as in modes with limited license term of protected applications. Source Code Generator. This utility allows you to reduce labour put into the development of application protection systems based on Guardant API. Various development tools and programming languages are sup ported. Obtained source code provides sophisticated logic of interaction with the dongle sufficient for reliable protection of the majority of commercial products.
19
Users Manual
Server and network monitors. A set of utilities that enable functioning of Guardant Net in LANs. Those include Win32 Guardant Net server that binds protected application to the dongle, and network monitors for monitoring the status of dongles from any workstation. Guardant Software On line Update Utility. This utility enables complete automation of Guardant software update process via Internet. It verifies whether an update is required for any of the software components and downloads them from the server for subsequent installation. Guardant API A set of libraries (.OBJ, .BIN, .LIB, .DLL) that provide all necessary functions for operating the dongle directly from the body of the protected application. The libraries are supplied with samples of their usage with the most popular programming languages and development tools. Dongle Drivers A set of Guardant drivers for Windows 95/98/Me and Windows NT/2000/XP with installation and configuration program. Service Files Service files required for running the above mentioned utilities.
Hardware Requirements and Compatibility

Guardant protection system sets minimal hardware and software re quirements. To run Guardant software the following is required: IBM PC AT, PS/2 or other IBM compatible computer. Standard parallel port with any interface or USB port. Windows 95/98/Me/NT/2000/XP Operating System.
Minimal Storage Requirements

Loading and running of DOS protected application additionally requires at least 30Kb of RAM. Additional RAM space required for running of Windows applications depends on the structure of a given application.
20
Chapter 2. Installation
Attaching the Dongle

LPT Dongle To connect an LPT dongle to the computer a male DB 25 connector is used. You can connect the dongle to any parallel port of the computer. It is very important that this connection be reliable, i.e., tight and not loose. It is necessary to tighten metal screws to make the connection more reli able, and to ground the dongle. A socket (female connector) on the opposite side of the dongle is used to connect other dongles, a printer or other peripheral device. USB Dongle The USB dongle has only one connector, which is plugged into the avail able USB socket. Attaching Multiple Dongles You may attach several LPT dongles, including those of different types, to the same computer port. There are no special requirements as to the order in which Guardant dongles of different types should be connected to the computer during cascading. In case you wish to daisy chain the don gles of other manufactures, please refer to their operating Manual for connection tips. The USB allows connecting up to 127 devices to one port. Therefore, it is possible to connect as many USB dongles as there are available USB sockets.
Installing the Software

The procedure for installation of Guardant software is the following: 1. Insert Guardant CD in the CD ROM drive. Installation will start automatically by running AUTORUN.EXE program. 2. If automatic start is disabled, then run AUTORUN.EXE program from the root directory of Guardant CD to start the installation. 3. If you wish to install Guardant system immediately, select Install Developrs Kit. In this case, SETUP.EXE program will be started automatically, and you will have to follow its instructions on the screen. 4. If you first wish to preview the structure of the distributive disk, or review the READ.ME file, etc., select Browse this CD. In this case, to proceed with the installation you will either have to start SETUP.EXE manually and follow its instructions or restart AUTORUN.EXE and act as described in Step 3 above.
21
Users Manual
SETUP program will adjust Guardant software to your codes. For this reason you will have to select from the displayed screen the types of Guardant dongles that you intend to use and enter Public and Private ac cess codes for them. All codes are supplied with the Developers kit; they are printed on the sheet enclosed in the envelope. Please note that some of the codes are shown in bold typeface. These are the codes to be entered. If you are installing the software from the demo Developers kit, select Use demo codes option to adjust Guardant software to demo dongles. Warning
If you have not specified any type of dongles, the utilities associated with these dongles will start only with demo-dongles after you install the software. To be able to use non-demo-dongles of the appropriate type you will have to reinstall the Developers kit.
It is recommended that you choose all types of Guardant dongles straight away (and enter access codes for them accordingly). By spending just a lit tle more time on this, once you will avoid undesirable efforts in the future when you may decide to switch to a different type of dongle. In the course of installing the software, NVCODES.DAT file will be cre ated on your disk to contain information on your dongles access codes. This file is required in order to activate dongle tests, and all automatic protection and dongle programming utilities except for remote program ming tools, which are intended for end users. Warning
NVCODES.DAT file is only intended for those Guardant utilities which you use yourself. Neither protected applications nor any other utilities intended for end-users can use this file. You should never pass NVCODES.DAT file to third parties!
During running of the SETUP program Guardant driver will also be in stalled. The driver is required to improve reliability when working with the dongle. Furthermore, in Windows NT/2000/XP the dongle cannot be ac cessed without the driver at all. Never forget to install the drivers on any particular computer on which you wish to check protected applications work. Also, bear in mind that Guardant drivers should be supplied to gether with the protected application. After the software installation procedure is completed, a Guardant group will be created in the Programs submenu under Start menu.
22
Chapter 3. Getting Started
Chapter 3 Getting Started

This chapter contains information that will be useful anytime from your first session with Guardant. You will learn what the difference between a network dongle and a local dongle is; find out what dongle access codes mean and what they are for, how memory is organized inside the dongle and how its main fields can be used. You will get an idea of what hardware algorithms are and of the purpose of remote memory programming and how it can be used. You will learn to gather information on all dongles at tached to the computer and check their functionality. Finally, you will learn about different protection methods and their distinctive features, and a short lesson will be provided for you to master the easiest and fastest way of protection. Important
Please pay special attention to the comments concerning selection of a protection method.
Introduction to the Dongle

Local Dongle Local dongle is a dongle designed for using on a local (non network) computer. Such a dongle cannot be utilized in the network, and thus can be used to protect non network software only. Local dongles include Guardant Stealth and Guardant Fidus. Network Dongle The network dongle possesses extended capabilities. It can be used on stand alone computers as well as on workstations and servers in LAN. Therefore, this dongle can be used to protect both non network and net work software. Guardant Net is the brand name for the network dongle of Guardant family. Access Codes You can communicate with the dongle only if you know a special access code to this dongle. The code serves as a password for the protected appli cation to find the appropriate dongle and activate it in order to execute any certain operation. Such code is called a Private code. Latest dongles of Guardant family are assigned three different Private access codes:
23
Users Manual
Private Read Code allows you to read the dongles memory and execute hardware algorithms. Private Write Code allows you to write to the dongles memory. Private Master Code allows you to execute special operations with the dongle. To make the dongle execute any certain operation the protected applica tion should send to it a corresponding Private code. All Private codes are confidential and may not be disclosed to any third party. Furthermore, each Guardant dongle is assigned a Public code. It is not used to communicate with the dongle and is not confidential. The pur pose of this code is to show whether this particular dongle is owned by you. The Public code can be viewed with dongles search utilities supplied together with Guardant software. Access codes are embedded into the memory of the dongle at the presale stage and cannot be changed. Demo and Operational Access Codes The demo Developers kit contains a dongle with demo access codes (demo dongle). Demo access codes are the same for all users of Guardant protection because dongles with these codes are used only to demonstrate protection capabilities. Demo access codes are listed in Appendix G. Demonstration Access Codes. When operational Developers kit is received, each user of protection is assigned operational access codes. Operational access codes are unique for each user of protection since the dongles with these codes are used for the actual protection of commercial software. All operational dongles sup plied to the same user will always have the same unique access codes. When Guardant software is installed on the computer it is adjusted to the access codes assigned to the dongles of a particular user and can function with these dongles only. Thus, none of the users of protection can have access to other users dongles. Dongles ID Number Each dongle in Guardant family stores a special 4 byte number which is this dongles identification number (ID). The ID is assigned a unique value; there are no two Guardant dongles with the same IDs. The ID is embedded at the site of manufacturing and can be neither duplicated nor changed by anyone, including by Guardant protection developers. This value can be used to establish a hard binding between the protected ap plication and a particular dongle. The dongles ID can be viewed by either search utilities (see Searching Dongles on Your Computer) or dongle programming utilities.
24
Memory and Memory Fields All types of Guardant dongles have a fixed memory size. EEPROM mem ory used in dongles provides data storing capacity for about 100 years and does not require any power supply. The memory supports an unlimited number of reads from the dongle and up to 1 million writes to the dongle. In order to make it easier to work with the memory, it is divided into logi cal fields. Also, for your convenience, the fields have different attributes such as: number, string, counter, dump, etc. Each dongle by default has several fields, the so called predefined fields. Guardant dongles have the following field structure (the unchangeable fields are highlighted):
Guardant Stealth and Guardant Net Dongles ID Public and Private Codes Program Number (1 byte) Version (1 byte) Serial Number (2 bytes) Mask (2 bytes) Counter #1 (GP) (2 bytes) Counter #2 (2 bytes) Index (2 bytes) Hardware Algorithms Descriptors Free memory Free memory Guardant Fidus Dongles ID Public and Private Codes Program Number (1 byte) Version (1 byte) Serial Number (2 bytes) Mask (2 bytes) Counter #1 (GP) (2 bytes) Counter #2 (2 bytes) Index (2 bytes)
Actually, dongles have a more sophisticated memory structure than de scribed above. This will be treated in detail in the respective Chapter of this Manual. Program Number field is used to identify a particular software product if more than one product is protected with Guardant. Version field can be used to identify software version when protecting new software versions. Serial Number field is generally used to bind the application to the don gle with specified serial number. Mask field is used as a bit mask to allow/prohibit running of independ ent program modules that constitute the software product. Counter #1 (GP Counter) field is mostly used to store the application executions counter that is protected in a special mode. The value of the counter is decremented by 1 each time the application is run, and when the value reaches 0, the application stops running. Also, depending on the protection mode you choose, this field can contain protected applica tions license term counter.
25
Users Manual
Counter #2 field (not used in Guardant Stealth and Guardant Fidus) contains the dongles license limit (or, in other words, the maximum number of copies of the protected network application which can be run in LAN at the same time). Index field is used by the dongle remote programming utilities. The above fields in the memory of Guardant Stealth and Guardant Net are followed by Y=F(X) hardware algorithms data (or descriptors). De scriptors of four default algorithms are embedded into the dongles at the site of manufacturing. You may use these algorithms to protect the soft ware, edit their parameters or remove them. You can divide free memory space into fields. You can edit the contents of any of these fields or delete them (except for the Public and Private access codes and ID). You can also set hardware based read or write locks on your chosen memory areas in Guardant Stealth, Guardant Fidus and Guardant Net dongles. Hardware Algorithms Hardware algorithms present the essential protective feature of Guardant Stealth, Guardant Fidus and Guardant Net dongles. Proper use of these algorithms not only expands capabilities of the protection system and in creases its resistance against cracking, but also guards the dongles func tioning logic from being emulated. The distinctive feature of Guardant hardware algorithms is that you can take an active part in their creation. You can edit data written in the de scriptor and create a unique algorithm. You may even create your own unique algorithm with a singular representation and set of properties. A more detailed overview of hardware algorithms will be presented in Chap ter 6 Hardware Algorithms Hardware algorithms of Guardant Fidus ex hibit certain differences treated in Specific Features of Guardant Fidus Hardware Algoritms. Warning
Hardware algorithms are vital for creating protection resistant to all existing cracking methods.
Remote Programming Concept Remote programming has been developed to foster building of efficient relationship with your customers. When can this programming be useful? You may need to edit certain data in the dongle that is already in the pos session of your customer. This may happen when you send him a new ver sion of the protected application, or when the application license term has expired and needs to be extended. In such cases, a method of remote pro gramming of the dongles memory can be very helpful.
26
The idea of this method is very simple. Your customer should have a spe cial utility from Guardant software package. By running it he will get a unique number that he will pass to you. You, on your part, will run an other utility, enter this number and get another unique number in re sponse. When the customer receives this number from you he will enter it, and the utility will edit the required values in the dongle. Thus no one will have to leave his desk, and the programming procedure will take but a few seconds. This way you can reprogram any memory area to which you have access. You may edit the values of executions and time counters, create new hardware algorithms in the dongle or correct parameters written in the memory by mistake, etc. However, since the data that you interchange with your customers are valid for the current programming session only, your customer will not be able to use them again. Searching Dongles on Your Computer To make it easier for you to operate a great number of Guardant dongles various special dongle search utilities have been developed.
Figure 1. Screen displayed by Guardant Stealth/Fidus/Net dongles search utility For Guardant Stealth, Guardant Fidus and Guardant Net:
CHKNSK.EXE CHKNSKW.EXE CHKNSK32.EXE DOS utility Win16 utility Win32 utility
Any of the above utilities checks all parallel and USB ports of the com puter for the purposes of identifying dongles attached to the correspond ing ports. Then the utility displays Public codes and IDs, as well as the values of general purpose fields and other information on any dongle that has been found.
27
Users Manual
These utilities can be used as a preliminary test of the dongles functional ity. You may pass them to your customers for evaluation purposes. By try ing out these utilities, your customer will be able to test an application protected through limitation of the number of executions. Checking Functionality of the Dongle Guardant dongle is a hardware device. Hence, it is not guaranteed against faults. To make it easier for you to identify the causes of possible prob lems, special test utilities have been developed: For Guardant Stealth, Guardant Fidus and Guardant Net dongles used on a stand alone computer:
TST_GS.EXE TST_GSW.EXE TST_GS32.EXE DOS utility Win16 utility Win32 utility DOS utility Win16 utility Win32 utility
For Guardant Net used in LAN:

TST_GN.EXE TST_GNW.EXE TST_GN32.EXE
Any of these utilities executes a standard set of operations with the appro priate dongle, such as: searching, reading from and writing to the mem ory, execution of hardware algorithms and encoding data, etc. Thus, you can figure out which of the operations is executed incorrectly by the don gle. If all operations complete successfully, that means that the dongle is functioning correctly. Warning
All of these utilities use NVCODES.DAT file, therefore you should never pass them to third parties! Your customers can use search utilities described above for preliminary check of the dongles functionality. After this check, the dongle that raises doubts with the customer should be forwarded to you for further detailed check with these tests. Tests for checking Guardant Net in LAN use network functions only, i.e., they run like network applications. These tests will fail to find a dongle if local network is unavailable or Guardant Net server is not activated.
Checking Computer Hardware Practice has shown that unstable functioning of any existing dongles is rather connected with the problems in the computer to which the dongle is attached than with the failure of the dongle itself. In most cases, the problem is caused by operating the computer at a higher speed (or, in other words, when the system bus is overclocked). Hardware engineers strongly recommend against setting any parameters of the computer higher than prescribed in the specifications. Unfortunately, many users ignore this recommendation. This often leads to unstable functioning of dongles and other hardware components.
28
You or your customer may be unaware whether a particular computer is overclocked. To find this out you can take use of CLOCKTST.EXE util ity supplied with Guardant software. This utility checks AT bus clock pa rameter when IN and OUT commands (commands which call peripheral devices) are executed. The value of this parameter is most important for stable functioning of the dongles. Time of execution of these commands should not be less than 0.8 micro seconds for Pentium processors and 1 microsecond for older processors. Otherwise, problems may arise when working with peripheral devices. If on any particular computer the utility shows time value lower than the limit, then the computers CMOS should be reconfigured. You are free to pass this utility to your customers; it may help them to re solve possible controversial issues and will save you time.
Protection Methods
Guardant system supports two protection methods: Automatic protection Protection with the Guardant API Automatic Protection This method is based on processing of executable applications by the automatic protection utility supplied with Guardant software. As a result, the application is bound to the dongle and obtains protection against de buggers and disassemblers. Automatic protection has a number of options (modes) that allow finer adjustment of the application to the dongles pa rameters (binding to the ID, serial number, etc.), protection against com puter viruses, limitation of the number of application executions or appli cations license term, and encryption of its body. It also supports dynamic protection of data files for DOS, regular dongle checks and other options. The chief advantage of this method is that protection can be implemented in a short time. The procedure requires just a few seconds. Moreover, to implement the protection no special knowledge is required. The main drawback of this method is that it cannot provide sufficient safety for the application. This method, by its very nature, deters the pro tection system from becoming an integral part of the application. Protec tion is implemented on an executable application, as if it were aggluti nated to it; that is why there is always a risk that it can be destroyed by a hacker. Besides, this method does not provide for a non standard logic element in the protection system, the latter being very important for in creasing resistance to intrusions.
29
Users Manual
Guardant API based Protection This method is based on usage of Guardant API special functions accu mulated in the object modules. The API functions enable any operations with the dongle, such as searching, reading from and writing to the mem ory, setting hardware based protection, encoding data using hardware algorithms, etc. To implement API based protection you should insert API function calls into the application source code before compiling it. The main advantage of this method is that it ensures an incomparably higher level of security. If it has been implemented correctly, protection forms an integral part of the application, and, therefore, it can hardly be removed by a hacker. Guardant API functions allow you to perform any operation with the dongle and process any accessible memory location; hence, opportunities for designing protection will entirely depend on your imagination and abilities. You may build up any protection scheme, even with the most non standard logic, which will make it even harder to crack the protection. Finally, only Guardant API functions give you a free hand when working with hardware algorithms of Guardant Stealth, Guardant Fidus and Guardant Net. As has been said, no effective protection can be achieved without employing these algorithms. The only disadvantage of this method is that it cannot protect the applica tion against either debuggers or disassemblers. Thus, a hacker can use his own tools to the best of his abilities to study the application logic. Will it be easy for him to break such a protection? Which Method to Choose? Of course, you can use these methods separately by selecting either automatic protection or the API based protection. However, all the above leads us to believe that it is better to combine both methods. This is the only way when advantages of both methods can be complemented to compensate for their disadvantages. Use automatic protection to protect the application against debuggers and disassemblers, to encode its body and to hide the API function calls. Besides, this is a good method of pro tection against unneeded curiosity of people who do not have enough skills to crack the protection. Automatic protection should serve as the first line of defense. However, the core of the security system should be composed of protection methods that use API functions. It is this protection that is entitled to do the greater part of the job: authenticate the dongle and respond to its absence; operate with the memory and hardware algorithms, etc. It is most important to build such a protection that would become an integral part of the applica tion, a component whose absence would prevent the application from functioning properly. It is not that difficult a task as it may seem at first sight. To help you with this a great number of examples and recommendations are provided in the Chapters to follow.
30
Auto Protection Wizard: Protection As Easy As ABC

Auto Protection Wizard utility has been designed to maximally facilitate and accelerate the procedure of automatic protection of applications. Be sides, Wizards logic makes it especially easy to learn. Auto Protection Wizard will allow you to create an adequate protection for an application in just a few steps, even if you do not know anything about protection in general or about Guardant system in particular. To set protection options you will have to answer a few simple questions. At any time, you can get a comprehensive help on the topic by pressing <F1>. The utility also provides for automatic setting of default options. After the procedure is complete simply click the appropriate button, and the application will be protected. Also, the Wizard can create for you a batch file by using which you may call up automatic protection utility with specified options. You can use these command files in the future for quick protection of the software. If, however, you do not feel content with the Wizards features, you may turn to automatic protection utilities. See Automatic Protection Utilities for more details on how to operate those.
31
Chapter 4. Stealth Technology
Chapter 4 Stealth Technology

In this chapter, we begin an in depth coverage of dongles designed using Stealth technology. This chapter describes the features of the technology and how they work to resist the existing protection cracking methods. Warning
Stealth technology described in this Chapter is used in Guardant Stealth and Guardant Net. Guardant Fidus dongles are based on a subset of Stealth technology; therefore, some of the features described below are not available for these dongles. The features of the technology on which Guardant Fidus is based are described in Special Features of Implementing Stealth Technology in Guardant Fidus.
Important
Please pay special attention to the properties of hardware algorithms and to the protocol of communication with the dongle.
Microprocessor Technology
Dongles manufactured according to Stealth technology (hereinafter called Stealth dongles) are based on microcontrollers. This design enables many new protection capabilities; the majority of the features available in Stealth dongles and explained below exist due to the microcontroller. The microcontroller used in Stealth dongles is a microprocessor with built in memory and quite an extensive set of commands. In fact, Stealth dongles contain a microcomputer on the level with IBM PC XT.
Availability of Y=F(X) Hardware Algorithms

Readers who are familiar with microcontrollers functioning basics know that these devices are capable of executing an embedded program. Devel opers of Stealth technology used this capability to turn the dongle into an intelligent device capable of processing data by applying sophisticated al gorithms. When a Stealth dongle is manufactured, a special set of com mands (known as a microprogram) is embedded into the memory of its microcontroller. In combination with the descriptors, this microprogram implements various hardware algorithms of Y=F(X) type. At the same time, the microcontrollers logic does not allow its microprogram to be af fected externally. There is no way to read or modify it. The microcontrol ler is like a black box that completely hides all the processes that take place inside.
33
Users Manual
Use of hardware algorithms allows encoding any information used by the protected application. If protection is organized correctly, the hardware algorithm makes it useless for hackers to remove API calls from the body of the application, since in this case decoding will become impossible. Be sides, the presence of hardware algorithms makes the dongles functioning logic so complicated that creation of an emulator becomes a real chal lenge for hackers.
Multiple Hardware Algorithms in One Dongle

One Stealth dongle may contain up to 18 different hardware algorithms. These algorithms are truly different, rather than various versions of the same algorithm. Any of these hardware algorithms can be used anytime. All the algorithms stored in the dongle can be used to protect one and the same application; for example, a portion of data can be encoded by the first algorithm, another portion by the second algorithm and so on and so forth. All other things even, this makes protection cracking 18 times harder (and, therefore, more expensive).
Creating Your Own Hardware Algorithms

If you use protection based on Stealth dongles, you can easily design your own hardware algorithms. Using a special utility, you can specify the properties of the hardware algorithm by designing its determinant. After that, the dongle will start to encode data using an algorithm whose type and properties set known to you only. Thus, Stealth dongles provide unlimited opportunities for increasing security level against intrusions. If your company produces more than one software product, each can be protected with a unique hardware algorithm. A unique algorithm can be even created in each dongle, thus enabling protection of each application copy with a unique method. Using this capability of Stealth technology, you will make your software products (or different versions of the same product) absolutely protected against universal emulators.
Complexity of Hardware Algorithms

Each hardware algorithm of Stealth dongle is described by its descriptor. Descriptors are stored in the memory of Stealth dongle and are protected from being read or modified. One part of the descriptor describes algo rithm properties (these will be described later). The other part of the de scriptor is called the determinant* of the hardware algorithm. It is essential for the implementation of any particular algorithm. The determinant is a sequence of bytes, which together with the micro controllers program participates in the creation of the dongles hardware algorithm.
34
The length of the determinant can be up to 200 bytes, or 1600 bits. It is not difficult to calculate that a hacker will have to look through up to 21600 dif ferent combinations to single out the right algorithm. If we assume that the minimum execution time of the algorithm with this determinant is 720 ms, then the hacker will need some 3,3*10472... thousand years to single out the algorithm! Even if the algorithm has the shortest determinant (4 bytes, or 32 bits, minimum execution time 250 ms), up to 1051 years would still be required to isolate it.
Using the Hardware Algorithms Properties

Part of the creation of a hardware algorithm is setting its properties. These properties are specified by a combination of special flags* that comprise the algorithm descriptor. By specifying a combination of hardware algo rithms properties, you make it behave the way you wish, and greatly in fluence its representation. The following properties are available in hard ware algorithms of Stealth dongles: 1. Dependence of the hardware algorithm on the dongles ID. An algo rithm with this property will depend on the dongles identification number (ID), a unique 4 byte value embedded in each dongle at the site of manufacturing. Thus, provided all other things are equal, such an algorithm will convert data in each of the dongles in a unique manner. 2. Dependence of the hardware algorithm on the value of its counter. Al gorithms with this property will depend, among other things, on the value of the algorithms counter* (a special 4 byte field included in the descriptor). Therefore, algorithms with different counter values will convert data in a different way, even if their determinants are the same. 3. Limiting the number of executions of the hardware algorithm. An algo rithm with this property can be executed only a specified number of times. The number of algorithm executions is stored in its counter. Each time the algorithm is executed, its counter value will be decre mented. When the value reaches 0, the hardware algorithm will cease to execute. Algorithms with this feature can be effectively used to protect applications with a limited life cycle (for example, demo versions). Hardware algorithms properties can be combined. For example, if you combine the second and third properties you will get a flexible algorithm that will convert data in a different way each time it is run. Using the hardware algorithm with this set of properties ensures a maximum level of security against dongle emulation. This algorithm can be used as a genera tor of pseudorandom numbers of up to 255 bytes (in this case the re sponses* of the flexible algorithm are treated as random numbers).
35
Users Manual
Encoding Data Using Hardware Algorithms

Dongles utilizing hardware algorithms work as follows: a dongle receives some sequence of bytes from the protected application (a query* to the dongle) and converts (encodes or decodes) this sequence using its hard ware algorithm. Thus, the dongle generates a response* which is sent to the protected application. Since the number of bytes that can be converted by the dongles algorithm during one session is limited, the number of com binations of these bytes is also limited. Therefore, the number of queries to the dongle, as well as the number of responses is limited. For example, if the dongles algorithm can convert 2 bytes (or 16 bits) of data simultane ously, then the overall number of queries to this dongle (as well as the number of responses) is 216, or 65536. This strategy is often used by hackers. By bombing the dongle with vari ous data, they get correct responses to all possible queries to the dongle. Then a table is created in which each potential query is supplied with the correct response of the dongle. This table is used in the emulator to gener ate responses of the pseudo dongle. In our example an array of 65536 two byte elements would be enough (this is an array which contains all re sponses of the dongle). In this case, the hacker will not need to look for the specific hardware algorithm; it will be enough for him to know which response (Y) satisfies query (X). Any of the Stealth dongle hardware algorithms can process up to 255 bytes (or 2,040 bits) of data during one session. The structure of algorithms im plies that the length of encoding sequence is the same as the length of the sequence to be encoded. In other words, the N byte long sequence to be encoded is superposed by a non cyclic encoding sequence of the same length. Thus, the overall number of possible queries to Stealth dongle to tals 22040. The number of responses is just the same. To write a complete emulator of the Stealth dongle the hacker would have to create an array of 22040 255 byte elements! It is obvious that there is no point in creating such an array, as it will take up a huge amount of space. Besides, this task would be much more expensive than simply buying a legal copy of a software product.
Fast Conversion Algorithms

Stealth dongle hardware algorithms of have a very important feature: they encode information rather slowly. Thus, to encode 255 bytes the hardware algorithm will require several seconds. At the first glance, this seems to be a disadvantage. In fact, all good algorithms work rather slowly. However, very often you will have to encode large amounts of informa tion from tens of kilobytes to more than one megabyte (various databases, text and graphic files, etc.). Therefore, a special software module has been developed to implement a fast data conversion algorithm*.
36
This algorithm works as follows: you specify an encoding password. Using any of the Stealth dongle hardware algorithms the password undergoes inner transformation (the length of the password is 32 bytes, so, only a few milliseconds are needed for the transformation). Data encoding is per formed with the transformed password using software implemented algo rithm. It is clear that the password for data encoding should be present in the body of the protected application. This can be considered as a disadvan tage since there is a risk that the password can be discovered by the hacker. However, encoding is executed not by the password as it is, but by its transformed form, which is not stored anywhere but created using the dongles hardware algorithm as necessary. Therefore, even if the hacker finds the password in the application body he still will not be able to de code the data correctly. Besides, the fast conversion algorithm is not meant for encoding critical data; the Stealth dongle hardware algorithms should be used for this purpose. Its main objective is to encode and de code data of any size on the fly. The fast data conversion algorithm al lows you to build rather reliable protection for large bodies of information.
Dongle Access Codes

To execute any operations with the Stealth dongle, an access code for this dongle must be specified. Access codes are embedded in Stealth dongles; they cannot be read or modified, and are unique for each user of protec tion. As we have already mentioned, there are two types of access codes used for Stealth dongle: Public Code and Private Codes. Public Code is not a confidential code and is used to identify the dongles of any particular user of protection. Private Access Codes are confidential codes and are used to access the dongle when executing various operations with this dongle. Each Private Code allows only a certain set of operations to be executed with the dongle. If you do not know any of the Private Codes, you cannot execute the operation associated with this code. Whats the point in using different codes for different types of operations? It is necessitated by the fact that the access code being used must be pre sent in the body of the protected application. Therefore, there is a tangible risk that it can be found by the hacker; and if it is the only code, the hacker will get a full access to the dongle. In Stealth dongles, there is no need to store all three Private Codes inside the protected application. For example, if the application just reads from the dongle and uses its hardware algorithms, it is enough to store only the Private Read Code in it. There is no need for the other two Private Codes; so, they will not be available in the application, and hackers will not have a chance to spy them out. Therefore, they will have nothing to do but search
37
Users Manual
for the right Private Codes manually. To find at least one of them, they will have to work through 232 combinations, which process will take up an other 544 years.
Hardware Read/Write Locks

Stealth dongles make use of non volatile memory. A part of this memory is both read and write protected and only read access is permitted for an other part. For the rest of the memory, full access is allowed. It is natural that hackers are highly interested in a dongles memory con tents. After all, if information is read from the dongle, its emulators, or perfect hardware copies can be created. Though it may seem strange, most dongle manufacturers can do nothing to prevent such intrusion. What is even stranger with some dongles, the bulk of memory contents can be read just using common software tools. Stealth technology has solved the problem of copying the dongles. The so lution was to use non volatile memory that allows to set hardware based read/write locks*. There is no way to copy the contents of the locked memory area using software tools, since there are no and there cannot be any suitable tools for that. Stealth dongle does not respond when a read/write request for the protected memory area is received. Hardware locks are implemented on the lower, i.e., hardware level; this prevents unlocking them with software tools. You can independently implement memory locks in Stealth dongles. You can implement hardware locks for any location of the Stealth dongles memory to which access is available, release a lock, increase or decrease the boundaries of the memory to be protected. Hardware read/write locks are automatically implemented for the descriptors of hardware algorithms created in Stealth dongles; this ensures protection of hardware algorithms of Stealth dongles from being illegally read or duplicated.
Encoding the Memory of Stealth dongle

As technology advanced, hackers mastered powerful hardware tools for accessing microchip memory, these tools having become a dangerous weapon in their hands. Although you can prevent the attempts of hackers to read the memory using software tools by applying hardware locks, these locks will not work when hackers use hardware tools. However, the Stealth technology has succeeded in solving this problem as well. All data are stored in the memory of Stealth dongles in an encoded form. Before data are sent to the protected application, they are decoded, and before being written into the dongles memory, the data are encoded. Encoding/decoding is executed by the dongles microcontroller; this makes the reading of the encoding algorithm next to impossible (if you
38
remember, the microcontroller is like a black box and permits no access from the outside). Finally, the most important thing is that each micro controller encodes the data of its dongle using a unique password. There fore, even if someone manages to read the memory contents of a Stealth dongle with the help of hardware tools, there will be no point in writing these data to another Stealth dongle. The microcontroller of another don gle will interpret these data incorrectly because it will decode them in a different way. Accordingly, the hardware copy of Stealth dongle will not function at all. As far as decoding of the read data is concerned, it cannot be done manually since neither the algorithm used for encoding nor origi nal data is known.
Anti debugging Hardware Features

It is widely known that when hackers attempt to crack protection they use special tools. Their most favorite tools are debuggers. There are very pow erful debugging tools available which are capable of emulating anything. It is quite a challenge to develop protection against such tools. Using debug gers, hackers can easily analyze the protection logic: study the protocol of communication with the dongle, send any query to the dongle and get a correct response, etc. However, Stealth dongle will strongly oppose hackers attempts to learn its logic of functioning using debuggers. By analyzing the time intervals at which data are input, Stealth dongle automatically diagnoses the envi ronment in which the application that has sent a query works. If the don gle detects that the communication protocol is executed in the debugger environment (in which case all time intervals are increased) it immedi ately switches to a standby mode and ignores any queries. Of course, the dongle can be woken up, but all the work will have to be started anew. Anyway, Stealth dongle cuts the ground from under the hackers feet. To study Stealth dongle the hacker will have nothing to do but always apply to atypical, unfamiliar and inconvenient methods.
Features of the Protocol of Communication with Stealth dongle

Protocol of communication* with the dongle is the most sensitive part of software hardware protection, since its studying and emulation play an essential part in creating dongle emulators. If the hacker fails to under stand the details of the protocol, he will be unable to create emulators. In fact, data flow between the application and the dongle is not random but complies with certain rules. If the emulator fails to keep to these rules, it will not be understood by the protected application.
39
Users Manual
The developers of dongles devote much effort on improving the strength of communication protocols. The protocol of communication with Stealth dongles has a number of unique features that impact the dongles strength, as well as transparency and compatibility levels. Features of Stealth dongle communication: Encoded. All the data flowing between the application and the dongle are continuously encoded. This feature makes the analysis of the communications protocol very complicated. Changeable. The method of data encoding changes randomly. This makes it difficult for the hacker to trace any logic in the protocol. Noised. A specially generated garbage (meaningless information) mixed up with the meaningful data is transferred between the protected applica tion and the dongle. Moreover, the nature of the garbage, as well as the order in which the meaningful data are interwoven in it, are changed in the course of time. As a result, the logic of the protocol understanding be comes even more difficult. Adaptive. During the execution of the protocol, its parameters are opti mally adjusted to the specific hardware and software environments. This enables reliable functioning of Stealth dongle on any computers, regard less of the quality of the parallel port. Automatic verification and retries. Every write to the Stealth dongles memory is verified, i.e., the adequacy of written data is always checked. If failure occurs during communication with the dongle due to the interfer ence with other devices, the operation is automatically retried. All of fea tures above help to considerably increase the reliability of communication with Stealth dongle.
Power Saving and Full Transparency

A flexible power consuming scheme is used in Stealth dongles, determin ing the level of their transparency. In addition to the two standard modes waiting, or sleeping mode (when no data are sent via the dongle) and active mode (when the dongle processes data intended for itself) the Stealth dongle also has a transient mode when a minimum of energy is consumed. Stealth dongle switches to this mode when it receives data in tended for a peripheral device connected through this dongle. This new mode is available due to the Stealth dongles microcontroller. When the dongle receives data intended for a peripheral device, the mi crocontroller switches to a very low speed letting the data flow directly through the dongle. Meanwhile, the dongle consumes very little power because of the low microcontroller speed. This mode is called the tran sient mode of a Stealth dongle. On receiving data intended for the dongle, the microcontroller enters its normal mode, activating the dongle.
40
Why is this so important? The data array intended for the peripheral de vice transits through the dongle. In this case, dongles that are not in a transient mode have to consume the same amount of energy as during processing their own data. Moreover, the higher the speed of the periph eral device (i.e., the faster the transit of data through the dongle is), the more energy these dongles consume. As a result, the dongle starts to inter fere with the parallel port, consuming a considerable amount of energy. Sometimes this may lead to a risk of partial data loss, i.e., loss of the don gles transparency. Flexible energy consumption and availability of the transient mode pro vide the dongle with a very high level of transparency. In practice, Stealth dongles are transparent to any peripheral devices and any com munication protocols. This feature of Stealth technology based dongles has been reflected in the name of the technology. The above capabilities of Stealth dongles have also enabled their ability to be cascaded in one parallel port. Unlike other manufacturers dongles, the number of Stealth dongles that can be cascaded depends on the PCs hardware LPT port load capacity only. The better the hardware, the more Stealth dongles can be attached to the computer parallel port simultane ously. An average PC allows about 10 dongles to be cascaded.
Special Features of Implementing Stealth Technology in Guardant Fidus

Implementation of Stealth technology in Guardant Fidus has a number of specific features, which bring about certain restrictions. Mainly, this has to do with the structure of hardware algorithms. Guardant Fidus hardware algorithms, as well as their descriptors represent a part of the dongles microprogram and cannot be changed. Specific in ternal arrangement of Guardant Fidus does not allow either creation of new algorithms or deletion of existing ones. Eight hardware algorithms can be used. Four of them are unique for each customer, and the remain ing four are unique for each dongle. The unicity of algorithms, and also the fact that their descriptors are not stored in the user memory, add strength to the protection. Parameters of Guardant Fidus algorithms have been selected in such a way as to provide a high level of protection for most of the applications and optimal system speed. However, the prede termined nature of the algorithms reduces flexibility of the system and makes the usage of some of their features impossible. In particular, the fixed length of the determinant will not allow changing the complexity of algorithms, while the absence of counters makes it impossible to employ a counter dependent algorithm and to limit the number of its executions. Regarding all the remaining features, the technology used in Guardant Fidus is analogous to the Stealth technology as described above.
41
Chapter 5. Structure of Stealth-dongle
Chapter 5 Structure of Stealth Dongle

You have already acquired first knowledge of how Guardant dongles are organized. However, Stealth dongles require a deeper study. From this Chapter onwards you will be introduced to the internal ar rangement of Stealth dongle, and learn the principles of creating and us ing its hardware algorithms. This knowledge will help you to build a sound and reliable protection for the software. Important
Please pay special attention to the difference between various memory addressing methods, and note which memory areas are available for use.
The Dongles Memory and Memory Addressing Methods

Guardant Stealth, Guardant Fidus and Guardant Net dongles contain 256 bytes of non volatile memory. A part of this memory is not available for either reading or writing, another part is available for reading only, and the third part can be edited only by special operations. The rest of the memory is available for both reading and writing. Also, a part of the latter can be used in a special way. You can implement hardware read and/or write locks in the memory. The dongles memory may contain information of the three following types: service information, hardware algorithms descriptors and data that you use for protecting the software product. The memory can be addressed in two modes: User Address Mode (UAM) and System Address Mode (SAM). In SAM, all 256 bytes of information are available (however, read and/or write locks are implemented for some memory areas). In UAM, access is provided to cells with the addresses beginning with 30 SAM, i.e., 226 bytes are available. SAM should be used only for reading the fields that cannot be accessed in UAM (for example, ID field) and for entering the descriptors of hardware algorithms. In other cases, UAM should be used. This mode provides ac cess to the memory area beginning with address 30 SAM. For example, the cell with address 33 in SAM has address 3 in UAM, and the cell with address 20 SAM is not available in UAM.
43
Users Manual
The two addressing modes have been introduced to prevent you from hav ing to modify the application, when in the future advanced versions of dongles are released and new fields are added before the field with address 30. It has to be remembered that the cells addresses of the user memory will not change in UAM. The dongle knows how to report this start ad dress in UAM. This provides for maintaining top to down and down to top compatibility of dongles versions.
Stealth Dongles Memory Map

The dongles memory can be logically segmented as follows (SAM ad dressing): bytes 0 through 13 are read only. This memory area is used by the dongle for its own purposes. The contents of this area are programmed at the site of manufacturing; it is a read only area. If you attempt to write to this area with the API function, nse_VerifyError message will be returned. This memory is not available in UAM. bytes 14 through 25 are read only. They contain Public code, the dongles hardware version, Guardant Net dongles maximum network license limit, bits containing the dongles type and ID. These memory fields can be useful when, for example, the dongles ID needs to be identified. The data are entered into this memory area at the dongles production stage. An attempt to write to this memory returns nse_VerifyError message. This memory area is not available in UAM. bytes 26 through 29 are available for Protect and Init operations only. They contain addresses of read/write locks and the number of hardware algorithms in the dongle. The fields of this memory are used to identify the number of hardware algorithms in the dongle and addresses of read/write locks. An attempt to write to this memory avoiding Protect operation returns nse_VerifyError message. This memory area is not available in UAM. bytes 30 through 43 always permit read and write access and contain the so called general purpose fields: program number, version, serial number, mask, GP executions counter (counter #1), current network license limit (counter #2), index for the dongles remote programming. These fields are available in UAM and can be used for various purposes, such as storing the programs serial number. These fields are intensively used by automatic protection utilities.
44
bytes 44 through 245 permit read and write access if they are not locked, and can be used for storing user data and hardware algorithms descriptors of Guardant Stealth and Guardant Net. These bytes are zero filled by Init operation. bytes 246 through 247 permit read and write access and you may also implement read/write lock for them; these bytes are also zero filled by Init operation. They are used by the automatic protection of executable applications. It is not recommended to use these bytes for other purposes. bytes 248 through 255 permit read and write access and you may also implement read/write lock for them, but they are not zero filled by Init operation. These cells are intended for diagnostic purposes and, therefore, are not recommended for other use. The cells are available in UAM. A detailed description of all memory fields of Stealth dongle is provided in the table below (if this information appears too special, you may skip to the next section and revert to it later, when you may wish to use all re sources of the dongle):
SAM address 0 1 2 3 4 6 7 UAM address N/A N/A N/A N/A N/A N/A N/A Length Read (R) Field Name in Bytes Write (W) Lock Read-only fields 1 1 1 1 2 1 1 W W W W W W W kmModel kmMemSize kmProgVer kmProtocol kmClientVer kmUserAddr kmAlgoAddr Dongle model code Memory capacity code Program version Version of communication protocol with the dongle Version of lower-level kernel UAM area address in words Address of hardware algorithms allocation table in words Address of the parallel port to which the dongle is attached Reserved Public code in numerical form Dongles version: bytes 0 to 3: minor bytes 4 to 7: major Maximum license limit of Guardant Net, which is programmed when the dongle is sold. Field Description
N/A
kmPrnPort
10 14 18
N/A N/A N/A
4 4 1
W W W
kmReserved kmPublicCode kmVersion
19
N/A
kmLANRes
45
Users Manual
SAM address 20
UAM address N/A
Length Read (R) Field Name in Bytes Write (W) Lock 2 W kmType
Field Description Bits containing the dongles type. The field can be used in the dongle search condition. The dongles ID (unique identification number). Can be used in the dongle search condition.
22
N/A
kmID
26
27
28 29
30
31
32
34
36
38
40
Special operations fields. You can change them only with the help of Init and Protect operations N/A 1 W kmWriteProtect SAM address of the first writable byte/2 (the lock is word aligned). N/A 1 W kmReadProtect SAM address of the first readable byte/2 (the lock is word aligned). N/A 1 W kmAlgoNum Number of the hardware algorithms. N/A 1 W kmTableLMS Contains address of the first byte of the license table (SAM mode) General purpose fields 0 1 kmNProg Program number. Can be used in the dongle search condition. 1 1 kmVer Version. Can be used in the dongle search condition. 2 2 kmSN Serial number. Can be used in the dongle search condition. 4 2 kmMask Bit mask. Can be used in the dongle search condition. 6 2 kmGP Counter of GP program executions (counter #1). Cannot be used in the dongle search condition. 8 2 kmRealLANRes Specified current network license limit of Guardant Net (counter #2). Cannot be used in the dongle search condition. 10 4 kmIndex Index. Cannot be used in the dongle search condition.
46
SAM address 44
UAM address 14
Length Read (R) Field Name in Bytes Write (W) Lock 202 User fields kmAlgoAddr
Field Description
User data (including algorithms descriptors of Guardant Stealth and Guardant Net) can be located beginning from this address. This field is used by automatic protection utilities and NSKUTIL. It can be used only if you do not employ automatic protection. This field is used by the dongle diagnostic utilities. It is STRONGLY recommended not to use it. The field is not zero filled by Init operation. Available in UAM only.
Special purpose fields 246 216 2
248
218
How the Dongles Memory is to be Used

You can use all these fields with the API functions. Some fields are also used by the automatic protection. This memory area is always write protected, therefore you cannot edit its contents. kmModel field. Contains dongle model code. The code can assume the following values: 0 Guardant Stealth, Guardant Net (LPT) 1 Guardant Stealth, Guardant Net (USB) 2 Guardant Fidus (LPT) kmMemSize field. Contains the information about the dongles memory capacity. The value of the field corresponds to an exponent of 2 resulting in the dongles memory capacity in bytes. kmProgVer field. Contains microcontrollers program version. This field can be used to identify dongles with customized microprograms. kmProtocol field. Contains the version of communication protocol with the dongle. The field is intended for internal usage. It is used by diagnos tics utilities. kmClientVer field. Contains the version of lower level kernel. Value 0x104 corresponds to version 1.4. The field is intended for internal usage. It is used by diagnostics utilities. kmUserAddr field. Contains SAM address of the location where user memory begins in two byte words.
47
Users Manual
kmAlgoAddr field. Contains the beginning address of the hardware algo rithms allocation table in two byte words. kmPrnPort field. Contains the address of the parallel port to which the dongle is attached. kmPublicCode field. Contains Public code of the dongle in numerical form (4 bytes), which unambiguously identifies you as the owner of this dongle. kmVersion field. Contains the hardware version of the dongle. Since Stealth dongles continuously advance, the application may verify the hardware version to check capabilities of the dongle with which it cur rently works. kmLANRes field. Contains the maximum license limit of network dongle. When you buy dongles of this type, you buy them with a specific license limit, which is written in this field. In Guardant Stealth the value of this field is 0. kmType field. Indicates the dongles type. Allows the software to identify the type of Stealth dongle (Guardant Stealth, Guardant Fidus or Guard ant Net). You may use this field when verifying the presence of the dongle (this can be handy when you use both types of Stealth dongles for protect ing the software products). kmID field. Contains the dongles identification number (ID). ID is en tered into this field of the Stealth dongle at the site of manufacturing. It is guaranteed that there are no two dongles with same IDs. This field is used in a special automatic protection mode. You may adjust your software product to the dongles ID, and after that it will work only with the dongle that has this particular ID. Special Operations Fields These fields contain information about read or write locks that have been implemented for user area, as well as about the number of hardware algo rithms in this Stealth dongle. You can change the contents of these fields only using Init and Protect operations (see Operations for more details). The fields contain information for internal usage only. There is no reason in using the raw contents of these fields when building protection. kmWriteProtect field. Contains address (SAM) of the first byte/2, which permits write access (the lock is word aligned; addressing in words is used). If the value is 0 it means that no write locks are implemented. The value should be higher than 22 (i.e., the lock can be implemented begin ning with address 44 SAM). You can only write into this field using Pro tect operation, and only if the value in this field is 0. Zero filling is possible only when Init operation is used. kmReadProtect field. Contains address (SAM) of the first byte/2, which permits read access (the lock is word aligned; addressing in words is used).
48
If the value is 0 it means that no read locks are set. This value should be above 22 (i.e., the lock can be implemented beginning with address 44 SAM). You can only write into this field with the help of Protect opera tion, and only of the value in this field is 0. Only the Init operation can clear this field. kmAlgoNum field. Contains the number of hardware algorithms in Stealth dongle. Initially the value 4 is written into this field, because at the presales stage four default algorithms are created in the dongle. The maximum value is 18. This is ignored in Guardant Fidus since the number of algo rithms is predetermined (8 algorithms). General purpose Fields Most of these fields are intensively used by the automatic protection (see Chapter 12 Automatic Protection in Every Detail). You can also change the contents of these fields and use them with the API functions. kmNProg Program number. This field can be checked to distinguish between various software products protected with Guardant system. kmVer Program version. You can use this field to check software product versions when new software version is to be pro tected. kmSN Serial number. You can adjust your software product to this value so that the programs of one of end users do not work with the dongle of another end user. kmMask Mask. This field can be useful if the software product com prises several independent applications. You can check the contents of this filed in order to be able to permit/forbid running of certain applications from your software package. kmGP Application executions counter (GP, counter #1). The value of this field is decremented by 1 each time when special API function is called, or when an application is run that has been protected using automatic protection in a special mode. As soon as the value reaches 0 all subsequent similar queries to the dongle will return an error. The field is used to limit the number of executions of the protected application. kmReal Actual license limit of network dongle (counter #2). Initially LANRes the value of this field is equal to the value of kmLANRes field and can never exceed this value. However, you can de crease it using dongle programming utilities. kmRealLANRes field is used by Guardant Net servers to analyze the license limit. kmIndex It is used by the dongle remote programming utilities.
49
Users Manual
User Fields If you intend to use the API functions and hardware algorithms inten sively, this memory area will be your primary target. It is here where you can store the protection related data. The following information is entered into this memory area: hardware al gorithms allocation table, hardware algorithms descriptors and data, which you can use with the API functions. Unlike in Guardant Stealth and Guardant Net, in Guardant Fidus dongles this memory area is en tirely allocated for user data, because hardware algorithms are already predefined in them, and so no space is needed to store the descriptors. At the site of manufacturing the descriptors default algorithms that occupy altogether 64 bytes are entered in Guardant Stealth and Guardant Net. By default, hardware algorithm #0 (AutoProtect) is used by the automatic protection of finished applications (see Automatic Protection in Every Detail). Using a special utility, you can create your own hardware algo rithms and add them to already existing ones, or change the descriptors of default algorithms and make them unique as well (see Hardware Algo rithms for more details on creating hardware algorithms). All algorithms (both default and those designed by yourselves) can be used with the help of special operations. See below for more details on algorithms. Besides, this memory area can contain any data that you may wish to use when protecting the software. These may include keywords, data sets, program code fragments, etc. You can access them if you execute read operation with API functions. This memory area should be organized as follows: first, you should enter hardware algorithms allocation table and all algorithms descriptors, and then any other data. This should be done because the algorithms de scriptors must be read and write protected, and locks are implemented for the continuous memory area beginning from address 44 SAM (kmAl goAddr field). Special Purpose Fields The last and the most remote area of the dongles memory is used by the automatic protection, Stealth dongle programming utilities, as well as by special programs used to diagnose its working condition. Warning
To avoid problems do never store any data in the fields of this memory area!
50
Chapter 6. Hardware Algorithms
Chapter 6 Hardware Algorithms

This Chapter will provide you with a detailed description of hardware al gorithms. You will learn about their use against various cracking methods, how they are created in the dongle, how they are built, and how they can be used to convert data and to make the dongles logic more sophisticated. Also in this Chapter you will find examples of using algorithms in the pro tected applications. Warning
Hardware algorithms, such as they are described in this Chapter, are used in Guardant Stealth and Guardant Net. Algorithms of Guardant Fidus are somewhat different; therefore, not all of the features described below are available for them. The distinctive features of hardware algorithms related to Guardant Fidus are described in Specific Features of Guardant Fidus Hardware Algorithms.
Important
Please pay special attention to the algorithms organization and to the specific features of data conversion methods using these algorithms.
What are Hardware Algorithms for?

To answer the question we will have to provide are going to give a bit of background information. The first systems of protection against computer piracy were purely soft ware based. Protected application was bound to the information held ei ther on the computer (BIOS type and version, unique characteristics of the computer, etc.) or on a key diskette (non replicable key label). Hackers were very quick to learn how to crack such protection. As real experts they knew all ins and outs of the computer and of diskettes, there fore it was not a problem for them to find the key information and change its validation procedure. When dongles appeared the hackers task became more difficult as the dongle information was now stored in an external device whose internal design was unfamiliar to the hacker. However, very soon hackers found their way of cracking those first don gles. The fact is that the dongles of the first generation used to have a rather simple logic of functioning. In most cases, their responses to the application were either yes or no. Primitive logic along with relatively vulnerable communications protocol were the underbelly of those don gles. Hackers succeeded in analyzing the protocol of communication with the dongles and learnt to build their protection cracking scheme based on this protocol. This is how emulators of dongles appeared.
51
Users Manual
Emulator is a program module which is capable of imitating communica tion with some dongle and which palms off the data upon the protected application, which it expects. From the standpoint of the protected appli cation, a software emulator becomes a full substitute for the dongle. The only effective way to fight emulation is to make the dongles func tioning logic more sophisticated. Only when the dongle exchanges a lot of data with the application, which are each time different, does creation of an emulator turn into a painstaking job. Only when these data cannot be spied or foreseen creation of an emulator becomes next to impossible. Thus in Stealth dongles the hardware algorithms have been introduced as a solution to the problem of emulation. First and foremost they have given an opportunity to make the dongle functioning logic much more sophisti cated. Secondly, the dongle learnt to generate data that a hacker is un able to foresee since they do not exist in pure form at all. Today Stealth dongles enjoy quite secure protection against emulators that constitute enemy # 1 to the contemporary hardware software protection.
Protective Features of Hardware Algorithms

It has been noted above that hardware algorithms make protection logic far more sophisticated. If implemented correctly, the protection renders emulation virtually impossible. The hardware algorithms of Stealth dongles support the following protec tive features: Data are converted not inside the application but in the dongle which makes it impossible to study the algorithms with a debugger and useless to remove protection modules from the application. Data are converted by long data blocks (up to 255 bytes). This makes manual decoding very difficult and creation of dongles emulators practically impossible. The microcontrollers commands have been selected in such a way that regardless of the algorithms type all bytes of data to be converted by this algorithm are significant (i.e., the code chain has the same length as the sequence to be converted). The user of Guardant Stealth and Guardant Net knows only the descriptor of the algorithm, while the designers of dongles know only the microprogram, which processes this descriptor. Thus, a particular representation of the hardware algorithm created by the user cannot be known to anyone.
52
One and the same protected application can use several unique hardware algorithms (up to 18) to convert various information. This would force a hacker to reach the representation of each algorithm. You can easily create hardware algorithms whose representation would depend on a variable. Therefore, such algorithms will always convert information in a different way.
Hardware Algorithms Structure

The microcontroller of Guardant Stealth, Guardant Fidus and Guardant Net dongles contains a set of commands (microprogram), which are em bedded in the dongle at the site of manufacturing. The microcontrollers commands can neither be read nor modified. The commands have been selected in such a way so as to form a lot of hardware algorithms of Y=F(X) type when combined with the descriptor. The descriptor specifies the properties and representation of each hard ware algorithm. Each hardware algorithm has its descriptor. Each descrip tor occupies a certain space in the memory; therefore, the number of al gorithms in the dongle is limited. Since a hardware algorithm is fully described by its descriptor, we imply the structure of its descriptor when speaking about the structure of the hardware algorithm. The descriptor of Stealth dongles hardware algorithm comprises the fol lowing components:
Offset from the beginning of the descriptor 0 1 2 6 7 8 Field length in bytes 1 1 4 1 1 km_ad_klen Field name Field description
km_ad_flags km_ad_algo km_ad_GP km_ad_klen km_ad_blen km_ao
Algorithms flags. Reserved (should be 0). Algorithms counter. The size of the determinant in bytes. The size of the query in bytes. Algorithms determinant.
km_ad_flags field. Contains flags*, which specify the properties of the hardware algorithm. The following flags can be set (names of flags pro vided below are used in Guardant API): nsaf_ID: the algorithm depends on the ID nsaf_GP: the algorithm depends on its km_ad_GP field nsaf_GP_dec: km_ad_GP field must be decremented each time before the algorithm is executed.
53
Users Manual
km_ad_GP field. Contains the algorithms counter*. If nsaf_GP_dec is indicated, the field specifies the number of times the algorithms can be executed. When the counter reaches 0 value the algorithm ceases to con vert data. This field can be incremented only if the entire algorithm is written anew. km_ad_klen field. Contains the size of the algorithms determinant in bytes (should be even number ranging between 4 and 200). To achieve op timal protection level versus execution time ratio it is recommended to use a value between 4 and 32. km_ad_blen field. Contains the size of the algorithm query* in bytes. The algorithm can convert only data arrays whose length is equal to this size. Allowed values range between 4 and 255 (it is recommended that queries of even numbered length be used). km_ao field. Contains the algorithms determinant*. The determinant is very important during specifying a method for converting data (i.e., when specifying the type of hardware algorithm). Hence, the minimum length of an algorithm descriptor is 12 bytes (8 bytes + the minimum length of the algorithms determinant). A hardware based read and write lock is implemented for the memory area occupied by descriptors; this makes illegal study, replication or modi fication of hardware algorithms impossible. A most important part of the descriptor is its determinant. The length of the determinant ranges between 4 and 200 bytes. It is very important for the representation and properties of the hardware algorithms to be specified by you. Using a special utility, you can easily design descriptors of unique algorithms whose representation will be un known to anyone but you. This ensures a maximum level of protection. Hardware algorithms are designed to convert information of various size and kind. During one session, the algorithm can convert from 4 to 255 bytes (it is recommended that even number of bytes be used). This infor mation should be pre encoded by a special utility and then, during the running of the protected application, it should be specified as an in pa rameter when API special function is called.
54
Methods of Creating Hardware Algorithms

To create a hardware algorithm you should design its descriptor. This can be achieved by two methods: Using NSKUTIL Program This is the easiest and a most preferable way of creating hardware algo rithms. NSKUTIL provides easy to use window based interface for this purpose. You should just specify some major properties of the future algo rithm, all the rest will be done by the program. It will create algorithms al location table, write algorithms descriptors in the dongle and implement read/write locks for the memory area occupied by these descriptors. Using NSKUTIL, you can also add new algorithms to already existing ones, change the properties and the representation of the existing algo rithm (i.e., its descriptor) or remove some (or all) of the algorithms. Manually, Using Guardant API Special Functions This method is much more sophisticated. It includes the following steps: 1. If algorithms are already present in the dongle, they should first be removed using Init operation. 2. The algorithms allocation table* is written in the area beginning from kmAlgoAddr address. 3. The descriptors of algorithms are written in the area beginning from the next word (i.e., algorithms should always start from the even ad dress). 4. Using Protect operation read/write locks are implemented for the memory area, which is occupied by descriptors, while the number of algorithms is written to kmAlgoNum field. From this moment, you will not be able to read the descriptors until the lock is released. This method has some severe limitations. It can only be used to remove all existing algorithms and create new ones instead. However, it does not al low you to add a new algorithm or change the descriptor of the existing al gorithm, or remove algorithms partially.
Hardware Algorithms Features

Hardware algorithms features are specified by the flags* of its descriptor. Major algorithms features are as follows: Dependence on the ID nsaf_ID flag sets the dependence of the hardware algorithm on the identi fication number (ID) of a particular dongle. This means that such an algorithm will convert data in each of the dongles in a unique way, even if all descriptor values are the same in all of the dongles.
55
Users Manual
Warning
In case an end-user damages the dongle with such a hardware algorithm by accident, you will not be able to replace it with another dongle with the same algorithm since there cannot be two dongles with identical IDs.
Dependence on the Algorithms Counter Using nsaf_GP flag, you may specify a data conversion method that would depend on the algorithms counter (i.e., on the value of km_ad_GP field in its descriptor). When preparing the dongles for sale you can enter random numbers to the algorithms counter field; with other things being equal, this will automatically make hardware algorithm representations unique for each dongle. An Algorithm with a Limited Number of Executions If nsaf_GP_dec flag has been set in the algorithm descriptor, then each time this algorithm is executed the value of its counter (km_ad_GP field of the descriptor) will be decremented by 1. When the value in the counter reaches 0, the algorithm will cease to convert data. This is an excellent way of creating an application protected through limiting the number of its executions. The advantage of this method compared to the automatic protection method, which is similar to the described, is that it makes it impossible to increase the number of executions of the protected applica tion illegally even if all access codes to the dongle are known. Simultaneous setting of nsaf_GP and nsaf_GP_dec flags gives an oppor tunity to obtain a hardware algorithm with extremely valuable features. This algorithm will execute a limited number of times and each time it will convert data differently since it will depend on the variable value, i.e., on decrementing value of the algorithms counter. The algorithm with such features allows you to arrange for the protection based on changeable data, which provides strong resistance to intrusions.
The Importance of the Algorithms Determinant

By combining hardware algorithms features one can manipulate to a cer tain extent the way the data are converted. Still, the predominant factor which influences on a particular representation of the algorithm is its de terminant. Hardware algorithms determinant presents a set of bytes written in a spe cific field of the algorithm descriptor and interpreted by the microcontrol ler according to its microprogram (set of commands). The determinant should be of even length ranged between 4 and 200 bytes.
56
There is no direct dependence between values of the determinant and the complexity of the specified algorithm. For example, you cannot say for sure that value 32 written in one of the determinants bytes will specify a more sophisticated and subtle algorithm than value 31. Furthermore, had such a dependence existed this would be somewhat dangerous as in this case a hacker could figure out the value of the determinant as soon as he got access to the information before and after its conversion in the dongle. Therefore, there are only a few recommendations that you can follow when creating determinants: The longer the determinant, the more sophisticated and reliable the algorithm it specifies (yet longer time will be required for the algorithm to convert information). It is recommended that determinants should be maximum 32 bytes long. Change of at least one byte of the determinant causes a complete change in the whole conversion process. You can use this to render unicity to those hardware algorithms that are written into the dongles at presale stage without having to change any features. The data in the determinant should not contain any zeroes as this may considerably worsen the quality of the algorithm. It is advisable that the number of even valued and odd valued bytes be approximately the same.
Types of Hardware Algorithms

In order to make it easier for you to use hardware algorithms, some com binations of their features have been standardized. This resulted in crea tion of several algorithm types adapted to standard protection tasks. The following algorithm types are available: Random Random number generator. It can be used for generating uniformly dis tributed random numbers. It has the following features: runs a limited number of times, depends on the decrementing value of the algorithms counter (nsaf_GP and nsaf_GP_dec flags are set) the algorithms counter has fixed high value (around 232) by default, the length of the determinant is 4 bytes by default, the length of the query and response (i.e., of a random number) is 4 bytes.
57
Users Manual
Fast Fast reversible conversion algorithm. It can be used for a fast reversible conversion of large volumes of information using CodeInit, EnCode and DeCode operations (see Fast Reversible Conversion Using CodeInit, EnCode and DeCode Operations for more details). It has the following features: the algorithms flags are not used (0 value in the flags field) the algorithms counter is not used the determinant has a fixed length which is 8 bytes the query has a fixed length, which is 32 bytes. Simple User specified algorithm. It is a type of algorithm, which gives you a free hand in designing its properties and particular representation. You can set various combinations of flags, specify any length for the determinant and query. Algorithms of this type can be used for a wide range of tasks. As you can see, the above algorithm types (except for Simple) have a number of limitations. This is quite natural since each type is focused on a specific range of tasks. However, it is still possible to change the determi nants of such algorithms making their representation unique. You can arrange all these algorithms in the dongle by NSKUTIL program using the names assigned to algorithm types (Random, Fast or Simple).
Example of Hardware Algorithms Descriptors

In our example, we will investigate the creation of four default algo rithms whose descriptors are entered into the dongle at the stage of pre sales preparation:
Address Address Field Length Value (SAM) (UAM) in Bytes 44 45 46 47 48 52 53 54 14 15 16 17 18 22 23 24 1 Field Name Comments
Hardware algorithms allocation table 26 (i.e., 52/2) n/a Address of the descriptor of algorithm #0 1 32 (i.e., 64/2) n/a Address of the descriptor of algorithm #1 1 40 (i.e., 80/2) n/a Address of the descriptor of algorithm #2 1 46 (i.e., 92/2) n/a Address of the descriptor of algorithm #3 4 0, 0, 0, 0 n/a Reserved Algorithm #0: AutoProtect (for automatic protection) 1 0 km_ad_flags Flags are not used 1 0 km_ad_algo Reserved 4 0, 0, 0, 0 km_ad_GP Algorithms counter is not used
58
Address Address Field Length Value (SAM) (UAM) in Bytes 58 59 60 28 29 30 1 4
Field Name km_ad_klen
Comments
64 65 66 70 71 72
34 35 36 40 41 42
80 81 82 86 87 88
50 51 52 56 57 58
The size of the determinant is 4 bytes 1 4 km_ad_blen The size of the query is 4 bytes 4 D3h, F5h, km_ao Algorithm determinant for the 4Dh, 48h Demo-dongle. In operational dongles this determinant is unique for each user of protection. This helps to ensure uniqueness of automatic protection of dongles for all customers. Algorithm #1: Fast (used by CodeInit operation) 1 0 km_ad_flags All the flags of this algorithm should contain zero values. 1 0 km_ad_algo Reserved 4 0, 0, 0, 0 km_ad_GP Algorithms counter is not used 1 8 km_ad_klen The size of the determinant is 8 bytes 1 32 km_ad_blen The size of the query is 32 bytes km_ao Algorithm determinant for the 8 12h, 79h, Demo-dongle. 64h, 73h, In operational dongles this 37h, 16h, determinant is unique for each F4h, 73h user of protection. Algorithm # 2: Random (random number generator) 1 3 km_ad_flags nsaf_GP and nsaf_GP_dec flags are set 1 0 km_ad_algo Reserved The maximum value of the 4 FEh, FFh, km_ad_GP algorithms counter is set FFh, FFh 1 1 4 The size of the determinant is 4 bytes 4 km_ad_blen The size of the query (random number) is 4 bytes Algorithm determinant for the 91h, E2h, km_ao Demo-dongle. 03h, 5Eh In operational dongles this determinant is unique for each user of protection. Algorithm #3: DEMO (to be used in examples) 0 km_ad_flags Flags are not used 0 km_ad_algo Reserved 0, 0, 0, 0 km_ad_GP Algorithms counter is not used 8 km_ad_klen The size of the determinant is 8 bytes 4 km_ad_blen The size of the query is 4 bytes Algorithm determinant. 78h, 54h, A3h, km_ao In operational dongles this 22h, determinant is not unique (in 17h, E1h, FEh, order to make examples work). 61h 4 km_ad_klen
92 93 94 98 99 100
62 63 64 68 69 70
1 1 4 1 1 8
59
Users Manual
After these data have been written to the dongles memory, the following values are entered using Protect operation: kmReadProtect= (100+8)/2=54 (100 is SAM address of the last field in the last algorithm, 8 is the length of this field), kmWriteProtect=54, kmAlgoNum=4. Hardware algorithms allocation table contains SAM addresses of algo rithms descriptors. Please note that addressing in words is used (this should be remembered when you create hardware algorithms manu ally; NSKUTIL utility writes the appropriate values into this table automatically). Algorithm #0 (AutoProtect). It belongs to Simple type and is used by the automatic protection by default. Warning
If you are using automatic protection do not remove this algorithm from the dongle, otherwise you should use a special automatic protection option (see Do Not Use Hardware Algorithm # 0).
The determinant of this algorithm is unique for each user of Guardant protection; therefore, Algorithm #0 converts data in a unique manner for each user (the same applies to other algorithms that are created in the dongles by default, except for Algorithm #3 DEMO). Despite the fact that this algorithm belongs to Simple type (i.e., user specified algorithm), you will not be able to change the combination of flags and lengths of the determinant and query of this particular algorithm using NSKUTIL program. This has been done to ensure that the change of algorithms features do not interfere with the running of automatic pro tection. However, you may edit the determinant of this algorithm. Algorithm #1 (Fast). It belongs to Fast type. It is used to carry out fast reversible conversion of large volumes of information by CodeInit, En Code and DeCode operations. If you plan to convert your information thus, you do not need to create any new algorithm of Fast type, as it al ready exists in the dongle. However, you may edit its determinant. Algorithm #2 (Random). It belongs to Random type. It is used to gener ate uniformly distributed random numbers. You can edit the determinant of this algorithm to make its particular representation unknown to anyone but you. Algorithm #3 (DEMO). It belongs to Simple type. It is used in samples from API directory. You may change all elements of the descriptor of this algorithm and use it to solve wide range of tasks related to protection.
60
Specific Features of Guardant Fidus Hardware Algorithms

Guardant Fidus uses same types of algorithms as the other dongles of Guardant family, i.e., Simple, Fast and Random. They are described in detail in Types of Hardware Algorithms. Methods of using Guardant Fidus hardware algorithms are generally the same as those for Guardant Stealth and Guardant Net hardware algorithms. Hardware algorithms in Guardant Fidus are fully determined by the mi crocontroller and do not require any space to store the descriptors. User data can be stored in the area starting from address 44 SAM, i.e., the ad dress where Guardant Stealth and Guardant Net store hardware algo rithms descriptors. As a result, more storage becomes available. Algorithms descriptors are not stored in user memory and cannot be changed, removed or added to. A particular representation of hardware algorithm is unique for each customer. There are algorithms, which also depend on the ID. These can be used for building up a unique protection for each particular dongle. Totally, there are eight algorithms in the don gle: four algorithms, which are unique for each user, and four algorithms, which depend on the ID. There are no counters available in Guardant Fi dus algorithms; therefore no dependency can be established between the algorithm and the counter. List of Guardant Fidus Hardware Algorithms:
# Name Type Dependence on ID No No No No Yes Yes Yes Yes Query Size in Bytes 4 32 4 4 4 32 4 4 Genuine random numbers generator For samples and tests Notes
0 1 2 3 128 129 130 131
AutoProtect Fast Random Demo AutoProtect ID Fast ID Random ID Demo ID
Simple Fast Random Simple Simple Fast Random Simple
Used by the automatic protection
Warning
Guardant Fidus algorithms convert data differently than Guardant Stealth algorithms, therefore responses of Guardant Fidus algorithms differ from those generated by Guardant Stealth algorithms. To avoid confusion when using different dongles you should specify the type of the dongle.
Important
Algorithms of Random type generate 4-byte long genuine random numbers whose sequence cannot be repeated if generator is re-initialized.
61
Users Manual
How to Use Hardware Algorithms?

How to Convert Data Using Hardware Algorithms Hardware algorithms of Stealth dongles provide you with two methods of data conversion. These methods have a number of essential differences and therefore are used for different purposes. Let us have a look at these methods. Conversion by Transform Operation Conversion by Transform operation usually takes place when verifying whether the application copy is legal. The main purpose of this method is to make the functioning logic more sophisticated and thereby prevent its emulation. Conversion has two important features: It is one way conversion, i.e., there is no F 1() function reverse to F(X) function so that X=F 1(F(X)). The whole conversion is carried out by the dongle, therefore the procedure takes quite a long time (about 250 ms are required to convert four bytes of information). Based on these features you can outline a range of tasks that can be solved using this conversion method. This conversion method can be used in case smaller volumes of information are to be converted (tens or hundreds of bytes). This method can be used to encode data that you will not have to decode later into their original form. For example, if we take a most simple case: the application can convert some optional data sequence, determine the CRC of the response sequence and compare it to the reference CRC obtained at the stage when protection was implemented. If CRCs match each other, then the protected application copy is deemed legal. It is harder to emulate such communication with the dongle than carry out a simple validity check of the dongle based on access code. This method is often used together with the fast reversible conversion method described below. For example, it provides a password for EnCode and DeCode operations. It is not recommended that you use this method to encode data since the conversion is one way. Generally, reversibility in any dongles which generate Y=F(X) functions is quite a big issue. The matter is that advanced reversible algorithms re quire quite a lot of resources, while the dongle does not have enough re sources to provide the required performance yet.
62
Therefore, another data conversion method has been created which is only partially based on the dongles algorithms and has overcome the drawbacks of the Transform method. Such conversion can be achieved with CodeInit, EnCode and DeCode operations. Fast Reversible Conversion Using CodeInit, EnCode and DeCode Operations This method is most often applied for encoding / decoding data which are used by the protected application. This data conversion method is characterized by two important features: The conversion is reversible, i.e., there is F 1() function reverse to F(X) function so that X=F 1(F(X). Conversion is partially carried out by the computer and therefore, is rather quick. This conversion method is especially helpful when large volumes of data are to be converted (kilobytes and megabytes) or when reversible conver sion may be needed for data (to present data in original form). To be able to use CodeInit, EnCode, and DeCode operations a special fast conversion algorithm (Fast type) should be defined in the dongle. You can create it on your own or use the one which is programmed in the dongle at the presales stage (algorithm #1). You can change the descriptor of the algorithm using NSKUTIL utility so that no one except you knows the representation of this algorithm. Conversion mechanism is as follows: First, the dongle converts your specified 32 byte password by CodeInit operation, which uses an algorithm of Fast type. Then this modified password is used to convert data with EnCode and DeCode operations. These operations are executed by the computer. EnCode operation is used for information encoding while DeCode is used to convert the en coded information into its original form. The reason for converting the password before it is used in EnCode and DeCode operations is to improve the level of protection of encoded data. In this case, data are converted not with the password itself but of its modification, which is not stored in the applications body. Therefore, the hacker will not be able to get it. In general, using CodeInit operation is not critical in this case. To convert the password you can use any of the algo rithms created in the dongle with 32 byte long query for Transform opera tion. By the way, pair algorithms, which are described, next can be used as an example of this method. Finally, you can refuse to convert the pass word before EnCode/DeCode operations at all, but this will weaken the security of the data. The only mandatory requirement is that the password must be 32 bytes long.
63
Users Manual
New Protection Technologies Provided by Hardware Algorithms It is most important to apply ones creativity when using hardware algo rithms. Actually, the information can be converted in a number of ways depending on the objective pursued. Protection reliability directly de pends on the inventiveness of implementation of hardware algorithms and ingenuity of use of the algorithm converted data. We are going to show you just a few examples so that you could under stand that there is a great variety of ways of applying hardware algorithms in practice. Converting Large Volumes of Information If the application contains many constants critical for its functioning or if it works with databases, it needs to have some place to store these con stants, names of fields and tables and any other information. This infor mation can be encoded by a special utility and then decoded by the pro tected application. This allows you to arrange for a reliable protection against intruders when the hacker himself does not have a legal copy (i.e., he has no dongle). If used in combination with other methods, this can make protection even stronger. Important
The described protection mechanism can be implemented only through fast conversion by CodeInit, EnCode and DeCode operations, since only this type of conversion is reversible.
Multiple Algorithms Up to 18 different algorithms can be specified in the Stealth dongle simul taneously. This means that one dongle can convert data using eighteen different methods. This allows large opportunities for creating various methods for protecting your applications. Let us describe some of them: a) For example, if an accounting application is protected, all tables (data bases) can be divided into groups, and these groups can be encoded by dif ferent algorithms. In fact, in 32 bit application this can be done simulta neously in different threads. This will make protection logic more intricate and harder for the hacker to analyze the protection method. To crack such protection one would have to spare 18 times as much effort or so. b) Each of the 18 algorithms can be programmed separately, which gives you an opportunity to combine protection methods. For example, you can specify 2 algorithms: random number generator and simple data con version (please be reminded that the information on any particular algo rithm representation is stored in its descriptor).
64
In this case, you can build protection as follows: 1. Generate a random number using the dongles algorithm and su perpose it bitwise with current time accurate to the second. 2. Select an element from the array of initial values (which is created in advance at the stage when protection is designed) using a ran dom number as the array index. 3. Convert the received number by the second algorithm. 4. Calculate the CRC of the received value using Guardant API func tion. 5. Select an element from the array of the reference values (the sec ond array which is created in advance at protection designing stage) using a random number (see Step 1) as the array index number. 6. If the results of Steps 4 and 5 match each other, the legality check will be deemed completed successfully. Changeable Data Conversion Method An algorithm can be created in the dongle with the following two features that would allow: to convert information a limited number of times; to establish dependence of the conversion method on the algorithms counter. Let us name this algorithm counter dependent conversion. This algorithm converts information a limited number of times. Besides, each conversion is unique since it depends on the decrementing value of the algorithms counter. Thus, one and the same number each time will be converted differently. This not only makes advancing of all algorithm responses impossible (because they are always unique), but can also be used to limit the number of times the application is run. For example, protection can be built as follows: 1. Convert some constant by this algorithm. 2. Calculate the CRC of the received value. 3. Find the identical value in the CRC table, which is created before hand (this table should be created at the stage when protection is designed and its size should not be less than the number of permit ted executions for the application).
65
Users Manual
Coupled Algorithms Method This method suggests that two algorithms of counter dependent conver sion type (see above) should be used, however with some individual fea tures. The counters of each of these algorithms should contain real big values (say, something around 1,000,000,000), but the counter of the first algorithm should exceed the value of the other algorithm by one. Besides, these algorithms should have identical determinants. Let us call the first algorithm a decoding algorithm and the second one an encoding algo rithm. Protection scheme can be built as follows.
Protection Designing Stage:

1. 2. 3. Take any optional 32 byte long sequence of data and save it (for example, in the dongles memory). Convert this sequence by the encoding algorithm. Encode data, which are used by the application, by EnCode opera tion. Use the sequence obtained at Step 2 as a password. Save the encoded data on the disk.
In the Protected Application:

Read the stored data sequence from the dongles memory. Convert this sequence using decoding algorithm. Read the data used by the application from the disk and decode them using DeCode operation. Use the sequence received at Step 2 as a password. 4. Use the decoded data in the application. 5. Read the stored data sequence from the dongles memory and con vert it by the encoding algorithm. 6. Encode application data by EnCode operation. Use the sequence received at Step 5 as a password. Save the encoded data on the disk. With this method encoding and decoding are carried out differently each time. As a result, constantly changing files are generated with data used by the application. However, in case any failure occurs and the information is destroyed, the protected application will be unable to run any further. Therefore, to reduce the risk of failure you should try to execute all these steps as fast as possible. 1. 2. 3.
66
Random Numbers and Distribution Function Analysis You can create a hardware algorithm that will return uniformly distributed pseudorandom numbers. The length of the random number can range be tween 4 and 200 bytes. Use of the random number generator together with the above methods allows you to create most powerful systems of protec tion against copying. By applying probabilistic principles, you can build reliable protection schemes. For example, an algorithm can be created which returns a ran dom sequence of 100 bytes. This sequence is split into 50 numbers 2 bytes each, then mathematical expectation and mean square deviation are cal culated, and then it is determined whether the probability function is uni formly distributed. If no, it means that the hacker is trying to emulate copyprotection because he has no ability to find that many correct ran dom sequences that are uniformly distributed. If the application calls the dongle periodically, these statistics can be accumulated and adjusted with each call, thus making statistics increasingly true. To be able to crack protection quite a bulky program module needs to be developed, and it is not even clear how to implement it in the protected application. Alternatively, the entire protection system can be analyzed which may require a lot of time in case statistics collection and analysis system is spread across the application.
67
Chapter 7. Working with Guardant Net in LAN
Chapter 7 Working with Guardant Net in LAN

This Chapter contains tips on how to work with Guardant Net protection in local networks. You will learn about local networks in which protected products can be run, how they interact with Guardant Net dongle and how the license licenses are allocated. You will learn to configure Guard ant Net servers and find out about the importance of network monitors. Finally, you will be advised on the issues of making network communica tion fault free. This information is not related to the protection issue di rectly. It is rather intended for network administrators. We recommend that you take the most important tips from below and include them into your software Manual. Important
Please pay special attention to the mechanism of allocating network licenses and to the tips on increasing the reliability of network communication.
Guardant Net Concept

Let us first investigate the basic principles of Guardant protection. This knowledge will help you understand why you should work with Guardant Net in the way prescribed in this chapter. What is Guardant Net? Guardant Net is a Guardant Stealth dongle specially adapted for local networks. It ensures not only protection but also licensing of network software*. The idea of licensing may be formulated as that of exercising control over the number of copies of network products that run simulta neously on a network. The objective of licensing is to prevent running of more copies than allowed. The network license limit (i.e., the maximum permitted number of workstations for the network product) is stored in the memory of Guardant Net in the field of counter #2. For full protection and licensing of your network product, one Guardant Net dongle is enough for the entire local network. It can be installed either on a workstation or on a server.
69
Users Manual
What is Guardant Net Server? Protected network products have no ability to communicate with the net work dongle directly. No network protocol can provide for it. A special utility called Guardant Net server provides a link between the client (i.e., protected application) and Guardant Net dongle. It is utility providing for transmission of queries from the client directly to the dongle and back wards in accordance with the network protocol. This brings about the main rule of loading Guardant Net server. Important
Guardant Net server must be loaded on the same workstation or server to which Guardant Net dongle is attached. Otherwise, the server (as well as the Guardant Net client) will be unable to detect the dongle and serve as a link between this dongle and the client.
How does Guardant Net Work? When started, Guardant Net server reads network license limits and other parameters of all dongles attached to the computer and stores them. To start working with the dongle the protected application should be logged in the server. Logging in is carried out by Login operation. During its exe cution, the server verifies if the dongle with required parameters is at tached to the computer, and decrements its license counter by 1. Other wise, it returns an error code to the client stating that The dongle is not found. After login is completed successfully, the application can execute any permitted operations with the dongle. When the application termi nates it logs out using Logout operation. During its execution, the license counter of the corresponding dongle is restored (the value is incremented by 1). Thus, correction of the license counter is essential for Guardant Net pro tection. If the client executes Login operation when the network counter of the dongle has already been exhausted (shows 0), the server will return a corresponding error message, and the application copy will not be started. This is how licensing of network software is implemented in Guardant Net protection. Important
Network license counters are corrected in the servers memory, but not the memory of Guardant Net dongles. This ensures the safety of the network license counter during hardware failures in the network, workstation hang-ups, etc.
70
How are Licenses Allocated? The important result of logging in Guardant Net server is the capture of one of the licenses. Theoretically, the licenses of the network dongle can be allocated between two objects: protected applications and workstations on which these ap plications run. On the face of it, allocation to applications seems more reasonable, since it is their running that causes the license counter to be decremented. However this way of allocating licenses has the following serious disadvantages. If network licenses were allocated to applications, then: in case an application hung up its network license would remain captured (as a matter of fact, the license would be lost) until Guardant Net server is reloaded; running of several copies of the same application on the same workstation would lead to overuse of licenses. By the way, this is quite a common situation. This may happen if a user (either accidentally or due to lack of experience) runs several application copies on his computer. That is why in Guardant Net protection the network licenses are allocated to workstations but not to protected applications. It means that: The network license is captured (license counter decremented by 1) only when the first copy of protected application is run. If new copies of the same application (or other applications bound to the same dongle) are run on this workstation, the network license counter will not decrement. The network license counter of the dongle recovers (i.e., is incremented by 1) only after the last copy of the protected application that has been started on this workstation terminates. In this case, it does not matter in which order the copies have been started. If the running protected application has hanged up, the license will remain captured by this workstation. You will still be able to run the application on this workstation, however this will not result in the license counter changing. If after capturing the license no application from this workstation communicates with Guardant Net server for 24 hours, then the license will be returned to the dongle after the timeout. Important
In Guardant 4.1 (released 07.06.02) and later versions the license control mechanism has been improved. In order to release the hung-up licenses the Guardant Net is regularly polled, at least every five minutes, by the Client (Win16, Win32). Communication with the application, which has not sent its data during the three intervals between the polls, terminates, if a new client lacks a license.
71
Users Manual
Guardant Net Features Guardant Net protection is very easy to use. All the end users will have to do is install the protected product, set up configuration files of the dongles client and server (GNCLIENT.INI and NNKSRV32.INI) and run Guardant Net application server; as soon as they are done with this they can proceed with their work straight away. Even if your customers have several different NetBIOS interfaces loaded on their workstations, this will not affect either the user of the protected application or the protection itself. The client will agree with Guardant Net server which NetBIOS interface should be used for communication. All this will be done automatically and require no additional settings of Guardant Net software. Guardant Net software provides for highly reliable network communication. If several NetBIOS interfaces are loaded on the workstation and one of them fails, Guardant Net will simply switch to another available NetBIOS interface (and in this case there is no need in reloading Guardant Net server). Guardant Net protection ensures reliable functioning on network bridges (i.e., computers with several network adapters). Guardant Net software will be automatically adjusted to the environments. Supports complex networks, composed of several segments. Guardant Net dongles support all protection capabilities provided by Guardant Stealth plus special capabilities such as protection and licensing of network software.
Supported Networks and Protocols

Guardant Net supports TCP/IP and NetBIOS network protocols (or their emulators). TCP/IP protocol can be used by Win16 and Win32 ap plications only, while NetBIOS can be used by DOS, Win16 and Win32 applications. At least one of these protocols should be configured in LAN, otherwise the dongles server will return an error: Protocol not found. In other words, there may be cases when the client (i.e. the protected application) and the Guardant Net server do not see each other, because neither NetBIOS nor TCP/IP protocol, which are present on the client com puter, has been loaded on the computer with the dongles server. Guardant Net network dongles can work in any local networks with Net BIOS and TCP/IP interfaces. However, one should note that Guardant Net server is a Win32 application, so it must be loaded on the server or workstation that is running under Windows.
72
Supporting Several Adapters and Network Interfaces Latest operating systems are capable of supporting several protocols si multaneously, for each of the network adapters installed on the computer. Each network interface adapter pair is supplied with a unique number and is called LANA (LAN Adapter). All Guardant Net network software products are designed with the capability to concurrently work with sev eral network interfaces and network adapters. Specifics of Using the NetBIOS Protocol Working in Complex Networks By default, the Client can see Guardant Net Server only if it is located within the same network segment. However, sometimes it may be needed to run the protected application in a complex network composed of sev eral segments. Here are some ideas: 1. If network configuration permits, Guardant Net Server can be loaded on a computer that can be accessed from several network segments at a time (for example, on Windows NT Server con nected to several network segments simultaneously). 2. Permission of packet exchange between the segments. This requires installation or reconfiguration of the router and/or the switch. This can be done, for example, for one of the NetBIOS interfaces avail able. 3. Installation of one Guardant Net Server in each segment. 4. Use of Guardant Stealth (i.e., local dongles) on some of the workstations that belong to other segments. Compatibility with Network Interfaces in Various Operating Systems The most widespread versions of NetBIOS interfaces are the following: Microsoft NetBEUI. Non routed protocol offered by Microsoft for smaller networks. In Windows 95 it is installed by default. Microsoft NetBIOS over TCP/IP. In Windows 95/98/Me it is installed by default during the installation of TCP/IP. Routing is possible. Microsoft NetBIOS emulator over IPX. It is most often used in mixed networks to link applications, which run under MS Windows and NOVELL NetWare. Routing is possible. NOVELL NetBIOS emulator over IPX. It is most often used in mixed networks to link applications, which run under NOVELL NetWare and MS Windows. Routing is possible. IBM NetBIOS in OS/2. Basic protocol for OS/2. LANtastic NetBIOS. Basic protocol for ARTISOFT LANtastic.
73
Users Manual
By now the following have been tested:

MS LAN Manager MS Windows 3.11 MS Windows 95 MS Windows 95 OSR2 MS Windows 98 MS Windows 2000 MS Windows XP MS Windows NT 3.5x MS Windows NT 4.00 IBM OS/2 4.00 NOVELL NetWare 3.1x NOVELL NetWare 4.1x ARTISOFT LANtastic NetBEUI + + + + + + + + + N/A N/A N/A N/A NB on IPX N/A + + + + + + + + N/A + + N/A NB on TCP/IP N/A + + + + + + + + N/A N/A N/A N/A NetBIOS N/A N/A N/A N/A N/A N/A N/A N/A N/A ? N/A N/A ?
+ protocol has been tested. ? protocol has not been tested yet. N/A NetBIOS interface is not available in this particular operating sys tem. It should be kept in mind that NetBIOS interfaces are not generally com patible with each other. It means, for example, that packets exchange be tween NetBEUI and IPX based NetBIOS emulator is impossible. The only exceptions are IPX based NetBIOS emulators from Microsoft and NOVELL, which are highly compatible. Network Throughput As it has been mentioned above, operating systems, such as Windows 95/98/Me/NT/2000/XP are capable of supporting several protocols si multaneously for each of the network adapters installed on the computer. This is a very useful capability, yet an inefficient configuration can consid erably reduce the network throughput. In our case, to minimize Guardant Net Server response time during Login operation (logging the protected application in Guardant Net Server) it is a good idea to use one of the NetBIOS interfaces already in stalled on the computer running Guardant Net Server, as a default proto col for each of the Client workstations. Otherwise, the Client will attempt to establish a link with the Server by trying all available NetBIOS inter faces one after another until it finds the required one.
74
Configuring the Guardant Net Server and Client

General Information To run the protected application in local network it is enough to install one Guardant Net dongle on any workstation or server. Operations with Guardant Net dongle via the network are supported by the Client (Guardant Net API and/or automatic protection vaccine) and the Server (Guardant Net server) components of Guardant Net software. To link the Client with the Server of Guardant Net software you must set up the Clients (GNCLIENT.INI) and the Servers (NNKSRV32.INI) configuration files; depending on the current protocols you must specify the Servers NetBIOS name, its IP (or host name), set timeouts for send ing and receiving of data, etc. Guardant Net Client software does not require Guardant drivers to be in stalled since it does not communicate directly with the dongle. Instruc tions for installation of Guardant drivers required for Guardant Net Server functioning are the same as for the local usage of Guardant Stealth (see Guardant Drivers). Configuring Guardant Net Server Configurable parameters of Guardant Net servers are accumulated in NNKSRV32.INI file, which must be located in the same directory as the corresponding server. If this file is not found all parameters of the server will be assigned default values. Configurable parameters of the server are grouped into the [NCBs], [CACHE], [TIMEOUT], [SYSTEM], [SERVICE], [PROTOCOLS] and [SERVER] sections. [NCBs] Section [NCBs] section accumulates parameters, which allow you to configure the server to work with greater or smaller number of clients. By default, Guardant Net server has configuration that is enough to serve about 10 clients at a time, no additional configuration is required for this. Intervention may be needed when the peak value of NCB parameter dis played in the status window of Guardant Net server is getting close to its maximum, or when corresponding messages are displayed by the server.
TotalNCB=xx
This parameter specifies the maximum number of NCBs that Guardant Net server can create when working with clients (or, in other words, it is the maximum number of network packets which the server can re ceive/transmit). A server can spend up to 2 NCBs per client at a time, therefore TotalNCB value indirectly reflects the maximum number of cli ents the server can theoretically poll simultaneously. Valid values of the parameter range between 1 and 256, the default value is 50.
75
Users Manual
NCBInLANA=xx
When using NetBIOS protocol LANA parameter is very important. The number of LANAs on a workstation depends on the number of NetBIOS interfaces installed on this workstation, as well as the number of installed network adapters (in fact, the number of LANAs on a workstation is to be equal to the result of multiplying these two values). After being loaded, the server waits for queries from new clients via all available LANAs, yet ac tual communication with each client is carried out via one LANA only. NCBInLANA parameter specifies the number of NCBs that are allocated by the server for waiting a query from a new client on each LANA. To put it otherwise this parameter shows how many new clients can theoretically be logged in by the server on each LANA at the same time. Allowed values of the parameter range between 1 and 9, the default is 3. For proper functioning of the server, the value of TotalNCB parameter should exceed by two the value of NCBInLANA parameter multiplied by the number of LANAs used on a particular workstation. Thus, the follow ing condition is to be met:
TotalNCB > NCBInLANA*LANAs + 2
[CACHE] Section [CACHE] section accumulates parameters, which specify the configura tion of Guardant Net servers cache. The cache is used to reduce the re sponse time of Guardant Net server during execution of the most frequent operation, i.e., reading from the dongles memory. The cache is most ef fective for a Guardant Net server interfacing with a big number of clients, and it dramatically increases the stability of the server during peak over loads.
CacheMode=On|Off
This parameter allows you either to enable (On) or disable (Off) the cache of Guardant Net server. If the cache is off, other parameters of [CACHE] section are ignored. By default, the cache is enabled (On).
CacheCnt=xx
This parameter specifies the maximum number of reads during which the information can be taken from the servers cache but not from the dongle. Allowed values of the parameter range between 1 and 16, the default value is 10. As soon as the counter reaches the specified value, the next read op eration is done directly from the dongle, while the cache contents will be updated. The cache contents are also updated during each write into the dongles memory.
76
CacheTime=xx
This parameter specifies the interval in seconds during which the read op erations will be executed from Guardant Net servers cache, when possi ble. Allowed values of the parameter range between 1 and 60, the default value is 30. Upon the expiry of this interval, the next reading will be done from the dongle, while the cache contents will be updated. Thus actual reading from the dongles memory will be executed in case ei ther of the conditions specified by the above two parameters are met: ei ther the number of reads from the cache reaches its maximum value or the specified time interval expires. This scheme has been implemented in or der to prevent any attempts to activate the server without the dongle. [TIMEOUT] Section [TIMEOUT] section contains parameters that set the duration of timeout for dongls locking, as well as timeouts for sending and receiving of data (in seconds):
LockTimeout=xx
You can lock and unlock a dongle using LockBeg and LockEnd opera tions. If, for some reason, the dongle remains locked for a long time, it will be automatically unlocked after the timeout period expires. Timeout values can be specified in the range between 1 and 600, the default is 60.
TO_SEND=xx
Timeout for sending of data by the client to the dongle server. Timeout duration can range between 1 and 120 seconds, the default duration is 10 seconds.
TO_RECEIVE=xx
Timeout for receiving of clients data by the dongles server. Timeout du ration can range between 1 and 120 seconds, the default duration is 10 seconds. If the line is slow or the server is overloaded, it is recommended that you set higher values for TO_SEND and TO_RECEIVE parameters, in order to prevent the cut off of the client upon the expiry of the timeout. [SYSTEM] Section [SYSTEM] section contains parameters, which specify the behavior of the server as Windows application.
StartMinimized=On|Off
Enabling of this parameter (On) allows Guardant Net server to be loaded with the main window minimized. By default, this parameter is disabled (Off).
77
Users Manual
MoveToTSA=On|Off
Enabling of this parameter (On) allows the server to place its icon to TSA (Taskbar Status Area) during loading. When the window is minimized, the server removes its icon from the main Taskbar. You can invoke the main window of the server by double clicking on its icon in TSA. This pa rameter can be used in 32 bit server only. By default, this parameter is en abled (On).
QuietExit=On|Off
This parameter allows you to activate (On) or deactivate (Off) the mode of shutting down the server without confirmation. If the parameter is acti vated (On) and none of network licenses of any dongle appears captured at the moment of exit, the server terminates its running without confirma tion. Otherwise, the server displays a corresponding warning message, and termination of the application should be confirmed by the user. [SERVICE] Section [SERVICE] section accumulates parameters that specify the features of running 32 bit Guardant Net server as Windows NT/2000/XP Service.
ServiceMode=On|Off
Enabling (On) of this parameter gives an opportunity to run Guardant Net server as Windows NT/2000/XP Service. In case the parameter is disabled, the remaining parameters of this section are ignored. The default value is Off.
ServiceInstTimeout=xx
When Guardant Net server is loaded, it polls all network dongles attached to the computer. Since the Service is started during the loading of the OS, this process may coincide in time with Guardant drivers initialisation process. If, during starting of the Service Guardant drivers are not yet loaded, then the dongles will be unavailable, and the Service will fail to start. ServiceInstTimeout parameter specifies the time in seconds during which Guardant Net Service will be waiting for Guardant drivers to be loaded. Timeout values range between 1 and 600 seconds, the default value is 100.
78
[PROTOCOLS] Section The [Protocols] Section contains parameters that define current network protocols and their priority
TCP_IP=x NETBIOS=x
Possible values for the parameter: 0 protocol is not used 1 protocol is used as the primary protocol 2 protocol is used as the secondary protocol DOS applications cannot use TCP/IP protocol. All they need from the NNKSRV32.INI file is only the information about NetBIOS: server name (NB_NAME) and timeouts (TO_SEND, TO_RECEIVE). If the .INI file is not found, all parameters of the server will be assigned default values. [SERVER] Section The Server Section contains parameters that are used to specify NETBIOS name of the server and the TCP/IP address of the port. When license management system is being used, the dongle description counter is also stored in this section.
NB_NAME=NVSK_SRVR
NVSK_SRVR is a default server name
TCP_PORT=3182
3182 is a default number of TCP/IP port.
Dongles=x
x is the number of dongle descriptions [KEY_xx] Section When license management system is enabled, the sections of [KEY_xx] type, where xx is a section number, are added to the server configuration file by means of NSKUTIL program (or manually in any text editor). These sections contain descriptions (such as license table data and dongle search parameters) of dongles that can be used for any applications. Dongle search parameters are arranged in the window according to their priority, in the descending order. Thus, the dongle ID has the highest pri ority while the bit mask, the lowest priority. The value of the higher priority parameter is higher than the aggregate value of all lower priority parameters.
79
Users Manual
When the Guardant Net server is launched, it reads information from the attached dongles and selects out of descriptions contained in the INI file the one which fits each dongle most of all. The most fitting description is the one in which the aggregate priority of the search parameters, which fit a particular dongle, is higher that the aggregate priority of all other de scriptions. If there are several descriptions sections in the INI file with the same aggregate priorities, then the first description section will be used.
Public Code=xx
Public code of a dongle.
ID=xx
ID number of a dongle. This parameter is assigned the highest priority. If the ID of a dongle is specified, the description will be allocated to this par ticular dongle only.
VendorName=xx
Name of the vendor. Data from the license table.
ProgramName=xx
Name of the protected software package. Data from the license table.
ProgramNumber=xx
Program number. An additional parameter for the search of a fitting de scription for the dongle.
Version=xx
Version. An additional parameter for the search of a fitting description for the dongle.
Mask=xx
A bit mask. An additional parameter for the search of a fitting description for the dongle.
SerialNumber=xx
A serial number. An additional parameter for the search of a fitting de scription for the dongle.
Module0=xx
Name of the first module of the software package. Data from the license table.
ModuleN=xx
Name of the n module of the software package. Data from the license table.
80
Example: You are required to specify text descriptions for the vendors multi module applications. The vendor releases Version 1 of the application (OLD_ PROGRAM) under its original name (OLD_NAME). While the two new applications Version 2 are released under the new name (NEW_NAME) such as NEW_PROGRAM A and NEW_PROGRAM B. Below is a fragment of the configuration file, beginning from the [SERVER] section.
[SERVER] ; Default NETBIOS-name of the dongle server NB_NAME=NVSK_SRVR ; Default TCP/IP port TCP_PORT=3182 ; A number of sections with descriptions of dongles Dongles=3 [KEY_00] ; Public code of the vendor PublicCode=PBLCODE ; Previous name of the vendor VendorName=OLD_NAME ; Name of the old program ProgramName=OLD_PROGRAM ; Program version Version=1 ; Name of modules of the old program Module0=OLD_MODULE 1 Module1=OLD_MODULE 2 ModuleN=OLD_MODULE N [KEY_01] ; Public code of the vendor PublicCode=PBLCODE ; Program number of the NEW_PROGRAM A program ProgramNumber=0 ; Program version Version=2 ; New name of the vendor VendorName=NEW_NAME ; Program name ProgramName=NEW_PROGRAM A ; Program modules name
81
Users Manual Module0=MODULE_A 1 Module1=MODULE_A 2 ModuleN=MODULE_A N [KEY_02] ; Public code of the vendor PublicCode=PBLCODE ; Program number of the NEW_PROGRAM B program ProgramNumber=1 ; Program version Version=2 ; New name of the vendor VendorName=NEW_NAME ; Program name ProgramName=NEW_PROGRAM B ; Program modules name Module0=MODULE_B 1 Module1=MODULE_B 2 ModuleN=MODULE_B N
Configuring Guardant Net Client Configurable parameters of Guardant Net client are accumulated in [PROTOCOLS], [TIMEOUT] and [SERVER] sections of GNCLIENT.INI file. This file should be located in the same directory as the copy of the protected application. Configuration file for the JAVA network client can also be stored in the Windows root directory (for ex ample C:\WINDOWS). If the GNCLIENT.INI file is not available, all parameters of the Guard ant Net server are assigned default values. In this case, the client will search for a server with the default name (NVSK_SRVR) and only via NETBIOS protocol. [PROTOCOLS] Section The [Protocols] Section contains parameters that define current network protocols and their priority
TCP_IP=x NETBIOS=x
Possible values of the parameter: 0 protocol is not used 1 protocol is used as the primary protocol 2 protocol is used as the secondary protocol
82
DOS applications cannot use TCP/IP protocol. All they need from the NNKSRV32.INI file is only the information about NetBIOS: server name (NB_NAME) and timeouts (TO_SEND, TO_RECEIVE). [TIMEOUT] Section [TIMEOUT] section contains parameters that set the duration for the sending and receiving of data (in seconds):
TO_SEND=xx
Timeout for the sending of data by the client to the dongle server. Time out duration can range between 1 and 120 seconds, the default duration is 10 seconds.
TO_RECEIVE=xx
Timeout for the receiving of clients data by the dongles server. Timeout duration can range between 1 and 120 seconds, the default duration is 10 seconds. If the line is slow or the server is overloaded, you should set higher values for TO_SEND and TO_RECEIVE parameters, in order to prevent the cut off of the client upon the expiry of the timeout. [SERVER] Section The Server Section contains parameters which are used to specify NETBIOS name of the server and TCP/IP address of the port.
TCP_PORT=3182
3182 default address of the TCP/IP port.
IP_NAME=127.0.0.1
If the network uses dynamic IP addresses (DHCP server), you should specify the host name of the computer in which the dongles server is in stalled, instead of the IP address. 127.0.0.1 is the default IP address of the dongle server.
NB_NAME =NVSK_SRVR
NVSK_SRVR is the default name of the dongle server.
83
Users Manual
Guardant Net Server

Guardant software includes a 32 bit Guardant Net server (NNKSRV32.EXE utility). Guardant Net server enables communication between the protected network application and Guardant Net dongle in LANs where TCP/IP and NetBIOS protocol are supported. One server is capable of servicing queries addressed to several Guardant Net dongles. Loading the Server Guardant Net server should be loaded on the same computer to which the dongle is attached. Within the LAN several Guardant Net servers can be run. They must be run on different computers and have unique names. You cannot run two servers (server and service, two services) on the same workstation. Important
For running of 32-bit Guardant Net server (NNKSRV32.EXE) the presence of external vaccine file NOVEX32.DLL is required.
Guardant Net server can run not only as an ordinary window application, but also as Windows NT/2000/XP service. After loading is completed, the main window of Guardant Net server will be displayed. Monitor Function Guardant Net Server combines the functions of both a server and a moni tor. The server window is split into two parts.
Figure 2. Guardant Net Server main window. The upper part of the window displays, in a tree like structure, informa tion about the computer on which a dongle/dongles and a server are in stalled, as well as basic data about clients.
84
At the bottom of the tree the details about the computer on which the Guardant Net server is run are displayed, such as the computer name (host name), IP address, NetBIOS name. The first nesting level contains the Public code of the dongle. The second nesting level displays information about the dongle, particu larly the name of the application protected by the dongle, the license counter (current/maximum), dongles ID, application number, serial number, program version, value of counter 1. The third nesting level displays basic information about the client, such as network protocol, name and IP address of the computer on which the cli ent is run. If the license management system is enabled, the license table icon is displayed on this level as well. The level below the license table contains information about protected application modules, particularly the module name and the number (cur rent/maximum) of licenses in the module. The next level contains basic information about the clients that use re sources of any application module: network protocol, name and IP address of the computer on which the client runs. Important
The status of a dongle registered on the server is indicated by means of special marks next to the dongle icon: - lock means that the dongle is locked by the LockBeg operation (one of the application copies executes several read/write operations one after another). - x means that the dongle is not available (disconnected). Absence of marks means that the dongle is available (i.e. physically connected to the computer port) and is not locked.
At the bottom of the server window you can find a table with a detailed in formation about the clients: Login time Time elapsed since the last communication with the client Public code and ID of the dongle, which serves the client Program vendor Program name and number Module name and number (if the license table is used) Network protocol used for the connection Name and IP address of the computer on which the client is run Platform for which the application has been designed Data about clients can be sorted by any parameter, in ascending or de scending order.
85
Users Manual
If a query is not received from the client within 15 minutes (i.e. the client hangs up), the client is highlighted in grey but is not removed from the cli ents list. Connection with the hung up client terminates only when a new user needs this particular license. The server status line displays statistics about its functioning: Utilization of server resources current, peak and maximum number of NCBs used by the server during the sessions of communication with clients. Clients current and peak number of clients currently served by the server. Sessions current and peak number of sessions opened by the clients (communication sessions). Cache the state of server cache. Important
Peak value means the maximum value of the parameter actually achieved at some point of time.
Registration of a New Dongle A new dongle can be added to the dongles already registered on the server. However, mere attachment of the dongle to the computer is not enough; the dongle needs also to be registered. To register a new dongle, System|Refresh menu command can be used. The dongle is deemed registered successfully if the information about this dongle has appeared in the list of dongles of this server. From this moment onwards pro grams bound to this dongle can be run. If you disconnect the registered dongle from the workstation and then re read the dongles using System|Refresh menu command, the dongle will be marked with an x symbol, which means that the dongle is regis tered but is physically not attached (i.e., the dongle is unavailable). From this moment onwards running of any programs bound to this dongle will become impossible. To restore the dongle registration follow the above described steps. If reg istration is completed successfully, the x symbol will disappear. Important
You cannot cancel the registration of the dongle, which has already been registered.
License Management System Guardant software versions 4.5 and up allow Guardant Net server to manage licenses in multi module software packages, separately in each module. A two level license control scheme is used in the Guardant Net server: 1. The total number of workstations, on which the protected applica tions are run, is limited to the actual license limit available in a don gle (value of counter #2)
86
The number of workstations on which a certain module of the pro gram is used, is limited to a resource of this module (value of the ap propriate byte in the license table) An actual license limit should not necessarily be equal to the total number of licenses in all modules. Example: The protected program package consists of four modules: Accounting, Wages, Personnel, Office. The actual license limit in a dongle is 15. The number of licenses in each module is indicated in the table:
Module
Accounting Wages Personnel Office
2.
Number of licenses
10 10 7 5
Thus, different modules can be run on 15 workstations simultaneously, but the number of computers, on which any of these module runs, cannot exceeded the license limit of this module (i.e. not more than 10 Account ing licenses, 7 Personnel licenses, 5 Office licenses, etc.) If several modules, for example Accounting, Wages and Personnel mod ules, are run on the same computer, the actual license counter in the don gle is decremented by 1; likewise the number of license counters in each of these modules will be decremented by 1 too. To be able to utilize the license management system you should do the following: create the License table field in the dongles memory and define the number of modules, license limits, as well as additional parameters in this table enable /MN=xx option during the automatic protection, where xx is the number of the module in the license table (use Enable the license management system parameter of the autoprotection wizard) when working with an API based protection you should use nnkLoginLMS function, instead of nnkLogin, to register the application on the server. Important
When you are updating the entire memory of a dongle using the Guardant API, you should apply nnkProtectLMS function, instead of nnkProtect.
License table format

The address of the license table is identified in the dongle memory by the value indicated in kmTableLMS field (29 SAM). The size of the table heading is two bytes.
87
Users Manual
The first byte contains the information on the size of a cell (1 byte if the high bit is 0, and 2 bytes if the high bit is 1) and on the number of modules in the license table. The maximum license limit in a module depends on the size of a cell. If the size of a cell is 1 byte, the number of licenses in each module can be limited to a maximum of 254; if the size of a cell is 2 bytes, the number of licenses in a module can be limited to a maximum of 65534. Example: 00000011 a high bit of the first byte of the table is set to 0, so the size of each cell is one byte and the number of modules in the table is three. 10000010 a high bit of the first byte of the table is set to 1, so the size of a cell is two bytes and the number of modules in the table is two. The second byte of the table is reserved. The cells of the table go below the heading. 1) General structure of the license table with single byte cells
Offset 0 1 2 3 4 5 ... Description Number of modules in the table Reserved Number of licenses for the 1st module Number of licenses for the 2nd module Number of licenses for the 3rd module Number of licenses for the 4th module .................................................... An extra byte for word-alignment (ONLY if the number of modules is odd)
2) General structure of the license table with the two byte cells
Offset 0 1 2 3 4 5 6 7 8 9 ... Description Number of modules in the table Reserved Number of licenses for the 1st module (low byte) Number of licenses for the 1st module (high byte) Number of licenses for the 2nd module (low byte) Number of licenses for the 2nd module (high byte) Number of licenses for the 3rd module (low byte) Number of licenses for the 3rd module (high byte) Number of licenses for the 4th module (low byte) Number of licenses for the 4th module (high byte) ....................................................
88
Running the Server As Windows NT/2000/XP Service Guardant Net server can run not only as an ordinary window application, but also as Windows NT/2000/XP Service. The advantages of this Service is that it is started by the operating system when the latter is loaded, and to start the Service no logging in computer is required, while the user gets access to Windows special Service control facilities. Starting Guardant Net Service To permit the running of Guardant Net server as a Service you should specify On value in ServiceMode parameter of NNKSRV32.INI file (for more details on configuring the server see below). After that you will be able to run the server both as an ordinary application and a Service. Otherwise, NNKSRV32.EXE utility can be run only as an ordinary win dow application. To launch a Service you should run Guardant Net server with /I option: nnksrv32.exe /I This operation needs to be executed only once. As soon as Guardant Net server is successfully launched, the protected applications will get access to Guardant Net dongles. The Service will be launched automatically each time when Windows NT/2000/XP is started. Important
Guardant Net Service can run only in Windows NT/2000/XP.
Working with Guardant Net Service Guardant Net Service cannot be launched if ServiceMode=On parameter is not specified in NNKSRV32.INI file. Guardant Net Service has no interface window. You should control network licenses allocation and the status of Guardant Net dongles with the help of Guardant Net network monitors. You can temporarily suspend Guardant Net Service. To do this, you should select Control Panel|Services (for Windows NT) or Control Panel|Administrative Tools|Services (for Windows 2000/XP) and right click on Guardant Net Service item. In the popped out menu you should choose Stop item. The Service will remain installed in the system, but will no longer process queries sent to Guardant Net dongles. To resume the running you should start the Service from Control Panel or use NNKSRV32.EXE /I command.
89
Users Manual
Specifying of Off value in ServiceMode parameter does not lead to automatic removal of Guardant Net Service from the system. Meanwhile it will become impossible to start the Service during loading of Windows. To prevent this, you should change ServiceMode value and start the Service from the Control Panel or by NNKSRV32.EXE /I command, or delete it from the system as described below. If no Guardant Net dongle is attached to the computer, you will not be able to launch the Service when loading Windows. To resume its running you should attach the dongle and start the Service from Control Panel (see above) or by NNKSRV32.EXE /I command.
Removing Guardant Net Service From the System To disable Guardant Net Service you should run NNKSRV32.EXE with /R option:
nnksrv32.exe /R
Guardant Net Network Monitors

The purpose of network monitors is to receive information about Guard ant Net dongles via network. They can be started from any workstation, and the same rules apply to them as to Guardant Net clients. There are three network monitors, which are identical in functions:
NNKMON.EXE NNKMONW.EXE NNKMON32.EXE DOS application; 16-bit Windows application; 32-bit Windows application.
When any of these utilities is started, it will connect to Guardant Net server and display the information received from the server about current parameters and the status of all Guardant Net dongles registered on the server (this information is identical to the information displayed by the server in its window). This will allow the network administrator to receive information about the status of Guardant Net server and about the alloca tion of license resources to Guardant Net dongles at any time and from any workstation.
How to Increase Reliability of Network Communication

Improving Protection Strength against Attacks End users may try to run more copies of the protected application in the network than permitted. After running a maximally permitted number of copies, they may force reloading of Guardant Net server and get an op portunity to run just as many application copies again.
90
It is quite easy to protect against this. Both Guardant Net server and Guardant Net client have reliable built in facilities to obstruct such at tempts on the part of the user. Your task is to activate these facilities. The protected network application should periodically verify the dongles presence. Use timer based dongle verification option during the auto matic protection of the application and/or periodically poll the dongle with the API functions from different locations of the application. The thing is that after being reloaded Guardant Net server will not process queries of those applications started before reloading. Thus, the first poll ing of the dongle carried out by an old application copy after the server has been reloaded will return the following error: nse_ServerReloaded. In some time, all copies of the application started before the reloading of the server will stop running. Increasing Performance of Guardant Net Server 1. It is not recommended that you call the dongle too often. The point is that the minimum response time of Guardant Net is about 150 200 milliseconds. Thus, the server can exchange with Guardant Net no more than 5 to 6 times per second. Moreover, during the execution of Transform operation the time of exchange may even increase several times (Transform operation is quite slow). There fore, for example, five applications, each calling the dongle once in a second, can easily overload Guardant Net server, because in this case little will depend on its speed. The server will start freezing for a long time and lose network packets. Therefore, you should remember that the optimal interval between the polls should be random and range between 5 and 30 minutes. It is not recom mended that you carry out many tests at one time, because in this case the possibility of peak overloads increases dramatically. If you follow these recommendations, the server will be able to poll up to 100 protected applications, which are running simultaneously. This number seems big enough, however it should be kept in mind that there has to be only one server in the network and that several don gles can be registered on it (each with its own network license limit). Network administrators should be warned against the risk of overloading the server. 2. Usage of cache enables to considerably increase Guardant Net servers speed. Accordingly, the server will be capable of working with more clients (protected applications) at a time. However, if the above recommendations are not followed, even cache will not help to prevent overloading of the server.
91
Users Manual
3.
4.
5.
It is not recommended that you enable the automatic start function for the protected network application, because in this case the risk of overloading is also very strong. For example, imagine how a new day begins in a big bank, where hundred of terminals are turned on at once, and all of them start to send their queries to the dongle al most simultaneously. To avoid overloading it is not recommended that complicated checks on the dongle be carried out (especially, where several Transform operations are used one after another) when loading the protected application. A simple check of the dongles presence would be enough, while more complicated tests should be better postponed until a later stage, making them incidental and timed to certain events. This will make the hackers life more difficult. Do not assign too high values to configurable parameters in INI file of Guardant Net server. This will not lead to the effect you expect (increase of performance, stable functioning during peak loads, etc.). Instead, the server will start to consume system resources (RAM and CPU usage) excessively. The default values of parame ters appear to be optimal for the networks with little and medium number of workstations; there is sense in increasing them only when serious matters arise (for example, when the server has to work in large scale networks with many dongles) and this should also go along with corresponding changes in the NetBIOS protocol configuration. By the way, if there is a shortage of resources speci fied by the configurable parameters, the server will inform of this by displaying a corresponding message on the screen.
How to Avoid Problems of Sharing Data in the Network 1. When polling the dongle try not only binding it to its Private codes, but also do carry out a deeper check, involving general purpose fields (serial number, version, etc.). This will guarantee that the protected application will only use the network licenses of the don gle to which it is bound. It is of importance when several dongles with your Private codes are registered on one server. 2. When hardware algorithms are used which depend on the decre menting value of their executions counter (with the set nsaf_GP and nsaf_GP_dec flags of the hardware algorithm), there is a risk of this protected application copy receiving wrong responses from such algorithm, because only one counter is used in it for all copies of the protected application. Therefore, to avoid possible conflicts do not use algorithms with this set of properties to protect the net work applications.
92
Chapter 8. Guardant API
Chapter 8 Guardant API

From this Chapter onwards study of Guardant protection facilities begins as such. This Chapter addresses the principal method of protection pro tection with API functions. You will learn which operations are supported by Guardant dongles, and will get comprehensive advice about API func tions that these operations are executed with. Important
Please pay special attention to Transform and EnCode/DeCode operations and, particularly, to the way they are executed and to the difference between them.
Operations
As you already know Guardant API functions allow various actions to be performed with the dongle, including but not limited to writing to the memory, implementing hardware locks, running hardware algorithms, etc. These actions are called operations*. To execute an operation a corresponding API function has to be called. When calling most of API functions Private access codes are used as mandatory parameters. Operations with Guardant Stealth, Guardant Fidus and Guardant Net dongles can be divided into 2 main groups: built in* operations and ser vice* operations. Built in Operations The main distinctive feature of built in operations is that all of them are executed by the dongle. Built in operations are further subdivided into primary and secondary. Primary built in operations allow you to execute most important opera tions with the dongle, particularly: Search for the dongle that matches specified search conditions Initialize the dongles memory Read from the dongles memory Write data to the dongles memory Implement or release memory read/write locks Convert information using the dongles hardware algorithms.
93
Users Manual
The following operations are included in this group:

Operation Name Check Access Code Private Read Brief Description Searches for the dongle. Can be used for a simple check of the availability of the dongle. Search condition can be specified. Obtains a result of Y=F(X) one-way conversion. Reads a block of bytes in UAM. Writes a block of bytes in UAM Reads a block of bytes in SAM Writes a block of bytes in SAM Searches for all dongles. Can be used to review all Guardant Stealth dongles attached to the computer. Removes read/write locks, number of hardware algorithms and all data from user fields. Execution takes about 1 second. Implements read/write locks and assigns a number of hardware algorithms. Implements read/write locks and assigns a number of hardware algorithms when using license management system.
Transform ReadBytesUAM WriteBytesUAM ReadBytesSAM WriteBytesSAM ChkNSK
Private Read Private Read Private Write Private Read Private Write Not required
Init
Private Master
Protect ProtectLMS
Private Master Private Master
Secondary built in operations are used by a number of primary built in operations for their own purposes. All capabilities of secondary built in operations are available through primary built in operations. This group includes the following operations:
Operation Name ReadUAM WriteUAM ReadSAM WriteSAM Access Code Private Read Private Write Private Read Private Write Brief Description Reads a word block in UAM Writes a word block in UAM Reads a word block in SAM Writes a word block in SAM
Hence, with built in operations you can gain access to the dongles mem ory and convert data using hardware algorithms. Service Operations To convert large volumes of information and execute some auxiliary op erations a special software module, i.e., a group of operations called ser vice operations, has been designed. Unlike built in operations, they are partially executed by the dongle and partially by the computer. This group includes the following operations:
94
Operation Name SetMode FindFirst
Access Code Brief Description Not required Public Sets flags and other parameters for future queries to dongles Searches for the dongle. Used for searching the first dongle with the specified Public Code. Search conditions can be specified. Searches for the dongle. Used for searching the next dongle with the specified Public Code. Search conditions can be specified. Initializes password for EnCode/DeCode operations Performs fast reversible encoding Performs fast reversible decoding Gets a 4-byte random number using hardware algorithm # 2 (Random) Calculates CRC8, CRC16 or CRC32 Logs in to Guardant Net server Logs in to Guardant Net server Logs out from Guardant Net server Locks Guardant Net Unlocks Guardant Net
FindNext
Public
CodeInit EnCode DeCode GetRandom4 CRC Login LoginLMS Logout LockBeg LockEnd
Private Read Not required Not required Private Read Not required Private Read Private Read Private Read Private Read Private Read
As you may see, service operations allow you to execute some very useful actions such as generate random numbers and calculate the CRC (cyclic redundancy check) of data array (CRC is generally used as checksum when verifying the authenticity of these data).
Methods of Executing Operations

Guardant Stealth, Guardant Fidus Operations with Guardant Stealth and Guardant Fidus are executed by calling respective API functions. There are two methods of querying the dongle: 1. Calling the functions of nskXXXX() type: (nskSetMode, nskCheck, nskTransform, nskRead, nskWrite and other). 2. Calling NSKCOMMAND() function. In the first method, each operation has its corresponding function with nsk prefix. For example, Check operation has a corresponding nskCheck function, Transform operation nskTransform function, etc. This method is a lot easier and more convenient of the two. This method is used in examples, which you will find in API\STEALTH\ directory. The second method is more bulky and can be used only in such program ming languages as C, Pascal, etc., because in and out parameters are united into structure. In this method, executable operations are specified by commands with nsc_ prefix. For example, Check operation has a corresponding nsc_Check command, Transform operation nsc_Transform command, etc. This method is rather bulky and we rec ommend that you use it in emergency only.
95
Users Manual
Guardant Net Operations with Guardant Net are executed in LAN by calling functions of nnkXXXX() type: (nnkSetMode, nnkLogin, nnkLogout, nnkLockBeg, nnkLockEnd, nnkCheck, nnkTransform, nnkRead, nnkWrite, nnkInit, nnkCodeInit, nnkEnCode, nnkDeCode and other). If you plan to use Guardant Net dongles as local dongles (for example, to run the application when local network is unavailable), you can use all Guardant Stealth API functions. In this case, Guardant Net should be at tached to the computer on which the protected application is run.
Where are API Files Located?

Dongle Type Guardant Stealth, Guardant Fidus Guardant Net Directory Containing API API\STEALTH\ API\NET\
Guardant API Error Codes

Guardant Stealth, Guardant Fidus and Guardant Net API functions may return the following error codes:
Error Name nse_Ok nse_KeyNotFound nse_AddressTooBig nse_GPis0 nse_BadCommand nse_VerifyError nse_LANProtNotFound nse_LANResourceExhaust nse_ConnectionLost nse_LANplugsNotFound nse_LANserverMemory nse_LANDPMIError nse_Internal nse_ServerReloaded nse_VersionTooOld nse_BadDriver nse_LANNetBIOS nse_LANpacket nse_LANneedLogin nse_LANneedLogout nse_LANKeyBusy nse_DriverBusy Error Code Brief Description 0 Operation completed successfully 1 Dongle with specified search conditions not found 3 The specified address is too big 5 GP executions counter exhausted (has 0 value) 6 Bad dongle call command 8 Verification error occurred during writing to the dongles memory 9 Network protocol not found 10 License counter of Guardant Net is exhaust 11 Connection with Guardant Net server was lost 12 Guardant Net server not found 13 Guardant Net server memory allocation error 14 Guardant Net server found DPMI error 15 Guardant Net server internal error 16 Guardant Net server has been reloaded 17 This command is not supported by this dongle version (the version is too old) 18 Windows NT driver is required 19 Network protocol error 20 Network packet format is not supported 21 Logging in Guardant Net server is required 22 Logging out from Guardant Net server is required 23 Guardant Net is busy (locked by another copy of protected application) 24 Guardant driver cannot capture the parallel port
96
Error Name nse_CRCError nse_CRCErrorRead nse_CRCErrorWrite nse_Overbound nse_AlgoNotFound nse_CRCErrorFunc nse_CRCChkNSK nse_ProtocolNotSup nse_CnvTypeError
Error Code Brief Description 30 CRC error occurred while attempting to call the dongle 31 CRC error occurred while attempting to read data from the dongle 32 CRC error occurred while attempting to write data to the dongle 33 The boundary of the dongles memory has been override 34 The hardware algorithm with this number has not been found in the dongle 35 CRC error of the hardware algorithm 36 CRC error occurred while attempting to execute ChkNSK operation, or all dongles found 37 Guardant API release is too old 38 Non-existent reversible conversion method has been specified
Functions of nskXXXX() / nnkXXXX() Types

A set of functions of nskXXXX() and nnkXXXX() types provides you with an easy to use interface for accessing Guardant Stealth, Guardant Fidus and Guardant Net dongles. Using these functions, you can execute all necessary operations with the dongle (except for ChkNSK operation that can be executed using NSKCOMMAND() function for Guardant Stealth and Guardant Fidus dongles only). All required external modules and examples of usage of these functions are located in API\STEALTH subdirectory. The following functions of nskXXXX() and nnkXXXX() types are available:
Function Name Guardant Stealth, Guardant Fidus nskCheck nskDecGP Guardant Net Access Code Brief Description
nskTransform nskRead nskWrite nskInit
nskProtect
Primary built-in operations Private Find a dongle that matches specified search Read conditions. nnkDecGP Private Find a dongle that matches specified search Write conditions and decrements GP executions counter by 1 (counter #1). nnkTransform Private Convert information with the specified hardware Read algorithm. nnkRead Private Read N bytes from the dongle when in SAM/UAM. Read nnkWrite Private Write N bytes into the dongle when in SAM/UAM. Write nnkInit Private Initialize the dongles memory (release locks, Master remove the number of algorithms and their descriptors, as well as all data from user area). nnkProtect Private Implement locks/ assign the number of hardware nnkProtectLMS Master algorithms. nnkCheck
97
Users Manual
Function Name Guardant Stealth, Guardant Fidus Guardant Net
Access Code Service operations Brief Description
nnkDllMain nskSetMode nskFindFirst nskFindNext nskCodeInit nskEnCode nskDeCode nskCRC nnkSetMode nskFindFirst nskFindNext nnkCodeInit nnkEnCode nnkDeCode nnkCRC nnkLogin nnkLoginLMS nnkLogout nnkLockBeg
Not required Not required Public Public Private Read Not required Not required Not required Private Read Private Read Private Read Private Read Private Read
Must be called before any other Guardant API function in the protected DLL Set flags and other parameters for subsequent queries to the dongle. Find the first dongle with the specified Public Code. Find the next dongle with the specified Public Code. Initialize a password and a method for fast reversible conversion. Encode information using fast reversible conversion method. Decode information using fast reversible conversion method. Calculate 32-bit CRC of the memory block. Log in Guardant Net server. Log in Guardant Net server when using license management system. Log out from Guardant Net server. Lock Guardant Net in LAN (obtain an exclusive read/write access to the dongle for this particular application copy). Unlock Guardant Net in LAN (make it readable/writable for all network application copies).
nnkLockEnd
Functions, which do not require any access code, do not call the dongle during their execution.
Calling Functions of nskXXXX()/ nnkXXXX() Type

Guardant Stealth, Guardant Fidus
OUT_TYPE nskXXXX(parameters_set)
Guardant Net
OUT_TYPE nnkXXXX(parameters_set)
Most functions return error code in OUT_TYPE parameter with the ex ception of nXkSetMode functions (that return no message) and nXkCRC functions (return 4 byte CRC).
98
Below you will find a description of all functions of nskXXXX() and nnkXXXX() types. For better understanding, we recommend that you look at the example created for your programming language. Definitions of all functions and constants used by these functions for C/C++ lan guage are given in NVSKEY.H and NVSKEY32.H files. Below you will find an explanation to the types of variables used when de scribing functions (in accordance with the Hungarian Notation the type of a variable is specified in the prefix of the variables name):
dw w b n p
4-byte unsigned integer (double word). 2-byte unsigned integer (word). 1-byte unsigned integer (byte). 2-byte signed integer (integer). Address of another variable (pointer to another variable).
99
Users Manual
nnkDllMain Operation
For Guardant Stealth and Fidus:
Not available
For Guardant Net:

int nnkDllMain(HINSTANCE hModule, DWORD ul_reason_for_call, LPVOID lpReserved)
Operation type:
Service
In parameters:
HINSTANCE hModule DWORD ul_reason_for_call LPVOID lpReserved
Out parameters: Description: nnkDllMain() function is used in the Guardant Net API in order to cor rectly terminate procedures executed in 32 bit DLLs. The function is activated when an object file should be linked to Win32 DLL. You must call the nnkDllMain() at the start of DllMain function, prior to calling any of the Guardant Net API procedures. DllMain functions parameters are used as the parameters of the nnkDllMain() function. Example:
BOOL APIENTRY DllMain(HANDLE hModule, DWORD ul_reason_for_call, LPVOID lpReserved) { nnkDllMain(hModule, ul_reason_for_call, lpReserved); switch(ul_reason_for_call) { case DLL_PROCESS_ATTACH: break; case DLL_PROCESS_DETACH: nnkLogout(dwPrivateRead); break; case DLL_THREAD_ATTACH: break; case DLL_THREAD_DETACH: break; } return TRUE;
100
SetMode Operation. Specifying dongle search conditions & operation modes

nskSetMode (dwFlags, bProg, dwID, wSN, bVer, wMask, wType)
For Guardant Net:

nnkSetMode(dwFlags, bProg, dwID, wSN, bVer, wMask, wType)
Operation type:
Service
In parameters:
dwFlags BProg DwID WSN BVer WMask WType Search flags Application number Dongles ID Dongles serial number Version Mask Dongle type
Out parameters:
Not available
Description: nXkSetMode() functions set search conditions and other necessary in formation for further operations with Guardant Stealth (nskSetMode() function) or Guardant Net (nnkSetMode() function). Dongle search conditions and operation modes are specified by dwFlags parameter. The remaining parameters are used only when an appropriate flag is set. The following flags are available (their description for C/C++ language is given in NVSKEY.H and NVSKEY32.H files, flag values are presented in the table in hex system):
Flag Name nsf_Nprog nsf_ID nsf_SN nsf_Ver nsf_Mask nsf_Type Flag Value 0x1 0x2 0x4 0x8 0x10 0x20 Brief Description Dongle search flags Specifies that dongle with the program number specified in bProg parameter should be searched for. Specifies that dongle with the ID specified in dwID parameter should be searched for. Specifies that dongle with the serial number specified in wSN parameter should be searched for. Specifies that dongle with the version which is higher or same as specified in bVer parameter should be searched for. Specifies that dongle with the mask value which contains wMask parameter value should be searched for. Specifies that dongle of the type which is specified in wType parameter should be searched for.
101
Users Manual
Flag Name nsf_SysAddrMode nsf_CodeIsString nsf_NoRetry nsf_NoFullAccess nsf_OnlyStdLPT1 nsf_OnlyStdLPT2 nsf_OnlyStdLPT3
Flag Value 0x80 0x100 0x200 0x400 0x800 0x1000 0x2000
Brief Description Operation mode flags Enables SAM (System Address Mode) in read/write operations (UAM is a default mode). Reserved (used by NSKCOMMAND() function only). Disables auto configuration of dongle communication protocol. Disables full capture of the parallel port resource. Enables search for the dongle in LPT1 parallel port only (address 0x378). Enables search for the dongle in LPT2 parallel port only (address 0x278). Enables search for the dongle in LPT3 parallel port only (address 0x3BC). If none of these 3 flags is set, the dongle will be searched for in all parallel ports available. Indicates that data segment is different from the standard one (used by NSKCOMMAND() function only in 32-bit API). Reserved
nsf_NoAutoMem32 nsf_UseOldCRC
0x4000 0x8000
Furthermore, different types of Stealth dongles have different combina tions of dongle type flags (or OS types for which this dongle can protect applications). When searching for the dongle, these flags can be specified as well. The following dongle type flags are available:
Flag Name nskt_DOS, nskt_WIN nskt_LAN nskt_Time Flag Value 0 1 2 Brief Description The dongle supports protection of both DOS and Windows applications. The dongle supports protection of LAN applications. The dongle is capable of limiting the protected applications license term.
Flags of dongle types are used in order to provide compatibility with older API versions. In newer API versions you can manage without these flags since the type of Stealth dongle is identified automatically: nskXXXX() functions work with Guardant Stealth and Fidus (or Guardant Net is considered as local Guardant Stealth), nnkXXXX() functions work with Guardant Net in LAN environment. Automatic identification of Stealth dongle types provides for even more facilitated operations with Stealth dongles. Current models of Stealth dongles function as if they contained the fol lowing dongle type flags:
Guardant Stealth Guardant Fidus Guardant Net - nskt_DOS, nskt_WIN, nskt_Time. - nskt_DOS, nskt_WIN, nskt_Time, nskt_LAN.
102
If you have indicated nsf_Type among dongle search flags, then a dongle type flag(s) must be specified in wType parameter. Warning
nXkSetMode() functions do not call the dongle directly. They just set the API functions for operations with Guardant Stealth, Guardant Fidus or Guardant Net, which matches the specified parameters. During subsequent calls all nskXXXX() functions will be searching for the dongle in accordance with the search flags specified, and execute any operations with this dongle only. In case this dongle is not found, the function will return a corresponding error. Thus, nXkSetMode() call opens a session with the Stealth dongle of appropriate type. You should call this function before calling any other nskXXXX()/nnkXXXX() function. In the event you need to call another dongle of yours or change its search conditions, you should call nXkSetMode() again, but with new parameters.
After executing all operations with the dongle, we recommend that you call nXkSetMode() once again but with parameters, which have zero val ues. Thus, you will remove settings from the memory, which have been used by API functions. Examples: 1. Set the following parameters for nskXXXX() functions: search for the dongle of Guardant Stealth type with 10 as serial number, use SAM (Sys tem Addressing Mode) when executing read/write operations.
dwFlags = nsf_SN + nsf_SysAddrMode; dwFlags = dwFlags + nsf_Type; /* not mandatory */ bProg = 0; /* parameter is not used */ dwID = 0; /* parameter is not used */ wSN = 10; bVer = 0; /* parameter is not used */ wMask = 0; /* parameter is not used */ wType = nskt_WIN; /* or 0 if nsf_Type is not specified*/ nskSetMode(dwFlags, bProg, dwID, wSN, bVer, wMask, wType);
2. Set the following parameters for nnkXXXX() functions: search for the dongle of Guardant Net type with 20 as serial number, use SAM (System Addressing Mode) when executing read/write operations.
dwFlags = nsf_SN + nsf_SysAddrMode; dwFlags = dwFlags + nsf_Type; /* not mandatory */ bProg = 0; /* parameter is not used */ dwID = 0; /* parameter is not used */ wSN = 20; bVer = 0; /* parameter is not used */ wMask = 0; /* parameter is not used */ wType = nskt_LAN; /* or 0 if nsf_Type is not specified */ nnkSetMode(dwFlags, bProg, dwID, wSN, bVer, wMask, wType);
103
Users Manual
FindFirst Operation. Obtaining the ID of the First Dongle Found

nRet = nskFindFirst(dwPublic, pdwID)
Operation type:
Service
In parameters:
dwPublic Public code in numerical form. Address of the buffer for the ID.
Out parameters:
pdwID Error code
Description: nskFindFirst() function searches for the Stealth dongle of any type that has the Public code specified in numerical form. Search conditions are specified by nXkSetMode() functions. If such a dongle is found, nse_Ok message is returned, and the ID of the located dongle is written into pdwID, otherwise nse_KeyNotFound message is returned. This function can be used when identifying the required dongle in case several dongles are attached simultaneously. Example: Find the first Guardant Stealth/Net/Fidus demo dongle.
DWORD dwFoundID = 0; /* Specify Public code (described in NVSKEY.H file) */ dwPublic = ns_DEMONVK; /* Find this dongle */ nRet = nskFindFirst(dwPublic, *dwFoundID); /* Then there is a need to check error code (in nRet) and to decide on further running of the application */
104
FindNext Operation. Obtaining the ID of the Next Dongle Found

nRet = nskFindNext(pdwID)
Operation type:
Service
In parameters:
Not available
Out parameters:
pdwID Error code Address of the buffer for the ID.
Description: nskFindNext() function searches for the Stealth dongle of any type that has the Public code specified by nskFindFirst() function. Search condi tions are specified by nXkSetMode() and nskFindFirst() functions. If such a dongle is found, nse_Ok message is returned, and the ID of the lo cated dongle is written into pdwID, otherwise nse_KeyNotFound mes sage is returned. The function searches among the available dongles, ex cluding those already found. This function can be used during identification of the required dongle in case several dongles are attached simultaneously. Example: Find all Guardant Stealth/Net/Fidus demo dongles.
DWORD dwFoundID = 0; /* Specify Public code (described in NVSKEY.H file) */ dwPublic = ns_DEMONVK; /* Find this dongle */ nRet = nskFindFirst(dwPublic, *dwFoundID); /* Search over the remaining dongles */ while (nRet == nse_Ok) nRet = nskFindNext(*dwFoundID); /* Then there is a need to check error code (in nRet) and to decide on further running of the application */
105
Users Manual
Login Operation. Logging in Guardant Net Server

Not available
For Guardant Net:

nRet = nnkLogin(dwPrivateRD)
Operation type:
Primary built-in
In parameters:
dwPrivateRD Private Read code in numerical form.
Out parameters:
Error code
Description: nnkLogin() function allows a particular copy of the protected application to be logged in Guardant Net server. nnkLogin() searches for Guardant Net application server (that has to be loaded on the same computer to which Guardant Net is attached) across all NetBIOS interfaces available, establishes a link with this server and verifies the presence of the dongle with the Private Read code specified in numerical form. Additional don gle search conditions are set by nnkSetMode() function. If such a dongle is found (i.e., the information about this dongle becomes available to Guardant Net server), the value of its license counter is decremented by 1, and after that, the application copy is deemed logged in (nse_Ok message will be returned). Otherwise, a corresponding error code will be returned, and log out will take place. Guardant Net server will store the needed information about the logged in copy of the protected application until it is logged out by nnkLogout() function. To establish a link with the server all Guardant Net API func tions will be using its network address obtained upon login. This will sub stantially accelerate network exchange process. Warning
By calling nnkLogin() function a session of direct communication with Guardant Net in LAN begins. You should call this function before calling any other nnkXXXX() function except for nnkSetMode(). Any nnkXXXX() function (except for nnkSetMode()) called before nnkLogin(), will return nse_LANneedLogin error. You may not call nnkLogin() several times during one session with Guardant Net (i.e., before calling nnkLogout() function which logs the application copy out Guardant Net server). If an attempt is made to call nnkLogin()more than once, nse_LANneedLogout error will be returned. The Guardant Nets license counter is decremented in the memory of Guardant Net server, but not in the dongle.
106
Example: Find Guardant Net server with Guardant Net demo dongle that has 20 as serial number (search condition have already been specified by nnkSet Mode() function in the previous example) and log in it.
/* Specify Private Read demo code (described in NVSKEY.H file) */ dwPrivateRD = ns_DEMORDO; /* Log in Guardant Net server */ nRet = nnkLogin(dwPrivateRD); /* Then there is a need to check error code (in nRet) and to decide on further running of the application */
107
Users Manual
LoginLMS Operation. Logging in Guardant Net Server

Not available
For Guardant Net:

nRet = nnkLoginLMS(dwPrivateRD, bModuleLMS)
Operation type:
Primary built-in
In parameters:
dwPrivateRD bModuleLMS Private Read code in numerical form Module number in the license table
Out parameters:
Error code
Description: nnkLoginLMS() function is similar to nnkLogin() function and is exe cuted when the license management system is used, i.e. when the lisense limit of each module in a multi module application is controlled. nnkLoginLMS() logs a copy of the protected application in the Guardant Net server and captures a certain license from the license table. The function searches for the Guardant Net server (that should be in stalled on the same computer to which Guardan Net dongle is connected) and establishes a connection with it. Then nnkLoginLMS() checks the presence of the dongle with the specified Private Read code in numerical form (dwPrivateRD), as well as availability of the license table and the state of license counter of the required module (bModuleLMS) in this ta ble. Additional search conditions are specified by nnkSetMode function. If the dongle with the specified parameters has been found, its lisense counter as well as the license counter of the the required module in the li cense table, are decremented by one respectively. After that the applica tion copy is deemed logged in (nse_Ok code will be returned). Otherwise a respective error code is returned and the logging process is cancelled. Guardant Net server stores information about the registered copy of the protected application until its registration is terminated by nnkLogout() function. In order to get connection to the server all Guardant Net API functions use the servers network address that has been assigned to it dur ing the log in process. This considerably facilitates network communica tion.
108
Warning
By activating the nnkLoginLMS() function you can open a session of direct communication with Guardant Net in LAN. You should call this function prior to any other function of nnkXXXX() type, except for nnkSetMode(). If any function of nnkXXXX() type is called before the nnkLoginLMS(), the nse_LANneedLogin error code will be returned. Also, you should not call the nnkLoginLMS() function more than once during one session of communication with Guardant Net (i.e. before the nnkLogout() function is called that logs the application out from the Guardant Net server). If you try to call the nnkLoginLMS() more than once, an nse_LANneedLogout error code will be returned. The Guardant Nets license counter is decremented in the memory of Guardant Net server but not in the dongle itself.
Example: Suppose you need to find the Guardant Net server, which uses the license management system, with a demo dongle, then log into the server and es tablish connection with module 1 of the license table. The dongles serial number is 20 (search conditions have been already specified by the nnkSetMode() function in the previous example).
/* Specify Private Read demo code (see NVSKEY.H) */ dwPrivateRD = ns_DEMORDO; /* Specify the number of the module from the license table */ bModuleLMS = 1; /* Log into the Guardant Net server and connect to module 1 */ nRet = nnkLoginLMS(dwPrivateRD, bModuleLMS); /* Then you should check an error code (in nRet) and decide on further running of the application */
109
Users Manual
Check Operation. Checking for Availability of the Dongle

nRet = nskCheck(dwPrivateRD)
For Guardant Net:

nRet = nnkCheck(dwPrivateRD)
Operation type:
Primary built-in
In parameters:
Out parameters:
Error code
Description: nXkCheck() functions search for Stealth dongle of the appropriate type that has a Private Read code specified in numerical form. Search condi tions are specified by nXkSetMode() functions. If such a dongle is found nse_Ok message is returned; otherwise nse_KeyNotFound will be re turned. You may periodically call this function from various points of the applica tion to make sure that the dongle has not been removed from the com puter after the application has been started. Example: Check for the presence of Guardant Stealth demo dongle with 10 as serial number (search conditions have already been specified by nskSetMode function in the first example).
/* Specify Private Read demo code (described in NVSKEY.H file) */ dwPrivateRD = ns_DEMORDO; /* Find this dongle */ nRet = nskCheck(dwPrivateRD); /* Then there is a need to check error code (in nRet) and to decide on further running of the application */
110
DecGP Operation. Checking for Availability of the Dongle and Decrementing GP Executions Counter
nRet = nskDecGP(dwPrivateWR)
For Guardant Net:

nRet = nnkDecGP(dwPrivateWR)
Operation type:
Primary built-in
In parameters:
dwPrivateWR Private Write code in numerical form.
Out parameters:
Error code
Description: nXkDecGP() functions search for Stealth dongle of the appropriate type with a Private Write code specified in numerical form. Search conditions are specified by nXkSetMode() functions. If such a dongle is found, the value of GP counter (counter #1), generally used as protected application executions counter is decremented by 1. If completed successfully, nse_Ok message is returned. If the dongle is not found nse_KeyNotFound error will be returned, and if GP counter is used up (i.e., the counter value was 0 when the function was called) nse_GPis0 will be returned. Example: Find Guardant Stealth demo dongle with 10 as serial number (search conditions have already been set by nskSetMode function in the first ex ample). If such a dongle is found, decrement value of GP counter by 1.
/* Specify Private Write demo code (described in NVSKEY.H file) */ dwPrivateWR = ns_DEMOPRF; /* Find the dongle and decrement the value of its GP counter by 1 */ nRet = nskDecGP(dwPrivateWR); /* Then there is a need to check error code (in nRet) and to decide on further running of the application */
111
Users Manual
Transform Operation. Transforming Information Using the Dongles Hardware Algorithm

nRet = nskTransform(dwPrivateRD, bAlgoNum, bLng, pData)
For Guardant Net:

nRet = nnkTransform(dwPrivateRD, bAlgoNum, bLng, pData)
Operation type:
Primary built-in
In parameters:
dwPrivateRD bAlgoNum bLng pData Private Read code in numerical form. Hardware algorithm number. Length in bytes of the data block to be converted. Address of the data block to be converted.
Out parameters:
Error code
Description: nXkTransform() functions allow you to convert (transform) any informa tion using specified hardware algorithm of Stealth dongle of appropriate type. Conversion is one way; this feature is used to make the logic of op erating the dongle more complicated. Conversion is carried out by the al gorithm whose number is specified in bAlgoNum parameter. This algo rithm should be created in advance. The length in bytes of data array to be converted is specified by bLng parameter. The array length should be equal to the length of the algorithm query specified in its descriptor (al lowed values range between 4 and 255). The array should be placed in lo cation with the address specified in pData parameter. If the function is completed successfully, a sequence of converted data of the same length will be placed in location with the same address. In this case, the function returns nse_Ok.
112
Example: Find Guardant Stealth demo dongle with 10 as serial number (dongle search conditions have already been set by nskSetMode function in the first example) and convert Demo string using hardware algorithm #3 (DEMO, algorithm type is Simple, the length of the algorithm query is 4) created in this dongle.
BYTE szStringToTransform[] = {Demo}; /* A string to be converted */ dwPrivateRD = ns_DEMORDO; /* Private Read code */ bAlgoNum =3; /* Algorithms number */ bLng = 4; /* String length */ pData = szStringToTransform; /* String address */ nRet = nskTransform(dwPrivateRD, bAlgoNum, bLng, pData); /* Convert a string */ /* Then there is a need to check error code (in nRet) and to decide on further running of the application */
113
Users Manual
LockBeg Operation. Locking Guardant Net

Not available
For Guardant Net:

nRet = nnkLockBeg(dwPrivateRD)
Operation type:
Primary built-in
In parameters:
Out parameters:
Error code
Description: nnkLockBeg() function allows you to lock Guardant Net, i.e., make it readable/writable only for this particular copy of protected application. It is recommended that the dongle be locked before you execute several reads/writes in succession, so as the dongles memory contents are not damaged by any other protected application copy executing the same op erations at the same time. If any other copy of the protected application attempts to read/write the contents of the locked dongle, nse_LANKeyBusy error will be returned. The same error message will also be returned if an attempt is made to call nnkLockBeg() function for the locked dongle. Important
The lock applies only to read/write and lock operations executed with the dongle. Any other operations (log in/log out Guardant Net server, operations with hardware algorithms, etc.) can still be executed when the dongle is locked.
Example: Check the presence of Guardant Net demo dongle, with 20 as serial number (search conditions have already been specified by nnkSetMode() function in the first example) and implement a read/write lock for this particular copy of the protected application.
/* Specify Private Read demo code (described in NVSKEY.H file) */ dwPrivateRD = ns_DEMORDO; /* Find and lock the dongle */ nRet = nnkLockBeg(dwPrivateRD); /* Then there is a need to check error code (in nRet) and to decide on further running of the application */
114
Read Operation. Reading a Block of Bytes from the Dongles Memory

nRet = nskRead(dwPrivateRD, bAddr, bLng, pData)
For Guardant Net:

nRet = nnkRead(dwPrivateRD, bAddr, bLng, pData)
Operation type:
Primary built-in
In parameters:
dwPrivateRD bAddr bLng pData Private Read code in numerical form. Address of the first byte to be read from the dongle. Number of bytes to be read. Read data buffer address.
Out parameters:
Error code
Description: nXkRead() functions allow you to read data from the memory area of the Stealth dongle, which is not read protected. Additional condition for nnkRead() function: Guardant Net must not be locked by another copy of the application. The address of the first byte to be read is specified by bAddr parameter, and the number of bytes by bLng parameter. The op eration will be completed faster if the address of the first byte to be read is even numbered and you are reading an even number of bytes. The ad dressing mode is set while calling nXkSetMode function (UAM is the de fault addressing mode). If the function is completed successfully, the data read from the dongle will be placed in address specified by pData parame ter. In this case, the function returns nse_Ok message. If you attempt to read data from the memory area, which is read protected nse_Ok will also be returned, but no bytes will be read. Example: Find Guardant Stealth demo dongle with 10 as serial number and read 4 bytes from this dongle starting with address 108 SAM (dongle search conditions and SAM have already been specified by nskSetMode function in the first example). Place the read data in szBuffer buffer.
BYTE szBuffer[4]; /* Buffer for read data (4 bytes) */ dwPrivateRD = ns_DEMORDO; /* Private Read code */ bAddr = 108; /* Address of the first byte to be read*/ bLng = 4; /* Number of bytes to be read */ pData = szBuffer; /* Buffer address */ nRet = nskRead(dwPrivateRD, bAddr, bLng, pData); /* Read data */
115
Users Manual
Write Operation. Writing a Block of Bytes into the Dongles Memory

nRet = nskWrite(dwPrivateWR, bAddr, bLng, pData)
For Guardant Net:

nRet = nnkWrite(dwPrivateWR, bAddr, bLng, pData)
Operation type:
Primary built-in
In parameters:
dwPrivateWR bAddr bLng pData Private Write code in numerical form. Address of the first written byte. Number of bytes to be written. Address of the source data buffer.
Out parameters:
Error code
Description: nXkWrite() functions allow you to write data into the memory area of the Stealth dongle of appropriate type, which is not write protected. Addi tional condition for nnkWrite() function: Guardant Net must not be locked by another copy of the application. The address of the dongle, where the first written byte will be placed, is specified by bAddr parameter, and the number of written bytes by bLng parameter. The operation will be completed faster if the address of the first byte is even numbered and you are writing an even number of bytes. The addressing mode is set dur ing calling nXkSetMode function (UAM is the default address mode). If the function is completed successfully, bLng number of bytes will be taken from buffer with pData address and written to the dongle from the address specified by bAddr parameter. In this case, the function returns nse_Ok message. If you attempt to write data into the memory area, which is write protected nse_Ok will also be returned, but no bytes will be written. Example: Find Guardant Stealth with 10 as serial number and write 4 bytes to it from address 108 SAM (dongle search conditions and SAM have already been specified by nskSetMode function in the first example). Data to be written would be taken from szBuffer buffer.
BYTE szBuffer[4]; /* Buffer for data to be written (4 bytes) */ dwPrivateWR = ns_DEMOPRF;/* Private Write code */ bAddr = 108; /* Address of the first written byte */ bLng = 4; /* Number of bytes to be written */ pData = szBuffer; /* Buffer address */ nRet = nskWrite(dwPrivateWR, bAddr, bLng, pData); /* Write data */ /* Then there is a need to check error code (in nRet) and to decide on further running of the application */
116
LockEnd Operation. Unlocking Guardant Net

Not available
For Guardant Net:

nRet = nnkLockEnd(dwPrivateRD)
Operation type:
Primary built-in
In parameters:
Out parameters:
Error code
Description: nnkLockEnd() function allows you to unlock Guardant Net, i.e., make it readable/writable for all copies of the protected application. The function should be called immediately after completing several successive reads/writes in case you have already locked the dongle using nnkLock Beg() function. Otherwise, Guardant Net will remain read/write protected for some time for all the remaining copies of the protected ap plication running in LAN. Example: Check for the presence of Guardant Net demo dongle with 20 as serial number (search conditions have already been specified by nnkSetMode() function in the first example) and unlock it.
/* Specify Private Read demo code (described in NVSKEY.H file) */ dwPrivateRD = ns_DEMORDO; /* Find and unlock the dongle */ nRet = nnkLockEnd(dwPrivateRD); /* Then there is a need to check error code (in nRet) and to decide on further running of the application */
117
Users Manual
Init Operation. Initializing the Dongles Memory

nRet = nskInit(dwPrivateMST)
For Guardant Net:

nRet = nnkInit(dwPrivateMST)
Operation type:
Primary built-in
In parameters:
dwPrivateMST Private Master code in numerical form.
Out parameters:
Error code
Description: nXkInit() functions initialize the memory of Stealth dongle, i.e., they re lease read and write locks, zero fill the number of hardware algorithms and remove all data from user fields (i.e., all algorithm descriptors and other data stored in this area). The functions are used during manual reor ganization (i.e., without NSKUTIL program) of the dongles memory. We do recommend that you use these functions only in case of emer gency, as improper usage of those may cause damage to vital data. To re organize the dongles memory NSKUTIL program should better be used.
118
Protect Operation. Implementing Locks / Specifying the Number of Hardware Algorithms

nRet = nskProtect(dwPrivateMST, bWrProt, bRdProt, bNumAlgo)
For Guardant Net:

nRet = nnkProtect(dwPrivateMST, bWrProt, bRdProt, bNumAlgo)
Operation type:
Primary built-in
In parameters:
dwPrivateMST bWrProt bRdProt bNumAlgo Private Master code in numerical form. Address of the first word, which is not write-protected. Word addressing is used. Address of the first word, which is not read-protected. Word addressing is used. Number of hardware algorithms.
Out parameters:
Error code
Description: nXkProtect() functions allow you to set hardware read/write locks on a specified memory area of Stealth dongle of appropriate type, as well as specify the number of hardware algorithms in the dongle. Hardware locks can be set on a continuous memory area of the dongle beginning from ad dress 44 SAM. bWrProt parameter specifies the address of the first word that is not write protected. If the value of this parameter is 0, it means that no write locks have been set. bRdProt parameter specifies the address of the first word that is not read protected. If the value of this parameter is 0, it means that no read locks have been set. Both parameters use word ad dressing. For example, if bWrProt parameter is 54, it means that memory will be write protected from address 44 SAM through to address 108 SAM (bWrProt=108/2=54). bNumAlgo parameter specifies the number of hardware algorithms in the dongle. All these algorithms are to be created beforehand, i.e., their descriptors should be written into the dongles memory.
119
Users Manual
nXkProtect() functions are used at the final stage of manual reorganiza tion (without NSKUTIL program) of the dongles memory. At first, the dongles memory is initialized with nXkInit() function, then algorithms allocation table and algorithm descriptors are written into it. Finally, nXkProtect() function sets locks on locations containing the descriptors and specifies the number of algorithms created in the dongle. NSKUTIL program allows you to do this faster and easier; therefore we do not rec ommend that you use nXkInit() / nXkProtect() functions except for emergency.
120
ProtectLMS Operation. Implementing Locks and Specifying the Number of Hardware Algorithms
For Guardant Stealth Fidus:
Not available
For Guardant Net:

nRet = nnkProtectLMS(dwPrivateMST, bNumAlgo, bTableLMS) bWrProt, bRdProt,
Operation type:
Primary built-in
In parameters:
dwPrivateMST bWrProt bRdProt bNumAlgo bTableLMS Private Master code in numerical form. Address of the first not write-protected word in the dongle. Word addressing is used. Address of the first not read-protected word in the dongle. Word addressing is used. Number of hardware algorithms. Address of the first word in the license table (SAM). Addressing in words is used.
Out parameters:
Error code
Description: nnkProtectLMS() function is similar to nnkProtect() function and is exe cuted when the license management system is used, i.e. when the number of licenses of each module in a multi module application is controlled. nnkProtectLMS() allows you to implement hardware read/write locks on a specified memory area of Guardan Net dongle, as well as assign the number of hardware algorithms. Unlike the functions of nXkProtect() type, it takes into account the existence of the License table field (bTableLMS parameter). Hardware locks can be implemented on a continuous memory area of the dongle beginning from address 44 SAM. bWrProt parameter sets the ad dress of the first non write protected word . If the value of this parameter is 0, it means that no read locks have been implemented .
121
Users Manual
bRdProt parameter defines the address of the first non read protected word. If the value of this parameter is 0, it means that no read locks have been implemented. Both parameters use addressing in words. For exam ple, if bWrProt parameter is 54, it means that the write lock will be im plemented on the memory area starting from address 44 SAM through to address 108 SAM (bWrProt=108/2=54). bNumAlgo parameter defines the number of hardware algorithms in the dongle. All these algorithms must be created beforehand, i.e., their de scriptors should be written into the dongles memory. bTableLMS parameter defines the address of the first word in the license table (SAM). nnkProtectLMS() function is enabled at the final stage of the manual (without running the NSKUTIL program) reorganization of Guardant Net dongle memory. In the first instance, the dongle memory is activated by nnkInit() function, then the algorithm allocation table and algorithm descriptors are entered in to this memory. Finally, using the nnkPro tectLMS() function you can implement locks on the memory area where descriptors are stored and assign the number of algorithms in the dongle. NSKUTIL program can facilitate this procedure, therefore we recom mend you to use nnkInit() / nnkProtectLMS() functions only if its really necessary.
122
CodeInit Operation. Initializing Password for Fast Reversible Conversion

nRet = nskCodeInit(dwPrivateRD, wCnvType, bAddr, pKey)
For Guardant Net:

nRet = nnkCodeInit(dwPrivateRD, wCnvType, bAddr, pKey)
Operation type:
Service
In parameters:
dwPrivateRD wCnvType bAddr pKey Private Read code in numerical form. Fast reversible conversion method Hardware algorithms number. Address of the variable that contains conversion password
Out parameters:
Error code
Description: nXkCodeInit() functions prepare for fast reversible conversion. This con version method is suitable for processing large volumes of information (ki lobytes and megabytes). Besides, this conversion is reversible. nXkCodeInit() functions allow you to convert a password for its subse quent usage in nskEnCode() and nskDeCode() functions. The address of the variable containing a password to be converted specifies pKey pa rameter. The password length is fixed at 32 bytes. To convert a password a special hardware algorithm of Fast type is used; its number is specified in bAddr parameter. In case the function is completed successfully, the con verted password will be placed in location whose address is specified in pKey. wCnvType variable specifies a method for fast reversible conversion, which will be used in EnCode and DeCode operations. Three conversion methods are to be differentiated:
Name of Method nsat_Algo0 nsat_AlgoASCII nsat_AlgoFile Value 0 1 2 Brief description Basic method Character method File method
123
Users Manual
Basic method nsat_Algo0. Conversion of data is performed by 32 byte blocks. This method is better to be used for conversion of non string data. An important feature of this method is that if a large memory area (or file) is encoded by blocks, then decoding must be carried out using the same blocks, or the size of the blocks should be divisible by 32 bytes. nXkEn Code() and nXkDeCode() functions do not change the password. Character method nsat_AlgoASCII. Conversion of data is performed by 32 byte blocks. This method is suitable for conversion of string data. For example, if you wish to encode the name of a database field in the source code of the application, there will appear a problem of creating strings with non character values (this may happen when basic method of con version is used) in certain programming languages. On the contrary, char acter method converts strings so that they do not have non printable characters. For example, SerialNumber string can be converted into 13eFGSDFSDA0 string. nXkEnCode() and nXkDeCode() functions do not change the password. File method nsat_AlgoFile. Conversion is performed by blocks of optional size, therefore this method is well suited for conversion of files. However, this method turns to be ineffective when converting a file by blocks smaller than 32 bytes. nXkEnCode() and nXkDeCode() functions used in this method change the password, therefore nXkDeCode() function should be used in the same order as nXkEnCode() function. For example, if you have converted the file by four blocks (from the first block from the begin ning of the file to the fourth block) using nskEnCode() function, then re versible conversion using nskDeCode() function is to proceed in precisely the same order. Example: Find Guardant Stealth with 10 as serial number (dongle search conditions have already been specified by nskSetMode() function in the first exam ple), convert a password specified by szPassword string using algorithm #1 (Fast) of this dongle and specify a file method of conversion.
/* 32-byte long password to be converted */ BYTE szPassword[] = {"This is Demonstration Password !"}; dwPrivateRD = ns_DEMONVK; /* Private Read code */ wCnvType = nsat_AlgoFile; /* File method */ bAddr = 1; /* Algorithms number */ pKey = szPassword; /* Password address */ /* Convert the password and specify a file method */ nRet = nskCodeInit(dwPrivateRD, wCnvType, bAddr, pKey); /* Then there is a need to check error code (in nRet) and to decide on further running of the application */
124
EnCode Operation. Encoding Data Using Fast Reversible Conversion

nRet = nskEnCode(wCnvType, pKeyBuf, pData, dwLng)
For Guardant Net:

nRet = nnkEnCode(wCnvType, pKeyBuf, pData, dwLng)
Operation type:
Service
In parameters:
wCnvType pKeyBuf pData dwLng Fast reversible conversion method (should be the same as the one specified by nskCodeInit() function). Address of the variable that contains converted password. Address of the buffer that contains data to be converted. Size of data (in bytes) to be converted.
Out parameters:
Error code
Description: nXkEnCode() functions allow you to encode information through fast re versible conversion. In this case, the function does not call the dongle, and conversion is completed solely by the computer. This helps to achieve high conversion speed. pKeyBuf parameter contains a password previ ously converted by nXkCodeInit() function. This password will be used during data conversion. The data should be stored in the buffer whose ad dress is specified by pData parameter, the length (in bytes) of sequence to be converted is specified by dwLng parameter. Encoding is performed us ing method specified in wCnvType parameter. When choosing a method for conversion, you should take into account its features and restrictions (see description of methods). If the function is completed successfully, the encoded data will be placed in the buffer whose address is specified in pData. In this case, the function will return nse_Ok. wCnvType parameter specifies fast reversible conversion method. The value of this parameter will acquire special importance in future API ver sions, when reversible conversion mechanism becomes more sophisti cated. To provide compatibility with future API versions at this stage, you should specify the same method that you specified above when nXkCo deInit() function was called.
125
Users Manual
Example: Encode a 32 byte string using file method. Use the password converted in the previous example by the hardware algorithm of Guardant Stealth. En coding should be executed in two steps using 16 byte blocks. 16 byte blocks are used in this example in order to save space. However, you should remember that use of a string that is less than 32 bytes is rather in effective.
/*A 32-byte string to be encoded */ BYTE szString[] = {"This is My Demonstration String!"}; /* Length of one block of the string */ BYTE bPartSize = 16; wCnvType = nsat_AlgoFile; /* File method */ pKeyBuf = szPassword; /* Converted password */ pData = szString; /* First block of the string */ dwLng = (DWORD)bPartSize; /* Length of block */ /* Encode first block of the string using file method (in this case the password will be changed) */ nRet = nskEnCode(wCnvType, pKeyBuf, pData, dwLng); /* Then there is a need to check error code (in nRet) and to decide on further running of the application */ ... pData = szString+bPartSize;/* Second block of the string */ /* Encode second block of the string using file method (in this case the password will be changed again) */ nRet = nskEnCode(wCnvType, pKeyBuf, pData, dwLng); /* Then there is a need to check error code (in nRet) and to decide on further running of the application */
126
DeCode Operation. Decoding Data Using Fast Reversible Conversion

nRet = nskDeCode(wCnvType, pKeyBuf, pData, dwLng)
For Guardant Net:

nRet = nnkDeCode(wCnvType, pKeyBuf, pData, dwLng)
Operation type:
Service
In parameters:
wCnvType pKeyBuf pData dwLng Fast reversible conversion method (should be the same as the one specified by nskCodeInit() function). Address of the variable that contains converted password. Address of the buffer that contains data to be decoded. Size of data (in bytes) to be decoded.
Out parameters:
Error code
Description: nXkDeCode() functions allow you to decode information previously en coded by EnCode operation. The function does not call the dongle; con version is performed solely by the computer. pKeyBuf parameter contains a password previously converted by nXkCodeInit() function. This pass word will be used to decode data. The data should be stored in the buffer whose address is specified by pData parameter, the length (in bytes) of the string to be decoded is specified by dwLng parameter. If the function is completed successfully, decoded data will be placed in the location whose address is specified in pData. In this case, the function will return nse_Ok. wCnvType parameter specifies reversible conversion method. The value of this parameter will acquire special importance in future API versions, when reversible conversion mechanism becomes more sophisticated. To provide compatibility with future API versions at this stage, you should specify the same method that you specified above when nXkCodeInit() function was called.
127
Users Manual
Example: Decode a 32 byte long string encoded in the previous example, using file method. Use szPassword converted by nskCodeInit() function. Decoding should be executed in the same order as encoding (i.e., in two steps by 16 byte blocks).
/* A 32-byte string with encoded data */ BYTE szString[] = {"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}; /* Length of one block of the string */ BYTE bPartSize = 16; wCnvType = nsat_AlgoFile; /* File method */ pKeyBuf = szPassword; /* Converted password */ pData = szString; /* First block of the string */ dwLng = (DWORD)bPartSize; /* Length of block */ /* Decode the first block of the string using file method (in this case the password will be changed) */ nRet = nskDeCode(wCnvType, pKeyBuf, pData, dwLng); /* Then there is a need to check error code (in nRet) and to decide on further running of the application */ ... pData = szString+bPartSize;/* Second block of the string */ /* Decode the second block of the string using file method (in this case the password will be changed again) */ nRet = nskDeCode(wCnvType, pKeyBuf, pData, dwLng); /* Then there is a need to check error code (in nRet) and to decide on further running of the application */
128
CRC Operation. Calculating 32 bit CRC of a Memory Block

dwCRC = nskCRC(pData, dwLng, dwPrevCRC)
For Guardant Net:

dwCRC = nnkCRC(pData, dwLng, dwPrevCRC)
Operation type:
Service
In parameters:
pData dwLng dwPrevCRC Address of the memory block to calculate CRC. Length in bytes of the memory block. CRC of the previous memory block (if required).
Out parameters:
32-bit (4-byte) CRC of memory block
Description: nXkCRC() functions allow you to calculate the CRC (cyclic redundancy check) of a memory block. The CRC is generally used as a very reliable checksum of any data (change of at least one bit of data will result in se vere change of the CRC value). pData parameter specifies address of the memory block, and dwLng specifies the length of this block in bytes. If you wish to calculate the overall CRC of several blocks, you should enter the CRC calculated in the previous step into dwPrevCRC parameter when calculating the CRC of each next block. Otherwise, dwPrevCRC parameter should contain 0 value. nXkCRC() functions do not return any error code.
129
Users Manual
Example: Calculate the overall CRC of two strings.

/* The first string to calculate CRC */ BYTE szStr1[] = {"Copyright 1998-2000 Aktiv"}; BYTE bStr1Size= 28; /* Length of the string */ /* The second string to calculate CRC */ BYTE szStr2[] = {"All Rights Reserved"}; BYTE bStr2Size= 19; /* Length of string */ /* Here the intermediate CRC will be stored */ DWORD dwCRCtmp; /* Here the overall CRC will be stored */ DWORD dwCRCtotal; pData = szStr1; /* Address of the first string */ dwLng = (DWORD)bStr1Size; /* Length of the first string */ /* Calculate the CRC of the first string (the intermediate CRC) */ dwCRCtmp = nskCRC(pData, dwLng, 0); pData = szStr2; /* Address of the second string */ dwLng = (DWORD)bStr2Size; /* Length of the second string */ /* Calculate the overall CRC for two strings */ dwCRCtotal = nskCRC(pData, dwLng, dwCRCtmp);
Important
Among the functions of nskXXXX() / nnkXXXX() type there is no particular function available that would allow to generate a random number. However, you can take advantage of nXkTransform() functions using a hardware algorithm of Random type for conversion. Algorithm features have been chosen so that the value converted by this algorithm is a random number. The default size of the random number is 4 bytes, however, you can create an algorithm of Random type that would generate random numbers of other length.
130
Logout Operation. Logging out from Guardant Net Server

Not available
For Guardant Net:

nRet = nnkLogout(dwPrivateRD)
Operation type:
Primary built-in
In parameters:
Out parameters:
Error code
Description: nnkLogout() function allows you to log out a particular copy of the pro tected application from Guardant Net server. This function terminates the session with the network dongle and it is generally called upon termi nation of the protected application. During execution of this function the license counter of Guardant Net used by the application is recovered (in cremented by 1), and all information about this application copy is re moved from the memory of Guardant Net server. From that time on the application can access the network dongle only after executing nnkLogin() function. Warning
By calling nnkLogout() function the session with Guardant Net in LAN is closed. It is mandatory that you call this function before terminating a network application. Otherwise, the license captured by this application copy at the time of login will not be released and it will remain inaccessible to other application copies for the next 24 hours. Guardant software ver. 4.1 (release 7.06.02) and later uses improved license control mechanism. Client application (Win16, Win32) enquiries the server at least each 5 minutes. If the server does not receive enquiry from the client during 3 periods, it closes session and the license becomes available.
131
Users Manual
Example: Find Guardant Net server with Guardant Net demo dongle with 20 as se rial number (search conditions have been specified by nnkSetMode() function in the first example) and log out this copy of network application.
/* Specify Private Read demo code (described in NVSKEY.H file) */ dwPrivateRD = ns_DEMORDO; /* Log out this application copy from Guardant Net server */ nRet = nnkLogout(dwPrivateRD); /* Then there is a need to check error code (in nRet) and to decide on further running of the application */
132
Specific Features of Using Guardant Net API

To increase reliability of an application protected with Guardant Net in LAN, we strongly recommend that you take into account the following specific features of using Guardant Net API while designing protection: Before opening a session with Guardant Net, you should call nnkSetMode() and specify the required parameters of the dongle in it. All further operations will be executed only with the dongle whose parameters are identical to those specified in nnkSetMode(). If you plan to bind the application to Private codes only, there is no sense in calling nnkSetMode(). A session with Guardant Net should always begin with logging a particular application copy onto Guardant Net server with this dongle using nnkLogin() function. An attempt to call functions other than nnkSetMode() before executing nnkLogin() function will generate nse_LANneedLogin error. While executing this function, the dongle will be located, and its license counter will be decremented. As soon as nnkLogin() is successfully completed, you can call other Guardant Net API functions. Since in the course of execution of nnkLogin() availability of the dongle with the specified parameters is checked, this function can serve as a good substitute for nnkCheck() function during the initial dongle check. You can use nnkCheck() function in the future, for instance, when checking for the dongles availability at certain intervals. Since execution of nnkLogin() function may take quite a long time, it is better to call it during application loading. If that is impossible, it is advisable that a response to the pause that occurs be provided in the application (for example, a cursor can be changed or a corresponding alert can be displayed). A session with Guardant Net should always terminate by calling nnkLogout() function, which logs out the application copy from Guardant Net server. During execution of this function, the network license counter will be recovered. If the application is terminated without calling nnkLogout(), the license will remain captured (it will remain assigned to this workstation for the next 24 hours). Guardant software ver. 4.1 (release 7.06.02) and later uses improved license control mechanism. Client application (Win16, Win32) enquiries the server at least each 5 minutes. If the server does not receive enquiry from the client during 3 periods, it closes session and the license becomes available.
133
Users Manual
Using nnkLogin() you can connect to one Guardant Net only. If you wish to establish synchronous binding to several Guardant Net dongles with different parameters, you may switch between the two dongles as follows: o o o Call nnkLogout() function to disconnect from the first dongle; Call nnkSetMode() function to specify parameters of the second dongle; Call nnkLogin() function to connect to the second dongle.
While working with network dongles, you should always bear in mind that one and the same dongle can be queried by several copies of the protected application at a time. Imagine a situation when you need to read the contents of the dongles memory field, then modify and write them back to the dongle. It is probable that a second copy of the application is doing the same at the moment, writing the value that it has modified just in the interval between memory read and write operations executed by the first copy of the application. As a result, the first application copy will ruin what the second copy has just written to the dongle. This is not good at all. Therefore, it is very important to provide a mechanism for sharing the dongle as network resource between applications, especially when executing several interdependent read/write operations. This mechanism is enabled by two Guardant Net API functions, such as nnkLockBeg() and nnkLockEnd(). Before executing a number of sequential read/write operations, you should call nnkLockBeg() function (to lock the dongle). In case the function is completed successfully, the dongle will be captured by this particular copy of protected application, which can now start to perform its set of operations with the dongle. From this moment onwards should any other copy of the protected application or a different application attempt to perform read, write or lock operation, it will be terminated with nse_LANKeyBusy error displayed. You can call nnkLockBeg() function several times, and each time the locks counter of this dongle will be incremented by 1. The value of locks counter is displayed in the window of Guardant Net server to the left of the Public code of a respective dongle.
134
After you complete any interdependent operations, you should release the dongle (unlock it) with nnkLockEnd() function as soon as possible. Otherwise, the dongle will remain unavailable for reading from/writing to by other application copies. During execution of nnkLockEnd() function, the dongles lock counter will be decremented by 1. However, the dongle will become accessible only when the value of its lock counter reaches 0. Therefore, you should call nnkLockEnd() function the same number of times as nnkLockBeg() function. If any of the dongles remains locked for a long time (for example, because of the hang up of the computer running the application that locked the dongle), it will be forcibly unlocked upon timeout specified by LockTimeout=xx parameter from INI file of Guardant Net server. Dongle lock applies to read/write and lock operations only. Other operations (login/logout, checking of dongles presence, operations with the dongles hardware algorithms, etc.) can be executed by any copy of the protected application regardless of whether the dongle is locked. If, during execution of nnkLogout() function the dongle is locked by the application copy, it will be unlocked automatically. However, you should not overuse this capability. It is recommended to unlock the dongle as soon as possible after you have completed a set of interdependent operations. If any of nnkXXXX() functions returns nse_ServerReloaded error, it means that during running of the application Guardant Net server was for some reason reloaded. From that time on the server will not process queries of this particular application copy; this helps to prevent running of more copies of protected application than permitted by means of enforced reloading of Guardant Net server. Therefore, your application should respond to this error in the same way as it would to the absence of the dongle.
NSKCOMMAND() Function
Using this function, you may execute all necessary operations with the dongle. In fact, the difference between this function and nskXXXX() functions is that using NSKCOMMAND() you can also execute ChkNSK operation, i.e., find all dongles attached. All other capabilities of this function are also supported by nskXXXX() functions.
135
Users Manual
However, NSKCOMMAND() function is less convenient to use, and it can be employed only in languages that support usage of data structures. If you are not planning to use ChkNSK operation (frankly, it is difficult to imagine a situation when this operation may be needed for an ordinary application), you may skip this section. Description of NSKCOMMAND() function is rather complicated and is given here for your information only. API external modules containing NSKCOMMAND() function, are lo cated in API\STEALTH subdirectory. Important
NSKCOMMAND() function is available only in Guardant Stealth API.
NSKCOMMAND() Function Call Format 16 bit:

unsigned short pascal NSKCOMMAND(ns_Args far*);
32 bit:
unsigned NSKCOMMAND(ns_Args *);
To assign in parameters and obtain out parameters ns_Args structure is used. Its description can be found in NSK_SYS.H file. You should in clude this file into the source code of the protected application. Below is the description of ns_Args structure:
// Structure of in/out parameters for NSKCOMMAND function. typedef struct S_ns_Args { BYTE a1[5]; // Reserved BYTE na_bCmd; //IN Command code BYTE a_bAddr; //IN Address for read/write commands BYTE na_bLen; //IN Data length (in words/bytes) void FAR *na_pMem; //IN Pointer to data WORD na_wMem_Seg32; //IN Additional for FLAT32 DWORD na_dwPrivate; //IN Long binary Private Code DWORD na_dwFlags; //IN Search conditions BYTE na_szSprivate[9]; //IN Private in character form BYTE na_bNProg; //IN NProg used for dongle search DWORD na_dwID; //IN ID used for dongle search WORD na_wSN; //IN SN used for dongle search WORD na_wVer; //IN Ver used for dongle search WORD na_wMask; //IN Mask used for dongle search WORD na_wType; //IN Type used for dongle search WORD na_wRetCode; //OUT Return Code BYTE na_bRkmUserAddrW; //OUT wkmUserAddr BYTE na_bRkmAlgoAddrW; //OUT wkmAlgoAddr WORD na_wPrnport; //OUT Address of the parallel port WORD na_wNSKClientVersion; //OUT Number of the dongle client version
136
Chapter 8. Guardant API union U_na_CRC { BYTE bCRC8; WORD wCRC16; DWORD dwCRC32; } na_CRC; DWORD na_dwLen32 ; void FAR *na_pFast_Mem; //OUT Result of nsc_CRC command: //CRC 8 bit //CRC 16 bit //CRC 32 bit //IN Length of data array for which //CRC nsc_Code is to be calculated //IN pointer to data to be converted // with fast conversion method //IN Additional for FLAT32 //IN Type of algorithm used during // conversion or CRC calculation //Reserved
WORD na_wFast_Mem_Seg32; WORD na_wCnv_Type; BYTE na_cReserved[112]; } ns_Args;
Some fields of the structure are used to assign in parameters (they are marked as IN), while others contain the results of commands (marked as OUT). Description of NSKCOMMAND() Function Commands
Command name nsc_Check nsc_ChkNSK nsc_Transform nsc_ReadUAM nsc_WriteUAM nsc_ReadSAM nsc_WriteSAM nsc_Init nsc_Protect nsc_ReadBytesUAM nsc_WriteBytesUAM nsc_ReadBytesSAM nsc_WriteBytesSAM nsc_CodeInit nsc_EnCode nsc_DeCode nsc_GetRandom4 Access code PrivateRead Not required PrivateRead PrivateRead PrivateWrite PrivateRead PrivateWrite PrivateMaster PrivateMaster PrivateRead PrivateWrite PrivateRead PrivateWrite PrivateRead Not required Not required PrivateRead Brief description Search for Guardant Stealth and Fidus Find all dongles Get conversion result Read a block of words in UAM Write a block of words in UAM Read a block of words in SAM Write a block of words in SAM Release locks + number of algorithms + data from user fields Implement locks/assign the number of algorithms Read a block of bytes in UAM Write a block of bytes in UAM Read a block of bytes in SAM Write a block of bytes in SAM Initialization for nsc_EnCode/nsc_DeCode Encoding Decoding Get a random number (4 bytes) Primary built-in operations
Secondary built-in operations
Service operations
Those commands that do not require an access code, do not call the don gle during execution.
137
Users Manual
To run an operation you should fill in the required parameters and call NSKCOMMAND() function. Some parameters depend on a specific command, yet those that comprise a standard set of parameters (SSP) must be specified for all commands (except for nsc_ChkNSK and service commands):
Parameter name BYTE na_szSprivate[10]; DWORD na_dwFlags; Mandatory Yes, if nsf_CodeIsString flag is set Yes Purpose Private code in character form. Can be indicated if nsf_CodeIsString flag is set Flags: specify search conditions, type of Private code (character or numerical) Private code in numerical form Required application number Required ID value Required serial number value Version (it should be either higher or identical to the required one) Mask (bits of the specified mask should be found in the dongles mask)
DWORD na_dwPrivate; BYTE na_bNProg; DWORD na_dwID; WORD na_wSN; WORD na_wVer; WORD na_wMask;
Yes, if nsf_CodeIsString flag is not set No No No No No
Most commands always return a standard returnable set of parameters (SRS):

WORD na_wRetCode BYTE na_bRkmUserAddrW BYTE na_bRkmAlgoAddrW WORD na_wPrnport WORD na_wNSKClientVersion Duplicates return code. kmUserAddrW (see Stealth Dongles Memory Map). kmAlgoAddrW. Address of the parallel port, on which the dongle has been found. Dongle client version number (low byte, i.e., minor byte; high byte, i.e., major byte).
Besides, NSKCOMMAND() returns Guardant API Error Codes. When commands are executed, errors from the set of standard error codes (SEC) are usually returned:
nse_Ok nse_KeyNotFound nse_CRCError nse_ProtocolNotSup No errors. The dongle was not found. CRC error (doubtful action; response should be the same as to nse_KeyNotFound). Client protocol is not supported by the dongle.
Note that na_pMem_Seg32 and na_pFast_Mem_Seg32 parameters are required only for 32 bit applications and only in case when nsf_NoAutoMem32 flag is set. During execution of NSKCOMMAND(), about 50 bytes of stack are used (nsc_ReadBytesXXX and nsc_WriteBytesXXX commands require 150 bytes of stack). In Windows NT 16 bit libraries use extra 460 bytes of stack.
138
nsc_Check Operation type:

Primary built-in
Purpose: Searches for the dongle with indicated PrivateRead code and other pa rameters specified in na_dwFlags (for information about dongle search flags and dongle type flags). Required access code:
Private Read
In parameters:
na_bCmd = nsc_Check SSP
Out parameters:
SRS
Possible errors:
SEC
nsc_ChkNSK Operation type:

Primary built-in
Purpose: This command allows you to detect and sort over all Stealth dongles at tached to a stand alone computer. Parameters of the found dongle are en tered into ns_ChkNSK structure (the structure is described in NSK_SYS.H). Required access code:
Not available
In parameters:
na_bCmd na_pMem+ na_wMem_Seg32 na_bAddr = nsc_ChkNSK Table of rejected Ids (the size of each element of the table is 4 bytes). Number of elements in the table. Allowed values range between 1 and the block boundary. When calling nsc_ChkNSK for the first time, you should set that ID as 0. Length (in words) of data to be received. Allowed values range between 1 and chk_cAlgoAddr/2. If na_bLen=0, the function fails, and if na_bLen is higher of the stated maximum, then nse_CRCChNSK error will be returned.
na_bLen
139
Users Manual
Out parameters:
SRS na_pMem+ na_wMem_Seg32 If error code is 0, then data from the dongle will be located here from kmPublicCode field through to kmMnfTime field and from kmNProg field through to kmIndex field. Number of words not read (0, if everything is OK)
na_bLen
Possible errors
SEC nse_CRCChkNSK CRC error generated during receiving the response (occurs if there are no other dongles except for the rejected ID, or in case of an error, what is unlikely).
Commentary: Thus, to develop CHKNSK.EXE, you should first call nsc_ChkNSK with the blank table of rejected IDs, then with the table containing one ID found during the first query, then with the table containing two IDs received from two queries, etc., until nse_CRCChkNSK error is re turned, which means that all dongles have been sorted over. This command may be useful in extraordinary cases when multiple don gles with same codes are attached to the computer, and when the pro tected application needs to communicate with all of the dongles. nsc_Init Operation type:
Primary built-in
Purpose: This command clears all memory in the range between kmAlgoAddr and the end of kmUserData and from kmWriteProtect through to kmRe served2 (see Stealth Dongles Memory Map). The command is used when you need to delete algorithms, user data or hardware locks. The last 8 bytes are not deleted since they are in use by diagnostic programs. We do not recommend that you erase this area manually or otherwise use it, be cause this will make diagnostics more problematic in case of a dongle fail ure. Required access code:
Private Master
In parameters:
na_bCmd SSP = nsc_Init
140
Out parameters:
SRS
Possible errors:
SEC
nsc_Protect Operation type:

Primary built-in
Purpose: Fills in kmWriteProtect, kmReadProtect, kmNumAlgo and kmRe served2 fields (see Stealth Dongles Memory Map), if they contain 0 values. This is the only command that can be used to enter values in these fields. Required access code:
Private Master
In parameters:
na_bCmd SSP na_pMem+ na_wMem_Seg32 = nsc_Init Address of four bytes to be written starting from kmWriteProtect address and through to kmReserved2 address. Only zero valued cells may be filled. For example, if kmNumAlgo field contains 3, then nothing can be written to this field until it is cleared by nsc_Init command. In this case no diagnostics is returned.
Out parameter:
SRS na_bLen Shows how many bytes are not written in case of an error. If there is no error, 0 is returned.
Possible errors:
SEC nse_VerifyError nse_CRCErrorWrite Verification error after several retries; writing terminates. CRC error; writing terminates
141
Users Manual
nsc_Transform Operation type:

Primary built-in
Purpose: Returns a result of conversion performed by Y=F(X) hardware algorithm. Conversion is performed by the dongle, therefore, this command is not convenient for converting large data volumes. Conversion is one way. X and Y size is assigned during algorithm definition. Required access code:
Private Read
In parameters:
na_bCmd SSP na_pMem+ na_wMem_Seg32 na_bAddr na_bLen = nsc_Transform Address of a buffer containing data sequence to be converted; also used for holding results. Number of the algorithm. Allowed values range between 0 and kmNumAlgo - 1. Query size or a number of bytes in the argument/result. This should match rs_blen parameter, which is specified when creating an algorithm in NSKUTIL
Out parameters:
SRS na_pMem+ na_wMem_Seg32 Converted data
Possible errors:
SEC nse_AlgoNotFound nse_CRCErrorFunc Algorithm with the specified number does not exist. CRC error occurred during algorithm execution. This error usually occurs if the length of the sequence to be converted does not coincide with the length specified during algorithm creation. Algorithms counter has reached zero value. It is no longer possible to get an algorithm result.
nse_GPis0
142
nsc_ReadUAM, nsc_ReadSAM Operation type:

Primary built-in
Purpose: Using these functions, you can read a specified number of two byte words beginning from the specified address in UAM (SAM) system. If you at tempt to read data, which are write protected, they will be read as 0. If you specify too high an address and/or length, nse_CRCErrorRead error will be returned, and nothing will be read in this case. Required access code:
Private Read
In parameters:
na_bCmd SSP na_pMem+ na_wMem_Seg32 na_bAddr = nsc_ReadUAM (nsc_ReadSAM) Address of a buffer to be read. Required size in bytes can be calculated using the following formula: na_bLen*2. Address in UAM (SAM) of the first word to be read. Allowed values range from 0 to ns_realMAXAddrWkmUserAddrW (to ns_realMAXAddrW) (see Stealth Dongles Memory Map). Number of words to be read. Allowed values range from 1 to ns_realMAXAddrW-kmUserAddrW-na_bAddr (to ns_realMAXAddrW-na_bAddr)
na_bLen
In parameters:
SRS na_pMem+na_wMem_Seg32 Read data.
Possible errors:
SEC nse_CRCErrorRead CRC error occurred during reading; indicates that not everything has been read
nsc_WriteUAM, nsc_WriteSAM Operation type:

Primary built-in
Purpose: Write the specified number of words from the specified address in UAM (SAM) system. If you attempt to write data, which are write protected, then after write retries verification error will be returned. If you specify too high an address and/or length, nse_CRCErrorRead error will be returned, and nothing will be written in this case.
143
Users Manual
Required access code:

Private Write
In parameters:
na_bCmd SSP na_pMem+ na_wMem_Seg32 na_bAddr = nsc_WriteUAM (nsc_WriteUAM) Address of buffer. Address of the first word to be written in UAM (SAM). Allowed values range from 0 to ns_realMAXAddrW-kmUserAddrW (to ns_realMAXAddrW) (see Stealth Dongles Memory Map). Number of words to be written. Allowed values range from 1 to ns_realMAXAddrW-kmUserAddrWna_bAddr (to ns_realMAXAddrW-na_bAddr).
na_bLen
Out parameters:
SRS High byte Number of words that have not been written (if error has occurred).
Possible errors:
SEC nse_VerifyError nse_CRCErrorWrite Verification error displayed after several retries; writing terminates. CRC error; writing terminates
nsc_ReadBytesUAM, nsc_ReadBytesSAM, nsc_WriteBytesUAM, nsc_WriteBytesSAM Operation type:

Primary built-in
Purpose: Read and write a block of bytes (i.e., these commands address the mem ory in bytes). Difference from similar commands operating with word addressing: 1. Allowed values for na_bAddr range between 0 and ns_realMAXAddr 1, for na_bLen range between 0 and ns_realMAXAddr 1 (where 0 means 0x100, i.e., ns_realMAXAddr) in SAM, these values being lower by kmUse rAdrr in UAM. 2. Time of execution of read commands may be two times as much as word reading in case odd numbered start addresses and/or length are specified (let it be called even boundaries rule).
144
3.
4. 5.
6.
7.
Time of execution of write commands may be five times as much as word writing in case odd numbered start addresses and length are specified. In case of an error, write command returns the number of unwrit ten bytes in the high byte of return code. If an attempt is made to read/write more bytes than permitted (be yond the memory limit), then the length is truncated (na_bLen pa rameter is changed when returned from the function). When these commands are executed NSKCOMMAND() func tion is called recursively, therefore, the stack is used very inten sively. For the normal execution of commands, approximately 150 stack bytes are required. In the low byte of return code (na_wRetCode and AL register), two high bits are intended for a special purpose. Since NSKCOMMAND() function can be called several times, then if even boundaries rule has been violated only a part of operation can be executed. If return code is any other but 0, the values of two high bits (6 and 7) help to determine which part of the operation has not been executed: 0 The first byte has not been read/written. 1 The last byte has not been read/written. 2 The first and the last bytes have not been read/written. 3 Nothing has been read/written. In a high byte the number of bytes that have not been read (0 means 0x100).
nsc_CodeInit Operation type:

Service
Purpose: Specifies fast reversible conversion method and converts the password for fast reversible conversion, which will be further used in commands such as nsc_EnCode, nsc_DeCode. Required access code:
Private Read
145
Users Manual
In parameters:
na_bCmd na_pMem+ na_wMem_Seg32 na_bAddr na_wCnv_Type SSP = nsc_CodeInit Address of buffer containing a password to be converted. Algorithms number in the dongle. Allowed values range between 0 and kmNumAlgo - 1. Conversion method. Allowed values are: nsat_Algo0, nsat_AlgoASCII, nsat_AlgoFile.
Out parameters:
SRS na_pMem+ na_wMem_Seg32 Converted password
Possible errors:
SEC nse_AlgoNotFound nse_CRCErrorFunc Algorithm with the specified number does not exist. CRC error occurred during algorithm execution. It usually occurs if the length of the password to be converted does not coincide with the length of the algorithm response. The algorithms counter has reached zero value. No result can be obtained from this algorithm anymore. Wrong conversion method has been specified.
nse_GPis0 nse_CnvTypeError
nsc_EnCode, nsc_DeCode Operation type:

Service
Purpose: Encoding (decoding) of data by fast reversible conversion. Required access code:
Not required
In parameters:
na_bCmd SSP na_pMem+ na_wMem_Seg32 na_pFast_Mem+ na_wFast_Mem_Seg32 na_dwLen32 na_wCnv_Type = nsc_EnCode (nsc_DeCode) Address of a buffer containing a password that has been modified by nsc_CodeInit. Address of data to be converted. Length of data block to be converted. Conversion method (should be equivalent to the method specified by nsc_CodeInit command). Allowed values: nsat_Algo0, nsat_AlgoASCII, nsat_AlgoFile.
146
In parameters:
SRS na_pMem+ na_wMem_Seg32 Converted data.
Possible errors:
SEC nse_CnvTypeError Wrong fast conversion method was specified.
nsc_CRC Operation type:

Service
Purpose: Calculates 8, 16 or 32 bit CRC (cyclic redundancy check). You can cal culate continued CRC if hmf_UseOldCRC flag is specified. This is use ful when CRC needs to be calculated for the memory area that is split into several blocks. Note that CRC values of the same memory area calculated using different blocks will be different. Required access code:
Not required
In parameters:
na_bCmd na_CRC.bCRC8 na_CRC.wCRC16 na_CRC.dwCRC32 na_pFast_Mem+ na_wFast_Mem_Seg32 na_dwLen32 = nsc_CRC Initial 8-bit CRC if na_wCnv_Type equals nsv_CRC8, and nsf_UseOldCRC flag is set, or Initial 16 bit CRC if na_wCnv_Type equals nsv_CRC16, and nsf_UseOldCRC flag is set, or Initial 32-bit CRC if na_wCnv_Type equals nsv_CRC32, and nsf_UseOldCRC flag is set. Address of buffer containing information for calculating the CRC. Number of bytes for the CRC calculation (only 16 bits are used for 16-bit mode and 32 bits for 32-bit mode). 8-bit CRC (for nsv_CRC8) 16-bit CRC (for nsv_CRC16) 32-bit CRC (for nsv_CRC32) nse_Ok
Out parameters:
na_CRC.bCRC8 na_CRC.wCRC16 na_CRC.dwCRC32 na_wRetCode
Possible errors:
nse_Ok
147
Users Manual
nsc_GetRandom4 Operation type:

Service
Purpose: Obtains a 4 byte random number. Random number is generated in the dongle using algorithm #2 (Random) embedded in the dongle at the site of manufacturing. If algorithm #2 is not available in the dongle or if it is of other type than Random, the function will return an error. Required access code:
Private Read
In parameters:
na_bCmd SSP na_pMem+ na_wMem_Seg32 = nsc_GetRandom4 Address of buffer to receive a random number (the minimum buffer size is 4 bytes).
Out parameters:
SRS na_pMem+ na_wMem_Seg32 Random number
Possible errors:
SEC nse_AlgoNotFound nse_CRCErrorFunc nse_GPis0 Algorithm with specified number does not exist. CRC error occurred during execution of the algorithm. Algorithms counter has reached zero value. No result can be obtained from this algorithm anymore. The counter is exhausted if the command has been called over 232-2 times (about 4 billion times).
148
Source Code Generator

Guardant Source Code Generator is a utility that facilitates creation of software protection systems based on Guardant API. Using the data required for running of the protected application the Gen erator creates a source code for the procedure, which verifies the legality of the application copy. The created code is compiled with the original source code of the application. You will only be required to arrange for correct error processing, and the process of creation of API based protec tion will be henceforth deemed completed. The Generator contains an editor for programming languages description files (LNG files) that allows you to generate descriptions for almost any programming language. Besides, descriptions are available for the most commonly used programming languages. Guardant Source Code Generator allows you to configure the settings of the future procedure, including: Encoding of source tables (3 modes) CRC validation (5 options) Encryption of dongle access codes (3 modes) Utilization of extra capabilities of the Generator provides an opportunity to create a more efficient and stronger protection system. This version of the Generator supports three types of dongles: Guardant Stealth, Guardant Fidus and Guardant Net. Operating Principles Using the dongles hardware algorithm the Generator converts data re quired for the application into a source code to be represented in the lan guage you choose. This obtained text contains encoded data, a password for encoding/decoding and a decoding function. The password and the function are generated during the running of the utility. The password is built according to a certain rule out of numerical values accumulated in the so called source tables. The decoding function is composed of a num ber of math operations and Guardant API function calls. The code created by the Generator should be spread across the applica tion source code and compiled. Important
After compilation, the file with initial data is no more required for the application, since all information is now contained in the generated code.
When the protected application is started, the transform function decodes the password, which, in turn, decodes encoded data to original form. It is obvious that only legal application copy will decode these data correctly if dongle with the specified parameters is available.
149
Users Manual
Procedure After the utility has been started, follow the steps below: 1. In the Generation tab specify the name of the file that contains the initial data to be encoded and identify the type of the latter specify the name of the file to save the generated code specify a programming language to be used for code generation specify the form in which the generated code will be presented (a complete program or a code fragment) Build project after generation and Execute application after building options may be set for debugging purposes when several protection modules are used, specify a names prefix of this module 2. In the Transforms tab specify parameters of the algorithm which executes external data transform specify the number and size of source tables in which the encoding/decoding password will be located specify parameters of the decoding transform function define a mode of encryption of source tables 3. In the More tab specify CRC validation options specify a method of generating random numbers specify a reaction on runtime errors occurred in the code being generated 4. In the Dongle tab, specify type and parameters of the dongle to be used with the protected application. 5. Save the specified parameters and start generation process. Hints on Usage Parameters of Data to be Encoded Data to be encoded can be represented by vital data in the absence of which the program cannot run properly, a list of passwords to program settings, a small database, program code, etc. The size of the file contain ing source information should not exceed 10 KB in 16 bit applications. Otherwise, problems may arise with compilation of the code. Options Used for Debugging Purposes Only
Complete program option (Generation tab) Build project after generation and Execute application after building options (Generation tab) Options of the Display passwords group (More tab)
150
Options Used to Strengthen the Protection System

Encrypt decoded data option (Generation tab) options of the Tables encoding group, except for Do not encode option (Transforms tab) CRC validation options (More tab) options of the Encrypt dongle access codes group, except for Do not encode option (Dongle tab)
Restrictions Imposed on Interface Parameters Sometimes during the compilation of the generated code, some develop ment tools return error messages such as Function too large or State ment part too large. This may happen in FoxPro, Pascal, Visual Basic and other programming languages with fixed size program elements (data and code segments, number of relocations). Code generated through combining certain settings of the Generator can exceed these sizes. To solve this problem you should decrease the values of the following pa rameters of the Generator: Maximum function length, Number of ta bles and Size of each table. You should select such a combination of pa rameters that would allow the compiler to process generated code without errors. Spreading the Generated Code Across the Application. Intermixing of Variables The generated code should not be embedded into the protected applica tion as an unbroken fragment. Instead, the code should be split into small parts which need to be spread across the application body so that the fragment which implements protection functions is not regarded as a sin gle whole entity. To make finding of protection functions variables with a debugger more difficult it is recommended that these variables be intermixed with other variables in the application. Multiple Protection Modules To add strength to the protection system you can create and compile sev eral code fragments with various sets of source data, Generator settings and name prefixes. Configuration file of each fragment can be saved sepa rately for further usage. Fragments should be called from different parts of the protected application by various parameters (dates, events, theoretic frequency). For example, you can arrange for a specific program execution algorithm so that different protection modules would be activated at each applica tion startup.
151
Users Manual
Main Window of the Source Code Generator The Generators interface is composed of four tabs (Generation, Trans forms, More and Dongle). Typically, controls in tabs are joined in groups, however sometimes they can be placed separately. At the bottom of the window, there are buttons available which control running of the Genera tor: [English/Russian] switch from one language to another. The Genera tor automatically identifies the code page.
[Generate] start generation of the source code [Load] load the saved program settings from the configuration file [Save] save the current program settings to a configuration file [Help] call on line help [Exit] exit the Generator
In the lower left corner of the window the statistics about Generators ac tivities is displayed. Generation The Generation tab contains the controls that allow you to choose pro gramming language, specify names of the files, which contain initial data and results, edit LNG files, etc.
Figure 3. Generation tab of the Generator
152
Source Code Format

The source code created by the Generator can be represented in the form of a complete program or a code fragment. In the first case, the generated program can be immediately compiled and used for testing and debugging purposes. To be embedded into the source code of the application, protection mod ules should be represented as code fragments. Important
Descriptions of Guardant API functions required for compilation of the application to be protected and of generated fragment, can be found in the LNG file created for the corresponding programming language (see the LNG file).
Prefix and Comments

Before generation of the source code, you can check the option Insert
comments. This will facilitate analysis of the generated code.
The Module names prefix field is used for building of multiple protec tion modules when several fragments of the source code are created that interact according to certain principles. In this case, names of variables in different modules should have different prefixes. This is important for such programming languages as Assembler and FoxPro, in which there exists a global names space. This means that the variables of one applica tion module can be seen in other application modules. By default, the prefix entered in this field is m1_. Example: If the name of the variable is dwTmp1 and the prefix of the module names is m1_, the name of the generated variable in the source code should be read as m1_dwTmp1. Initialize arrays during description option defines method of initiliza tion of arrays in the generated text. If the flag has not been set, the initiali zation is done by assigning values element by element, however if it has been set, the initialization is done during the description of the array. This option can be useful when you need to diminish the size of the generated code.
Programming Language
A programming language for the source code to be created is selected from the pull down list. Next to it there is a button available for calling LNG files Editor. It provides access to the file containing a description of chosen programming language (see the LNG file).
153
Users Manual
Current version of Generator includes LNG files for the following pro graming languages: Assembler 16 bit real mode Assembler Win32 Borland Pascal 16 bit Delphi 32 bit MS Visual Basic 32 bit MS & Borland C/ C++ 16 bit MS & Borland C/ C++ 32 bit Important:
Starting from Version SRCGEN 2.0, TopSpeed Clarion 32 bit and Visual FoxPro 32 bit are not supported. In order to generate a source code for these development tools, you should use the Generator of the previous version.
Source Text
The name of file for the generated code to be placed is entered and dis played in the Name of file to be created field. The file can be selected by a click on the button next to the input field, or specified manually. On checking the option Open with the input field becomes available. The name of the program, to be used for opening the generated file is en tered into this field. The program can be selected by a click on the button next to the input field. You can configure this option so that it would acti vate the required compiler or development environment. By default, the created file will be opened with Windows notepad (notepad.exe). Build project after generation and Execute application after building options may be used if complete program code is to be generated (Complete program option is selected). These options are useful for de bugging purposes only. Build project after generation option forces immediate compilation of the program after it has been generated. Use of this option requires the full path to the compiler to be specified in DO_COMPILE tag of LNG file. Execute application after building option forces execution of the pro gram after it has been compiled. The full path to the executable module must be specified in DO_RUN tag of LNG file.
Data to be Encoded
The Name of file for data to be encoded field is used for entering of the name of file containing the source data to be encoded. The file can be selected by a click on the button next to the input field. The Read the file as pull down list is used to identify the form in which the data to be encoded will be represented: Binary data are represented in binary form Text data are represented in alphanumeric form
154
Word array data are represented as numerical values separated by commas. The maximum numerical value is 65535 Double word array data are represented as numerical values separated by commas. The maximum numerical value is 232 1 Encrypt decoded data flag is set if the protected application does not need the data after they have been used. This may happen, for example, when encoded data are used only for checking the legality of the software product copy. As soon as this option is selected, a function that re encrypts the decoded data will be placed into the generated code thus adding strength to the protection system. Decoded data must be used between matching nXkDecode/nXkEncode function calls. Transforms In this tab, you can specify the type and specifics of the tools that are used for data conversion: hardware algorithm parameters and decoding func tion, the number and size of source tables, etc.
Figure 4. Transforms tab of the Generator
Algorithm
Source data are encoded using hardware algorithms of the dongle. You should specify for the Generator the parameters of the algorithm, which will be used in the process of encoding. These are specified in the fields Algorithm number (ordinal algorithms numbers are specified in the Type column of the main dialogue box of NSKUTIL utility) and Algorithm request and response length.
155
Users Manual
In the latter field of the group, the length of data blocks interchanged be tween the dongle and the protected application is specified in bytes. The [Check] button allows you to test the execution of the algorithm with the specified parameters. Important
1. Algorithms of Random type cannot be used with the Generator 2. By default, the Algorithms number field contains 0 (AutoProtect algorithm)
Transform Function
The Generator creates a pseudorandom function with specified parame ters, which decodes data. In the Maximum function length field the number of mathematical op erations performed by the function during one cycle (iteration) is speci fied. The number of function iterations equals to the number of source ta bles (see next section). The Apply constant function length flag is set when the same number of operations is to be maintained in all cycles. If the option is not acti vated, the number of operations varies and is calculated in each iteration of the function generated (the number can range from 1 to maximum function length).
Tables
The Tables group is used to specify the number and size of source tables from which the numerical values will be randomly picked up. On these values queries to the hardware algorithm are calculated when running the protected application. The Number of tables (Transform steps) field is used to specify the number of source tables. The number of tables determines the number of iterations (cycles) executed by the transform function. At the end of each iteration, the Transform operation is executed using parameters of the al gorithm specified in the Algorithm group. The function depends on the value obtained during the previous mathematical operations. The Size of each table field specifies the size of the table in double words.
Tables Encoding
Tables encoding adds more strength to protection because in this case queries are not stored in the application memory as is. Conversion of queries is executed by the previously chosen hardware algorithm. Table encoding process supports 3 modes: Not encoded queries are not encoded. Random password queries are encoded using the password produced by the Generator.
156
User defined password queries are encoded using the password specified by the developer of the protection system. The password is entered in the field that becomes available only in this particular mode. You can select the mode of encoding from the pull down list. More The More tab is used for selection of additional generation parameters among which are several modes of CRC validation and methods of gener ating random numbers, as well as options useful during debugging and testing of the generated code.
Figure 5. More tab of the source code Generator
Validate
Using the options of this group, you can make the Generator execute and include into the source code some additional functions, which hamper greatly protection code modification. In case the following flags are set, then: Dongle codes CRC the source code of the function generated is complemented by the validation of the CRC of the codes, which qualify access to the dongle in use Source tables CRC allows you to verify the integrity of tables built during execution of the Generator and contained in the generated text. This option is more effective when tables encoding mode is used
157
Users Manual
Complement tables CRC allows you to validate the integrity of tables which contain complements. These tables are formed during execution of the Generator. They present vital components during password generation and are used during its encoding /decoding Each step result CRC selection of an element from the source table for each next iteration depends on CRC value calculated during previous iteration Decoded data CRC correctness of decoding of initial data is checked
Random Values
You can assign a method of generating a random number to the Genera tor. The following methods are available: Regular language function: a random number is generated by utilizing built in programming language tools. This method provides for generation of a numerical sequence closest to a random one. However, not every programming language has standard routine for gen erating random numbers. For languages that do not have either these rou tines or their routines do not fully satisfy the task conditions, it is recom mended that you use alternative methods (i.e. timer based method, don gle algorithm, user defined function). Another alternative is to include the user defined functions source code into LNG file (see description of the PROGRAM_STRUCTURE tag). Timer-based: a random number is generated using the function that depends on the system time. Dongle algorithm: a random number is determined by the hardware algorithm of the dongle. When this method is selected, the input field, where you can specify the number of the hardware algorithm of Random type, becomes available. User expression: any user defined expression is used as a random number. This may be a constant value or a variable, or a function that has been specified in other module of the protected application.
Error Handling
Options of this group are used to identify application response to errors that may occur during execution of the generated code. In case of an error the following can be performed: Exit the program: the program is terminated. In the input field, you should specify the return code, which the generated function will return in case of a failure to the module that called it. GOTO <label>: jump to the label specified by the developer
158
In the input field, you should specify the name of the label. It should be noted that not all programming languages support this operation. User expression: calling of the exceptions handler in the application (for example, processing of exceptions in C++) or calling of a certain error processing function. The information of the protection developer is entered into the input field. Call nnkLogout on errors option may be set if Guardant Net is used. When the option is set, nnkLogout (log out from dongle server) function call is in cluded into the source code for correct shutdown of the application.
Display Passwords
Elements of this group manage the display of passwords on the screen. When the Decoding flag is set, a password that has been used for encod ing of initial data will be displayed on the screen. When the Decoded flag is set, the decoded initial data will be displayed on the screen. Important
It is recommended that you use these flags only for debugging purposes, i.e., during generation of the complete program to verify the correctness of decoding.
Dongle In the Dongle tab, controls are available for including of queries to a spe cific dongle into the code to be generated.
Figure 6. Dongle tab of the source code Generator
159
Users Manual
Dongle Type
This group defines type of Guardant dongle to be used with the protected application: Guardant Fidus, Guardant Stealth or Guardant Net.
Search Parameters
This group defines parameters of the dongle to be used with the protected application. You can specify the following dongle search parameters: Program number Version Serial number Dongle ID Type Bit mask To bind the protected application to a specific dongle parameter you should select a certain flag and read the data from the memory of the don gle attached to the computer ([Read values from the dongle] button), or enter the data to the input field if another dongle is being used.
Encrypt Dongle Access Codes

Encryption of dongle access codes is recommended in order to increase protection strength. The following encryption modes are available: Not encoded access codes are not encrypted Random password codes are encrypted using the password created by the generator User-defined password codes are encrypted using the function which depends on the password specified by the user. The password is entered in the input field, which becomes available only in this mode. Editor of LNG Files Editor of Language Description Files (hereinafter referred to as LNG files) is called by clicking on the button in the Programming language group, Generation tab. Editor of LNG files has been designed to create and edit files that contain descriptions of programming languages. An LNG file can be defined in the following way. This is a file containing description of elementary language structures (tags) put into the generated source code, as well as of specific language features. The editor interface comprises two tabs containing controls. Besides, at the bottom of the window there are four buttons available, whose purpose can be guessed from their names: [Save as], [Save], [Close], [Help].
160
Language Properties Located under the Language properties tab are controls that will help you to make changes to the LNG file when creating your own description files. Each control in the tab has a corresponding option of LNG file. It should be remembered that there are preset default options available for LNG files of main programming languages that are best to be left un changed. It is recommended to create new LNG files on the base of exist ing descriptions of similar programming languages. A set of options will depend on the language specifics. The Programming language name field (Language_Description op tion) is used to enter and display the name of the programming language and development environment where the source code will be generated. The Main function name field (MAIN_FUNC_NAME option) stores the name of the main function of a respective language. Some languages impose restrictions on the name of the main function of the program, for example, C (C++) main() or WinMain(), while in FoxPro the main function should have the same name as the file in which it is saved.
Figure 7. Language properties tab of the LNG files editor.

Incorrect prefix characters field (BADMODNAMPREF option) con
tains characters that cannot be used as prefixes in this particular language (see the Module names prefix field under the Generation tab).
161
Users Manual
Programming language files extension field (LanguageType option)
contains extension that is assigned to the source code files in this particu lar programming language. Project file extension field (PrjExtension option): the project file is cre ated for compilation of the generated file. The project includes operation system commands. By default, BAT extension is assigned to the project files and PRJ extension to Clarion projects. Number of operators per string field (OpersPerString) defines the maximum possible number of operators in a string for the generated source file. If the parameter has not been declared or if it equals to 0, then the string length will not be restricted.
Call timer-based random number generation function with one parameter flag (NumParTmrRndGen option indicates that in pro
gramming languages such as C and ++, the function should be called with one parameter. This is not applicable to other languages.
Arrays
Arrays group describes array features of your chosen programming lan
guage.
Start array indexation from zero (ZeroIndex option): if this flag is set, it means that this programming language starts counting array elements from zero. FoxPro and Visual Basic languages do not provide full support of this option, while Pascal and Delphi do not support it in variables and constants of string type. Locate array in the memory discretely (ArrayPlacement option): if this flag is set, it means that array elements are not located one after an other in adjacent memory sections (applicable to FoxPro and Visual Basic languages). Passing arrays to functions as arguments (PntArrElem option): if this flag is set, it means that in this language the array can be passed to the function as an argument (for example, FoxPro does not support this op tion directly). Possible initialization during description (PrintArrayAsTab option): if this flag is set, it points that this language supports initialization of arrays during declaration.
More
Differences between data types char and byte (DifByteChar op
tion): if this flag is set, it means that such difference does exist in this lan guage (applicable to Pascal and Delphi). Indents in source code are allowed (AutoIndent option). This flag organizes the structure of the text of the generated function making it more convenient to read. Some languages, such as Fortran, do not allow using indents.
162
Print function header under all data (PrFnHdBelowData option). This flag manages printing of the functions header during generation of the code fragment. This flag must be used when the particular develop ment tool does not support interleaving of code and data (for example As sembler). Compiler directives in comments (CommentPrintingDisable option). The flag is set for those programming languages in which the compiler di rectives are arranged as comments (Delphi, FoxPro, Pascal).
Elementary Constructions The Elementary constructions tab contains a pull down menu, from which you choose the required tag, and an edit window for displaying and editing the tag body. LNG File LNG file lays basis for creating a source code using the Generator. In fact, it presents a formal description of a programming language. Any LNG file contains the following data types: options, comments and tags. Warning
For the operation of the Generator its version should be the same as of the LNG-file. Information on the version of the Generator is stored in SRCGEN.CFG configuration file; also in the LNG-file there is VersionOfLngFile field, which is checked during the reading of the file. To achieve a consistency between the versions, the number, which describes VersionOfLngFile, should be divided by the constant 100.
Example
LNG-file for Version SRCGEN 2.0: VersionOfLngFile = 200
Options
Options header is separated into the section called [Options]. The ap proach to writing LNG file options is the same as in INI files. Option types are divided into numerical (values 1 and 0) and character. All changeable options are listed and described above (see Language Properties section). LanguageType and FLAGS options are not subject to changes. The former is used to generate certain system settings of the pro gram. It is of a character type. Like DefExtension option, it contains ex tension of programming language file names in upper case strictly. FLAGS option indicates availability of a certain tag in the LNG file. This option is used by the LNG files editor during tags removal/adding.
163
Users Manual
Figure 8. Elementary constructions tab of the LNG files editor
Comments
Comments standing before the Options section ([Options]) are marked by # prefix, and after the beginning of the Options section by ; prefix. Comments are marked in tags in the same way as in a programming lan guage and can be located in any part of the tag, except parameters.
Tags (Elementary Language Structures)

Each tag consists of three parts: Header. The header contains the name of the tag. The header is placed in square brackets, no spaces. During editing the header is placed onto a separate line. Tag body. A tag body is a set of language expressions (lexical elements), which executes an operation defined by the tag. In the absence of a finished set of lexical elements for a specific case, this set can be arranged as an individual procedure and then placed in the header of the LNG file (into the PROGRAM_STRUCTURE tag be fore the program code). This procedure call should be placed into the body of the required tag. Parameters. Parameters have <Params> header specified by a separate line and placed in angle brackets with no spaces. In the absence of tag pa rameters, you can omit the header. Each parameter in the tag body is marked by % symbols, no spaces. For example, the MOV_ADD tag designed for the C language can look as fol lows:
164
Chapter 8. Guardant API [MOV_ADD] %SUMMA% = %FIRST% + %SECOND%; <Params> SUMMA FIRST SECOND
Apart from mandatory parameters, the tags can also have the following parameters (for the mandatory parameters see the Tag Table). The first four parameters are used only in case indents are enabled (AutoIndent op tion): AddLevelAfter Increases the indent after the body of the tag be ing printed. This parameter should be indicated at the end of the tag arguments list. AddLevelBefore Increases the indent before printing the tag body. This parameter should be indicated at the end of the tag arguments list. SubLevelAfter Decreases the indent after the body of the tag be ing printed. This parameter should be indicated at the end of the tag arguments list. SubLevelBefore Decreases indent before printing the body of the tag to the source code (AutoIndent option). This parameter should be indicated at the end of the tag arguments list. StopUniqueName Used in assembler LNG files to set the end of the label area during generation of jumps and cycle conditions. UniqueLabelName Used in assembler LNG files to generate a unique label name. For example, during prepara tion of a cycle on assembler language the follow ing two labels will be generated (in case the mod ule name prefix is m1_): m1_10 for the cycle beginning, and m1_10_endfor for the cycle end. ELEMENT_LIST Used to print elements of line arrays in Pascal and Delphi. VARIABLES Reports to the generator about the moment of printing of data section CONSTANTS Points to the section in the program structure where constants are described. PROGRAM_BODY Reports to the generator about the moment of printing of a code section. SingleLineOperator Printing of a tag in one line.
165
Users Manual
Each of these parameters is marked in the tag body by % symbols, no spaces. It is not recommended to use these parameters in other tags or languages. Important
VARIABLES and PROGRAM_BODY parameters are used only PROGRAM_STRUCTURE tag when a complete program is being generated. in the
Tag Types
Tags can be of the following types: Calculating tags perform some arithmetical operations and returning a result to a certain variable accordingly. For example, MOV_ADD tag adds up two variables and returns the result to a third variable. Syntactical tags are basic lexical elements of a programming language. For example, ADDRESS tag is a lexical element that specifies address of an operand. Nested tags can be inserted into one another. Lexical analyzer is capable of analyzing such expressions. When the analyzer encounters inside the tag body a construction enclosed in % symbols, it identifies its type and looks for parameters. In case the search is successful, the structure is printed applying macro substitution. The level of substitutions nesting is 128. Calling the tag nested into another one:
%TAG_NAME%(Parameters, ...)
Let us take LNG file for 16 bit assembler as an example. It should be noted that parameters of the nested tag should be ex plicitly specified, i.e., they should be identical to the parameters of the parent tag, or should be specified using immediate values. The analyzer does not examine the correctness of tag nesting. Example 1
[ARRELPUT_BYADDRESS] mov bx, word ptr %INDEX% mov cl, 2 shl bx, cl add bx, offset %ARRAY_NAME% %MOV_DWORD_BYADDR% (%VAL%) mov [bx], ax mov [bx+2], dx <Params> ARRAY_NAME INDEX VAL
166
Predetermined tags Predefined tags can belong to one of two subtypes: path tags and calculating tags. Path tags (path substitution macros) are intended for definition paths to development tools (compilers, linkers etc.). These macros form the basis of DO_COMPILE and DO_RUN tags. %FN_GRDNT_DIR% returns the path to Guardant Developers kit home directory; no arguments. Example:
If Guardant Developers kit is installed to C:\GUARDANT folder the macro returns C:\GUARDANT string.
%FN_FULL_PATH% Example:
builds a full path from specified relative path and current path; 1 argument.
%FN_FULL_PATH%(..\LIB\NVSKEY32.DLL) returns C:\GUARDANT\API\STEALTH\LIB\NVSKEY32.DLL string, if current path is C:\GUARDANT\API\STEALTH\
%FN_MERGE% Example:
builds a full path from component parts: drive, path, file name and extension; 4 arguments
%FN_MERGE%(D, Path, FileName, Ext) returns D:\Path\FileName.Ext string
%FN_DRIVE% Example:
extracts drive name from the specified path; 1 argument.
%FN_DRIVE%(D:\Path\FileName.Ext) returns D string
%FN_PATH% Example:
extracts a path from the specified full path; 1 argument.
%FN_PATH%(D:\Path\FileName.Ext) returns Path string
% FN_NAME% Example:
extracts a file name without extension from the specified full path; 1 argument.
%FN_NAME%(D:\Path\FileName.Ext) returns FileName string
%FN_EXT% Example:
extracts a file extension from the specified full path; 1 argument.
%FN_EXT%(D:\Path\FileName.Ext) returns Ext string
%FN_CHGEXT%
assigns a new extension to the specified file; 2 arguments.
167
Users Manual
Example:
%FN_CHGEXT%(D:\Path\FileName.Ext, .NewExt) returns D:\Path\FileName.NewExt string
Names of path tags are marked by % symbols, no spaces. Parameters are enclosed to the brackets. If an interface variable is used as argument, it is marked by % symbols also. Paths may be specified directly, in this case a path string must be quoted.
All the paths are built and searched relatively to Guardant Developers kit home directory.
Example: Using of macros in LNG file for 16 Assembler (Guardant Stealth dongle). DO_COMPILE tag must contain following lines:
tasm.exe %SCG_szOutFileName% tlink.exe %FN_CHGEXT%(%SCG_szOutFileName%,.OBJ) %FN_GRDNT_DIR%()API\STEALTH\LIB\NVSKEY.OBJ where: tasm.exe Assembler translator; SCG_szOutFileName variable that contains name of file for output data; tlink.exe linker; %FN_CHGEXT%(%SCG_szOutFileName%,".OBJ") macro that changes the extension of source file ASM to OBJ; NVSKEY.OBJ library file to be linked with output data file; %FN_GRDNT_DIR%()\NVSKEY.OBJ macro that specify the path to the library.
Calculating tags:
HIWORD obtains the high word from a double word LOWORD obtains the low word from a double word HIBYTE obtains the high byte from a word LOBYTE obtains the low byte from a word Bodies of these tags are not indicated in the LNG file, they are processed exclusively by the lexical analyzer of the generator. Predetermined tags should be called as follows: Tag name enclosed in % symbols, no spaces, and the argument is en closed in brackets, for example, %HIWORD% (25). Calculating tags are applicable only to certain specified numerical oper ands. The analyzer is incapable of calculating the expression similar to %HIWORD%(offset m1_PrivRD), since the offset value of m1_PrivRD is not defined until the code is compiled. The LNG file for 16 bit assembler can be used as a sample of usage of predetermined tags.
168
Example:
[ARRAY_ELEM_PUT] mov bx, word ptr %INDEX% mov cx, %LOWORD% (%VAL%) mov di, %HIWORD% (%VAL%) mov ax, word ptr %SIZE% mul bx mov bx, ax add bx, offset %ARRAY_NAME% mov [bx], cx mov [bx+2], di <Params> ARRAY_NAME INDEX VAL SIZE
It should be noted that the ARRAY_ELEM_PUT tag is suitable only for assigning to an array element a value represented by a number, but not a variable. Predetermined tags can also be nested one within another. Permitted nesting level should be either 2 or less. Examples:
Path tags nesting: %FN_DRIVE%(%FN_GRDNT_DIR%)) This macro retrieves name of the drive where Guardant Developers kit is installed. If the Developers kit is installed to C:\GUARDANT\ the macro will return C:\. Calculating tags nesting: mov ax, %LOBYTE%(%HIWORD%(65536)) will be converted by the generator as follows mov ax, 1
For the convenience sake, tags in the LNG file are separated from each other by the following line: ## . When the LNG file editor is used, this line is inserted and removed automatically, whereas when you do the editing on your own the line should be inserted manually.
169
Users Manual
Tag Table
Tag name ADDRESS ADDRESS_ARRAY _OF_BYTE_IN_ARRAY _ELEMENT_OF _ADDRESS_CHAR_PUT ARR_EL_FROM_ARR Tag purpose qty Specifying operand address Assign byte array address to an element of the array with pointers to char Assign the value of one array element to the element of another array Assigning a value of array element to the variable Assigning a value to the array element Assign a variable value to an array element End symbol for array initialization Start symbol for array initialization Assigning a value of variable to the array element Description of the non-initialized byte Description of the initialized array of bytes Description of the non-initialized array of bytes Description of the initialized byte Byte initialization Transformation of the code into a symbol Calculation of the 256-bit hash function of the selected teable element 1 3 Mandatory parameters description VARIABLE arpchName, nIndex, arbyName
ARRAY_ELEM_GET ARRAY_ELEM_PUT ARRAY_ELEM_PUT _VARIABLE ARRAY_INIT_SYMBOL _CLOSE ARRAY_INIT_SYMBOL _OPEN ARRELPUT_BYADDRESS BYTE BYTE_ARRAY BYTE_ARRAY_NI BYTE_INIT BYTE_REINIT BYTE_TO_CHAR CALL_HASH256
4 4 4 1 1 3 1 2 3 2 2 2 7
RECIEVER_ARRAY_NAME, RECIEVER_INDEX, EMITTER_ARRAY_ NAME, EMITTER_INDEX RES, ARR_NAME, INDEX, ELEMENT SIZE ARR_NAME, INDEX, VAL, ELEMENT SIZE ARRAY_NAME, INDEX, dwVariable, SIZE SingleLineOperator SingleLineOperator ARRAY, INDEX, VAR_NAME VARIABLE ARRAY_NAME, SIZE ARRAY_NAME, SIZE, ELEMENT LIST VARIABLE, VALUE VARIABLE, VALUE byVal, SingleLineOperator dwId pData, dwDataSize, dwCRCTable, dwCRCRecord, dwCRCResult, dwRand, pRes RES, A1, A2, A3, A4 RES, A1, A2, A3 dwRes, nData, dwDataSize, dwOldCrc RES, A1, A2, A3 RES, A1, A2, A3, A4 dwRes, wDecodeType, pPassword, nData, dwDataSize RES, A1, A2, A3, A4 RES, A
CALL_NNKCODEINIT CALL_NNKCRC CALL_NNKCRC _STRING CALL_NNKCRCDW CALL_NNKENCODE CALL_NNKENCODE _STRING CALL_NNKENCODEDW CALL_NNKLOGIN
Calling nnkCodeInit function Calling nnkCRC function Alias of nnkCRC function call. Buffer address is indicated in the WORD variable. Alias of nnkCRC function call Calling nnkEnCode function Calling the nnkEnCode function. Buffer address is indicated in the WORD variable. Alias of nnkEnCode function call Calling nnkLogin function
5 4 4
4 5 5
5 2
170
Tag name CALL_NNKLOGOUT CALL_NNKDECODE CALL_NNKDECODE _STRING CALL_NNKDECODEDW CALL_NNKREAD CALL_NNKREADDW CALL_NNKSETMODE CALL_NNKTRANSFORM CALL_NNKWRITE CALL_NNKWRITEDW CALL_NSKCODEINIT CALL_NSKCRC CALL_NSKCRC _STRING CALL_NSKCRCDW CALL_NSKDECODE CALL_NSKDECODE _STRING CALL_NSKDECODEDW CALL_NSKENCODE CALL_NSKENCODE _STRING CALL_NSKENCODEDW CALL_NSKFINDFIRST CALL_NSKFINDNEXT CALL_NSKREAD CALL_NSKREADDW CALL_NSKSETMODE CALL_NSKTRANSFORM CALL_NSKWRITE CALL_NSKWRITEDW CALLFUNC
Tag purpose qty Calling nnkLogout function Calling nnkDeCode function Calling the nnkDeCode function. Buffer address is indicated in the WORD variable. Alias of nnkDeCode function call Calling nnkRead function Alias of nnkRead function call Calling nnkSetMode function Calling nnkTransform function Calling nnkWrite function Alias of nnkWrite function call Calling nskCodeInit function Calling nskCRC function Calling the nskCRC function. Buffer address is indicated in the WORD variable. Alias of nskCRC function call Calling nskDeCode function Calling the nskDeCode function. Buffer address is indicated in the WORD variable. Alias of nskDeCode function call Calling nskEnCode function Calling the nskEnCode function. Buffer address is indicated in the WORD variable. Alias of nskEnCode function call Calling nskFindFirst function Calling nskFindNext function Calling nskRead function Alias of nskRead function call Calling function nskSetMode Calling nskTransform function Calling nskWrite function Alias of nskWrite function call Structure of a function without parameters that does not return a value Structure of a function without arguments that returns an integer value Structure of a one-argument function that returns an integer value Structure of a two-argument function that returns an integer value 2 5 5
Mandatory parameters description RES, A RES, A1, A2, A3, A4 dwRes, wDecodeType, pPassword, nData, dwDataSize RES, A1, A2, A3, A4 RES, A1, A2, A3, A4 RES, A1, A2, A3, A4 A1,.., A7 RES, A1, A2, A3, A4 RES, A1, A2, A3, A4 RES, A1, A2, A3, A4 RES, A1, A2, A3, A4 RES, A1, A2, A3 dwRes, nData, dwDataSize, dwOldCrc RES, A1, A2, A3 RES, A1, A2, A3, A4 dwRes, wDecodeType, pPassword, nData, dwDataSize RES, A1, A2, A3, A4 RES, A1, A2, A3, A4 dwRes, wDecodeType, pPassword, nData, dwDataSize RES, A1, A2, A3, A4 RES, A1, A2 RES, A1 RES, A1, A2, A3, A4 RES, A1, A2, A3, A4 A1, A2, , A7 RES, A1, A2, A3, A4 RES, A1, A2, A3, A4 RES, A1, A2, A3, A4 FUNCTION
5 5 5 7 5 5 5 5 4 4
4 5 5
5 5 5
5 3 2 5 5 7 5 5 5 1
CALLFUNC0
RES = FUNCTION
CALLFUNC1
RES = FUNCTION (ARG)
CALLFUNC2
RES = FUNCTION (ARG1, ARG2)
171
Users Manual
Tag name CALLFUNC3
Tag purpose qty Structure of a three-argument function that returns an integer value Structure of a four-argument function that returns an integer value Structure of a five-argument function that returns an integer value Structure of a six-argument function that returns an integer value Structure of a seven-argument function that does not return a value Structure of an eight-argument function which returns a value Structure of a ten-argument function which returns a value Search for the dongle of specified type Description of the non-initialized fixed-size array of characters Definition of an initialized array of characters Obtaining a value of the element of the array of characters Assigning a value to an element of the array of characters Description of uninitialized array of pointers to they char type (symbol) Operation of summation of two symbols (char) Header of the code section A structure that specifies line comment Comparing a variable of DWORD type and a constant Description of three-operand condition Definition of a constant Assigns the value of the table element to a local variable Converting an array of double words into a string Header of the data section Build the project Run application after build 4
Mandatory parameters description RES = FUNCTION (ARG1,..,ARG3) RES = FUNCTION (ARG1,..,ARG4) RES = FUNCTION (ARG1,..,ARG5) RES = FUNCTION (ARG1,..,ARG6) FUNCTION (ARG1,..,ARG7) RES = FUNCTION, ARG1,, ARG7 RES = FUNCTION, ARGUMENTS, 1..10 RES, 1, .., 10 ARRAY_NAME, SIZE ARRAY_NAME, SIZE, ELEMENT LIST RES, ARR_NAME, INDEX ARR_NAME, INDEX, VALUE ARRAY_NAME, SIZE
CALLFUNC4
CALLFUNC5
CALLFUNC6
CALLFUNC7
CALLFUNC8 CALLFUNC10 CALL_SETDONGLES CHAR_ARRAY_NI CHAR_ARRAY CHAR_ARRAY_GET CHAR_ARRAY_PUT CHAR_POINTER _ARRAY_NI CHAR_SUMMATION _SYMBOL CODE_SECTION COMMENT COMPARE_CONST COMPOSITE_IF CONSTANT COPY_TABLE _ELEMENT CVTLNGSTR
9 12 11 2 3 3 3 2
1 1 3 2 3 -
SingleLineOperator STRING , , NAME, VALUE A, B, C The function to be designed by the user as required -
DATA_SECTION DO_COMPILE DO_RUN
172
Tag name DWORD DWORD_ARRAY DWORD_2D_ARRAY DWORD_ARRAY_2D _ELEM_GET DWORD_ARRAY _2D_NI DWORD_ARRAY_2D _SUB_ARRAY_GET DWORD_ARRAY_2D _ELEM_PUT DWORD_ARRAY_NI DWORD_INIT DWORD_PTR DWORD_PTR_ARRAY END_CODE_STRING END_CODE_SECT END_DATA_SECT END_FUNCTION0 END_FUNCTION1 ERROR_PRINT EXIT_FUNCTION0 EXIT_FUNCTION1 EXIT_PROGRAM FOR FOREND FUNC_HEADER GOTO IF_NOTEQU IFEND IF_EQU MOV MOV_ADD
Tag purpose qty Description of a non-initialized double word Description of an initialized array of double words Description of the initialized 2D array of double words Obtain the value of the element of 2D array Description of the uninitialized 2D array of double words Copy a string from the 2D array to the 1D array Assign a value to the element of the 2D array Description of a non-initialized array of double words Description of an initialized double word Pointer to a double word Array of pointers to the lists of double words End of a string with the source code End of code section End of data section Standard structure of function termination Two-parameter structure of function termination Printing an error message Standard structure of function termination Two-parameter structure of function termination Termination of the program with a return code Header of three-operand cycle Structure declaring the end of cycle Function header structure Jump to the address specified by the label The structure checking inequality of operands The structure ending the comparison block Condition of equality of the operands Assigning the value of one variable to another variable Returns the sum of operands 1 3 4 4 3 4 4 2 2 1 2 1 1 2 2 1 2 1 3 1 1 2 2 2 3
Mandatory parameters description VARIABLE ARRAY_NAME, SIZE, ELEMENT LIST NAME, SIZE1, SIZE2, ElementList dwRes, ardwName, nX, nY NAME, SIZE1, SIZE2 A, B, C, dwNewValue, ardwName, nX, nY ARRAY_NAME, SIZE VARIABLE, VALUE VARIABLE ARRAY_NAME, SIZE SingleLineOperator RET_CODE (return RET_CODE) FUNCTION_NAME= RET_CODE DESCRIPTION, VALUE RET_CODE (return RET_CODE) FUNCTION_NAME =RET_CODE RET_CODE Count, Start, End FUNCTION_NAME LABEL If (A!=B) == MOV A, B A=B+C
173
Users Manual
Tag name MOV_ADD_STRING MOV_DDI_ON_ADDR MOV_DDI_ON_VALUE MOV_DIV MOV_DWORD _BYADDR
Tag purpose qty Result of concatenation of strings Assigning a value to a variable of DWORD type Assigns the constant value to a variable of DWORD type Returns operands quotient Returns value of a double word from specified address to DX: AX registers. Valid only in 16-bit Assembler language Returns value of a double word to DX:AX registers. Valid only in 16-bit Assembler language Returns a signed residual of operands division Returns a result of operands multiplication Returns a bitwise "OR" of operands Returns a bitwise cyclic left shift of operands Returns a bitwise cyclic right shift of operands Returns a bitwise left shift of operands Returns a bitwise right shift of operands Assigns a value to the string pointer Initializes a string with a constant value Returns a remainder after operands subtraction Returns bitwise exclusive OR of operands Multi-line comment Returns an unsigned residual of operands division Separator between operators within one source code string Message output Output of source text Prints a value with description Program structure Pushes an intersegment address of the operand into the stack Standard random number generator Defines a string 3 2 2 3 1
Mandatory parameters description "MaLo"="Ma"+"Lo" DWORD dwName=Value dwName, const A=B/C Value
MOV_DWORD_BYVAL
Value
MOV_MOD MOV_MUL MOV_OR MOV_ROL MOV_ROR MOV_SHL MOV_SHR MOV_STRING MOV_STRING_CONST MOV_SUB MOV_XOR MULTISTRIGCOMMENT NSTD_MOD OPER_DELIMITER PRINT_MESSAGE PRINT_SRC_TXT _DATA PRINT_VAL PROGRAM _STRUCTURE PUSH_FAR_ADDRESS RANDOM STRING
3 3 3 3 3 3 3 2 2 3 3 1 3 1 1 4 2 1 1
A=B%C A=B*C A=B|C A = B rol C A = B ror C A = B << C A = B >> C A, B strName, strConst A=BC A=B^C STRING =% SingleLineOperator STRING A, B, C, D DESCRIPTION, VALUE -
VARIABLE
174
Tag name STRING_ARRAY STRING_ARRAY_NI STRING_FIRST _ELEMENT STRING_TO_2D _DWORD_ARRAY STRING_TO_DWORD _ARRAY TIMER_RAND TYPE_BYTE TYPE_CHAR TYPE_DWORD TYPE_WORD VALUE_ADDRESS_ IN_ARRAY_ELEM_PUT VERSION WORD WORD_INIT WORD_REINIT
Tag purpose qty String array initialized during the description Description of the uninitialized string array Obtain a first element of the string Convert the string into a 2D array of long type Conversion of the string into an array of long type Timer-based random number generator Converts the data type to BYTE Converts data type to CHAR Converts data type to DWORD Converts data type to WORD Assign the address value of the variable to an element of the array LNG file version Defines a non-initialized word Defines an initialized word Initializes word 3 2 1 4 3 1 1 1 1 4
Mandatory parameters description ARRAY_NAME, SIZE, ElementList ARRAY_NAME, SIZE strName A, B, C, D A, B, C VARIABLE VARIABLE VARIABLE VARIABLE arName, nIndex, Value, ValueSize VARIABLE VARIABLE, VALUE VARIABLE, VALUE
1 2 2
175
Users Manual
Variables of LNG file Two types of variables can be found in LNG files: variables that are used in the source code of the generated module interface variables that are not used directly in the source code of the generated module, but can affect process of generation of the source code Variables of the Generated Module Names of variables excluding module prefixes are presented in compli ance with Hungarian Notation.
Variable Name
PrivRD dwTmp0, dwTmp1, dwTmp2, dwTmp3, dwRes, i nNum, nStrtNum nRet dwPassword [8]
Variable Description
Private read code. Only this access code of the dongle is used during generation. Temporary variables of DWORD type that contain calculation results Variables of INT type to store the index of the chosen array element A variable of INT type to store API function return code An array containing a password for decoding. It is filled during execution of the generated function. The size of the element is 4 bytes (32 bytes constitutes a string equivalent of the array) A string containing a decoding password converted from the array of 4byte numbers into character representation, or a string. It is used in FoxPro and Visual Basic, where dongles function prototypes operate with string variables. Arrays of source tables which originally contain a decoding password, where ## is a table number. The size of the element is 4 bytes. Array of complements table. The dimension is the same as of adwSrc Array of variables of a BYTE type containing a password for decoding an array of queries to the dongle. It is used when the table encoding option is activated. Array of variables of a BYTE type containing a password for decoding a dongle access code. It is used when the dongle code encoding option is activated. Character string obtained as a result of decoding main data
szPassword
adwSrc## adwAdd sTabPass
sCodePass
cbEncData
176
Interface Variables Each interface element of the Generator has matching variable that is processed by lexical analyzer. These variables are used in conditional statements of LNG file. Variable types are given in accordance with Hungarian Notation, i.e., b BOOL, by BYTE, w WORD, dw DWORD, sz STRING. The lines separated by commas, which are enclosed in square brackets and fol low a variable name (LNG file variable column) present a list of allowed values of this variable.
Interface Element Name Generation Tab Source code format Prefix and comments Form of a code being generated: complete program or a fragment Insertion of comments in the source code Prefix of module variable names Initialization of arrays upon declaration Name of programming language Name of file to be created Open with Build project after generation Source text Execute application after building Name of command file for compilation Name of command file for execution of compiled application Name of data file to be encoded Data to be encoded Reading the file as binary or text file, or an array of words, or an array of double words Encrypting decoded data Transforms Tab Algorithm Number of the dongle algorithm Dimensions of the dongle algorithm Constant function length Transform function Length of function being generated (number of operations performed by the function during one cycle) Number of source tables (number of function cycles) Size of each table (in double words) SCG_byAlgoNum SCG_byAlgoQuerySize SCG_bConstFuncLenFlag SCG_byFunctionLenght SCG_bySourceTablesNumber SCG_bySourceTablesSize SCG_szProgrammingLanguage SCG_szOutFileName SCG_bLoadTo SCG_bCompile SCG_bExecute SCG_szDoCompileFileName SCG_szDoExecuteFileName EDF_szInFileName %EDF_BIN%, %EDF_TXT%, %EDF_WRD%, %EDF_DWRD% EDF_bEncryptDecryptedDataFlag SCG_bCompleteModule SCG_bInsertCommentsFlag SCG_szModuleVariablesPrefix Purpose LNG File Variable
Programming language
Tables
177
Users Manual
Interface Element Name Tables encoding More tab CRC of the dongle access codes CRC of source tables Validate CRC of complements tables CRC of the result of each step CRC of decoded data Printing an error message Error handling Responsive actions to an error (exit the program, jump to a label, user expression) Parameter of an error handler Call nnkLogout on errors Method of obtaining a random number (predefined function of programming language, system time, dongle algorithm of Random type, user expression) Number of algorithm used to obtain a random number User expressions used to obtain a random number Display passwords Dongle tab Enables program number check Value of the program number parameter Enables version check Value of the version parameter Enables serial number check Search parameters Value of the serial number parameter Enables ID check Value of the ID parameter Enables dongle type check Value of the dongle type parameter Enables mask check Value of the mask parameter Displaying of a decoding password Displaying of a password being decoded Purpose Encoding of source tables
LNG File Variable SCG_bEncryptSourceTables
CRC_bCheckDongleCodes CRC_bCheckSrcTables CRC_bCheckAddTables CRC_bCheckAfterEachStep CRC_bCheckDecryptedData ERR_bPrintErrorMsgFlag %ERR_EXIT%, %ERR_GOTO%, %ERR_USER% ERR_szParam SCG_bForceLogout %RND_STD%, %RND_TIME%, %RND_DONGLE%, %RND_USER%
Random values
RND_byRndAlgoNum RND_szUserMethod RND_bShowDecryptingPassword RND_bShowDecryptedPassword
DSP_bCheckProgramNumber DSP_byProgramNumber DSP_bCheckVer DSP_byVer DSP_bCheckSerNum DSP_wSerNum DSP_bCheckID DSP_dwID DSP_bCheckType DSP_byType DSP_bCheckBitMask DSP_byBitMask
178
Interface Element Name Dongle type Encrypt dongle access codes Purpose Guardant Fudus Guardant Stealth Guardant Net Enables encryption of dongle access codes
LNG File Variable DUT_bFidus DUT_bStealth DUT_bNet SCG_bEncryptAccessCodes
LNG files editor. Language properties tab Programming language name Main module/function name Incorrect prefix characters Programming language files extension Project file extension Number of operators per string Call timer-based random number generation function with one parameter Array starting elements index is zero Locate arrays in the memory discretely Arrays Passing arrays to functions as arguments Possibility to initialize arrays during declaration Differences between data types char and byte Indents in source code are allowed More Printing of function header under all data (depending on the chosen programming language) Compiler directives in comments LNG_szProgrammingLanguage LNG_MainFunctionName LNG_szIncorectPrefixChar LNG_szFileExt LNG_szPrjFileExtention LNG_dwOperatorsPerString LNG_byTimerRandomFuncParmsNumber ARR_bZeroIndex ARR_bDiscretArrangement ARR_bPassArrayPointer ARR_bInitByAssigment ADV_bByteIsNotChar ADV_bAutoIndent ADV_bFunctionHeaderBelowData ADV_bDisableCommentsPrint
179
Users Manual
Conditional Statements Conditional statements (1 3) and constants (4 5) that are used by the lexical analyzer for processing of interface variables: 1. %IF%(expression condition expression), calculation of conditional expressions as in the C language. 2. %ELSE% 3. %ENDIF% 4. %T% = true (equivalent to expression %TRUE% = true) 5. %F% = false (equivalent to expression %FALSE% = false) A list of supported conditions: ==; !=; >; <; !; ||; &&; >=; <= and (). Example
%IF%(%bFullSrc% != %F% || (%EDF_szReadFileAs%==DWRD)) char *dwSome= { #include "%EDF_szReadFileAs%" }; %ENDIF%
No precedence is set in the order of performing operations in expressions. For example, the next two expressions will be perceived differently by the lexical analyzer:
%IF%(%SCG_bCompleteModule% != %F% && %SCG_bInsertCommentsFlag% !=%T%)
and
%IF%((%SCG_bCompleteModule% !=%F%) && (%SCG_bInsertCommentsFlag% !=%T%))
Therefore, the precedence in calculating compound conditions should be set using brackets.
180
Chapter 9. Programming Guardant Dongles
Chapter 9 Programming Guardant Dongles

In the previous chapters of the Manual you have been introduced to the structure of Stealth dongles and to all methods of protection of your appli cations. By now you have become aware of all Guardant protection capa bilities, including use of the Auto Protection Wizard for setting up auto matic protection and implementation of API functions for strengthening of protection. You also know what is the purpose of Stealth dongles hard ware algorithms of, how they work and why they must be used. There still remains one more important issue to cover: how to program Guardant Stealth, Guardant Fidus and Guardant Net dongles and how to achieve the required functionality. This is what the present Chapter is about. This Chapter also discusses use of Stealth dongles programming utilities, including creation and editing of the required memory fields with the help of these utilities. You will learn to design hardware algorithms with the features you need and use them for converting your data, implement read and write hardware locks and carry out all kinds of remote programming of the dongles memory. Important
Please pay special attention to how data conversion is completed using different types of algorithms, and how memory remote programming function is implemented.
NSKUTIL. Main Programming Utility

NSKUTIL is a utility that allows you to execute all types of programming of Stealth dongles, including programming the applications license term. NSKUTIL is the only utility you will need to work with the dongles memory. NSKUTIL can be used for the following tasks: Programming the dongles memory. You can read the contents of the don gles memory, create new fields and hardware algorithms in the memory, edit field values, delete fields and algorithms, implement read/write memory hardware locks and carry out remote programming of the dongle.
181
Users Manual
Preparing for application protection. You can get the ID value of any par ticular dongle, create arrays with hardware algorithms responses so that they can be used in the protected applications, encode data using reversi ble conversion method, carry out debugging and troubleshooting of appli cation protection by checking the results of calling API functions. Important
Before running the utility, you have to attach any of the supplied Guardant Stealth, Guardant Fidus or Guardant Net dongles to the computer.
NSKUTIL Main Window After the utility has been started, its main window will appear on the screen:
Figure 9. NSKUTIL main window. The left part of the main window contains a list of general purpose fields: program number, version, serial number, executions (GP) or license term counter (counter #1), current license limit of Guardant Net (counter #2) and index. You cannot delete these fields since they are used by the auto matic protection. The right part of the main window displays the contents of user fields area. This memory area may contain hardware algorithms descriptors and any data that you wish to use for the protection. Memory area is divided into fields, and a list of those is displayed in this part of the main window.
182
Using the toolbar in the upper part of the window, you can execute all of the available actions: save the structure and values of the memory fields in a special file read and write the contents of the dongles memory get dongles ID value prepare data for remote programming query hardware algorithms implement memory read and write locks invoke online help, etc. Some of these actions can also be executed from the menu located at the top of the window. Also, from this part of the window you may select the base of number system to display the addresses, sizes and values of the memory fields. You can deactivate the toolbar as necessary by unchecking View|Tool Bar menu item. The status bar of the main window displays reference data, such as: Public code of the dongle in the numerical and character form; available mem ory size; size of the memory area where read and write locks are imple mented; type of the loaded mask file. You can disable the status bar as necessary by unchecking the View|Status Bar menu item. You can switch between controls and fields using mouse or <Tab> key (reverse switch using <Shift+Tab>). Using Mask The number, type and values of all memory fields of the dongle form the so called mask (it is not the same as bit mask field which belongs to gen eral purpose fields). Usage of mask makes operations with the dongles memory more demonstrative and convenient: you will always be able to identify into how many fields the dongles memory is split, what kind of information is stored in this or that field, etc. Besides, you will not have to start you work anew every time: the structure of the dongles memory can be stored in a special mask file with NSD extension. Masks for Guardant Stealth/Net and Fidus dongles are to some extent different, but they can be converted into one another and vice versa. It is important for you to ensure that the dongle and mask types match each other. Creating a New Mask
Menu Hotkey File|New <Ctrl+N>
By default, the mask file is created automatically, depending on the type of the dongle, which is used at the first start of NSKUTIL. Sometimes, it is necessary to create mask files, for example, when using other types of dongles or if a mask is required, in which the fields and their default values are entered.
183
Users Manual
To create a new mask, choose a menu item or press a combination of dongles indicated above. During creation of a new mask NSKUTIL prompts to select the type of the dongle for which it will be created. The new file is assigned default.nsd name, which can be changed at a later stage. Loading the Mask from the File
Toolbar Menu Hotkey File|Open <Ctrl+O>
To be able to use a previously created mask it has to be loaded from the mask file. To do this, click on a button on the toolbar or choose menu item, or press a combination of dongles indicated above. In the displayed window, you can choose the required mask file from the list of available files. After loading the mask, NSKUTIL will display a list of memory fields and the values entered into them at the moment of creation (or last modification) of this mask file. To enter actual values from the attached dongle into the mask fields, you should perform reading of the dongle. Important
During running of NSKUTIL the mask that had been previously used (or DEFAULT mask) is automatically loaded, and data read from the dongle are displayed. The mask name is displayed in the title bar of the main window.
After completing its running session the utility will ask you to confirm if the current mask is to be saved in the file in case changes had been made to this mask. To automate this procedure check the File|Autosave on exit menu item. The mask will be saved automatically in the currently ac tive file when exiting NSKUTIL. Saving Mask to File
Toolbar Menu Hotkey File|Save <Ctrl+S>
The currently active mask file is saved. Saving Mask to a New File
Menu File|Save As
In the displayed window you can specify the name of the file in which the current mask will be saved (the file should have NSD extension).
184
Converting a Mask
Menu File|Convert Into
A corresponding mask should be used for each type of Stealth dongles. It may happen that you will need to transfer information from the mask used for one type of dongles to a mask used for another type of dongles. Of course, due to the differences between dongle types, not all information can be transferred into another mask. In this case new fields with default values can be added to the new mask. Editing General purpose Fields General purpose fields are intensively used by the automatic protection, but you may also use them with the help of API functions. The values of these fields are displayed in the left part of NSKUTIL main window. To the left of the value of each field its start UAM address in the dongle is displayed. You can edit the values of any of these fields by placing a cursor in the appropriate input field and specifying a new value, yet you cannot delete these fields from the dongles memory. Programming the Applications License Term NSKUTIL allows you to enter into the dongle memory (GP counter #1 field) the license term of applications protected in the limited time mode. It is convenient to make the counter indicate the time in days, hours and minutes, for example 40d15h49m. To do this you should check the View|Show GP as time menu item. Then the required data are entered into the counter field and with Dongle|Write command, they are stored in the memory of the dongle. The maximum timer value is limited by the size of the GP field (2 bytes) and it equals 227d13h15m. Editing User Data Area You may use this memory area as you deem appropriate by calling API functions. For your convenience, you should first create the required fields in this area to store various data in the future. Fields created in the user data area are displayed in the form of a list in the right part of NSKUTIL main window.
185
Users Manual
The following data are indicated for each field: Address the UAM address of the field. A pictographic icon denoting the type of the field is displayed to the left of the address, while hardware locks, which are set on this field, are displayed to the right:
r rw wrw r-w the whole field is read-protected part of the field is read-protected the whole field is write-protected part of the field is write-protected the whole field is read- and write-protected part of the field is read- and write-protected
These symbols will visually guide you through the memory structure. Size length of the field in bytes. Type type of the field (i.e., the type of information to be contained in the field). There are the following field types available: Integer a 1, 2 or 4 byte field that contains an integer with a sign. Unsigned (unsigned integer) a 1, 2 or 4 byte field that contains an integer without a sign. Counter a 1, 2 or 4 byte field that contains an unsigned integer. The value is automatically incremented by 1 whenever the mask fields are written into the dongles memory. String a field that contains a sequence of characters (letters or numbers). You can specify any length of the String; it is limited only by the memory available in the dongle. Dump a field that contains a sequence of any ASCII symbols. The length of Dump string is also limited only by the available memory. Algorithm a field that contains a hardware algorithms descriptor. The length of the Algorithm field cannot exceed the maximum length of the algorithms descriptor. Name name of the field. You may assign any meanigful names to the fields. Value/Algorithm type value (i.e., the contents) of the field, or hardware algorithm type: Random, Fast or Simple. Important
All dongles offered for sale contain descriptors of default hardware algorithms (four fields of Algorithm type with the following names: AutoProtect, Fast, Random and Demo).
With NSKUTIL you can change the contents of the fields in the user data area, add new fields and remove unwanted ones.
186
Adding a New Field

Toolbar Menu Hotdongle Edit|Add <Ins>
A new field is added following the highlighted field in the list. If you click on any of the above controls the following window will appear.
Figure 10. NSKUTIL window that displays adding of a new field. Here you should select the type of a field to be created. If you choose any type except for Algorithm, you will be asked to specify the size of this field. You should bear in mind that access to the fields of even numbered length is faster. After you have chosen a field type, a window will appear where you can edit the field.
Figure 11. NSKUTIL window for editing a numeric field. In the window for editing numeric fields and strings you should enter the name of the new field and its value (i.e., the field contents). In case the data you have entered are correct, the new field will be added to the list.
187
Users Manual
Figure 12. NSKUTIL window for editing a field of Dump type. To edit the fields of Dump type a special hexadecimal editor is used. It allows you to enter information in hexadecimal codes, save it in files and load the dumps from the files with DMP extension. It is also used for ed iting algorithms determinants. Important
When creating new fields, note that no fields of other type can be inserted between the fields of Algorithm type. Fields that contain algorithm descriptors should be stored in the memory before any other data, because these fields are always read and write locked (this was explained in greater detail when the dongle structure was described in Chapter 5 of this Manual).
Creating a New Algorithm To create a new algorithm its descriptor must be written into the dongle. NSKUTIL utility will allow you to do this easily and fast. To create a new algorithm you should add a new field of Algorithm type. From the displayed window (see Figure 10) select the type: Algorithm. After that a window will appear in which you will need to select the type of the algorithm.
Figure 13. NSKUTIL window for creating a new algorithm.
188
If you have chosen algorithm of Simple type, then you will be prompted to specify the length of the algorithms determinant. Simple is the only algorithm type for which you can specify all descriptor components. Other types of algorithms have fixed sets of properties and lengths of de terminants (see Types of Hardware Algorithms for specific features of each algorithm type). After you have chosen the algorithm type, the following window will ap pear.
Figure 14. NSKUTIL window for editing the algorithm. In this window you should specify the name (random name), as well as the properties, size of the query and a determinant of the new algorithm. To change the determinant, invoke determinant editor by clicking on the [Determinant] button. By default, random numbers are written into the determinant. When editing the determinant you should follow the in structions described in The Importance of the Algorithms Determinant. When creating a new algorithm, NSKUTIL automatically adjusts the size of the memory area on which hardware locks will be set in order to read/write protect the descriptor of the new algorithm. After you write mask values to the dongle, your newly created hardware algorithm will be ready for use. Warning
Since an algorithm is started by its sequential number, it is not recommended that new algorithms be inserted between the existing ones; this will lead to changes in algorithms numbers, which follow the created algorithm in the memory.
Creating a License Table To set up a license table you must create a special field of the License ta ble. You can add the field using the Edit|Add menu item. In the appeared window (see Fig. 10) select the type of the field (License table) and specify the size of the table cell either 1 or 2 bytes.
189
Users Manual
The license limit in a protected application module depends on the size of a cell. If the size of the cell is 1 byte, the available number of licenses per each module will be limited to a maximum of 254; if the size of a cell is 2 bytes, the number of licenses per module will be limited to a maximum of 65534. If the values are 255 and 65535, the license resource in the module becomes unlimited.
Figure 15. Window for editing the license table In the appeared license table window you can indicate the vendors name and the program name. Then you should specify the number of modules of the application to be protected and their parameters use [Add] button.
Figure 16. Window for editing the modules parameters In the Modules parameters window you should specify the name and the license limit for the module. These parameters will be displayed in the license table window. To remove a module or to edit its parameters you can use respective but tons in the license table window. A number of modules in the license table can be up to 127.
190
Then you should export the data from the license table, as well as addi tional dongle search parameters, to the file in which Guardant Net server settings are stored (NNKSRV32.INI) for this purpose use the [Export] button.
Figure 17. Window for exporting parameters to the INI file Dongle search parameters are defined in the Export to the INI file win dow. Using these parameters the Guardant Net server assigns description to a dongle and screens an additional text information about the owner of the dongle code, application name and its modules. To define search parameters you must set a flag next to the required item. The parameter values can be obtained from the mask file or directly from the dongle memory (use appropriate buttons in the Take values from section). Dongle search parameters are arranged in the window according to their priority, in the descending order. Thus the dongle ID has the highest pri ority while the bit mask, the lowest priority. The value of the higher priority parameter is higher than the aggregate value of all lower priority parameters. So, if the dongles ID has been specified among other search parameters, the server will allocate the description only to a particular dongle with the indicated ID, etc. As soon as you press the [Save] button, the dongles description will be exported to the NNKSRV32.INI file which contains Guardant Net server settings. The Review the generated file flag, if set, allows you to review the INI file where the dongles description is stored (section of [KEY_] type, where is a description item number) and edit it, if necessary. You can export several dongle descriptions to the file with settings. Each time you click the [Save] button, a new description is added to the INI file.
191
Users Manual
When the Guardant Net server is run, it reads information from the at tached dongles and selects out of descriptions contained in the INI file the one which fits a dongle most of all. The most fitting description is the one in which the aggregate priority of the search parameters, which fit a particular dongle, is higher that the aggregate priority of all other descrip tions. If there are several sections with descriptions in the INI file having the same aggregate priorities, the first section will be used. Editing the Field
Toolbar Menu Hotkey Edit|Field properties <Ctrl+P>
To edit the existing field you should select it and click on any of the above controls. One of edit windows will appear. You can either change the name and the value of any field other than Algorithm or change the name, the properties and the determinant of the algorithm descriptor. Deleting the Field
Toolbar Menu Hotkey Edit|Delete <Del>
To delete a field you should select it and click on any of the above con trols. You should confirm deleting of the field in the corresponding dia logue box. Important
Be careful when deleting the descriptors of the default algorithms. For example, algorithm #0 (AutoProtect) is used by default in the automatic protection of executable applications. Therefore, if you delete this algorithm from the dongle, you will have to use /NOA automatic protection option that prevents usage of algorithm #0 for applications protected with this dongle.
Programming the Dongles Memory Reading Data from the Dongle

Toolbar Menu Hotkey Dongle|Read <Ctrl+R>
After the mask is loaded, its fields will contain the same values as during the last saving of the mask to a file. To enter the values from the attached dongle into the mask fields, you should read the data from this dongle and enter them into the mask.
192
We recommend that you read the data from the dongle and enter them into the mask before editing the mask fields. If the number and/or the length of mask fields do not match the layout of data in the dongle, then reading from the dongle may turn to be incorrect. For example, if the mask contains only descriptors of 4 default algorithms, while apart from these there is also one more field created in the dongle, then during reading from such a dongle neither this field nor its contents will be displayed in the fields list. Therefore, you should ensure that a re quired mask is loaded when reading the information from the dongle. Writing Data into the Dongle
Toolbar Menu Hotkey Dongle|Write <Ctrl+W>
To reorganize the dongles memory it is not enough to edit the list of fields and their values in the mask. To store the mask changes in the dongles memory, you should write the mask values to the dongle. While writing, the program will automatically create new fields in the dongles memory (if you have created them in the mask), write all mask data to the dongle and adjust hardware locks (if you have created or deleted hardware algo rithms). Warning
Do not forget to write the data into the dongle after editing the mask fields. Otherwise, the changes in the mask will not be reflected in the dongles memory!
After each write session the values of the fields of Counter type are automatically incremented by 1. You can use this feature to get the don gles with unique serial numbers, because the Serial Number field of don gles is of Counter type. Setting Read/Write Locks
Toolbar Menu Hotkey Dongle|Set Read/Write locks <Ctrl+L>
You are already aware that read/write locks can be implemented for cer tain areas of the dongles memory. The locks are set for a continuous memory area starting with address 14 in UAM (i.e., where user data area begins, which is displayed in the middle of NSKUTIL main window). Locks are always implemented for that memory area where algorithms descriptors are stored. NSKUTIL automatically adjusts the lock values during creation/deletion of fields of Algorithm type.
193
Users Manual
However, you may as well implement locks for any data written in this memory area. For example, if you have created a field of String type at the location with address 78 in UAM and entered some password in this field, you can set a write lock on this field, thus making it absolutely im possible to modify the password. By clicking on any of the above controls the following window will appear:
Figure 18. NSKUTIL window for setting read/write locks. In this window, you are asked to specify the length of memory areas, which are read/write protected. In the input field you should specify the UAM addresses of the last byte to be read and write protected. By default both fields value is set to 77. This means that bytes from address 14 in UAM (i.e., where user data area begins) through to address 77 in UAM are read and write protected. This area contains descriptors of the default algorithms. If read and write locks are implemented for some memory area, then the locks will apply to bytes whose addresses are both read and write protected. For example, if you have implemented a read lock for the area ending with address 77, and a write lock for the area ending with address 87, then the bytes with addresses 14..77 in UAM will be read and write protected, while the bytes with addresses 78..87 in UAM will be only write protected (they can be read using the API functions, but cannot be modified). To release the lock implemented for a certain memory area, you should decrement the value in the relevant input field (Figure 15). For example, if you need to release the write lock implemented in the previous example, you should designate value 77 in the Write Lock field. Then the String field (addresses from 78 through to 87 in UAM) will not be write protected. Important
You cannot release locks implemented for those memory areas, where hardware algorithms descriptors are located. After setting (releasing) locks do not forget to execute writing to the dongle!
194
Obtaining Dongle Information

Toolbar Menu Hotkey Dongle|Dongle Information <Ctrl+I>
Selection of this menu item allows you to read the following information about the attached dongle: dongle model, memory size, program version, protocol version, client version, the starting address of UAM area, the ad dress of the area used for algorithms, parallel port address, type of the dongle, hardware version of the dongle, maximum license limit, dongles ID number (ID). The displayed message window will present information about the dongle in your selected numbering system. Obtaining Responses from Hardware Algorithms
Toolbar Menu Hotkey Dongle|Generate algorithm report <Ctrl+Q>
To use hardware algorithms of the dongle, it is necessary to know the se quence that the required algorithm will return in reply to a query. This re sponse can then be used, for example, to make the protection logic more sophisticated. To obtain responses from a particular algorithm you should select it in the list and click on any of the above controls. The following window will ap pear:
Figure 19. NSKUTIL window for generating algorithm report. The algorithms number is indicated in the title bar of this window. In the Number of queries field you should specify the number of times this algorithm should be queried in order to obtain response. Each time the algorithm is queried it generates a response whose length is the same as the length of the query specified in the algorithms descriptor. For exam ple, if the length of the query is 32 bytes (as of the algorithm of Fast
195
Users Manual
type), and you have specified value 4 in the Number of Queries field, then four responses, each 32 byte long, will be generated. In the Properties section you are asked to choose sequences to be used as queries to algorithms. There are two alternatives: a query can be presented as a sequence of random numbers or as an arithmetic progression. If you choose the second option, you will additionally have to indicate the step of progression (in the Step field) and specify its first term. It is speci fied in hexadecimal editor that appears on clicking on the [First query] button. For your convenience queries to algorithms and their responses are writ ten to a special report file. This is a text file created according to syntax rules of one of the three programming languages: C/C++, Pascal/Delphi or Assembler. You can select the required language in the Programming Language list. Queries and responses are written into the report file as arrays. You can choose whether queries and responses should be written in one or two ar rays in the Report form section. In the first case both the query and the response of the algorithm will be accumulated in one array. The elements of this array will be represented as interleaved queries and responses, the number of the array elements will be equal to the doubled number of que ries; and the length of each element will be the same as the length of the query. In the second case two arrays will be created in the report file: one will contain queries, and the other one responses to these queries. The number of elements in each array will be equal to the number of queries; and the length of each element will be the same as the length of the query. Now, to generate a report file you should click on [Generate Report] button. In the window that appears you will be asked to specify the name of the report file (a file with REP extension, the default is TRANSFOR.REP). By using the Transform operation NSKUTIL will query the chosen algorithm, get a response from it and generate a report file. Conversion of the query into a response is oneway. To obtain re sponses you can use any of available algorithms. You can use arrays written in the report file in the application to be pro tected. You will be using an array of queries for further calls to the dongle (we strongly recommend you not to store it in the application in the ex plicit form; it is better be encoded in some way). An array of responses should not be stored in the application at all; otherwise you will not be able to achieve a desired level of protection. For example, encode some important data using this array (you can use fast reversible conversion where an array of responses will serve as a password).
196
Fast Reversible Conversion

Toolbar Menu Hotkey Dongle|Transform <Ctrl+T>
To encode and then decode data fast reversible conversion is used. This conversion uses a special password, which is generally modified by hard ware algorithms of Fast type. It is more convenient to prepare for the conversion in NSKUTIL utility. The utility allows you to assign a pass word for reversible conversion and encode information using any of the three methods. You should select the algorithm of Fast type in the main window and click on any of the above controls (they are available only if the algorithm of Fast type has been selected). The following window will appear:
Figure 20. NSKUTIL window for conversion by Fast type algorithm. The sequential number of the algorithm used for password conversion is indicated in the title bar of this window. In the Input data section you may specify to represent the data to be converted as a text string or a file. After you have made a choice, you should either enter a string in the text editor invoked at the click of [Enter string] button or specify the name of the file by clicking on [File name] button. After that the string or the file name will be displayed in the Input data section. Output data section is used to specify the representation format for en coded data. This can be either a text file or a binary file. In the first case the encoded data will be written as an array of numbers in a text file cre ated according to syntax rules of any of the three programming languages: C/C++, Pascal/Delphi or Assembler (for example, this form of data rep resentation may be convenient when you wish to encode a Copyright string). In the second case a file will be created that will contain an en coded sequence of bytes (for example, this form of data representation may be convenient when you wish to encode a database). You can enter a name of the file by clicking on [File name] button. By default,
197
Users Manual
OUTPUT.REP file is used. After that the name of the file that you have specified will be displayed in the Output data section. In the Command section you should choose between the two fast re versible conversion commands to be used for data encoding. To encode data use Encode command, and Decode command to decode data. Reversible conversion is performed by any of the three methods. You should specify it in Method field. While doing this, you should remem ber of the particular features of these methods described in Chapter 9 In Programming language section you should choose what program ming language syntax will be used for creating an array to contain con verted data (if you have chosen the text file form). To perform reversible conversion a password is required. By default, NSKUTIL creates a password as a sequence of random numbers. How ever, you can assign your own password; for this purpose you can use a hexadecimal editor activated at the click on [Password] button in the lower part of the window (Figure 17). The length of the password is fixed and equals 32 bytes. Upon finishing with the preparations you can proceed to data conversion. To do this, you need to click on [Execute] button in the lower part of the window. You will be asked to enter the name of the file in which the speci fied password will be written as an array. The array is created according to syntax rules of any of the three programming languages: C/C++, Pas cal/Delphi or Assembler; the particular language can be chosen in the Programming language section. By default, the password containing file is named PASSWORD.REP. Then the utility will start converting data. At first, using CodeInit opera tion it will convert specified password by chosen algorithm of Fast type. Then, using a modified password and specified operation (generally, it is EnCode operation) a string or an input file will be converted. Conversion will be executed using the method you choose. Converted data will be placed into a specified output file either as an array of numbers or a se quence of bytes. Now, to access the encoded data from the protected application, these data should be decoded. Decoding procedure is similar to encoding pro cedure. At first, by using the same algorithm CodeInit operation modifies the password created as an array by NSKUTIL utility. Then using De Code operation the data are decoded. For the decoding to be correct, you should use the same algorithm, password and conversion method that you used when executing encoding in NSKUTIL.
198
Executing Guardant API Functions

Toolbar Menu Hotkey Dongle|Execute Guardant API function <Ctrl+F>
Sometimes it is useful to check how API functions are executed. In order to do this, there is no need in writing any program, compiling and debug ging it. You can call API functions and check their results directly from NSKUTIL utility. Via an easy to use and plain interface you can experi ment on function parameters, function calls and field values written in the dongles memory. What you need to do is just choose a menu command or press a key combination indicated above. The window that is used to work with the functions contains two tabs. The first one Function is used for selecting an API function, setting call function parameters and monitoring results of its execution. The second one displays the history of all function calls made during the current session.
Figure 21. NSKUTIL window for executing Guardant API functions. Function tab. Function tab contains the following items: Pull down list of available functions Prototype of the selected function written in C language along with the list of parameters and their types Fields for entering and displaying parameter values of the called function Button for executing the selected function after its call parameters have been specified Fields for displaying the function return code and its description
199
Users Manual
Pull down list that allows you to set one out of four number systems for entering and displaying parameters Button for restoring information in the dongles memory in accordance with the mask used. Some fields designed for entering values of function parameters are sup plied with a special [...] button. By clicking on this button you can either select a field value from the available list of constants or generate a value in hexadecimal editor depending on parameter type. The editor is also used to review and save the results of functions execution if this result is a data array. The procedure for calling functions is as follows: 1. Select a required function from the pull down list. 2. Enter the values of its parameters in the appropriate fields. 3. Click on [Execute] button, which will call the selected function with specified parameters. 4. After the function has completed its execution, the results of the call will be displayed in the Return value fields. 5. Data in the dongles memory can be restored by clicking on [Restore] button. In this case the data from the current mask will be written to the dongles memory. Statistics tab allows you to view the log that lists the functions in the or der they have been called. It contains a numbered list of function names, parameter values, return codes and execution results. To clear this log click on [Clear list] button.
Figure 22. NSKUTIL window for executing Guardant API functions. Statistics tab.
200
Preparing Data for Remote Programming of the Dongle Guardant software makes it possible to carry out remote programming of a dongle, i.e., it allows end users to update the contents of a dongles memory by themselves. There are different types of remote programming which are as follows: Remote update of the dongles memory cell or block in accordance with the mask fields. Remote update of the dongles entire memory in accordance with the mask fields. Remote update of the application license term. The remote programming process consists of passing of some unique long numbers or of a special encrypted file to your customer. These serve as a password for the NSKINST.EXE remote programming utility. Generally, the procedure is as follows: Using GSREMOTE.EXE utility the customer obtains some ran dom number (the so called number question) and communicates it to you. 2. Using NSKUTIL.EXE program you get either another random number (number answer) or an encrypted file containing a mask with the new data to be written in the dongle, depending on the mode of remote programming. Then you pass the number answer or the mask file to the customer. 3. Using GSREMOTE.EXE utility, having specified either the num ber answer or the mask file, the customer writes the new informa tion into the dongle all by himself. This procedure helps to save a lot of time and is very important in the fol lowing cases: If you have protected an application through limiting its executions counter or license term (/DC and /DT automatic protection options respectively), then, by using the remote programming facility, you can easily increase the license term of such application or even cancel the above limits at all. If your software has been protected through verification of its version (use /UV option when running the automatic protection utility), then, by using the remote programming facility, you can easily update the software for your customers by entering a new version value in their dongles and distributing a new version of the protected software product to them. If your software package is protected with unicity by mask option (use /UM option when running the automatic protection utility), then, by using remote programming you can either permit or forbid the customer to use any module out of the protected software package. 1.
201
Users Manual
If, in order to protect a new software version you have created a new hardware algorithm or a new field, then, by using remote programming, you can easily add these data to the customers dongle when you will be updating the software. The end user cannot obtain information needed for the remote pro gramming of the dongle by himself, since he does not have a file with the relevant field values and does not know the number answer. Sorting out of the right number answer would take a lot of time, because the size of this number is rather big. As is obvious, the idea of remote programming assumes that the end user has access to the GSREMOTE.EXE utility. Therefore, we recommend you to consider carefully which items you are going to supply together with your software, and if you plan to use the remote programming fea ture in the future, you should include the above utility in to the package with your software. This utility is dongle protected, therefore other users would not be able to utilize it. Important
Besides GSREMOTE.EXE, the end-user can use NSKINST.EXE (updates the dongles memory) and NSKTCHK.EXE (extends an applications license term) utilities for the remote update of its dongle.
Let us take a look at some methods of remote programming of the don gles memory. Method of Remote Change of a Memory Cell or Block
Toolbar Menu Hotkey Dongle|Update remotely|Memory Block <Ctrl+M>
This method allows you to change the value in some certain cell or the contents of some continous memory area (memory block), which has not been protected by hardware locks. Important
To update the protected fields you have to overwrite the entire dongles memory, because hardware locks can be released only by the Init operation (removal of all fields).
This method can be used to correct the contents of general purpose fields (particularly GP executions counter, version, dongle mask, current li cense limit of Guardant Net, etc.), dongles memory blocks, as well as add new fields, etc. The end user should be the one who initiates preparations for the remote programming of a dongle. Whenever a need arises, he should start GSREMOTE.EXE utility on his computer and convey a number question generated by this utility to you. Having received the number question from the user, you should select the Dongle|Remote Pro-
202
gramming|Memory Block menu item to call up the Remote repro
gramming dialogue.
Figure 23. NSKUTIL window for preparing data for remote reprogramming of the dongles memory block. In the Size section of the displayed window, select the size for the mem ory field whose contents you wish to change. This can be a byte, a word (2 bytes), a double word (4 bytes) or a memory block. For the first three options you should specify a new field value in the Value box, and the UAM address of the field to be corrected in the Ad dress box. For example to correct the value of GP executions counter (counter 1) you should select the Word option in the Size box and en ter 6 (this is the UAM address of the GP counter field) in to the Address box. For the Memory block option enter the starting UAM address of the block into the Address field, and the length of the block in bytes into the Length field. For example, for changing a 16 byte field, which starts from address 78, you should enter 78 in the Address field and 16 in the Length field. In the Number question field type in the number question forwarded to you by the end user. After that, click on the [Generate answer] button in the lower part of the window. For the Byte, Word and Double word options the NSKUTIL will display in the applicable fields the ID of the currently reprogrammed don gle and a number answer. The number answer shows which value should be written in the dongle and at which address. Moreover, each number answer is unique, and it can be used only once. This feature is very useful when you update counter values (for example, the value of the GP execu tions counter).
203
Users Manual
For the Memory block option the NSKUTIL will display the ID of the currently reprogrammed dongle and ask you to enter the name of the up date file, in which the image of the memory block that requires changing (it is a file with UPD extension, the default is REMOTE.UPD) will be saved. Important
Knowing the dongles ID, you can protect dongles with other IDs from being reprogrammed (either accidentally or intentionally) by the end-user.
You must pass the update file or the number answer to the end user, so that he could finish the remote programming. Method of Remote Change of the Entire Memory
Toolbar Menu Hotkey Dongle|Update remotely|Entire Memory <Ctrl+A>
This method is used if the contents of the entire memory of a dongle need to be changed at once (i.e., the values of all general purpose fields and the contents of the entire user data area) or the contents of memory fields that have been protected by means of hardware locks. For example, if you have released a totally new version of your software product, and for the protection of this product an overall reorganization of the dongles memory is required, then by using this method you can easily update the software which is used by your old customers. Also, this method allows you to change hardware algorighms descriptor or features. This method is based on the usage of a special encrypted update file, which stores the overall structure of fields and their values from the cur rent mask. Remote programming of the dongle is carried out as follows: Having received the number question from the user you must load a new mask from the file or edit the fields of the current mask. Then use Dongle|Remote Programming|Entire Memory menu item to call up the following dialogue box.
Figure 24. NSKUTIL window for preparing data for the remote reprogramming of the dongles entire memory.
204
The only parameter that you should specify in this window is the number question communicated to you by the end user. After that you should click on the [Generate Answer] button in the lower part of the window. NSKUTIL will display the ID of the currently reprogrammed dongle and ask you to enter the name of the update file in which the image of the memory segment that requires changing (it is a file with UPD extension, the default is REMOTE.UPD) will be saved. You must pass this file to the end user, so that he could finish the remote pro gramming. Important
Knowing the dongles ID, you can protect dongles with other IDs from being reprogrammed (either accidentally or intentionally) by the end-user.
You should remember that when using this remote programming method the values of all general purpose fields, algorithms descriptors and other data previously written into the memory will be overwritten. Therefore, you should not use this method if you may need an old value from any field. Remote Programming of the Application License Term
Toolbar Menu Hotkey Dongle|Update Remotely|License term <Ctrl+X>
This option of remote programming is used when the application is pro tected in the limited time mode. Using NSKUTIL, you can prolong pro grams license term or release the limitation at all. This can be accomplished as follows: Using GSREMOTE or NSKTCHK utility the end user obtains a number question and passes it to the developer. The developer loads a corresponding mask file and opens Remote programming of time window:
Figure 25. NSKUTIL window for preparing information for remote reprogramming of the applications license term.
205
Users Manual
To extend the applications license term you should enter the obtained number question in the respective field and then specify the time in days, hours and minutes in the appropriate field, for example, 30d10h45m. The maximum license term is limited by the size of the GP counter field (2 bytes) and is set at 227d13h15m. To cancel the restriction imposed on the applications license term the developer should check License term is unlimited option. In case the serial number of the user dongle is known (it is recommended that you have this information for each user), you may invoke Check se rial number option, and the input field will appear. This option prevents accidental or intentional attempts to reprogram other users dongle. The number question contains information on the serial number of the don gle. During generation of the number answer, it is compared to the num ber of the dongle that has been specified by the developer. If these num bers do not match, an error message is displayed. In this case, the num ber answer is not generated, and the true number of the dongle is indi cated. To obtain the number answer you will only need to click on the [Generate] button and then pass the generated number to the end user.
NSKUCM32. Programming in the Batch Mode

When programming a great number of identical dongles it is convenient to use Win32 command line utility NSKUCM32.EXE or an equivalent DOS utility NSKUCMD.EXE. The utilities use a mask file created by NSKUTIL, and within one session, they can program one dongle using the field values of this mask. Command line format is as follows:
nskucm32.exe mymask.nsd nskucmd.exe mymask.nsd
Thus, you should prepare the mask file only once, and then just specify it each time the utility is called. To automate the programming process you can use the batch file, for ex ample:
@echo off :BEGIN cls echo Attach a new dongle pause nskucmd.exe %1 if errorlevel 1 goto ERROR cls
206
Chapter 9. Programming Guardant Dongles echo The key has been successfully programmed ask "Program one more key (Y/N)? ",YN if errorlevel 2 goto END if errorlevel 1 goto BEGIN :ERROR echo Error occurred during programming the key! :END
Now you can program any number of dongles, specifying, for example, the following in the command line:
program.bat mymask.nsd,
where PROGRAM.BAT is the name of batch file, and MYMASK.NSD is the name of the mask file that you have created in NSKUTIL program. After programming of each dongle, the values of the fields of Counter type are automatically incremented by 1 in the mask file. Thus, using NSKUCMD you will get a batch of dongles with unique serial numbers (the serial number field of the dongle is of Counter type).
NSKTUTIL. Programming the Applications License Term

To write the license term of applications protected in a special mode into the dongles memory NSKTUTIL.EXE utility can be used. The utility prepares the dongles for the work in this mode, entering the specified li cense term of the protected application in the GP field of the dongle. Also, using NSKTUTIL you can correct the applications license term in the dongles that are already held by your customers (i.e., carry out remote correction of license term). Warning
This utility must never be provided to end-users! To carry out remote correction of license term in their dongles they will have to use the appropriate remote programming utility described below.
Guardant Net does not support protection of applications in the time limit mode, because GP field of these dongles cannot be used as the time counter.
207
Users Manual
NSKTUTIL Command Line Parameters

nsktutil.exe <L | R> </T[x]xx:xx[:xx] | U> [/Sxxxxx] [/Qxxxxxxxxxxxx]
Options:
L is an option used during the processing of a local dongle (i.e., the dongle which is attached to the computer); R is an option used during remote programming of the dongle; L and R options are mandatory and command the utility to execute one of
its two main functions. These options are mutually exclusive.

/T[x]xx:xx[:xx] write the license term of the protected application
into the dongle (or add the time during the remote programming of the dongle). Here XXX:XX:XX is the added time, which is set as days:hours:minutes. The maximum value that can be written into the dongle is 226 days. Not all of the time elements are obligatory. When specifying option with time set as XX:XX it will be interpreted as hours:minutes.
/U - disable restriction set on the protected applications license term (used only during remote license term correction together with R option). /T and /U options are mandatory, but they are alternative to each other since their approaches to solving one and the same task are different. Only either of them can be specified when the utility is called. /Sxxxxx change serial numbers of the dongle to be programmed (or
check the serial number during the remote programming of the dongle). Here XXXXX is a serial number of the dongle ranging between 0 and 65534; /Qxxxxxxxxxxxx specify number question (12 characters) to gener ate a number answer on its basis (used only during remote correction of license term together with R option); Before running the utility you should attach either Guardant Stealth, Guardant Fidus or Guardant Net dongle to the computer.
208
Writing the Time into the Local Dongle To write license term of the protected application into the dongle /T[x]xx:xx[:xx] option is used. For example, to write the time such as 2 days 15 hours sharp into the dongle the utility should be called as fol lows:
nsktutil.exe L /T2:15:00
L option points to the utility that it should process the dongle, which is currently attached to the computer (i.e., a local dongle). Note that in this example 00 numbers must be specified in the time settings, otherwise the time 2 hours 15 minutes will be set. If during calling the utility /Sxxxxx option is also specified, then when programming the dongle its serial number will be changed to the one that you have specified. For example, imagine that you wish to program the dongle for 5 days 10 hours 30 minutes and specify 124 as a serial number of the dongle. To do this you should call the utility as follows:
nsktutil.exe L /T05:10:30 /S124
Generally, when using this protection mode, it is better to bind the pro tected application to the serial number of the dongle as well. This will en sure that the protected application will decrement the time of its usage in the dongle with which it is protected. Otherwise, the first found dongle, which has your access codes, will be decremented. In fact, the serial number of the dongle can also be set from NSKUTIL program described above. However, it is not convenient to use both utili ties for programming one dongle. Therefore, this additional feature has been provided in NSKTUTIL utility. Remote Correction of Time You may correct the license term of the applications protected on a time limit basis remotely. This means that you can extend this time or even cancel time restriction without having to leave your office or to hold the dongle used for protection of these applications. The remote correction process is based on the interchange of unique in formation (the so called number question number answer) with your customer. To carry out such correction it is mandatory for the cus tomer to be able to run GSREMOTE or NSKTCHK utility. Using these utilites he will be able to reprogram the time in his dongle by himself.
209
Users Manual
The remote correction procedure consists of three stages: 1. When the license term of the protected application expires, the cus tomer should run GSREMOTE or NSKTCHK utility. It will gen erate a 12 character sequence (number question), which he will have to communicate to you. 2. After you receive the number question from the customer, you should run NSKTUTIL utility specifying this particular number question and the mode of remote correction (for more details see below). The utility will generate a 12 character sequence (number answer), which you will have to communicate to the customer. 3. After the customer receives the number answer from you he will supply it at the prompt of GSREMOTE or NSKTCHK utility, which will then carry out the correction of time in the dongle. Number question and number answer are unique, however, they depend on the serial number of the dongle held by the customer. Warning
When the customer starts NSKTCHK and receives a number-question, he should not terminate the utility until he completes reprogramming of his dongle! The point is that if the utility is restarted it will generate another number-question, which will require another number-answer. This ensures that the customer will be unable to extend the license term of protected applications without due authorization from the developer.
Remote Extension of License Term The customer should initiate the procedure of remote extension of time. He should pass to you the number question generated by his remote time programming utility. Your task is to get the number answer that is suitable for this number question. To do this you should run the utility with the following options:
nsktutil.exe R /T[x]xx:xx[:xx] /Qxxxxxxxxxxxx [/Sxxxxx]
R option points to the utility that the remote correction of time is to be carried out in the dongle. /T option in combination with R option indicates for how much the ap plications license term should be extended. Using /Q option you should specify a number question passed to you by the customer. Example. Imagine you need to extend the dongles license term for an other 30 days 10 hours and 25 minutes. The user has communicated to you the following number question: 10AF340C15AE. To get a corre sponding number answer you should run the utility with the following op tions:
nsktutil.exe R /T30:10:25 /Q10AF340C15AE
210
If you know which serial number is written in the dongle of this user (it is recommended that you have this information on all your customers), then you can also specify /S option when calling the utility. For example:
nsktutil.exe R /T30:10:25 /Q10AF340C15AE /S1234
In this example we assume that according to your database you have sold the dongle with serial number 1234 to this particular customer. Using /S option in combination with R option allows you to carry out honesty check on your customer. In this case the serial number that you have indicated is compared with the number question (which, among other parameters, depends on the serial number of the dongle). In case se rial numbers do not match, the utility generates an error message and the true serial number of this dongle. The number answer will not be gener ated. Thus, you become aware that the user attempts to extend the license term of somebody elses dongle, and you can apply appropriate sanctions to this user. In case you do not specify /S option such check will not be carried out. You should communicate the generated number answer to the customer, so that he could complete the time correction procedure in his dongle. Remote Cancelling of Time Restriction To cancel the time restriction you should run NSKTUTIL with the fol lowing options after you have received the number question from the cus tomer:
nsktutil.exe R /U /Qxxxxxxxxxxxx [/Sxxxxx]
This particular mode is different from the above mode of remote correc tion in that instead of /T option you should specify /U option. It points to the utility that instead of extending the protected applications license term it should cancel the time restriction. For example, if the user has communicated his number question 3FD876AC12AE to you, then to get a corresponding number answer you should run the utility with the following set of options:
nsktutil.exe R /U /Q3FD876AC12AE
In this mode it is also possible to arrange for the check of the serial num ber of the customers dongle, which is specified by /S option. By the way, this check is most important in this mode, would you agree? You should communicate the number answer generated by the utility to the customer, so that he could complete the reprogramming of his dongle.
211
Chapter 10. Remote Programming of Guardant Dongles
Chapter 10 Remote Programming of Guardant Dongles

Guardant system provides you with a number of capabilities for remote programming of dongles held by the users of your protected software products. Remote programming approach suggests mutual participation of both parties, i.e., your customer and yourself. Each should work with one of the following utilities:
Remote programming mode Remote update of the dongles memory, executions counter correction. Remote correction of the applications license term, removal of license term restrictions (only for Guardant Stealth and Guardant Fidus). Dongle programming utility Developer NSKUTIL.EXE Customer GSREMOTE.EXE or NSKINST.EXE GSREMOTE.EXE or NSKTCHK.EXE
NSKUTIL.EXE or NSKTUTIL.EXE
The utilities that the customer should have are called remote program ming utilities. In the previous Chapter of this Manual, procedures for remote program ming were described. Now, we are going to investigate what should be done on the part of the customer.
GSREMOTE. Remote Programming of the Dongle Memory and Correction of the Applications License Term
GSREMOTE utility is designed for the end users of the software pro tected by Guardant dongles. It allows you to change the contents of the memory of dongles, including correction of the applications license term upon authorization from the protected software owner. GSREMOTE is a universal Win32 utility that replaces DOS utilities such as NSKINST and NSKTCHK, which are recommended only for DOS users. The necessity in this utility arises when terms of use of a protected pro gram are changed in any manner (for example, when the program rental period is prolonged, a new program version is released, additional features are activated, etc.).
213
Users Manual
It is obvious that GSREMOTE should be supplied together with the ap plication. Also, NOVEX32.DLL should be included in this package. GSREMOTE supports two types of remote programming: it can be used to update the memory contents of the dongle (either in full or in part) and correct the license term of the protected application. The utility has a wizard like interface and comprises several windows. You can move to a new window by clicking on the [Next>] button after the current dialogue has been completed and return to the previous win dow by clicking on the [<Back] button.
Figure 26. Start window of GSREMOTE utility. Changing the Contents of the Dongle Memory The user starts GSREMOTE and selects Whole or partial update of don gles memory contents option. The utility generates a number question which is then passed by the user to the developer (supplier) of the pro tected program. After that, the user may terminate the program by clicking on the [Finish] button, in case an answer is not anticipated in the nearest future. Having received the number question, the developer starts the main pro gramming utility NSKUTIL, introduces the required changes in the cor responding mask file and performs operations needed for generation of a number answer (see Preparing Data for Remote Programming of the Dongle). Then he passes the answer as a hex number or update file (de pending on the update method) to the end user. In case the user has terminated the program he should start it anew and repeat operations above, then select Process number answer received from software vendor option (set by default) in the next window.
214
In case the user has not terminated the program, he can select Process number answer option. By selecting a corresponding option, the user specifies whether the entire memory is to be updated or only its block. In the first case the path to the update file is to be specified in the dialogue box, in the second case it should be additionally specified whether the answer has been received in the form of a hexadecimal number or a file. If it is a number, it is to be typed in the input field, and if it is a file, a path is to be specified. After that, you can move to the last window where the utility reports on the result of the update procedure. Correcting the Applications License Term The user starts GSREMOTE and selects Prolongation of the license term of the protected program option. The utility reports how much net time (in days, hours and minutes) is left before the protected program termi nates and generates a number question in the next window. This number is passed by the user to the developer (supplier) of the protected program. After that, the user may terminate the program by clicking on the [Finish] button in case an answer is not anticipated in the nearest future. Having received the number question, the developer starts the main pro gramming utility NSKUTIL, introduces the required changes of counter #1 (GP) in the corresponding mask file and performs operations needed to generate the number answer (see Preparing Data for Remote Pro gramming of the Dongle). Then he passes the number answer to the end user. In case the user has terminated the program he should start it anew and repeat operations above, then select the Process number answer received from software vendor option (set by default) in the next window. In case the user has not terminated the program, he can select Process number answer option. Then the user enters the received number answer in the input field and moves to the last dialogue window, where the utility reports on the result of the correction procedure.
NSKINST. Remote Programming of the Dongles Memory

NSKINST.EXE utility can correct values written in the memory of Guardant dongles (create and remove mask fields, update information written in the dongle, etc.). It uses either an update file created by NSKUTIL program and containing the dongles memory image or a number answer generated by NSKUTIL.
215
Users Manual
The objective of NSKINST application is to carry out remote program ming of the dongle held by the end user. Warning
You must supply this utility with your product if you are planning to utilize any of the remote programming methods in the future.
NSKINST utilitys interface can be translated into any language, because all messages are assembled in one file NSKINST.MSG. NSKINST.MSE file contains messages that have been translated into English. For NSKINST utility to start communicating in English the file should be simply renamed into NSKINST.MSG. NSKINST can run only in batch mode. There are several options a cus tomer can set in order to switch it to a required mode. Utility call format is the following:
nskinst.exe </Q | /A | file | /M file>, where /Q Display number question
Process number answer Remote change of the memory block using update file /M file Remote change of all memory using update file For example:
file nskinst.exe nskinst.exe nskinst.exe nskinst.exe /Q /A REMOTE.UPD /M REMOTE.UPD
/A
Fast Correction of the Dongles Memory Contents To ensure easy and fast updating of protected software products held by your customers, as well as for other purposes, the remote updating of the dongles memory is used. When the customer receives a new version of protected software product, he should update Version field of the dongle to which the software prod uct of the previous version has been bound. To be able to do this he should run NSKINST utility with /Q option on his computer (displaying of a number question):
nskinst.exe /q
The utility will display a generated random number (number question) that will depend on the specific features of the dongle held by the user. He will have to pass this number question to you by any possible means.
216
On the basis of the received number question, you generate a random number answer using NSKUTIL program, in which data needed for re mote programming are embedded (this procedure is described in detail in Method of Remote Change of a Memory Cell or Block). You should pass the number answer to the end user. When the end user receives this number from you, he should restart NSKINST utility with /A parameter:
nkinst.exe /A
and enter the number answer received from you at the utility prompt. The end user will not be able to use the same number answer again to re program the dongle. Remote Updating of the Dongles Memory Block To change the contents of a particular memory block of the dongle it is good to use another remote programming method that of remote up date of the memory block. The end user starts preparing for this remote programming method as has been described in the previous section, i.e., by starting NSKINST utility with /Q option (displaying of a number question):
nskinst.exe /q
As soon as the end user gets a number question, he should communicate it to you. On the basis of the received number question using NSKUTIL program you should create an encoded update file that should contain changes to be introduced to the required memory block of the dongle, for example, a new hardware algorithms descriptor. You should then pass the update file to the end user. After receiving this file from you, the user should restart NSKINST util ity, having specified the name of this file as additional parameter, for ex ample:
nskinst.exe remote.upd
Using the information from REMOTE.UPD file the utility will update the contents of the required memory block of the dongle that will result (in our example) in the creation of a new hardware algorithm. From that time the customer will be able to work with the new version of your prod uct, using a new algorithm.
217
Users Manual
Remote Updating of the Dongle's Entire Memory In the method of remote updating of the dongles entire memory the up date file is also used, although it contains the image of the entire available memory, including both general purpose fields and user data areas. To prepare for this remote programming method the user should start NSKINST utility with /Q option:
nskinst.exe /q
and communicate to you a number question returned by this utility. Based on the number question returned by NSKUTIL program you should create a special file for updating the dongles entire memory (see Method of Remote Change of the Memory Block). Then you should pass the update file to the end user. When the user receives this file from you, he should restart NSKINST utility, having specified /M option and the name of this file as additional parameters, for example:
nskinst.exe /M remote.upd
Using the information from REMOTE.UPD file, the utility will update the entire memory of the dongle. As a result, the user will be able to work with a completely new version of your software product with a different memory organization of the dongle.
NSKTCHK. Remote Correction of the Applications License Term

This utility allows the customer to determine his protected applications time limit. Besides, using this utility he can either extend the applications license term or cancel the time limit at all. For the sake of users working with applications protected in this mode, you should supply this utility together with the protected application. Warning
Guardant Net does not support protection based on the implementation of time limits for applications, because the GP field of these dongles cannot be used as a time counter.
Displaying the License Term To find out how much time is left before the protected application expires the user should start the utility without parameters:
nsktchk.exe
In this case, the utility will display information similar to the following:
License term available is 22 days / 17 hours / 15 minutes
Thus, a user can take a preliminary decision on extending this time.
218
Correcting the License Term With your consent, the customers will be able to prolong the license term of the protected application or even cancel the license term limit all by themselves. In both cases, the customers task will be to generate a number question, communicate it to you and receive a number answer from you. The number question depends on the serial number of the dongle. The num ber answer depends on the serial number of the dongle, correction mode (extension or cancellation of the time limit) and the amount of time to be added to the programs running limit. Both numbers are unique and it is almost impossible to figure them out. Let us have a closer look at both functions provided by remote correction: 1. When the customer wishes to extend the applications license term, he should run the utility with /A option:
nsktchk.exe /A
The utility will return a number question that is necessary for the remote reprogramming of the dongle, for example:
Number-question - 47784F3512AB Number-answer -
The user should pass this received number question to you. By running NSKTUTIL utility with /T and /Q options you will get a respective num ber answer (see Remote Correction of Time). You should immediately communicate this number to the user. The user will enter this number at the prompt displayed by the running utility, for example:
Number-question - 47784F3512AB Number-answer - 2410F3EF8A
and the utility will increment the time counter of his dongle by the value that you specified in the /T option when calling NSKTUTIL. 2. If the customer wishes to cancel the limit set on protected applications license term, he will have to act as described above. However, in this case to receive a number answer you should run NSKTUTIL utility with /U option, but not with /T option as described above. Warning
When running the utility in the remote correction of time mode the end-user, upon getting a number-question, should not terminate the utility before the dongle reprogramming process is complete! If the utility is restarted it will generate another number-question, which, of course, will have a different number-answer associated with it.
219
Chapter 11. Guardant Drivers
Chapter 11 Guardant Drivers

Guardant drivers are needed for safe and stable INSTDRV. Driver Instal lation Utility. When Guardant software is installed, driver files are copied into \DRIVERS subdirectory, and all files that provide management of drivers from your application are copied into \DRIVERS\INST.DLL subdirec tory. Besides, during the installation of Guardant software drivers are automatically installed in the operating system. To install, configure and remove Guardant drivers INSTDRV.EXE util ity is used. When the program is started, the following files should be lo cated in the same directory as INSTDRV.EXE:
Windows 95/98/Me
NVKEY95.VX_ NVKEYU95.SYS NVKEYUSB.SYS NVKEY98U.SYS GSNUSB.IN_ INSTDRV.INI GRDCTL32.DLL GRDDRV32.CPL GRDDRV32.DLL Windows 95/98/Me driver; Windows 95 OSR 2.x USB driver; Windows 98/ME USB driver; Windows 98/ME additional USB driver; Configuration file for USB drivers; Default configuration file. Diagnostic utility component; Control panel applet; Driver management library
Windows NT/2000/XP
NVKEYNT.SYS NVKEYVDD.DLL NVKEY4NT.SYS NVKEYUSB.SYS GSNUSB.IN_ INSTDRV.INI GRDCTL32.DLL GRDDRV32.CPL GRDDRV32.DLL Windows NT/2000/XP kernel driver; Virtual DOS driver; DOS device driver; Windows 2000/XP USB driver; Configuration file for USB driver; Default configuration file. Diagnostic utility component; Control panel applet; Driver management library
221
Users Manual
Important
Guardant USB driver can be installed only with INSTDRV utility or API functions intended to work with drivers (to be described below). It is recommended that you do not install it manually applying a standard Windows wizard. Guardant USB dongle is to be connected to the computer no sooner than the drivers are installed, otherwise Windows will start searching drivers for them. In case this happens, you should refuse searching drivers by Windows wizard by clicking on the [Cancel] button and disconnect the USB-dongle from the computer.
When starting INSTDRV program its main window will be displayed: running of protected applications, as well as for all utilities working with dongles. Use of drivers helps to avoid possible conflicts of sharing re sources of the parallel or USB ports when accessing the dongle. Warning
You have to supply Guardant drivers together with protected product!
This Chapter contains tips on installing and setting Guardant drivers, and describes how to manage them from your applications.
Figure 27. INSTDRV main window. When the utility is started, it will check for the presence of Guardant driver in the system. If the driver is not found, only [Install driver] but ton will be available in the main window. Installing the Driver To install or update Guardant driver click on [Install driver] or [Reinstall driver] button. If installation is completed successfully, INSTDRV will display a corresponding message and then return to the main window. Important
During the installation of drivers, ALL applications, especially in DOS sessions, should be closed! Otherwise a file sharing error may occur.
In Windows NT and Windows 2000/XP it is also required for the user to have system administrators privileges to install drivers, otherwise installa tion, removal and configuration will be impossible.
222
Configuring the Driver You may set the parameters of Guardant driver installed in the system. To do this, you should click on [Configure driver] button in INSTDRV main window. Below is the driver configuration dialogue. The only difference between Guardant drivers configuration procedure in Windows 95/98/Me and NT/2000/XP lies in the methods of capturing ports.
Figure 28. Dialogue box for configuring the driver of INSTDRV utility in Windows 95/98/Me.
Figure 29. Dialogue box for configuring the driver of INSTDRV utility in Windows NT/2000/XP.
223
Users Manual
Driver configuration procedure includes the following steps: Assign ports to search for the dongle Assign methods of capturing ports Set timeout Set advanced parameters. Assigning Ports to Search for the Dongle In the left upper corner of the window, a list of parallel ports found on the computer is displayed. In Windows 95/98/Me the address of the port is displayed next to its name. Furthermore, in case hardware and software to be used with USB devices is installed on the computer, the list of ports contains USB line. You can specify on which ports the driver should search for dongles. This is very helpful when you need to reduce the re sponse time of the dongle. For example, if the dongle is attached to LPT2 port, and the printer is attached to LPT1 port, you may disable the search of the dongle on LPT1 port. If you only use Guardant USB dongles, you may disable the search of dongles across all LPT ports. By default, the search is enabled across all USB and LPT ports. Assigning Methods of Capturing the Port Parallel port capture helps to avoid conflicts in case the protected applica tion attempts to access the dongle when another application uses the same port (for example, during printing). The port is captured by the driver only for the period of communicating with the dongle, after which the port is released. By default, configuration utility sets automatic capture method. Other methods are good for experienced users only, which would know the tricks of working with operating systems and peripheral devices. You can assign a combination of capture methods for each of the selected parallel ports. Setting Timeout In case the port that Guardant driver tries to access appears captured, the driver will wait for the port to be released. This waiting period of the driver is called timeout. During this time, the driver will constantly check the status of the port, and if the latter remains captured, error #24 (Port busy) will be returned. Timeout period in seconds is specified in the lower part of the window (Figure 25 or Figure 26). Allowed value ranges between 0.001 and 600 seconds. Default timeout value is 10. Important
Timeout period is understood as the overall waiting time for all ports and not per each port (for example, the default timeout of 10 seconds means the total time, but not 10 seconds per each port).
224
Setting Advanced Parameters A dialogue box for setting advanced parameters is invoked by clicking on
[Advanced] button in the lower part of the window (Figure 25 or 26):
Figure 30. Dialogue box for setting advanced parameters for configuring INSTDRV utility driver. Advanced parameters allow you to set timer type to be used by Guardant drivers, as well as specify a method for generating delays that are necessary when communicating with the dongle. This may be required when work ing on old or unstable computers (for example, overclocked computers), which often experience problems with system timers. This will help to achieve maximum stability of communication with Guardant dongles. For those who are not too well familiar with the design of PCs, an auto matic mode (set by default) is provided for selecting parameters. In this case, the driver gathers statistics, analyzes stability of computer timers and chooses an optimal setting. After setting all necessary parameters press [Ok]; to cancel changes press [Cancel]. During the first start of INSTDRV, while Guardant driver is not installed in the system, the default parameter values are read from INSTDRV.INI file located in the same directory as the installer.
225
Users Manual
All parameters that you specified are written into the system registry and are further read from there both by Guardant driver and INSTDRV utility. No system reboot is needed after configuration. All changes introduced come into effect immediately. Removing the Driver To remove the driver from the system, click on [Uninstall driver] button in INSTDRV main window (Figure 24). Important
In Windows 95/98/Me after the driver is removed, it remains active until the system is restarted. Only driver load instruction is removed from the system registry. All previously set driver configuration (such as ports to be used, methods of their capture, timeout value) are preserved.
Using Command Line Options INSTDRV can be used in batch mode. When started with command line options, INSTDRV main window (Figure 24) will not be displayed. The installer supports the following command line options:
/H, /? /U Display message box with a list of available options. Uninstalls the driver from the system (should be used with /Q option, otherwise you will be returned to the main window, where you should click on [Uninstall driver]). Report in detail of all existing errors. This option is better be used in emergency only, since it also reports of nonfatal errors that do not affect the result of the operation (for example, if INI file is not found the default parameters are set). Enforce setting of the language for messages (/LE English, /LR Russian). By default, the language is automatically subject to active code page number, and all messages and dialogues are displayed in the local language. Ignore /Q option when a prompt for system reboot is displayed (if /Q option is specified and /RB option is not, then if system reboot is needed INSTDRV will carry it out without any prompts, which is not always convenient). Disable automatic reboot of the system. Do not display anything on the screen. This option is useful when starting INSTDRV from other applications. By default, it installs the driver, and when used with /U option it removes the driver.
/I
/LE, /LR
/RB
/NORB /Q
226
Return Codes Return codes are generated by the program in the batch mode (i.e., when windows are not displayed during running of the program, for example, when INSTDRV is started with /Q option). When an error occurs in win dow mode, a corresponding message is displayed. The following return codes are available: 0 The task has been completed successfully. 1 The operation has been interrupted by user. 2 Attempt has been made to install the driver in environment other than Windows 95/98/Me or Windows NT/2000/XP. 3 Error occurred during installation. 4 User does not possess sufficient rights (only in Windows NT/2000/XP). 5 The driver is occupied by another application. 1 Code returned after a prompt (/?, /H) has been displayed.
Installing Drivers from Your Application

You may install, configure and remove Guardant drivers from your Win dows applications (for example, from your software installer). For this reason, a 16 bit INSTDRV.DLL library that contains all necessary API functions is supplied along with your product. Description of all used constants, return codes and data structures are given in INSTDRVF.H and INSTDRVS.H files. You can include these files in your application that uses INSTDRV.DLL library. The procedure of using the library is described in detail in the example written in C language (INSTDRV.C and DIALOG.C files). After the ex ample is compiled, you will get INSTDRV application that is functionally identical to the driver installation program described above, but that works with Guardant drivers through INSTDRV.DLL. INSTDRV.DLL library and all files necessary for its usage, as well as files connected with this example, are written in DRIVERS\INST.DLL sub directory. API Functions to be Used with Guardant Drivers All functions described below are designed for using in both Windows 95/98/Me and Windows NT/2000/XP.
227
Users Manual
Installing the Driver

int WINAPI GD_InstallDriver(void);
In parameters:
Not available
Out parameters:
Error code
Description: The function installs Guardant driver in the operating system. If the driver is already installed, the function returns ge_DRIVER_ALREADY_INSTALLED error. Installing (Reinstalling) the Driver
int WINAPI GD_ReInstallDriver(void);
In parameters:
Not available
Out parameters:
Error code
Description: The function installs a new version of Guardant driver. If the driver is al ready installed in the system, it is reinstalled (the previous driver configu ration is saved). Removing the Driver
int WINAPI GD_RemoveDriver(BOOL bSaveConfig);
In parameters:
bSaveConfig save the driver configuration or not.
Out parameters:
Error code
Description: The function removes Guardant driver from the system. If bSaveConfig variable has TRUE (1) value, the driver configuration is not removed from the system registry. In this case, during further installation of the driver the existing configuration will be used. If bSaveConfig has FALSE (0) value, the driver configuration will be deleted from the registry. Important
In Windows 95/98/Me after the driver is removed, the operating system should be rebooted since the driver remains active for DOS applications and 16-bit Windows applications.
228
Obtaining Information about the Installed Driver

int WINAPI dwSize); GD_GetDriverInfo(PGD_DRIVER_INFO pDI, DWORD
In parameters:
pDI dwSize Pointer to the driver information buffer Buffer size
Out parameters:
Error code
Description: The function places into the buffer information about the current state of Guardant driver installed in the system. The information is structured in accordance with the fields of GD_DRIVER_INFO structure (see INSTDRVS.H file). dwSize value should be equal to the size of GD_DRIVER_INFO structure. If it is lower than the structure size, ge_RETURNED_PART_ONLY error code will be returned, and only dwSize bytes of data will be entered into the buffer. Other possible error codes: ge_DRIVER_NOT_FOUND ge_DRIVER_BUSY Guardant driver is not installed in the system Guardant driver is busy and can not currently display data about its state The version of the driver found is too old and does not support the display of data about its state
ge_DRIVER_OLD_VERSION
No errors, the buffer contains all information about the state of the driver. Using this function, you can only get information about the driver in stalled in the system (including its version, time and date of creation, modes of capturing LPT ports, etc.). However, it does not allow you to estimate whether the driver needs to be updated and whether it can be re configured using this INSTDRV.DLL version. If you wish to update the driver or change its configuration, you should use GD_CheckDriver() function, which will give you answers to the above questions. The function will be displaying the information on any version of Guard ant driver (the version is returned to pDI >di_wVersion), except for the oldest ones, which do not support this service. Guardant drivers should not necessarily be present in the directory that contains INSTDRV.DLL. ge_NO_ERROR
229
Users Manual
Checking the Presence and Current Status of the Driver

int WINAPI GD_CheckDriver(PGD_DRIVER_INFO pDI, DWORD dwSize);
In parameters:
pDI dwSize Pointer to the driver information buffer Buffer size
Out parameters:
Error code
Description: The function checks for the presence and current state of Guardant driver. This function requires Guardant drivers presence in the directory where INSTDRV.DLL is located. If the error code is ge_NO_ERROR (no errors), then the structure con taining full information about the current state of the driver installed in the system is placed in the buffer (see INSTDRVS.H file). The value of dwSize should be equal to the size of GD_DRIVER_INFO structure. If it is lower than the structure size, ge_RETURNED_PART_ONLY error code will be returned, and only dwSize bytes of data will be entered into the buffer. Using GD_CheckDriver() function you can also estimate whether the in stalled driver needs to be updated and whether its settings can be changed. The following return codes are used during such estimation: ge_NO_ERROR the driver installed in the system is the same as the one located in the directory where INSTDRV.DLL is stored. It can be reconfigured, updating of the driver is not nec essary. the driver installed in the system is older than the one located in the directory where INSTDRV.DLL is stored. You do not have to re configure it, and such driver should be updated. the driver installed in the system is newer than the one located in the directory where INSTDRV.DLL is stored. You do not have to re configure it, and updating of such driver is not required.
ge_DRIVER_OLD_VERSION
ge_DRIVER_NEWER_VERSION
230
Restore Default Driver Configuration

int WINAPI GD_ConfigSetDefaults(void);
In parameters:
Not available
Out parameters:
Error code
Description: The function sets the default driver configuration. Default values are taken from INSTDRV.INI file. To enable changes in the driver configuration, GD_ReconfigureDriver() should be called. Assigning Ports to Search for Dongles
int WINAPI GD_ConfigPortsUse(BYTE byPortsMask);
In parameters:
byPortsMask Mask of ports to be used
Out parameters:
Error code
Description: The function assigns ports across which dongles will be searched. The mask is specified as a sum of gd_USE_PORT_LPTx (see INSTDRVS.H file). To enable changes in the driver configuration GD_ReconfigureDriver() should be called. Assigning Methods for Capturing a Specified Port
int WINAPI GD_ConfigPortAlloc(BYTE byPort, DWORD dwMethod);
In parameters:
byPort dwMethod Port number Capture method mask
Out parameters:
Error code
Description: The function sets a combination of methods for capturing a specified port. The port number is specified by gd_PORT_LPTx constant (see INSTDRVS.H file). Capture method is specified as a sum of required constants gd_METHOD_xxxxx. To enable changes in the driver configuration GD_ReconfigureDriver() should be called.
231
Users Manual
Enabling USB Ports

int WINAPI GD_ConfigUSBUse(BOOL bUSBUse);
In parameters:
bUSBUse Enable USB ports
Out parameters:
Error code
Description: The function instructs Guardant driver whether it should search for don gles across USB ports. If bUSBUse parameter has 1 (TRUE) value, then the search will be enabled across all USB ports, if the value is 0 (FALSE), the search will be disabled. To invoke changes in the driver configuration GD_ReconfigureDriver() should be called. Setting TimeOut Values
int WINAPI GD_ConfigTimeOut(DWORD dwTimeOut);
In parameters:
dwTimeOut Timeout in milliseconds
Out parameters:
Error code
Description: Sets the overall time, during which the driver tries to capture the port. Upon the expiry of this time, the driver returns PORT_BUSY error. The timeout value should range between 1 and 600000 (i.e., from 0.001 to 600 seconds). To enable changes in the driver configuration GD_ReconfigureDriver() should be called. Setting IRQL Value During the Port Capture
int WINAPI GD_ConfigIrql(BYTE byPort, BYTE byIrql);
In parameters:
byPort byIrql Port number IRQL value
Out parameters
Error code
232
Description: Sets IRQL value when a respective capture method gd_METHOD_IRQL (see INSTDRVS.H file) is used for the port. Port number is specified by gd_PORT_LPTx constant. IRQL value should range between 0 and 26. To enable changes in the driver configuration GD_ReconfigureDriver() should be called. Important
This function is used in Windows NT only. In Windows 95/98/Me use of this function makes no sense.
Finish the Driver Configuration Procedure

int WINAPI GD_ReconfigureDriver(void);
In parameters:
Not available
Out parameters:
Error code
Description: The function actually reconfigures the driver. It should be called after all required driver parameters have been set. The function will reconfigure all specified driver parameters using GD_ConfigXXXXX() functions during the current application running session. Setting Messages Display Mode
void WINAPI GD_SetMessageMode(BOOL bShowMessages, BOOL bShowFullDescriptions);
In parameters:
bShowMessages bShowFullDescriptions Enable messages Enable detailed messages
Out parameters:
Not available
Description: Sets a mode for displaying messages for all functions. If bShowMessages parameter is TRUE (1), messages about common errors and operation re sults will be displayed, if it is FALSE (0) no messages will be displayed on the screen. If both parameters are TRUE, messages about all errors and all operation results will be displayed. This mode is useful during de bugging and troubleshooting.
233
Users Manual
Setting Messages Display Mode and Language

void WINAPI GD_SetInstdrvConfig(DWORD dwFlags);
In parameters:
dwFlags configuration flags (gic_XXXX)
Out parameters:
Not available
Description: Sets a mode for displaying messages for all functions. Mode is defined by dwFlags parameter, which is a combination of follow ing configuration flags:
gic_ SHOWMESSAGES gic_FULLINFO - enables displaying of messages. If this flag is not set, no messages will be displayed on the screen. - enables displaying of detailed messages. If this flag is set, detailed messages about all errors and operation results will be displayed. This mode is useful during debugging and troubleshooting. If this flag is not set, only messages about common errors and operation results will be displayed. This flag is effective when gic_SHOWMESSAGES flag is set. - enables logging of messages to a file. If this flag is set, messages about all errors and operation results will be logged to _INSTDRV.LOG file, which will be created in the same folder with INSTDRV.DLL. If INSTDRV.DLL file already exists, new data will be appended to the existing file. - enables manual selecting of language of messages. If this flag is set, language of mesages will be defined by gic_ENGLANGUAGE flag (see below). If this flag is not set, all messages will be dislayed or logged in Russian when cyrillic code page is installed, or otherwise in English. - sets the language of all messages. If this flag is set, all messages will be displayed or logged in English, otherwise in Russian. This flag is used when, for example, messages always must be displayed in English. This flag is effective when gic_MANUALLANGUAGE flag is set.
gic_PRINTLOG
gic_ MANUALLANGUAGE
gic_ENGLANGUAGE
234
Default mode for displaying messages (if GD_SetInstdrvConfig() func tion was never called) is as follows: Display only general messages Do not log messages to a file Language selection mode is automatic according to a current code page. Identifying Version Number
void WINAPI GD_GetVersions(BOOL *bWinNT, BOOL *bRus, int *CurDrvVer);
In parameters:
bWinNT bRus CurDrvVer Buffer containing Windows indicator Buffer containing the Russian language indicator Buffer containing driver version indicator
Out parameters:
Not available
Description: When INSTDRV.DLL is loaded, it identifies Windows version (NT/2000/XP or 95/98/Me), current code page (system language) and Guardant driver version, which are supplied together with DLL (but not the one that might have been already installed in the system). All these data can be used for further checks. If any of the parameters has NULL value, it will be ignored.
235
Chapter 12. Automatic Protection in Every Detail
Chapter 12 Automatic Protection in Every Detail

You were introduced to automatic protection in the beginning of this Manual, when the Auto Protection Wizard was described. To set any such protection mode the facilities offered by the Wizard would be quite enough. However, if for any reason you are not satisfied with the Wizard, you can protect applications using automatic protection utilities inde pendently (by the way, Wizard also uses these utilities). This Chapter will describe how you can do it. Important
Please pay special attention to Guardant automatic protection principles, to the distinctive features of combined usage of different protection options, and to limitations connected with implementation of some of the options.
Automatic Protection Features

Guardant automatic protection offers a wide range of facilities. It allows you: To protect executable applications of any format and length (DOS applications of COM format are automatically converted into EXE format), including those that contain internal overlays or dynamically loadable data, applications compressed by LZEXE, PKLITE utilities, etc. To protect executable LAN applications. To protect applications those use DOS Extenders. To protect applications against computer viruses, including stealth viruses. To use the dongles ID for unambiguous identification of a particular dongle. To protect several software products using the program number to identify a particular product. To bind protected applications to the serial number and version of the dongle. To use a mask field for protection of a set of applications with further permission/prohibition of running certain applications from the protected set. This option may also be used from a remote computer.
237
Users Manual
Warning
To verify the dongles presence not only when the protected application is started, but also throughout the entire session, at specified intervals. To limit the number of executions of the protected application, turning it into a demo application and allowing for subsequent change of the executions counter or even for cancellation of this limitation. This option may also be used from a remote computer. To limit the protected application license term, providing the opportunity to correct time or even cancel this limitation. This option may also be used from a remote computer. To encode loadable part of the protected application by selecting the required encoding mode. To encode internal overlays and dynamically loadable data of the protected application; To protect any of DOS format files (LOTUS macros, AutoCAD LISP, databases, text and graphic files, etc.) against unauthorized access by binding them to the protected application. During protection, data files are encoded, and the protected application acquires a new feature allowing it to process encoded data correctly. To choose a mode of running protected DOS applications with encoded data files. To limit the number of protected network application copies that can be run in LAN simultaneously. To verify the presence of the network dongle on a stand alone computer, when the network is not available. To create protection that would be independent of the dongle type (Guardant Net, Guardant Stealth or Guardant Fidus).
Despite the wide capabilities offered by automatic protection, it cannot guarantee absolute safety of your software product. We strongly recommend that you improve protection with Guardant API!
Automatic Protection Principles

The automatic protection functioning principle employed in Guardant system is different from those used in other similar systems. In the basis of Guardant protection is vaccine*, designed as a universal external module. All protection functions are supported by this module. This gives an op portunity to fully unify the protection process, while abandoning various inconvenient and bulky methods of protecting non standard software.
238
Guardant automatic protection works as follows: a relatively small execu table module (internal vaccine*) is embedded into the body of a protected application. In the startup phase this module loads an external vaccine* from a separate file. This external vaccine carries out all necessary checks and conversions of the protected application code and runs it. This automatic protection principle offers a great advantage both to you and to the end user of a protected application. Imagine that a new version of the operating system has been released that requires improved protec tion. In this case, you just have to supply the customer with one relatively small file with a new version of external vaccine. This will help to ensure normal functioning of protected applications in the new OS version im mediately. Also, new vaccine versions that will contain improvements, new features, etc., will be delivered to you (and, consequently, to the customers) in the same way. Today the procedure of updating protection vaccines has even become automated. Use of external vaccine allows you to noticeably save your efforts and time. Besides, usage of external protection modules helps to improve protection against studying its functioning logic using debuggers. Guardant protection can work with three different vaccines:
NK.DAT NOVEX.EXE NOVEX32.DLL for DOS applications and data files, for 16-bit Windows applications, for 32-bit Windows applications.
An appropriate vaccine file should be supplied along with the protected application. Warning
When running a DOS application, NK.DAT vaccine should be located in the same directory as the application. When running a protected 16-bit Windows application, NOVEX.EXE vaccine should be located where it can be found by WinExec function (in the current directory, Windows system directory, directory containing the protected application, one of the directories from PATH list or one of network directories). When running a protected 32-bit Windows application, NOVEX32.DLL vaccine should be located where it can be found by LoadLibrary function (in the current directory, Windows system directories, directory containing the protected application, one of the directories from PATH list).
Automatic Protection Utilities

Protection is carried out by special utilities included in Guardant software package. You can use any of these utilities instead of Auto Protection Wizard, if that appears more convenient.
239
Users Manual
There are three different automatic protection utilities available:

NSDKEY.EXE NWKEY.EXE NWKEY32.EXE for DOS applications, for 16-bit Windows applications, for 32-bit Windows applications.
You may call the necessary utility with specified options either manually or from batch file. You need to distinguish between those options that can be used for your specified protection mode and those that are incompatible. The automatic protection utility embeds special module into the applica tion code, which enables external vaccine loading. Also, the utility per forms necessary conversions in the protected application in accordance with the specified protection mode. You can implement protection of two types: local (intended for protec tion of applications running on stand alone computers) and network (intended for protection of applications oriented for running in local net works). Local protection binds the application to Guardant Stealth (Guardant Fidus), and the network protection to a Guardant Net. Therefore, if you do not use Guardant Net, you cannot implement net work protection for your applications. Files Required for Protection To protect applications you will need the following: Automatic protection utility for the application format you use. External vaccine for the application format you use. File containing error messages (it has the same name as the automatic protection utility, but with MSG extension). NVCODES.DAT file containing information about your dongle access codes. All these files have to be located in the same directory. Important
In case NVCODES.DAT file is not available, applications will be protected with a demodongle.
Warning
NVCODES.DAT is required only for automatic protection and dongle programming utilities. Protected applications themselves do no need this file. Never pass this file to end-users!
Protection Procedure Before initiating protection, you should attach a dongle to the computer. Automatic protection utility call syntax:
<utility_name> [options] [path]files_list
or
<utility_name> [options] @[path]filename.fil
240
As soon as you specify any parameters required for protection in the command line, press <Enter>. The utility will start protection process, displaying appropriate messages when running. These include: Values of the dongles memory fields involved in the protection. These can include either values of the actually attached dongle or values you have specified in the options; A list of specified protection options (modes of binding to the dongle, application and data encoding, etc); A list of messages that can be displayed by the external vaccine during running of the protected applications; Name of the directory, into which protected applications and data files (destination path) will be placed; Messages about errors that occurred during protection. You can interrupt this procedure at any time by pressing <Esc>. The util ity will terminate protection of the current file and will stop running. Brief Description of Protection Options Let us have a look at the list of automatic protection options available. They are grouped by their types in tables, and each table, along with the name of the option and its brief description, indicates Guradant dongles that can be used with these options and applications that can be protected there with. Options of Specifying the Dongle Type
Option
/GS /GF /GN
Description
Bind to Guardant Stealth. Bind to Guardant Fidus. Bind to Guardant Net.
Type Dongle
Guardant Stealth Guardant Fidus Guardant Net
Application
All All All
Options of Binding to the Dongle

Option
/UI[=[0x]...] /US[=[0x]...]
Description
Unicity of the dongles ID (either specified value or the value from the ID field is used). Unicity of the dongles serial number (either specified value or the value from the serial number field is used). Version check (either specified value or the value from the dongles version field is used). Mask check (either specified value or the value from the dongles mask field is used). Application number check (either specified value or the value from the application number field is used). Do not use hardware algorithm #0. Leave the information about the key in the RAM.
Dongle
All All
Type Application
All All
/UV[=[0x]...] /UM[=[0x]...] /UN[=[0x]...] /NOA /SM
All All All All All
All All All All All
241
Users Manual
Option
/DC
Description
Limit the number of application executions (GP field of the dongle is used: in case the field contains 65535 no limitations are set, if it contains 0 the application will not run). Limit the applications license term (GP field of the dongle is used; in case the field contains 65535 no limitations are set, if it contains 0 the application will not run). Check for the dongles presence periodically at specified time intervals (check intervals range between 1 and 60 minutes). Allocate a license for the module #xx from the license table
Dongle
All
Type Application
All
/DT
All
All
/T=xx
All
All
/MN=xx
Net
All
Options of Encoding the Protected Application

Option
/CEN /CEN /CEP /CEF /OVL /CED
Description
Do not encode loadable application part. Do not encode the application. Partially encode loadable application part. Fully encode loadable application part. Encode application internal overlays. Carry out application dynamic encoding.
Dongle
All All All All All All
Type Application
DOS Win16, Win32 DOS DOS DOS Win16
Additional Application Protection Options

Option
/V /NOS /MR
Description
Protect the application against viruses. Do not strip the application. Forbid starting of several application copies.
Dongle
All All All
Type Application
All Win16, Win32 Win16
Options of Protecting Data Files

Option Description Type Dongle Application
All DOS
/DEP=... Assign a password for protecting data files. This parameter is mandatory if there are data files in the files list and/or if at least one option belonging to this group is present among the specified options. Password length range between 1 and 16 characters. /DEN Do not encode files created by the protected application. /DED Encode only created data files (by default). /DEA Encode all files created by the protected application. /DEU= Encode only files with the specified extensions created by the ext, ext, protected application. /DEE Encode data files in child processes. /PRN Prohibit printing of files. /AUX Prohibit transmission of files through the serial port. /UPS Unicity of data protection password based on the dongles serial #
All All All All All All All All
DOS DOS DOS DOS DOS DOS DOS DOS
242
Other Options
Option
/MSG=[path]*.msg /LBL=file.ext /OUT=D:\PATH
Description
Take vaccine messages from *.MSG file (utility_name.MSG by default). Change vaccine file name to FILE.EXT. Specify a path for copying the protected files (by default, files are copied into the directory containing source files). Prohibit displaying of messages generated by the protection utility.
Type Dongle
All All All All All All
Application
/Q /SND[=file.ext]
All
All Win32
Permit generation of audio error messages. All Messages are taken either from FILE.EXT file or from default NWKEY32.SND file.
Error Codes Automatic protection utilities can return the following error codes:
Common:
0 1 2 3 4 5 6 7 8 9 10 11 32 33 34 35 36 37 38 39 40 41 45 Process completed successfully Process interrupted by user Memory allocation error Invalid or unavailable option *.MSG file not found or access is denied File has non-supported format Reserved Dongle not found File is already protected File already exists Unable to copy file Dongle access error Unable to open FileName.Ext file Unable to change size of FileName.Ext file Unable to read FileName.Ext file Unable to write to FileName.Ext file Invalid value of alignment parameter Unable to protect data file Unable to protect DLL Too many segments (over 0FEh) Unable to find the first segment Unable to free space for making additions to the tables NWKEY32 (NWKEY) utility should be used to protect this application
Only for NWKEY.EXE and NWKEY32.EXE:
243
Users Manual
Only for NSDKEY.EXE:

64 65 66 67 68 69 70 71 72 73 74 75 Unable to protect file Conflicting or repetitive options detected Password for protecting data files not found. Length of password for protecting data files exceeds 16 characters Length of extensions list exceeds 30 characters Length of vaccine message exceeds 59 characters Files to be protected (encoded) are not specified File not found *.FIL file not found Destination path not found Unknown error Application has no internal overlays
Limitations When protecting DOS applications: Protection of resident software (TSR) is not recommended, especially when operating in the mode of linking data files. You cannot change creation time of protected DOS data files independently. This can be done only by the protected applications that work with the encoded data. Otherwise, the files will be processed by the protected applications incorrectly. You cannot protect files with DAT extension using the automatic protection utility. This helps to prevent accidental encoding of the vaccine file, which has the same extension. If you need to protect files with DAT extension, you should rename them before protecting them, and then restore their names after protection is complete. When protecting Windows applications: Protection with /CED option (dynamic encoding of 16 bit applications) is based on a unique algorithm. This powerful protection tool enables decoding of an application in its running phase. However, be careful when using this option, because applications protected with /CED will not run under Windows 95/98/Me, and some non standard applications will not run under other MS Windows OS either.
244
Automatic Protection Options

Let us take a more detailed look at the automatic protection options. Be low you will find a full list of automatic protection options. To make it easier for you to choose a protection option, each option is supplied with explanatory notes. Options for Specifying the Dongle Type /GS, /GF, /GN Options Protected application format:
DOS/Win16/Win32.
Description: You can specify one or more options from this group at one time in any combination. In the latter case, protected application will be run only if a Guardant family dongle of the type you specified is attached to the com puter. For example, if all options of this group are set the protected appli cation will search for the dongle as follows: Search for Guardant Stealth, Guardant Fidus or Guardant Net on a stand alone computer. Search for Guardant Net in a local network. The search will be stopped on either stage as soon as any of specified don gle types that matches search conditions (specified by the dongle binding options as described below), is found. If the protected application keeps polling the dongle in the running phase, all calls will be addressed only to that dongle type, which has been found during the first call. This will greatly reduce the time of communication with the dongle when, for ex ample, it is periodically checked. If, during protection you have used options from this group, you will be able to run the protected application with your dongle only: when pro tected, the application adjusts to the access code of specified dongle that was attached to the computer at the time of protection. Therefore, when protecting the application, you should attach one dongle deriving from the following rule: For /GS option Guardant Stealth or Guardant Net For /GF option Guardant Fidus For /GN option Guardant Net When you specify any of these options, the application will automatically obtain reliable protection against debuggers.
245
Users Manual
Important
If you do not specify any option from this group, the application will not be bound to the dongle (i.e., it will run even when none of the dongles is attached to the computer). Still, it will be protected against debuggers. You can use this feature, for example, to protect applications that work in demo mode when used without the dongle.
Examples:
nwkey.exe /GF myprog.exe nwkey32.exe /GS /GF myprog.exe
In the first example, the protected MYPROG.EXE Win16 application will run if any of Guardant Fidus dongles (additional dongle search condi tions are not specified) is attached to the computer. In the second exam ple, the protected MYPROG.EXE Win32 application will run if any of Guardant Stealth or Guardant Fidus dongles (additional dongle search conditions are not specified) is attached to the computer. Options of Binding to the Dongle Options of this group allow you to adjust the protected application to the parameters of the dongle that it should work with (or, in other words, specify additional dongle search conditions), as well as specify distinctive features of protection used for this application. You may use options of this group in any combination, as well as combine them with options from other groups, except for cases described below. Important
If neither /GS, /GF nor /GN option is specified, then all options of this group will be unavailable (they will become useless, because the application will not be bound to any dongle at all). Still you can use options from other groups (application encoding, data file protection, etc.).
Unicity of the Dongles ID /UI[=[0x]...] Protected application format:

DOS/Win16/Win32
Dongle type:
Any
Description: This option is used to bind the application to the unique parameter of a dongle belonging to Guardant family, i.e., to its identification number (ID). The application protected with this option can be run only if the dongle that has been used to protect the application is attached to the computer (or whose ID has been specified in the option).
246
If you have specified /UI option, the application will be bound to the ID of the dongle that was attached to the computer at the time of protection. To bind the application to the ID of any other of the dongles, you should specify its value in the option after = sign. To represent the ID in hexa decimal format, prefix 0x should be specified. You can find out IDs of Guardant Stealth, Guardant Fidus and Guardant Net dongles by running dongle search utilities such as CHKNSK, CHKNSKW or CHKNSK32 (the value is in brackets next to the dongle manufacturing date), or NSKUTIL dongle programming utility. Warning
Dongles ID is a unique value. There cannot be two dongles in Guardant family with the same IDs! You can neither change the ID of the dongle nor manufacture a new dongle with the required ID. Therefore, you should be aware that in case a dongle is damaged by the end-user, you would have to replace not only the dongle but the protected application as well. Also, this protection option will not work correctly in case you bind the application to several dongles of different types simultaneously, since they have different IDs. Be careful when using this hard and fast protection method!
Examples:
nwkey.exe /GF /UI myprog.exe nwkey.exe /GS /UI=912459016 myprog.exe
In the first example, the protected Win16 application MYPROG.EXE will run only with Guardant Fidus (/GF option) that was attached to the computer during protection of the application (/UI option, the ID of the attached dongle is used). In the second example, MYPROG.EXE will run only with that Guardant Stealth (/GS option), whose ID is 912459016 in decimal format (/UI option is 912459016). Unicity of the Dongles Serial Number /US[=[0x]sssss] Protected application format:
DOS/Win16/Win32.
Dongle type:
Any
Description: To bind the application to any particular dongle /US option is used as well. In this case the protected application will run only if a dongle is at tached that has the same value in the serial number field as has been speci fied at the time of protection of the application. The value of the serial number can vary between 0 and 65535.
247
Users Manual
This protection method is more flexible than the previous one: it uses the parameter of the dongle that you specify using a special program. If an end user accidentally damages the dongle that has been used to protect the application, you can easily produce a dongle with the same serial number and replace the damaged unit. Examples:
nwkey.exe /GS /US myprog.exe nwkey.exe /GN /US=0xFFFE myprog.exe
In the first example, the protected Win16 application MYPROG.EXE can be run only with Guardant Stealth that was attached to the computer at the moment of protecting the application (/US option, serial number of the attached dongle is used). In the second example, MYPROG.EXE can be run only with Guardant Net, whose serial number is FFFE when pre sented in hexadecimal format (/US option is 0xFFFE). Checking the Version of the Protected Application /UV[=[0x]vvv] Protected application format:
DOS/Win16/Win32.
Dongle type:
Any
Description: /UV option is used to bind applications to the value written in that field of the dongle, which contains application version. This method is good if you often release new versions of the software. It helps to easily solve the issue of updating customers software. Let us imagine that originally the version of the software product was 1.0. Then you should specify /UV=10 option during its protection. You should also enter this value into the version field of the dongle to be used for this product version. Later, when you release a new version of the software product (we will call it version 1.1) and wish to update the software of your old customers, you will not have to supply them with a new dongle. Instead, you will sim ply protect a new version by specifying /UV=11 option. The customer will be able to correct the version field in his dongle using the remote dongle programming utility (this mechanism is described in greater detail in Chapter 11 Remote Programming of Guardant Dongles). After that, the user will be able to take advantage of both new and old versions of the software product.
248
In fact, the application protected with this option not only verifies the presence of the dongle but also analyzes its version field contents. The ap plication will run only if the version specified in the dongles field is higher or same as the version that you specified during protection of the applica tion. Thus, if the customer somehow gets a protected copy of the new ver sion of the product, he will not be able to run it until he corrects the ver sion field in his dongle. He will not be able to do this by himself since he does not have access to the information required for this operation. To specify a version in /UV parameter, a value in the range between 0 and 255 is used. Example:
nwkey.exe /GS /GF /UV myprog.exe nwkey.exe /GS /GF /UV=11 myprog.exe
In the first example, MYPROG.EXE Win16 application is bound to the version number written in the field of the attached dongle (let us imagine that the value written in the field of the dongle was 10, i.e., version 1.0). The protected application will run if Guardant Stealth or Guardant Fidus is attached, whose version field contains 10 or a higher value. In the sec ond example the updated MYPROG.EXE application version 1.1 is pro tected (/UV=11 option). In this case, the application will run after the end user enters 11 in the version field of his Guardant Stealth or Guard ant Fidus. He will be able to run both the old and new versions of MYPROG.EXE. Checking Mask /UM[=[0x]mmmmm] Protected application format:
DOS/Win16/Win32.
Dongle type:
Any
Description: If you have designed a product composed of several independent software modules, you can use /UM option for its protection. This option will al low you to either permit or forbid running of specific modules out of your software package. For example, you have created an electronic interpreter composed of three programs: MYPROG1.EXE a demo version with limited capa bilities, MYPROG2.EXE English Russian interpreter and MYPROG3.EXE French English interpreter.
249
Users Manual
Let us imagine that your practice is to first distribute a demo version, and then customers additionally purchase from you those interpreter programs that they are interested in. Usage of /UM option will make the task of dis tributing the product easier. Applications protected with this method use the dongles mask field as a set of semaphores, and each of the semaphores either enables or disables running of the application with the number assigned to it during protec tion. When started, the program checks the value of the corresponding bit in the dongles mask field, and if it equals 1, the application will run prop erly. At the time of protection you should specify the number for each protected application in /UM option (you can present it either in decimal format or in hexadecimal format using 0x as prefix). For example, let us assign number 1 to MYPROG1.EXE, number 2 to MYPROG2.EXE and number 4 to MYPROG3.EXE, since bit #0 corresponds to number 1, bit #1 corresponds to number 2, and bit #2 corresponds to number 4. In the version field of the dongle we will enter number 1. In this case, you will be able to supply all three applications together with your software. However, the customer will be able to run only MYPROG1.EXE, because the mask field of his dongle will contain the value that corresponds to this application number only (i.e., 1). If in the future, the customer also wishes to use MYPROG2.EXE, he will change the value in the mask field of his dongle to value 3 on the basis of the information received from you and using the remote programming utility. From that time he can run not only MYPROG1.EXE, but also MYPROG2.EXE, since value 3 entered in his dongle corresponds to bits #0 and #1. The capacity of the dongles mask field is 16 bits. During protection it is advisable that you choose the numbers for the applications that corre spond to the single non zero bit set, i.e., 1, 2, 4, 8, 16, 32, 64, etc. Assign ing of other numbers may lead to problems during the checking of the mask. Example:
nwkey.exe /GS /UM=1 myprog1.exe nwkey.exe /GS /UM=2 myprog2.exe nwkey.exe /GS /UM=4 myprog3.exe
The example above demonstrates calling of the utility for protecting Win16 applications using Guardant Stealth.
250
Checking Program Number /UN[=[0x]nnn] Protected application format:

DOS/Win16/Win32.
Dongle type:
Any
Description: This option will be useful in case you distribute several different software products (for example, electronic accounting and inventory management software) and protect all these products using Guardant dongles. In this case, you can bind them to the same parameters of the dongle, still mak ing it impossible to use the same dongle for both products. You should assign a number to each product (let us, for example, assign number 0 to electronic accounting application and number 1 to the inventory management application) and protect them with /UN option. Then you should enter 0 value in the application number field of the dongles used for the electronic accounting application, and 1 value for the inventory management application. All of the remaining protection parameters can be made identical. An application protected with this method will check the value in the application number field; thus, it will be impossible to run the electronic accounting application with the dongle used for the inventory management application, and vice versa. Allowed values for the application number range between 0 and 255. All dongles sold to you contain 0 value in their application number field. Therefore, you can use this option even if at the moment you are distrib uting only one software product. In the future, the number of your prod ucts may increase, and then you will not have to worry about protecting new products against unauthorized use by the old customers. Example:
nwkey32.exe /GN /UN=0 myacctg.exe nwkey32.exe /GN /UN=1 myinvent.exe
This example demonstrates calls made to the utility used for protecting Win32 applications with Guardant Net.
251
Users Manual
Do Not Use Hardware Algorithm # 0 /NOA Protected application format:

DOS/Win16/Win32.
Dongle type:
Guardant Stealth, Guardant Fidus, Guardant Net.
Description: By default, applications protected with Guardant Stealth, Guardant Fidus or Guardant Net based automatic protection use hardware algorithm #0 (AutoProtect) of the dongle. This greatly increases the strength of auto matic protection since in this case data conversion element is imple mented. Hardware algorithm #0 is always available in the dongles sold to you. The protected application uses the response of this algorithm when verifying the legality of the running copy. By using NSKUTIL utility you can change the determinant of algorithm #0 in the dongle, and then the specific form of this algorithm will become unknown to anyone but you. By modifying determinants, you can either create identical algorithms for all the dongles (for this reason their determinants should be the same) or create a unique algorithm in each dongle. However, since protection util ity utilizes the algorithm of the actually attached dongle, you should en sure that by the time when protection is started, algorithm #0 has already been entered in the dongle with the parameters you require. Also, when replacing end users dongle you should ensure that algorithm #0 has the same determinant in the new dongle as in the old one. In some cases, you will have to abandon this hardware algorithm. This happens when you remove algorithm #0 from the dongle and replace it with a different type algorithm, or when despite our warnings you decide to give up algorithms altogether and allocate the entire memory for some other purposes. Then the automatic protection will be functioning cor rectly only if you make it function without using hardware algorithm #0. To abandon the usage of an algorithm by the automatic protection you should run NSDKEY utility with /NOA option. Example:
Nwkey32.exe /GS /NOA myprog.exe
Win32 application protected by this method will not use the hardware al gorithm when checking Guardant Stealth.
252
Keeping the Information on Dongles Parameters in RAM /SM Protected application format:
DOS
Dongle type:
Any
Description: This option allows you to set the following mode of running of the pro tected application: After checking the presence of the dongle, the protected application writes the information about parameters of the attached dongle to the PCs RAM. The information is written to the following addresses: Information about Guardant Stealth, Guardant Fidus and Guardant Net:
Address
0:0218h 0:0219h 0:021Ah 0:021Eh 0:0222h 0:0223h 0:0224h 0:0226h 0:0228h
Size in bytes
1 1 4 4 1 1 2 2 2
Value
4Eh 53h -
Purpose of the Field

Information availability flag Public Code in numerical form Dongles ID Application number Version Serial Number Mask GP counter value
All addresses and values are given in hexadecimal format. You can use data that have been written in RAM when, for example, set ting values of parameters for the API functions. After the session is over, the protected application erases this information from the memory. Example:
nsdkey.exe /GS /SM myprog.exe
Example of /SM option usage when protecting MYPROG.EXE DOS application with Guardant Stealth.
253
Users Manual
Limiting the Number of Application Executions /DC Protected application format:

DOS/Win16/Win32.
Dongle type:
Guardant Stealth, Guardant Fidus.
Description: By using /DC (Decrement of Counter) option you can easily transform the executable application into a demo application by limiting its lifetime. In the executions counter (GP) field of the dongle enter a number of times a user can execute this particular application. Each time the protected application is started it decrements by 1 the counter value written in the GP field of the dongle. When the value reaches 0, the application will stop running. This mode provides the following two advantages: First, you can sell software with a limited number of executions. For ex ample, a user pays for the first one hundred sessions of working with the application; in this case you protect the application with /DC parameter and enter 100 in the GP field of the dongle. When the user uses this re source up to the end, on the basis of a number answer* that you provide to him, he will correct the GP field of his dongle using the dongle remote programming utility by entering a new value for the resource (for example another 100 executions). Thus, it looks as if you were to lease out your software and collect a rental fee from users. Secondly, you can easily transform the demo version of the application into an operational non demo version. In this case, after a user pays the cost of a full version, you provide him with a special number answer, which he will use to enter value 65535 into the GP field of his dongle. If the GP field contains this value, the protected application will not decre ment it, automatically turning into an operational protected application. Thus, to limit the number of times the application is used you should pro tect it with /DC parameter, and enter the value ranging from 1 to 65534 in the GP field. The number answer is a unique value, and it depends on the number of additional executions requested by the user (in the last example it de pended on value 65535).
254
The end user can always determine how many times he can run the appli cation. To do that he will need to run the utility to search for the dongle of required type (you will have to supply one or more of these utilities to gether with the software product). The information the user needs will be indicated in the Executions counter field. Important
This option is not available in Guardant Net-based network protection.
Warning
All protected applications bound to one dongle in this mode, decrement the same counter. If, for example, software product consists of two protected applications MYPROG1.EXE and MYPROG2.EXE, the GP field of the dongle contains 5, and if the user has already started MYPROG1.EXE three times, then he will be able to start MYPROG2.EXE application only twice.
Example:
nwkey.exe /GS /NOA /UV=10 /DC myprog.exe
Here is an example of protecting MYPROG.EXE Win16 application ver sion 1.0 by Guardant Stealth without using algorithm #0 (/NOA option), but applying product version check (/UV=10 option) and limiting the number of its executions (/DC option). MYPROG.EXE will run if Guardant Stealth is attached, that has 10 or a higher value in the version field, and it stop cease running when the value of the GP counter reaches 0. Limiting the Applications License Term /DT Protected application format:
DOS/Win16/Win32.
Dongle type:
Guardant Stealth, Guardant Fidus.
Description: Guardant protection allows you to supply applications with their license term limited. The idea of this protection method is the following. You protect the appli cation using a dongle and specify the applications license term (for ex ample, 5 hours and 30 minutes). The user works with this application for 5 hours 30 minutes of net time (the dongle counts only the time when the application is running). Upon the expiration of this period, the applica tion will stop running. However, a user can extend the applications li cense term or obtain a right to run the application within the unlimited timescale (on the basis of number question / number answer method).
255
Users Manual
Protection in this mode is activated with /DT (Decrement of Time) op tion. In the GP field of the dongle you should enter the protected applications license term. NSKUTIL and NSKTUTIL utilities can be used to write the time into the dongle (for Guardant Stealth and Guardant Fidus). You should not pass this utility to the end users. In order to indicate the appli cations license term left and to extend it remotely GSREMOTE or NSKTCHK utility can be used (for Guardant Stealth and Guardant Fi dus). You should pass this utility to the end user if you plan to extend or cancel the time limit. The procedure of using these utilities is described in detail in Correcting the License Term When running the protected application the time counter written in the GP field of the dongle will be periodically decremented (at fixed inter vals). When the applications license term expires, a message will be dis played or audio signal produced at the same interval. The protected appli cation runs normally until the session is over, however re running of this application would be impossible. If, during a regular call the dongle has not been located, the application will be locked until the user attaches a dongle and presses the retrial but ton. Important
This option is not available in Guardant Net dongle-based network protection. Since both /DT and /DC options (decrementing the application executions counter) use the same field (GP field) of the dongle, they must not be used for the software protection simultaneously. Thus, it is wrong to call the protection utility with both /DC and /DT options. Besides, /DT and /T=xx options (verifying the presence of the dongle against timer, for more details see below) are incompatible. The matter is that /DT option includes the capabilities of /T=xx option, being its extended option. Therefore, there is no sense in using both options when protecting applications. Hence, it is wrong to call protection utilities with both /DT and /T=xx options.
Warning
All protected applications that are bound to one dongle in this mode, decrement one and the same time counter. If, for example, the software product consists of two protected applications MYPROG1.EXE and MYPROG2.EXE, the dongle is programmed for three-hour running, and a user has already run MYPROG1.EXE for two hours, he will be able to run MYPROG2.EXE application for just another hour.
Example:
nwkey32.exe /GS /DT myprog.exe
Example of protecting MYPROG.EXE Win32 application using Guard ant Stealth in the license term limiting mode. MYPROG.EXE can be run until the value in the GP counter field of the dongle reaches 0.
256
Checking Periodically for the Dongles Presence /T=xx Protected application format:
DOS/Win16/Win32.
Dongle type:
Any
Description: You may check for the presence of the dongle not only when the pro tected application is started, but also during the running session at the in tervals that you specify. Such opportunity is provided by /T=xx option, where xx is the value of the interval in minutes between two checks. You can set check intervals in the range between 1 and 60 minutes (only integer values are allowed). If, during a regular check the dongle is not found, the protected applica tion will display a corresponding message or produce an audio signal. The application will be locked until the user attaches a dongle and presses the retrial button. Important
/T=xx and /DT options are incompatible (for more details see above).
Example:
nsdkey.exe /GN /T=05 myprog.exe nsdkey.exe /GN /T=5 myprog.exe
Equivalent examples of protecting MYPROG.EXE DOS application us ing Guardant Net. MYPROG.EXE will poll the dongle during the entire running session at five minute intervals. Using License Management System: /MN=xx Protected application format:
DOS/Win16/Win32
Dongle type:
Guardant Net
Description: This option allows you to take account of licenses of each module in a muti module application. Let us suppose that the protected software package consists of four mod ules: MYPROG1.EXE Accounting, MYPROG2.EXE Wages, MYPROG3.EXE Personnel, MYPROG4.EXE Office.
257
Users Manual
Using this option you can control any module. To make this control pos sible you need to protect all modules, one by one, using the /MN= op tion, where is the number of the module (valid numbers are 0 to 127). If any number is used which exceeds the number of modules in the license table, then an error code 10 (License counter of Guardant Net exhausted) will be returned at the attempt to login the application in to the Guardant Net server. Important
To be able to utilize the license management system you need to create a special License table field in the dongles memory and indicate in this table the number of modules and the license limits per module.
When applications that have been protected in this mode are started, they log in to the Guardant Net server and capture a certain license from the li cense table. Now the end user can start modules of the protected applications only on a certain number of workstations defined by the vendor. Example:
nwkey32.exe /GN /MN=00 myprog1.exe nwkey32.exe /GN /MN=01 myprog2.exe nwkey32.exe /GN /MN=02 myprog3.exe nwkey32.exe /GN /MN=03 myprog4.exe
These are the examples of calling the utility for the protection of Win32 applications by a network dongle required for the above example. Protected Application Encoding Options Options of this group allow you to encode the body of protected applica tion using different methods, thus greatly improving protection strength and hiding the application running logic. These options can be combined with any other automatic protection options (including when protection is implemented without binding to the dongle), except for cases specifically described below. Encoding of Loadable Part of Application /CEN, /CEP, /CEF Protected application format:
DOS/Win16/Win32 (/CEN option). DOS (/CEP, /CEF options).
Dongle type:
Any
258
Description: When protecting a DOS application you can encode its loadable part (i.e., the part of the executable (ok) file located in RAM). This will greatly im prove the strength of protection against disassembling and analyzing the application running logic with a debugger. There are three possible options: Disable encoding of the loadable part (/CEN option is set by default for DOS applications). Encode application partially (/CEP option). Encode the entire loadable part (/CEF option). Use /CEF option to achieve maximum protection against disassemblers. If the license term of the application protected with this option has sub stantially increased, you can try to protect it using /CEP option. In this case, only a half of the application loadable part will be encoded. If your application is of a typical format and encoding of its loadable part affects its running, use /CEN option (specifies that the application load able part should not be encoded). This mode is set by default for DOS ap plications, i.e., when none of the three options is specified. Important
Note that only one option out of the three can be specified at a time, i.e., a call of the protection utility, for example, with /CEN and /CEP options will return an error message. When protecting 16- and 32-bit Windows applications only /CEN option is available to you, specifying that the application should not be encoded. By default, the protection utility itself chooses the optimal method of encoding, determines fragments of Windows application to be encoded and then encodes them.
Example:
nsdkey.exe /GS /T=1 /CEF myprog.exe
This is an example of protecting MYPROG.EXE DOS application with Guardant Stealth. MYPROG.EXE will have fully encoded loadable part (/CEF option). The presence of Guardant Stealth will be checked by the application during its running session at one minute intervals. Encoding Internal Overlays /OVL Protected application format:
DOS.
Dongle type:
Any
259
Users Manual
Description: You may also carry out automatic protection of internal overlays of DOS applications. They are encoded using a unique algorithm, and the pro tected application can decode them dynamically when reading from the disk. This considerably improves protection against attacks and, in some cases (for example, for applications written on FoxPro language), it is the only method of fighting against program decompilation. To protect DOS applications in this mode /OVL option is used, which is specified during calling of NSDKEY.EXE utility. This option can be specified in combination with any /CEx options and any other protection options. Protection utility itself analyzes whether the protected application has in ternal overlays and loadable data. In case NSDKEY does not detect them, a message will be displayed and the application will be protected without /OVL option. Example:
nsdkey.exe /CEF /OVL myprog.exe
MYPROG.EXE will have fully encoded loadable part (/CEF option), as well as encoded internal overlays (/OVL option). Thus, the entire applica tion body except for its header will be encoded. In this case, the applica tion will not be bound to the dongle (no option to specify the dongle type is set: /GF, /GS or /GN). Dynamic Application Encoding /CED Protected application format:
Win16.
Dongle type:
Any
Description: This option allows you to dramatically increase the strength of protected 16 bit Windows applications against debuggers. Warning
Applications protected with /CED option do not run in Windows 95/98/Me, and some non-standard applications even in other MS Windows versions.
Example:
nwkey.exe /GS /CED myprog.exe
This is an example of protecting MYPROG.EXE Win16 application with Guardant Stealth applying dynamic encoding of the application body.
260
Additional Application Protection Options Options of this group allow you to set some additional application protec tion modes. These options can be specified together with any other auto matic protection options (including when protection does not support binding to the dongle), except for cases specifically described below. Antiviral Protection /V Protected application format:
DOS (with application self-recovery capability). Win16/Win32 (without application self-recovery capability).
Dongle type:
Any
Description: This option allows you to set a mode that provides for the protection of an application against computer viruses. Protected DOS application becomes capable of self recovering after it has been infected either by ordinary or by stealth viruses. It means, that when the application is started it checks for its data integrity, and in case it de tects that it has been infected it will display a message indicating the viruss length in bytes:
WARNING: VIRUS detected Try to kill? (Y/N) 1024
To eliminate the virus, Y should be pressed. If damages caused by the vi rus are recoverable, the vaccine will remove the virus from the protected application and recover its original image. Win16 and Win32 protected applications are not capable of self recovering due to their nature. However, like DOS applications, they check for their data integrity when started and send alerts if infected. In this case, it is recommended that the application be recovered from the distribution disk or backup copy but not cured using antiviral programs. Example:
nsdkey.exe /V myprog.exe
This is an example of protecting MYPROG.EXE DOS application with out binding it to the dongle, but implementing protection against com puter viruses (with self recovery capability).
261
Users Manual
Do Not Strip the Application /NOS Protected application format:

Win16/Win32.
Dongle type:
Any
Description: Usually, the utilities employed for protection of Windows applications remove (or strip) data that do not comprise application segments. In most cases this allows you to delete some past debugging data and even save on the size of the protected application: the file will become smaller than be fore protection. However, in some cases such stripping can produce nega tive impact on further running of applications, since some of them may store their vital data in a non standard location of EXE file. For example, in Windows applications written in FoxPro language, the byte code to be interpreted is stored not in a certain segment, but at the end of EXE file. /NOS (NO Strip) option allows you to deactivate the stripping operation. If a Windows protected application runs incorrectly you can protect it with /NOS option. Example:
nwkey32.exe /GN /NOS myprog.exe
This is an example of protecting Win32 application with Guardant Net. During protection of the application, the data that do not comprise its segments will not be deleted (thus the application will not be stripped). Prohibiting the Running of Several Application Copies /MR Protected application format:
Win16.
Dongle type:
Any
Description: Use /MR option so that an end user could not start more that one copy of protected application on the same computer. In case the application de tects that at least one more copy of it already exists in the computer mem ory, it will stop running and will display a corresponding message. Important
This option can be used during protection of 16-bit Windows applications only (i.e., it is available only in NWKEY.EXE protection utility).
262
Example:
nwkey.exe /GF /MR myprog.exe
This is an example of protecting MYPROG.EXE Win16 application with Guardant Fidus dongle. Only one copy of MYPROG.EXE can be run on any particular computer. Data Files Protection Options Options of this group allow you to arrange for protection of DOS format data files that are in use by the protected application. If, during calling the protection utility you specify one or more of the options listed above, the applications, after they have been protected, will acquire a new capability of processing encoded data files. If apart from application names you specify the names of data files in the command line, these files will be en coded using the password that you have specified. The protected application will be able to carry out dynamic (on the fly) decoding of its data files while reading them from disk, and dynamic en coding while writing them to the disk. Important
Options of this group are available only during the protection of DOS applications (i.e., they are supported by NSDKEY.EXE utility only). Protection of data for Windows applications is much more complicated. The matter is that due to the nature of Windows OS there are a lot of ways whereby the hackers can obtain decoded copies of protected data files. Developers of some protection systems offer certain solutions to solve this problem, however time has shown that they are not universal or reliable enough - at least to withstand the Russian hackers. Developers of Guardant protection already possess some technologies that provide reliable data protection for Windows applications. Currently, these technologies are being improved to make them more convenient to use.
Password Setting for Data Files Protection /DEP=password Protected application format:
DOS.
Dongle type:
Any
Description: This is a basic and mandatory option to be used during protection of data files. By using this option, you can assign a password to encode with the data files, and that will serve as a password to access the encoded data in the running phase of the protected application. The size of the password should not exceed 16 characters.
263
Users Manual
Note that the protected application can process correctly only those data files that are encoded using the password that has been specified by /DEP=...option, or any non encoded data. Warning
During running of the protected application, the time of creation of encoded data files is analyzed. Therefore, you may not change creation time of these files independently after they have been protected! This can be done only by the application that works with the encoded data. Otherwise, the protected applications will cease to process data files correctly. Still, if this happens you can decode such file by running NSDKEY.EXE utility and specifying the same password in /DEP=... parameter as was used at the time of file protection.
Example:
nsdkey.exe /GS /DEP=password myprog.exe mybase.dbf
This is an example of protecting MYPROG.EXE DOS application using Guardant Stealth, further allowing using it for processing of MYBASE.DBF encoded data file. The data file will be encoded with password password, and using this password the protected application will decode the file when reading it from the disk and encode when writing it to the disk. Setting Data File Processing Mode /DEN, /DED, /DEA, /DEU=ext,ext,... Protected application format:
DOS.
Dongle type:
Any
Description: MYPROG.EXE application, which was protected in the previous exam ple, can now process encoded data files. This means that any already ex isting data file that has been encoded using the correct password will be correctly decoded when read from the disk and encoded when written to the disk. Also, it is possible to encode new files created by the application. Guardant protection provides several options of working with the en coded data files:
/DEN /DED /DEA /DEU=ext,ext,...
Do not encode newly created files. Encode only newly created data files, except for executable files (used by default). Encode any newly created files (including execu table files) Encode only files with specified extensions.
264
Since these options are focused on the same task, only one of the options can be specified during software protection. 1. Let us imagine that the application permits only viewing of files (for ex ample, the application is a kind of a reference system). Then in order to protect it all you need to do is use /DEN option, for example:
nsdkey.exe /GS /DEP=password /DEN myprog.exe mybase.dbf
In this case, MYPROG.EXE application will be able to process correctly MYBASE.DBF encoded database, however, all newly created data files will not be encoded (for example, service files). We recommend that you do not to use this mode for protecting applica tions in which a user can change data files (edit, copy, save on disk, etc.). The matter is that many applications after editing the file create it anew. Therefore, after the first edit of the data file it will be re written in an original form. Moreover, if the application provides a facility for copying files, then it will be even easier to get a non encoded data file you will just have to copy it, and this created copy will be decoded. 2. Protection mode set by /DED option allows the protected application not only to work with the encoded data, but also create new data files (i.e., files with any extensions except for EXE, COM, SYS and BAT) in an encoded form. This mode provides a more powerful protection of data files and is recommendable when protecting text and graphic editors, compilers, DBMS and other software products. To protect applications and data in this mode you should use the line similar to the following:
nsdkey.exe /GS /DEP=password /DED myprog.exe mybase.dbf
Files with EXE, COM, SYS or BAT extension will not be encoded by the application protected in this mode. This mode is set by default (i.e., when none of /DEN, /DED, /DEA or /DEU options is specified in the command line). 3. The mode specified by /DEA option provides a more powerful protec tion of data files. The application protected in this mode will encode any files it creates: both data files and executable files. This is suitable when you protect DBMS or text editor. If you wish to protect, for example, a compiler, you will probably dislike the fact that after protection it will be gin to create encoded executable files, which, of course, will not start! Therefore, before starting protection process you should carefully con sider which data protection method to choose, taking into account the tasks that are to be solved by the software. You will most likely have to agree to a reasonable compromise between reliability of data protection and considerations of convenience. To protect in this mode you should call the protection utility with the fol lowing parameters:
nsdkey.exe /GS /DEP=password /DEA myprog.exe mybase.dbf
265
Users Manual
4. The mode specified by /DEP option allows you to determine which file types will be created by the application in encoded form. To protect the software in this mode you should call the utility with /DEU=ext,ext,... parameter, for example:
nsdkey.exe /GS /DEP=password /DEU=doc,db,.,dbf myprog.exe base.dbf
In this case, MYPROG.EXE application, in its creation phase, will en code only files with extensions such as DOC, DB, and files without ex tension (marked with . in the extension list) or DBF. All files with other extensions will be created in non encoded form. This is useful when the application generates, for example, report files, which are not to be en coded. The size of extension list (i.e., the string following = sign in /DEU=... option) should not exceed 30 characters. Encoding Data Files in Child Processes /DEE Protected application format:
DOS
Dongle type:
Any
Description: Usually, if any unprotected application is run from a DOS application protected through data files linking, and then processing of protected data will be deactivated (i.e., child processes will not run correctly with en coded data of parent processes). This considerably increases reliability of protection of data files for those DOS applications that are capable of launching child processes (for example, applications which can enter OS Shell). In this case, the user will not be able to get a decoded copy of data file by running, for example, Norton Commander from the protected ap plication, and using Guardant vaccine handlers that are present in the memory. However, in some cases this mode of processing encoded data is unac ceptable; for example, if the software product comprises two EXE modules, of which one is protected through data file linkage, and the other is not protected at all. In this case, if the unprotected application is to run from the protected application and use the same encoded data files, deactivation of decoding of these data files will make running of the un protected application impossible (it will process the encoded data incor rectly).
266
To avoid this, a method of protection has been created that permits proc essing of encoded data even when running child processes. Thus, the un protected application will be able to process the encoded data in the same mode as the protected application that has launched it. This mode is set by /DEE (Data Encryption after Execution) option dur ing the calling of NSDKEY.EXE utility. This option can be specified in combination with any other data file pro tection options. Note that safety of protected data files is somewhat decreased in case the application, from which the child process is to be run, is protected with any /DEx option, except for /DEA (Data Encryption All, which means encode any created data files) option. Therefore, we recommend that you use /DEA option in combination with /DEE option (see example be low), or protect both parent and child applications through data file link age (and using the same password, so that both applications could use the same encoded data files). In this last case /DEE option is not needed. /DEE option should also be used if encoded data files are processed by external software overlay started from the main protected application (typical examples include: AutoCAD, P CAD systems as well as EXE files created using FoxPro in Compact mode). Example:
nsdkey.exe /GS /DEP=password /DEA /DEE myprog.exe mybase.dbf
This is an example of protecting MYPROG.EXE DOS application though binding to Guardant Stealth and with the capability of processing data files. MYBASE.DBF file is encoded with password password, and MYPROG.EXE encodes any created files using this password. In case any unprotected application is started from MYPROG.EXE, it will also be able to work with the encoded data of MYPROG.EXE application (/DEE option). Prohibit File Printing /PRN Protected application format:
DOS.
Dongle type:
Any
Description: If you need to prohibit files printing and forbid copying the contents of the screen, you should use /PRN (Forbid printing) option when protecting the application.
267
Users Manual
Important
Application protected in this mode forbids printing of any files: both encoded and nonencoded.
Example:
nsdkey.exe /GS /DEP=password /PRN myprog.exe mybase.dbf
In this example, MYPROG.EXE DOS application will encode created data files (/DED option is specified by default), and you will not be able to print out any of the files. Copying the contents of the screen in this appli cation will also be prohibited. Prohibit File Transfer via Serial Port /AUX Protected application format:
DOS.
Dongle type:
Any
Description: Specifying of /AUX option at the time of protection allows you to set such mode of running of the protected application that will prohibit files trans fer via serial port. Important
An application protected with this option prohibits transmission of any files (both encoded and non-encoded) via the port. Besides, this protection will be ineffective in those applications, which transmit data directly to the port.
Examples:
nsdkey.exe /GS /DEP=password /AUX myprog.exe mybase.dbf
As you may have noticed, /PRN and /AUX options can be specified to gether with any option of /DEx type. Besides, /PRN and /AUX options can also be specified together. For example, MYPROG.EXE application protected with
nsdkey.exe /GS /DEP=password /DED /PRN /AUX myprog.exe mybase.dbf
options will prohibit transmission of files to both the printer and serial port. Unicity of File Protection Password /UPS[=[0x]sssss] Protected application format:
DOS.
Dongle type:
Any
268
Description: This option allows you to strengthen data protection in case you distribute the software on a large scale basis. /UPS option allows you to make the data protection password, which you specify using /DEP=password option, unique for each distribution kit of the software product. The password will depend on the value of the serial number written in the dongle, which has been attached during protection (if option is specified either /UPS or if entered inside the /UPS option after = sign). Therefore, users will be unable to use each others pro tected data since data access passwords will be different. For example, you can protect two software kits with the following options:
nsdkey.exe /GN /DEP=password /UPS=1 myprog.exe mybase.dbf
and
nsdkey.exe /GN /DEP=password /UPS=2 myprog.exe mybase.dbf
The real data protection password in the first case will depend on value 1, and in the second case on value 2. Therefore, access password to MYBASE.DBF file will be different in these kits. Though the password in this mode can be made dependent on the don gles serial number (when /UPS option is specified), you do not have to necessarily protect the software with /US option (Unique serial num ber). The matter is that data protection password is generated only during protection process, and its value is stored by the protected application. During running, the application does not poll the serial number of the dongle to get a password, but uses the known password. /UPS option can be used together with any other data file protection op tions reviewed in this Section. Important
If you set /US (Unique serial number) and /UPS options at the same time, then data protection password will depend on the serial number specified by /US option.
Examples:
nsdkey.exe /GN /US=1 /DEP=password /UPS=2 myprog.exe nsdkey.exe /GN /US /DEP=password /UPS=2 myprog.exe
In the first case, data protection password will depend on 1 (/US=1 op tion). In the second example, regardless of the value specified by /UPS option, the password will depend on the serial number of the dongle that was attached to the computer at the moment of protection. Thus, specify ing the serial number in /UPS option makes sense only when /US option is not used at all.
269
Users Manual
Specifying User defined Vaccine Message File /MSG=[path]file_name Protected application format:
DOS/Win16/Win32.
Dongle type:
Any
Description: If any error occurs during running of the protected application, the vac cine displays a corresponding message, and the application stops running. Vaccine messages can be divided into main and optional. Main messages are displayed in case the dongle is not found, the counter of the dongle is exhaust, an illegal application copy is run, and in other similar cases, while optional messages are displayed, for example, when an internal pro tection error occurs. During software protection, main messages are extracted from MSG file and entered into the vaccine. By default, the <protec tion_utility_name>.MSG file is used that is located in the directory con taining a corresponding protection utility. MSG file is an ordinary text file composed of four lines. Each line con tains one of the main messages that can be displayed by the vaccine during running of the protected application in the following cases: The first message specified in MSG file is displayed in case: o Hardware algorithm #0 of Guardant Stealth, Guardant Fidus or Guardant Net dongle returns a wrong answer. The dongle with specified ID, application number, se rial number, version and mask is not attached (when appropriate search conditions are specified). Executions counter is exhausted (number of executions is limited); The application license term has run out (application license term is limited); The specified number of users who can work simulta neously with the protected network application in local network environments has been exceeded (only when bound to Guardant Net).
The second message is displayed in case: o
The third message is displayed in case: o o o
270
The fourth message is displayed in case: o System error occurs when the protected application is started (lack of memory, system resources allocation er ror, etc.); Virus has been detected in the protected application; Vaccine is not found when starting the protected appli cation.
o o
Guardant Stealth, Guardant Fidus and Guardant Net dongles do not generate responses, such as a dongle is available, but not with the re quired parameters. In this case the dongles do not respond at all, and the protection software returns a code that corresponds to the second message of MSG file. This has been done in order to increase protection strength against attacks, so that hackers fail to get any information about the don gle. The only case when the first message is displayed after Guardant Stealth or Guardant Net dongle has been found is when the application is protected without /NOA option (i.e., it uses the response of hardware al gorithm #0), but the parameters of this hardware algorithm are incorrect in the found dongle. You can create your own messages for the vaccine. To do this, you should write a file containing four messages in any language. The length of one message should not exceed 59 characters. Each message should be written in a separate line, one message must contain only one line, empty lines are not allowed. In order to make the vaccine use the user defined messages, you should specify the name of the new file with messages and, if required, path to this file in /MSG parameter. If the path to the file is not specified the lat ter will be placed in the directory where the protection utility is located. Examples:
nwkey.exe /GS /MSG=:\mydir\mymes1.msg myprog.exe nwkey.exe /GN /MSG=mymes2.msg myprog.exe
In the first case, vaccine messages will be read from MYMES1.MSG file, located in C:\MYDIR, and in the second case from MYMES2.MSG file, located in the same directory as NWKEY.EXE utility. Specifying a New File Name for the Vaccine /LBL=filename.ext Protected application format:
DOS
Dongle type:
Any
271
Users Manual
Description: By default, the vaccine file working with DOS applications is named NK.DAT. However, you may change this name to any other. The point is that if the software product comprises many files with similar names, then the standard vaccine name will be distinct from any other. Using /LBL=...option you can change vaccine file name, thus hiding it among service files of the software product. This will add, though not very substantially, to the level of software protection against its logic being studied. Warning
To rename vaccine file you should use /LBL option only. Do not try to rename vaccine file using ordinary OS tools after software protection, because the protected applications will remain adjusted to the vaccine with a standard name (and, therefore, will not start). End-users must not rename the vaccine file either. If the software product comprises several executable files to be protected, all these files should be protected using /LBL option (thus, they will be adjusted to the vaccine with a new name).
Important
/LBL option is available only during protection of DOS application (i.e., only in NSDKEY.EXE utility).
Example:
nsdkey.exe /US /LBL=alpha.qdf alpha.exe alpha.dbf
During protection of DOS applications NK.DAT vaccine file will be re named to ALPHA.QDF, and an ALPHA.EXE protected application will be using the vaccine with a new name. Specifying Audio Error Messages /SND[=FileName.Ext] Protected application format:
Win32
Dongle type:
Any
Description: When an error occurs, the protected Win32 application is capable not only of displaying a corresponding message on the screen but also of play ing a corresponding audio file. Audio messages are specified using /SND[=FileName.Ext] option. By default (/SND option), audio messages are used that are specified in NWKEY32.SND file, however, you can specify SND file in the following way, for example:
/SND=myfile.snd
272
SND file is an ordinary text file composed of four records. Each record should contain the name (without path and extensions) of WAV audio file, which will be reproduced in case a corresponding error occurs. Names of WAV files are written in SND file in the same order as text mes sages are written in MSG file. The length of WAV file name should not exceed 8 characters, and each name is written on a new line. WAV files should be delivered together with protected software, and dur ing installation of this product they should be copied to the location where they can be found by an appropriate Windows function, i.e., to a current directory or directory containing protected application, or one of directo ries out of PATH list. Example:
nwkey32.exe /GS /SND=mysnd.snd myprog.exe
This is an example or protection of a MYPROG.EXE Win32 application using Guardant Stealth. When one of main errors occurs, a corresponding WAV file specified in MYSND.SND (MYSND.SND is located in the same directory as the protection utility) will be reproduced. Specifying Destination Path /OUT=path Protected application format:
DOS/Win16/Win32
Dongle type:
Any
Description: By default, protected files are placed in the same directory where source files are located (the latter are renamed into files with OLD extension). Using /OUT option you can specify a different path for the protection utility to place the protected files. This is especially helpful when protect ing several files with different extensions, but with the same names. The same path will be used when copying NK.DAT vaccine file (only when protecting DOS applications), and if you have used /LBL=...option, then DOS vaccine file will be renamed. Examples:
nsdkey.exe /CEP /US /T=2 /OUT=c:\protect myprog.exe nsdkey.exe /CEP /US /T=2 /LBL=myprog.vks /OUT=c:\protect myprog.exe
In both cases, at the time of protection MYPROG.EXE DOS application will be copied to C:\PROTECT directory. Vaccine will be copied to the same location (in the first case it will have a standard name NK.DAT, and in the second case it will be renamed into MYPROG.VKS when copied).
273
Users Manual
Forbidding Display of Utility Messages on the Screen /Q Protected application format:

DOS/Win16/Win32
Dongle type:
Any
Description: Usually, in its execution phase, the protection utility displays various mes sages meant to provide you with guidance throughout the protection process (information read from the dongle, application and data protec tion modes, error messages, etc.). However, the utility can be started from some external program with win dow based interface. In this case, the utilitys messages can corrupt in formation generated by external program. To deactivate displaying of messages on the screen, you should run pro tection utility with /Q option. In case an error occurs, the utility will discontinue protection session, and you will be able to identify an error type by its return code. Example:
nsdkey.exe /GS /UM /Q myprog.exe
Specifying a List of Files to Be Protected (Encoded) The protection utility is capable of protecting or encoding several files during one session. A list of files to be protected (encoded) should be specified in the command line following all protection options, and these files should be separated by spaces, for example:
nsdkey.exe /GS /CEF /DEP=1234 myprog.exe mybase1.dbf mybase2.dbf
In this case, the utility will protect MYPROG.EXE, MYBASE1.DBF and MYBASE2.DBF files located in the current directory. The file list can also indicate full paths to these files, as well as * and ? symbols, for example:
nsdkey.exe /GS c:\mydir\*.exe myexec.com nsdkey.exe /GS /DEP=1234 myprog.exe c:\base\*.dbf c:\base\*.idx
In the first case, the utility will protect all EXE files and MYEXEC.COM file. All these files will be extracted from C:\MYDIR directory. In the sec ond case, MYPROG.EXE file will be protected, which is located in the current directory, as well as all DBF and IDX files located in C:\BASE directory. Note that you should always indicate the extensions of the files listed (ex cept for data files that have no extensions), or a mask specified by * or ? symbols.
274
Using List File It may so happen that due to abundance of parameters and/or files the maximum length of the command line will be exceeded. To avoid this you can use the list file. A list file is an ordinary text file with FIL extension, which contains a list of files to be protected (encoded). Each file in the list should be written in a separate line; if required, full pathnames and * and ? symbols can be specified in the file names and extensions. Below is a sample of the list file:
myprog.exe *.dbf c:\new_base\*.exe c:\new_base\*.dbf c:\new_base\*.idx
In this case, MYPROG.EXE file will be protected alongside all DBF files located in the current directory, as well as all EXE, DBF and IDX files lo cated in C:\NEW_BASE directory. To instruct the utility that it should extract a files list from the list file, its name should be entered in the command line following all protection op tions (i.e., instead of files list described in the previous section). For the utility to be able to differentiate the list file from an ordinary file, this pa rameter of the command line should start from @ symbol, for example:
nsdkey.exe /GS /DEP=1234 @myfil.fil nsdkey.exe /GS /DEP=1234 @c:\mydir\myfil.fil
In the first case, the files to be protected will be extracted from MYFIL.FIL list file located in the current directory. In the second case, the utility will use MYFIL.FIL list file located in C:\MYDIR directory. You can specify several list files (each should start with @ symbol) in the command line. This is useful for grouping files to be protected by their types, for example:
nsdkey.exe /GS /DEP=1234 @myprogs.fil @mydata.fil
In this case, it is convenient to enter the names of all executable files, which are to be protected, in MYPROGS.FIL, and the names of all data files to be encoded in MYDATA.FIL.
275
Chapter 13. Files to Pass to an End-User
Chapter 13 Files to Pass to an End User

The objective of this Chapter is to summarize all information related to supplying of protected software with protection files. Three examples connected with the usage of Guardant Stealth, Guardant Fidus and Guardant Net will be described below:
Protection mode Dongle Type Guardant Stealth & Fidus Guardant Net
Guardant Drivers
All nvkey95.vx_, nvkeyu95.sys, nvkeyusb.sys, nvkey98u.sys, nvkeynt.sys, nvkeyvdd.dll, nvkey4nt.sys, nvkeyusb.sys, gsnusb.in_, instdrv.ini, instdrv.exe, instdrv.txt, grddem32.exe, grdctl32.dll, grddrv32.cpl, grddrv32.dll
Common files
All Guardant drivers, chknsk.exe, Guardant drivers, chknsk.exe, chknskw.exe, chknsk32.exe, chknskw.exe, chknsk32.exe, clocktst.exe, nnksrv32.exe, clocktst.exe, , grddiag.exe nnksrv32.ini, nnkmon.exe, nnkmonw.exe, nnkmon32.exe, grddiag.exe
Files for Protecting DOS Applications

Automatic protection Protection with dongle remote programming function Protection in the mode which sets a limit on the application license term Automatic protection Protection with dongle remote programming function Protection in the mode which sets a limit on the application license term Common files, nk.dat Common files, gsremote.exe + novex32.dll (for Windows), nskinst.exe + nk.dat (for pure DOS) Common files, gsremote.exe + novex32.dll (for Windows) nsktchk.exe +nk.dat (for pure DOS) Common files, novex.exe Common files, gsremote.exe + novex32.dll Or nskinst.exe +nk.dat Common files, gsremote.exe + novex32.dll or nsktchk.exe+nk.dat Not supported Not supported
Files for Protecting Win16 Applications
277
Users Manual
Protection mode
Dongle Type Guardant Stealth & Fidus Guardant Net
Files for Protecting Win32 Applications

Automatic protection Protection with dongle remote programming function Protection in the mode which sets a limit on the application license term Common files, novex32.dll Common files, gsremote.exe + novex32.dll or nskinst.exe +nk.dat Common files, gsremote.exe + novex32.dll or nsktchk.exe +nk.dat Not supported
Important
1. NK.DAT vaccine file is needed when using NSKINST and NSKTCHK utilities, because they are supplied already protected by the automatic protection option. 2. NOVEX32.DLL vaccine file is needed when using GSREMOTE.EXE utility, because it is supplied already protected by the automatic protection option.
278
Appendix A. How to Update Guardant Software
Appendix A How to Update Guardant Software

Guardant protection is an up to date, dynamically developing product. It is very important that Guardant software is periodically updated; this is only way to get new and more advanced protection technologies, increase protection level, and minimize the risk of incompatibility with the latest hardware and software. Guardant developers have made every effort to make the software update procedure as easy and convenient as possible. Currently there are three different methods of updating Guardant software available to you. Important
Software can be updated only on those computers where it has already been installed.
Updating from Guardant Software CD

You can get a new software release at the offices of Aktiv company or from our dealers. If Guardant software is supplied on CD, it would be more convenient to write a new release directly on this disk. Then you should act as described in Installing the Software for choosing your op tion. Note that there are two possible choices. You Just Wish to Update Guardant Software In the main window of SETUP program select the required option. The SETUP will then update all Guardant files in the original directory, and you will not have to enter dongle access codes. You Wish to Start Using Dongles of a New Type If during the initial software installation you have not entered codes for these dongles, youll have to do it now. Click on [Next] button in the main SETUP window and follow the steps described in Installing the Software. * ** If several releases of Guardant software have been written on distributive CD, you should choose the latest one (use names of directories, in which these releases are written, as a guide). AUTORUN.EXE, a program that starts automatically once the disk is installed in the disk drive, will do the job for you.
279
Users Manual
Important
Updating from distributive medium is the only method that gives you an opportunity to adjust the software to the new types of dongles.
Guardant Software On line Update

This update method is probably the fastest and most convenient. To use this method you should first connect to Internet. After Internet connection has been established, you should run Guardant Software On line Update application. GSOFTUPD.EXE program will be started. It will automatically connect to the web site of Aktiv company (www.guardant.com) and download the information about the latest re lease of Guardant software. Then the program will display a list of Guardant software components available for downloading.
Figure 31. Main window of GSOFTUPD.EXE utility. The checked components are either not available or have become out dated and need an update. You may also check any other components to download. The types of Guardant dongles to which the Developers kit software has been adjusted (i.e., for which you have specified access codes) are dis played in the right part of the window. Note, that if you download a com ponent for the dongles to which your software is not yet adjusted, then af ter the download it will work with demo dongles only. Therefore, you should first update from a distributive medium (to adjust your software to the new dongles), and then return to the on line method (to update the software).
280
Appendix A. How to Update Guardant Software
After you have marked all components you are interested in, click on [Download]. The components will be downloaded into \PAKS subdirec tory under the directory containing Guardant software. Then click on [Finish], and downloaded components will be updated by SETUP pro gram. Downloaded components are not removed from \PAKS subdirec tory; you can use them for repeated downloading using a method de scribed below. Besides, downloaded components cannot be re downloaded (unless they have been updated). This allows you to reduce download time, for example, during a session closedown in case of emer gency.
281
Appendix B. How to Increase Protection Strength. Recommendations to a Programmer
Appendix B How to Increase Protection Strength. Recommendations to a Programmer

Guardant is a high efficiency software hardware system designed for pro tecting the software. It allows you to build protection of almost any com plexity and level of immunity to attacks. To achieve this you should follow the recommendations below:
Automatic Protection of Executable Programs

To protect the functioning logic of executable applications against illegal study you should use automatic protection utilities. In this case the follow ing options are advisable: Protection against debuggers. It is always enabled by default and is intended for protecting the functioning logic of an application against study with debuggers. Protection against viruses. This option allows you to protect the application not only against file viruses, but also against illegal modification of the application file (adding of software modules, changing copyright information, etc.). Encoding of the loadable part and internal overlays of the application. This will ensure the application from attempts of disassembling, which is but another method of studying your applications logic. If protected application uses data stored in external files, then encoding of data files is advisable. In this case, even if a hacker manages to separate the protected application from automatic protection vaccine, it will still not work with the encoded data, because it is the vaccine that performes the decoding. Use options of checking dongles against timer. In this case, even full dumping of the memory of the application will be useless for the hacker. Before proceeding to protection, it is desirable to compress applications using packers of EXE files (LZEXE, DIET and etc.). This will considerably strengthen protection of application running logic against study by debuggers.
283
Users Manual
API Based Protection

General Recommendations With reliable automatic protection in place, you can build internal Guardant API based protection. In this case, you should follow the rec ommendations below: 1. Do not store dongle access codes in explicit form. You should not keep the Private codes that are used to access the dongle in an ex plicit form. To make the search of Private codes in the application body harder for hackers, these codes can be encoded (for example, using XOR operation). Decode the codes immediately before call ing the API function, and as soon as the function is complete, im mediately remove the decoded Private code version from the memory. You can also store different parts of Private codes in dif ferent variables, for example:
DWORD GetPrivateReadCode( void ) { /* Random value for most security*/ #define Crypt 0x8566783lu DWORD dwPrivRD = ns_DEMORDO Crypt; /* Access code is stored in the application ac encoded double-word */ return dwPrivRD + Crypt; /* Access code has been decoded before API function call */ }
2.
3.
4.
Each time GetPrivateCode() function is called, it will place the demo Private code in szPrivCode variable. It should be called each time before calling any other API function. Spread API calls across the whole body of the application. This will dramatically increase the size of the code to be studied by a hacker in order to locate the check code and its modifications. If protected application contains overlays, place API calls in the overlay part. In this case, the system overlay manager will serve as additional obstacle to a hacker. It is very good to use probabilistic calls, when the API is not called every time, but with probability of, say, 1/7. In different parts of the application different call probabilities can be used (you can set a higher probability value for vital parts of the application, and lower for less important parts). As a result, a hacker can simply be un able to detect calls with low probability of occurrence, and eventu ally the allegedly cracked application will unpleasantly surprise illegal users.
284
5.
6.
7.
Make the logic of processing the API functions return codes more sophisticated. If you are checking the API function return code by a simple comparison, a hacker will easily destroy this comparison straight inside the application body and thereby crack the protec tion. Therefore, you should develop a more sophisticated logic. For example, use return codes as indexes of some data arrays, or as start values for random number generators, or else in math calculation of algorithms implemented in the application, etc. There will be no apparent point at which the protected application is taking a deci sion on further running. A hacker will have to understand not only the protection logic, but also intricate processes that take place in side the application. Thus, protection will become an integral part of the application, in the absence of which the calculations will be incorrect, or the wrong data will be used, etc. Delay the application response time to the API functions return codes. A method has proven very useful, when the application de cides upon its further actions not straight after it receives the API function return codes, but much later. For example, the API func tion is called at the start of the application, but its returned values are analyzed when the user executes certain actions (for example, opens or saves a file, invokes application setup menu, etc.). In this case it will be difficult for a hacker to track cause effect relation of the application. Besides, this method will force the hacker to inves tigate very large fragments of application code in the debugger. Limit the applications features in case the dongle has not been found. This method can be used in addition to the one described above. If the API function returns an error, you can avoid taking fundamental decisions on its further running, but just limit its fea tures. For example, you can disable the export of files to other for mats, or the retaining of settings, or printing out of reports, etc. Moreover, in case the API calls made from different parts of the application fail, you can gradually deprive the application of more and more features, turning it into a demo application. Apart from important features, you may also disable several options of minor importance; the hacker is unlikely to notice this, and the applica tion will get into the black market in this impoverished form. Us ers of such a demo version, where some features turn to be un available, will be forced to buy a legal copy of the application.
285
Users Manual
8.
9.
Calculate checksums of the important parts of the application code. This is a powerful means of protection against the application code being modified by a hacker. You may calculate in advance the checksum of code blocks where the API functions calls are made, analyze functions output and take decisions on further running of the application. While the application is running, you calculate these blocks once again and thereby get precise information about whether these blocks have been illegally modified. It is better to cal culate checksums in a background mode (this can be carried out as a separate procedure in Win32 applications), and you should do this either much earlier or much later than the control is passed to the verified code block. It is advisable that one and the same block is verified from different parts of the application. The response to the application code modification should be somewhat the same as when an error occurs during the API function calling. As a result, a hacker will have to look additionally throughout the whole applica tion body for the locations where you check the checksums. To get a checksum you can use Guardant Stealth or Guardant Net API function that calculates the CRC (cyclic redundancy check) of the data block you need. In order to increase reliability of this method, you can write your own checksum calculation algorithms to be used along with this function. Their implementation is not very dif ficult, and a good algorithm for CRC calculation is described in any of application programming guides. Change the logic of using protection modules. It is very useful to change the logic of using protection modules from time to time (it is optimal if that is done in every new version of the protected product). Use new methods similar to the ones described here, combine them in a different way, and then with every new release of the software product a hacker will have to start from scratch. All of hackers previous experience will be worth nothing, since the ap plication will now be interacting with protection modules in a very different way!
Additional Tips on Stealth dongles If you have chosen either Guardant Stealth, Guardant Fidus or Guardant Net, you will have an opportunity to benefit from a range of effective methods of strengthening protection against attacks. 1. Activate hardware algorithms of Stealth dongles. This is a manda tory requirement in case you wish protection to be truly strong. Correct usage of hardware algorithm responses makes creation of Stealth dongle emulators almost impossible. Besides, removal of the API functions from the protected application becomes point less, because if the hardware algorithm has not been run, this
286
2.
3.
4.
means that the data critical for the application have not been de coded. Decoding can be done by hardware algorithms only... Send more queries to Stealth dongle. If protection is based on the conversion of only one data array (i.e., if the application always sends one and the same query to the dongle), there is a risk that a hacker can spy out the right response of the dongle and develop a module stub that will cheat the application by providing it rather with its response than the API function. Since in this case the don gle always returns one and the same response, this module stub can make the hardware algorithm useless for protection. To avoid this, you should send a wide range of queries to the hardware algo rithm. Create a set of various queries (i.e., encoded data blocks) and use hardware algorithm to decode various encoded blocks in different parts of the application. By the way, along with the appli cation critical data you can also include unnecessary data, which are actually useless for the application, into the array to confuse the hacker. It would be good if you could arrange for a random selec tion of queries; in this case, different queries will be processed in one and the same part of the application, but at different points in time. This will make creation of both a module stub and of a Stealth dongle emulator virtually impossible for the hacker. Use different queries in different versions of the application. If you are using different queries (i.e., different encoded data blocks) in different software products or in different versions of the same product, you can be sure that a hacker will be unable to create a universal tool to crack all your products (or their versions). Even if the hacker somehow manages to create an emulator for your appli cation, with the release of a new version he will have to start every thing anew since the new version will be using different encoded data. Use different hardware algorithms in different versions of the appli cation. You should at once create several (for example, four) differ ent algorithms in the dongle. Then in the first version of the soft ware product encode data using, say, the first and the third algo rithms, in the second version using the second and the fourth al gorithms, and in the third version using the first and second algo rithms, and so on and so forth. The effect will be similar to the above, and, besides, you will not have to reprogram the dongle since all necessary hardware algorithms will exist in the dongle from the very beginning.
287
Users Manual
5.
6.
Do not store hardware algorithm responses inside the protected ap plication. The principle of using hardware algorithms is based on the precondition that a hacker cannot foresee the hardware algo rithm responses. Otherwise, algorithms would have been useless, because if the hacker knew all of the answers, he would be able to create a dongle emulator and a module stub. Therefore, do never store the responses of the dongle anywhere inside the application or in data files! Just use the responses of the Stealth dongle for their original purpose without preliminary checking the correctness of their decoding by the algorithm, and after that delete them from the memory whenever possible. The data can be decoded incorrectly only when something undesirable has been done either to the pro tected application or to the dongle. In this case malfunctioning (and even hanging) of the application is quite natural. In fact, such behavior is quite natural for an application that is being at tacked by the hacker, especially if the protection is of a good stan dard. Nevertheless, if you still need to check the correctness of re sponses, you can use the CRC calculation function from the Guardant Stealth API. At the stage when you implement protec tion and before you encode data, you should calculate their CRC, and then during running of the application you should calculate the CRC of the same data after they have been decoded by the dongles algorithm. If the two calculated values match, this means that the data have been decoded correctly. Do not store irrelevant access codes in the protected application. For example, if the application executes only such operations as reading from the Stealth dongle and running its hardware algo rithm, then only Private Read Code should be stored in the appli cation. All the rest Private codes will be unnecessary, and if they remain in the application body, this will facilitate hackers access to the dongle.
Additional Tips on Network Dongles When using network dongles you should follow the recommendations be low: 1. At the time of running the protected application, you should check for the presence of the dongle periodically. This is done in order to prevent overloading of Guardant Net server, when an attempt is made to artificially exceed the license limit and simultaneously run the application from more workstations than permitted. 2. To avoid excessive network traffic load and to increase system reli ability, you should not poll the network dongle too often. The ad visable interval between the polls is about five minutes.
288
Appendix C. Additional Devices to be Used with Dongles
Appendix C Additional Devices to be Used with Dongles

Certain devices can be supplied together with Guardant system that pro vide for additional dongle programming options, or serve to ensure effi cient use of dongles and to support your computer hardware.
The Saver
Programming of a great number of dongles is inevitably connected with intensive usage of a parallel port connector. Yet, this connector allows only around 500 connections. This means that after processing 500 don gles, the parallel port connector may wear down, and connection with the dongle will not be tight anymore. This risk is very high. To avoid this by effect, a device called Saver has been designed. It consists of two DB 25 connectors linked by interface cables. You should attach one of Savers connectors to the parallel port, while the dongles are at tached to another connector. Use of the Saver allows you to minimize the risk of failure of the parallel port connector. In this case, it is Savers connector, which will be wearing down, while connection to the computers parallel port will be done only once. Use of Savers is cost efficient, since its cost is, of course, much lower than that of port adapter. Besides, with the Saver programming of dongles will become more com fortable. You will not have to work with a computer turned backwards or change dongles in the port connector blindly. Instead, you can fix the available device connector in an easily reached place (for example on the front side of your desk). This will reduce the overall processing time of one dongle and will save you many troubles. Saver is not included in a standard delivery package and is to be purchased separately.
289
Appendix D. Specifications
Appendix D Specifications
Dongle Type Feature Guardant Stealth Guardant Net Guardant Fidus
General Features
Base element Method of attaching to computer Connector type Number of cascaded dongles Dongles Transparency Microcontroller Parallel or USB port of IBM-compatible computer DB-25 or USB type A Depends on computer (usually about 10) To any peripheral devices and communication protocols 2 volts < 1,8 volts ~180 ms 0..+70 0..100 % condensate free -10..+80 46x52x16 mm Microcontroller Parallel port of IBMcompatible computer DB-25 Depends on computer (usually about 10) To any peripheral devices and communication protocols 2 volts < 1,8 volts ~180 ms 0..+70 0..100 % condensate free -10..+80 46x52x16 mm 256 bytes Unlimited Up to 1,000,000 Up to 100 years Supported
Minimum Operating Voltage Minimum Voltage Average dongle search time Operating ambient temperature Operating air humidity Storage and transit temperature Dimensions Non-volatile memory capacity Number of memory read cycles Number of memory write cycles Written data storage time
Non-Volatile Memory
256 bytes Unlimited Up to 1,000,000 Up to 100 years
Capability of implementing Supported hardware memory read/write locks
291
Users Manual
Dongle Type Feature Guardant Stealth Guardant Net Guardant Fidus
Hardware Algorithms
Number of hardware algorithms in one dongle Minimal time of hardware algorithm execution Length of a sequence specifying the type of one hardware algorithm Up to 18 changeable ~250 ms 4..200 bytes (32..1,600 bits) 8 predetermined ~250 ms 8 bytes for IDindependent algorithms 12 bytes for IDdependent algorithms 4 bytes for Simple and Random algorithms 32 bytes for Fast algorithm; the output sequence length and the input sequence length are equal Supported Supported to achieve maximum level of transparency and compatibility in different dongle operation modes Supported to achieve maximum level of transparency and compatibility
Size of data encoded by one hardware algorithm during one session
4..255 bytes (32..2,040 bits); the output sequence length and the input sequence length are equal
Other Features
Hardware lock against debuggers Fast adjustment of microcontrollers speed Supported Supported to achieve maximum level of transparency and compatibility in different dongle operation modes Supported to achieve maximum level of transparency and compatibility
Availability of intermediate state of the dongle
292
Appendix E. Hardware Algorithm's Parameters
Appendix E Hardware Algorithms Parameters

Parameter Purpose of Parameter Range of Parameter Values 4..200 Notes
In parameters
Determinant size Specifies the length of algorithms determinant in bytes. Specifies the number of bytes an algorithm can convert during one session. Involved in the formation of the algorithm representation. Should be evennumbered. Even number is recommendable. The size in bytes should be equal to the value of Determinant size parameter.
Query size
4..255
Determinant
4..200 bytes
Algorithms counter
Specifies the number of algorithm executions when nsaf_GP_dec algorithm flag is set.
0..232
Out parameters
Query Array of data to be converted by the algorithm during one session. Array of data that have been converted by the algorithm. 4..255 bytes The size in bytes should be equal to the value of Query size parameter. The size in bytes is always equal to the size of the algorithm query.
Response
4..255 bytes
293
Appendix F. Demonstration Access Codes
Appendix F Demo Access Codes

Guardant Stealth, Guardant Fidus and Guardant Net
Code
Public Code Private Read Code Private Write Code Private Master Code
Code Presentation Form Character

DEMONVK DEMORDO DEMOPRF DEMOMST
Numerical
519175B7 51917645 51917603 5191758C
295
Glossary
Glossary
Access Codes
Codes stored in the non volatile memory of the dongle and used for iden tification purposes. Access codes serve as passwords that allow you to exe cute operations with the dongle. See also: Public Access Code, Private Access Codes.
Algorithm Properties
A part of algorithms descriptor. This is a set of data determining the be havior of a particular hardware algorithm. It is composed of flags, a counter, and size of the determinant, size of the query. There are the fol lowing algorithm properties available: Dependence on the identification number (ID) of the dongle determines the unicity of the algorithm implemented by each copy of the dongle. Dependence on the counter value determines the change in the represen tation of algorithm subject to the change of the algorithm counter value. Limitation of number of executions determines the life cycle of a particu lar algorithm depending on the executions counter. See also: Algorithms Descriptor, Algorithm Properties Flags.
Algorithm Properties Flags

A combination of algorithm properties is also involved in the creation of a hardware algorithm. The properties are specified by a combination of spe cial flags, which comprise the algorithm descriptor. By specifying a com bination of properties of the hardware algorithm, you can achieve its re quired behavior and greatly influence its representation. See also: Algo rithms Descriptor.
Algorithm Response
An information block returned by a hardware algorithm in response to a query. The algorithm response has the same length as the query and is, in fact, a query that has been converted by the hardware algorithm. See also: Hardware Algorithms, Query to the Algorithm.
Algorithms Allocation Table

The area of a dongles non volatile memory for storing SAM (System Ad dress Mode) addresses of hardware algorithm descriptors. The algorithms allocation table begins at kmAlgoAddr.
297
Users Manual
Algorithms Counter
A special 4 byte field included in the algorithms descriptor. This counter can be used for limiting the number of algorithm executions and for de termining the particular representation of an algorithm. Thus, in case al gorithms counters have different values, then they will be converting data differently even if algorithms determinants are identical. Whenever the algorithm is queried the counter decrements automatically. See also: Al gorithms Descriptor.
Algorithms Descriptor
A set of data for describing a hardware algorithm of a particular type. It consists of two parts: algorithm features (properties) and a determinant. Descriptors are stored in the non volatile memory of the dongle and are protected against reading and modifications. The addresses of descriptors are saved in the algorithms allocation table. See also: Algorithms Alloca tion Table.
Algorithms Determinant
A part of an algorithms descriptor. A numerical sequence that specifies a particular representation of Y=F(X) function realized by the algorithm. The length (size) of the determinant can range between 4 and 200 bytes. See also: Algorithms Descriptor.
API (Application Programming Interface).

A set of functions used by applications for sending queries and executing of low level services.
Automatic Protection
A method of an executable application protection during which a vaccine is embedded into its body. This method allows quick implementation of protection, but does not provide high immunity to attacks. The closest synonyms are protection envelope, envelope method. See also: Vac cine.
CRC (Cyclic Redundancy Check)

Method of data integrity verification using cyclic redundancy encoding. Generally, CRC is used as a very reliable checksum of certain data. When cyclic redundancy encoding is used, error correction capability is avail able. Also, this method can be used for validation the authenticity of data, for example, of software code blocks. Depending on the exponential order of the constitutive polynomial there are the following CRC types avail able: CRC8, CRC16 and CRC32.
298
Glossary
Demo dongle
A dongle of Guardant family whose functionality is limited by demo and test functions. This dongle contains only demo access codes, which makes it impossible to use it for commercial purposes associated with software protection.
Dongle
(Referred to as dongle, key and hardware key in various parts of this Man ual.) A relatively small electronic device attachable to a computer. Dongle is the bedrock of Guardant protection system, since protected applications are bound to the information stored within this device. See also: Demo dongle, Stealth technology.
EEPROM (Electrically Erasable and Programmable Read Only Memory)

Read only memory that permits multiple overwriting without any specific conditions as opposed to EPROM, which requires clearing of memory with ultraviolet radiation. In this case, data in EPROM are erased com pletely, and EEPROM permits overwriting of individual memory cells. EEPROM is a non volatile memory, i.e., it allows you to store data with out consuming power for quite a long time (approximately 100 years). Memory of this type supports a great number of overwriting cycles. The number of reading cycles is unlimited.
External Vaccine
Vaccine accumulated in a separate module. External vaccine carries out main protective operations: decoding and debugging of the protected ap plication, checking of the dongle, processing of encoded data files, etc. See also: Vaccine, Automatic Protection.
Fast Conversion Algorithm

It is used for processing large amounts of information. This algorithm uses a block of information converted by a hardware algorithm as a conversion password. Fast conversion algorithm is implemented through software means. Thus, the information cannot be decoded without the dongle, even if the source password is available. Unlike hardware algorithms, fast conversion algorithm is not a one way algorithm. Using it you can both encode information and decode it into its original form. See also: Hard ware Algorithms.
299
Users Manual
Guardant API (Guardant Application Programming Interface)

A set of functions used by applications for executing operations with Guardant dongles. See also: API, Guardant API based Protection.
Guardant API Based Protection

A method of applications protection during which Guardant API calls are used. This method permits integration of protection into the applica tion. Based on use of the API functions, this method is characterized by slower implementation of the protection, yet provides high immunity to attacks. See also: API, Guardant API.
Hardware Algorithms
Mathematical algorithms which realize some functions of Y=F(X) type. These algorithms are called hardware, because they are executed in ac cordance with a microprogram by the dongles microcontroller, without using computing facilities (processor, memory) provided by PC. All data required for the functioning of algorithms (descriptors) are also stored in the non volatile memory of the dongle. The protected application can use hardware algorithms for converting (encoding or decoding) of any data. See also: Hardware Algorithms Descriptor.
Hardware Locks
These are locks programmed by the user of protection and implemented for certain operations to be executed with the contents of the dongles se lected memory area. There are read and write memory locks. You cannot execute any operations using software tools with the contents of a locked memory area.
Internal Vaccine
Vaccine implemented in the body of an executable application by the automatic protection utility. The main purpose of the internal vaccine is to detect and pass the control over to external vaccine. See also: Vaccine, Automatic Protection.
Length of Query to an Algorithm

Length of the query is the length of an information block processed by the dongle at a time. Length of the query impacts the overall number of que ries that can be sent to the dongle, and, consequently, the strength of pro tection. See also: Query to the Algorithm.
Licensing of Network Software

The idea of licensing implies exercising control over the number of copies of a network product run in the network simultaneously. The objective of licensing is to prevent running of more copies that permitted.
300
Glossary
Logical Fields
Data are stored in the dongles memory as a linear array of two byte words. To make operations with the memory more convenient it can be divided into logical fields of different types with the help of a mask. The memory is divided into the logical fields with the help of the dongle pro gramming utility. Usage of logical fields is similar to describing variables of different types using high level programming languages. It is very impor tant to verify that the contents of the dongles memory and the mask match each other, because if different masks are used, the data will be in terpreted differently.
Operations with the Dongles

Operations that can be executed with dongles, such as searching, memory reading and writing, implementing and releasing of hardware locks, que rying of hardware algorithms, etc. Operations can be of two types: built in and service operations. The main difference is that service operations are partially executed by the dongle and partially by the computer.
Private Access Codes

Confidential access codes that allow you to execute various operations with the dongle: read, write, special operations. Each of these operations is assigned with its special code: Private read code, Private write code and Private master code accordingly. See also: Access Codes, Public Access Code, and Operations with the Dongle
Protocol of Communication with the Dongle

A set of rules and signals according to which the information is inter changed with the dongle. The distinctive feature of this protocol is its pro tection strength. Owing to some preventive actions, study of the commu nication protocol with the dongle becomes very difficult.
Public Access Code

Non confidential access code used solely for identifying the owner of the dongle. See also: Access Codes.
Query to the Algorithm

Information block of a certain length to be converted by a hardware algo rithm. The array of queries should be prepared at the stage when a par ticular algorithm is created. See also: Hardware Algorithms.
301
Users Manual
Remote Programming of a Dongle

A method of remote programming of the dongles memory carried out in dependently by the end user of a protected product. This method is based on conveying a unique number to the end user that serves as a password for programming. Programming is carried out by a special utility held by the end user. Usually, this method is employed during updating counter (executions counter, license limit) values, as well as version and dongle mask fields.
Stealth Technology
Technology of protection against most powerful and up to date methods of dongle cracking. Dongles based on the Stealth technology (or Stealth dongles) are smart (intelligent) dongles, i.e., they are microcontroller based. These dongles are transparent to any peripheral devices, have built in protection that prevents their emulation, copying of their memory con tents by hardware and software means, study of their communication pro tocol by debuggers and other cracking methods. Moreover, such dongles provide additional capabilities for strengthening the application protection level. Among these are: encoding of data using dongles hardware algo rithms, creating of a much more sophisticated logic of protection, use of hardware algorithms for preventing protection emulation etc.
Vaccine
Software code that executes various operations required for protection of an application: it obstructs debuggers, communicates with the dongle, en codes application body and data files, etc. Vaccines are used during auto matic protection of executable programs. See also: External Vaccine, In ternal Vaccine, Automatic Protection.
302

Guardant User Manual

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Guardant User Manual

Uploaded by

Copyright:

Available Formats

Guardant

Anti piracy Protection System

2004 Aktiv Company

About This Book

About This Book

Additional Sources of Information

About This Book

How does Guardant Work?

Advantages of Using Guardant

Protective Features of Guardant

Dongles of Guardant Family

Guardant Developers Kit

Hardware Requirements and Compatibility

Minimal Storage Requirements

Attaching the Dongle

Installing the Software

Chapter 3. Getting Started

Chapter 3 Getting Started

Introduction to the Dongle

Chapter 3. Getting Started

Chapter 3. Getting Started

For Guardant Net used in LAN:

Chapter 3. Getting Started

Chapter 3. Getting Started

Auto Protection Wizard: Protection As Easy As ABC

Chapter 4. Stealth Technology

Chapter 4 Stealth Technology

Availability of Y=F(X) Hardware Algorithms

Multiple Hardware Algorithms in One Dongle

Creating Your Own Hardware Algorithms

Complexity of Hardware Algorithms

Chapter 4. Stealth Technology

Using the Hardware Algorithms Properties

Encoding Data Using Hardware Algorithms

Fast Conversion Algorithms

Chapter 4. Stealth Technology

Dongle Access Codes

Hardware Read/Write Locks

Encoding the Memory of Stealth dongle

Chapter 4. Stealth Technology

Anti debugging Hardware Features

Features of the Protocol of Communication with Stealth dongle

Power Saving and Full Transparency

Chapter 4. Stealth Technology

Special Features of Implementing Stealth Technology in Guardant Fidus

Chapter 5. Structure of Stealth-dongle

Chapter 5 Structure of Stealth Dongle

The Dongles Memory and Memory Addressing Methods

Stealth Dongles Memory Map

Chapter 5. Structure of Stealth-dongle

N/A N/A N/A

kmReserved kmPublicCode kmVersion

UAM address N/A

Chapter 5. Structure of Stealth-dongle

Special purpose fields 246 216 2

How the Dongles Memory is to be Used

Chapter 5. Structure of Stealth-dongle

Chapter 6. Hardware Algorithms

Chapter 6 Hardware Algorithms

What are Hardware Algorithms for?

Protective Features of Hardware Algorithms

Chapter 6. Hardware Algorithms

Hardware Algorithms Structure

km_ad_flags km_ad_algo km_ad_GP km_ad_klen km_ad_blen km_ao