You are on page 1of 22

Sentinel Hardware Key

Quick Start Guide


Overview

Sentinel Hardware Key guards your software against unauthorized use by


providing reliable and easy-to-use protection technology. It is the easiest
way to license/protect your application. The licensed application uses the hardware
key to support the license agreement you have with your customer. It has options to
quickly protect your applications and ways to implement intensive and controlled
protection strategies. Before you get started to license your application, you need to
decide the type of licensing you would use in your application. With Sentinel-
Hardware Key, every user of your application needs to obtain a license before he can
run 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 network 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.

Getting Started with Sentinel Hardware Keys:-

Step 1: How to go about the whole process of using SHK.


Step 2: Understanding Sentinel Keys SDK components
Step 3:- Protect your application using Shelling.
Step 4:- API Protection: The method in which you insert the Business Layer
API functions into your application's source code.
Step 5:- Building the samples that came with the toolkit.
Step 6:- Using API explorer
Step 1:- How to go about the whole process of using SHK.

Install the toolkit

Prepare a conceptual protection


plan.

Add API or Shell feature Apply Shell protection for


depending upon your Windows only
requirement. (We will discuss
later)

Build License template. Add


business layer API function in
your code compile and link
your application

Test the protected Application

Step 2:-

Sentinel Hardware Keys SDK basic Components: - We will be discussing few


components to know about each please go through Sentinel Keys Developer guide
Sentinel Keys Toolkit: - The Toolkit is a Java application. It is used for preparing
the application protection strategy and programming hardware keys for your
customers and distributors.
Generic For Customer For Developers For Distributors
Component
(For all)

Sentinel Sentinel Keys Sentinel Keys Sentinel Keys


System Driver Sentinel Keys Toolkit License Manager
Server Command-Line (stand-alone
Shell Utility application)
Sentinel Keys
License Monitor Developer Key Distributor Key
Sentinel Compiler For Remote Updates
Protection Installer Interfaces Secure Update
For Remote Updates Key Programming Utility
Secure Update APIs
Utility
Secure Update
Wizard
(for Windows only)

About the Toolkit Screens:-

Quick Shell
In the Quick Shell screen, you can protect an executable with popular
licensing controls, like an expiration date, expiration time, and execution count. It
offers basic licensing controls; for advanced licensing, use Shell option in the License
Designer.

License Designer
In the License Designer screen, you can design and build your application
protection strategya license template consisting of Shell and API features.
You can begin by creating a template using the License Designer wizard.

License Manager
In the License Manager screen, you can package the licenses and program
hardware keys. Groups are created to package the license (templates).
Subsequently, these groups are used for programming Sentinel Keys and
distributor keys.

Update Manager
In the Update Manager screen, you can create update actions and generate
update codes for remotely updating the hardware keys.

API Explorer
In the API Explorer screen, you can experiment with the Business Layer
API prior to adding them into your source code. It also generates the usage
code in popular programming languages for a platform

Key Status Panel


A panel (in the left-side of the Toolkit) that displays the developer, distributor,
and Sentinel hardware User keys attached to the system. You can select the
hardware key using the left and right arrow buttons

Developer Key: - The developer key is meant for youthe software


publisher/vendor, who prepares the application protection strategy using the Toolkit.
You will not be able to build (prototype) the protection strategy in the
Toolkit, unless the developer key is plugged-in.

Sentinel User Keys:-


The Sentinel Keys are meant for your customers. They will be able to run your
protected application only if the correct Sentinel Key is accessed. It is available for
both stand-alone and network environments. A network key allows multiple network
clients to run the protected application concurrently. It is typically connected to a
networked system running the Sentinel Keys Server in the subnet. A stand-alone
protected application is licensed to run on a single computer without using a
network.

Sentinel Keys Server:-


The Sentinel Keys Server manages the licenses available with the Sentinel
Keys attached to a system. It maintains a database of the Sentinel Keys attached to
a networked system and handles the availability, maintenance, sharing, and
cancellation of licenses for its clients. It must be redistributed with your network
applications.

