Copyright: Copyright © 1995 Rainbow Technologies


API (Application Program Interface)

The set of client interface routines your application uses to communicate with the SentinelSuperPro driver, which in turn communicates with the hardware key.


About Rainbow
Rainbow Technologies

9292 Jeronimo Rd

Irvine, Ca 92718

Main Phone:	(800) 852-8569

Main Fax:	(714) 454-8557

BBS:	(714) 454-1058

Tech Support:	(800) 959-9954

Tech Support Fax:	(714) 454-6516


activation password

A two-word value that can be used to activate an inactive algorithm descriptor.  The password is programmed into the two cells immediately following the algorithm descriptor.  You give your users the password and a utility with which to enter it.

Activation passwords are identified by access code 3.  They are called hidden words because their values cannot be read by your application.


Address

The hex address for this cell (or the first cell, if you are defining a group of cells). You can type the address yourself, or click the down arrow and select the address you want.


Algorithm

A simple algorithm descriptor. Use this item type if you want to scramble an input string but do not want an associated counter or activation password.


Algorithm Descriptor

The bit pattern that defines how query strings will be scrambled. Word 1 is the hex value for the first word of the algorithm descriptor. Word 2 is the hex value for the second word of the algorithm descriptor.

The first character of the value in Word 2 controls (1) whether the algorithm is active or inactive, and (2) whether the enhanced algorithm engine is enabled or disabled. Details on this value are provided in the Developer's Guide. To make sure you are creating the type of algorithm you want, check the Algorithm Enabled and Enhanced Engine Enabled options at the bottom of the window. If you click a button to toggle the state of that option, SPROEDIT automatically changes the first character of Word 2 to make the algorithm work the way you want.


Algorithm Enabled

Controls whether the algorithm is active (enabled) or inactive (disabled). If you click this button on or off, SPROEDIT adjusts the value in word 2 of the algorithm descriptor if necessary.


Algorithm Word

The four-character hex value to be placed in a word to be used as half of an algorithm descriptor. This entry is required by the Algorithm Word (Locked and Hidden) item type only.

SPROEDIT does not validate values entered with this item type, nor will it set the value for you to make the algorithm active or enable the enhanced algorithm engine. You are responsible for ensuring that the algorithm descriptor is defined and positioned properly.


Algorithm Word (Locked and Hidden)

A cell that will be used as half of an algorithm descriptor. Usually, this item type is used when your protection strategy has the user or installer supply the second half of the algorithm descriptor in the field. Do not use this item type unless you are well aware of all rules governing algorithm descriptor values and location.


Algorithm with Counter

An algorithm descriptor that has a counter associated with it. Usually, this item type is used to limit the number of times a demo program can be executed.


Algorithm with Counter and Password

An algorithm descriptor that has a counter and a password associated with it. Use this item type to implement an algorithm if (1) the algorithm is to be deactivated when a specified counter reaches 0, and (2) the user must input a password to get the application to run initially, or to reactivate it after the counter reaches 0.


Algorithm with Password

An algorithm descriptor that has a password associated with it. Usually, this item type is used when you want the user to enter a password to get the application to run initially. (The password activates the inactive algorithm.)


Algorithm with Two Counters

An algorithm descriptor that has two counters. The first counter to reach 0 deactivates the algorithm, which usually stops your application from running properly.


Algorithm with Two Counters and Password

An algorithm descriptor that has two counters and a password. Use this item type to implement an algorithm when (1) the algorithm is to be deactivated when either of two counters reaches 0, and (2) the user must input a password to get the application to run initially, or to reactivate it after it is deactivated.


Before You Run

Before you run the SPROEDIT utility, do the following:

*	Review the information in Chapter 6 of the Developer's Guide on cell types and how they can be used.

*	Plan your protection strategy. Decide how you will use each memory cell, and prepare a worksheet with cell addresses, values, and cell types. A sample worksheet you can photocopy is provided in Appendix C of the Developer's Guide.

*	Make sure you have the developer ID and passwords given to you in your evaluation kit.

*	Attach your SentinelSuperPro key to a parallel port on your programming workstation. You must have a key attached when you run SPROEDIT.

The programming specifications you create with SPROEDIT are tied to your developer ID. If you have multiple developer IDs, make sure you log on with the correct one before creating files.


Change Passwords

