Getting Started with Sentinel RMS—Standalone Lease Mode

The purpose of this document is to get you started with the licensing workflow of SCL (Sentinel Cloud Licensing) Add-on for RMS. It aims to familiarize you with the following processes—obtaining SDKs of Sentinel RMS and SCL Add-on, provisioning licenses using Sentinel EMS, obtaining license using the SCP service and consuming licenses by building and executing the Sentinel RMS samples for the standalone lease mode.

The Basics

The following are the basic concepts you need to know to use this guide.

ClosedSentinel EMS

ClosedSentinel RMS

ClosedStandalone and Network Licensing

ClosedOn-premises and Lease Modes

The Samples

The sntl_lease_demo sample has been referenced in this document. It is a console-based sample that shows how to use Unified APIs to obtain, use (request), and release a license in standalone lease mode.

The samples for the lease mode are available with the SCL Add-on for Sentinel RMS package, which you can download from the Thales Sentinel order emails.

NOTE    On placing an order for a Sentinel product, you receive two emails from Thales. The first email is referred to as the Thales Sentinel Order email and the second one as Thales Sentinel Secret Credential email. These emails contain order details, software download links, support details, and other important information.

ClosedScope

Prerequisites

The following are the requirements for running the lease sample.

ClosedSentinel RMS SDK and SCP SDK

ClosedMicrosoft Visual Studio

The Steps

Follow the steps below to run an SCP-enabled RMS sample application on Windows.
  

The first step is to download the Sentinel RMS SDK and SCL Add-on zip package from the Sentinel order emails, and install the Sentinel RMS SDK.

Downloading and Installing the Sentinel RMS SDK

NOTE   If you are a production customer, refer to the Thales order emails for links to download the SDK. Alternatively, you can log in to your Thales support account and use the available links to download the SDK. If you are an evaluation/trial customer, the SDK download links are present in the trial portal, details of which are shared with you over emails.

1.Open the Thales Sentinel order email. In the Download Details table, click the Download link corresponding to the Sentinel RMS SDK (Windows) field.

2.For trial licenses, clicking the link will directly start the SDK download. For all other licenses, you will be redirected to the Thales Support Portal.

3.Extract RMSSDK10.x.xxxWindows.zip downloaded in the step above.

4.Run the StartHere.exe file and follow the instructions provided with the graphical installation wizard. Note the following:

•One of the screens displayed during the installation is Customer Information dialog box. In this dialog box, type your name, organization name, and the Sentinel Serial Number. You can copy and paste the Sentinel Serial Number from the Thales Sentinel Order email. This serial number is unique for each customer.

•The default Sentinel RMS installation directory is: C:\Program Files (x86)\Thales\Sentinel RMS Development Kit\10.x\

Downloading the SCL Add-on for Sentinel RMS Package

1.Open the Thales Sentinel Order email. In the Download Details table, click the Download link corresponding to the Sentinel Cloud Add-On Package field. This redirects you to a download page on the Thales support portal.

2.Enter the Sales Order (SO) number in the Enter SO Number field. The SO number is available in the subject field of the Thales Sentinel Order email.

3.Click Get Download Key. You will receive an email with the download key on your registered email address. The download key is valid for 24 hours.

4.In the Enter Download Key field, specify the received download key, and click Download. This will start the download of the SCL Add-on for Sentinel RMS package, which is a password-protected archive containing separate packages for different operating systems.

In this step, you connect to the Sentinel EMS Portal using the credentials shared by your Thales representative.

1.Navigate to the URL shared by Thales.

2.Log on using the User ID and Password provided by Thales.

On the first login to Sentinel EMS, the getting started page is displayed which provides links to help you get started with Sentinel EMS. For existing users, the Entitlements page is displayed.

A license model is a combination of various parameters that define how a product can be used by an end user. You need to use the Flexible license model as the base for defining a license for the standalone lease mode.

1.From the navigation pane, select Catalog > License Models.

2.In the License Models page, search by Name for the Flexible License Model.

3. Under the Actions column, click Copy .

4.In the Copy License Model page, in the Name field, enter any license model name, for example, MyLicense.

5.From the Deployment Mode drop-down, select Lease.