The Sentinel Key Server runs as Windows service with its executable under
C:\Program Files\Common Files\SafeNet Sentinel\Sentinel Keys
Server\sntlkeyssrvr.exe. The key server executable is named
sntlkeyssrvr.exe.
Step 3:- Protecting your Application using Shell.

Protecting your application with Sentinel shell is the quickest and easiest way to
license your application. The Shell features can be added only using the Windows
version of the Toolkit.

Some of the reasons you might consider using Shell are:

1. You dont have access to the source code for the application you want to protect.
2. You want to quickly set up a demo product and dont need special licensing.
3. You want to get familiar with Sentinel Hardware Kit quickly and easily.
Quick Shell is a gateway to the Toolkit. You can use it for quickly protecting an
executable with basic licensing controls, like expiration date and execution count.

Example - Protecting WordPad Using Quick Shell

In the example below, we will protect Wordpad.exe, so that:

It will not run unless the correct Sentinel Key is attached.


It will not run more than once.

Step A: - Attach both the Developer key and Sentinel Key to USB hub/ports on your
system. When these are shown in the Key Status panel, select Sentinel Key using the

or icons.
Step B: - Select protect my application with licensing limit I choose from below.

Select the Execution Count check box and specify 1.

Step C: - Click Prepare Key. When done successfully, the Application settings options
are enabled.

Step D: - Click Browse to select Wordpad.exe (available at <OS Drive>\Program


Files\Windows NT\Accessories on Windows XP). When done successfully, the
remaining fields are populated automatically. Choose the access mode as network or
standalone depending upon your requirement
Step E: - Click the Make Shell button. When done successfully, a message box
appears. Click Close. The Make Key button is activated.

Step F: - Click Make Key. When done successfully, a message box appears. Click
Close.

Running the Protected WordPad

Browse to <OS Drive>\Program Files\Windows NT\Accessories. Run


wordpad_SHELLED.exe.

It should run successfully as long as the Sentinel Key is attached to the system.
However, it will not run more than once because we allowed only one execution. The
following message will appear on further executions:

Consider using the Shell option in the License Designer screen to make use of
advanced options. The Shell features can be added only using the Windows version
of the Toolkit, using any of the following options.
i) Using the License Designer Wizard - This option allows you to create a license
template by adding a Shell or API feature to it

ii) Under the Shell tab of the License Designer screen - This option allows you to add
a Shell feature to an existing license template

Using License Designer Wizard for Windows

You can launch the wizard using any of the following ways:

Click the icon in the License Designer screen.


Click the Create button in the Templates Management dialog box.

Selecting Option in the License Designer Wizard

The License Designer wizard shows you the following options:


I'm new to creating features and templates

Using this option, you can create a new license template by adding Shell and API
features into it. This option is recommended for new users who want to be guided
step-by-step on creating a template

I want to copy a sample template

Using this option, you can create a new template by copying a sample template.
Afterward, you can modify its settings and/or build it.

I want to add features under the Shell/API tabs

This option is recommended for users who want to create a blank template here
and add features in the License Designer screen.

Option 1 - I'm new to creating features and templates

Select I'm new to creating features and templates in the License Designer Wizard
launching screen.
1. Click Start.
2. Choose any of the two options depending on whether you wish to create a
Shell or an API feature.
3. Click Continue.
We will be choosing Shell Feature here.
.
You must add at least one file with a .exe or dll extension to proceed

Specify
Destination
Path

Type or
browse for the
path of the
destination
directory in
the edit box
under the
Change the
destination
path check
box. This is
the destination
path for
writing the
output files
(recommended
step).
Attributes
Active: Select to provide a perpetual license for using the application.
Lease: Select to allow specifying an expiration date or expiration time for the
application.
Limit executions: Select to allow specifying the number of times the protected
application will run.
Add instances later
It will allow you to add new feature instances later in the License Manager screen.