The Change Passwords option on the Key menu lets you enter new values for your developer ID, write password, and overwrite password. This is equivalent to exiting and logging back on, but does not require you to save the programming specifications currently displayed.

Remember that key files are tied to their developer IDs. If you enter a new developer ID, you cannot access files created with the one you used previously.

To enter a different developer ID and/or passwords:

1	Pull down the Key menu and select Change Passwords.

2	Enter the new developer ID, write password, and overwrite password. Enter all values, even those you are not changing.

3	Click OK.


Contents

Getting Started

Before you run

Items and Item Types

Defining Items

Key Files

Menu Commands

Glossary

Using SPROEDIT

Start SPROEDIT

Program Cells

Modify Cell Specifications

Delete Cell Specifications

Save Data to a File

Open a File

Refresh the Screen

Read Data from a Key

Write Data to a Key

Program Multiple Keys

Send a Query

Change Passwords

Convert Hex to Decimal

Create a Listing File

Exit SPROEDIT


Convert Hex to Decimal

The Hex <==> Decimal command on the Utilities pull-down menu lets you convert numbers from hex to decimal or vice versa. If you have decimal data that you wish to program into the key, you can use this command to determine the hex values required for programming.

To convert numbers between hex and decimal:

1	Pull down the Utilities menu and select the Hex <==> Decimal command.

2	Type the value you want to convert in the appropriate field.

3	The converted value appears in the opposite field. Record the value shown.

4	Repeat steps 2 and 3 as desired. When you are finished converting numbers, click OK.


Counter

A cell that contains a value you can decrement. This item type can be used to limit the number of times a demo program can be executed, or to count the number of times any particular operation is performed.


Counter, Counter #1, Counter #2

The initial value (in hex) to be stored in a counter.


Create

The Create pull-down menu lists the various ways SentinelSuperPro cells can be programmed.  To program a cell, you start by selecting an option from this menu.

Some options on the Create menu program multiple cells at once. For example, if you choose Algorithm with Counter, you will program three cells: two for the algorithm descriptor and one for the counter.

The options listed on the Create menu are called "item types." Each time you select one, you create an "item." An item is simply the programming specifications for one or more cells.

See also

Items and Item Types


Create a Listing File

The Create Listing File command on the Utilities pull-down menu saves a copy of your programming specifications to a disk file. You can then review or print the file with the Windows Notepad. The file contains a copy of the key matrix, plus a description of each item programmed.

To create a listing file:

1	Pull down the Utilities menu and select Create Listing File.

2	Select Yes to continue or No to cancel.

3	Enter a name for the file and click OK.

4	The listing file is displayed in Notepad for you to review or print.


data word

A cell in a SentinelSuperPro key that is used to store information.  Your application can use the stored value to verify that the key is still attached, or to control program flow or operation.  A data word has an access code of 0 (read/write) or 1 (read-only).


Defining Items

To program cell values and types, you add an item using the Create menu. After you select an item type, SPROEDIT displays a dialogue box with fields appropriate for that item type.

The following are all possible fields that may appear when you define an item. Only the fields appropriate to the selected item appear at any one time.

Identifier

Address

Algorithm Descriptor

Algorithm Word

Counter, Counter #1, Counter #2

Data Word

Activation Password

Algorithm Enabled

Enhanced Engine Enabled


Delete Cell Specifications

To delete the value and cell type programmed for a cell, you delete the item that defines it.

To delete cell specifications:

1	Double-click the item that defines the cell(s) you want to delete, or click on any of the item's cells in the key matrix.

2	Review the displayed data. Make sure this is the item you want to delete.

3	Click Delete.

4	Select Yes to delete the item, or No to cancel.

5	If you selected Yes, the item is deleted from the item list. The corresponding cell(s) in the matrix are changed to 0000 ** (undefined).


Enhanced Engine Enabled

Controls whether the enhanced algorithm engine is enabled or disabled. If you click this button on or off, SPROEDIT adjusts the value in word 2 of the algorithm descriptor if necessary. This feature is available only with the latest model of the SentinelSuperPro.


Exit SPROEDIT

To quit from the SPROEDIT utility, select the Exit command from the File pull-down menu.

To exit from SPROEDIT:

1	Pull down the File menu and select Exit.

2	Select Yes to exit or No to continue using SPROEDIT.


File

