TOOLBOOKDEVELOPER.COM

Software Protection User's Guide

It's

Go to User Guide Home

Software Protection - About the System

Developed for: 

Click2Learn ToolBook Instructor version 8.0/8.1 and 8.5/8.6

Works in: 

Native ToolBook Projects

Type of Tool: 

ToolBook system book

IMPORTANT!  Protection Plus Background

The Software Protection system enables you to easily integrate the Protection Plus system into your ToolBook Project.  In order for this system to work, you must have a copy of Protection Plus and the ActiveX Control.  It is also important that you have a basic understanding of the Protection Plus system.  If you are using the Automation Client (on-line unlock), it is also important that you have purchased that dll and that you have a basic understanding of how the automation client works.

For a Protection Plus and Automation Client primer click here.

How Easy is Implementation?

The Software Protection System that I have built for ToolBook requires modification of certain ToolBook Scripts.  Normally my products are set-up in an easy to use Widget that does not require any mucking with open script. I make extensive use of user properties and extended properties so it is really easy to use the Tool.  However, anyone with ToolBook Instructor can access and modify those user and extended properties.  This is not a problem with my other tools. But for software protection, we don't want others to be able to change or modify the system that you have set up to protect your application!  For that reason, I have put all of the pertinent code into open script.  For the highest level of security, after you are finished adding the system to your project, please save the book for development purposes and then save it again as a distribution version.  With the distribution version, remove the scripts from the book before distribution.

Installation

When you download the program, it will self extract into your Program Files directory into a folder for NirvanaBound\PLUS##\ where ## is either 80 or 85 - (80 for ToolBook version 8.0/8.1 or 85 for ToolBook version 8.5/8.6). The installation is a simple self extracting zip file that includes all of the ToolBook and Software Protection files required. It does not include any of the Protection Plus software ActiveX control or the required DLLs. You must have a valid copy of the Protection Plus system.

How to Use the Software Protection System

Please note that the following steps and the details are quite voluminous.  This not a reflection on the ease of use of this tool, however, it will demonstrate the depth of functionally. It is truly very simple to use when simplicity is all that you need.  But the system has the ability to work, control and be controlled in very complex interactive programs.

After you have installed the Software Protection system and you have installed the Protection Plus system from Concept Software you need to modify the PLUS80.sbk or PLUS85.sbk system book.

I strongly advise that you duplicate the system book and re-name it and use your own naming scheme, for the purpose of clarity I will use PLUS.sbk from here on. BTW using your own name will help disguise the fact that you are using the Nirvana Bound Software Protection system.

1.

Copy the PLUS85.sbk or PLUS80.sbk to a new folder and re-name the file {YourName.sbk}, I will use PLUS.sbk.

2.

Open PLUS.sbk and edit the sharedScript “PLUS_Book” and replace all occurrences of PLUS80.sbk or PLUS.85.sbk with {YourName.sbk}, save the sharedScript and save the book.

3.

Go to page 2, page “Plus”, and on the background “Plus” you need to replace the graphic with your own logo image, please replace the existing image. The size of this image is 166 x 227 pixels. You may also wish to change the backdrop at this time. Save the book.

4.

Go to page 3, page “YourDetails," and enter your details and then save the book.

5.

Navigate through the book and change any text to meet your needs and audience. Note that page 4 and 20 (RegWizard_Register and PLUS_About) are blank, the text for these pages are build via the OpenScript function PLUS_AdoutDetails().

Note that pages 5 and 18 (RegWizard_Nag_TimeLeft and RegWizard_Registered) have a hotword, be careful not to delete these. Page 7 (RegWizard_Nag_NotReg) has a field “PlusMessage” on the page, this field will show the text in the system variable s_PLUS_Message.

Page 16 (RegWizard_RegMethodReg) has a hidden field "URL_Link" which is shown if the user is registering via "Online - Browser", this field has a hotword "Unlock" with OpenScript that links to a web page that will allow the user to enter their details. The URL is set to the SOLO server test store, when you finish your testing it will need to change from:
   URL = "http://teststore.softwarekey.com/unlock/getvals.asp"
to:
   URL = "http://softwarekey.com/unlock/getvals.asp"

On pages 14 and 17 (RegWizard_RegMethodFax and RegWizard_RegMethodPhone) there is some red text, replace this with your information.

You may change the caption of any of the buttons including the label buttons like button “CompanyName,” caption “Company Name:” to say caption “Organization:,” however, do not change any names of the buttons!

The button “Close” (at the bottom left) is on the background and the caption is controlled via OpenScript in the button. The caption will change from “Close” to “Exit” where Close will simply close the popup viewer and Exit will exit the ToolBook instance (your application). If you need to change this then you need to change the OpenScript of the button.  Please ensure that the caption will convey the correct meaning to the user.

Save your changes.

6.