Networking and Security Settings

Network Settings

Choose from the following networking settings:


Access Mode
Stand-alone, by default.

Stand-alone mode (SP_STANDALONE_MODE)


The application looks for a license on the same system without requiring the
Sentinel Keys Server.

Network (SP_SERVER_MODE)
The application obtains a license from a network key.
Specify a template name (necessary). The user name automatically appears as
the default owner.
Providing comments is optional. These comments will be visible under the
template layout (in the License Designer screen) and the group layout (when a
group is created using that template in the License Manager screen).
Click Finish. The template you created just now is listed under the template
layout. You may add more Shell features into it, if required.

After selecting your choices in the Add Shell Feature dialog box, you must now
perform the following final steps:

The Make Shell Button

Click the Make Shell button. This will wrap the Shell layer around your executables
and DLLs and encrypt the data files; if any. This may take time depending
upon the number of files and layers you have added.
The Build Button

Click the Build button to update your template settings and program the Sentinel Key
with it.

Step 4:- API Protection


If you want more control or want to use more sophisticated licensing models, you
should consider using the Sentinel Hardware Key API protection. In the initial stage
you need to decide which software locks to use for protecting your application. The
purpose of a software lock is to verify the presence of the correct Sentinel Key. You
will begin by contacting the Sentinel Key for a license (SFNTGetLicense API call).
Subsequently, you can craft variety of software locks to check the presence of the
Sentinel Key
You can create the following API features in the Toolkit:

1) AES: - A 128-bit AES algorithm-based feature that allows you to:


i) Encrypt data
ii) Decrypt data
iii) Use the query-response protection.
iv) Specify licensing controls (like, expiration date, expiration
time and an execution count).

2) ECC: - An ECC algorithm-based feature that allows you to:


i) Digitally sign content
ii) Verify signed content
iii) Specify licensing controls (like, expiration date, expiration time).
3) String:-A data feature that can contain up to 256 ASCII printable characters.

4) Raw Data: - A data feature that can contain 256-bytes of any developer-defined
data type, including printable/non-printable characters and hexadecimal numbers.

5) Integers: - Data feature that can contain any of the following integers: 8-bit, 16
bit or 32 bit.

6) Boolean: - A data feature that can contain a true or false value.

7) Counter:- A data feature that can contain a count-down value between 0 to


4,294,967,295

Please refer to API help located in C:\Program Files\SafeNet Sentinel\Sentinel


Keys\1.2.1\Compiler Interfaces\Help\English\API\Business_Layer_API_Help.htm
directory for more details about each feature.

The API features can be added using any of the following ways:
1) Under the API tab of the License Designer screen - This option allows you to add
an API feature to an existing license template.
2) Using the License Designer Wizard - This option allows you to create a license
template by adding a Shell or API feature .We will start from the add feature this
time since we have covered creating template earlier.

Below is an example of adding string feature.

To obtain the Add Feature dialog box:

1. In the License Designer screen, load the template to which the API
feature will be added.

2. Click the API tab.

3. Click the Add button. The Add Features dialog box appears.

4. Select String.
5. Specify a string containing up to 255 ASCII printable characters for the default
instance Specify a write password if you want to write the feature value. The option
will be disabled if you have selected the Read-only option.
6. Selecting the Add instances later check box will allow you to add new feature
instances later in the License Manager screen.
7. If you selected the check box described in step 6, specify the maximum size. It
has to be greater than the existing string length and less than 256 ASCII printable
characters.
8. Provide a name for this feature (necessary).

9. The constant name will be automatically generated. However, you may modify it,
if needed.
10. You may optionally provide comments. When done, click OK.
Setting Build Options:-
1. Click the Build Options tab.
2. Specify the File generation option to guide on how often the template header
file and code sketch should be generated. You can select any of the following
options:
o Automatically generate when necessary (default)
The Toolkit generates the header file and code sketch whenever
necessary.
o Generate for every build
The Toolkit generates the header file and code sketch every time the
Build button is clicked.
o Ask me before building
The Toolkit requires your permission every time the header file and code
sketch need to be regenerated.
3. Select the Operating system for which header files are to be generated. The
available options are Windows, Linux, and Macintosh.