The File pull-down menu provides commands that let you create and update disk files that contain your programming specifications. By saving your cell specifications to a file, you can easily recall them and modify them or use them to program additional keys. SentinelSuperPro files created through SPROEDIT are called key files.

New	clears the work buffer by setting all unrestricted cells to undefined.

Open	lets you edit or review an existing key file.

Save	writes the displayed data to disk under the original file.

Save As...	writes the displayed data to disk a new name you provide.

Exit	quits the SPROEDIT utility.

None of these commands has any effect on the hardware key itself. The File commands simply create and access disk files that you can subsequently write to the hardware key using the Key menu.


Getting Started

Before you run

Items and Item Types

Defining Items

Key Files

Menu Commands

Glossary


Glossary

access code

activation password

active/inactive bit

algorithm

algorithm descriptor

API (Application Program Interface)

counter word

data word

developer ID

hidden word

input string

locked word

overwrite password

query

response string

software lock

write password


Help

The Help pull-down menu provides on-line help for using SPROEDIT.


Identifier

A unique, maximum 16-character name that describes the item. Use this field to identify how this item is used in your protection strategy, or to describe the type of data it stores. The identifier appears in the item list to identify the item.


Items and Item Types

The cell or group of cells you are programming is assigned a category called an "item type." Basically, an item type identifies the way you want to use the cell(s). For example, "Data Word" is an item type in which you define a single data word (DW) cell. "Algorithm With Counter" is an item type in which you define three cells: two algorithm descriptor words and one algorithm counter word (CA).

For more information on how certain cell types and cell groups can be used, see the Developer's Guide.

Algorithm

Algorithm with Counter

Algorithm with Counter and Password

Algorithm with Password

Algorithm with Two Counters

Algorithm with Two Counters and Password

Algorithm Word (Locked and Hidden)

Counter

Data Word

Locked Data Word


Key

The Key pull-down menu provides commands used to interface with a hardware key attached to the programming workstation.

Read	displays the contents of the attached key.

Write	programs the attached key with the values displayed on the screen.

Query	lets you send a query string to a specified algorithm descriptor in the attached key, and receive the scrambled value returned. Use this command to determine the values your application will receive when it uses the sproQuery() API function.

Change

Passwords	lets you log on again, so you can enter a different developer ID, write password, and/or overwrite password.

Program Units	gives you an easy way to program multiple keys (sequentially) with the same data.


Key Files

When you use SPROEDIT, you can save your programming specifications to a file on disk. This file, called a key file, contains all of the items you have programmed. Once a key file has been saved, you can read it back into the SPROEDIT buffer to modify it or to use it to program keys.

Your developer ID is encoded into each key file you save. To open a key file later, it must have the same developer ID as the one you used to log on. You cannot access a key file created under another developer ID.

Note	SentinelSuperPro key files have a special file format. They can be created only with SPROEDIT.

See also

Open a File

Save Data to a File


Locked Data Word

A cell that contains a read-only data value your application can test. Your application can read the stored data but cannot change it without the overwrite password.


Menu Commands

The menu bar at the top of the SPROEDIT screen provides the following commands:

File	Provides commands that let you open and save key files (files that contain your programming specifications).

Create	Lists the ways you can program each cell.

Key	Provides commands that let you read from, write to, and query a hardware key.

Utilities	Provides various functions you may find helpful when running SPROEDIT.

Help	Provides on-line instructions for using SPROEDIT.


Modify Cell Specifications

To change the specifications for a cell, you change the item it belongs to. First, select the item from the Item List and select it, or click on any of the item's cells. This displays dialogue box for that item. You can then change each field as desired.

See Items and Item Types for definitions of the fields used to describe each item.

If you change the value assigned to a cell, the change is reflected in the key matrix.

Note	You cannot change an item's type. To redefine an item, delete it and then add it back.

To modify cells:

1	Double-click the item that defines the cell(s) you want to change, or click on the cell in the matrix. If the item affects more than one cell, you can click any of its cells.

2	Change the values programmed for the item as desired.

3	When the data is correct, click OK. If you want to cancel the change, click Cancel.


Open a File

After you have used Save to create a key file, you can load that file back into the SPROEDIT buffer using the Open command. Use this option if you want to program a key using specifications you have already saved, or if you want to modify the saved specifications.