Go to page 2 (page “Plus”). This page contains all of the OpenScript that controls the protection system.  There are 10 functions that need to be changed to suit your specific implentation of the protection system. These changes are made in OpenScript so that fellow ToolBookers cannot bypass your protection. When finished and prior to delivery you would make a backup and then use the Script Remover tool, thus making it impossible for anyone (even yourself) to bypass the security.

You need to edit the script of this page and make the following changes:

 

Function name

Description

PLUS_ExitWhenExpired()

currently returns true, change this to false if you need your application to continue to run when the license is periodic and has expired.

PLUS_AutoCheckOnOpenBook()

currently returns true, change this to false if you wish to check the authorization in your own code. Note that if this is false and you do not check the authorization then you have no security!!

isPLUS_NagDaysLeftOn()

currently returns true, change this to false if the license file is periodic and you do not want the nag screen to popup.

isPLUS_EncryptOn()

currently returns false, this feature has not been implemented as yet, although the code has been tested. When implemented and this function returns true then all data stored in the PLUS.lic (Application information) file is encrypted.

encryptKey()

currently returns “PLUS”, this feature has not been implemented as yet. When implemented this value will be used to ensure a unique encryption for your installation. I strongly advise that you update this now, think of this like a password and you will need to remember it. Also, case is important!

licenseFileName()

currently returns “Plus.lic”, you should change this to make your implementation different from fellow ToolBookers.

Note that the next 4 functions use an INI style file to store the information, the file name is set in the above licenseFileName() function. This is an excellent method to use while you are testing as you can easily change the info. without needing to change the code.

However, if the isPLUS_EncryptOn() function above returns true then you can not easily change the information and if it returns false then your users could easily change the information.

Function name

Description

PLUS_LFPassword()

currently returns the value in the license information file which is the word “password” see the Protection Plus documentation for details on this value. Once testing is complete you should change this so the value is “hard wired” i.e. return “{YourPassword}”

PLUS_LFName()

currently returns the value in the license information file which is the word “PLUS.lf” see the Protection Plus documentation for details on this value. Once testing is complete you should change this so the value is “hard wired” i.e. return {path} & “{YourLicenseFileName}”

PLUS_SemPrefix()

currently returns the value in the license information file which is null (nothing is the default and means the prefix will be “sema”) see the Protection Plus documentation for details on this value. Once testing is complete you should change this so the value is “hard wired”

PLUS_ProductNumber()

currently returns the value in the license information file which is the word “38a”. This is used for additional security mainly for network installations, however it works for local PC use as well. The first 2 characters of the product number MUST be numeric and between 10 and 99. The number is used to generate a random number that is encrypted and stored in the license file and also in the license information file.

Once testing is complete you should change this so the value is “hard wired”

Save and close the book.

7.

Copy the PLUS.lic file to the same folder that the new (modified) PLUS.sbk is in. This is the additional license information file and is used to store information about your application and some Protection Plus license file details. There are three sections in this INI style file.

The [PLUS_DETAILS] section holds information about the Protection Plus license file, this has been provided for testing purposes and this section should be removed after testing. The item names in this section are the same names as the functions referred to in Step 5 above and the default values are:

PLUS_LFName=PLUS.lf

PLUS_LFPassword=password

PLUS_SemPrefix=

PLUS_ProductNumber=38a

When you “hard wire” these values this whole section should be removed from this file.

The [LICENSE_DETAILS] section stores demographic details about your customer and is used as the default when you customer enters their details the first time they run your application. If you do not need to supply this information then this section could be omitted as it is updated automatically.

The [PLUS] section will store the user response for the activation method eg. RegMethod=Phone.

Therefore, if you do “hard wire” the functions in Step 5 that relate to the items in section [PLUS_DETAILS] and you don’t need to supply default demographic details in section [LICENSE_DETAILS] then this file can be supplied as an empty file. Note that it MUST exist!

8.

Create a license file using LFEdit.exe and save this in the folder where the PLUS.sbk file is stored. Ensure that the license and the details returned from the functions in Step 5 are in alignment. e.g. The license file name is the same as in the function PLUS_LFName() which may get the value from the license information file.

9.

Copy all of these files to a testing area and create a new blank ToolBook (this blank book is for testing only) and import the SharedScript “PLUS_Book” from the PLUS.sbk (the PLUS.sbk is the original system book that you copied and re-named in Step 1 above) and then assign this SharedScript to the new book. Now add the following OpenScript to the book:

to handle enterApplication

   forward

   send enterThisApp to self

end enterApplication

 

Look for: PLUS_SBK = "PLUS##.sbk" - where ## will be 80, 85 or 89

Change the PLUS##.sbk to the correct name, this will be what you called the book in Step 1 above.  Note that PLUS_SBK = "PLUS##.sbk" is in two locations and must be changed in both places.

Save and close the book. Now test, test and re-test.

As you can see this last step is simple, however, you should not do this step to your actual application until it is finished and then only in a “pre-delivery” folder. Do not do this step on your application in your development folder!!

10.