Note: The toolkit will not be available on non-windows platforms. The header files for
Linux and Macintosh should be generated from the Windows Toolkit and moved to
the intended platform.
4. Select the programming language of your choice. If the language/compiler you
want is not shown, select Common header. It will generate a language/compiler-
independent header file. You need to convert the syntax into your chosen
development language on your own. You can also select the Generate For All option
to generate header files for all supported languages.
5. You can set the following query-response settings if an AES feature is included in
your license template:
o Number of queries
Specify the number of queries you want to make.
o Query size
Select how long, in bytes, you want the query string to be.
o Include Shell features (for Windows only)
If you have added any Shell features to your template, we recommend
you to select this check box
6. Make sure that both the Developer key and Sentinel Key are attached to the
system. The Sentinel Key must be selected in the Key Status panel.
7. Click the Build button. A dialog box will appear displaying the status of the
activity.
8. As soon as the license template is built, a dialog box will appear prompting you to
copy the libraries and header files (include files) at a path of your choice.
9. You may click Copy to copy the header file
10. To view the code sketch for this license template in the selected language, click
View on the Build Option Tab.
When a license template is built, the following tasks are performed:

i) Sentinel Key is programmed with the license information.


ii) Header file is generated.
iii) Code sketch is generated.
Add the Business Layer API functions into your applications source
code. The Business Layer API Help provides complete details on each function.
Compile your application after including the Sentinel Keys header
files and libraries. The code snippet below illustrates the most-basic API functions
used for implementing licensing.

int main ().

{
/*Calling SFNTSetContactServer( ) */
Sets the Sentinel Keys Server to be contacted for obtaining a license.
You may optionally call this function to direct the license request to a specific
Sentinel Keys Server for obtaining a license. The function needs to be called before
calling SFNTGetLicense.

/*Calling SFNTGetLicense ()*/


Obtains a license from the Sentinel Key (having required developer ID and license
ID) attached to a system.Call this function before calling any other Business Layer
API function in order to obtain a license.

/*Calling SFNTReadString()*/
Reads the String feature value in the Sentinel Key.
You can call this function anytime after successfully calling SFNTGetLicense.

/*Calling SFNTReleaseLicense()*/
Releases the license and cleans up the memory allocated to the client library
resources.
}

You could embed these APIs within your applications source code depending on
where the application should request the license. These are the basic licensing APIs.

The Business Layer API Help provides complete details on each function
Step 5:- Building the samples that came with the SDK.

Sample applications are provided that demonstrate various licensing


models, such as lease and demos. These samples make use of Business Layer
API functions, suitable for that licensing scheme.
Follow the steps given below.

1. In License Designer select load License Template Types select samples choose
a sample license template provided (e.g.:- LeaseDemo) in the Toolkit.

2) Provide your build options under the Build Options tab, such as specify the
development language you want the sample for.

3) Build it by clicking Build button. The following dialog box will appear
(the dialog box differs across platforms) on completion of the build
process for windows sample.

4) Click the Take me there link (the dialog box differs across platforms).
You are directed to the language-specific directory for the sample wherein you can
compile the sample application and understand the API functions used.

Working with the Sample (VC++):-


The SHK API help is located in the C:\Program Files\SafeNet Sentinel\Sentinel Keys\
1.2\Compiler Interfaces\Help\English\API\Business_Layer_API_Help.htm directory.
The SHK Visual C++ samples are located in the C:\Program Files\SafeNet
Sentinel\Sentinel Keys\1.2.1\Sentinel Keys Toolkit\Samples\Microsoft\Visual C++
sub-directories.
We will be building LeaseDemo sample.
LeaseDemo.cpp is the Visual C++ source code file.
SentinelKeys.lib is the SHK static link library.
SentinelKeysLicense.h is a project specific header file created by the SHK Toolkit.