To create a key file, you must use the Save command on the File pull-down menu. If the file you try to open is not an SPROEDIT key file, an error is displayed.

You cannot open a file created using a developer ID other than the one you are now logged in with.

To open a key file:

1	Pull down the File menu and select the Open command.

2	Change directories if needed, then select the desired file.

See also

Key Files


Program Cells

To program a cell, you choose an item type from the Create menu and completing the dialogue box it displays.

See Items and Item Types for definitions of the fields used to describe each item.

To program cells:

1	Pull down the Create menu and choose the type of item you want to program. (You can also click the cell you want to define, then select the desired item type from a pop-up menu.)

2	Complete the displayed entry fields. For the Address field, click the down arrow and select the desired entry.

If you clicked on a cell in step 1, the address is filled in automatically. Note that if you select an item type that requires multiple cells, the address shown is that of the first cell, which may not be the one you clicked on.

3	When the entry fields are complete, click OK. The new item is added to the list below the key diagram, and the diagram is updated with your changes.


Program Multiple Keys

Use the Program Units command to program your production keys.  Every key must be programmed separately.

To program multiple keys:

1	Program one test key with your specifications. Save the specifications to a file.

2	Test your protected application with the test key. Make any changes to the programming specifications as required. Save the changes to the key file.

3	When your specifications have been fully tested, attach the first key to a parallel port.

4	Start Windows, launch SPROEDIT, and log on.

5	Pull down the File menu, select Open, and enter the name of your key file.

6	Pull down the Key menu and select Program Units.

7	Press ENTER to program the attached key. Note that the Units Programmed field shows the number of keys programmed so far.

8	Remove the first key and insert the next key.

9	Repeat steps 7 and 8 until all keys are programmed.


Read Data from a Key

The Read command on the Key pull-down menu displays the cell values and cell types programmed into the key attached to your workstation. The data appears in the matrix.

This is a read-only option: you cannot modify the data programmed into the key, and cannot save the displayed data to a file. To reprogram a key, you must create new items and write them to the key.

For security reasons, hidden cell types (algorithm descriptors and passwords) are not readable. The values in these cells appear as all asterisks.

To read a key's cell specifications:

1	Attach the key to a parallel port on your workstation. This key must have the same developer ID as the one you used when you logged on.

2	Pull down the Key menu and select Read.

3	SPROEDIT displays the key's data. Review the display.

4	When finished, click OK.


Refresh the Screen

The New command on the File pull-down menu clears all programming information on the screen. Use this command if you want to start completely over.

To refresh the SPROEDIT screen:

1	Pull down the File menu and select New.

2	To confirm the refresh, select Yes. If you change your mind, select No to leave the work buffer as is.


Save Data to a File

To create or update a key file, use the Save command on the File menu. If you are designing a complex programming scheme, you should use Save often to prevent losing your work in case of a system failure.

When naming your files, consider using a name that identifies the application the key is programmed to control. You should also use a consistent extension (such as .DAT) for all key files.

To save your key file:

1	Pull down the File menu and select the Save command (to save the file under its original name) or Save As... (to save the file under a new name).

2	If you chose Save As..., select the desired directory and enter a name for the file.

See also

Key Files


Send a Query

The Query command on the Key pull-down menu lets you send a string to the key, to determine the responses your application will receive when it performs queries.

Note	If the response matches your query, the address you specified is not the first cell of an active algorithm descriptor. Use the Read command on the Key menu to find the algorithm cell.

To query the attached key:

1	Pull down the Key menu and select Query.

2	In Address, type the starting cell address (an even number from 02-3E) of the algorithm descriptor to be used for the query.

3	In Query String, type the data to be scrambled  up to 112 hex characters (56 bytes). A longer entry may be allowed but is not supported by the driver. Your entry must contain an even number of characters.

4	Click Query. SPROEDIT displays the scrambled response.  Make a note of this response value for use in your protected application.

5	To send another query, go back to step 2.

6	When you are finished, click Cancel.


Start SPROEDIT

To start SPROEDIT:

1	Install the software on your programming system as described in Chapter 3 of the Developer's Guide.

2	Connect a SentinelSuperPro key directly to any parallel port. Attach only one key.

3	Start Windows, then launch SPROEDIT through the File Manager.

4	Enter the developer ID, write password, and overwrite password provided in your evaluation kit.  All entries must be in hex.  For security purposes, your entries are hidden.

