SafeNet Sentinel Developer's Manual

Table of Contents

Quick Links

1.2.0

Table of Contents

Need help?

Do you have a question about the Sentinel and is the answer not in the manual?

Questions and answers

Summary of Contents for SafeNet Sentinel

Page 1 1.2.0...
Page 2 Manuals directory for details. CONFIDENTIAL INFORMATION The Sentinel Keys SDK is designed to protect your software applications from unauthorized use. It is in your best interest to protect the information herein from access by unauthorized individuals. Part Number 002266-001, Revision F Software versions 1.2.0...
Page 3 Certifications European Community Directive Conformance Statement Sentinel Hardware Keys are in conformity with the protection requirements of EC Council Directive 89/336/EEC. Conformity is declared to the following applicable stan- dards for electro-magnetic compatibility immunity and susceptibility; CISPR22 and IEC801. This product satisfies the CLASS B limits of EN 55022.
Page 4 Mac OS X Universal Logo Compliance The Sentinel Hardware Keys SDK is designed for the Macintosh operating system (Mac OS X) and runs natively on both PowerPC- and Intel-based computers from Apple. USB 2.0 Compliance Sentinel Hardware Keys comply to the USB 2.0 standards.
Page 5 FCC Compliance Sentinel Hardware Keys have passed the FCC Self-authorization process of Computers and Computer Peripherals. FCC Part 15 Class B Specifications. FCC Notice to Users This equipment has been tested and found to comply with the limits for a class B digital device, pursuant to part 15 of the FCC Rules.
Page 6 Sentinel Hardware Keys Developer’s Guide...
Page 7: Table Of Contents
Sentinel Keys Protect Against Software Piracy ..............4 License Models to Increase Your Revenue ..............6 Sentinel Keys Offer Sophisticated Protection..............7 Frequently Asked Questions..................14 Chapter 2 – Sentinel Keys SDK Components ........ 17 Overview ........................17 Sentinel System Driver ....................19 Sentinel Keys Toolkit....................21 Command-Line Shell Utility ..................24...
Page 8 Developer Key......................25 Compiler Interfaces ..................... 27 License Manager (Stand-alone)................... 28 Distributor Key ......................29 Sentinel Keys ....................... 29 Sentinel Keys Server ....................33 Sentinel Keys License Monitor..................35 Sentinel Protection Installer..................37 Configuration Files ...................... 38 Remote Update Options ....................38 Frequently Asked Questions..................
Page 9 Programming Hardware Keys ......161 Chapter 8 – License Grouping ............163 Why Create Groups?....................163 Creating New Groups ....................165 Loading Groups ......................166 Duplicating Groups ....................166 Removing Groups...................... 167 Sending Group Files to Distributors................167 Sentinel Hardware Keys Developer’s Guide...
Page 10 Export-File Manager....................171 Locking/Unlocking Groups ..................172 Frequently Asked Questions..................173 Chapter 9 – Programming Sentinel Hardware Keys ....179 Programming Sentinel Keys using Sentinel Keys Toolkit ......... 179 Programming Sentinel Keys using the Key Programming APIs....... 184 Frequently Asked Questions..................188 Part 4: Distributing Protected Applications ..
Page 11 Appendix C – Sentinel Keys Hardware Specifications ....255 Appendix D – Migration from SuperPro and UltraPro ....257 Stage 1 - Distribute Sentinel Dual Hardware Keys ............ 257 Stage 2 - Design New Protection Strategy..............259 Index ....................261...
Page 12 Contents Sentinel Hardware Keys Developer’s Guide...
Page 13: Preface
■ Implement different license models for different customers. ■ Secure your product revenue. ■ Where to Find Information? The Sentinel Keys SDK documentation is for the following users: You Could Be a... Recommended References Manager or New User ❑ Release notes You want to understand the product ❑...
Page 14: Conventions Used In This Guide
Installer Help (for redistributables. Windows only) Sales Distributors ❑ Help included with the You want to program Sentinel Keys for your License Manager applica- customers. tion Customers and Helpdesk ❑ System Administrator’s For users who want to learn how to use the...
Page 15: Technical Support
Online support system to get quick answers for your queries. It also provides you direct access to SafeNet knowledge base. Sentinel Integration Center (C3) http://www.safenet-inc.com/support/ic/iclogin.asp Provides the information you need to successfully integrate Sentinel products with your solutions. Sentinel Hardware Keys Developer’s Guide...
Page 16 E-mail support@safenet-inc.com 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) Sentinel Hardware Keys Developer’s Guide...
Page 17: Safenet Sales Offices
SafeNet Sales Offices SafeNet Sales Offices For more information about SafeNet products and offerings, contact the sales offices located in the following countries: Australia Brazil China +61 3 9882 8322 +55 11 6121 6455 +86 10 88519191 Finland France Germany...
Page 18: Export Considerations
The title and version of the guide you are referring to. ■ The version of the software you are using. Your name, company name, job title, phone number, and e-mail ■ address. Send us e-mail at: techsupport@safenet-inc.com xviii Sentinel Hardware Keys Developer’s Guide...
Page 19: Part 1 Sentinel Key Basics
Part 1 Sentinel Key Basics Software piracy problem and its solution ❑ Sentinel Keys SDK components ❑ Planning application protection and licensing ❑ strategy...
Page 21: Chapter 1 - Introduction
Moreover, software protection must be simple to implement, so that your schedules are not burdened with lengthy training and licensing implementation. Read on to know how Sentinel Keys can do all this and much more! Sentinel Hardware Keys Developer’s Guide...
Page 22: Sentinel Keys Protect Against Software Piracy
Whatever method you choose, the outcome will be a protected application, different from the original application. The protected application is depen- dent on the Sentinel Key for execution. It will check for the presence of the Sentinel Key in order to run successfully. If the operation is successful, the application is allowed to run.
Page 23 You can see the diagram below to understand the typical behavior on the customer site when the correct Sentinel Key is attached or not. Note: The Secure Communication Tunnel (term used in the diagram below) is explained on page 15.
Page 24: License Models To Increase Your Revenue
It also provides better market penetration by increasing the product usage/trial rate among the potential customers. A few examples are described below. Using Sentinel Keys, you can: ■ Lease the protected application for certain period. Later, your customers may want to extend the lease or convert it to a perpetual license.
Page 25: Sentinel Keys Offer Sophisticated Protection
Sentinel Keys Offer Sophisticated Protection Sentinel Keys Offer Sophisticated Protection This section provides a summary of the main features of Sentinel Keys SDK, which make it the most reliable and chosen solution to protect your intellec- tual property and copyrights.
Page 26 USB 2.0 compliant, full-speed for bulk transfer. ■ 16-bit RISC MCU for high performance. ■ WHQL certified Sentinel System Driver for Windows 2000, XP (32-bit ■ and x64), and Server 2003 (32-bit and x64) compatibility. Role-enforcement Using Hardware Keys The Toolkit application is used to prepare important and confidential license policies.
Page 27 Sentinel Keys for your customers Innovative Licensing Models for Market Penetration Sentinel Keys not only secure unauthorized usage of your software, but also provide options to package your software differently to suit different price or feature categories. Using Sentinel Keys, you can: ■...
Page 28 Sentinel Shell protection from batch files without going through the Sentinel Keys Toolkit screens. The Sentinel Keys Command-Line Shell Utility is also referred to as CMDShell.exe. The utility is a console-based program that protects executables and DLLs using the Shell method via command-line.
Page 29 Sentinel Keys Offer Sophisticated Protection The Business Layer API Functions Smart and Flexible (One-time) Implementations The Toolkit is based on the architecture that divides the complete licensing process as per the different roles seen in real-life. Typically, the license designing and implementation part is done by the developers, while the license management and hardware key programming is handled by market- ing and administration personnel, involved in license fulfillment.
Page 30 The count can be updated remotely. Note: If desired, your Sentinel Key vendors can program Sentinel Keys in bulk for you. See the option described page 182. Convenient Licensing for Your Customers Sentinel Keys are ultimately deployed on your customer's site to allow authorized access to your protected applications.
Page 31 .lgx file is a package of licenses that you want to program in the Sentinel Key for your customers. Note: The .lgx/*.ISV/*.DIS/*.OPR files are generated by the Developer using the Sentinel Keys Toolkit.
Page 32: Frequently Asked Questions
Question 1 - What is the Secure Communication Tunnel? The Secure Communication Tunnel is an end-to-end secured session between the client and the Sentinel Key for providing secure private com- munication. The communication packets are encrypted using the AES algorithm, for which the session key is generated using ECC-based key exchange (ECKAS-DH1).
Page 33 For example, you can use the 128-bit AES algorithm for data encryption/decryption or use the ECC algorithm for digital signing and veri- fication. The Sentinel Keys can also store variety of data in its memory like, strings, integers, Boolean, and raw data commonly used by developers.
Page 34 Please do not try implementing the licensing scheme incompletely or directly (such as by just calling the Business Layer API functions and linking libraries). Refer to the Sentinel Keys Toolkit Help or this guide for under- standing the complete steps involved.
Page 35: Chapter 2 Sentinel Keys Sdk Components
This chapter provides information about the major components included in the Sentinel Keys SDK. Overview The Sentinel Keys SDK contains various components that are used by the following category of users: ■ Developer - An individual or a software development company that uses the Sentinel Keys SDK to protect and license their applications.
Page 36 Sentinel Keys are available for both the stand-alone and network environments (and are referred hereafter as stand-alone keys and network keys, respectively). Sentinel Keys A program that manages the Sentinel Keys license information in a network. Server Sentinel Hardware Keys Developer’s Guide...
Page 37: Sentinel System Driver
(the process is known as remote update process). Options Sentinel System Driver The Sentinel System Driver (version 7.4.0 or higher) is the device driver for communicating with the USB hardware keys listed below. It must also be redistributed with your protected applications: Sentinel Keys ■...
Page 38 Chapter 2 – Sentinel Keys SDK Components For Windows Supports the following Windows platforms (Windows NT does not ■ support USB): ❑ Windows 98 ❑ Windows ME Windows 2000 ❑ Windows XP (32-bit and x64) ❑ Windows Server 2003 (32-bit and x64) ❑...
Page 39: Sentinel Keys Toolkit
Installed at the following path on a Macintosh system: /System/ Library/Extensions. Backward-compatibility Information For Macintosh, if any of the following Sentinel products are already installed on your system, then the installation package will upgrade the existing Sen- tinel System Driver (KEXT/Framework): Sentinel UltraPro SDK ■...
Page 40 In the License Manager screen, you can package the licenses and program hardware keys. Groups are created to package the license (templates). Sub- sequently, these groups are used for programming Sentinel Keys and distributor keys. Using the Export - File Manager dialog of License Man- ager, you can export files of *.ISV, *.DIS,*.OPR, and *.NLF files used for key...
Page 41 Key Status Panel A panel (in the left-side of the Toolkit) that displays the developer, distribu- tor, and Sentinel hardware keys attached to the system. You can select the hardware key using the left and right arrow buttons. Key Status Panel...
Page 42: Command-Line Shell Utility
Provides a Toolkit independent programming environment wherein the license group files are exported by the developer and programmed into the memory of the Sentinel Keys using the Key Programming API functions. Refer to section, “Programming Sentinel Keys using the Key Programming APIs”...
Page 43: Developer Key
Note: Please refer to the Key Programming API Help, for more information. Developer Key The developer key is meant for you—the software publisher/vendor, who prepares the application protection strategy using the Toolkit. The developer key provides an authentication and signing mechanism to the Sentinel Hardware Keys Developer’s Guide...
Page 44 128-bit AES secret keys for the following: ■ Digitally signing the licenses programmed into the Sentinel Keys ■ Encrypting the remote update packets Digitally signing the licenses programmed into the distributor keys ■...
Page 45: Compiler Interfaces
Fortran Intel Visual Foxpro Microsoft Visual Windev Pc Soft 11.0 1. The Windows x64 libraries are provided for Microsoft VC, .NET C#, VB .NET, and COM only. 2. For Windows x64 platforms, only version 2005 is supported. Sentinel Hardware Keys Developer’s Guide...
Page 46: License Manager (Stand-Alone)
2. The samples installed for the Xcode compiler version 2.2 also support compiler version 2.4. License Manager (Stand-alone) A Java application that your distributor can use for programming Sentinel Keys for customers. You also need to provide a license group file (.lgx) and the associated distributor key.
Page 47: Distributor Key
Sentinel Keys for your customers. Sentinel 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:...
Page 48 Stand-alone keys have zero (0) hard limit and do not serve any license requests from network. Hence, these can neither be detected by the Sentinel Keys Server running on the system, nor monitored by the Sentinel Keys License Monitor.
Page 49 Sentinel Keys One Network Key For Multiple Clients in LAN/WAN Sentinel Keys Models Details about the Sentinel Keys Models Model Name Description Characteristics Sentinel S Stand-alone ❑ Form-factor: USB non-RTC version ❑ Total memory: 8KB ❑ Hard-limit: Zero (0); for stand- alone users only ❑...
Page 50 Sentinel Dual Hardware Keys provide migration platform for Sentinel Ultra- Pro and Sentinel SuperPro developers and customers to the much-advanced Sentinel Hardware Keys. Sentinel Dual Hardware Keys are available in USB form factor with the following two flavors: Sentinel Dual Hardware Keys for UltraPro: Meant for Sentinel ■...
Page 51: 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 applica- tions.
Page 52 Chapter 2 – Sentinel Keys SDK Components ■ Installed at the following path on a Windows 32-bit NT-based system: <OS Drive>:\Program Files\Common Files\SafeNet Sentinel\Sentinel Keys Server. Installed at the following path on a Windows x64 system: ■ <OS drive:>\Program Files(x86)\Common Files\SafeNet Sentinel\Sentinel Keys Server.
Page 53: Sentinel Keys License Monitor
Sentinel Keys License Monitor Sentinel Keys License Monitor Sentinel License Monitor shows the details of the Sentinel Keys and clients accessing them via a Web browser. It is a convenient way to view and track license activity and analyze application usage.
Page 54 Hard Limit ■ Total number of licenses in use (sum of licenses issued from the Sentinel Key) License Information Page (clicking Keys# will display this page) License # (a list of licenses/templates programmed into the Sentinel ■ Key) ■ License ID ■...
Page 55: Sentinel Protection Installer
Sentinel Protection Installer Sentinel Protection Installer The Sentinel Protection Installer is a dual installer of the Sentinel System Driver and Sentinel Keys Server. These components are required by the cus- tomers using your protected applications. Note: No additional steps are needed to deploy Sentinel Keys License Monitor, unless you are customizing its .class files.
Page 56: Configuration Files
■ Server-side Configuration File (sntlconfigsrvr) Using this file, the system administrator (root user) on the customer site can set these parameters: the network protocol, Sentinel Keys License Monitor HTTP port, Sentinel Keys Server socket port and logging details. Remote Update Options...
Page 57 Frequently Asked Questions Its licenses are neither managed by the Sentinel Keys Server, nor monitored by the Sentinel Keys License Monitor. Question 2 - How can I install and run the Toolkit? For details on installation, please refer to the Release Notes available in the Manuals directory.
Page 58 Chapter 2 – Sentinel Keys SDK Components Sentinel Hardware Keys Developer’s Guide...
Page 59: Chapter 3 - Planning Application Protection And Licensing Strategy
About Features, Templates, and Groups This section explains the concepts of features, license templates, and groups as used in the Sentinel Hardware Keys Toolkit and other components. Features A feature is the most-basic unit of an application protection strategy. The Toolkit assigns a feature ID to every feature created in a license template.
Page 60 8-bit (0 to 255), 16-bit (0 to 65,535), or 32-bit (0 to 4,294,967,295). ❑ Boolean - A data feature that can contain a true or false value. 1. To understand the query-response protection, please see “Implement Query-Response Pro- tection” on page 113. Sentinel Hardware Keys Developer’s Guide...
Page 61 Group A group is a package of licenses (templates) that you want to program in the Sentinel Key for your customers. These groups can be created to meet the packaging and licensing requirements. Note: The license groups are created in the License Manager screen. More information on license grouping is provided in “License Grouping”...
Page 62 Chapter 3 – Planning Application Protection and Licensing Strategy Relating Features, Templates, and Groups Sentinel Hardware Keys Developer’s Guide...
Page 63 In Shell, protective wrappers are put around your application that guard it from unauthorized access. Shell encrypts your original application and will deny access unless the correct Sentinel Key is always present and all the licensing conditions are met. The Shell has multi-layer architecture. The previous layer, if executed suc- cessfully, only will decrypt the successive layer.
Page 64 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>\Sentinel Keys Toolkit\Shell SDK folder for more details. Note: The Shell SDK support is provided only for Windows 32-bit executables and DLLs.
Page 65 When you use API features to protect your applications, you need to add the Business Layer API into your application code. The Business Layer API are the Sentinel Keys API functions—used for com- municating between your application and the Sentinel Key. These API...
Page 66 Sentinel Key. For example, an application might verify the validity of the signed data or send query data to the Sentinel Key and require a specific response in order to continue execution. Other software locks may simply read the data and compare it to the value known.
Page 67 You must create a license template in the License Designer screen to add features to it. Use the License Designer Wizard to create a license template. The Sentinel Keys Toolkit Help provides detailed steps on adding and managing features, templates, and groups.
Page 68: Planning Application Protection And Licensing Strategy
45 and page 47. How many different license templates do you need? This is typically dependent on the number of applications you want to pro- tect. Each license template has a license ID that will distinctly identify it Sentinel Hardware Keys Developer’s Guide...
Page 69 Planning Application Protection and Licensing Strategy when multiple applications are protected using one Sentinel Key. You can create a group of the license templates to be programmed into a Sentinel Key. Which API features will you use? There are seven API features provided in the Toolkit, including AES and ECC.
Page 70 For example, if the Sentinel Key hard limit is 25 and you need to allow for maxi- mum 15 users, then stipulating a user limit equal to 15 meets your requirements exactly.
Page 71 At the time of programming Sentinel Keys. To do so, make sure you ■ keep the Override user limit later check box selected.
Page 72 Are you protecting applications for a stand-alone or network environment? This decision will help you in choosing the type of Sentinel Key you want to ship with your protected application. Please note that a stand-alone key cannot provide licenses to network users; while, a network key can provide licenses to users across LAN/WAN.
Page 73 For Macintosh: Only TCP/IP (SP_TCP_PROTOCOL) is supported. ContactServer Sets the Sentinel Keys Server host (the system where the Sentinel Key is attached). It can be set across LAN and WAN. Multiple entries (up to 10) can be specified, separated using a new line char- acter (the Enter key).
Page 74 SP_MIN_HEARTBEAT = 60 ■ SP_INFINITE_HEARTBEAT = 0xFFFFFFFF ServerPort Sets the Sentinel Keys Server port. Tag Values The default port is 7001. It can be set as a value between 1025 to 65535. Make sure of the following: The port specified is not already in use.
Page 75 ■ Note: The terminal clients can access both the network and stand-alone Sentinel Keys in a network. To allow stand-alone keys (Sentinel S and ST) access, set the SP_ENABLE_TERMINAL_CLIENT flag in the SFNTGetLicense API func- tion. The network keys (Sentinel SN and SNT) can be accessed without any such setting.
Page 76: Frequently Asked Questions
If network resources and timing is an issue for your customers, you may want to set the Sentinel Keys Server host in the SFNTSetContactServer API function or they can set it in the cli- ent-side configuration file.
Page 77 For larger data, you can use the function in a loop. Question 6 - What is the size of data that can be signed/verified? The maximum data length that can be sign/verified is 0xFFFFFFFF. Sentinel Hardware Keys Developer’s Guide...
Page 78 Question 7 - How to specify the number of users for an application/ feature? By default, the number of users is equal to the hard limit of the Sentinel Key. The Sentinel Keys come with the following “standard” hard limits: 3, 5, 10, 25, 50, 100, and 250.
Page 79 Application C has 10 user limit available, only three users can run it. This is because the hard limit is obtained first, then the user limit. ■ You may want to share the licenses for seat users. Sentinel Hardware Keys Developer’s Guide...
Page 80 Chapter 3 – Planning Application Protection and Licensing Strategy Sentinel Hardware Keys Developer’s Guide...
Page 81: Part 2 Designing And Implementing Protection
Part 2 Designing and Implementing Protection Using the Shell protection ❑ Using the Business Layer API protection ❑ Designing remote update strategy ❑ The best practices for secure licensing ❑...
Page 83: Chapter 4 - Protecting Applications Using Shell
Using the License Designer Wizard - This option allows you to create a license template by adding a Shell or API feature to it. Refer to the Sentinel Keys Toolkit Help for complete steps. Note: Quick Shell, shown on the introductory screen, is a gateway to the Toolkit.
Page 84: Add Shell Feature Dialog Box
3. Specify a Shell name (necessary). The constant name will be auto- matically generated. However, you may modify it if needed. 4. You may optionally provide comments for this feature. You can now provide the licensing settings. Sentinel Hardware Keys Developer’s Guide...
Page 85: Providing Licensing Settings
Providing Licensing Settings Add Shell Feature Dialog Box Providing Licensing Settings To provide the licensing settings: 1. Click the Licensing tab in the Add Shell Feature dialog box. Sentinel Hardware Keys Developer’s Guide...
Page 86 Expiration date Specify an expiration date One year from current date (mm/dd/yy format). Expiration time Specify an expiration time 14400 minutes (10 days) (in minutes). Execution count Specify an execution count for running the protected application. Sentinel Hardware Keys Developer’s Guide...
Page 87: Providing Networking Settings
Later, if desired, the marketing/key programming per- sonnel can modify it to suit some customer's requirement (such as, 10/10/07) and program the Sentinel Key. This does not require you to apply the Shell protection again, modify the API calls, or repackage the product.
Page 88 The terminal client option OFF (Terminal Client service Client allows you to shell an disabled) application in a Terminal Service environment. You may now specify the advanced security settings for a Shell-protected application under the Security tab. Sentinel Hardware Keys Developer’s Guide...
Page 89: Providing Security Settings
Non- present malicious users will close the debugger and start the application again. However, if for some reason you want to allow your application to run in the presence of debuggers, select this check box. Sentinel Hardware Keys Developer’s Guide...
Page 90 Setting I have used Select this check box if you used the Shell SDK Shell SDK (available under the \Sentinel Keys Toolkit selected directory) for protecting your important code fragments, constants, and string data. Refer to the readme file available in the folder for details.
Page 91: Customizing Error Messages
You can customize the Shell run-time error messages by clicking the Cus- tomize the shell error messages link, available while adding/editing the Shell feature in License Designer of Sentinel Keys Toolkit. This is an optional step and the default text messages will be shown if you do not mod- ify them.
Page 92: Changing File Encryption Settings
When not-in-use these files remain encrypted. If your application creates one of these files, it will be decrypted only if the correct Sentinel Key is being used to run the application. Though this step is optional for adding a Shell feature, and by default all files, other than .exe and .dll, you selected under...
Page 93 - Encrypted data files for Windows 9x, or - .NET applications for 9x The data protection driver installer can be found in the \Data Protection Sentinel Hardware Keys Developer’s Guide...
Page 94: Applying Shell Protection
Chapter 4 – Protecting Applications Using Shell Driver directory of the Sentinel Keys CD. See also, “Deploying Sentinel Data Protection Driver (Windows Only)” on page 209. Applying Shell Protection After selecting your choices in the Add Shell Feature dialog box, you must now click the Make Shell button.
Page 95 Applying Shell Protection same name, even if selected from different path, are not overwritten during the Shell process and their source path can be tracked easily. Output Files at the Destination Path Sentinel Hardware Keys Developer’s Guide...
Page 96: Shell Protection Using The Command-Line Utility
■ Files to be copied: Before you use the Command-Line Utility on a system on which the Sentinel Keys software installation has not been performed, you must copy certain files/components to it. Following is a list of all possible files/components that you must copy.
Page 97 Using the Command-Line Shell Utility This section provides details on using the Command-line Shell Utility. 1. Attach the Sentinel Hardware key and the Developer key to an avail- able USB port on your system. The developer ID of the Sentinel Key and the Developer Key should be the same as that of the Developer Key that was used to program the created license.
Page 98 CMDShell [/?] [/S] /F LicenseTemplateFilePath [/L1 or /L2 LogFile- Path] [/G or /U file.xml] [/NF] Note: At a time, only an instance of either the Toolkit, or the Command Line Shell utility can be run. Sentinel Hardware Keys Developer’s Guide...
Page 99: What's Next
Description Displays the help. Denotes the silent mode and suppresses all messages sent to the console. Provides the full path of the Sentinel Keys Toolkit license template file LicenseTemplateFilePa to load the license template. /L1 LogFilePath Provides the full path of the log file to generate a brief log.
Page 100 Sentinel Key both attached and missing. Note: If you are testing your protected application in network environment, make sure to restart the Sentinel Keys Server. Sentinel Hardware Keys Developer’s Guide...
Page 101: Frequently Asked Questions
5.0, 6.0, 7.0, 7.1, 8.0 Visual Basic 5.0, 6.0 Visual FoxPro 5.0, 6.0, 7.0, 8.0, 9.0 Borland C++ Builder 6.0, v2006 Borland Delphi 7.0, v2006, v2007 Power Builder 6.0, 7.0, 8.0, 9.0, 10.0, 10.5, 11.0 Sentinel Hardware Keys Developer’s Guide...
Page 102 File Types/Compilers Supported by Shell Compiler/Tool Version Executable DLLs Visual C++ VB .NET 8.0 with .NET Framework version 2.0, and 3.0 8.0 with .NET Framework version 2.0, and 3.0 a. Only any CPU and x86 target binaries are supported. Sentinel Hardware Keys Developer’s Guide...
Page 103 Question 4 - What are the file types 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 ■ Sentinel Hardware Keys Developer’s Guide...
Page 104 Shelling .NET applications, signed with strong names, is not supported. Question 7 - Why do .NET applications protected using Quick Shell and Shell methods fail to run if it uses XML serialization? The prob- lem exists in .NET EXEs only. Sentinel Hardware Keys Developer’s Guide...
Page 105 Please check for the .mui files, located at the location as advised in the example. For more FAQs, refer to the Sentinel Keys Toolkit Help. Question 9 -Are there any special files to be distributed to the end user for applications protected using the .NET enhancement...
Page 106 DLL. Whereas, if the DLL is linked dynamically, it exe- cutes successfully? This is a static linked DLL issue that occurs once you have protected your application. Please follow the following tips while protecting a statically linked DLL to resolve this issue. Sentinel Hardware Keys Developer’s Guide...
Page 107 In case you want to edit the other options, then you have to edit the license via the Sentinel Keys Toolkit, and then use the new license template (*.ltm) file (after programming the license), with the command-line shell tool.
Page 108 Chapter 4 – Protecting Applications Using Shell Sentinel Hardware Keys Developer’s Guide...
Page 109: Chapter 5 - Protecting Applications Using Api
Sentinel Key. You will begin by contacting the Senti- nel Key for a license (SFNTGetLicense API call). Subsequently, you can craft variety of software locks to check the presence of the Sentinel Key, such as encrypting the data using the AES algorithm present in the key. Please refer to the Business Layer API Help to understand the various API functions.
Page 110 2. The code sketch consists of an outline of the Business Layer API functions that you should incorporate in your source code. It is a good reference when you are not sure which API func- tions are relevant for your particular strategy. Sentinel Hardware Keys Developer’s Guide...
Page 111 API functions that can be called. Also, do refer to the best practices described in Chapter 7, “Implementing Secure Licensing,” on page 145. Finally, compile and link your application after including the Sentinel Keys header files and libraries. Apply the Shell Protection (for Windows Applications...
Page 112 Chapter 5 – Protecting Applications Using API Steps for Protecting Applications Using API Sentinel Hardware Keys Developer’s Guide...
Page 113: Adding Api Features
Using the License Designer Wizard - This option allows you to ■ create a license template by adding a Shell or API feature to it. Refer to the Sentinel Keys Toolkit Help for complete steps. Add Feature Dialog Box To obtain the Add Feature dialog box: 1.
Page 114 1. In the License Designer screen, load the template to which the AES feature will be added. 2. Click the API tab. 3. Click Add. The Add Features dialog box appears. 4. Select AES from the list of API features. Sentinel Hardware Keys Developer’s Guide...
Page 115 Refer to the Business Layer API Help for details on the function. Lease Select to allow specifying an Not selected expiration date or expiration time for the application. Else, the application will use a perpetual license. Sentinel Hardware Keys Developer’s Guide...
Page 116 Not selected generating the secret key at the time of programming the Sentinel Key. The random value is generated by the Sentinel Key itself and is not known to you/your application. Selecting this will automatically disable the Secret Key field.
Page 117 Later, if desired, the marketing/key programming per- sonnel can modify it to suit some customer's requirement (such as, 10/10/07) and program the Sentinel Key. This does not require you to apply the Shell protection again, modify the API calls, or repackage the product.
Page 118 Not selected expiration date or expiration time for the application. Else, the application will use a perpetual license. Limit Select to allow specifying the number Not selected executions of times the protected application will run for. Sentinel Hardware Keys Developer’s Guide...
Page 119 Not selected generating the private key and public key pair at the time of programming the Sentinel Key. When generated randomly, the private and public key pair will not be shown in the Toolkit; however, the public key will be written in the header file.
Page 120 Later, if desired, the marketing/key programming per- sonnel can modify it to suit some customer's requirement (such as, 10/10/07) and program the Sentinel Key. This does not require you to apply the Shell protection again, modify the API calls, or repackage the product.
Page 121 Note: You can use the following Business Layer API functions for a Counter fea- ture: - SFNTCounterDecrement - To decrement the Counter value by specified amount on each call. - SFNTReadInteger - To read the Counter value Sentinel Hardware Keys Developer’s Guide...
Page 122 Sentinel Key is programmed. You can specify its length in the String Length field. The random value is generated by the Sentinel Key itself and is not known to you/your application. However, you can call the SFNTReadString API function to read the value.
Page 123 8. If you selected the check box described in step 7, specify the maxi- mum size. It has to be greater than the existing string length and less than 255 ASCII printable characters. The overridden values will never exceed the maximum limit set. Sentinel Hardware Keys Developer’s Guide...
Page 124 Adding Raw Data Feature 1. In the License Designer screen, load the template to which the Raw Data feature will be added. 2. Click the API tab. 3. Click Add. The Add Features dialog box appears. Sentinel Hardware Keys Developer’s Guide...
Page 125 Sentinel Key is programmed. You can specify its length in the Raw Data Length field. The random value is generated by the Sentinel Key itself and is not known to you/your application. However, you can call the SFNTReadRawData API function to read the value.
Page 126 - SFNTReadRawData - To read the Raw Data feature value. - SFNTWriteRawData - To write the Raw Data feature value. Adding Integer Feature 1. In the License Designer screen, load the template to which the Inte- ger feature will be added. Sentinel Hardware Keys Developer’s Guide...
Page 127 Integer type radio buttons. The random value is generated by the Sentinel Key itself and is not known to you/your application. However, you can call the SFNTReadInteger API function to read the value.
Page 128 "licensing values" without modifying the "licensing implementation" in the application/code. The option will be disabled if you have selected the Write-once and/or Write-random option. 9. Provide a name for this feature (necessary). Sentinel Hardware Keys Developer’s Guide...
Page 129 Sentinel Key is programmed. The random value is generated by the Sentinel Key itself and is not known to you/your application. However, you can call the SFNTReadInteger API function to read the value.
Page 130 Update value command. If you selected Write random check box, the value will be written at the time of programming the Sentinel Key. You can read the Integer feature value using the SFNTReadInteger function. Write-once Select this check box if you want to...
Page 131 Note: API functions for Boolean feature You can use the following Business Layer API functions for an Boolean fea- ture: - SFNTReadInteger - To read the Boolean feature value. - SFNTWriteInteger - To write the Boolean feature value. Sentinel Hardware Keys Developer’s Guide...
Page 132: What's Next
Sentinel Key both attached and missing. Note: If you are testing your protected application in network environment, make sure to restart the Sentinel Keys Server after building the license template. Sentinel Hardware Keys Developer’s Guide...
Page 133 SFNTSetContactServer - Sets the Sentinel Keys Server to be contacted for obtaining a license. ❑ SFNTGetLicense - Obtains a license from the Sentinel Key having required developer ID and license ID. ❑ SFNTQueryFeature - Performs the query-response operation and verifies the licensing con- trols.
Page 134: Frequently Asked Questions
Question 3 - Are there any API samples provided? Yes. 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: Sentinel Hardware Keys Developer’s Guide...
Page 135 3. Build it by clicking Build button. The following dialog box will appear on completion of the build process. Take me there Link 4. Click the Take me there link (the dialog box differs across platforms). You are directed to the language-specific directory for the sample, Sentinel Hardware Keys Developer’s Guide...
Page 136 Chapter 5 – Protecting Applications Using API wherein you can compile the sample application and understand the API functions used. Note: For more FAQs and troubleshooting tips, refer to the Toolkit Help. Sentinel Hardware Keys Developer’s Guide...
Page 137: Chapter 6 - Secure Remote Updates
You do not even need to prepare a remote update strategy in advance at the time of license designing. Secure Remote Updates could be of the following two types: Secure Remote Feature/License Update ■ Sentinel Hardware Keys Developer’s Guide...
Page 138: Secure Remote Feature/License Update
The following illustration explains the remote update processes involved in updating Sentinel Keys with feature/license updates, or new license additions. Secure Remote Feature/License Update The Sentinel Keys can be updated for features/licenses using files or e-mails in one of the following ways: ■ Bidirectional Update ■...
Page 139 9. The developer sends the update code (.upw) file using an e-mail to the customer. 10.The customer applies the update code using the secure update utility/ secure update wizard, to have access to the requested applications/ features. Sentinel Hardware Keys Developer’s Guide...
Page 140 They can do so using the Secure Update Utility or a custom option that calls the Secure Update API func- tions. See “Updating Distributor Key Metering Count” on page 182 for details. Sentinel Hardware Keys Developer’s Guide...
Page 141 2. Unidirectional Broadcast Update: The Developer generates the update code without any request code from the end user, and broad- casts the code to all the end users possessing Sentinel Keys with the same DeveloperID. Some exceptions in the unidirectional mode are listed as follows: ■...
Page 142 4. The developer enters the serial number (derived from a database maintained by the developer) of the Sentinel Key targeted for unidi- rectional single target update, in the Token Serial Number field. 5. The developer selects the actions to be performed on the Key. The update actions are listed, corresponding to the License/Feature Action Types, present in the token.
Page 143 4. The developer clicks Generate Update Code to generate an update code (described on page 140). 1.Some features like Counter, AES, ECC, and Lease are restricted for selection, from the action list while generating *.upw file in unidirectional mode. Sentinel Hardware Keys Developer’s Guide...
Page 144 Chapter 6 – Secure Remote Updates 5. The developer sends the update code (.upw) file using an e-mail to the customer. 6. The customers apply the update code to have access to the requested applications/features. Unidirectional Broadcast Remote Update Process Sentinel Hardware Keys Developer’s Guide...
Page 145: Secure Remote New License Addition
(*.nlf) file. The following section explains the processes involved in new license additions into the end user tokens. Remote New License Addition Process The Sentinel Keys can be updated for new licenses in one of the following ways: ■ Bidirectional New License Addition Unidirectional New License Addition ■...
Page 146 3.The Device Update Counter, stored in the .req file in bidirectional mode, is needed when the developer wants to delete all licenses from the Sentinel Key, before loading new licenses. Sentinel Hardware Keys Developer’s Guide...
Page 147 2. In License Manager, the developer clicks the Export-File Manager icon ) to open the Export-File Manager wizard. 3. In the Export-File Manager wizard, he selects Export a file for License Addition. (Allows creation of *.NLF) option, and clicks Next. Sentinel Hardware Keys Developer’s Guide...
Page 148 ID. The developer is restricted to delete all licenses from tokens, in this mode, before loading a license. 5.In unidirectional mode, you need to keep track of this value while sending the update codes. Sentinel Hardware Keys Developer’s Guide...
Page 149: Remote Update Codes
Secure Update Utility/ Wizard, or the SFNTApplyUpdateCode () function of Secure Update Library. The *.nlf file is generated using the Export-File Manager under the License Manager stage of the Toolkit. Sentinel Hardware Keys Developer’s Guide...
Page 150: Remote Update Methods
The Buy button prompts your customer for the necessary ■ information and completes the product activation. Note: The Secure Update Wizard is localization ready. You can translate the wiz- ard text and messages—currently in U.S. English—into a language of your Sentinel Hardware Keys Developer’s Guide...
Page 151 Remote Update Methods choice. Refer to the Sentinel Keys Toolkit Help for complete details on integrating the Secure Update Wizard with your Shell or API-protected application. Also, Chapter 10, “Redistributables for Customers and Distributors,” on page 197 describes what to ship along with your protected application to allow remote updates.
Page 152 (.nlf) in response, which can be applied by the customer/distributor using the same utility. Note: Since, the .upw file generated by Sentinel Hardware Keys version 1.2 will not be applied using the Secure Update library of version 1.0, please make sure that you distribute the latest Secure Update Utility and associated DLLs to your customer/distributor.
Page 153 A developer may instead create a customized remote update option using the Secure Update API functions implemented in SecureUpdate.h. It is avail- able at the following path in your Sentinel Keys SDK installation: ■ For Windows: <installdir>\Secure Update\Secure Update Utility\INTF.
Page 154: About Remote Update Actions
Chapter 6 – Secure Remote Updates About Remote Update Actions To be able to update Sentinel Keys and distributor keys in the field, you must define the update actions under the Add Actions tab of the Update Man- ager screen.
Page 155 Replaces the existing secret key with the value you specify. Overwrite Replaces the existing execution count value ❑ execution count with the value you specify. ❑ Increment Increments the existing Counter feature value ❑ execution count by the amount you specify. ❑ Sentinel Hardware Keys Developer’s Guide...
Page 156 The name should be concise, yet descriptive, so the people generating update codes can easily see how the hardware key will be updated. 6. You may optionally include comments for the action in the Com- ments edit box. 7. Click OK to add the action. Sentinel Hardware Keys Developer’s Guide...
Page 157 1. In the Update Manager screen, load the license template for which the actions are to be created. 2. Under Action Types, select the Sentinel Key radio button. 3. Click Add. The Add action for Sentinel Key dialog box appears. Shown below are commands applicable to Sentinel Keys: Command...
Page 158: Generating Update Codes
The following section explains the Sentinel Key details you must know for generating an update code file (.upw) or a new license addition file (.nlf): Sentinel Hardware Keys Developer’s Guide...
Page 159 Key Serial Number targeted for a single target update. Unidirectional Broadcast Update: Requires the common ❑ Developer ID for all the Sentinel Keys targeted for a unidirectional broadcast update. Note: In all of the above modes, the cheat counter value can be specified in the Cheat Counter (only for non-RTC keys) field, before generating the *.nlf file.
Page 160: Frequently Asked Questions
❑ Unidirectional Single Target License Addition: Requires the following information by the developer, to generate the .nlf, new license addition code file: Serial Number of the Sentinel Key in field, targeted for a single ❑ target license addition ❑ The Device Update Counter value for formatting the Key before loading a license.
Page 161 Question 6 - Can Secure Update Utility of version 1.0 apply the *.upw file generated by SHK1.2? No, since the .upw file generated by Sentinel Hardware Keys version 1.2 will not be applied using the Secure Update library of version 1.0, please ensure that you distribute the latest Secure Update Utility and associated DLLs to your customer/distributor.
Page 162 Its value is also updated in the following scenarios: ■ Cheat counter value updates. ■ Last known date and time (LKDT) updates, once the lease operation has been performed. ■ User limit value updates. Sentinel Hardware Keys Developer’s Guide...
Page 163: Chapter 7 - Implementing Secure Licensing
Otherwise, even the strongest lock can be easily defeated. Sentinel Key provides the best software protection system available today. However, like the auto manufacturer, you must take the time to properly implement the system or it will be bypassed.
Page 164: Vulnerability Assessment - Basic Types Of Attacks
Before you can plan a good protection strategy, you need to understand the type of attacks targeted at breaking licensing. The diagram below shows the vulnerable points typically targeted for attacks: Basic Types of Attacks Sentinel Hardware Keys Developer’s Guide...
Page 165 System time tampering or rolling back of the system clock is one of the most- common way of license infringement for lease/trial applications. To address this, you can use Sentinel Key with real-time clock. It contains a tamper- resistant internal real-time clock that indicate the exact date and time to track the usage of the leased applications.
Page 166 If the system clock is corrected, normal tampered for more than 30 are disabled—regardless functionality can be resumed. days of the cheat counter value. a. Refers to the duration between the plug-in and plug-out of the Sentinel Key. Sentinel Hardware Keys Developer’s Guide...
Page 167: Tips And Tricks
Sentinel Key. Query-response protection is a challenge-response like technique driven by the AES algorithm programmed in the Sentinel Key. The application sends a query to the Sentinel Key, which sends a response calculated using the AES Sentinel Hardware Keys Developer’s Guide...
Page 168 Using the SFNTQueryFeature API on an AES feature programmed into the Sentinel Key allows your application to issue a nearly infinite amount of unique challenges. This mechanism becomes the backbone of your protec- tion strategy since it is extremely difficult to duplicate the correct responses.
Page 169 Tips and Tricks Create a Large Query/Response Table If your application only knows a few challenges to issue to the Sentinel Key, then it becomes easier to predict them. However, a large table will take a long time to use every possibility; thereby increasing the time taken to emu- late every possible challenge.
Page 170 You can specify a cheat counter value only for non-RTC Sentinel Keys. The cheat counter value is global to the Sentinel Key. It applies to all the fea- tures having lease attribute enabled. You can specify a the cheat counter value right before programming hardware keys in the License Manager screen.
Page 171 Sentinel Key is assumed to be present. It becomes impossible to replicate these results by skipping the Sentinel Key because all the operations are performed in the hardware. SFNTEncrypt and SFNTDecrypt Operations...
Page 172 1. Generate a random message. 2. Call the SFNTSign API function to sign this message using the private key is stored secretly in the Sentinel Key. 3. Call the SFNTVerify API function to verifies the signature using the known public key of the token. If the function returns success, the correct Sentinel Key is assumed to be present.
Page 173 You can implement a similar signature verification scheme for your digital content (such as, text files and images) and store the 42-bit signature as raw data in the Sentinel Key memory. Decentralize Your Security Checks Decentralizing the security checks throughout the code is a good practice.
Page 174 13.0. Assume that one of the query strings you send to the key returns the decimal number 12,345. Set the floating variable to -12,332.0. ■ Send the query. ■ Add the response to the variable. ■ Sentinel Hardware Keys Developer’s Guide...
Page 175 API functions will return errors. Refer to the Business Layer API Help for exact status codes. If your application detects that the Sentinel Key is not present, it is up to you to decide what action you want to take. Typically, you should not shut down your application because of a single unexpected response.
Page 176 Note: For more personalized assistance in integrating the security checks in your application, please contact our Technical Support using the information given on page xv. Sentinel Hardware Keys Developer’s Guide...
Page 177: Frequently Asked Questions
The query-response pairs are available in the header file generated under the Build Options tab. These are written in the hexadecimal format. You can convert it into ASCII format using the method described below (sample): Sentinel Hardware Keys Developer’s Guide...
Page 178 Chapter 7 – Implementing Secure Licensing Sample Conversion of Hexadecimal into ASCII Sentinel Hardware Keys Developer’s Guide...
Page 179: Part 3: Grouping Licenses And Programming Hardware Keys
Part 3 Grouping Licenses and Programming Hardware Keys License grouping and management ❑ Programming Sentinel Hardware Keys using Sentinel Keys ❑ Toolkit and the Key Programming APIs...
Page 181: Chapter 8 - License Grouping
The ability to bundle license templates into groups allows you create inno- vative licensing models in the most straight-forward manner. Using groups you can: Program multiple licenses into a single Sentinel Key in just a few ■ clicks. Because each license is independent of the other, the Sentinel Key makes it possible for you to offer products for both enterprise-level and small-scale customers.
Page 182 For example, the AppSoft marketing team can now roll different editions of their applications, at different times—without engineering's assistance. In fact, for bulk orders the Sentinel Key programming activity can be delegated to your Sentinel Key vendor (see “Creating WPS File” on page 182).
Page 183: Creating New Groups
1. Before you move to the License Manager screen, use the License Designer screen to build all of the templates you plan to use. Make sure that both the developer key and Sentinel Key are attached to the system. 2. In License Manager, click the first icon (beside the license group name).
Page 184: Loading Groups
2. Select the group you want to load currently. 3. Click Load. The loaded group is shown in the group layout. Duplicating Groups You may duplicate groups to copy the settings. To duplicate a group: Sentinel Hardware Keys Developer’s Guide...
Page 185: Removing Groups
To create a file for your distributor: 1. In License Manager, click the first icon (beside the license group name). The Group Management dialog box appears. 2. Select the group you want to send. Sentinel Hardware Keys Developer’s Guide...
Page 186: Viewing Group Layouts
5. Provide the same File Encryption Key (FEK) used earlier (when you programmed the distributor key, see page 180). 6. Click OK. Viewing Group Layouts The group layout shows the license group currently loaded, its templates, features (default and new), and memory requirement. Group Layout Sentinel Hardware Keys Developer’s Guide...
Page 187: Modifying Default Feature Instances
Creating New Feature Instances Note: Only the license templates selected using check boxes will be programmed in the Sentinel Key/distributor key. By default, all the license templates are selected. If the memory size of the group has exceeded that of hardware key, an error will be shown at the time of programming.
Page 188: Add Templates To Groups
4. Click Add. When done, you are brought back to the License Man- ager screen. Remove Templates From Groups You can remove templates from a group created already. Here are the steps to do so: Sentinel Hardware Keys Developer’s Guide...
Page 189: Export-File Manager
Define/view additional comments by clicking the Add comments to the file hyperlink. Note: For more information on the Export-File Manager wizard process, please refer to the Sentinel Keys Toolkit Help. Sentinel Hardware Keys Developer’s Guide...
Page 190: Locking/Unlocking Groups
You will need to unlock the group in order to load it. For an Unloaded Group 1. Click Load button under the Group Management dialog box. A small dialog box will appear asking you to provide the password. 2. Specify the password. 3. Click OK. Sentinel Hardware Keys Developer’s Guide...
Page 191: Frequently Asked Questions
“adding a new instance? Updating a default feature instance allows you to modify the licensing set- tings right-before programming a batch of Sentinel Keys. This modification does not affect your protection implementation at the application-level. For example, you can specify 999 executions instead of 99, without generating the header file again, or applying the Shell protection again, and so on.
Page 192 For example, you might want to change the expiration date. Select the default feature in the group layout to view the update option (see the screen-shot below). Modify the licensing value (such as, the Expiration Date) and click Update to save the modifications. Sentinel Hardware Keys Developer’s Guide...
Page 193 If you had selected the Add instances later check box while creating that feature in the License Designer screen, you will see the Add button enabled in the right-side panel. Modify the licensing values and click Add to create the new feature instance. Sentinel Hardware Keys Developer’s Guide...
Page 194 No. A distributor can only receive the groups created by you. The stand- alone Sentinel Keys License Manager application does not allow modifying the licensing values (see the screen-shot below, where a distributor can only choose the number of Sentinel Keys to be programmed in a batch). Sentinel Hardware Keys Developer’s Guide...
Page 195 This could happen when the license template was updated in the License Designer screen but was not built to reflect the changes. Build the license template in the License Designer screen to enable the check box shown beside the template name. Sentinel Hardware Keys Developer’s Guide...
Page 196 Chapter 8 – License Grouping Sentinel Hardware Keys Developer’s Guide...
Page 197: Chapter 9 - Programming Sentinel Hardware Keys
This chapter describes how to program the Sentinel Keys and distributor keys in the License Manager screen in the Sentinel Keys Toolkit. It also briefs on the steps to program the Sentinel Keys using the Key Pro- gramming APIs. Programming Sentinel Keys using Sentinel Keys...
Page 198 USB ports on your sys- tem. 6. Specify the Cheat Counter value. It will be global for the Sentinel Key (applicable only to non-RTC Sentinel Keys). 7. Click Make Keys. Please do not attach/detach keys from the port/ hub while the process is going on.
Page 199 Sentinel Keys. 7. Attach a single distributor key you purchased from SafeNet to your USB port/hub (it is not same as developer key or Sentinel Key). 8. Click Make Distributor Key. 9. Specify a path to write the group file (.lgx) for your distributor.
Page 200 Creating WPS File If desired, you can also write a .wps file for your Sentinel Key vendors. Using the .wps file they can program Sentinel Keys in bulk for you.
Page 201 Programming Sentinel Keys using Sentinel Keys Toolkit 1. Load the group from the Group Management dialog box. 2. In the layout, select the required licenses (templates) using the check boxes. You can create a file containing multiple licenses (having one instance per feature).
Page 202: Programming Sentinel Keys Using The Key Programming Apis
Sentinel Keys in bulk. The Key Programming APIs enable you to create your own programming utility or a stand- alone executable to program each Sentinel Key with the license group file exported using the Export-File Manager wizard in the License Manager of Sentinel Keys Toolkit.
Page 203 This file is programmed onto the end user token at the fulfillment center. a.An individual or a software development company that uses the Sentinel Keys SDK to protect and license their applications. Sentinel Hardware Keys Developer’s Guide...
Page 204 Chapter 9 – Programming Sentinel Hardware Keys b.An individual/organization authorized by the developer to distribute the protected application along with the Sentinel Keys c.An individual/group who is unaware of the contents, and is more concerned about the number of tokens being programmed using the programming utility/stand-alone executable provided to him by a developer.
Page 205 Step 2 - Implementing the Key Programming APIs into your Solution Once you have successfully exported the License Group file (*.ISV/*.DIS/ *.OPR) onto your system, you need to program the Sentinel Key with the exported file. The Sentinel Keys are programmed with the *.ISV/*.DIS/*.OPR file informa- tion, using the Key Programming API library.
Page 206: Frequently Asked Questions
Question1 - How would I know if the group I created exceeds the amount of memory available in the Sentinel Key? In case the size of the group exceeds the memory size of your sentinel key, then you will get the error (stating that your key does not have sufficient memory to program the group) while programming the key.
Page 207 Yes. Question 5 - Are there any log files created at the time of program- ming hardware keys? Yes. The following log file are created when the Sentinel Keys and distribu- tor keys are programmed: ■ EndUserLog.xml - For Sentinel Keys ■...
Page 208 Chapter 9 – Programming Sentinel Hardware Keys Question 6 - Is Sentinel Keys Toolkit the only utility using which I can program my Sentinel Keys? No. You have several other options for doing so. Sentinel Hardware Keys offer different interfaces for programming that enable a quick and easy implementation of your protection strategy.
Page 209 Frequently Asked Questions The table below provides a summary (description) of each programming component and the category of users using them. Various Programming Interfaces for Sentinel Keys Programming Utility User Associated File/Key Usage Description Sentinel Keys Developer Developer Key Refer to “Programming...
Page 210 Chapter 9 – Programming Sentinel Hardware Keys Question 7 - What do I need Key Programming APIs for? Key Programming API (Setup) library can be used for two purposes: 1. Programming the license information generated by Toolkit. 2. Updating the instance values of features, based on conditions.
Page 211 Question 15 - I get an error while programming the distributor file. What is this? Please refer to the error code descriptions for the source of the error and its description. The error codes have been listed down in the Key Programming API Help. Sentinel Hardware Keys Developer’s Guide...
Page 212 Chapter 9 – Programming Sentinel Hardware Keys Sentinel Hardware Keys Developer’s Guide...
Page 213: Part 4: Distributing Protected Applications
Part 4 Distributing Protected Applications Checklist of redistributables for customers and ❑ distributors Information on deploying the redistributables ❑...
Page 215: Chapter 10 - Redistributables For Customers And Distributors
■ Customers who will be using the protected applications. ■ Distributors who will be programming the Sentinel Keys for customers. Please make sure that you are familiar with your application’s licensing and protection strategy, so that you can choose the appropriate items for deployment.
Page 216 Configuration file For setting up the host to be contacted, (client) network protocol, heartbeat interval, and Sentinel Keys Server socket port on the client-side (application) Secure Update Utility For updating hardware keys in the field and its Help Secure Update Wizard...
Page 217: Deploying Sentinel System Driver
Each distributor requires a different pair of distributor key and group file (.lgx). Deploying Sentinel System Driver When to Deploy? Sentinel System Driver is the USB device driver for using the hardware keys. It must be redistributed to all customers and distributors. Where to Deploy? The Sentinel System Driver must be deployed on the system where the hard- ware key is attached (whether stand-alone or network key).
Page 218 For stand-alone environments, you can use the SentinelSystemDriver.pkg, available in the SDK CD. This will only install the Sentinel System Driver and related files. This installer will also install an uninstallation script at: /Appli- cations/SafeNet Sentinel/Common Files/Sentinel System Driver/.
Page 219: Deploying Sentinel Keys Server
Where to Deploy? The Sentinel Keys Server must be installed on the networked system where the Sentinel Key is attached. For platforms supported and installation path, refer to “Sentinel Keys Server” on page 33.
Page 220: Deploying Secure Update Utility
For Macintosh: <installdir>/Configuration File Template. ■ Note: The Sentinel Keys Server configuration file is deployed along with the Sen- tinel Keys Server in its installation directory. You need not ship it sepa- rately. However, you may provide instructions to your customers on how to set parameters in the configuration files.
Page 221 Where to Deploy The Secure Update Utility must be installed on the same system where the Sentinel Key/distributor key is attached. This is because the hardware keys cannot be updated over network. Be sure to modify your installation pro- grams appropriately.
Page 222: Deploying Secure Update Wizard (Windows Only)
When to Deploy? The Secure Update Wizard need to be deployed on a Windows-based cus- tomer’s system only if you are planning to update Sentinel Keys remotely and not using the Secure Update utility or API functions. Where to Deploy The Secure Update Wizard must be installed on the same system where the Sentinel Key is attached.
Page 223 .cab: The compressed file for the template. ■ ■ UPWITF.dll: A DLL that exports the UpdateWizard API. You can obtain its copy from the following location in your Sentinel Keys SDK installation: <installdir>\Secure Update\Update Wizard\INTF. UpdateWizard API Function Format unsigned short UpdateWizard (SPP_UPDATE_WIZARD_INFO p_UpdInfo);...
Page 224 SP_ERR_UPDATE_WIZARD_USER_CANCELLED The application was canceled when the try/buy option is shown. Applicable only to applications that use Sentinel Update Wizard and are protected using Shell. SP_ERR_INVALID_DLL_VERSION The Secure Update DLL version is invalid. It can be 1.0 or 1.2 only.
Page 225 Update Wizard. It is passed to the function UpdateWizard to run the Update Wizard. Format typedef struct SP_UPDATE_WIZARD_INFO DWORD size; DWORD wndHandle; long spawnAndWait; long enableTryButton; long daysLeft; long executionsLeft; long minutesLeft; char configFile[SP_MAX_PATH_LEN]; Sentinel Hardware Keys Developer’s Guide...
Page 226 Define a value of 0 to indicate that the trial period has expired and –1 or undefined to disable this feature. This option is only valid when enableTryButton is set to ENABLE_TRY_BUTTON. Sentinel Hardware Keys Developer’s Guide...
Page 227: Deploying Sentinel Data Protection Driver (Windows Only)
Deployment of Sentinel Data Protection Driver is required only for Windows 98/ME systems. If you have shell protected encrypted data files or .NET applications, then you need to deploy the Sentinel Data Protection Driver on your customer’s system. Where to Deploy? It must be deployed in the /System folder on the system where the protected application is installed.
Page 228 Chapter 10 – Redistributables for Customers and Distributors How to Deploy The \Data Protection Driver directory in the Sentinel Keys SDK CD consists of the following files: File Description Instdrvr.exe The Data Protection driver installer. Instdrvr.c C source code of the Instdrvr.exe utility for you. You can use it to customize the driver installation and registry modification procedure.
Page 229: Deploying Stand-Alone License Manager
-1. Deploying Stand-alone License Manager When to Deploy You need to provide the stand-alone License Manager application to your product distributors/resellers, so that they can program Sentinel Keys for the customers on their own. Sentinel Hardware Keys Developer’s Guide...
Page 230 USB hubs, cables, and connectors to attach multiple USB keys on your system. ❑ PDF File Viewer Adobe Acrobat 4.0 or higher (to view this - CD-ROM if installing using a CD. readme and other PDF files) Sentinel Hardware Keys Developer’s Guide...
Page 231: Deploying System Administrator's Help
Deploying System Administrator’s Help How to Deploy An installer is included in the Sentinel Keys installation CD using which, your distributors can install the following components: ■ The License Manager application ■ The License Manager Help file Java 2 Run-time Environment (version 1.6) ■...
Page 232: Frequently Asked Questions
For Linux <installdir>/manuals/english/SysAdminHelp For Macintosh <installdir>/Manuals/English/SysAdminHelp Frequently Asked Questions Question 1 - Where is the Sentinel System Driver installed? Can I modify its location? The Sentinel System Driver is installed at the following location. Its location cannot be modified: ■...
Page 233 On Linux: /opt/safenet_sentinel/common_files/sentinel_usb_daemon ■ On Macintosh: /System/Library/Extensions ■ Question 2 - Where is the Sentinel Keys Server installed? Can I mod- ify its location? The Sentinel Keys Server is installed at the following location. Its location cannot be modified: Installed at the following path on a Windows 32-bit NT-based system: ■...
Page 234 Question 4 - What are the options available for using the Sentinel Protection Installer in a Windows Installer based installation program? You can use the Sentinel Protection Installer in the following ways to install Sentinel System Driver and/or Sentinel Keys Server. ■...
Page 235 Sentinel Protection Installer themselves from http://www.safenet-inc.com/support/tech/sentinel.asp. A copy of the self-extracting installer is available at: <installdir>\Sentinel Protection Installer\English\Internet Installer. For additional information, refer to the Sentinel Protection Installer Help. Sentinel Hardware Keys Developer’s Guide...
Page 236 Chapter 10 – Redistributables for Customers and Distributors Sentinel Hardware Keys Developer’s Guide...
Page 237: Appendix A Troubleshooting
■ The SafeNet Knowledge Base at http://c3.safenet-inc.com/search.asp ■ Sentinel Keys Toolkit Help, integrated with the Toolkit, for a list of Shell and API specific error codes. Problems and Solutions Problem: Time/Date Tampering You are using Sentinel Keys Toolkit to shell an application with a Lease License, and Make Keys works successfully.
Page 238 Problem: Updating Keys You are using Sentinel Hardware Keys for protecting two applications and each application is set up with a different license template (the first applica- tion uses License template A, and the second application uses License template Customer 1 purchases the first application.
Page 239 Problems and Solutions Yes, Sentinel Hardware Keys Secure Update allows you to activate and add user licenses to the key. Refer to, “Secure Remote New License Addition” on page 127. Problem: Protecting .EXE and .Dll files using a Com- mand Line Interface You want to use a command line interface for protecting the exe and dll files.
Page 240 Sentinel Protection Installer 7.4.0.exe ■ Sentinel Protection Installer 7.4.0.msi ■ setup.exe Problem: Accessing Sentinel Hardware Key on a differ- ent network subnet You want to access a Sentinel Hardware Key on a different network subnet. Solution: Sentinel Hardware Keys Developer’s Guide...
Page 241 Note: This applies to networked implementation of security only. Problem: Monitoring Sentinel Hardware Keys licenses in Use You want to monitor Sentinel Hardware Keys licenses that are in use on the key server. Solution: You can do the same by connecting to http://localhost:7002, or http://...
Page 242 Keys Server You want to upgrade the Sentinel USB Driver and Sentinel Keys Server. Solution: Use the following steps to upgrade the Sentinel USB Driver and Sentinel Keys Server: 1. Verify that the USB or parallel port is working correctly.
Page 243 Note: If you are using standalone applications, you can perform a custom install and uncheck both the servers from the installation. The Sentinel Keys Server only needs to be installed on a Sentinel Hardware Keys server com- puter. The Sentinel Protection Server only needs to be installed on a Super- Pro and/or UltraPro key server computer.
Page 244 Appendix A – Troubleshooting loadserv.exe. Specify the service name, <OS Drive>:\Program Files\Common Files\SafeNet Sentinel\Sentinel Keys Server\ sntlkeyssrvr.exe and click Remove Service. Problem: Selecting .Net Framework version When protecting a .NET application with multiple versions installed, you want to select the version of .Net Framework to be used.
Page 245 Solution: Use the following series of steps to build multiple applications to a single key: 1. In License Designer of Sentinel Keys Toolkit, create a template for each application. 2. In License Manager, create a group that includes both the templates.
Page 246 Appendix A – Troubleshooting 1. In License Designer of Sentinel Keys Toolkit, create a shell template for the shelled application. 2. Create an API template for the integrated application. 3. In License Manager, create a group that includes both the templates.
Page 247 ■ This error may also occur when the server port is already in-use. You can verify this in the system EventLog or the Sentinel Keys Server error log file. To troubleshoot this, you can set a non-busy port in the server-side configuration file to run the Sentinel Keys Server.
Page 248 (for 32-bit application executable) or relLic64.dll (for 64-bit appli- cation executable) in the directory that contains the application executable. This DLL can be obtained from \Sentinel Keys Toolkit directory of the Senti- nel Keys SDK installation. Problem: .NET applications protected using Quick Shell...
Page 249 For example, for an English version of vista, if the protected Note- pad.exe resides in C:\ protected then the .mui files must reside at the same location inside the en-US folder. Please check for the .mui files, located at the location as advised in the example. Sentinel Hardware Keys Developer’s Guide...
Page 250 If you suspect a technical problem, contact SafeNet Technical Support to help you in troubleshooting. The support representative will work with you to rule out resolvable software and/or configuration problems. If the prob- lem cannot be resolved, you will be issued a RMA (Return Material Sentinel Hardware Keys Developer’s Guide...
Page 251 You get an error while programming the distributor file, using the Key Pro- gramming APIs. Solution: Please refer to the error code descriptions for the source of the error and its description. The error codes have been listed down in the Key Programming API Help. Sentinel Hardware Keys Developer’s Guide...
Page 252 Appendix A – Troubleshooting Sentinel Hardware Keys Developer’s Guide...
Page 253: Appendix B Glossary
You can use it through the AES feature to encrypt/decrypt 16-bytes of data. Short for Application Program Interface. The set of client interface routines your application uses to communicate with the Sentinel Key. Sentinel Hardware Keys Developer’s Guide...
Page 254 Business Layer API Refers to the Sentinel Keys client library API functions—used for communi- cating between your application and the Sentinel Key. See page 47 and page 115 for more information. A separate Business Layer API Help is also Sentinel Hardware Keys Developer’s Guide...
Page 255 (you can launch it from the Help menu of the Sentinel Keys Toolkit). Cheat Counter A count-down value that allows tolerating the time tampering attacks rang- ing between 1 second to 30 days (excluding the daylight savings) till it reaches zero.
Page 256 The conversion of encrypted data into plain text data (the original form), so it can deciphered by the intended recipients/process. Developer An individual or a software development company that uses the Sentinel Keys SDK to protect and license their applications. Developer ID A unique identification code for the hardware keys provided by SafeNet to the developer.
Page 257 Distributor An entity/organization authorized by the developer to distribute the pro- tected application along with the Sentinel Keys. They can also program Sentinel Keys using the License Manager (stand-alone) application. Distributor Key The hardware key that your distributor requires to use the License Manager (stand-alone) application.
Page 258 Appendix B – Glossary End User Token The Sentinel Key, used to protect the applications, being used by an individ- ual or an organization. Execution Count The number of times the application will run for. It can be a value between 1 and 65535.
Page 259 Refer to the topic “ About Features, Templates, and Groups” on page 41 for details. Short for File Encryption Key. Refers to a 16-byte AES secret key used for encrypting/decrypting the license group file (.lgx) sent to your distributor. Sentinel Hardware Keys Developer’s Guide...
Page 260 Appendix B – Glossary Feature Attributes An attribute defines the properties of a feature. Refer to the Sentinel Keys Toolkit Help for a list of feature attributes. Feature ID An identifier of a feature in the license template. It is assigned by the Toolkit while a feature is created.
Page 261 The hard limit is the factory-programmed limit that defines the maximum number of users allowed by the hardware key. Sentinel Keys are available with the following hard limits: 3, 5, 10, 25, 50, 100, and 250. Sentinel Keys with 0 hard limit are known as stand-alone keys.
Page 262 Key Programming APIs A set of API functions that enable you to create your own programming util- ity or a stand- alone executable to program each Sentinel Key with the license group file exported using the Export-File Manager wizard in the License Manager of Sentinel Keys Toolkit.
Page 263 A 16-bit identifier generated by the Toolkit for the license template you created. It is written into the Sentinel Key memory at the time of programming. The SFNTGetLicense function makes use of the license ID and developer ID for finding your Sentinel Keys on the customers' site.
Page 264 Network Applications A network application is designed to be run on multiple computers so that several users can run it concurrently. You should attach the Sentinel Key on a networked system, where the Sentinel Keys Server and Sentinel System Driver are also installed.
Page 265 Cryptography based on methods involving a public key and a private key. Query Data The data scrambled using the AES algorithm in the Sentinel Key. You pro- gram your application to send queries to the Sentinel Key. The Sentinel Key scrambles the string using the AES algorithm and returns a response to the application.
Page 266 Response Data The scrambled result derived when the Sentinel Key processes the query data using the AES algorithm. The Sentinel Key returns the response data to the application. The application then uses the response to determine whether the user is authorized to run the application.
Page 267 The hardware key meant to be used by your customer in order to run the protected application. It can be attached to a stand-alone or network system depending the key type. A Sentinel Key can be programmed by you (the developer) or your distribu- tor with a license group. Sentinel System Driver The Sentinel System Driver is the device driver for communicating with the hardware keys (Sentinel Key, developer key, and distributor keys).
Page 268 A decision point in a protected application. The purpose of a software lock is to verify the presence of the correct Sentinel Key. For example, an applica- tion might verify the validity of the signed data or send query data to the Sentinel Key and require a specific response in order to continue execution.
Page 269 Stand-alone Keys Refers to the Sentinel Keys with zero (0) hard limit. It is typically connected to a user’s local workstation, providing access to the protected application only on a single system.
Page 270 The Developer generates this code (Feature/License update [.upw], or New License Addition [.nlf]) without any request code from the end user, and broadcasts the code to all the end users possessing Sentinel Keys with the same DeveloperID. Unidirectional Single Target Code Generation The Developer generates this code (Feature/License update [.upw], or New...
Page 271 USB peripherals. With USB-equipped PCs and peripherals are automatically configured and ready for use. Sentinel Keys are USB 2.0 compliant. User limit A soft limit that restricts the number of users allowed by the hard limit. Oth- erwise, the number of users allowed is equivalent to the hard limit.
Page 272 Key Programming API library. Only a Developer, along with a Developer Key, and in the presence of an end user token, can generate this file. This file is programmed onto the end user token at the fulfillment center. Sentinel Hardware Keys Developer’s Guide...
Page 273: Appendix C Sentinel Keys Hardware Specifications
Appendix C Sentinel Keys Hardware Specifications This appendix contains details about the Sentinel Key hardware. Sentinel Key - S (Standard) Hardware Specifications EMC and Product Safety Compliance Part 15, Subpart B, CLASS B EN55022: 1998, CLASS BEN55024: 1998, CLASS B VCCI CAN-CSA V3/2001.04 (VCCI)CISPR 22:1997, CLASS B...
Page 274 Appendix C – Sentinel Keys Hardware Specifications Sentinel Key - S (Standard) Hardware Specifications (Continued) Depth 2.192" Weight 0.23 ounces/6.5g Electrical Characteristics Operating Voltage 4.0V - 5.5V Static Current 60mA max Operating Current 60mA max Suspend Current 1mA typ. 1.5mA max...
Page 275: Appendix D Migration From Superpro And Ultrapro
Stage 1 - Distribute Sentinel Dual Hardware Keys In Stage 1, you will be creating a customer-base for Sentinel Hardware Keys by distributing Sentinel Dual Hardware Keys instead of SuperPro or Ultra- Pro. These keys have support for your current protection scheme (SuperPro or UltraPro) and enable seamless migration to your future protection scheme (Sentinel Hardware Keys).
Page 276 Sentinel Dual Hardware Keys are available for stand-alone and network versions ❑ Sentinel Dual Hardware Keys have 256 cells of memory for use by your SuperPro or UltraPro implementation so you will receive a new model number with your kit 2.
Page 277: Stage 2 - Design New Protection Strategy
Hardware Keys can function as Sentinel Hardware Keys to support your latest software release. You will need to ship them: 1. The upgrade licenses can be generated using a higher version of Sentinel Keys Toolkit (to be released later in this year).
Page 278 (using Secure Update utility or any other custom action), the Dual key will support Sentinel Hardware Keys-dependent applications. These license codes can be applied universally to the Sentinel Dual Hardware Keys distributed in stage 1. New Customers Who Do Not Have Sentinel Dual Hardware ■...
Page 279: Index
46 distributor Utility 10, 24, 78 API 235 distributor key 180, 239 options 81 API Explorer redistributables 197 pre-requisites 78 about 22 distributor key 39 using 79 API protection 47–118 configuration file API samples 116 Sentinel Hardware Keys Developer’s Guide...
Page 280 106 heartbeat 243 limit executions, read-only, attribute 107, Help attribute 68 System Administrator’s redistributables 197 Help 213 regulations, export xviii hexadecimal 160, 243 MAC address 246 remote updates hiding import symbols 72 metering count, distributor Sentinel Hardware Keys Developer’s Guide...
Page 281 Sentinel Keys Protection adding 104 Installer 199 symmetric key 251 Sentinel Keys SDK components 17 Sentinel Keys Server 33, template, license 43, 49, 114, 245 Sentinel Protection terminal client 47 Installer 37, 199–200 tips and tricks 145–160 Sentinel Hardware Keys Developer’s Guide...
Page 282 Index Sentinel Hardware Keys Developer’s Guide...

SafeNet Sentinel Developer's Manual

Preface

Part 1 Sentinel Key Basics

Chapter 1 - Introduction

Chapter 2 Sentinel Keys SDK Components

Chapter 3 - Planning Application Protection and Licensing Strategy

Part 2 Designing and Implementing Protection

Chapter 4 - Protecting Applications Using Shell

Chapter 5 - Protecting Applications Using API

Chapter 6 - Secure Remote Updates

Chapter 7 - Implementing Secure Licensing

Part 3: Grouping Licenses and Programming Hardware Keys

Chapter 8 - License Grouping

Chapter 9 - Programming Sentinel Hardware Keys

Part 4: Distributing Protected Applications

Chapter 10 - Redistributables for Customers and Distributors

Appendix A Troubleshooting

Appendix B Glossary

Appendix C Sentinel Keys Hardware Specifications

Appendix D Migration from Superpro and Ultrapro

Index

Quick Links

Need help?

Questions and answers

Summary of Contents for SafeNet Sentinel

Table of Contents