This SHK sample code is located in C:\ Program Files\SafeNet Sentinel\Sentinel


Keys\1.2.1\Sentinel Keys Toolkit\Samples\Microsoft\Visual C++\LeaseDemo
directory.
Insert the Developer Key and a User Key.
Start the SHK Toolkit
Under Key Status, select the User Key (Sentinel Key), not the Developer Key.
Select License Designer
Select License Template (Click the load button)
Under License Templates Types: Select Samples
Select LeaseDemo and click Load
Select the Build Options tab
Change Generate options: to Generate for every build
Change Programming language: to ANSI C
Click the Build button, then OK
Click the Copy button, and then select your build directory.
Now you have a new header file called SentinelKeysLicense.h in your build
directory.
Start Microsoft Visual Studio 6.0, Microsoft C++ 6.0.
File > Open Workspace, then select your build directory and the project file
LeaseDemo.dsw->click open
Build > Rebuild All
Build > Start Debug > Go

Enter your Dev ID

.
Screen Display while demo is running

Final screen

Step 6:- Using API Explorer

In the API Explorer screen, you can experiment with the Business Layer API prior to
adding them into your source code. Corresponding to each function, it also generates
the usage code for various languages.

Getting Ready to Use API Explorer Before you can use the API Explorer, you must be
ready with the following:
License Template (built using the Build option)
You can use a template created in the Toolkit, or a sample template, or a
template imported from any other Toolkit installation.
Sentinel Key
Attach the Sentinel Key (the license template was built with) to your system.
The Developer ID of your Sentinel Key is shown in the Key Status Panel.
Test your template you have built .You will begin by contacting the Sentinel
Key for a license (SFNTGetLicense API call).When you open the template the
Developer ID is entered for you.

Some of the commonly used terms:-


RTC Tokens: - It contains a tamper resistant internal real-time clock that indicates
the exact date and time to track the usage of the leased applications. The real clock
keeps track of time independent of the system clockproviding the best solution
against time tampering attacks.

Non-RTC tokens with Sentinel V-Clock allows reliable and secure distribution
of time-limited applications. These do not require an on-board battery to detect time
tampering and allow you to tolerate the number of time tampering attempts
specified in the cheat counter.

Hard Limit: The hard limit specifies the number of tokens (instances) a license can
have or number of instances of licensed application that can be run simultaneously.

User limit:-A soft limit that restricts the number of users allowed by the hard limit.
Otherwise, the number of users allowed is equivalent to the hard limit

Cheat counter is a count-down value that allows tolerating the time tampering
attacks ranging between 1 second to 30 days (excluding the daylight savings) till it
reaches zero. For other attributes please refer to Sentinel Keys Developer's Guide.
Where Can I Find Out More?
Please note that this is a quick start reference guide that talks about conceptual
knowledge and quick steps you need to learn to protect your application. For more
information on how to create and implement your licensing strategy, refer to the
Sentinel Keys Developer's Guide. That guide also discusses how to deploy your
protected application to your customers, and what information you should send your
customers on setting up and using licensing. For the latest information on Sentinel
Hardware Key, go to http://www.safenet-inc.com.

Contacting Technical Support


We are committed to supporting Sentinel Hardware Key. If you have questions, need
additional assistance, or encounter a problem, please contact Technical Support:

http://www.safenet-inc.com/support/index.asp

E-mail: support@safenet-inc.com
United States
Telephone (800) 545-6608
Fax (949) 450-7450Europe
France
Telephone 0825 341000
Fax +44 (0) 1276 608080
Germany
Telephone 01803 7246269
Fax +44 (0) 1276 608080
United Kingdom
Telephone +44 (0) 1276 608000
Fax +44 (0) 1276 608080