6.From the License Type drop-down, select Standalone.

7.Under the Policy section, toggle Enforce Clock Tampered to No. This disables time tampering detection.

If you want to enable the time tampering, you will need to set up the persistence information on the standalone machine by using the sntl_persistence_create API. For the API details, refer to the Sentinel RMS API Reference Guide. For the C interface, you can set up the persistence information by first compiling and then executing the sntl_lspmgmtinit sample, which is available in the Samples folder of the standard Sentinel RMS installation.

8.Under the Cloud Served section, toggle Fingerprint Registration to No. This specifies that the machine registration is not required to consume the entitlement.

9.Click Save.

 

You've successfully configured the license model. Next, you will create a feature using this license model.

The first step in creating a catalog is defining features.

1.From the navigation pane, select Catalog > Features.

2.In the Features page, click Add Feature.

3.In the Add Feature page, from the Namespace list, select General.

You see the Namespace list only if multiple namespaces are available in the system.

4.In the Name field, enter a feature name, such as Addition.

5.In the Version field, type 1.

6.In the Identifier field, leave the default Identifier for now.

When you create your own features, you can use the default Identifier or apply another Identifier to match an existing feature in one of your company's products. The Identifier must match the feature Identifier in your licensed application.

7.In the Available License Models area of the Associate License Models pane, click the license model you created to add it to the Associated License Model list.

8.Click Save.

You've created your first feature. Next, you will add the feature to a product.

Now that you created a feature, you can add it to a product. This is known as associating a feature with a product.

1.From the navigation pane, select Catalog > Products.

2.In the Products page, click Add Product.

3. In the Add Product page, from the Namespace list, select General.

4.In the Name field, enter any product name, for example, MyProduct.

5.In the Version field, type 1.

6.In the Available Features area of the Associate Features pane, click the feature you created to add it to the Associated Features list.

7.Click Save. The product is created as a draft.

8.In the Products page, for the product you created, in the Actions column, click the Complete button.

9.In the confirmation box that opens, click Complete (not shown). This makes the product available for distribution.

You've successfully created your first product. Next, you will create an order, known as an entitlement, for the product.

In this step, you are creating an entitlement.

1.From the navigation pane, select Entitlements.

2.In the Entitlements page, click Add Entitlement.

3.Associate this entitlement with a new customer.

a. In the Add Entitlement page, next to the Customer field, click Add Customer .

Tip: You can also define customers directly from the Customers tab.

b. In the Add Customer dialog box, in the Name field, enter any customer name, for example, MyCustomer.

c. In the Identifier field, enter an alphanumeric value, let's say, MyCustomerID.

For the lease mode, it is mandatory to enter the Identifier, also referred to as the customer identifier. You will require this during the SCP configuration as will be explained in the later part of this guide.

d. Click Add to finish creating the customer.

4.Add user details to the customer you just created.

a. In the Add Entitlement page, next to the User Email field, click Add User to open the Add User dialog box.

b. In the Email field, add the email address to which the entitlement certificate will be sent.

c. Click Add. The user is created and the user email address is associated with the customer you just created.

5.In the Associate Products / Product Suites pane, under Available Products, click the product you created to add it to the Associated Products / Product Suites section.

6. Specify the number of product licenses purchased by the customer.

Let's suppose that the customer ordered 10 copies of your product.

In the Available Quantity field, change the value to 10.

7.Click Save to save the entitlement as a draft.

8.In the Entitlements page, in the Actions column, click Mark as Complete to complete the entitlement.

(The image shows the Draft status prior to confirmation.)

9.In the confirmation box, click Complete (not shown). The entitlement details are saved. An Entitlement Certificate email is sent to the user email address you entered earlier.

(The image shows the Completed status post-confirmation.)

You've successfully created your first entitlement.

You need to merge the contents of standard RMS SDK installation with the SCL Add-on for Sentinel RMS Package to obtain SCL lease samples, and setup the environment required for the execution of the samples.

To merge the Sentinel RMS SDK and SCL Add-on for Sentinel RMS Package:

1.Unzip the SCL Add-on for Sentinel RMS package (zip archive) by using the password received in the Thales Sentinel Order Secret email.