5	Click OK.

Note 	If you enter the wrong write or overwrite password, no error is displayed. If the write password is invalid, an error will appear when you attempt to write to the key. If the overwrite password is missing or invalid, you will not be able to write to any words except data and undefined words (assuming your write password is correct). To correct your passwords after logging in, use the Change Passwords command on the Key pull-down menu.


Using the Integrated Editing Environment

Start SPROEDIT

Program Cells

Modify Cell Specifications

Delete Cell Specifications

Save Data to a File

Open a File

Refresh the Screen

Read Data from a Key

Write Data to a Key

Program Multiple Keys

Send a Query

Change Passwords

Convert Hex to Decimal

Create a Listing File

Exit SPROEDIT


Utilities

The Utilities pull-down menu provides various commands related to the programming process.

Hex <==> Decimal	converts hexadecimal numbers to decimal numbers and vice versa.

Create Listing File	saves the displayed programming specifications to a file which you 	can print for reference.


Write Data to a Key

The Write command on the Key pull-down menu programs the cell specifications displayed on your screen into the attached SentinelSuperPro key. Use this command when you have finished your programming layout and are ready to program a key to test with your application.

After you have fully tested your protection scheme, you can use the Write command to program each production unit prior to shipment. If you are programming several keys, you may prefer the Program Units command. Remember that every key must be programmed separately.

To write to a key:

1	Attach the key to a parallel port on your workstation. This key must have the same developer ID as the one you used when you logged on.

2	Pull down the Key menu and select the Write command.

3	Select Yes to continue or No to cancel.


access code

A one-byte field that identifies the accessibility (to your application) of the value that is stored in a cell.  Possible values are:

0	read/write data word
1	read-only (locked) data
2	counter
3	algorithm/hidden


active/inactive bit

A bit in an algorithm descriptor that controls whether or not the algorithm will respond correctly a query.  To use an algorithm descriptor, it must be active.

An inactive algorithm descriptor can be made active using the sproActivateAlgorithm() function.  An active algorithm can be made inactive by using the sproDecrement() function to decrement an associated counter to 0.


counter word

A cell that is used to count down from a pre-programmed value.  The value in a counter word is decremented by 1 every time your application sends the sproDecrement() API function.  A counter word has an access code of 2.

Usually, counters are used to control the number of times a demo application is executed.  If desired, a counter can be associated with an algorithm descriptor; when the counter reaches 0, the algorithm is deactivated automatically.


developer ID

A unique identification code assigned to you by Rainbow Technologies or your distributor.  You must use your developer ID to program your keys.  You must also use it in your protected application to establish a connection with a key.


hidden word

A cell that cannot be read by your application.  Most hidden words are algorithm descriptors and activation passwords.  Your write password and overwrite password are also hidden words.  A hidden word has an access code of 3.


input string

The value an application sends in a query to the hardware key.  The key scrambles the string according to its internal logic and the bit pattern defined in a specified algorithm descriptor.  It then returns the response string to the application.


locked word

A data word that contains a value that can be read but not changed by your application unless the overwrite password is used.  A locked word has an access code of 1.


overwrite password

An identifier you must have in order to set or change the value or access code of any cell other than a data word or a cell that is not yet defined.

Your overwrite password will be given to you by Rainbow Technologies or your distributor.  Keep this value secure: it has the power to reprogram all unrestricted cells in your key.


query

The process by which an application verifies that the hardware key is attached.  This is done by sending an input string to be scrambled using a specific algorithm descriptor stored in the key.

If the expected response string is returned, the application assumes that the correct hardware key is connected.  It then continues executing until the next query.


response string

The scrambled result derived when the hardware key processes an input string according to the bit pattern contained in an algorithm descriptor.  The hardware key returns the response string to the application.  The application then uses the response string to determine whether the user is authorized to run the application.


software lock

A decision point in an application.  The purpose of a software lock is to verify the presence of the correct hardware key.

For example, an application might send a data string to the hardware key, and require a specific scrambled response in order to continue execution.  Other software locks may simply read the value in a cell and compare it to the value known to be programmed in that cell.


write password

An identifier you must have in order to set or change the value or access code of a data word or a cell that is not yet defined.  This password also lets you decrement counter words.  Your write password will be given to you by Rainbow Technologies or your distributor.