Sentinel Superpro 6.5 Developer'S Guide
Sentinel Superpro 6.5 Developer'S Guide
Sentinel Superpro 6.5 Developer'S Guide
5
Developer’s Guide
Copyright © 2007, SafeNet, Inc.
All rights reserved.
All attempts have been made to make the information in this document complete and accurate. SafeNet, Inc. is
not responsible for any direct or indirect damages or loss of business resulting from inaccuracies or omissions.
The specifications contained in this document are subject to change without notice.
SafeNet, Sentinel, and Sentinel SuperPro are either trademarks or registered trademarks of Safenet, Inc.
Microsoft Windows, Windows 98, Windows ME, Windows 2000, Windows 2003, Windows XP, and Windows Vista
are either trademarks or registered trademarks of Microsoft Corporation in the United States and other
countries. Linux is a trademark of Linus Torvalds, in the United States and other countries. All other product
names referenced herein are trademarks or registered trademarks of their respective manufacturers.
CONFIDENTIAL INFORMATION
Sentinel SuperPro protection system is designed to protect your applications from unauthorized use. The less
information that unauthorized people have regarding your security system, the greater your protection. It is in
your best interest to protect the information herein from access by unauthorized individuals.
Part Number 007632-001, Revision A
Software versions 6.5 and later
U.S. (New Jersey) U.S. (Virginia) U.S. (Irvine, California) U.S. (San Jose, California)
+1 201.333.3400 +1 703.279.4500 +1 949.450.7300 + (408) 452 7651
The Beijing, China; Irvine, California, U.S.A; and Rotterdam, The Netherlands
facilities are certified to the latest, globally-recognized ISO 9001:2000 standard.
The certificate number is: CERT-02982-2003-AQ-HOU-RAB Rev 3.
RNBOsproSetHeartBeat............................................................................................. 341
RNBOsproSetProtocol ............................................................................................... 344
RNBOsproCheckTerminalService ............................................................................. 346
RNBOsproSetSharedLicense...................................................................................... 348
RNBOsproWrite......................................................................................................... 350
API Status Codes ....................................................................................................... 352
M ............................................................................................................................... 428
N ................................................................................................................................ 428
O ................................................................................................................................ 429
P ................................................................................................................................ 429
Q ................................................................................................................................ 430
R ................................................................................................................................ 430
S................................................................................................................................. 430
T ................................................................................................................................ 432
U ................................................................................................................................ 432
W ............................................................................................................................... 432
Thank you for selecting Sentinel SuperPro to protect your applications from
unauthorized use. The Sentinel SuperPro software protection system com-
bines a programmable hardware key with the ability to encrypt data, giving
you a wide range of methods for securing multiple applications from illegal
distribution and use.
<OS Drive> The root drive on your system where your operating system
is installed.
Chapter/Appendix Description
Chapter/Appendix Description
Chapter/Appendix Description
E-mail [email protected]
United States
Telephone (800) 545-6608, (410) 931-7520
Europe
E-mail [email protected]
France
Telephone 0825 341000
Germany
Telephone 01803 7246269
United Kingdom
Telephone +44 (0) 1276 608000, +1 410 931-7520 (Intl)
Pacific Rim
E-mail [email protected]
Australia and New Zealand
Telephone +1 410 931-7520(Intl)
China
Telephone (86) 10 8851 9191
India
Telephone +1 410 931-7520 (Intl)
Taiwan and Southeast Asia
Telephone (886) 2 27353736, +1 410 931-7520 (Intl)
Export Considerations
We offer products that are based on encryption technology. The Bureau of
Industry and Security (BIS) in the U.S. Department of Commerce adminis-
ters the export controls on our commercial encryption products.
In this chapter we will assess how software piracy threatens your profits and
understand how Sentinel SuperPro can curb widespread piracy and add
value to your software distribution.
3. Once found, the server queries the Sentinel System Driver to obtain
the license limit from a hardware key attached to an external port on
the server.
4. The driver reads the license limit in the key and returns it back to the
server.
5. The server decides whether or not to grant the license and then sends
the license information to your application.
8. When all software locks are complete, the application releases the
license back to the key through the server, allowing the license to be
obtained by another client.
Note: The above procedure assumes use of the default access mode:
RNBO_SPN_ALL_MODES. You can change how Sentinel SuperPro obtains a
license by changing the access mode. See “Setting the Access Mode” on
page 103 for more information.
Protection Types
Sentinel SuperPro offers you two methods for protecting your application:
integrated or automatic. When and where the software locks are implemented
depends on the type of protection being used.
■ Integrated: Integrated protection consists of software locks (API
function calls) added directly to your source code. It is used to create a
custom protection strategy, with control over the amount and
location of software locks.
Because you must understand the API function calls used to support
the protection strategy you have designed, and manually add them to
your code, using integrated protection may take longer.
Automatic protection also gives you more control over demo options
such as expiration dates, counters and time/date limits.
For more details, see “About Shell Protection” on page 7 and “Provid-
ing Advanced Security Settings” on page 167.
1.The method in which protective wrappers are put around the application quickly and eas-
ily.
Shell also provides the following security options that you can choose while
adding a Shell feature :
■ Multi-layered Protection
The Shell provides multi-layered protection. Since the joint between
an application and the Shell layers is vulnerable to attacks, you can
choose the number of layers the Shell uses to protect your application,
from level 1 to 5. Level 1 provides reasonable protection and level 5
provides the most protection. However, with each level of protection
added, the size of the application and the time it takes to start up also
increases. By default, level 3 multi-layering is used.
■ Anti-debugging Protection
The Shell is capable of detecting the debuggers, like SoftICE and
OllyDbg. It can also provide reasonable protection against break-
points targeted at important functions. You can choose to deny
application execution in the presence of debuggers. The protected
application will exit if a debugger is detected on a system. Non-
malicious users will close the debugger and start the application
again. Otherwise, you may even allow your application to run in the
presence of debuggers.
■ Anti-reverse Engineering Protection
Using the Shell SDK module, you can protect your important code
fragments, strings, and constants for Visual C, Visual BASIC, and
Delphi. Refer to the readme available under the
<installdir>\Tools\Shell SDK folder for more details.
■ Anti-dumping Protection
Shell provides protection against a memory dump of the protected
application. You need to select the Hide import symbols check box
(under the Security tab of Add/Edit Shell Feature dialog box) to
enable this added protection.
■ Anti-disassembling Protection
A Shell-protected application is difficult to disassemble due to the use
of expert techniques, like Maze technology and dummy macros.
For example, cells can be used to store fixed user data, such as serial
numbers, user names or codes controlling feature access. Such data
can be read by your application to verify the key is still attached or to
perform some other function. You can also use stored data to control
program flow or application functions.
Cells can also store algorithms used to scramble query codes sent by
your application. Other cells can be programmed as counters used to
restrict the number of executions. While some memory cells are
reserved for SafeNet use, most are fully programmable by you the
developer. See the table below for the reserved memory ranges and
available memory for various types of keys.
Note: In SuperPro XM keys, the last16 cells apart from the 8 reserved for
system information are also reserved for SafeNet’s usage.
■ Password Protection
The ability to program Sentinel SuperPro hardware keys is protected
by three passwords: the Write Password and two Overwrite Passwords.
The Write Password allows you to write to undefined cells and read/
write data words. The two Overwrite Passwords allow you to write to
all other non-restricted cells: read-only data words, counters and
algorithm words.
You must have your passwords to program keys through the SSP
Toolkit or the Make Keys Utility. You must also include the passwords
in your protected application to reprogram cells in the field or use
some API function calls. Passwords ensure only authorized users can
change your protection strategy or program keys.
■ Sublicensing
Sublicensing is useful when you want to apply a license limit to a spe-
cific feature of the protected application. If you have specified a user
limit in your protection strategy, you can allow sharing the sub-
licenses issued on the basis of a combination of User Name and MAC
Address(i.e. a seat), so that if a request for accessing that feature of the
protected application comes more than once from the same seat, then
no extra license is consumed.
Thus, the network’s total concurrent license limit is the sum of all the
limits in all keys attached to all servers. If a user attempts to access a
protected application (assuming the application is running in the
default RNBO_SPN_ALL_MODES—see page 104), and the first
server has reached its license limit, Sentinel SuperPro automatically
checks the first key on another server for an available license. Use of
multiple servers helps avoid a single point of failure.
■ Application Time-Out
The server can disconnect a user, and release the license for use by
other users, after a pre-determined amount of time has elapsed with-
out a Sentinel SuperPro query or heartbeat message. This helps pre-
vent idle users from tying up licenses, and permits recovery of licenses
used by aborted programs or workstations that are unexpectedly dis-
connected from the network.
Tip: Refer to Chapter 10, “Programming Keys,” on page 233 for more informa-
tion about programming product and distributor keys. For more information
about how keys are activated and updated, refer to Chapter 12, “Activating
and Updating Keys,” on page 265.
The hardware key is the heart of Sentinel SuperPro protection. The key con-
trols and verifies access to your protected applications, assuring that only
authorized users can run them.
Before you begin designing your protection strategy, however, you should
understand how the key works, and how it can be used.
This chapter covers the following topics:
■ Physical key layout
■ Possible uses for the key
■ Reserved cells
■ Access codes
■ Cell values
■ Cell types
■ Algorithm values and addresses
■ Ordering and returning keys
Reserved
Cells 00 01 02 03 04 05 06 07
08 09 0A 0B 0C 0D 0E 0F
10 11 12 13 14 15 16 17
Available 18 19 1A 1B 1C 1D 1E 1F
Cells in 20 21 22 23 24 25 26 27
SuperPro
28 29 2A 2B 2C 2D 2E 2F
XM Keys
30 31 32 33 34 35 36 37
38 39 3A 3B 3C 3D 3E 3F
40 41 42 43 44 45 46 47
48 49 4A 4B 4C 4D 4E 4F
50 51 52 53 54 55 56 57
58 59 5A 5B 5C 5D 5E 5F
60 61 62 63 64 65 66 67
68 69 6A 6B 6C 6D 6E 6F
70 71 72 73 74 75 76 77
78 79 7A 7B 7C 7D 7E 7F
80 81 82 83 84 85 86 87
88 89 8A 8B 8C 8D 8E 8F
90 91 92 93 94 95 96 97
98 99 9A 9B 9C 9D 9E 9F
A0 A1 A2 A3 A4 A5 A6 A7
A8 A9 AA AB AC AD AE AF
B0 B1 B2 B3 B4 B5 B6 B7
B8 B9 BA BB BC BD BE BF
C0 C1 C2 C3 C4 C5 C6 C7
C8 C9 CA CB CC CD CE CF
D0 D1 D2 D3 D4 D5 D6 D7
D8 D9 DA DB DC DD DE DF
E0 E1 E2 E3 E4 E5 E6 E7
E8 E9 EA EB EC ED EE EF
Extra reserved F0 F1 F2 F3 F4 F5 F6 F7
Cells for
SuperPro XM F8 F9 FA FB FC FD FE FF
Keys
Tip: Think of a cell as being a holding container (memory location) for the words
that make up your algorithms, counters and other elements. Cells have
addresses that represent their location on the key, much like street addresses
represent the location of houses in a neighborhood.
Note: In SSP XM key, the password counter is enabled. If someone uses wrong
password while writing to a cell for more than 15 times, the key gets
locked. The key must be returned to SafeNet for unlocking.
When you program a cell, you assign it various attributes. These attributes
determine how the cell (and the word it contains) is used by your applica-
tion. Cell attributes include the cell type, the access code and the cell value.
Each of these attributes are explained later in this chapter. Generally, each
cell contains one of the following types of words:
■ Data Words: A data word can store data such as sublicenses,
customer information, serial numbers, passwords, and check digits.
You code your application to read the word and then evaluate and act
upon the stored value. A data word cell may be programmed as read-
only or read/write.
■ Counter Words: A counter word contains an initial value you set
that is then decremented by your application. A typical use of a
counter word is to limit the number of times a demo application can
be executed.
■ Algorithms: An algorithm contains a bit pattern that defines how
the hardware key should encrypt query data sent by your application.
The key uses the algorithm cell value—plus an internally stored
proprietary algorithm—to transform the query data and then return
a value to your application. You design your application to send
queries to the key and then evaluate and act upon the responses.
Algorithms are active or inactive. Only active algorithms can return a
valid response to a query. The active/inactive bit in the cell value con-
trols whether or not the algorithm is active. “Algorithm Values” on
page 35
Additionally, all algorithms are two words (and thus, two cells) long,
and may have activation passwords and counters associated with
them (see “Valid Algorithm Addresses” on page 37).
Restricted Cells
Cells 00 through 07 in SuperPro key are restricted cells that contain fixed,
preprogrammed system information:
Programmable Cells
Cells 08 through 3F are available for you to program in SuperPro Key, while
the SuperPro XM key provides you with a vast cell range to program i.e.
from 08 through EF. The next section explains in detail how to program
these cells in the key.
Access Codes
Every cell has an access code associated with it that controls how the cell can
be used by your application—it defines the cell’s cell type attribute. For
example, some cell types have an access code that permits cell values to be
both read and overwritten, while others are read-only, or not writable at all.
Access codes are numbers whose value can be 0 - 3 or 7. Both SuperPro and
SuperPro XM supports access codes in the 0 - 3 range. However, access code
7 is only valid on SuperPro XM keys.
When you define an element using the SSP Toolkit’s Element Definition Wiz-
ard, you do not assign the cell access codes. The access codes are determined
by the wizard, based on the protection feature you are implementing. If your
application programs or reprograms cells in the field, it must specify the new
access code.
Code Description
0 Read/write data word
Your application can read the word in the cell and, if the Write
Password is supplied, modify its contents.
1 Read-only (locked) data word
Your application can read the word in the cell, but cannot change it
without the Overwrite Passwords.
2 Counter word
The cell contains a word (value) that your application can decrement
using the Write Password. The cell’s value cannot be changed (other
than by decrementing it) without the Overwrite Passwords.
3 Locked and hidden/algorithm word
Your application cannot read the cell’s value. Modification requires the
Overwrite Passwords. The cell value (contents) is hidden (unreadable).
7 AES Algorithm Engine
Access code 7 is used for AES algorithm words and is exclusive to the
SuperPro XM key. Similar to access code 3, your application cannot read
the cell's value. Modification requires the Overwrite Passwords, even if
the cell is unlocked (access code 0).
Cell Types
Each cell is assigned a code that defines how you want to use the selected
cell. This code is called a cell type. The cell type classifies the type of data
stored in the cell, which in turn affects how the cell can be used.
Each cell type is identified by a two-letter abbreviation; for example, CW
identifies a counter word.
Some cell types are designed to be used in groups. For example, algorithms
can have counters and passwords associated with them. Other cell types
have address restrictions, meaning they can be assigned only to specific cells
on the key.
The following table describes the available cell types, with the following sec-
tions explaining each cell type in greater detail.
Undefined (**)
The Undefined cell type is used to identify a cell that has not yet been pro-
grammed or is not used in your protection strategy. This cell type is
identified by two asterisks (**).
Cells you don’t need for your protection strategy can be left undefined. How-
ever, you may want to program unused cells as read-only data words or
algorithm/hidden words. It prevents them from being written to without
both the write and overwrite passwords. Hackers can use an unlocked data
word to try to figure out the write password. Making unused cells read-only
or algorithm/hidden words helps to prevent these type of brute force attacks
on the write password.
Tip: Undefined cells can also be programmed with random values to make your
strategy more confusing for hackers. See “Programming a Product Key” on
Access Code
An Undefined cell has an access code of 0 – read/write data.
Valid Addresses
For the SuperPro key, any unrestricted cell in the range 08 - 3F can be classi-
fied as undefined. In the case of SuperPro XM key, the rule is the same except
the range is 08 - EF
Access Code
An AA cell has an access code of 3 or 7 – algorithm/hidden.
Valid Addresses
The first AA word must be in a cell located at an unrestricted, even address.
Additional restrictions apply if a counter and/or password is associated with
the algorithm. See “Valid Algorithm Addresses” on page 37 for more
information.
the same as that created by two AA or IA cells; the difference is that you can
program the descriptor in two steps, which may be useful in some protection
schemes.
The value in the second AH cell must be between:
■ 0000 to 7FFF for a disabled algorithm
■ 8000 to BFFF for an enabled simple algorithm
■ C000 to FFFF for an enabled enhanced algorithm
■ 8000 to FFFF for an enabled AES algorithm (access code must be 7)
See “Algorithm Values” on page 35 for more information.
AH cells can have a password and counter(s) associated with them.
Access Code
An AH cell has an access code of 3 or 7 (SuperPro XM only) – algorithm/
hidden.
Valid Addresses
An AH word can be located in any unrestricted cell 08 – 3F for Super Pro
keys and 08-EF for SuperPro XM Keys. You must leave an adjacent cell
vacant for the other half of the algorithm. Also, the first AH word of the pair
must be located in an even-numbered cell.
Additional restrictions apply if a counter and/or password is associated with
the algorithm. See “Valid Algorithm Addresses” on page 37 for more
information.
Access Code
An AP cell has an access code of 3 – algorithm/hidden. It cannot be directly
read or written to; its value is used only to verify a user-supplied password
during execution of the RNBOsproActiveAlgorithm() API function.
Because an AP cell has an access code of 3, it can also be used as an algo-
rithm. See “Querying Activation Passwords” on page 91 for more
information.
Valid Addresses
An AP cell must be located immediately after a two-word algorithm (cell
type AA, AH or IA).
Additional restrictions apply if a counter is also associated with the algo-
rithm. See “Valid Algorithm Addresses” on page 37 for more information.
Access Code
A CA cell has an access code of 2 – counter. It can be read, but cannot be
written to except by the RNBOsproDecrement() or RNBOsproOverwrite()
API functions.
Valid Addresses
A CA cell is always located immediately before a two-word algorithm (cell
type AA, AH or IA). See “Valid Algorithm Addresses” on page 37 for more
information.
Access Code
A CW cell has an access code of 2 – counter. It can be read, but cannot be
written to except by the RNBOsproDecrement() or RNBOsproOverwrite()
API functions.
Valid Addresses
Any unrestricted cell 08 – 3F for Super Pro keys and 08-EF for SuperPro XM
Keys can be classified as a CW cell type.
Warning! If you program a counter cell, and you use the next two cells for an
algorithm, the counter will function as an algorithm counter. When
the counter reaches zero, the algorithm will be deactivated, even if
you did not intend for that to happen.
Developer ID (DI)
The Developer ID (DI) cell type is used for cell 01 only. This cell holds a read-
only data word that contains the unique developer ID assigned to you by
SafeNet Inc. You cannot assign cell type DI to any other cell.
Access Code
A DI cell has an access code of 1 – locked. You can read the developer ID, but
cannot change it.
Valid Addresses
The only cell that can be defined as cell type DI is cell 01.
Access Code
A DL cell has an access code of 1 – locked. After you program the cell, your
application can read it, but cannot change it without the Overwrite
Passwords.
Valid Addresses
Any unrestricted cell 08 – 3F for Super Pro keys and 08-EF for SuperPro XM
Keys can be classified as a DL cell type.
Access Code
A DW cell has an access code of 0 – read/write. It can be reprogrammed
using the Write Password.
Valid Addresses
Any unrestricted cell 08 – 3F for Super Pro keys and 08-EF for SuperPro XM
Keys can be classified as a DW cell type.
Access Code
An IA cell has an access code of 3 or 7 for SuperPro XM keys – algorithm/
hidden.
Valid Addresses
The first IA cell must be at an unrestricted, even address. Additional restric-
tions apply if a counter and/or password is associated with the algorithm.
See “Valid Algorithm Addresses” on page 37 for more information.
Access Code
An RW cell has an access code of 3 – algorithm/hidden. You cannot read or
write to these cells.
Valid Addresses
The only cells defined as type RW are cells 05, 06 and 07 in case of SuperPro
Keys. However the SuperPro XM keys define 16 more cells from F0 to FF as
reserved cells apart from the cells 05, 06 and 07.
Note: Serial numbers ranging from 0–65535 are assigned sequentially and are
not guaranteed to be unique. If you require unique serial numbers, please
contact your SafeNet Inc. sales representative, as SafeNet must program
the keys.
Access Code
An SN cell has an access code of 1 – locked. You can read the serial number
but cannot modify the value in this cell.
Valid Addresses
The only cell defined as type SN is cell 00 in both Super Pro and SuperPro
XM keys.
Cell Values
Each cell also has a cell value containing a 16-bit value. The cell value is also
known as a word. The value in the second cell of an algorithm controls
whether or not the algorithm is active, and whether the enhanced algorithm
engine is enabled for the algorithm. See the next section for more
information.
Algorithm Values
There are special rules applied to the second cell of an algorithm. The word
(value) in the second cell controls:
■ Whether the algorithm is active or inactive. Only active algorithms
can be used for queries.
■ Whether the enhanced algorithm engine is enabled or disabled. The
enhanced algorithm engine provides a more secure algorithm.
The active/inactive state of an algorithm is controlled by bit 15 of the second
word of the algorithm:
■ If this bit is 1, the algorithm is active.
■ If this bit is 0, the algorithm is inactive
The state of the enhanced algorithm engine is controlled by bit 14 of the sec-
ond word of the algorithm:
■ If this bit is 1, the enhanced engine is enabled.
■ If this bit is 0, the enhanced engine is disabled.
Note: This bit 14 is not associated with the enhanced engine when the AES
engine is being used (access code = 7) but just becomes part of the data
like bits 13 to 0.
The following tables show how bits 14 and 15 of the second word control
the algorithm.
Second Word of an Active Algorithm, with Enhanced Engine Enabled
Bit Bit Bit Bit Bit Bit Bit Bit Bit Bit Bit Bit Bit Bit Bit
15 14 13 12 11 10 9 7 6 5 4 3 2 1 0
1 1 0 0 1 0 1 0 0 0 0 0 0 1 0
1 0 0 0 1 0 1 0 0 0 0 0 0 1 0
0 1 1 1 1 1 1 1 0 0 1 1 1 1 1
0 0 0 0 1 0 1 0 0 0 0 0 0 1 0
When you design your protection strategy, Sentinel SuperPro asks you if you
want the algorithm to be active or inactive. The following table summarizes
the effect of the value of the second word on the algorithm:
Note: AES algorithm can be activated only if SuperPro XM keys have been
selected on design time.
For example, an algorithm with a second word of 1FDC is inactive and has
the enhanced engine disabled because it falls within the range of 0000 –
3FFF. An algorithm with a second word of D000 is active and has the
enhanced engine enabled because it falls within the range of C000 – FFFF.
Note: For maximum security, use the AES algorithm engine in SuperPro XM keys.
Tip: While you are designing your protection strategy, the Element Definition
Wizard only allows you to select valid, available addresses for your elements.
You don’t need to worry about these restrictions while you are adding ele-
ments, but you should still be aware they exist.
These groups of cells are restricted as to where they can be placed on the
hardware key. The following combinations of algorithms, counters and
passwords (known as custom elements) are supported:
■ Algorithm (2 cells)
■ Algorithm with password (4 cells)
■ Algorithm with counter (3 cells)
■ Algorithm with two counters (4 cells)
■ Algorithm with password and counter (5 cells)
■ Algorithm with password and two counters (6 cells)
Tip: Remember, each word takes up one cell. So an algorithm with two counters
uses four cells, because it has four words: two counters, plus the algorithm’s
two words.
Note: MOD is used in the formula used to compute valid cell addresses. MOD is a
modulus arithmetic operator used to divide two numbers, resulting in the
remainder of the division. For example, 8 MOD 3 equals 2 because 8 / 3
equals 2, with a remainder of 2. The remainder is the result of the MOD
notation.
Color Element
Blue Algorithm
Magenta Counter
Yellow Password
Algorithm
A two-word algorithm that does not have a counter or password. It can start
in any unrestricted cell with an even address.
00 01 02 03 04 05 06 07
08 09 0A 0B 0C 0D 0E 0F
10 11 12 13 14 15 16 17
18 19 1A 1B 1C 1D 1E 1F
20 21 22 23 24 25 26 27
28 29 2A 2B 2C 2D 2E 2F
30 31 32 33 34 35 36 37
38 39 3A 3B 3C 3D 3E 3F
00 01 02 03 04 05 06 07
08 09 0A 0B 0C 0D 0E 0F
10 11 12 13 14 15 16 17
18 19 1A 1B 1C 1D 1E 1F
20 21 22 23 24 25 26 27
28 29 2A 2B 2C 2D 2E 2F
30 31 32 33 34 35 36 37
38 39 3A 3B 3C 3D 3E 3F
40 41 42 43 44 45 46 47
48 49 4A 4B 4C 4D 4E 4F
50 51 52 53 54 55 56 57
58 59 5A 5B 5C 5D 5E 5F
60 61 62 63 64 65 66 67
68 69 6A 6B 6C 6D 6E 6F
70 71 72 73 74 75 76 77
78 79 7A 7B 7C 7D 7E 7F
80 81 82 83 84 85 86 87
88 89 8A 8B 8C 8D 8E 8F
90 91 92 93 94 95 96 97
98 99 9A 9B 9C 9D 9E 9F
A0 A1 A2 A3 A4 A5 A6 A7
A8 A9 AA AB AC AD AE AF
B0 B1 B2 B3 B4 B5 B6 B7
B8 B9 BA BB BC BD BE BF
C0 C1 C2 C3 C4 C5 C6 C7
C8 C9 CA CB CC CD CE CF
D0 D1 D2 D3 D4 D5 D6 D7
D8 D9 DA DB DC DD DE DF
E0 E1 E2 E3 E4 E5 E6 E7
E8 E9 EA EB EC ED EE EF
F0 F1 F2 F3 F4 F5 F6 F7
F8 F9 FA FB FC FD FE FF
00 01 02 03 04 05 06 07
08 09 0A 0B 0C 0D 0E 0F
10 11 12 13 14 15 16 17
18 19 1A 1B 1C 1D 1E 1F
20 21 22 23 24 25 26 27
28 29 2A 2B 2C 2D 2E 2F
30 31 32 33 34 35 36 37
38 39 3A 3B 3C 3D 3E 3F
00 01 02 03 04 05 06 07
08 09 0A 0B 0C 0D 0E 0F
10 11 12 13 14 15 16 17
18 19 1A 1B 1C 1D 1E 1F
20 21 22 23 24 25 26 27
28 29 2A 2B 2C 2D 2E 2F
30 31 32 33 34 35 36 37
38 39 3A 3B 3C 3D 3E 3F
40 41 42 43 44 45 46 47
48 49 4A 4B 4C 4D 4E 4F
50 51 52 53 54 55 56 57
58 59 5A 5B 5C 5D 5E 5F
60 61 62 63 64 65 66 67
68 69 6A 6B 6C 6D 6E 6F
70 71 72 73 74 75 76 77
78 79 7A 7B 7C 7D 7E 7F
80 81 82 83 84 85 86 87
88 89 8A 8B 8C 8D 8E 8F
90 91 92 93 94 95 96 97
98 99 9A 9B 9C 9D 9E 9F
A0 A1 A2 A3 A4 A5 A6 A7
A8 A9 AA AB AC AD AE AF
B0 B1 B2 B3 B4 B5 B6 B7
B8 B9 BA BB BC BD BE BF
C0 C1 C2 C3 C4 C5 C6 C7
C8 C9 CA CB CC CD CE CF
D0 D1 D2 D3 D4 D5 D6 D7
D8 D9 DA DB DC DD DE DF
E0 E1 E2 E3 E4 E5 E6 E7
E8 E9 EA EB EC ED EE EF
F0 F1 F2 F3 F4 F5 F6 F7
F8 F9 FA FB FC FD FE FF
00 01 02 03 04 05 06 07
08 09 0A 0B 0C 0D 0E 0F
10 11 12 13 14 15 16 17
18 19 1A 1B 1C 1D 1E 1F
20 21 22 23 24 25 26 27
28 29 2A 2B 2C 2D 2E 2F
30 31 32 33 34 35 36 37
38 39 3A 3B 3C 3D 3E 3F
00 01 02 03 04 05 06 07
08 09 0A 0B 0C 0D 0E 0F
10 11 12 13 14 15 16 17
18 19 1A 1B 1C 1D 1E 1F
20 21 22 23 24 25 26 27
28 29 2A 2B 2C 2D 2E 2F
30 31 32 33 34 35 36 37
38 39 3A 3B 3C 3D 3E 3F
40 41 42 43 44 45 46 47
48 49 4A 4B 4C 4D 4E 4F
50 51 52 53 54 55 56 57
58 59 5A 5B 5C 5D 5E 5F
60 61 62 63 64 65 66 67
68 69 6A 6B 6C 6D 6E 6F
70 71 72 73 74 75 76 77
78 79 7A 7B 7C 7D 7E 7F
80 81 82 83 84 85 86 87
88 89 8A 8B 8C 8D 8E 8F
90 91 92 93 94 95 96 97
98 99 9A 9B 9C 9D 9E 9F
A0 A1 A2 A3 A4 A5 A6 A7
A8 A9 AA AB AC AD AE AF
B0 B1 B2 B3 B4 B5 B6 B7
B8 B9 BA BB BC BD BE BF
C0 C1 C2 C3 C4 C5 C6 C7
C8 C9 CA CB CC CD CE CF
D0 D1 D2 D3 D4 D5 D6 D7
D8 D9 DA DB DC DD DE DF
E0 E1 E2 E3 E4 E5 E6 E7
E8 E9 EA EB EC ED EE EF
F0 F1 F2 F3 F4 F5 F6 F7
F8 F9 FA FB FC FD FE FF
00 01 02 03 04 05 06 07
08 09 0A 0B 0C 0D 0E 0F
10 11 12 13 14 15 16 17
18 19 1A 1B 1C 1D 1E 1F
20 21 22 23 24 25 26 27
28 29 2A 2B 2C 2D 2E 2F
30 31 32 33 34 35 36 37
38 39 3A 3B 3C 3D 3E 3F
00 01 02 03 04 05 06 07
08 09 0A 0B 0C 0D 0E 0F
10 11 12 13 14 15 16 17
18 19 1A 1B 1C 1D 1E 1F
20 21 22 23 24 25 26 27
28 29 2A 2B 2C 2D 2E 2F
30 31 32 33 34 35 36 37
38 39 3A 3B 3C 3D 3E 3F
40 41 42 43 44 45 46 47
48 49 4A 4B 4C 4D 4E 4F
50 51 52 53 54 55 56 57
58 59 5A 5B 5C 5D 5E 5F
60 61 62 63 64 65 66 67
68 69 6A 6B 6C 6D 6E 6F
70 71 72 73 74 75 76 77
78 79 7A 7B 7C 7D 7E 7F
80 81 82 83 84 85 86 87
88 89 8A 8B 8C 8D 8E 8F
90 91 92 93 94 95 96 97
98 99 9A 9B 9C 9D 9E 9F
A0 A1 A2 A3 A4 A5 A6 A7
A8 A9 AA AB AC AD AE AF
B0 B1 B2 B3 B4 B5 B6 B7
B8 B9 BA BB BC BD BE BF
C0 C1 C2 C3 C4 C5 C6 C7
C8 C9 CA CB CC CD CE CF
D0 D1 D2 D3 D4 D5 D6 D7
D8 D9 DA DB DC DD DE DF
E0 E1 E2 E3 E4 E5 E6 E7
E8 E9 EA EB EC ED EE EF
F0 F1 F2 F3 F4 F5 F6 F7
F8 F9 FA FB FC FD FE FF
00 01 02 03 04 05 06 07
08 09 0A 0B 0C 0D 0E 0F
10 11 12 13 14 15 16 17
18 19 1A 1B 1C 1D 1E 1F
20 21 22 23 24 25 26 27
28 29 2A 2B 2C 2D 2E 2F
30 31 32 33 34 35 36 37
38 39 3A 3B 3C 3D 3E 3F
00 01 02 03 04 05 06 07
08 09 0A 0B 0C 0D 0E 0F
10 11 12 13 14 15 16 17
18 19 1A 1B 1C 1D 1E 1F
20 21 22 23 24 25 26 27
28 29 2A 2B 2C 2D 2E 2F
30 31 32 33 34 35 36 37
38 39 3A 3B 3C 3D 3E 3F
40 41 42 43 44 45 46 47
48 49 4A 4B 4C 4D 4E 4F
50 51 52 53 54 55 56 57
58 59 5A 5B 5C 5D 5E 5F
60 61 62 63 64 65 66 67
68 69 6A 6B 6C 6D 6E 6F
70 71 72 73 74 75 76 77
78 79 7A 7B 7C 7D 7E 7F
80 81 82 83 84 85 86 87
88 89 8A 8B 8C 8D 8E 8F
90 91 92 93 94 95 96 97
98 99 9A 9B 9C 9D 9E 9F
A0 A1 A2 A3 A4 A5 A6 A7
A8 A9 AA AB AC AD AE AF
B0 B1 B2 B3 B4 B5 B6 B7
B8 B9 BA BB BC BD BE BF
C0 C1 C2 C3 C4 C5 C6 C7
C8 C9 CA CB CC CD CE CF
D0 D1 D2 D3 D4 D5 D6 D7
D8 D9 EA EB EC ED EE EF
E0 E1 E2 E3 E4 E5 E6 E7
E8 E9 EA EB EC ED EE EF
F0 F1 F2 F3 F4 F5 F6 F7
F8 F9 FA FB FC FD FE FF
00 01 02 03 04 05 06 07
08 09 0A 0B 0C 0D 0E 0F
10 11 12 13 14 15 16 17
18 19 1A 1B 1C 1D 1E 1F
20 21 22 23 24 25 26 27
28 29 2A 2B 2C 2D 2E 2F
30 31 32 33 34 35 36 37
38 39 3A 3B 3C 3D 3E 3F
00 01 02 03 04 05 06 07
08 09 0A 0B 0C 0D 0E 0F
10 11 12 13 14 15 16 17
18 19 1A 1B 1C 1D 1E 1F
20 21 22 23 24 25 26 27
28 29 2A 2B 2C 2D 2E 2F
30 31 32 33 34 35 36 37
38 39 3A 3B 3C 3D 3E 3F
40 41 42 43 44 45 46 47
48 49 4A 4B 4C 4D 4E 4F
50 51 52 53 54 55 56 57
58 59 5A 5B 5C 5D 5E 5F
60 61 62 63 64 65 66 67
68 69 6A 6B 6C 6D 6E 6F
70 71 72 73 74 75 76 77
78 79 7A 7B 7C 7D 7E 7F
80 81 82 83 84 85 86 87
88 89 8A 8B 8C 8D 8E 8F
90 91 92 93 94 95 96 97
98 99 9A 9B 9C 9D 9E 9F
A0 A1 A2 A3 A4 A5 A6 A7
A8 A9 AA AB AC AD AE AF
B0 B1 B2 B3 B4 B5 B6 B7
B8 B9 BA BB BC BD BE BF
C0 C1 C2 C3 C4 C5 C6 C7
C8 C9 CA CB CC CD CE CF
D0 D1 D2 D3 D4 D5 D6 D7
D8 D9 DA DB DC DD DE DF
E0 E1 E2 E3 E4 E5 E6 E7
E8 E9 EA EB EC ED EE EF
F0 F1 F2 F3 F4 F5 F6 F7
F8 F9 FA FB FC FD FE FF
If your computer has only one parallel port, you may need to tempo-
rarily remove any existing parallel port devices (such as a Zip drive or
printer) in order to connect the key. These devices may be recon-
nected to the key’s outside connector after you have installed the key.
❑ If you are using a 25-pin key, we recommend you attach the key
directly to the parallel port without using an extension cable
between the computer and the key. However, you may use a cable to
connect a printer or other parallel device to the key; see below for
more information on using cables with the Sentinel SuperPro key.
❑ If you are using a 36-pin key, you may use a cable to connect the
key to the computer, but do not use an extension cable to connect
a printer or other parallel device to the key.
3. Tighten the screws to connect the key securely to the port.
Warning! There is one exception to this rule. If you are cascading Sentinel
SuperPro keys with SafeNet Inc.’s NetSentinel keys, the Sentinel
SuperPro keys must be located before any NetSentinel keys in
the chain. NetSentinel keys should be the last keys in the chain. If Sen-
tinel SuperPro keys are located behind NetSentinel keys, they will not
be recognized by the Sentinel system driver, and thus the protected
application will not run.
While Sentinel SuperPro keys can be cascaded with keys from other compa-
nies, this may cause compatibility issues and is not recommended.
When your application attempts to establish communication with a key, it
must specify the developer ID. The driver then locates the first key with this
developer ID. The application can also ask for another key with the same
developer ID if the first key is not desired for some reason.
Keys can also be connected to up to three parallel ports on the same com-
puter. For example, if you have three parallel ports on your computer, you
could attach a separate key to each port simultaneously. The Sentinel sys-
tem driver automatically polls all parallel (and USB) ports when looking for
a key.
Note: You cannot cascade keys with the same developer ID while you are pro-
gramming keys. Every key must be programmed individually.
2. Attach the key to the USB port. Make sure it is securely and tightly
connected.
Note: The model number is NOT the same as the developer ID programmed into
the key. The product identifier is used for ordering purposes only.
SRB00643 Model
9938L24319 Number
Manufacturing
Code
Note: The model number and the manufacturing code are in the same format on
both network and stand-alone keys.
When you place your order, you should also have the following information
on hand:
■ What type of keys you want: network or stand-alone
■ What form-factor you want your keys to be in: parallel or USB
■ If you are using network keys, what you want for the hard limit (see
page 15) that will be pre-programmed into the key
For more information about hardware key versions, see “Network Keys v.
Stand-alone Keys” on page 15. For more information about key form-fac-
tors, refer to “Attaching the Sentinel SuperPro Hardware Key” on page 52.
Returning Keys
Occasionally, you may find that you need to return a SafeNet product for
exchange or repair. To ensure proper handling is acknowledged for the
returned keys, you must obtain a Return Material Authorization (RMA) num-
ber prior to shipping the products to SafeNet. To obtain an RMA number:
■ If you suspect a technical problem, call SafeNet’s Technical Support.
The support representative will work with you to rule out resolvable
software and/or configuration problems. If the problem cannot be
resolved, the RMA department will assign you an RMA number over
the phone.
■ If you have keys to be returned for other than a specific technical
situation, call SafeNet’s RMA department for an RMA number.
Be sure to write your RMA number on the shipping label to ensure prompt
and correct handlings.
The goal of any software protection strategy developed using Sentinel Super-
Pro is to significantly reduce the chance that someone can defeat the
protection and use your application without the hardware key. In general,
the time and expense required for a skilled hacker to break your scheme is
directly related to the number and complexity of the locks you place in your
application. Protection can be as simple or as complex as you wish.
Before you actually start adding protection to your source code, however,
you should design your protection strategy, deciding what type(s) of protec-
tion you’ll use, which activation types you need, and more.
This chapter introduces you to the types of protection you can use with Sen-
tinel SuperPro, gives some guidelines for using various protection types, and
describes advanced protection techniques you can use for even greater secu-
rity. Once you have read through this chapter, you will be ready to start the
SSP Toolkit and begin adding protection to your application.
This chapter covers the following topics:
■ Introduction to software security
■ Protection types
■ Activation types
Note: All values and cell addresses used in this chapter’s examples are in hexadec-
imal format. Also, for simplicity, standard error-checking steps are omitted
from the examples. If you receive an invalid response to a query or another
function, we recommend retrying the operation before taking
action.
Protection Types
Sentinel SuperPro provides two general types of protection: integrated and
automatic. The protection type determines when and where software locks
are implemented.
Integrated
When you choose integrated protection, you add software locks—API func-
tions to verify the presence of the key—directly into your application’s
source code. You control the amount and location of the locks.
The frequency of software locks within your application, and the action
taken if no key is found, is left up to you. The more locks you add to your
application, the more difficult it will be for potential hackers to break your
application’s protection.
Because you must understand the API calls used to support the protection
strategy you have designed, and manually add them to your code, using
integrated protection may take longer.
Integrated protection is most commonly used when:
■ You want to have control over the protection techniques used to
secure your application.
■ You have access to the source code and understand the API functions
(for more information about the Sentinel SuperPro API go to “Using
the Sentinel SuperPro API” on page 301).
Automatic (Shelled)
Automatic protection is a simplified, fast, and easy way to protect your
application against unauthorized access.
Note: Some applications or .DLLs (such as those using threaded local storage)
may not work correctly with automatic protection applied. In this case, use
integrated protection instead.
Activation Types
When you protect your applications with Sentinel SuperPro, you also
choose how you want your customer to activate future applications, or addi-
tional features, after installation.
The methods defining how customers activate your application are called
activation types. There are four activation types in Sentinel SuperPro: active,
static, trusted and distributed.
The following table describes each of the available activation types, what
you must do to use each type, and suggestions for how you can use each
type. Typically, the activation type you use is based on whether you want
your application to be active or inactive.
Assume you want to create 100 copies of your application to ship to your
customers. Your product line is defined as follows:
■ You have a main application—named SceneryEditor— that you want
to run immediately at the customer’s site.
■ You have a demo of SceneryEditor that you want to run immediately
at the customer site, but it will expire at some point.
■ You have ten other add-on features for SceneryEditor that your
customer may purchase in the future as upgrades.
In general, the following procedure describes how you would use Sentinel
SuperPro to protect and distribute SceneryEditor and its add-on features:
5. Ship SceneryEditor, along with one product key and the Sentinel Cli-
ent Activator or Field Exchange Utility.
Exchange Utility may be used in order to obtain a locking code. Your cus-
tomer sends you the locking code, and you do the following:
2. Click the Field Activation tab, and then click License Generator.
Note: You can also use the License Generator Utility to generate a license code.
3. Enter the locking code provided by your user, and select the actions
you want to perform on the key in the field.
The actions you select determine which features the user will have
access to. Sentinel SuperPro generates a license code that will apply the
selected actions to the user’s key.
4. Send the license code to your user, who then enters the code in the Cli-
ent Activator or Field Exchange Utility, automatically activating the
appropriate product or upgrade.
The activation counter for each key should be set to 40—10 licenses
to activate SceneryEditor, and 10 licenses each to activate each of the
add-on features.
6. From the Project stage, export the protection strategy you defined in
step 1 to a .DST file.
3. Starts the License Generator Utility and opens the .DST file you
provided with the protected application.
4. Enters the locking code provided by the customer, and selects the
actions to perform on the key in the field.
The actions the distributor selects determine which features the cus-
tomer will have access to.
5. Generates a license code that will apply the selected actions to the cus-
tomer’s key.
6. Sends the license code to the customer, who then enters the code in
the Client Activator or Field Exchange Utility, automatically activat-
ing the appropriate product or upgrade.
When the license limit counter on a distributor’s key reaches zero, you can
increment the limit counter through field activation, much in the same way
that a customer’s product key is updated by the distributor. You may want to
charge for incrementing the distributor’s key. To increment the license limit
counter in a distributor’s key:
2. Click the Field Activation tab, and then click License Generator.
3. Ask the distributor to generate a locking code for his distributor key
using the Field Exchange Utility. The distributor key, not a product
key, must be connected the distributor’s system to generate the appro-
priate locking code.
4. Enter the locking code provided by the distributor, and select the
Increment Distributor Counter action. You should have already
programmed this action, and the increment value, when you initially
created your protection strategy.
6. Send the license code to your distributor, who then enters the code in
the Field Exchange Utility, automatically incrementing the license
limit for his distributor key.
Note: The distributed activation type is similar to the trusted activation type; the
only difference is that activations of distributed applications are metered.
Network Licenses
Another decision you need to make while protecting your application is how
you want to use licenses with your application. With Sentinel SuperPro 6.5,
every user of your application needs to obtain a license before running the
application. The license allows the user to start the application and access
the hardware key.
The license limit indicates the maximum number of concurrent users of the
application. Each instance of an application uses a license when it is started.
Licenses can be used in two ways—with a stand-alone application or with a
network application. If the application is stand-alone, each user needs his
own hardware key, as only one license can be obtained from each key. If the
application is a network application, only one key—located on the net-
work—is required, but the single key can issue multiple licenses, allowing
for simultaneous use of your application by several clients.
The type of licensing model to use is up to you. It depends on how you will be
selling your application, and how you expect your users to deploy it within
their organization.
Sublicensing
Sublicensing is useful when you want to apply a license limit to a specific
feature of the protected application. If you have specified a user limit in your
protection strategy, you can allow sharing the sub-licenses issued on the
basis of a combination of User Name and MAC Address (i.e. a seat), so that if
a request for accessing that feature of the protected application comes more
than once from the same seat, then no extra license is consumed.
You can program up to 232 separate sublicense license limits in each key—
each sublicense is a custom element occupying a single cell on the hardware
key. The total number of sublicense limits you can program is dependent on
the number of cells being used by other elements of your strategy
Getting Started
Now that you understand the concepts behind software security, you are
ready to get started with designing your own protection strategy. The first
decision you need to make is whether you want to use quick and easy pro-
tection, or if you want to take more time and create your own custom
protection strategy.
Customized Protection
If you have more time to work on your protection strategy, a custom strategy
may be the answer for you. Customizing your strategy allows you to take
advantage of a number of protection techniques, both basic and advanced,
using those that work best for your application.
Customized protection allows you to:
■ Choose how to use each memory cell in the key.
■ Select the algorithms used in your protection strategy.
■ Add data words or counters where appropriate.
■ Add API function calls to your source code to support your protection
strategy.
■ Create a very secure level of protection for your application.
Note: Creating your own customized protection scheme requires you to under-
stand the API functions and all rules governing how cells can be pro-
grammed. Be sure you have thoroughly reviewed the information in this
chapter, as well as Chapters 3 and 14, before you begin programming the
key and writing code.
If you decide you want to create your own unique protection strategy, con-
tinue with the next sections in this chapter, which provide information on
the various techniques you can use to protect your application. Once you’ve
completed this chapter, go to Chapter 5, “Starting the Sentinel SuperPro
Toolkit,” on page 113 to get started with implementing your strategy.
maintain the license. Failure to send this “heartbeat” message to the server
(and thus the hardware key) will result in loss of the license and an error
being sent to the application. Heartbeat messages let the server and key
know that the license is still in use by the client running the application. For
more information about heartbeat messages, see page 109.
Note: A returned value is the value received from any type of cell in response to
a query or read sent from your application.
Example
In this example, we programmed one cell in the key with a two-byte value.
We then had our application read that cell during execution, taking appro-
priate action after the read.
3. Use the SSP Toolkit to program the selected cell with the value. In this
example, we programmed the value 1234 into cell 20.
Note: To add a data word cell to your key, you need to create a custom element.
See Chapter 7, “Working With Design Elements,” on page 185 for detailed
instructions.
Use the Data Word cell type if you want the application to be able to
modify the cell later. Use the Locked Data Word cell type if you want
the cell to be read-only.
Note: For more information about the API functions used in this example, see
Chapter 14, “API Function Reference,” on page 301.
In this case, you send a data string to the key that is encrypted by the key
using a preprogrammed algorithm. Your application then examines the
returned value, verifying that the correct encrypted string was returned, or
using the value to control your application’s execution in some way.
Example
This example describes how to set up your application to require a correctly
encrypted response from the key.
1. Select two 16-bit hex values to use for the algorithm. We used 1234
and C000 to create an active algorithm using the enhanced algo-
rithm engine.
Remember, the second word must be between 8000 and FFFF to make
the algorithm active.
2. Select two cells to program these values in. We used cells 0A and 0B.
Note: Throughout the SSP Toolkit, only valid and available cell addresses are pro-
vided in Address drop-down lists, preventing you from selecting an inap-
propriate address. For more information about algorithm address
restrictions, see “Valid Algorithm Addresses” on page 37.
Sentinel SuperPro will select an address for you if you select Auto
instead of a cell; see page 189 for more information.
6. Move to the Prototype stage, and click Go to program a test key with
your specifications.
7. Move to the Implementation stage, and click the API Explorer tab.
Using our examples from above, the query string 8FA31B4B returns
a value of 3C5E4AD1.
long, and the password must immediately follow the algorithm. For exam-
ple, cells 0C - 0F can be used as follows:
Note: See “Valid Algorithm Addresses” on page 37 for more information about
address restrictions for algorithms and activation passwords.
1. Add an algorithm to your application via the SSP Toolkit, being sure
to set it to inactive. See Chapter 7, “Working With Design Elements,”
on page 185 for detailed instructions.
4. After buying your application, the user runs the utility you created in
step 3, entering the password you provide. The algorithm is then acti-
vated and returns the correct response, allowing the protected appli-
cation to execute.
For added security, you may want to use a different activation password for
each key.
Example
This example demonstrates how to activate an inactive application in the
field. Usually, an application is deactivated because it is a demo that has
been “turned off ” after the specified number of executions. Alternatively,
you may have set up your application so the user must enter an activation
password before the application will run.
You temporarily “turn off ” an application by including an RNBOspro-
Query() function call that requires the hardware key to return a correctly
encrypted value. Then you make it impossible for the hardware key to
return the value because its algorithm has been set to inactive.
By definition, an algorithm is inactive if the high-order bit of its second word
is 0. This is done as follows:
■ If a counter is used, when it reaches zero, the RNBOsproDecrement()
function sets the bit to 0.
■ In your factory, the SSP Toolkit is used to set the algorithm as inactive.
You must write a utility, or add a feature or function to your applica-
tion, to activate the algorithm once the user supplies the correct
password. The query performed by the protected application then returns
the correct response, and the application runs successfully.
Note: The utility used to enter activation passwords is not included with, nor can
it be created with, the SSP Toolkit. You must design and code this utility for
use with your application yourself.
Note: You may want to send a query using the algorithm before calling
RNBOsproActivate(). If the query returns the correct response, the algo-
rithm is already activated.
3. Write a utility the user can use to enter the password you provide.
This utility should also use the API calls listed above.
Instead, repeat your query; if the response is still wrong, then you can take
action. Possible actions include:
■ Display a message and wait for the user to respond. This method does
not prevent users from running the application, but it makes doing so
extremely annoying, especially if the application queries the
hardware key frequently.
■ Shut down the application after a predetermined number of failed
queries. (However, only under the most extraordinary circumstances
should you terminate your application without allowing the user to
first save his work.)
■ Allow the application to appear as if it is functioning properly, while in
fact it is not. (Be very careful if you use this method; less drastic
actions should be considered first.)
■ Display a critical error message and tell the user to contact your
technical support department.
These are just some suggested actions; you can implement any combination
of them to suit your needs.
Remember, other events, such as network transmission errors or parallel
port contention problems, can also cause your application to detect a hard-
ware key problem. Since these are almost always innocent events, you
should design your strategy to be as forgiving of them as possible, while still
maintaining protection integrity.
Note: All attempts have been made to guarantee error-free transmissions to and
from the key. However, a small possibility exists that an invalid response
may be received even if the key is attached. As a result, we recommend
always retrying the query one or more times if you receive an invalid
response. If the response is consistently invalid, then take the action you
deem appropriate.
ship your application to the field with encrypted code, which is decrypted
only if the hardware key is attached.
Most encryption algorithms depend on a key value—sometimes called a
password or seed—to transform the data.
Using a different seed produces different encrypted results, but reproduces
the original data if that seed is also used for decryption.
Tip: When decrypted data is “in the clear,” use some other form of protection to
block interrupts used by debuggers to gain control.
The most common reversible algorithms use the Boolean operator EXCLU-
SIVE OR (XOR). XOR works as follows:
■ If a seed bit has a value of 1, XOR reverses the state of the
corresponding bit in the original string and copies it to the result.
■ If a seed bit has a value of 0, XOR copies the corresponding bit in the
original string to the result.
Applying the same algorithm to the result reverses the encryption and
restores the data to its original state.
Examples
The following example uses the XOR operator to encrypt a 16-bit hex num-
ber (8FA3) using the seed 4B6A.
Notice that everywhere a bit in the seed is 1, the result bit is the opposite
state of the data bit. Where the seed contains a 0, the result bit is the same as
the original data bit. Without knowing the seed, the encrypted result is
meaningless.
To reproduce the original data, apply the XOR algorithm to the encrypted
result using the same seed.
The next example shows how to use the SSP Toolkit with the XOR operator
to encrypt and decrypt code in your application.
1. Select two 16-bit hex values to use for the algorithm. We used 4D59
and F123.
Remember, the second word must be between 8000 and FFFF to make
the algorithm active.
2. Select two cells to program these values in. We used cells 0A and 0B.
Sentinel SuperPro will select an address for you if you select Auto
instead of a cell; see page 189 for more information.
Note: For more information about algorithm address restrictions, see “Valid
Algorithm Addresses” on page 37.
6. Move to the Prototype stage, and click Go to program a test key with
your specifications.
7. Move to the Implementation stage, and click the API Explorer tab.
The encrypted return value is the encryption seed you will use to
encrypt part of your code. Using our examples from above, the query
string 7009AB12 returns a value of 60D6867D.
11. Select the data in your code you want to encrypt. We used the hex
value 8FA31B4B.
12. Apply the operator you selected in step 10 to the data, using the
encryption seed. If you ship your application with the encrypted code,
it will not execute correctly until the code is decrypted by a correct
response.
13. Code your application so it decrypts the encrypted code if the hard-
ware key is present. To do this, query the key. If it is present, the
RNBOsproQuery() function returns the response string you used as
the encryption seed.
14. Add the following required API functions in your application to make
the query:
Code your application to display a message and exit if the query does not
return the appropriate value and the code cannot be decrypted.
You can use this string as a seed with the XOR algorithm to encrypt a
32-byte string. For example, the ASCII string “This is the secret of my pro-
gram” can be represented as the following hex string:
5468 6973 2069 7320 7468 6520 7365 6372
6574 206F 6620 4D59 2070 726F 6772 616D
Using the 32-byte seed with the XOR algorithm produces the following
encrypted result:
1F02 FFA7 0DC0 2872 C2CC 0869 A9F7 D657
0F3F F4F9 CD0D 1F02 84C6 3B04 F5A8 44D8
The result looks nothing like the original character string, yet the original
data can be easily recovered using the same algorithm seed that changed it.
You can use this method with entire sections of code within your applica-
tion, expanding the seed as needed.
Note: You cannot use this method if you use the trusted activation type, which
creates a different activation password for each customer.
■ Program the application’s serial number in a data word cell. Read the
cell and compare the value to the correct serial number.
If you have multiple application packages, store the serial number for
each in separate data word cells.
■ Store the user’s name in data words as ASCII bytes, then compare or
display it.
■ Use the 56 programmable cells as one large, 896-bit bitmap. Various
combinations of bits can determine features or other responses,
depending on your application.
Hiding Calls
A hacker may analyze your object code and examine addresses referenced
by CALL instructions to find the calls to the Sentinel SuperPro interface rou-
tines. The hacker could then analyze the code of the interface routine and
the code following each call in order to defeat the lock.
One method to avoid detection of your queries is to call the key without
using the assembly language CALL instruction. Instead, push the return
address onto the stack followed by the procedure address, and then execute
a RET (return) instruction.
For example, after each unconditional jump and return, insert a garbage
data byte or two whose value is equal to the first byte of a very long assembly
language instruction.
This same technique can be used following conditional branches, as long as
the preceding code always guarantees the branch is invoked. Such a jump or
branch may also be used immediately prior to the call, with an intervening
data byte.
If you have many steps, or conditions, they can be stored in an array. The
application checks the array for a match with the string and returns the
number of the element matched. This number then determines the features
activated or the action taken by the application.
Obstructing Debuggers
Many potential hackers use debuggers to break large, complex software
packages with high licensing fees. You may want to incorporate safeguards
aimed directly at preventing the use of debuggers to circumvent the software
locks in your protection strategy.
For example, you might lock out the keyboard during hardware key queries,
or destroy the contents of interrupt vectors 1 and 3 (the trace and break-
point interrupts).
While no technique can deter every hacker, the more safeguards you imple-
ment, and the greater the variety you use, the more difficult the hacker’s task.
Eventually, it makes more sense for potential hackers to either purchase your
application, or attempt to break a different, less secure application.
Like the full version of an application, demos also require a license to access
the hardware key. You may want to consider whether you want your demo
applications to act as stand-alone applications or as network applications.
Both demo applications and the full version can be run on the network at
the same time, as long as enough licenses are available. For more informa-
tion about using licensing, see “Network Licenses” on page 72.
Using Counters
There are multiple ways of using counters to control access to your demo
applications. One way is to check the counter to see if it has reached zero,
then proceed accordingly.
Another, more secure, method is to associate the counter with an algorithm
the application requires for queries. When the counter reaches zero, the
associated algorithm is automatically deactivated. (RNBOsproDecrement()
changes the high-order bit of the algorithm’s second word.) Future queries
using this algorithm return incorrect values.
To limit application executions using an algorithm/counter, you must pro-
gram the key to meet the following specifications:
■ The word you decrement must be a counter word.
■ The counter must be located in a cell with an address equal to
3 MOD 8.
■ The two words immediately following the counter (at addresses equal
to 4 MOD 8 and 5 MOD 8) must contain an active algorithm.
Note: The relationship between a counter word and an adjacent algorithm exists
even if you do not intentionally plan it. The algorithm will be deactivated
when the counter reaches zero. See “Valid Algorithm Addresses” on page 37
for more information about where counters can be placed.
You can also use two counters: the algorithm is deactivated when either
counter reaches 0. The second counter must be located at an address equal
to 2 MOD 8. If desired, you could use the second counter after the algorithm
is re-activated with a password.
If you want to be able to re-activate the application after it has been disabled,
you must define an activation password. This is a two-word value immedi-
ately following the algorithm. See “Using Activation Passwords” on page 79
for more information.
Remember, the counter will still be zero after the algorithm is re-activated,
so make sure your application checks for the ALREADY_ZERO status from
the key.
Note: You could reset the counter and do decrements again, but this would
require putting your Overwrite Passwords in your activation utility. You
should avoid using your overwrite passwords in the field.
Any of the following cell type groups can be used to program an algorithm
with a counter:
■ Algorithm with counter
■ Algorithm with counter and password
■ Algorithm with two counters
■ Algorithm with two counters and password
The following illustrates a cell layout with an algorithm, counter and
password:
Cell 0B contains the counter you are decrementing. Cells 0C and 0D contain
the active algorithm. The second algorithm word must be between 8000
and FFFF for the algorithm to be active—this value will be changed auto-
matically when the counter reaches zero.
Cells 0E and 0F contain the activation password required to re-activate the
password after the counter reaches zero to deactivate the algorithm.
Example
This example demonstrates how to limit the number of times a demo appli-
cation can execute. This is done by requiring the application to query an
algorithm that becomes unusable (deactivated) after a specified number of
executions. The algorithm is associated with a counter that is initialized to
the number of times the application can run.
Remember, if you want to allow the user to re-activate the applica-
tion after the counter has reached zero, you must also program an
activation password.
Note: This example assumes you will be controlling the number of times your
demo can execute by adding a custom element. You also have control over
demo executions when you use integrated or automatic application pro-
tection. See Chapter 6, “Protecting Your Application,” on page 145 for
more information.
1. Select the cells you want to use for the algorithm and counter. Review
the address restrictions on page 37.
❑ Counter: 0B
❑ Algorithm Word 1: 0C
❑ Algorithm Word 2: 0D
2. Decide how many times you want the demo to run. We chose 5.
3. Select two 16-bit hex values to use for the algorithm. Remember, the
second word must be between 8000 and FFFF to make the algorithm
active.
Note: If you want to provide the ability to re-activate the application in the field,
you must add an algorithm with counter and password instead. This allows
you to program an activation password into the two cells following the
algorithm.
Tip: To make a potential hacker’s task more difficult, separate the RNBOspro-
Query() and RNBOsproDecrement() function calls in your code. This helps
obscure the connection between them.
Querying Counters
If you are using a counter with your demo application, you can use the
RNBOsproQuery() function to query the counter word, verifying it has been
counted down. This technique is useful because it allows you to see if a
hacker is trying to sidestep your counter in an attempt to continue the demo
condition indefinitely.
Counters used in this way must be two words long:
■ The first word has an access code of 2 (counter). This word must be
located in an even-numbered cell.
■ The second word has an access code of 3 (algorithm/hidden). This
word must be located in an odd-numbered cell. The value of this word
must be in the range for active algorithms.
Code your application to send a query to the counter/algorithm before per-
forming each decrement. A given query string should return a different
response value after each decrement, because the value in the first word
(the counter) will have changed.
If the query returns the same value, either the algorithm is not active, or the
counter was not decremented, which may mean a hacker is attempting to
circumvent your protection strategy.
Moving On
Now that you have designed your protection strategy, you are ready to use the
SSP Toolkit to add software locks to your code and program your hardware
keys. Go to the next chapter for instructions on Implementing Licensing.
License Sharing
Sentinel SuperPro 6.5 has introduced a concept of default seat license shar-
ing in the integrated protection environment and also gives you the ability
to enable/disable sharing. It offers additional flexibility to you as a developer
by providing three combinations of seat license sharing and user limit shar-
ing modes. You can now have:
Note: If you are running the shell protection strategy, you won’t be able to access the features of
seat license sharing mechanism. You can choose an option in which both main license shar-
ing and sublicense sharing is enabled or an option in which both main license sharing shar-
ing and sublicense sharing is disabled.
All protected applications must obtain a license before they can be run.
Licenses determine both who can use the application, and where the appli-
cation can be used. Each instance of an application uses a license when it is
started. As a developer, you have control over where your application will
look for a key and obtain a license.
The SuperPro functions that you would add to your application’s source
code would locate a key, obtain a license, maintain the license by sending
messages back to the server, and then release the license when it is no longer
needed.
This chapter explains how licensing is implemented in your protected appli-
cations. Detailed instructions for adding the appropriate code can be found
in “Adding API Functions to Your Source Code” on page 211.
This chapter covers the following topics:
• Setting the access mode
• Finding a key
• Getting a license
• Maintaining a license
• Releasing a license
• Using sublicenses
Note: If you don’t specify an access mode, your protected applications will use dual mode as the
default.
Note: If you set your application to network mode in code, your user must name his Sentinel Pro-
tection server the same as the server name you set. If it does not happen so, your application
will not be able to locate the server and key, and will not run. For this reason, if you want
your application to run in network mode, you may find it easier to use dual mode in code,
and then instruct your users to set the server name through the NSP_HOST variable. You
could also use a configuration file to set the variable. See page 105 for more information
about this variable.
For specific details about using this function, refer to Chapter 14, “API Func-
tion Reference,” on page 301.
Setting RNBO_SPN_ALL_MODES
Because RNBO_SPN_ALL_MODES is the default access mode, you do not
need to add any special API functions to your source code. The standard
pseudocode (see “Adding API Functions to Your Source Code” on page 211)
assumes your application will be used in RNBO_SPN_ALL_MODES mode.
When in RNBO_SPN_ALL_MODES, an application will send broadcast mes-
sages to the network to locate an appropriate server if no key is found on
local server. Keep in mind, broadcast messages require additional network
resources and result in a longer total time from application start-up to key
acquisition. If network resources and timing is an issue for you, you may
want to consider using network mode.
Setting this variable is optional, and, if you have set the access mode
through code, unnecessary. However, for maximum performance, we rec-
ommend to system administrators that this variable be set on each client
workstation. If the end-user does not set this variable, and you have not set
the access mode through code, the application will be in dual mode.
Detailed instructions for setting this variable can be found in the Sentinel
SuperPro System Administrator’s Guide.
Finding a Key
Before your application can obtain a license, it must first locate a Sentinel
SuperPro hardware key either on the local machine or somewhere on the
network. Where and how your application locates a key is dependent on
what access mode your application is using.
The following API function calls are used to locate a key:
• RNBOsproFormatPacket
• RNBOsproInitialize
• RNBOsproGetContactServer (optional)
• RNBOsproFindFirstUnit
cation will look only for the specified server. If the server cannot be located,
an error message appears and the application shuts down.
The application does not look for a key locally when it is in network mode.
Getting a License
All license information is maintained by Sentinel Protection server installed
on the client machines or the servers on the network.
Before an application can be started, it must first obtain a license from the
Sentinel Protection server. The server issues a license only if the license limit in
the key has not yet been exceeded. The license limit indicates the maximum
number of concurrent users of the application. Once a key is located, the way
in which a license is obtained is the same for applications running all modes.
Note: Remember, whether the application is stand-alone or network, it always uses the Sentinel
System Driver as the means of communicating with the key. That is why the Sentinel Protec-
tion Server must be installed on the same system as the Sentinel System Driver.
3. The driver returns the license limit to the Sentinel Protection server.
Note: All communication between the client and the server is encrypted for greater security.
The License ID
Once a license is obtained, a license ID that uniquely identifies the client and
the license is issued. The license ID number must be used in all subsequent
calls to the key from the client.
Note: The Sentinel Protection server maintains a log of all transactions that take place during a
particular session, allowing you to view when a license is issued and who it was issued to.
See the Sentinel SuperPro System Administrator’s Guide for more information about the
server log file.
Releasing a License
There are three situations in which a license should be released:
• The client has shut down the protected application
• The client fails to send a heartbeat message to the server
• Your application has completed all key operations
Use the RNBOsproReleaseLicense API function to release a license and make
it available for use by other clients. For more information about using this
function, see page 337.
Using Sublicenses
A sublicense is a license limit you define that is less than or equal to the hard
limit programmed into the key. Sublicenses allow you to:
• Implement fewer licenses for an application than the hard limit
programmed on the key
• Protect several applications using the same key, and define separate
license limits for each
• Control concurrent access to specific features or modules within your
protected application(s)
Sublicenses must be a constant number. But, there must be a hard license
available before a sublicense can be obtained, no matter how many subli-
censes are left.
Getting a Sublicense
To obtain a sublicense for a client, first use the RNBOsproFindFirstUnit func-
tion to obtain a license from the key, then use the RNBOsproGetSubLicense
API function to obtain the sublicense.
The key’s hard limit is decremented first, then the sublicense limit is decre-
mented for the requested application. It is up to you as to how you want to
handle a client request when a sublicense is unavailable.
We recommend that if the sublicenses for a particular application are all
being used, no additional clients should be allowed to obtain a license for
that application, even if there are still licenses available under the hard limit.
Once the sublicense has been obtained, it works in the same way as other
licenses—you can read or write to cells on the key, activate algorithms and
more. You also need to send heartbeat messages to maintain the sublicense
in the same way that you would to maintain a normal license.
Note: Cell availability depends on the number and type of elements being used in your protection
strategy, as well as the number of applications being protected.
Note: The procedures in this chapter assume you have already installed the SSP Toolkit and the
Sentinel Protection server.
Tip: You only need to enter these the first time you open Sentinel SuperPro Toolkit, as your passwords
are remembered for subsequent sessions. Even if you don’t enter them, the toolkit still allows you
to continue, up through the Prototyping stage after which entering the Developer ID, Write Pass-
word, and Overwrite Passwords 1 and 2 is required to proceed further.
Your developer ID is a unique identification code. You must use your devel-
oper ID to program or establish a connection to your keys. All the keys used
by your organization have the same developer ID.
The Overwrite Passwords allow you to set or change the value or access code
of any cell other than a restricted cell. Keep these passwords secure, as they
have the power to reprogram all other cells in your key!
The Write Password allows you to change or set the value or access code of a
data word or undefined cell. This password also allows you to decrement
counter words.
Tip: If you want to be able to see the actual password and developer ID characters, select the Show
Passwords check box. Password characters are hidden (displayed as asterisks) by default.
4. In the Write field, enter the Write Password for your key.
Note: Cells 8 and 9 are used internally while configuring a key. If you are re-configuring an already
programmed key, the information stored in cells 8 and 9 would be lost.
6. Enter a secret code in the space provided. You may however click on
Auto Generate to get an auto generated code.
8. Click OK.
If you have already created projects with the Toolkit, be sure to read
the warning message that appears thoroughly and take the appropri-
ate action.
Note: The Toolkit prompts an error message if a proper key is not attached to your
machine, when setting the developer configuration parameters,
Note: The one-time update option is available for use with both product keys and distributor keys.
4. In the Storage Cell field, select the cell you want the one-time update
feature stored in. Select Auto to allow Sentinel SuperPro to select a cell
for you. Once you select this cell, it cannot be moved or changed.
5. Click OK.
If you have already created projects with the Toolkit, be sure to read
the warning message that appears thoroughly and take the appropri-
ate action. See “The Toolkit prompts an error message if a proper key is
not attached to your machine, when setting the developer configura-
tion parameters,” on page 117 for more information.
Title Bar
Menu Bar
Orientation
Pane
Navigation
Pane
Stage
Window
Navigation
Buttons
Help Buttons
Stage Task
Home No tasks are performed in this stage.
Overview Tasks performed in this stage are for informational use only
and are not required to implement a protection strategy.
Project Create a new project or open existing project.
Enter your developer ID and passwords.
Save an existing project.
Design Select integrated or automatic protection type.
Select an activation type.
Define time/date/execution controls (for demos only).
Add counters, passwords, sublicense limits and/or data
words.
Prototype Program attached hardware key memory cells.
Generate pseudocode and field exchange data.
Stage Task
Implementation Shell applications.
View pseudocode and add appropriate API functions to
application source code.
Define field activation actions and commands.
Generate license codes based on locking codes received
from customers in the field who have purchased upgrades.
Make Keys Program product keys for distribution to customers and
distributor keys for use by distributors who will activate
your application.
About No tasks are performed in this stage.
Menu Bar
SSP Toolkit commands are located in menus at the top of the toolkit window.
When a command appears dimmed, it is unavailable for use with the
selected stage or section. Menu options are described in the following table:
Sentinel SuperPro Toolkit Menu Commands
Getting Help
There are several ways to get help while using the SSP Toolkit. For general
issues, look for answers in this guide and in the online Help system that is
included with the SSP Toolkit.
You may also want to read through the text provided in the SSP Toolkit’s
Overview stage. The introductory information included there can help you
gain a basic understanding of Sentinel SuperPro concepts.
Additionally, as you move through the stages, pay attention to the text that
appears in the orientation pane at the top of the SSP Toolkit window. This text
provides a quick overview of the steps you’ll take in each stage and how they
way to familiarize yourself with the available functions and their uses prior
to designing your strategy.
2. Click the API Explorer tab. The API Calls section appears.
Tip: For more information about activation passwords, access codes, query data and response val-
ues, please see Chapter 2, “Using the Hardware Key,” on page 19.
5. Click Execute.
The API function is invoked, with the parameters you selected. The
API Call Results message box appears:
Note: Remember, you need to call the RNBOsproFormatPacket() and RNBOsproInitialize() func-
tions prior to calling any other function.
1. In the Value field, click the down arrow. The Numeric Assistant dialog
box appears.
3. Click Close.
The value from the Hexadecimal field is transferred to the Value field.
3. Click MemView. The MemView section appears with all cells shaded
grey. This means the key has not yet been queried for the status of the
programmed cells.
4. Click Refresh. The SSP Toolkit queries the key, returning the access
code and value of each cell.
Cell access codes are identified by different colors, as shown in the legend on
the right. Cell values are provided in hexadecimal format within each indi-
vidual cell.
A question mark (?) represents a restricted cell, or a cell programmed with
an algorithm value.
To view a selected cell’s address, move the mouse pointer over that cell. The
address appears in the Address field automatically.
Tip: To view cell values and addresses in decimal format, select Decimal in the lower right of the
window.
To invoke an API function for a selected cell from the MemView section:
1. Right-click on the cell and select API and then the function from the
shortcut menu that appears. The API Function dialog box appears.
2. Enter the appropriate parameters for the function. See page 128.
3. Click Execute.
The API function is invoked on the selected cell, and the return value
appears in the API Call Results message box. See “Invoking API Func-
tions” on page 128 for more information.
Querying Algorithms
The Query Response Generator allows you to experiment with and learn
about the different types of algorithms and their states.
When your application sends a query to an algorithm in your key, it com-
pares the encrypted response to the response it expects. To determine the
expected responses, you must query the algorithm during your development
phase.
To query an algorithm word:
Use the MemView section to determine which cells on your key are
algorithm cells. See “Viewing Memory Cells” on page 132.
5. In the Query Length box, enter or select the number of queries you
want to make.
6. In the Table Length box, enter or select the number of pairs you want
for the Query Length defined in Step 5.
7. Click Query.
The SSP Toolkit queries the algorithm cell you selected in step 4 with
the query string selected in step 6.
Creating a Project
What Is a Project?
A project is stored in a Sentinel SuperPro Toolkit file. The project contains
all the data used to create your protection strategy—elements, passwords,
your developer ID, algorithm values, counters, data words, field activation
commands, etc.
Your project is the template that will be used to program the keys protecting
your application.
Projects are protected with strong encryption, so your passwords and devel-
oper ID cannot be obtained from a project without opening it in the SSP
Toolkit.
Additionally, you can prevent unauthorized users from being able to open
your projects (even if they have the SSP Toolkit) by locking them. See “Adding
Password Protection to Your Project” on page 140 for more information.
Because your project contains sensitive information about your protection
strategy, we recommend making it accessible to developers only—do not
give your project file to manufacturing or distribution personnel who also
have access to the SSP Toolkit.
Note: Manufacturing personnel do need the project file to use the Make Keys Utility, but they will
not be able to make changes to your project with these utilities. Distributors should be
given a .DST file for use with the License Generator Utility. See “Creating a Project File for
Distributors” on page 143 for more information.
2. Click New.
3. If another project is open, and you haven’t saved it, you are asked if
you want to save the current project. Click Yes to save your changes,
or No to discard them.
Tip: In case you did not enter the Developer ID, Write Password and the Overwrite Passwords 1
and 2 in the developer configuration dialog box, at the time of saving your project you will
get a message stating: “You must specify the secret code, the spp file can not be saved, first
complete the developer configuration in the project stage“. Complete the developer configu-
ration and then proceed further.
Note: .DAT files were created by Sentinel SuperPro versions 5.1 and earlier. Projects created using
Sentinel SuperPro 6.0 were saved with a .SPP extension, and may be opened using the pro-
cedure on page 139. Files saved in NetSentinel cannot be opened in Sentinel SuperPro 6.5.
3. Browse to locate the .DAT file you want to import, then click Open.
The .DAT file, with the elements you defined in the previous version, is
imported into the current project. The elements are added to the cur-
rent project. If there are cell conflicts during the import process, a
warning message appears and the element that caused the conflict is
not imported.
You can merge two .DAT files into one project file by importing both
.DAT files into the same project file.
Note: Cells 8 and 9 are used internally while configuring a key. If you are re-configuring an already
programmed key, the information stored in cells 8 and 9 would be lost.
Tip: If you want to be able to see the actual password and developer ID characters, select the
Show Passwords check box. Password characters are hidden (displayed as asterisks) by
default.
6. In the Write field, enter the Write Password for your key.
2. Click Open.
3. Browse to locate the Sentinel SuperPro project you want to open, then
click Open.
4. If you haven’t saved the currently open project, you are asked if you
want to save the current project. Click Yes to save your changes, or No
to discard them.
If the project was locked, the Password dialog box appears. Enter the
unlock password. The project opens in the SSP Toolkit.
Tip: You can verify the name of the project you are currently viewing by looking at the Sentinel
SuperPro window title bar, where the name of the project is displayed.
1. From the File menu, select Save As. The Save As dialog box
appears.
2. Enter the new project name in the File Name field, then click Save.
The project is saved under the new file name.
Warning! If you forget your password, you will need to recreate your project. There is no “back-
door” that SafeNet Inc. Technical Support can use to give you access to your project.
Thus, it is VERY important that you remember the password you use to lock your
project.
Locking a Project
1. In the SSP Toolkit, open the project you want to lock.
4. In the New Password field, enter the password you want to use to
lock the project. Passwords are case-sensitive and are limited to 12
characters.
5. In the Confirm Password field, enter the same password again for
confirmation.
6. Click OK. The project is locked. The next time you open it, you will be
required to enter the password you selected in step 4.
6. In the Confirm Password field, enter the new password again for
confirmation.
7. Click OK. The password for the locked project is changed. The next
time you open the project, you will need to enter the new password.
Unlocking a Project
To unlock a project and remove the password protection:
4. Enter the password for the locked project, then click OK.
Password protection is removed from the project and the Unlock but-
ton becomes unavailable, indicating the project is no longer locked.
1. In the SSP Toolkit, open the project you want to create a distributor’s
file from.
2. While in any stage, from the File menu, select Export .DST File. The
Save As dialog box appears.
3. Enter the distributor file name in the File Name field, then click Save.
The distributor file is saved under the file name you entered, with a
.DST extension. It is now ready to be sent to your distributors.
2. If you have made changes to your project, but haven’t saved them, you
are prompted to do so. Click Yes to save your changes or No to discard
them.
When you start designing your protection strategy, the first decision you
need to make is whether you want to protect your application using one of
the predefined protection types—integrated or automatic—or if you want to
add your own custom elements.
Custom elements are individual algorithms, counters, sublicense limits or
data words. You define not only the values for these elements, but also their
location on the key. For more information about using custom elements, see
Chapter 7, “Working With Design Elements,” on page 185.
This chapter explains how to protect your application using one of the pre-
defined application protection types. We recommend selecting and imple-
menting one of these types for every application you are protecting. If you
want to also use custom elements, you can do so in addition to the standard
application protection.
This chapter covers the following topics:
■ What is application protection?
■ Selecting a protection type
■ Using integrated protection
■ Using automatic protection
Note: If you apply both automatic and integrated protection to your application,
when the automatic portion of the application executes it will run in the
mode set during protection (i.e. either Standalone, Network, or dual).
When the integrated portion of the application executes, it will run in the
access mode you set in code, or dual mode if no access mode was specified.
See “Setting the Access Mode” on page 103 for more information.
Demo Applications
With both types of application protection, you can designate your applica-
tion as being a demonstration (demo) or trial version through the use of a
counter that controls the number of times the application can run before it
expires.
For example, set the demo counter value to 5. Each time the application is
run, the counter is decremented by one. The sixth time the user tries to run
the application, it won’t allow him to run, because the execution counter
has expired, which deactivates the algorithm, and the algorithm returns an
invalid response.
*The action to take if a key is missing or the license is denied is up to the developer.
a password when it expires and you have verified purchase of the full version
of the application.
For more information about designating demo applications, see “Control-
ling Demo Applications” on page 94.
Note: Before you create the first element in your protection strategy, you need
to decide whether you will be using SuperPro XM or SuperPro keys for
your design. When you click on one of the buttons in the “Add element”
group, you will be asked to specify whether the design will be used with
SuperPro XM or SuperPro keys. Alternatively, you can specify SuperPro XM
keys by clicking on the “Enable SuperPro XM Features” check box in the
lower right-hand corner before creating the first element.
This way, when viewing the element list, you’ll quickly be able to rec-
ognize what applications you have protected. The icons in the ele-
ment list show you what kind of application protection is used for
each application.
Tip: This name will be used throughout the SSP Toolkit to identify this element,
so be sure it adequately describes the element.
6. Click Next.
Note: Throughout the SSP Toolkit, only valid and available cell addresses are pro-
vided in Address drop-down lists, preventing you from selecting an inap-
propriate address.
6. Click Close.
The value from the Hexadecimal field is transferred to the Algo 1 field.
Note: If you already know the value you want to use for the algorithm words,
you can enter it directly in the Algo 1 and Algo 2 fields. Algo 1 is the first
algorithm word and Algo 2 is the second algorithm word. When you select
an activation type, the Algo 2 value will be automatically changed, as nec-
essary, to make the algorithm active or inactive.
10. In the counter value box, enter a number representing the number of
times you want to allow the demo application to be executed.
For example, if you enter 5, the application can be run five times. The
sixth time the user tries to run the application, they will be unable to.
1. Select the activation type you want to use for this application: Active,
Static, Trusted or Distributed.
Tip: For more information about activation types, including when to use each
type, please see “Activation Types” on page 63.
Note: If you selected Trusted or Distributed, you cannot override the default acti-
vation passwords. Unique activation passwords are generated based on
the developer ID, serial number and product information. See the table
“Activation Types” on page 63 for more information about the Trusted
and Distributed activation types.
See page 152 for instructions on using the Numeric Assistant dialog
box.
4. Repeat step 3 for the Password 2 field to enter a password for the sec-
ond word of the algorithm.
Tip: For more information about the Client Activator, see “Using the Client Acti-
vator” on page 271. You may also want to refer to the Client Activator docu-
mentation, included in the Client Activator package.
6. Click Next.
Tip: Be sure to select the Show advanced options check box to view the
1. From the Address drop-down list, select the address of the cell you
want the first word of the element to be placed in.
Note: Be sure to review “Valid Algorithm Addresses” on page 37 for more infor-
mation about where elements can be placed on the key.
3. In the Algo 1 field, click the arrow button to access the Numeric
Assistant dialog box.
5. Click Close.
The value from the Hexadecimal field is transferred to the Algo 1 field.
Note: If you already know the value you want to use for the algorithm words,
you can enter it directly in the Algo 1 and Algo 2 fields. Algo 1 is the first
algorithm word and Algo 2 is the second algorithm word. When you select
an activation type, the Algo 2 value will be automatically changed, as nec-
essary, to make the algorithm active or inactive.
the output file—the file you will ship to your customers.You must select both
an input file and an output file.
2. Browse to locate and then select the executable file you want to pro-
tect, then click Open.
Note: There is a 127-character limit for the path of the input or output files. If
the file you want to shell is in a path that exceeds this limit, an error mes-
sage will appear at the Prototyping stage. Move the file to a path with
shorter directory names, then update the location and click Next again to
continue.
4. Browse to locate the directory path you want the protected executable
file placed in after the shell is added. Be sure to enter a file name for
the shelled executable file at the end of the path.
5. If you want the shelled file to overwrite an existing file with the same
name, select the Overwrite existing output file check box.
Warning! If you specify the shelled application’s executable file to have the
same name as the non-shelled file, and you select the overwrite
option, the non-shelled file will be overwritten with the shelled file.
6. You must also decide how and where you want your protected appli-
cation to access the key. Choose any of the options given below before
clicking Next:
8. You can optionally choose a cell address from the Address drop down
or simply select Auto to let the Toolkit assign a cell automatically. You
may also add a counter value for the Value field. It allows to restrict
the number of sublicense issued to a protected application.
Use the following table to decide which options you want to use. You can
select any, all or none of these options.
Note: In Sentinel SuperPro 6.0, you were able to control how often the applica-
tion checked for the presence of the key (the “background check” option).
This option is now automatically set for all applications using automatic
protection. The application will check for the presence of the key every
minute; if the key does not respond, the application will shut down.
After you have finished selecting the options you want to use, click Next to
continue.
Use the following table to decide which options you want to use. You can
select any, all or none of these options..
Security Options
Option Description To Enable:
Multi-layering You can choose from layers with varying The option is enabled with
levels strengths, from level 1 to 5 the size of the a default setting of 3.
application increases, as more protection Select a layer level of your
code is added with higher levels. Level 1 choice from the Multi-
provides reasonable protection, with Layer Level drop down.
minimum increase in the file size. Level 5
provides maximum protection and maximum
increase in the file size. The default setting is
3.
Please note that you must always run the
output files (protected applications) in an
environment, typical to your product users, to
experience its performance. If the size of the
application is an issue for your, you may
choose the best-fitting level of protection.
Check terminal Allows your protected application to check Select the Check terminal
client terminal client in a Terminal Service client check box.
environment. The default setting is Selected.
Hide import Shell provides protection against a memory Select the Hide mport
symbols dump of the protected application. You need symbols check box.
to select the Hide import symbols check box
to enable this added protection. The default
setting is Selected.
Advanced Options
Option Description To Enable:
.NET .NET Enhancements feature provides Select the .NET
Enhancement enhanced security to pure .NET applications Enhancement check box.
(Exes and Dlls):
• Hides original entry point method (only
.NET executable)
• Encrypts string of original application
• Encrypts constant of original application
Note: The Advanced Options of Shell Security settings are not displayed if you
have not checked the Show advanced options check box, while entering
a Protection Element Name in the first dialog of Shell Wizard.
1. After you have finished selecting the options you want to use, click
Next to continue.
Note: If you select files to be encrypted at shell time, and your application will be
run on Windows 98, you must install the Sentinel data protection driver on
your user’s system. See “Installing the Sentinel Data Protection Driver” on
page 258 for more information.
If you are shelling an application and you try to encrypt a .DLL which is a
dependency of the application you are shelling, the .DLL will not be
decrypted at runtime because the operating system tries to load the .DLL
before the shell has a chance to decrypt it.
The actual file encryption takes place when you add the shell to the applica-
tion in the Prototyping stage.
You can encrypt a maximum of 50 files at a time. To encrypt more than 50
files, add a second automatic protection element. In the second element, be
sure to use the same encryption seed to encrypt the additional files with the
same encryption.
Note: If an .EXE or .DLL is selected in the above dialog, then an error will be dis-
played as these kinds of files are not allowed for selection.
3. Browse to locate and then select the file you want to encrypt, then
click Open. The file’s path appears in the Input File field.
5. Browse to locate the directory path you want the encrypted file placed
in, then click Open. Be sure to enter a file name for the encrypted file
at the end of the path.
6. Click OK.
Note: If you add a file and then decide you don’t want to encrypt that file, select
the file and then click Delete. You can also change the location path for
an input and/or output file by selecting the file and then clicking Edit.
A random encryption seed is provided; you can choose to use this seed
if you like. If encrypted data files are shared by multiple applications,
all the applications must use the same encryption seed. See page 86
for more information about encryption seeds.
9. If you want encrypted files to overwrite existing files with the same
name, select the Overwrite existing files check box.
Note: For more information about activation types, including when to use each
type, please see “Activation Types” on page 63.
1. Select the activation type you want to use for this application: Active,
Static, Trusted or Distributed.
Note: If you selected Trusted or Distributed, you cannot override the default acti-
vation passwords. Unique activation passwords are generated based on
the developer ID, serial number and product ID. See the table “Activation
Types” on page 63 for more information about the Trusted and Distributed
activation types.
See page 152 for instructions on using the Numeric Assistant dialog
box.
4. Repeat step 3 for the Password 2 field to enter a password for the sec-
ond word of the algorithm.
Tip: For more information about the Client Activator, see “How Distributors Acti-
vate an Application” on page 269. You may also want to refer to the Client
Activator documentation, included in the Client Activator package.
6. Click Next.
1. In the Error Messages list, select the message you want to custom-
ize.
2. In the Message Text field, modify the default message text as needed.
4. When you have finished customizing your error messages, click Next
to continue. This will take you to the page which summarizes your
protection strategy. Click on Finish. Element definition is complete
and you are returned to the Element List View, where your application
now appears in the list.
4. Click Delete.
5. You are asked if you want to confirm the deletion. Click Yes.
Note: If you have edited or deleted a protected application after you have com-
pleted the Prototype stage, you must complete the Prototype stage again
before you can continue to the Implementation or Make Keys stages.
Question 2 - What are the file types supported by Shell for encryp-
tion/decryption?
The table below lists the file types supported by Shell for encryption/
decryption:
File Types and Application Supported for Encryption/Decryption
Question 3 - Which file types are not supported by the "Hide import
symbols" option?
The Hide import symbols option (under the Security tab) cannot be applied
to the following file types:
■ .NET
■ Visual FoxPro
■ Director
■ Power Builder
■ Adobe Acrobat Reader (PDF files)
■ Applications that use SmartHeap DLLs
1.The sgen.exe utility can be found in "Program Files\Microsoft Visual Studio 8\SDK\v2.0\Bin"
folder of Visual Studio Installation.
2. Now Shell the exe and copy paste the .XMLSerializers.dll generated in
step 1 to the same folder where the shelled exe is located.
Question 9 - How can I rebuild the original C++ builder DLL if the
shelled C++ builder DLL crashes during unload?
You can rebuild the original DLL and also prevent the crash to occur again
by following the steps mentioned below:
Note: If you add custom elements, the SSP Toolkit cannot generate the API
pseudocode for you. You must write the API calls required to use the values
programmed into your keys yourself.
Adding Algorithms
To add a custom algorithm to your protection strategy:
4. Select the type of algorithm you want to add, then click Next.
5. In the Name field, enter a name for this algorithm. There is a 16-
character limit for element names.
Tip: This name will be used throughout the SSP Toolkit to identify this algorithm,
so be sure it adequately describes it.
7. Click Next.
9. In the Algo 1 field, click the arrow button to access the Numeric
Assistant dialog box.
11. Click Close. The value from the Hexadecimal field is transferred to
the Algo 1 field.
Note: If you already know the value you want to use for the algorithm words,
you can enter it directly in the Algo 1 and Algo 2 fields. Algo 1 is the first
algorithm word and Algo 2 is the second algorithm word.
13. The AES algorithm engine is selected by default for protection strate-
gies using the SuperPro XM key. This is the most secure algorithm
engine. However, you can select one of the other two algorithm
14. If you want to make this algorithm active, select the Make the algo-
rithm active check box. Clear the check box to make the algorithm
inactive.
For example, if you want to use the counter to control a demo applica-
tion’s executions, and you enter 5, the application can be run five
times. The sixth time the user tries to run the application, she will be
unable to.
See page 190 for instructions on using the Numeric Assistant dialog
box.
2. Repeat step 1 for the Password 2 field to enter a password for the sec-
ond word of the algorithm.
3. Click Finish.
Adding Counters
To add a single counter to your protection strategy:
5. In the Name field, enter a name for this counter. There is a 16-char-
acter limit on the counter name.
Tip: This name will be used throughout the SSP Toolkit to identify this counter, so
be sure it adequately describes it.
7. Click Next.
9. From the Address drop-down list, select the address of the cell you
want the counter to be placed in.
5. In the Name field, enter a name for this data word. There is a 16
character limit on the data word name.
Tip: This name will be used throughout the SSP Toolkit to identify this user data
cell, so be sure it adequately describes it.
7. Click Next.
10. From the Address drop-down list, select the address of the cell you
want the data to be placed in.
11. If you want your application to be able to read this data, but not make
changes to it, select the Read-Only check box.
If you leave this check box blank, your application will be able to
change the data located in this cell.
Data word definition is complete and you are returned to the Element
List View tab, where the data word element appears in the list.
Tip: This name will be used throughout the SSP Toolkit to identify this sublicense,
so be sure it adequately describes it.
7. Click Next.
10. From the Address drop-down list, select the address of the cell you
want the sublicense to be placed in.
Deleting an Element
In addition to editing an element, you can also remove the element from
your protection strategy. Be sure you want to remove the element from your
protection strategy before you complete the following procedure, as you
cannot recover an element once it has been deleted—you would need to add
the element again as if it was new.
To delete an element:
5. You are asked if you want to confirm the deletion. Click Yes.
Note: If you have edited or deleted an element after you have completed the
Prototype stage, you must complete the Prototype stage again before you
can continue to the Implementation or Make Keys stages.
Note: If you selected the One Time Update option in the Developer Configura-
tion dialog box, an element for the update will appear on the key. You
cannot move this element via the drag-and-drop method. For more infor-
mation about this option, see page 114.
3. Move your cursor over the cells to view the name of the element
located in the cell.
The Sentinel SuperPro 6.5 Toolkit provides the facility to design and
program the SuperPro and SuperPro XM keys. It enables the devel-
oper to design a strategy of upto the maximum key size (232) that is
supported by the Toolkit (available only in case of SuperPro XM keys).
One key can be programmed to provide several different types of both
fixed and variable responses, giving you many variations in the types
of software locks you can create.
For example, cells can be used to store fixed user data, such as serial
numbers, user names or codes controlling feature access. Such data
can be read by your application to verify the key is still attached or to
perform some other function. You can also use stored data to control
program flow or application functions.
Cells can also store algorithms used to scramble query codes sent by
your application. Other cells can be programmed as counters used to
restrict the number of executions. While the first 8 cells are reserved
for system information, in both SuperPro and SuperPro XM keys, the
Note: If you delete an element from your strategy, and then repeat the prototype process, when
you view the key using MemView, it may look like the element is still there. This is because
when you prototype a key, it skips any unassigned cells. Since the cells from the element you
deleted are now unassigned, they weren’t overwritten, and thus still contain the values
from the previous prototype. Despite this, the element has been deleted and is not pro-
grammed into the key.
Note: The Prototype stage is a required stage in the SSP Toolkit—when you create a prototype,
you are committing to your strategy’s design. If, after creating an initial prototype, you
return to the Design stage to edit or add more elements, you must repeat the prototyping
process before you can continue to the Implementation and Make Keys stages. The Proto-
type stage may be repeated as many times as necessary.
2. Click Go.
The prototype process begins. The status and outcome of each stage of
the process appears in the text box. The more elements you have in
your strategy, the longer the prototype process takes. When the “Pro-
totype Stage Complete” message appears, you are ready to continue.
Note: If a message appears informing you that your developer ID or passwords are incorrect, you
need to return to the Project stage and enter the correct ID and/or passwords before you can
continue. See “Changing Your Developer ID or Passwords” on page 138 for more information.
3. Go to the next section if you want to verify the key was programmed
correctly (this is an optional step).
3. Click MemView. The MemView section appears with all cells shaded
grey. This means the key has not yet been queried for the status of the
programmed cells.
4. Click Refresh. The SSP Toolkit queries the key, returning the access
code and value of each cell.
Cell access codes are identified by different colors, as shown in the legend on
the right. Cell values are provided in hexadecimal format within each indi-
vidual cell. A question mark (?) represents a restricted cell, or a cell pro-
grammed with an algorithm value.
To view a selected cell’s address, move the mouse pointer over that cell. The
address appears in the Address field automatically. To view cell values and
addresses in decimal format, select Decimal in the lower left of the window.
After you have verified your key was programmed correctly and your pro-
tection strategy is complete, you are ready to add protection to your
application code.
• If you are using both integrated and automatic protection for a single
application, you must first add the appropriate API function calls to
your source code and then recompile. After you have recompiled, you
can apply the shell to the executable file. Go to the next section to add
the API function calls.
• If you selected only integrated protection for your application(s), you
need to add API function calls directly to your source code. Go to the
next section.
Note: If you are using only automatic (“shelled”) protection for your application, the appropriate
API functions are added during the shell process. You do not need to manually add API func-
tion calls to your application source code. Go to “Shelling an Application” on page 215.
Warning! The pseudocode protection plan contains your developer ID and passwords—make
sure you keep it secure!
3. From the drop-down list, select the application you want to view the
pseudocode protection plan for.
4. From the options on the right, select the development language you
want to view the pseudocode in.
The pseudocode protection plan for the selected application and lan-
guage appears in the text box.
The first part of the plan describes what you need to do in your development
language to prepare to use the Sentinel SuperPro API.
The next part of the plan shows you the expected responses for queries to the
algorithms programmed into your keys. Random query strings and their
Tip: For more information about Sentinel SuperPro API functions, please refer to Chapter 14, “API
Function Reference,” on page 301.
3. To evaluate the API function, click API Explorer to access the API
Explorer section.
4. From the API function list, select a function. A description of the func-
tion appears to the right.
See page 128 for more detailed information about selecting parameters.
6. Click Execute. The API function is invoked, with the parameters you
selected, and the API Call Results message box appears:
Note: Remember, you need to call the RNBOsproFormatPacket() and RNBOsproInitialize() func-
tions prior to calling any other function.
Shelling an Application
Applications you have defined as using automatic (“shelled”) protection are
easy to implement, as all you need to do is click a button to add the protec-
tive shell layer to your executable file. Once the shell has been added, all the
protection options you defined for the application are in place.
To add the shell to an application:
2. In the Element List View tab click on automatic protection and select
the type of key whether it is SuperPro or SuperPro XM
Note: You’ll be prompted to select the key type only if you are using the Toolkit for the first time
during this session or if you have not already specified the Key type from the check box at
the bottom of the screen
4. Select the Show advanced options check box if you want to view
advanced options like element location or advanced security settings.
Click Next.
7. Enter values for the Algo 1 field or click the drop down and select
Randomize to generate a random value.
10. Select Override Existing file check box and click Next.
11. You must also decide how and where you want your protected applica-
tion to access the key. Choose any of the options given below:
• Expiration Date
• Execution Control
• Time Control
14. Select Shell Security options for the protected application. Customize
your protection by enabling any or all of the following:
• Security Options
• Multi-Layer Level
Note: The Advanced Options are available only if you have selected the Show advanced
options check box. Refer to Step 4 on page 215.
15. Select the Encrypt additional files check box. Add some additional
files by clicking on Add and browsing the file(s) location.
Note: You may also add or edit the existing files in the list.
16. Enter a value for the Encryption Seed. Select the Overwrite Exist-
ing files check box and click Next.
17. Select the activation type you want to use for this application: Active,
Static, Trusted or Distributed. Do one of the following:
Note: If you selected Trusted or Distributed, you cannot override the default activation passwords.
Unique activation passwords are generated based on the developer ID, serial number and
product information. See the table “Sentinel SuperPro Activation Types” on page 60 for
more information about the Trusted and Distributed activation types.
18. In the Password 1 field, click the arrow button to access the Numeric
Assistant dialog box, and enter an activation password for the first
word of the algorithm.
19. Repeat step 3 for the Password 2 field to enter a password for the sec-
ond word of the algorithm.
22. Click on Next, a list displaying your selected strategy will appear, Click
on Prototype Now button and your application will be Shelled.
With the key missing, you should be unable to run your application
and an error message should appear.
2. Start the Sentinel Protection server on the system you connected the
key to.
With the key attached to the server, the application should be able to
obtain a license and run normally.
4. Use the application for several minutes, to verify that heartbeat mes-
sages are being sent appropriately and that you do not receive any
time-out errors from the server.
5. With the application still running, go to the server computer and open
the Sentinel License Monitor to verify that the key is showing a single
license in use.
With the key missing from the server, you should be unable to obtain a
license and an error message should appear.
If your protected application does not respond as expected in either the stan-
dalone or the network scenarios, review your protection strategy for missing
elements or errors by rereading Chapters 7 and 8 in this guide. If, after
reviewing your strategy, you still need assistance, please contact SafeNet
Technical Support. See “Contacting Technical Support” on page xxi for
Technical Support contact information.
Note: If you are a Linux user, refer to the last section of this chapter “Configuring
the SafeCfg Utility for Linux” on page 232 for allowing field
activation by configuring the SafeCfg.
To be able to update keys in the field, you need to define the field activation
actions and commands that can be performed on those keys within your
protection strategy.
Commands are API function calls that describe what will be done to the key
in the field. For example, the Decrement Counter command locates the
counter cell on the key and decrements it by the value you specify. Actions
are groups of one or more commands.
When you generate a license code, the actions and commands you select are
encrypted into the license code specific to the selected key. When the license
code is entered in the Client Activator or Field Exchange Utility, the actions
and commands are applied to the key.
This chapter includes the following topics:
■ Adding actions
■ Adding commands
■ Available commands
■ Testing your strategy
Note: If you selected the Distributed activation type, be sure to add an action
and command for incrementing the counter on the distributor key. This
will allow you to add more licenses to your distributor’s key in the field.
When you create a .DST file for your distributor, the command for incre-
menting the distributor key counter is NOT included. This prevents your
distributor from giving himself more update licenses without your
approval.
If you change your strategy by returning to the Design stage, these actions
and commands are appropriately updated or removed automatically during
the Prototype stage.
You must define actions before you can add commands to your protection
strategy.
Adding an Action
1. Navigate to the Implementation stage.
2. Click the Field Activation tab. The Field Activation section appears
with the Action Definition window open.
4. Under Options, in the Name field, enter a name for the action.
Removing an Action
If you no longer want an action in your protection strategy, or you have
made a mistake, you can delete actions. To do so:
■ Select the action you want to delete, then click Remove Action.
The action—and all its corresponding commands—is removed from
the Command Description list.
Note: You are not asked to confirm the action deletion. Be sure you have
selected the right action, and that you want to delete this action perma-
nently, before you click Remove Action.
If you have provided your Sentinel SuperPro project file to users who are
generating license codes, you need to send a new file to those users after you
have removed an action. This prevents them from selecting the action you
just removed to update a key in the field.
Adding a Command
1. Navigate to the Implementation stage.
2. Click the Field Activation tab. The Field Activation section appears
with the Action Definition window open.
5. Under Options, in the Name field, enter a name for the command.
The name should be concise, yet describe what the command will do
to the key in the field.
6. From the Command drop-down list, select the command you want to
perform on the key.
7. From the Cell drop-down list, select the address of the cell you want
the command performed on.
Note: To view the cells being used in your protection strategy (and the elements
occupying them), open the Design stage, then click the Element Layout
View tab. See “Rearranging Elements on the Key” on page 201 for more
information. To view the addresses of these cells, open the Implementa-
tion stage, click the API Explorer tab, then click MemView. See “Viewing
Memory Cells” on page 132 for more information.
8. In the Value field, enter the value you want written to the selected
cell.
Click the arrow to access the Numeric Assistant dialog box. See
page 190 for instructions on using the Numeric Assistant.
Use the table on the next page as a guide for what values to enter,
based on the command you have selected.
Tip: The Overwrite Passwords are necessary whenever you want to change the
value of a locked data word or read-only cell on the key. If you will be imple-
menting the one-time update option for license codes (see below), you must
include the Overwrite Passwords in your field exchange DLLs.
The access code determines how you want to use the selected cell. For
example, to make the cell an algorithm cell, select access code 3; to
make the cell a counter, select access code 2. See “Cell Types” on
page 26 for more information.
Removing a Command
If you no longer want a command in your protection strategy, or you have
made a mistake, you can delete commands, just as you can actions.
Tip: To delete all commands in an action, it may be easier to delete the action
itself—see “Removing an Action” on page 224 for more information.
To remove a command:
■ Select the command you want to delete, then click Remove
Command.
The command is removed from the Command Description list.
Note: You are not asked to confirm the command deletion. Be sure you have
selected the right command, and that you want to delete this command
permanently, before you click Remove Command.
Because each action must have at least one command, you cannot delete a
command if it is the only command listed under the selected action. If you
need to delete such a command, click Add Command first to add a new,
undefined command, then remove the first command as described above.
If you have provided your Sentinel SuperPro project file to users who are
generating license codes, you need to send a new file to those users after you
have removed a command. This prevents them from selecting the command
you just removed to update a key in the field.
Available Commands
The following commands are available for field activation using Sentinel
SuperPro keys:
Command Description
Write Cell Writes the value you entered to the selected cell.
Activate Algo PW1 Enables an inactive algorithm already on the key. The
value you enter is passed as a parameter to the
Activate function. This command must be used in
conjunction with the Activate Algo PW2 command.
See “Using Activation Passwords” on page 79.
Activate Algo PW2 Enables an inactive algorithm already on the key. The
value you enter is passed as a parameter to the
Activate function. This command must be used in
conjunction with the Activate Algo PW1 command.
See “Using Activation Passwords” on page 79.
Decrement Counter Decrements a counter cell. This command reads the
current counter value and then subtracts one from the
value.
Increment Increments the activation counter cell on a distributor
Distributor Counter key. This command reads the current counter value
and then adds the value you specified. This command
is available only if you have a distributed application
included in your protection strategy.
Increment Counter Increments a counter cell. This command reads the
current counter value and then adds the value you
specified.
Bit Mask AND This action is valid for Read Only and Read/Write cells.
Bit Mask OR This action is valid for Read Only and Read/Write cells.
Decrement Counter Decrements a counter cell to zero, regardless of the
to Zero current value. Typically used when you are updating a
demo to a fully-licensed version; must be used in
conjunction with other commands. See “Controlling
Demo Applications” on page 94.
1. Program a key using your protection strategy. See Chapter 10, “Pro-
gramming Keys,” on page 233 for instructions.
2. Connect the key to any workstation and use it to run your applica-
tion.
3. Open the Client Activator or the Field Exchange Utility on the work-
station you ran your application on, and generate a locking code.
5. Enter the locking code and generate a license code, selecting the
actions you want to test. See Chapter 12, “Activating and Updating
Keys,” on page 265 for instructions.
7. After the license code updates the key, check to see if you have access
to the expected areas of your application, based on the action(s) you
selected in step 5.
9. Connect the key to the workstation you are running Sentinel Super-
Pro on to view the cells and their values using MemView in the API
Explorer section of the Implementation stage.
The values should match those you entered when you were defining
the commands. See “Viewing Memory Cells” on page 132 for more
information about using MemView.
Final Steps
Now that your strategy is complete, the final step in preparing the applica-
tion for shipping is to compile it.
Compile the application and link it with the appropriate interface modules
and the Sentinel system driver. Use the readme file for your development
language to determine what file(s) you need.
Once linked, the interface module and Sentinel system driver handle all
communication between your application and the key.
Note: The above steps are for applications using integrated protection only. If
you are using automatic (shelled) protection, you do not need to compile
or link your application. A shelled application is ready to ship as soon as
you have applied the shell.
2. Now, you need to fill in your developer ID and passwords in the order of
appearance. Read the instructions in the section“Developer Configura-
tion Dialog Box” on page 116 for more information. Ensure that you
choose the same settings to configure the SAFE objects.
3. You will be now asked to either auto generate the secret code or type
on your own. The secret code is a parameter that enables field updates
across multiple platforms. To use the auto generated string, type y, or
type n and specify a secret. A secret string must be 9 to 16 characters
long, consisting of at least one numeric character.
5. You may be asked to specify a one time update cell, only if you have
included your overwrite passwords in step 4 earlier. Type a cell address
in hexadecimal.
Tip: You could use the Memory View option in Toolkit window to decide which cell to select.
The instructions in this chapter are provided so you can familiarize yourself
with the key programming procedures used by your manufacturing depart-
ment, or so you can program product or distributor keys yourself if
necessary.
This chapter covers the following topics:
■ Setting up to program product keys
■ Programming a product key
■ Programming a distributor key
Note: You can cascade keys while they are being programmed.
Note: If you remove a key (which was inserted first in the series), while
programming multiple keys then, the keys that come next in the series will
not be programmed. You'll need to start the activity again.
1. In the SSP Toolkit, open the Sentinel SuperPro project containing the
protection strategy for the application you are programming the
key(s) for.
2. Navigate to the Make Keys stage, and verify you are on the Product
Keys tab.
Note: If you did not complete the Prototype stage, the Make Keys stage is
unavailable and you are not ready to program product keys. Refer to Chap-
ter 8, “Implementing Your Strategy,” on page 205 for more information on
completing the Prototype stage.
Note: The default activation status for each application depends on the
activation type you selected during the Design stage.
You may want to change this status for selected key(s) only—this
option allows you to do so on a per key basis without changing your
overall strategy.
Note: Because the override is on a per key basis, if you make a change to the
activation status, it will affect ALL keys programmed in the batch.
Note: If you are programming multiple keys, the activation type remains same
for all of them.
Note: You can program ONLY one Distributor key at a time. For more
information about using the Distributed activation type, see page 68.
Before you begin programming distributor keys, make sure you have an ade-
quate stock of keys with your assigned developer ID. The keys you will be
programming as distributor keys must have the same developer ID as the key
used while you designed your protection strategy.
If you need additional keys, please contact your SafeNet Inc. sales represen-
tative or distributor.
Note: You cannot cascade keys while they are being programed. Only one key
can be attached at a time during programming.
1. In the SSP Toolkit, open the Sentinel SuperPro project containing the
protection strategy for the application you are programming a key for.
Note: If you did not complete the Prototype stage, the Make Keys stage is
unavailable and you are not ready to program product keys. Refer to Chap-
ter 8, “Implementing Your Strategy,” on page 205 for more information on
completing the Prototype stage.
5. In the Distributed Applications list, select the check box for the
application you want to assign metering options for.
Note: A check mark must appear in the box for the application to be selected; if
the check mark does not appear, the application will not be programmed
onto the key. Be sure to select the check box and not just the application
name.
When your application is complete, and your product keys are programmed,
you are ready to ship your protected application to your distributors and/or
customers.
What you ship depends on who you are sending the application to. Custom-
ers usually only need the application, the key and the Sentinel system driver.
However, when you ship your application to distributors, there are
additional items you must ship along with your application and the product
key, such as the stand-alone utilities used for field activation or key
programming, and a distributor key for activating distributed applications.
This chapter provides lists of recommended items to send to distributors and
customers; you can modify these lists as appropriate for use with your
application.
To protect your product keys against damage during shipping, this chapter
also provides guidelines for handling and packaging your keys.
This chapter covers the following topics:
■ What to send to your customers
■ What to send to your distributors
■ Packaging and handling guidelines for product keys
Note: If you choose to use the Sentinel Client Activator, you also need to ship
your customers the Client Activator configuration file (activator.rac) and
installation tool (ainst.exe). See the Client Activator documentation for
more information.
Note: If the license code is generated by Sentinel Super Pro 6.5.0 Toolkit, you
must send the Sentinel Super Pro 6.5.0 Field Exchange Utility and
USafe32.dll to the end user.
■ If you are shipping the Field Exchange Utility, the following files to
provide support for HTML Help: hhupd.exe and hhactivex.dll (see
page 253 for more information).
■ Instructions for using the Client Activator or Field Exchange Utility
(fieldexutil.exe) for field upgrades.
■ One or more Sentinel SuperPro keys programmed with the license
limits and values expected by your application.
■ Instructions for attaching the key to the computer or network server.
■ The Sentinel system driver—sentinel.sys for Windows 2000/XP/
2003/Vista or sentinel.vxd for Windows 98/ME - version SSD7.4.0 or
later.
The Sentinel system driver—sntnlusb.sys for Windows 98/ME/2000/
XP/2003/Vista - version SSD7.4.0 or later in case you are using USB
keys.
■ If you are protecting data files for a Windows 98/ME application, you
also need to ship the Sentinel data protection driver. See “Installing
the Sentinel Data Protection Driver” on page 258.
■ If you wrote a separate utility for entering activation passwords, you
also need to ship that utility and its associated files.
When to Deploy?
Sentinel driver is the device driver for using the hardware keys. It must be
redistributed with all kinds of SuperPro protected applications, regardless of
the strategy chosen.
Where to Deploy?
The Sentinel driver must be deployed on the system where the hardware key
is attached. If the application is a stand-alone application, install the Senti-
nel driver on the system where the application is installed. If the application
is a network application, install the Sentinel driver on the system in the net-
work where the hardware key is attached.
How to Deploy?
You can use the Sentinel Protection Installer to deploy Sentinel driver and/
or Sentinel Protection Server. For Windows The <installdir>\Sentinel Protec-
tion Installer path contains the relevant files, including the merge modules
and an MSI that you can use in your Windows Installer-based package. It
also contains a Help file that guides you about the various methods to
deploy Sentinel System Driver.
When to Deploy?
It is the license manager for your protected applications. As a rule of thumb,
it is necessary for using network applications—when clients concurrently
access the hardware key(s) attached to a networked system.
The access mode you have chosen for your protected application can also
help you in deciding whether you need to ship the protection server or not.
Where to Deploy?
The Sentinel Protection Server must be installed on the system where the
hardware key is attached.
Note: If you use RNBO_STANDALONE then you don't need the Sentinel Protec-
tion Server at all.
How to Deploy?
You can use the Sentinel Protection Installer to deploy Sentinel driver and/
or Sentinel Protection Server.
For Windows
The <installdir>\Sentinel Protection Installer path contains the relevant files,
including the merge modules and an MSI that you can use in your Windows
Installer-based package. It also contains a Help file that guides you about the
various methods to deploy Sentinel Pro-tection Server.
On Windows 2000/XP/2003/Vista, the Sentinel Protection Server is
installed as a system service that will start automatically whenever you boot
up.
Note: You can also create your own installer program that includes just the Senti-
nel Protection Server and the Sentinel system driver, and have your users
run it separately from your application installer. How you install the server
and driver is up to you, as long as they do get installed.
For your convenience, merge modules for use with the Windows Installer
have been provided on the Sentinel SuperPro Installation CD. These mod-
ules can be found at: E:\Sentinel Protection Installer\Merge Modules
where E: is the CD drive. The following procedure provides instructions
for using the merge modules in your own installer.
If you choose to not use Windows Installer, another alternative is to add the
files manually to your own installer and then use the loadserv.exe utility to
add the Windows NT service, and manually add shortcuts for the Windows
9x (98/ME) server. Use the information on page 254 to help you manually
add the executable files into your installation program.
Note: To view HTML Help, users also must have Microsoft Internet Explorer 4.0 or
later installed on their systems. Internet Explorer is NOT part of this merge
module, and may need to be installed separately. Refer to
www.microsoft.com for more information.
The merge modules can be added to any Microsoft Windows Installer pack-
age. There are many third-party applications that can be used to design a
Windows Installer package. An example would be InstallShield® for Win-
dows Installer. As with other applications, it assists you in building the
actual installation media and simplifies configuration. For more informa-
tion about using and developing a Windows Installer package, visit
Microsoft’s MSDN Web site at http://www.microsoft.com.
Once you add the merge module to your installation package, you can asso-
ciate it with a particular installation feature. This allows the user to have
some control over whether this feature should be installed. Alternatively,
you can make it a required item so that the user must install it with your
application.
The merge module itself contains the necessary files, registry entries and
shortcuts to install the server. It will determine what needs to be installed
based on the operating system it is being installed on. This frees you from
having to understand exactly how to install the server, yet you can install
the server from your own installer, giving you full control of the installation.
There are no special custom actions or properties that have to be used with
these merge modules. The only supported properties are the standard prop-
erties that are used by any Windows Installer package. Please refer to the
Microsoft Windows Installer documentation for more information.
1. Verify that the Sentinel system driver has already been installed on
your system.
The path in this field is used for installing a server on Windows 2000,
XP, 2003 or Vista only.
5. Click Configure to set the path for the server log file.
The server checks for the log file location when it starts up; if no path
for a log file is set, logging will not occur.
6. Click Exit.
1. Verify that the Sentinel system driver has already been installed on
your system.
4. Confirm that the path in the Executable File field is the correct path
for the location of the spnsrvnt.exe file.
5. Click Configure to set the path for the server log file.
Note: The data protection driver must only be run on Windows 98/ME; it is the
responsibility of the calling program to check for the type of operating sys-
tem being used. Remind customers that their computer must be rebooted
after installing the data protection driver in order to load the driver.
Customer Items
These are those items you need to ship to your distributor so they can send
them to customers who purchase your protected application.
■ The application executable and associated data files.
■ The Sentinel Protection Server (required for both stand-alone and
network applications). See “Installing the Sentinel Protection Server”
on page 250.
■ The Sentinel SuperPro System Administrator’s Help in HTML format
(SentinelSP6.5 Sys Admin Help).
■ The Sentinel Client Activator (recommended) or Field Exchange
Utility if your application is a demo or is programmed to allow field
activation.
Note: If you choose to use the Sentinel Client Activator, you also need to ship
your customers the Client Activator configuration file (activator.rac) and
installation tool (ainst.exe). See the Client Activator documentation for
more information.
■ If you are shipping the Monitoring Tool or the Field Exchange Utility,
the following files to provide support for HTML Help: hhupd.exe and
hhactivex.dll (see page 253 for more information).
■ Instructions for using the Client Activator or Field Exchange Utility
for field upgrades.
■ One or more Sentinel SuperPro keys programmed with the license
limits and values expected by your application.
■ Instructions for attaching the key to the computer or network server.
■ The Sentinel system driver—sentinel.sys for Win 2000/2003 or
sentinel.vxd for Win 98/ME/XP—version PD-7.4.0 or later.
The Sentinel system driver—sntlUSB.sys for Windows 2000/2003/
Vista or sentinel.vxd for Windows 98/ME/XP—version PD -7.4.0 or
later in case you are using USB keys.
■ If you are protecting data files for a Windows 98/ME/XP application,
you also need to ship the Sentinel data protection driver. See
“Installing the Sentinel Data Protection Driver” on page 258.
Distributor-Only Items
The items in this section are shipped to distributors for their use only, if you
have decided to allow them to activate applications or generate license codes
for field upgrades.
■ A distributor key, if you want to manage the number of activations or
updates your distributor can perform.
■ The License Generator Utility (LicenseGenUtil.exe) and instructions for
using it.
1.The sp_gXX.dll file can be any of the following, depending on the color depth the display
driver is configured to: sp_g24.dll, sp_g08.dll or sp_g04.dll.
Documentation
You can copy the appropriate sections from Chapter 13, “Using the Stand-
alone Utilities,” on page 281 to send to distributors using the License Gener-
ator Utility, or to customers using the Field Exchange Utility. You can also
use the information in Chapter 14 to create your own documentation for
these utilities.
Warning! Electrostatic charges may damage the Sentinel SuperPro keys. Work
surface mats and wrist straps are strongly recommended.
3. Customer sends the locking code to you (or your distributor, if you
authorized your distributor to perform field activation) via telephone,
fax, e-mail or the Internet.
4. You (or your distributor) enter the locking code in the Field Activation
section of the SSP Toolkit Implementation stage or in the Sentinel
5. You select the actions you want to perform on the key in the field.
Note: Available activation and update actions, and their corresponding com-
mands, were defined when the protection strategy for the application was
being designed. See Chapter 9, “Defining Field Activation Actions,” on
page 221 for more information.
The license code tells the Field Exchange Utility or Client Activator
how to reprogram the key, including how to activate the application.
9. The key is updated and the customer has access to the services he pur-
chased.
Note: In previous versions of Sentinel SuperPro, the locking code was known as
the Key ID string.
Note: In previous versions of Sentinel SuperPro, the license code was known as
the Update Key string.
2. Customer sends the locking code to the distributor via telephone, fax,
e-mail or the Internet.
3. With his distributor key connected, the distributor opens the .DST file
you provided in the Sentinel SuperPro License Generator Utility.
4. The distributor enters the locking code in the License Generator Util-
ity. The key information is extracted from the locking code.
5. The distributor selects the actions to perform on the key in the field.
10. The key is updated and the customer has access to the application.
For more information about using the Client Activator, including the com-
plete list of files you need to ship to your customer, please refer to the Client
Activator documentation.
Note: The instructions in this section assume you are using the Field Activation sec-
tion of the Implementation stage to generate the locking code. If you are
using the License Generator Utility, refer to Chapter 13, “Using the Stand-
alone Utilities,” on page 281 for more information.
1. If you are using a distributor key, connect the key to the appropriate
port and proceed to Step 5.
❑ If you copied the locking code to the clipboard, click the paste
button to paste the code in the field.
❑ If the locking code was saved to a file (.LOC), click the open button
to locate and open the file. The code is entered in the field
automatically.
The developer ID and serial number of the key the code was generated
from appears in the corresponding fields.
6. Under Output, in the Action list, select the action(s) you want to
perform on the customer’s key.
Note: Only selected actions (identified with a check mark) are added to the license
code’s script. Remember, actions determine which application features will be
activated or upgraded. For more information about actions, see Chapter 9,
“Defining Field Activation Actions,” on page 221.
Assume you have two commands that operate on the same cell. One
command must be executed before the other because the second com-
mand expects the cell to be in a state set by the first command. In this
case, you should not randomize commands.
8. Select the Log Activity check box to create a log file (LicenseGen.log)
containing all the license codes you generate.
❑ To save the license code to a file, click the save button and
select a file name and location for the license code file.
11. Go to the next section to send the license code to your customer.
Note: If you selected the one-time update option, your customer will only be
able to apply the license code one time. If they attempt to apply the license
code more than once, no additional updates or counter increments will
occur.
However, if you did not select the one-time update option, your customer
can apply the license code as many times as they like, possibly increment-
ing counters more than you intended. For more information about using
the one-time update option, see “Enabling the One-Time Update Option
for License Codes” on page 119.
For information on how your customer enters the license code using the
Field Exchange Utility, refer to Chapter 13, “Using the Stand-alone Utilities,”
on page 281.
For information about using the Client Activator to enter the license code,
please refer to the Client Activator documentation.
Tip: Remember, you should provide your customers with instructions for generat-
ing the locking code and entering the license code. See “What to Send to
Your Customers” on page 248 for more information.
1. Ask your distributor to run the Field Exchange Utility, while his dis-
tributor key is connected to his system, to generate a locking code.
2. Tell your distributor to send the locking code to you via telephone,
fax, e-mail or the Internet.
3. Enter the locking code in the Field Activation section of the SSP Tool-
kit Implementation stage. The key information is extracted from the
locking code.
8. The key is updated and the distributor has access to additional activa-
tion or update licenses.
Sentinel SuperPro comes with a set of three stand-alone utilities that allow
you to give other people—such as manufacturing department employees or
distributors—the ability to perform selected Sentinel SuperPro functions
without also having access to your passwords and protection strategy infor-
mation. The three utilities are as follows:
• The Make Keys Utility allows you to program keys for your protected
application.
• The License Generator Utility allows you or your distributors to activate
and update product keys in the field through creation of a license code.
• The Field Exchange Utility is used by your customers to generate
locking codes and enter license codes. This utility is necessary only if
you are using field activation for your application, but are not shipping
the Client Activator.
Tip: For information about the stand-alone Sentinel License Monitor, please refer to the Sentinel
SuperPro System Administrator’s Guide, included in your package.
2000 users should use the spnsrvnt.exe and loadserv.exe files. Instruc-
tions for installing both server types are provided in “Installing the
Server with the Executable Files” on page 254.
You also need to provide these users with the Sentinel SuperPro project
(.SPP) containing the protection strategy for the application they will be cre-
ating keys for.
You’ll want to install the Make Keys Utility on computers that reside on your
manufacturing floor. You are free to install a copy of this utility and the
server on multiple computers within your manufacturing area, so that keys
can be programmed on multiple computers at the same time.
• From the Start menu, point to Programs > SafeNet Sentinel >
SuperPro > 6.5> Tools, then select Make Keys Utility.
• Double-click the MakeKeysUtil.exe file icon.
Note: If you did not use the Sentinel SuperPro setup program to install the Make Keys Utility, it
will not be accessible from the Start > Programs menu.
A list of the applications protected in the project appears. The values under
Metered indicates whether or not the application has a demo counter or
metered options associated with it.
For example, you can make a demo application inactive so that it must
be activated in the field.
Note: Because the override is on a per key basis, if you make a change to the activation status, it
will affect ALL keys programmed in the batch. Make key utility only reads the design and
does not allow you to modify it.
8. Click Program Key. The Make Keys Utility programs the key(s) with
the protection strategy you defined.
3. Connect the key you want to program to the appropriate port on your
workstation. See “Connecting the Keys” on page 235 for more infor-
mation.
Tip: A check mark must appear in the box for the application to be selected; if the check mark
does not appear, the application will not be programmed onto the key. Be sure to select the
check box and not just the application name.
7. Repeat steps 5 and 6 for each application you want the distributor to
be able to activate and update.
8. Click Program Key. The Make Keys Utility programs the key with the
protection strategy you defined.
10. Repeat steps 3 through 9 until all distributor keys have been pro-
grammed.
Note: To determine if a programming failure is due to a software error or a hardware error, try
programming another key with the same strategy. If the programming is successful, the pre-
vious error was hardware-related. If you try programming many keys, and all of them fail
programming, the error is software-related. Refer to Appendix A, “Troubleshooting,” on
page 373 for help, or contact SafeNet Inc. Technical Support for additional assistance.
• Total: The total number of keys you have programmed during this
session, whether they passed or failed.
• Elapsed Time: The amount of time it took to program the last key.
These statistics are not project-specific—even if you program multiple keys
with multiple project files (protection strategies), the statistics do not reset
until you exit the Make Keys Utility and start it again with a new session.
To reset the statistics without closing and restarting the Make Keys Utility,
click Reset Statistics.
You also need to provide these users with the Sentinel SuperPro distributor
project file (.DST) containing the protection strategy for the application they
will be providing field activation for.
• From the Start menu, point to Programs > SafeNet Sentinel >
SuperPro > 6.5> Tools, then select License Generator Utility.
• Double-click the LicenseGenUtil.exe file icon.
Note: If you did not use the Sentinel SuperPro setup program to install the License Generator Util-
ity, it will not be accessible from the Start > Programs menu.
1. If you are using a distributor key, connect the key to the appropriate
port.
2. From the File menu, select Import .DST File (if you are a distributor)
or Open (if you are a developer). The Open dialog box appears.
4. Under Input, in the Locking Code field, enter the locking code pro-
vided by your customer.
• If you copied the locking code to the clipboard, click the paste
button to paste the code in the field.
• If the locking code was saved to a file (.LOC), click the open button
to locate and open the file. The code is entered in the field
automatically.
The developer ID and serial number of the key the code was generated
from appears in the corresponding fields.
5. Under Output, in the Action list, select the action(s) you want to per-
form on the customer’s key.
Note: Only selected actions (identified with a check mark) are added to the license code’s script.
Remember, actions determine what elements of the application will be activated or
upgraded. For more information about actions, see Chapter 9, “Defining Field Activation
Actions,” on page 221.
Assume you have two commands that operate on the same cell. One
command must be executed before the other because the second com-
mand expects the cell to be in a state set by the first command. In this
case, you should not randomize commands.
given action set, even if the locking code is the same. Non-randomized
commands produce the same license code every time for any given
locking code and action set.
7. Select the Log Activity check box to create a log file (LicenseGen.log)
containing all the license codes you generate.
• To save the license code to a file, click the save button and
select a file name and location for the license code file.
10. Refer to “Sending the License Code to Your Customer” on page 277 for
instructions on sending the license code to your customer.
Warning! DO NOT send your customers the Sentinel SuperPro project (.SPP) containing the pro-
tection strategy for the application they purchased.
• If you are a developer, from the Start menu, point to Programs >
SafeNet Sentinel > SuperPro > 6.5> Tools, then select Field
Exchange Utility.
• If you are a user, double-click the FieldExUtil.exe file icon.
Note: Because the Field Exchange Utility is designed for use by end users, the instructions in the
following two sections are written as if they are being read by an end user. You may want to
reproduce these sections and send them to your customers as part of your product’s docu-
mentation if you will be providing them with the Field Exchange Utility.
You must communicate the locking code to the software provider as they
have instructed (for example, via fax or e-mail). The provider will then give
you a corresponding license code to enter into the Field Exchange Utility.
To generate a locking code for a key:
2. Click Get Locking Code. The locking code appears in the top field.
If the message “Error” appears in the top field, make sure the key is
firmly attached to the port and try again.
• Click the save button to save the locking code to a file. Define a
location and file name for the file, then click Save.
• Write down the code exactly as it appears in the field.
4. Send the locking code to the software provider as directed.
5. Wait to continue the update process until you have received the license
code from your software provider.
You can leave the Field Exchange Utility open, or you may close it.
Either way, the license code you receive will update your key correctly.
2. Verify the correct key is attached to your computer or server. Only one
hardware key should be attached to your computer during the update
process.
Note: If you are updating a key on a server, you must remove all other keys, leaving only the one
you are updating. Only one key should be attached to the server during the update process.
Because removing keys may terminate the application on some client systems, you may want
to perform key updates only during non-peak hours.
3. In the field above the Update License button, enter the license code
given to you by your software provider. Do one of the following:
• Click the paste button to paste the code from the clipboard, if
it was placed there.
• Click the open button to load the code from a file. Browse to
locate the file (.LIC), then click Open.
• Type the code in the field. Be sure to enter it exactly as it was
provided.
4. Click Update License. The key update process begins; it may take up
to two or three minutes to complete the process.
The application is now ready to use, and you should have access to the
additional licenses or new features you purchased.
Note: If the update process is not successful, verify the key is securely attached to your computer
and try again. If the process is still unsuccessful, or you do not have access to the upgrades
you purchased when the process is complete, contact your software provider for assistance.
4. Format the API packet that you previously declared using the
RNBOsproFormatPacket function call.
7. Add code to check for the presence of the key using the
RNBOsproFindFirstUnit function call.
9. Now you can use other SuperPro API functions, such as RNBOspro-
Query, RNBOsproRead, etc. as appropriate for the protection scheme
you have designed.
Note: The exact name of the API functions may be different that those listed
above, depending on the interface you are using.
Also, make sure you call a SuperPro API function, such as RNBOsproQuery
or RNBOsproRead, at least once every 90 seconds after obtaining a license.
This will provide the application heartbeat so that the server keeps the
license allocated to the application. See “Maintaining the License” on
page 109 for more information.
For additional information about using API functions in your protection
strategy, refer to Chapter 3, “Designing Your Protection Strategy,” on page
59. Also, for information about setting the application’s access mode
through code, see “Setting the Access Mode” on page 103.
Tip: Sample code can be found in the pseudocode generated during the Proto-
type stage. See “Viewing the Pseudocode” on page 211 for more informa-
tion.
Packet Definition
typedef RB_DWORD RB_SPRO_APIPACKET[SPRO_APIPACKET_SIZE/
sizeof (RB_DWORD)];
typedef RB_WORD SP_STATUS;
typedef RBP_VOID RBP_SPRO_APIPACKET;
RNBOsproActivate
This function activates an inactive algorithm at the specified cell address.
■ You can call this function anytime after obtaining a license.
■ An error will be returned if:
RBP_SPRO_APIPACKET thePacket,
RB_WORD writePassword,
RB_WORD activatePassword1,
RB_WORD activatePassword2,
RB_WORD address );
Parameters
Name Direc- Parameter Type Description
tion
thePacket IN RBP_SPRO_APIPACKET A pointer to the API
packet defined on
page 305.
writePassword IN RB_WORD The write password for
the key.
activatePassword1 IN RB_WORD The first word of the
activation password.
activatePassword2 IN RB_WORD The second word of the
activation password.
address IN RB_WORD The address of the first
word of an inactive
algorithm.
Return Values
If successful, the function returns SP_SUCCESS. If an error occurs, the func-
tion returns one of the codes listed in the section “API Status Codes” on
page 352.
Additional Information
For more information about using RNBOsproActivate, see “Using Activation
Passwords” on page 79.
RNBOsproCleanUp
This function releases the memory resources acquired by the SuperPro cli-
ent library.
Format
Parameters
None
Return Values
None
Additional Information
You can call this function immediately after calling
RNBOsproReleaseLicense.
RNBOsproDecrement
This function is used to decrement a counter word by one.
Note: If the counter is associated with an active algorithm, and the counter is
decremented to 0, the associated algorithm is made inactive.
Format
RBP_SPRO_APIPACKET thePacket,
RB_WORD writePassword,
RB_WORD address );
Parameters
Name Direc- Parameter Type Description
tion
thePacket IN RBP_SPRO_APIPACKET A pointer to the API
packet defined on
page 305.
writePassword IN RB_WORD The write password for
the SuperPro key.
address IN RB_WORD The address of the
counter to decrement.
Return Values
If successful, the function returns SP_SUCCESS. If an error occurs, the func-
tion returns one of the codes listed in the section “API Status Codes” on
page 352.
Additional Information
For more information about using RNBOsproDecrement, see “Controlling
Demo Applications” on page 94.
RNBOsproEnumServer
This function enumerates the number of Sentinel Protection Servers run-
ning in the subnet for the developer ID specified.
Format
ENUM_SERVER_FLAG enumFlag,
RB_WORD developerId,
NSPRO_SERVER_INFO *serverInfo,
RBP_WORD numServerInfo );
Parameters
Name Direc- Parameter Type Description
tion
enumFlag IN ENUM_SERVER_FLAG The flag used for contacting
any of the following:
❑ NSPRO_RET_ON_FIRST_AVA
ILABLE (first-found Senti-
nel Protection Server that
has a license to offer).
❑ NSPRO_RET_ON_FIRST
(first-found Sentinel Pro-
tection Server that may
have a license).
❑ NSPRO_GET_ALL_SERVERS
(all the Sentinel Protection
Servers in the subnet).
developerId IN RB_WORD The developer ID of the
SuperPro key to find. The
Sentinel Protection Servers
running on the system having
a key of matching developer
ID ONLY will respond. If
developer ID is specified as
0xFFFF, then all the Sentinel
Protection Servers (for a
specified protocol) will
respond.
serverInfo OUT NSPRO_SERVER_INFO A pointer to a buffer that will
contain the Sentinel
Protection Server
information, such as the
system address and the
number of licenses available.
A developer needs to allocate
memory for the buffer.
Return Values
If an error occurs, the function returns one of the error codes listed in the
section “API Status Codes” on page 352.
Additional Information
For more information about using RNBOsproEnumServer, see “Finding
Additional Servers” on page 107.
RNBOsproExtendedRead
This function reads the word and access code at the specified address. On
success, the data variable contains the information from the SuperPro key
and the access code variable contains the access code.
Format
RBP_SPRO_APIPACKET thePacket,
RB_WORD address,
RBP_WORD data,
RBP_BYTE accessCode );
Parameters
Name Direction Parameter Type Description
thePacket IN RBP_SPRO_APIPACKET A pointer to the API packet
defined on page 305.
address IN RB_WORD The address to be read.
data OUT RBP_WORD A pointer to the variable
that will contain the data
read from the key.
accessCode OUT RBP_BYTE A pointer to the variable
that will contain the access
code associated with the
word that was read.
Return Values
If successful, the function returns SP_SUCCESS. If an error occurs, the func-
tion returns one of the codes listed in the section “API Status Codes” on
page 352.
Additional Information
If an attempt is made to read a non-readable word or algorithm/hidden
word, the SP_ACCESS_DENIED error will be returned. For security reasons,
algorithm words cannot be read.
RNBOsproFindFirstUnit
This function finds the first SuperPro key with the specified developer ID and
obtains a license, if available.
If RNBOsproFindFirstUnit is called with an API packet that already has a
license, gives Success.
Format
RBP_SPRO_APIPACKET thePacket,
RB_WORD devleoperID );
Parameters
Name Direction Parameter Type Description
thePacket IN RBP_SPRO_APIPACKET A pointer to the API
packet defined on
page 305.
developerID IN RB_WORD The developer ID of the
Sentinel SuperPro key to
find.
Return Values
If successful, the function returns SP_SUCCESS. If an error occurs, the func-
tion returns one of the codes listed in the section “API Status Codes” on
page 352.
Additional Information
For more information about using RNBOsproFindFirstUnit, see “Dealing
With Missing Hardware Keys” on page 82.
RNBOsproFindNextUnit
This API finds the next SuperPro key based on the developer ID maintained
in the RB_SPRO_APIPACKET structure.
■ This function should be called when RNBOsproFindFirstUnit has
returned the NO_LICENSE_AVAILABLE error.
■ If RNBOsproFindNextUnit returns success, the application will
release the license obtained by the RNBOsproFindFirstUnit API call
and will contain the data for the next SuperPro key. However, if the
function returns an error, the RB_SPRO_APIPACKET structure will
be marked invalid. To re-initialize the structure, use
RNBOsproFindFirstUnit and optionally, RNBOsproFindNextUnit
depending on the number of SuperPro keys found.
Format
RBP_SPRO_APIPACKET thePacket );
Parameters
Name Direction Parameter Type Description
thePacket IN RBP_SPRO_APIPACKET A pointer to the API
packet defined on
page 305.
Return Values
If successful, the function returns SP_SUCCESS. If an error occurs, the func-
tion returns one of the codes listed in the section “API Status Codes” on
page 352.
RNBOsproFormatPacket
This function initializes and validates the API packet based on its size.
Format
RB_WORD packetSize);
Parameters
Return Values
If successful, the function returns SP_SUCCESS. If an error occurs, the func-
tion returns one of the codes listed in the section “API Status Codes” on
page 352.
Additional Information
You must call this function once before calling any other SuperPro API
function.
RNBOsproGetContactServer
This function returns the access mode set to obtain a license.
Format
RBP_SPRO_APIPACKET thePacket,
RBP_CHAR serverNameBuf,
RB_WORD serverNameBufSz );
Parameters
Name Direc- Parameter Type Description
tion
thePacket IN SPP_SPRO_APIPACKET A pointer to the API
packet defined on
page 305.
serverNameBuf OUT RBP_CHAR A pointer to the buffer
in which the Sentinel
Protection Server name
is copied. Memory
needs to be allocated
for the buffer.
serverNameBufSz IN RB_WORD The length of the
buffer. The maximum
length recommended
is 64 bytes.
Return Values
If successful, the function returns SP_SUCCESS. If an error occurs, the func-
tion returns one of the codes listed in the section “API Status Codes” on
page 352.
Additional Information
■ You can call this function anytime after successfully calling
RNBOsproFindFirstUnit.
■ You could call this function in order to know from where the license
was issued to your application. For example, you can display the
Sentinel Protection Server name via some command in your user
interface so that the user is aware of which system was contacted to
obtain a license.
RNBOsproGetFullStatus
This function obtains the return code of the last-called API function.
Format
RBP_SPRO_APIPACKET thePacket );
Parameters
Name Direction Parameter Type Description
thePacket IN RBP_SPRO_APIPACKET A pointer to the API
packet defined on
page 305.
Return Values
If successful, the function returns the status of the last-called API function.
If an error occurs, the function returns one of the error codes listed in the
section “API Status Codes” on page 352.
Additional Information
■ This function is provided for support purposes only. It returns an
RB_WORD value that can be interpreted by the Technical Support.
■ You can call this function anytime after obtaining a license.
RNBOsproGetHardLimit
This function retrieves the hard limit of the key from which the license was
obtained.
Format
RBP_SPRO_APIPACKET thePacket,
RBP_WORD hardLimit );
Parameters
Name Direction Parameter Type Description
thePacket IN RBP_SPRO_APIPACKET A pointer to the API packet
defined on page 305.
hardLimit OUT RBP_WORD A pointer to the location
that holds the hard limit of
the key. It defines the
maximum number of
licenses that can be issued
by this key.
Return Values
If successful, the function returns SP_SUCCESS. If an error occurs, the func-
tion returns one of the codes listed in the section “API Status Codes” on
page 352.
Additional Information
You can call this function anytime after obtaining a license.
RNBOsproGetKeyInfo
This function retrieves the following information about the key attached on
a stand-alone system or a network computer (where the Sentinel Protection
Server is running):
■ Developer ID
■ Hard limit
■ Licenses in-use
■ Licenses timed-out
■ Highest number of licenses used
RNBOsproGetKeyType
This function returns the following information about the key attached to a
system:
■ Key Family
The key family parameter will return 0 or 1, where 0 denotes the
SuperPro keys (the SSP keys) and 1 denotes the UltraPro keys (the
SUP keys).
■ Form Factor
The form factor parameter will return 0 or 1, where 0 denotes the
parallel keys and 1 denotes the USB keys.
■ Memory Size
The number of cells (inclusive of the reserved cells).
Format
RBP_SPRO_APIPACKET thePacket,
RBP_WORD KeyFamily,
RBP_WORD KeyFormFactor,
RBP_WORD KeyMemorySize );
Parameters
Name Direc- Parameter Type Description
tion
thePacket IN RBP_SPRO_APIPACKET A pointer to the API
packet defined on
page 305.
KeyFamily OUT RBP_WORD A pointer to an integer
value that represents the
key's family.
KeyFormFactor OUT RBP_WORD A pointer to an integer
value that represents the
key's form factor.
KeyMemorySize OUT RBP_WORD A pointer to an integer
value that represents the
number of cells in the
key.
Return Values
If successful, the function returns SP_SUCCESS. If an error occurs, the func-
tion returns one of the codes listed in the section “API Status Codes” on
page 352.
Additional Information
You can call this function anytime after obtaining a license.
Format
RBP_SPRO_APIPACKET thePacket,
RB_WORD devId,
RB_WORD keyIndex,
NSPRO_MONITOR_INFO *nsproMonitorInfo );
Parameters
Name Direc- Parameter Type Description
tion
thePacket IN RBP_SPRO_APIPACKET A pointer to the API
packet defined on
page 305.
devId IN RBP_WORD If 0xFFFF is specified,
the function will
return the developer
ID of the key along
with other
information.
keyIndex IN RBP_WORD The index of the key
whose information
is sought.
❑ For cascaded par-
allel port keys:
The sequential
position of the
key in the queue.
❑ For multiple USB
Keys: The order
in which the key
is plugged into
the USB port/
hub.
nsproMonitorInfo OUT NSPRO_MONITOR_INFO A pointer to the
nsproMonitorInfo
structure. This
structure has various
fields that contain
information about
the key. Refer to
spromeps.h for
details.
Return Values
If an error occurs, the function returns one of the error codes listed in the
section “API Status Codes” on page 352.
Additional Information
You can call this function anytime after obtaining a license.
RNBOsproGetSubLicense
This function obtains a sublicense from a locked data word (has an access
code 1).
You can call the RNBOsproGetSubLicense function only after calling the
RNBOsproFindFirstUnit function.
Note: The key’s hard limit is decremented first, then the sublicense limit is decre-
mented for the requested application.
Format
RBP_SPRO_APIPACKET thePacket,
RB_WORD address );
Parameters
Name Direction Parameter Type Description
thePacket IN RBP_SPRO_APIPACKET A pointer to the API packet
defined on page 305.
address IN RB_WORD The cell address of a locked
data word from which the
sublicense will be obtained.
Return Values
If successful, the function returns SP_SUCCESS. If an error occurs, the func-
tion returns one of the codes listed in the section “API Status Codes” on
page 352.
Additional Information
For more information about using RNBOsproGetSubLicense, see “Getting a
Sublicense” on page 111.
RNBOsproGetVersion
This function returns the Sentinel system driver's version and type.
Format
RBP_SPRO_APIPACKET thePacket,
RBP_BYTE majVer,
RBP_BYTE minVer,
RBP_BYTE rev,
RBP_BYTE osDrvrType );
Parameters
Name Direction Parameter Type Description
thePacket IN RBP_SPRO_APIPACKET A pointer to the API
packet defined on
page 305.
majVer OUT RBP_BYTE A pointer to the location
for the major version
number returned.
minVer OUT RBP_BYTE A pointer to the location
for the minor version
number returned.
rev OUT RBP_BYTE A pointer to the location
for the revision number
returned.
Return Values
If successful, the function returns SP_SUCCESS. If an error occurs, the func-
tion returns one of the codes listed in the section “API Status Codes” on
page 352.
Additional Information
You can call this function anytime after obtaining a license.
RNBOsproInitialize
This function initializes the API packet and sets the values specified (if any)
in the configuration file or the NSP_HOST environment variable.
Format
RBP_SPRO_APIPACKET thePacket );
Parameters
Name Direction Parameter Type Description
thePacket OUT RBP_SPRO_APIPACKET A pointer to the API packet
defined on page 305.
Return Values
If successful, the function returns SP_SUCCESS. If an error occurs, the func-
tion returns one of the codes listed in the section “API Status Codes” on
page 352.
Additional Information
You must call this function immediately after RNBOsproFormatPacket.
RNBOsproOverwrite
This function is used to change the value and access code of a word at the
specified address. The word data is placed in the data variable and its associ-
ated access code in the access code variable.
Format
RBP_SPRO_APIPACKET thePacket,
RB_WORD writePassword,
RB_WORD overwritePassword1,
RB_WORD overwritePassword2,
RB_WORD address,
RB_WORD data,
RB_BYTE accessCode );
Parameters
Name Direc- Parameter Type Description
tion
thePacket IN RBP_SPRO_APIPACKET A pointer to the API
packet defined on
page 305.
writePassword IN RB_WORD The write password
for the SuperPro key.
overwritePassword1 IN RB_WORD The overwrite
password 1 for the
SuperPro key.
overwritePassword2 IN RB_WORD The overwrite
password 2 for the
SuperPro key.
address IN RB_WORD Contains the cell
address where write
is to be performed.
data IN RB_WORD Contains the word to
write in the key.
accessCode IN RB_BYTE Contains the access
code associated with
the word to write.
Return Values
If successful, the function returns SP_SUCCESS. If an error occurs, the func-
tion returns one of the codes listed in the section “API Status Codes” on
page 352.
Additional Information
■ On success, the data and its associated access code are written at the
specified address.
■ If wrong write password or overwrite passwords are specified, the
SP_ACCESS_DENIED error is returned.
■ This function can be used to overwrite any word on the SuperPro key
(with the exception of the reserved words).
RNBOsproQuery
This function is used to query an algorithm at the specified address.
The query data pointer will point to the first byte of the data to be passed to
the algorithm. The length of the query data (in bytes) is specified in the
length variable. The minimum length is 4 bytes and the maximum length is
56 bytes.
On success, the query response will be placed in the buffer pointed to by the
response pointer. It will have the same length as the query data. The last
four bytes of the query response will also be placed in the Response32
variable.
Note: It is the programmer’s responsibility to allocate the memory for the buff-
ers.
Format
RBP_SPRO_APIPACKET thePacket,
RB_WORD address,
RBP_VOID queryData,
RBP_VOID response,
RBP_DWORD response32,
RB_WORD length );
Parameters
Name Direction Parameter Type Description
thePacket IN RBP_SPRO_APIPACKET A pointer to the API
packet defined on
page 305.
address IN RB_WORD The address of the
word to query. It must
point to the first word
of an active algorithm.
Return Values
If successful, the function returns SP_SUCCESS. If an error occurs, the func-
tion returns one of the codes listed in the section“API Status Codes” on
page 352.
Additional Information
If the address is not the first word of an active algorithm, the return status
will be successful and the response buffer data will be the same as the query
buffer data.
For more information about using RNBOsproQuery, see the following:
■ “Using Activation Passwords” on page 79
■ “Advanced Protection Techniques” on page 85
■ “Querying Counters” on page 99
RNBOsproRead
This function reads a word at the specified address. If successful, the data
variable will contain the word value.
Format
RBP_SPRO_APIPACKET thePacket,
RB_WORD address,
RBP_WORD data );
Parameters
Name Direction Parameter Type Description
thePacket IN RBP_SPRO_APIPACKET A pointer to the API
packet defined on
page 305.
address IN RB_WORD The cell address to be
read.
data OUT RBP_WORD A pointer to the
variable that will
contain the data read
from the key.
Return Values
If successful, the function returns SP_SUCCESS. If an error occurs, the func-
tion returns one of the codes listed in the section “API Status Codes” on
page 352.
Additional Information
If an attempt is made to read a non-readable word or algorithm/hidden
word, the SP_ACCESS_DENIED error will be returned. For security reasons,
algorithm words cannot be read.
RNBOsproReleaseLicense
This function can be used to either release a license or sublicense(s).
Format
RBP_SPRO_APIPACKET thePacket,
RB_WORD address,
RBP_WORD numSubLic);
Parameters
Name Direction Parameter Type Description
thePacket IN RBP_SPRO_APIPACKET A pointer to the API
packet defined on
page 305.
address IN RB_WORD Specify zero to release
the main license. Else,
specify the cell address
to release the
sublicense from a
particular cell.
numSubLic IN/OUT RBP_WORD The pointer to the
variable containing the
number of sublicenses
to be released. If the
main license is to be
released, this can be
specified as null.
Return Values
If successful, the function returns SP_SUCCESS. If an error occurs, the func-
tion returns one of the codes listed in the section “API Status Codes” on
page 352.
Additional Information
■ You can call this function anytime after obtaining a license; followed
by RNBOsproCleanUp.
■ You can call this function before your application terminates. For
example, the handler of the exit command button in your user
interface can make use of this function.
■ We recommend you to use this function in order to release the idle
licenses for other clients in queue. This function is especially useful in
cases where you have set the heartbeat interval as infinite. The
Sentinel Protection Server will not release the license unless you call
this function.
RNBOsproSetContactServer
This function sets the access mode for finding the key.
You may also set this function to the IP or IPX address, NetBEUI name or
name of the system where the Sentinel Protection Server is running.
Format
RBP_SPRO_APIPACKET thePacket,
RBP_CHAR serverName );
Parameters
Name Direction Parameter Type Description
thePacket IN RBP_SPRO_APIPACKET A pointer to the API
packet defined on
page 305.
serverName IN RBP_CHAR A pointer to the location
that contains one of the
following values:
❑ RNBO_STANDALONE
❑ RNBO_SPN_DRIVER
❑ RNBO_SPN_LOCAL
❑ RNBO_SPN_BROADCAS
T
❑ RNBO_SPN_ALL_MODE
S
❑ RNBO_SPN_SERVER_MO
DES
❑ IP address, IPX address,
NetBEUI name or the
workstation name.
However, the name
length cannot exceed
63 single-byte charac-
ters.
Return Values
If successful, the function returns SP_SUCCESS. If an error occurs, the func-
tion returns one of the codes listed in the section “API Status Codes” on
page 352.
Additional Information
■ You can call this function before calling RNBOsproFindFirstUnit. This
function will not work if the packet already has a license and will
return the SP_INVALID_OPERATION error code.
RNBOsproSetHeartBeat
This function sets the heartbeat interval for maintaining the communica-
tion between a client and the Sentinel Protection Server. The heartbeat time
can be set to INFINITE_HEARTBEAT or from 1 minute to 30 days, in multi-
ples of 1 second.
The heartbeat represents the interval within which your application notifies
the Sentinel Protection Server that it is still running. If this function is not
called, the protection server assumes the default value as two minutes (120
seconds). As a result, if no call is made to the key at least every two minutes,
the license will be released and the SP_INVALID_LICENSE error will be
returned if any call is made using the same packet.
Format
RBP_SPRO_APIPACKET thePacket,
RB_DWORD heartBeatValue );
Parameters
Name Direction Parameter Description
Type
thePacket IN RBP_SPRO_ A pointer to the API packet
APIPACKET defined on page 305.
heartBeatValue IN RB_DWORD A value that represents time in
seconds. The valid values are:
❑ LIC_UPDATE_INT = 120
❑ MAX_HEARTBEAT = 2592000
❑ MIN_HEARTBEAT = 60
❑ INFINITE_HEARTBEAT =
0xFFFFFFFF
Return Values
If successful, the function returns SP_SUCCESS. If an error occurs, the func-
tion returns one of the codes listed in the section “API Status Codes” on
page 352.
Additional Information
■ You should call this function after calling RNBOsproFindFirstUnit.
■ Alternatively, your customers can set the heartbeat interval in the
configuration file you shipped them. However, the time specified in
RNBOsproSetHeartBeat will always override the value specified in the
configuration file.
When the heartbeat time interval set is too low and there is congestion on
the network, then the application can terminate even before contacting the
protection server. To avoid such a situation, you may want to specify a
longer heartbeat interval. However, if infinite heartbeat set, then the protec-
tion server will never release the license unless RNBOsproReleaseLicense is
called.
RNBOsproSetProtocol
This function sets the network protocol for allowing communication
between the client and Sentinel Protection Server. You can choose from the
following protocols: NetBEUI, TCP/IP, and IPX. By default, TCP/IP is used.
Format
RBP_SPRO_APIPACKET thePacket,
PROTOCOL_FLAG protocol );
Parameters
Name Direc- Parameter Type Description
tion
thePacket IN RBP_SPRO_APIPACKET A pointer to the API packet
defined on page 305.
protocol IN PROTOCOL_FLAG The protocol chosen by a
client for communication
with the Sentinel Protection
Server. The valid values are:
❑ NSPRO_TCP_PROTOCOL
=1
❑ NSPRO_IPX_PROTOCOL =
2
❑ NSPRO_NETBEUI_PROTOC
OL = 4
Return Values
If successful, the function returns SP_SUCCESS. If an error occurs, the func-
tion returns one of the codes listed in the section “API Status Codes” on
page 352.
Additional Information
■ This function can be called after successfully calling
RNBOsproInitialize and before calling RNBOsproFindFirstUnit.
■ This function will not work if the packet already has a license and will
return the SP_INVALID_OPERATION error code.
■ Alternatively, your customers can set the network protocol in the
configuration file you ship to them. However, a protocol set using the
RNBOsproSetProtocol function will always override the value
specified in the configuration file.
RNBOsproCheckTerminalService
This function allows you to enable/disable the application execution on ter-
minal clients while RNBOsproFindFirstUnit, or RNBOsproFindNextUnit API
is executed.
This function shall be called before RNBOsproFindFirstUnit if the user wants
to enable the support for Terminal Client.
Format
SP_STATUS SP_API
RNBOsproCheckTerminalService (
SP_OUT thePacket,
RB_WORD termserv);
Parameters
Return Code
If successful, the function returns SP_SUCCESS. If an error occurs, the func-
tion returns one of the codes listed in the section “API Status Codes” on
page 352.
Additional Information
■ This API function should be called after calling the
RNBOsproFormatPacket and RNBOsproInitialize API functions and
before calling the RNBOsproFindFirstUnit API function.
■ When calling RNBOsproFindFirstUnit or RNBOsproFindNextUnit
API, it will act according to the following rules:
❑ If RNBOsproCheckTerminalService is not called:
❑ If RNBOsproCheckTerminalService is called:
RNBOsproSetSharedLicense
This function allows you to enable/disable the main and sublicense sharing.
The licenses issued to users from the same seat (a user name and MAC
address combination) are shared.
Format
Parameters
Name Direction Parameter Type Description
thepacket IN RBP_SPRO_APIPACKET A pointer to the API
packet defined on
page 305.
shareMainLic IN RB_WORD Enables/disables the
main license sharing.
Use any of the
following constants:
❑ SP_ENABLE_MAINLIC
_SHARING (enables
main license shar-
ing)
❑ SP_DISABLE_MAINLIC
_SHARING (disables
main license shar-
ing)
By default, main license
sharing is enabled.
shareSubLic IN RB_WORD Enables/disables the
sublicense sharing. Use
any of the following
constants:
❑ SP_ENABLE_SUBLIC_S
HARING (enables
sublicense sharing)
❑ SP_DISABLE_SUBLIC_S
HARING (disables
sublicense sharing)
By default, sublicense
sharing is disabled.
Return Values
If successful, the function returns SP_SUCCESS. If an error occurs, the func-
tion returns one of the codes listed in the section “API Status Codes” on
page 352.
Additional Information
You can call this function before calling RNBOsproFindFirstUnit.
RNBOsproWrite
This function is used to write a word and its associated access code at the
specified address. The word data is placed in the data variable and its associ-
ated access code in the access code variable.
Format
RBP_SPRO_APIPACKET thePacket,
RB_WORD writePassword,
RB_WORD address,
RB_WORD data,
RB_BYTE accessCode );
Parameters
Name Direction Parameter Type Description
thePacket IN RBP_SPRO_APIPACKET A pointer to the API
packet defined on
page 305.
Return Values
If successful, the function returns SP_SUCCESS. If an error occurs, the func-
tion returns one of the codes listed in the section “API Status Codes” on
page 352.
Additional Information
■ You can use this function to overwrite words with access code 0. To
overwrite words with other access codes, use the RNBOsproOverwrite
function.
■ If the write password was incorrect, or an attempt was made to
overwrite a locked word, the SP_ACCESS_DENIED error will be
returned.
Note: This chapter is meant for Linux users ONLY. If you are a Windows user, refer to other
chapters of the Developer’s Guide.
The Linux Platform of Sentinel SuperPro brings the popular Sentinel key
based-protection to a wide community of Linux developers—allowing them
to safeguard and control the use of their applications.
The network support that was added in the last release allowed multiple cli-
ents across the network to access a SuperPro key concurrently with the
Sentinel Protection server. You can even remotely activate inactive applica-
tions or enable selective features using the Field Exchange utility. This
release introduces the following:
■ The Sentinel UNIX Driver for parallel port supports communication
with the parallel form factor of the SuperPro key.
■ USB daemon supports communication with the USB form factor of the
SuperPro and SuperPro XM keys. Refer to Chapter -2 “Using the
Hardware Key” on page 19 for more information on SuperPro XM Key.
Apart from discussing these features, the following topics are also covered:
Tip: The APIs and various programs/utilities referred within this chapter, such as the Sentinel Pro-
tection server, Field Exchange, Sentinel License Monitor, are functionally similar to the Win-
dows components, unless stated otherwise. Therefore, developers who are already familiar
with the Windows version of the software will find it quick and easy to learn about the Linux
version of Sentinel SuperPro. First-time developers are recommended to begin with the Senti-
nel SuperPro Developer’s Guide for Windows.
A daemon has been provided to allow accessing the USB keys i.e. SuperPro
and SuperPro XM attached to the USB port. Refer to section “Installing the
USB Hardware Key” on page 55 for details.
Sublicensing
The Sentinel Protection Server now provides sharing of seat license
requested from the same user or machine. Refer to the section on “Subli-
censing” on page 12 for details.
Cancelling a License
If desired, the user can cancel the licenses issued to the clients from a key.
This need might arise in situations when some other privileged client needs
a license or an application terminates without releasing the license
acquired. The Sentinel License Monitor does not prompt users for any errors
encountered while canceling a license. However, a license will not be can-
celed if there is excessive traffic in the network or a wrong password is
specified. For more information on cancelling a license, refer to the Sentinel
SuperPro System Administrator’s Help.
Note: The Sentinel Protection server for Linux only supports the TCP/IP protocol.
File Description
/protection_install.sh Script to install the Sentinel Protection Installer’s all
four components.
/protection_uninstall.sh Script to uninstall the Sentinel Protection Installer’s
all four components.
/driver/drvr_install.sh Script to install the Sentinel UNIX Driver
components.
/driver/drvr_uninstall.sh Script to uninstall the Sentinel UNIX Driver
components.
/driver/sntl-sud-7.1.0-0.i386.rpm Script to install the parallel and/or USB port driver
components.
/server/sntl-server-7.1.0-0.i386.rpm Script to install the Sentinel Protection Server.
/licenseagreement.txt Stores legal agreement between the software seller
and the buyer.
/ReadMe.pdf Provides an overview of the Sentinel Protection
Installer, its installation and a few tips on using the
related components.
*For platform-independent field activation, ensure that you follow the same configu-
ration settings—and not only the same secret code—on Windows and Linux to have
identical SAFE objects.
Getting Started
Sentinel SuperPro on Linux does not provide you with a Toolkit as in the
Windows version. However, the Windows Toolkit itself can be used to per-
form similar actions on the SuperPro key. Your actions to protect an
application can be divided into four parts as described below:
Note: For detail on the procedures and concepts for using the Toolkit, refer to Chapter 5‚ ”Starting
the Sentinel SuperPro Toolkit”.
2. If starting the Toolkit for the first-time, you need to enter the devel-
oper-specific details, as your passwords are remembered for subse-
quent sessions. Even if you don’t enter them, the toolkit still allows you
to continue, up through the Prototyping stage after which entering
the Developer ID, Write Password, and Overwrite Passwords 1 and 2 is
Note: In case you did not enter the Developer ID, Write Password and the Overwrite Passwords 1
and 2 in the developer configuration dialog box, at the time of saving your project you will
get a message stating: “You must specify the secret code, the spp file can not be saved, first
complete the developer configuration in the project stage“. Complete the developer
configuration and then proceed further.
Note: Before you create the first element in your protection strategy, you need to decide whether
you will be using SuperPro XM or SuperPro keys for your design. When you click on one of
the buttons in the “Add element” group, you will be asked to specify whether the design
will be used with SuperPro XM or SuperPro keys. Alternatively, you can specify SuperPro XM
keys by clicking on the “Enable SuperPro XM Features” check box in the lower right-
hand corner before creating the first element.
4. Assign a name and comment for your application. This name will be
shown in the Element List View. Click Next.
5. From the Address drop-down list, select the address of the cell you
want the first word of the element to be placed in. If the location is
unimportant to you, select Auto to allow the Toolkit to select a loca-
tion for you.
8. In the next screen, you are required to specify an activation type for
your application. You can choose any of the following activation types:
active, static, trusted or distributed. Refer to the section “Activation
Types” on page 63 to learn more about each activation type. Note that
a Linux application in the field can only be activated using the Field
Exchange utility. Support for the Sentinel Client Activator is not pro-
vided for the SuperPro Linux release. Clicking Next will bring you
back to the Element List View, where you find your element added in
the list.
9. Now, navigate to the Prototype stage. Click Go. This will: program a
master key, generate query/response pairs, define default actions for
remote activation. More commands for field activation can be added in
the Implementation stage.
11. If you wish to allow remote activation for your application in the field,
you must define the field activation commands. Click the Field Acti-
vation tab. Refer to Chapter 9, “Defining Field Activation Actions” on
page 221 for exact procedure.
12. Once you are finished with the Implementation stage, you can pro-
ceed to make your product and distributor keys in the Make Keys
stage. Refer to Chapter 10,“Programming Keys” on page 233 for
detailed information.
Note: Ensure that you also link your application with the pthread system library along with the
SuperPro client library.
Warning! Each time you modify your configuration settings, a new pair of USAFE and DSAFE
objects is reproduced. However, to serve your applications already in the field, you
must make a backup of objects corresponding to the existing settings.
Note: The command-line switches given below are for bash Shell.
Action Switch
To run the Sentinel Protection server spnsrvlnx
To generate the log file -l < log file name >
To generate the error file. -f < error file name >
To view the Help -h
To display the server messages (the default -m 1
setting)
To hide the server messages -m 0
1. Firstly, obtain the PCI parallel port address from the /proc/pci file. Only
2. Now, edit the rc.local file available at the /etc/rc.d/rc.local path. The
entry: insmod –f /opt/sentinel/sud/parallal/mdrbdr.o
should be modified to: insmod –f /opt/sentinel/sud/paral-
lal/mdrbdr.o address=<address>.
The address of the I/O port was obtained in step 1. For example, ins-
mod –f /opt/sentinel/sud/parallal/mdrbdr.o
address=0xdcf8 will check the 0xdcf8 port.
3. Now, reboot the computer to apply the settings. Or, to access the key
right away, unload the driver using the rmmod mdrbdr command—
followed by reloading it using the following command: insmod –f //
opt/sentinel/sud/parallal/mdrbdr.o address=<address>.
Now, you are ready to access the key.
1. From the Start menu, select Settings > Control Panel. The Control
Panel window appears.
8. If any Sentinel SuperPro files are in use, the Files in Use screen
appears. Close any listed files, then click Retry.
Note: Depending on your operating system, you may need to reboot your system
at this point. You will be prompted if a reboot is required; if a message
appears, follow the on-screen instructions.
To completely remove Sentinel SuperPro files from your system, you should
also uninstall the following components:
■ Client Activator Wizard
Note: If you have more than one application that uses the Sentinel system driver
installed on your system, the Sentinel SuperPro uninstall process will not
uninstall the driver. The driver will be uninstalled only when the last appli-
cation using the driver is uninstalled. This holds true for the Sentinel Pro-
tection server also.
Also, the following files do not get automatically removed when you unin-
stall Sentinel SuperPro. You should delete these files manually to complete
the uninstallation process.
■ Log files generated by the Sentinel Protection server
■ Log files generated during key programming or license code
generation
■ Intermediate files created by compiling interfaces
■ Any Sentinel SuperPro project files (.SPP or .DST)
■ usafe32.dll and dsafe32.dll
1. From the Start menu, select Settings > Control Panel. The Control
Panel window appears.
Note: Depending on your operating system, you may need to reboot your system
at this point. You will be prompted if a reboot is required; if a message
appears, follow the on-screen instructions.
Question:
Is there a limit on the number of writes I can make to a cell?
Answer:
Making frequent writes to a cell can lead to premature key failure. For this
reason, SafeNet Inc. recommends limiting writes to a key to a reasonable
amount. For example, writing to any cell on a single key once every 10 sec-
onds, 8 hours a day leads to more than 2 million writes a year, which is too
many. Write to the key only when necessary; use other means—such as
querying or reading a cell—to verify the key is still attached and has not
been tampered with.
Question:
I receive an error if I attempt to encrypt more than 50 files when I apply a
shell to my application. How can I encrypt more than 50 files?
Answer:
When applying a shell, you can encrypt a maximum of 50 files at time. To
encrypt more than 50 files with an application using automatic (shelled)
protection, you need to create multiple application protection elements, all
of which use the same encryption seed. For example, if you need to encrypt
125 files, you will need to create three application protection elements using
automatic protection (50 + 50 + 25).
2. Specify the first 50 files you want to be encrypted at shell time. See
“Selecting Additional Files for Encryption” on page 170.
3. Write down the encryption seed you used for the first 50 files.
7. Enter the encryption seed you wrote down in step 3. You must use
the same encryption seed that you used for the first 50 files, if
you want the files to use the same encryption.
8. Repeat step 4.
9. Repeat steps 5 – 7 until you have specified all the files you want to
encrypt.
Note: While reading the following sections, keep in mind that even if an applica-
tion cannot be protected using automatic protection, it can always be pro-
tected using integrated protection instead.
Note: For a list of the compatible compilers and applications supported by Senti-
nel SuperPro, please see “Appendix B, “Compatible Compilers and Applica-
tions,” on page 393.
must clear the read-only attributes on the file properties sheet and run the
protection application again.
Question:
During key programming, I received a write failure message asking me to
enter my developer ID and passwords again. What happened?
Answer:
If you remove the key while it is being programmed, this message appears.
Verify the key is firmly connected to the appropriate port on the computer,
and that it is fully-seated in the port. An inadequate connection can cause
these types of errors.
Question:
A key failed the programming process. How can I tell if the error is software
or hardware related?
Answer:
To determine if a programming failure is due to a software error or a hard-
ware error, try programming another key with the same strategy.
If the programming is successful, the previous error was hardware-related.
If you try programming many keys, and all of them fail programming, the
error is software-related.
Question:
When I try to create a key prototype in the Prototype stage, or program a
key in the Make Keys stage, I get a message saying the server isn’t running.
What does this mean?
Answer:
The Sentinel Protection Server must be running to access the hardware key.
This includes any kind of key access operation, including creating a proto-
type or programming keys.
For server installation instructions, see “Installing the Sentinel Protection
Server” on page 250. For information about how to verify the server is run-
ning, see “Using the Field Exchange Utility” on page 282.
Question:
Why can’t my distributor activate applications or update keys using the
License Generator Utility?
Answer:
There are several possible reasons why a distributor could be having prob-
lems activating or updating applications.
■ His distributor key is not connected. The distributor must have
his distributor key connected in order to generate license codes for
applications using the distributed activation type. Verify that your
distributor has his distributor key appropriately and firmly connected.
■ The activation counter on his distributor key has reached
zero. If there are no more licenses to activate or update applications
left on the distributor key, your distributor will not be able to generate
license codes. You need to increment the activation counter on the
distributor’s key through field activation. See “Updating Distributor
Keys in the Field” on page 279 for instructions.
■ He is using an incorrect distributor key. The distributor key
connected to the workstation must be programmed with the Sentinel
SuperPro project the application was protected with. If your
distributors are responsible for activating multiple applications with
multiple keys, it is important that the correct key be connected when
attempting to generate license codes.
■ The wrong .DST file is being used. The .DST file opened in the
License Generator Utility must be the file that was created from the
same project you programmed the distributor key with, and protected
the application with. If the wrong .DST file is being used, license codes
cannot be generated.
■ The Sentinel Protection Server is not running. To use the
License Generator Utility, the Sentinel Protection Server must be
installed and running on the same workstation the distributor key is
connected to and the utility is being run on. Ask your distributor to
verify that the server is running, using the instructions found in
“Using the Field Exchange Utility” on page 282.
9 compatible
*
On local using 'NO-NET' mode on local machine user can take unlimited licenses with-
out sublicensing
From a remote sub-net machine only one network license available with no sublicenses
**
The zero hard-limit keys are treated as one hard-limit key.
In standalone mode user can run infinite number instances on his local machine.
In network mode the license(s) limit is defined by the hard-limit of the key.
In driver mode if the SuperPro/Sentinel Protection server/service is running on local
machine then number of license(s) available in driver mode is defined by hard-limit of
the key else it works similar to standalone mode. Also a single license is shared by n
applications running in driver mode if server is running.
***
The zero hard-limit keys are treated as one hard-limit key.
In standalone mode user can run infinite number instances on his local machine.
In network mode the license(s) limit is defined by the hard-limit of the key.
In driver mode if the SuperPro/Sentinel Protection server/service is running on local
machine then number of license(s) available in driver mode is defined by hard-limit of
the key else it works similar to standalone mode. Also a single license is shared by n
applications running in driver mode if server is running.
The concept of license or sublicensing sharing affects the consumption of hard limit in
driver and network mode.
Note: Applications that were protected using Sentinel SuperPro 6.0 can use 6.1
hardware keys only if version 5.39 of the Sentinel system driver is being
used. In this case, 6.1 hardware keys are viewed by the protected applica-
tion as stand-alone keys with a license limit of one.
Compatibility Requirements
The Sentinel SuperPro key operates on an IBM-compatible parallel port built
to Centronics standards. The key is completely transparent, allowing nor-
mal computer-printer communication.
The Sentinel SuperPro key’s circuitry inhibits the printer response on the
BUSY line from returning to the computer while the key is responding to a
command on the corresponding line. This prevents collisions on the
response line caused by simultaneous use by the printer and the key. Once
the key finishes processing the command, the printer’s response is
unblocked and allowed to pass through to the computer.
The Sentinel SuperPro key meets the electrical parameters for the logic cir-
cuits used in the IBM printer adapter card. If you encounter problems using
the key with other equipment, compatibility problems may be the cause.
Incompatible Connectors
Some computers otherwise compatible with the IBM specification include a
36-pin Centronics-type connector on the motherboard, rather than the
IBM-style DB-25 connector used with the Sentinel SuperPro key.
In this case, you need special printer cables to adapt the Sentinel SuperPro
key to the computer or the printer.
The table below lists the file types supported by Shell for encryption/
decryption:
Note: This appendix is meant for Windows users ONLY. If you are a Windows user, refer to other
appendices of the Developer’s Guide.
If you want to protect your application while you are still developing it, you
can use the Shell utility to easily “shell” your application after each build.
This utility is command line-based.
To use the Shell utility to add automatic (“shelled”) protection to your appli-
cation during the build process, add a batch file that calls an existing
Sentinel SuperPro project. The automatic protection options you set up and
saved in the SSP Toolkit are then used to shell your application during the
build process.
Note: A Sentinel SuperPro project file (*.spp) that defines the automatic (“shelled”) protection
options for the application(s) you want to shell must exist before you can use the Shell util-
ity. For more information about setting up automatic protection, see Chapter 6, “Protecting
Your Application,” on page 145.
where:
• ShellUtil is the name of the command line shell utility
• Project File is the name of the Sentinel SuperPro project file (*.spp)
you designed the application’s protection strategy in.
• [App 1] is the name of the application you want to shell, as it was
specified in the Sentinel SuperPro project.
More than one application may be shelled with the same command
See “Using the Shell Utility” on page 387 for more information.
Note: To use the Shell Utility, you need to program an active shell algorithm(s) based key using the
Toolkit.
Example
The following example shows how to use the Shell utility to apply automatic
protection to one or more applications.
Assume you have a Sentinel SuperPro project file named MyApps.spp. In this
project, you added three applications—ShapeEditor, SceneryEditor and
TextEditor.
You designed your protection strategy to use integrated protection for Shap-
eEditor, and automatic protection for SceneryEditor and TextEditor.
To shell SceneryEditor and/or TextEditor using the command line:
C:\SentinelSuperPro6\
If we had entered:
ShellUtil MyApps.spp
3. Press Enter. The applications are shelled via the command line.
API functions to source protection techniques 85– adding to source code 211–
code 211–214 94 214
commands 225 security settings 167 evaluating 213–214
counters 193–194 ainst.exe 272 in integrated protection 61
custom elements 188–200 Algorithm Counter Word invoking 128, 133
data words 195–197 (CW) 30 parameters 128
demo counter 154 Algorithm Half (AH) 28 pseudocode 207
field activation algorithms status codes 352–356
actions 223 activation passwords 80, API, SuperPro 16, 301–351,
commands 225 91 421
protection to applications active 23, 35, 191 APIPACKET 301
211 adding 188 application protection
sublicenses 198 addresses, valid 37–47 deleting 178
Address function parameter custom elements 186–192 description 146
128 default values 152, 159 editing 177
addresses description 23, 420 See also automatic protec-
algorithms 37–47 enhanced engine 35, 37, tion
cell 20 191 See also integrated protec-
cell types inactive 35–37, 191 tion
Activation Password overriding values 152, 159 testing 219
(AP) 30 querying 134 testing on network 219
Active Algorithm (AA) using to encrypt data 77– applications
28 79 activating 69, 81, 269
Algorithm Counter Word values 35, 155 activation status 238
(CA) 31 with counters 43–47, 96 active 63, 64, 420
Algorithm Half (AH) 29 with password 39, 47 adding protection to 210
Counter Word (CW) 32 anti-debugging protection 8, applying shell to 215
Data Word (DW) 33 169 calls to key 3
Developer ID (DI) 32 anti-disassembling protection compatible with automatic
Inactive Algorithm (IA) 8, 169 protection 393
34 anti-dumping 8 compiling 231
Locked Data Word (DL) anti-reverse engineering 8 demo
33 API Explorer activation types 71, 148
Serial Number (SN) 35 description 122, 127, 421 controlling 30, 94–98
Undefined (**) 28 evaluating functions 213– description 11, 63
description 420 214 protecting 146–148
selecting 37, 151 invoking functions 128 upgrading from 66, 68
advanced API function calls 5 FoxPro, protecting 382
encryption techniques 90 API functions in command-line shell utili-
description 221, 271, 423 contact server 103, 107 adding 193–194
requirements 272 context-sensitive help 127 description 187
shipping controlling demos 94 data words
to customers 248 converting values between description 187
to distributors 260 bases 130–131 deleting 200
using 156, 271–273 Counter Word (CW) 31 description 37, 145, 185
closing the Toolkit 144 counters editing 200, 208
code activation 65, 70, 229 rearranging on key 201–
adding API functions to adding 193 203
211–215 custom elements 187 sublicenses
Combo Installer for Linux 362 decrementing 95 adding 111, 198
command-line shell utility description 23, 423 description 187
description 397 moving 203 types 186
syntax 398 querying 99 when to use 186–187
using 399–401 time or execution control customers
commands 163 receiving locking code from
description 229 using 30–31, 94–99, 147– 274
field activation 148 role in field activation 274
adding 225 values, entering 191 sending license code to 277
default 207 with algorithms 45–47, 96 shipping applications to
description 221, 423 counting executions 94 248
randomizing order of 276 creating projects 136 using Client Activator 266
removing 228 custom elements customized
testing 230 adding error messages 176
menu 126 algorithms 188–192 protection 73
compatibility counters 193–194
key 390 data words 198–200 D
SentinelSuperPro 388 algorithms DAT files
compilers, compatible 393 adding 188–192 importing 137
compiling applications 231 description 186 data
components, SentinelSuper- valid locations 39 encrypting with algorithms
Pro 13, 14 with counter 43 77–79
concurrent access 110 with password 41 garbage 93
conditional access 93 with password and inserting extra 92
connecting keys counter 47 stored, reading 76
for distributor program- with password and two Data Protection driver
ming 242 counters 49 files 258
for product key program- with two counters 45 installing 258–259
ming 235 counters shipping
one-time update option 119 locked word 427 memory used 176
preventing multiple use of locking a project 140–141 Memory View 232
119 locking code memory, key 20
saving to file 277 copying 298 MemView
sending to customers 277 description 267, 427 description 132
License Generator Utility entering 275 invoking API functions 133
description 67, 281, 290 generating 298 using 132–133
generating license code loading from file 275 verifying prototype with
with 292 pasting 275 209
installing 290 receiving 274 menu commands 126
opening 291 saving to file 298 merge modules
required files 290 lockingcode.loc 274 description 249
shipping 261 locks server installation 252
license ID 109 See software locks using 252
license limit 4, 12, 72, 108 log file merging DAT files 138
licensegen.log 276 license codes 276 messages
licenses server 109 broadcast 104, 107
adding to distributor key error 176
222 M heartbeat
definition 427 machine code 91 description 74
description 72 maintaining licenses 109 sending 109
enforcement 12 Make Keys stage 123, 124, metered applications 237,
errors 109 237, 244, 428 244, 286
for demos 95 Make Keys Utility metering options, distributor
hard limit 15, 426 description 233, 281 key 245
heartbeat messages 74, 109 installing 282 methods, protection 76, 146–
maintaining 109 opening 282 148
obtaining 4, 108 programming distributor Migrating from Older Versions
releasing 110 keys 286–289 of Sentinel Keys 357
limited metering option 245 programming product keys missing hardware keys 82–83
limits, cell write 378 284–285 MOD 38
linking applications 231 required files 283 modes, access
loading license code 276 viewing statistics in 289 See access modes
loadserv.exe 254 makedll.dll 282 Monitoring Tool
locating keys 106 manipulating returned data description 428
Locked Data Word (DL) 32 75 moving
locked projects manufacturing code 56 counters 203
changing passwords 142 master key 207 from stage to stage 124
opening 140 meaningless locks 76 multi-file applications 380
spcommon.dll 282 status codes, API 352–356 threaded local storage 63, 382
spnsrv9x.exe 254 stepped access 93 time control
spnsrvnt.exe 254 stored data, reading 76 counter values 163
stage window 122 storing serial numbers 92 description 166
stages strategy time-out 13
About 123 creating prototype for 207 Toolkit
description 122 implementing 206 closing 144
Design 122 sublicense limits 111 navigating in 121
Home 122 sublicenses opening 114
Implementation 122 adding 111, 198 uninstalling 374
Make Keys 123 cell type used for 32 trial versions
moving from 124 custom element type 187 See demo applications
Overview 122 definition 431 troubleshooting
Project 122 obtaining 111 application activation 386
Prototype 122 sublicensing cannot update keys in field
required 124 description 12, 72 118
stand-alone heartbeat messages 111 deleted element still visible
access 13 percentages 110 in MemView 207
applications usage example 110 distributor can’t generate li-
demos 95 uses for 110 cense codes 386
licenses 72 subroutines, assembly lan- encrypting more than 50
protection types 146 guage 92 files at shell time 379
keys 57 SuperPro API 16, 301–351 hardware problems 391
definition 431 SuperPro server - Unload 369 key programming 384
description 15 SuperProNetServers.msm 252 repairing installation 376
selecting for program- syntax, command-line shell server not running message
ming 235 utility 398 385
stand-alone mode system driver update process unsuccessful
definition 431 installing 249 299
description 103 shipping 249, 261 trusted activation type
finding key in 106 uninstalling 375 description 65, 71, 432
setting 103 example 65
stand-alone utilities T overriding default password
See utilities techniques, protection 76–94 values 156
starter programs 383 testing querying activation pass-
static activation type 63, 71, application protection 219 words 91
431 field activation actions/
statistics U
commands 230
programming 240, 289 programmed keys 241 unauthorized access 14
A
access An attribute that identifies the accessibility and functionality of a cell. Possi-
code ble values are:
0 read/write data word
2 counter
3 algorithm/hidden
7 algorithm/hidden/AES
See also locked word, hidden word, data word, counter, algorithm.
access Access modes determine where your application will look for the appropri-
mode ate hardware key. There are three access modes that can be used by your
protected application: stand-alone, network and dual. See also network
mode, dual mode, stand-alone mode.
action A group of one or more field activation commands. See also field activa-
tion, command.
activation A two-word value that can be used to activate an inactive algorithm. The
password password is programmed into the two cells immediately following the algo-
rithm. You give your users the password and a utility with which to enter it.
Activation passwords use access code 3. They are called hidden words
because their values cannot be read by your application. See also access
code, algorithm, hidden word.
activation Protection provided by Sentinel SuperPro that allows for various methods of
type customer activation of program modules. Possible activation types are
active, static and trusted. See also active activation type, static activation
type, trusted activation type.
active/ A bit in an algorithm’s second word that controls whether or not the algo-
inactive rithm will respond correctly to a query. An algorithm must be active to
bit respond to a query. See also algorithm, query.
active An application that is ready to run when shipped to your customer. It will
application always remain active, as long as the hardware key is attached.
SuperPro XM keys provide an additional algorithm engine that uses indus-
try standard AES (Advanced Encryption Standard) encryption to generate
unique query responses.
address The memory used to identify a specific cell. See also cell.
algorithm An element containing a bit pattern that defines how the hardware key
should encrypt query data sent by your application. The key uses an algo-
rithm to encrypt the query data and then return a value to your application.
You design your application to send queries to the key and then evaluate
and act upon the responses.
anti- The Shell is capable of detecting the debuggers, like SoftICE and OllyDbg. It
debugging can also provide reasonable protection against break-points targeted at
protection important functions. You can choose to deny application execution in the
presence of debuggers. The protected application will exit if a debugger is
detected on a system. Non-malicious users will close the debugger and start
the application again. Otherwise, you may even allow your application to
run in the presence of debuggers.
anti- Shell provides protection against a memory dump of the protected applica-
dumping tion. You need to select the Hide import symbols check box to enable this
protection added protection.
API Application Program Interface. The set of client interface routines your
application uses to communicate with the Sentinel system driver, which in
turn communicates with the hardware key. See also driver.
API Allows you to experiment with API function calls on various cells in the key
Explorer before you add them to your source code. It is also a good way to familiarize
yourself with the available functions and their uses prior to designing your
strategy.
anti- Using the Shell SDK module, you can protect your important code frag-
reverse ments, strings, and constants for Visual C, Visual BASIC, and Delphi.
engineerin
g
protection
automatic Also known as shelled protection. The fastest and easiest method of protect-
protection ing your applications with Sentinel SuperPro.
Instead of adding software locks to your source code, a protective “shell” is
automatically added to your application’s executable file, so that the soft-
ware lock is called before the application starts—if the hardware key is not
present, the user sees an error message and the application does not run.
Automatic protection also gives you more control over demo options such as
expiration dates, counters and time/date limits. See also application pro-
tection, shell, software lock.
C
cell A memory location on the hardware key that holds 16-bit values. Elements
occupy one or more cells on the key.
cell type A code assigned to each cell that defines (logically) how you want to use the
cell. The cell type classifies the type of data stored in the cell, which in turn
affects how the cell can be used.
Each cell type is identified by a two-letter abbreviation; for example, CW
identifies a counter word.
cell value The 16-bit value contained in each cell. The cell value is also known as a
word.
command Function calls that describe what will be done to a key in the field. For exam-
ple, the Decrement Counter command locates the counter cell on the key
and decrements it by the value you specify. See also API.
counter A cell used to count down from a pre-programmed value. The value in a
counter is decremented each time your application sends the RNBOsproDec-
rement() API function. A counter 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; when the counter
reaches zero, the algorithm is deactivated automatically. See also access
code, demo, algorithm.
D
data word A cell in a Sentinel SuperPro key that is used to store information. A data
word can store data such as customer information, serial numbers, pass-
words, and check digits. You code your application to read the word and
then evaluate and act upon the stored value.
Your application can use the stored value to verify 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 (locked/read-only). See also access code, locked word.
decryptio The process of deciphering data that was previously encrypted. Decryption
n requires a secret key or password. See also encryption.
Design The Design stage has two sections: Element List View and Element Layout
Stage View. Use the Element Definition Wizard, accessible via Element List View, to
define cell types and cell values. Element Layout View allows you to view
and modify the location of algorithm, counter and data word cells on the
hardware key.
developer A unique identification code assigned to you by SafeNet Inc. You must use
ID your developer ID to program your keys. You must also use it in your pro-
tected application to establish a connection with a key.
distributor Someone outside of your organization who will be responsible for selling and
activating your application. For example, distributors could be resellers or
fulfillment centers. Distributors must receive a distributor key in order to
activate an application using the distributed activation type. See also, dis-
tributor key, distributed activation type.
distributo A key given to your sales distributors, allowing them to perform activation
r key and update functions on product keys provided to end-users when they sell
your protected application. A counter decrements each time the distributor
activates or updates an application. This allows you to keep track of applica-
tions activated by your distributor. See also, counter, distributed
activation type.
dual An access mode used when you want your application to use either a local
mode key or a network key. This is the default mode for all Sentinel SuperPro-pro-
tected applications. When in dual mode, an application will send broadcast
E
element An item in your protection strategy such as an algorithm, counter, data
word or application protection.
F
field A secure method of remotely updating a Sentinel SuperPro hardware key’s
activation memory after the key is sent to your user.
Field activation allows you to increase demo limits, upgrade demo applica-
tions to fully licensed versions, and provide access to additional modules or
features, without having to ship a new key to the customer or visit the cus-
tomer’s site.
field Enables you to ship your application in an unusable state, and provide a
exchange means for legitimate users to activate it. The activation process is protected
by encryption algorithms and passwords pre-programmed into the key. This
same process also allows you to support field upgrades and control feature
access. See also algorithm, field activation, activation password,
active/inactive bit.
H
hard limit Defines the maximum number of licenses that can be obtained from a key,
and thus the maximum number of users (both local and across the network)
that can access the protected application. The hard limit is programmed
into each key at the factory and cannot be changed. See also hardware key,
license, sublicense.
hardware The heart of Sentinel SuperPro protection. The key controls and verifies
key access to your protected applications, assuring that only authorized users
can run them
hidden A cell that cannot be read by your application. Most hidden words are algo-
word rithms and activation passwords. Your Write Password and Overwrite
Passwords are also hidden words. A hidden word has an access code of 3. See
also access code, algorithm, activation password, Write Password,
Overwrite Password.
I
Implement This stage allows you to add a shell to an application’s executable file, or
ation Stage view the pseudocode protection plan generated during prototyping,
This stage also allows you to define the actions that can be taken through
field activation, and is used to create license codes for distribution to cus-
tomers who have purchased upgrades in the field.
inactive
applicatio
An application that will not run until it is activated.
n
integrate A form of application protection where software locks (API function calls)
d are added directly to your source code. It is used to create a custom protec-
protection tion strategy, with control over the amount and location of software locks.
See also software lock, API, application protection.
L
license A license allows the user to start the protected application and access the
hardware key. Licenses are never physically moved between the server/key
and the client workstation. Instead, the Sentinel Protection server simply
keeps track of how many users can run the application and decrements and
increments the license count as authorized users are granted permission to
run the application and as they exit the application. See also hard limit,
sublicense.
license A code that describes the actions to be performed on a key in the field. It
code determines how the application will be activated or updated.
The license code is generated by Sentinel SuperPro based on the locking
code provided by the customer and the actions you select. When the cus-
tomer enters the license code in the Client Activator or Field Exchange
Utility, a script is automatically run that performs the selected actions on the
key.
License codes are unique to the key the locking code was generated from. See
also action, command, field exchange, locking code.
locked A data word that contains a value that can be read but not changed by your
word application unless the Overwrite Passwords are used. A locked data word
has an access code of 1. See also data word, access code, overwrite
Passwords.
locking A code that includes information about how a key is currently programmed,
code including the key’s serial number and developer ID. You must have a cus-
M
Make The Make Keys stage allows you to program keys prior to distribution. Hard-
Keys ware keys programmed with your protection strategy, as defined in the
Stage Design stage, must be distributed with each copy of your software.
multi- The Shell provides multi-layered protection. Since the joint between an
layered application and the Shell layers is vulnerable to attacks, you can choose the
protection number of layers the Shell uses to protect your application, from level 1 to 5.
Level 1 provides reasonable protection and level 5 provides the most protec-
tion. However, with each level of protection added, the size of the application
and the time it takes to start up also increases. By default, level 3 multi-lay-
ering is used.
N
network Allows multiple network clients to access a protected application using a
key single hardware key. Network keys, which are typically connected to servers
on the network, are programmed at the factory with a hard limit. See also
hard limit, hardware key, license.
network An access mode used for applications where you want only a network key to
mode be used. The application will look for a key only on the selected server. If the
selected server is not found, or a key is not found on the selected server, the
application will not send a broadcast message to the network looking for
another server and key. See also access modes, dual mode, stand-alone
mode.
O
Overview Sections in this stage introduce you to Sentinel SuperPro concepts. This
Stage stage also features the API Explorer, where you can test API function calls,
view the key’s cell layout, and send queries to the key to obtain return
values.
overwrite A set of passwords you must have in order to set or change the value or
password access code of any cell other than a data word or a cell that is undefined.
s
Your overwrite passwords are provided to you by SafeNet Inc. Keep them
secure; they have the power to reprogram all unrestricted cells in your key.
See also Write Password.
P
product See hardware key.
key
project A project is stored in a Sentinel SuperPro file. The project contains all the
data used to create your protection strategy—elements, passwords, your
developer ID, algorithm values, counters, data words, field activation com-
mands, etc.
Your project is the template that will be used to program the keys protecting
your application.
Project This stage provides setup and configuration information. Create or open
Stage projects and enter your developer ID and passwords in this stage.
Prototype In this stage, you program the cells in the hardware key with the values
Stage defined in the Design stage, generating pseudocode for use in adding API
functions to your source code. This stage is a required stage.
pseudoco Outlines the API functions you need to add to your application (if you are
de using integrated protection), as well as additional information about your
protection strategy.
Q
query The process by which an application verifies that the hardware key is still
attached or has not been tampered with. This is done by sending query data
to be scrambled using a specific algorithm stored in the key. See also algo-
rithm, query data.
query The value an application sends in a query to the hardware key. The key
data scrambles the string according to its internal logic and the bit pattern
defined in a specified algorithm. It then returns a response to the applica-
tion. See also response string, algorithm, query.
R
response The scrambled result derived when the hardware key processes query data
string according to the bit pattern contained in an algorithm. The hardware key
returns the response string to the application. The application then uses the
response to determine whether the user is authorized to run the application.
See also query data, algorithm.
S
server The Sentinel Protection server manages licensing and security for the pro-
tected application. The server is the link between the client running your
application and the hardware key, located on the network, that responds to
the API functions used in your protection strategy.
shell A protective layer wrapped around your application’s executable file when
you use automatic protection. This layer is encrypted, making it more diffi-
cult for a hacker to gain access to your application’s code.
All software locks and communication with the hardware key (such as
checking and verification) are handled by the shell. An application pro-
tected with a shell can be run only if the user has the correct hardware key.
See also automatic protection, software lock.
stand- An access mode used for applications where you want only a local key to be
alone used. The application will look for a key only on the client machine. If the
mode key is not found, the application will not send a broadcast message to the
network looking for a server and key. See also network mode, dual mode,
access modes.
sublicense A sublicense is a license limit you define that is less than or equal to the hard
limit programmed into the key. Sublicenses allow you to implement fewer
licenses for an application than the hard limit programmed on the key, pro-
tect several applications using the same key by defining separate license
limits for each, and control concurrent access to specific features or modules
within your protected application(s). See also hard limit, license.
T
trusted Method of product activation provided by Sentinel SuperPro where the
activation application is inactive until activated by an activation password, unless it is
type a demo or metered application. The activation password is different for every
key; it is derived from the key’s serial number, product information and an
encryption engine. See also activation password, demo, activation type.
U
USB Universal Serial Bus. A technology that features one “universal” plug type
for all USB peripheral-to-PC connections. USB replaces all the different kinds
of serial and parallel port connectors with one standardized plug and port.
USB simplifies the connection of peripherals to computers by providing an
instant, no-hassle way to connect USB peripherals. With USB-equipped PCs
and peripherals are automatically configured and ready for use.
W
word See cell.
Write A password you must have in order to set or change the value or access code
Password of a data word or a cell that is not yet defined. This password also allows you
to decrement counters. Your Write Password is provided by SafeNet Inc. See
also access code, data word, counter.