2.Unzip the Windows-specific SCL Add-on for Sentinel RMS package (Sentinel Cloud Add-On Windows.zip), and copy all its sub-folders (Development, Manuals, Redistributable, and Samples). The contents of Samples folder are shown below:

Interface

\Sentinel Cloud Add-On Windows
Samples for C

\Samples\C\

•sntl_scl_sample.MSVS2012.sln

•sntl_scl_sample.MSVS2015.mak

•sntlcloudp_configuration_[vendor_alias].xml

\Samples\C\Src\

•sntl_lease_demo.c

•sntl_lease_demo.vcxproj

•sntl_lease_tool.c

•sntl_lease_tool.vcxproj
Samples for Java

\Samples\Java-Jna\

•build_scl_sample.bat

•sntlcloudp_configuration_[vendor_alias].xml

•sntl_lease_demo.java

•sntl_lease_demo.MF

•sntl_lease_tool.java

•sntl_lease_tool.MF
Samples for C# and VB.NET \Samples\DotNet-Unmanaged\

•sntlcloudp_configuration_[vendor_alias].xml

\Samples\DotNet-Unmanaged\C#\

•sntl_lease_demo.cs

•sntl_lease_demo.csproj

•sntl_scl_sample.sln

•sntl_lease_tool.cs

•sntl_lease_tool.csproj

\DotNet-Unmanaged\VB.NET\

•sntl_lease_demo.vb

•sntl_lease_demo.vbproj

•sntl_scl_sample.sln

•sntl_lease_tool.vb

•sntl_lease_tool.vbproj

3.Go to the folder where RMS SDK is installed, that is: C:\Program Files (x86)\Thales\Sentinel RMS Development Kit\10.x\. Paste the folders copied earlier and confirm to merge the folders.

You need to configure SCP to ensure that the sample application can fetch licenses from the cloud. To configure SCP, you need to modify the SCP configuration file (sntlcloudp_configuration_<Vendor_Alias>.xml) available in the interface-specific folder inside the Samples folder.

•For C: \Samples\C\

•For Java: \Samples\Java-Jna\

•For .NET: \Samples\DotNet-Unmanaged\

To configure SCP:

1.Navigate to the folder containing the SCP configuration file (sntlcloudp_configuration_<Vendor_Alias>.xml).

2.Double click the SCP configuration file to open it, and update the following:

a.Copy the YPS URL from the Thales Sentinel Order emails and specify it in the SCP configuration file. Example: 

<YPSaddress value="https://abc.prod.sentinelcloud.com/YPServer" />

b.Set Customer ID to the Customer Identifier value that you entered while creating an entitlement. Example:

<Customer id="MyCustomerID" />

c. In the FingerprintFriendlyName element, set the value to the host name of the standalone machine on which you want to fetch the license. Example:

<FingerprintFriendlyName value="host_name"/>

NOTE   You will also need to setup the proxy configurations if you are working in a proxy environment. For details on proxy configuration, refer to the Sentinel Cloud Licensing (SCL) Add-on Installation and Configuration Guide.

You need to go to the RMS SDK installation and compile the sntl_lease_demo sample to get the executable application, which can be run to consume the license.

Steps for C

To compile the sntl_lease_demo.c sample:

1.Open Microsoft Visual Studio as Administrator.

2.Open the Samples32.MSVS2012.sln solution file in Visual Studio. This file is available in the \Samples\C\ folder.

3.(Optional) By default, the feature name is Addition and feature version is 1 in the sample source file. However, if you have created a feature in EMS by a different name and version, you can change the defaults in the sample. To do so:

a.In the Solution Explorer, navigate to the sntl_lease_demo folder, expand Source Files and double-click the sntl_lease_demo.c file to open it.

b.In the source file, change the feature name and feature version to the values defined in EMS.

4.Build the sample. To do so, right-click the sntl_lease_demo folder in the Solution Explorer, and click Build. The output is the sample application executable (.exe) in one of the following directories depending on the configuration setting (Release or Debug):
\Samples\C\Out\MSVS2012\x86\Release
\Samples\C\Out\MSVS2012\x86\Debug

Next, you need to run the sample application executable (.exe) to consume licenses. To run the sntl_lease_demo.exe file:

1.Open the command prompt as Administrator.

2.Change the directory to the output folder by running the following command:

cd C:\Program Files (x86)\Thales\Sentinel RMS Development Kit\10.x\Samples\C\Out\MSVS2012\x86\Release

3.Execute the sntl_lease_demo.exe file.

Once the sample compiles and runs, the Console window opens showing the execution results.

Steps for Java

You can compile Java samples by using batch files.

To compile and run the Java sample on Windows:

1.(Optional) By default, the feature name is Addition and feature version is 1 in the sample source file. However, if you have created a feature in EMS by a different name and version, you can change the defaults in the sample. To do so:

a.Go to the directory containing Java samples, which by default is \Samples \Java-Jna (on the RMS SDK installation).

b.Open the sntl_lease_demo.java source file in an editor of your choice.

c.In the source file, change the feature name and feature version to the values defined in EMS.

2.Open the command prompt as admin.

3.Change directory to the path where the Java samples are available.

4.Set the JDK path. Example:

SET JDK=C:\Program Files (x86)\Java\jdk1.8.0_121

5.Run the batch file. 

build_scl_sample.bat

All the samples will be compiled, and corresponding class and jar files will be created.

6.Run the sample. 

java -jar sntl_lease_demo.jar

Once the sample compiles and runs, the Console window opens showing the execution results.

Steps for .NET

The .NET samples are available for the following languages:

•C#

•VB.NET

To compile the .NET sample:

1.Open Microsoft Visual Studio as Administrator.

2.Open the Samples.sln solution file in Visual Studio. This file is available in the following folder on the RMS SDK installation:

•For C#:
\Samples\DotNet-Unmanaged\C#

•For VB.NET:
\Samples\DotNet-Unmanaged\VB.NET

3.(Optional) By default, the feature name is Addition and feature version is 1 in the sample source file. However, if you have created a feature in EMS by a different name and version, you can change the defaults in the sample. To do so:

a.In the Solution Explorer, navigate to the sntl_lease_demo folder, expand Source Files and double-click the sntl_lease_demo file (.cs or .vb depending on the language) to open it.

b.In the source file, change the feature name and feature version to the values defined in EMS.

4.Build the sample. To do so, right-click the sntl_lease_demo folder in the Solution Explorer, and click Build. The output is the sample application executable (.exe) in one of the following directories depending on the configuration setting (Release or Debug):

•For C#:
\Samples\DotNet-Unmanaged\C#\bin\x86\Release
\Samples\DotNet-Unmanaged\C#\bin\x86\Debug

•For VB.NET:
\Samples\DotNet-Unmanaged\VB.NET\bin\x86\Release
\Samples\DotNet-Unmanaged\VB.NET\bin\x86\Debug

Next, you need to run the sntl_lease_demo.exe sample application to consume licenses. To run the sntl_lease_demo.exe file:

1.Open the command prompt as Administrator.

2.Change the directory to the output folder containing the sample application executable (.exe):

3.Execute the sample application executable (.exe) file.

Once the sample compiles and runs, the Console window opens showing the execution results.

Run the Sample

After compiling, run the sample application executable to consume licenses.

The Console window displays the sample execution results.

1. An application context is created, and SCP initiates the retrieval of licenses from the cloud. The login call is also executed to consume the license.

2.Login API can return error 210018 (if the license is not fetched) or error 214109 (if the existing license on the machine has expired). In the image, the login API call has returned error 210018 to indicate that the license has not been yet fetched.

3.Press Enter to get sync lease job information. This gives the status as Node Registration in progress or Job in progress or License Add/Remove Operation Completed.

4.Press Enter to call the login API. This requests licenses for the feature you created.

5.Press Enter. The information for the Addition feature is displayed.

6.Press Enter. The session information is displayed, which is the information for the current license session. Note that a successful license request creates a license session. For example, <tokensInUse> is shown as 1 because one license has been used with the call to the login API.

Next, the refresh API is called to periodically refresh the license and keep the license session alive for a longer period.

Afterward, the logout call is executed to release licenses.

7.Press Enter to close the sample.

Congratulations! You've successfully generated and consumed Sentinel RMS licenses for a standalone machine.