Installation and packaging of your application. When using the auto packager ToolBook will automatically find the ActiveX control “SKCL.dll,” however you will need to ensure that you also add “Machnm1.exe” and “skca32.dll.” To do this when the auto packager locates the Protection PLUS ActiveX control in the extension you need to ensure that this is checked.  With this line selected click on the “Edit” button and enter the above 2 files.

 


Software Protection System Variables

There are a number of system variables that you can use in your application to determine the current status of the protection system:

Variable Name

Type

Description

s_PLUS_Authorized

logical

Set to true if the current PC has been authorized either for local or network, if s_PLUS_SecFlag is 2 or 3 then s_PLUS_Authorized is set to false even if the actual PC is authorized.

s_PLUS_BookPath

 

This is the path of your ToolBook application, this may change as you navigate from book to book.

s_PLUS_DaysLeft

 

Stores the number of days before the application will expire if the license is periodic. This may contain a negative number. Note the a value of 0 (zero) means that the application will expire today. Also note, a 0 (zero) value will be stored if s_PLUS_ExpireMode = “N”

s_PLUS_ExpireMode

 

Expiration Mode of the license file. Valid types are "D"emo, "P"eriodic, "S"hareware, "E"xecution count, and "N"one. The value is the first letter is used. For details on the expiration types (modes) and their meaning, refer to Expiration Types in Concepts & Definitions chapter in the Protection Plus help file. Note that the use of the word period refers to the modes D, P and S and not just the mode “P”eriodic. Also note that this implementation of the Protection Plus system uses the “EZ Trial” method and as such does not support "E"xecution count!

s_PLUS_IsClockTurnedBack

logical

Set to true if the user has set the clock back to try and get a few more days use before your application expires. Note that this is only checked if the license file is set for periodic. WARNING! If you have a network installation and your license file has the “Update last used time” and “Convert illegal copies to demo” checked (in the product setup of LFEdit) then the license file will auto set to demo mode if unless all of the client PCs have exactly the same time!

s_PLUS_IsDemo

logical

If the s_PLUS_ExpireMode = “D” then this is set to true.

s_PLUS_IsLocalDrive

logical

Set to true if the application is running on a local PC and not over a network.

s_PLUS_IsNetVersion

logical

True if the license file has one or more “LAN Users Allowed” (see s_PLUS_NetUsersAllowed below) Note that you can have a network license and allow a user to run directly of the server, you need to ensure that the number of “LAN Users Allowed” is one less that what your client has paid for. In this case you would need to authorize the server for “Local PC” use and one of the client PCs for network use. i.e. Two activations.

s_PLUS_LFileObj

object

This is the Protection Plus ActiveX control, you should not need to use this.

s_PLUS_Message

 

Stores the messages listed in s_PLUS_SecFlag below.

s_PLUS_NetUsersAllowed

 

Stores the maximum number of network users allowed for the given license. Note that you can have a network license and allow a user to run directly off the server, you need to ensure that the number of “LAN Users Allowed” is one less that what your client has paid for. In this case you would need to authorize the server for “Local PC” use and one of the client PCs for network use. i.e. Two activations.

s_PLUS_ProgramName

 

This is the name of your application as will be displayed in the about popup. The default is the book userProperty INFO_Title of first book that links the protection system book (PLUS.sbk). The OpenScript can be found in the SharedScript “PLUS_Book” and you can set the INFO_Title by opening the book properties enter the “Book title:” in the “Summary” tab. Note, if your ToolBook application has more than one book and you allow the user to launch any one of these books then you may need to “hard wire” this data which will allow you to have a different “book title” for each of your books and have a single “Program Name”

s_PLUS_SecFlag

int

This flag can be 0, 1, 2 or 3 where:
0 = Authorized – the license file is authorized and s_PLUS_Authorized is set to true
1 = Periodic license and within the period – the license file may or may not be authorized, s_PLUS_Authorized is set to true or false
2 = Periodic license and expired – the license file may or may not be authorized, however, s_PLUS_Authorized is set to false.
3 = Not authorized, an error or security violation - the license file may or may not be authorized, however, s_PLUS_Authorized is set to false., the details are stored in s_PLUS_Message and could be:
This program must be registered before it can be used.
User Limit Exceeded! Please purchase additional licenses. – Network installations
Your clock has been turned back. – Periodic license
This program has not been authorized for network use. – Trying to run a local PC license on a network
This program has an invalid license file. – User has tried to break into the system.
This program has an invalid license file, Network Shared name mismatch! – Network installation and your customer has copied/moved your software to another path on the same server, if copied this would give them twice the number of network users at no extra cost.


Software Protection Useful Functions


Software Protection Limitations


Frequently Asked Questions

Everything was working fine and now my users are getting error messages?
Updates to operating systems may result in these types of issues.  This does not have anything to do with the Protection Plus Widget itself, but rather it is likely an issue with the Protection Plus Active X Control.  I highly recommend that you maintain a support agreement with software key so that when these issues arise you will be able to get an update that will overcome the issue you are having.


Troubleshooting