Custom Clone Protection Scheme with Custom Fingerprint Library
Sentinel LDK provides multiple clone protection schemes to protect applications running in different machine environments. Each scheme validates the machine by using selected system identifiers to generate and compare system fingerprints. In environments using proprietary hardware platforms, virtualized systems, or industrial devices, the standard system fingerprint may not contain enough reliable identifiers to uniquely identify the machine or provide the required level of protection. In such scenarios, licenses can be locked to proprietary identifiers that are not included in the standard Sentinel LDK fingerprint using a custom fingerprint library.
The custom fingerprint library is a dynamic library that extends the standard Sentinel LDK clone detection mechanism by retrieving vendor-defined identifiers (such as proprietary identifiers) during system fingerprint generation. During fingerprint generation, the library collects vendor-defined identifiers and includes the identifiers in the Sentinel LDK fingerprint. This requires the vendor to implement the logic in the custom fingerprint library to retrieve and return the data for those proprietary identifiers whenever the Sentinel LDK runtime requests fingerprint information.
The custom fingerprint library returns a maximum of two custom identifiers. These custom identifiers can be used as part of custom clone protection schemes for both Custom Clone Detection for Physical Machines and Custom Clone Detection for Virtual Machines to include one or more criteria, resulting in a more precise custom clone protection scheme.
During license validation, the Sentinel License Manager recomputes the system fingerprint, including any proprietary identifiers retrieved by the custom fingerprint library, and compares it to the reference fingerprint stored in the license. The Sentinel EMS or Sentinel License Generation API uses this fingerprint data during license creation to ensure consistency between the generated license and the target machine’s identifiers.
To include vendor-defined identifiers in the system fingerprint, the custom fingerprint library must be available when the fingerprint is generated. Sentinel LDK uses this library to retrieve the vendor-defined identifiers. If the library is not available, the fingerprint contains only the standard Sentinel LDK identifiers. In this case, if a custom clone protection scheme is requested for that fingerprint, license generation may fail if the required custom identifiers are missing, unless other identifiers in the scheme satisfy the requirements.
NOTE Custom identifiers supported by the custom fingerprint library are available only with Sentinel EMS or the Sentinel License Generation API and are not supported in Sentinel LDK-EMS.
See the Sentinel License Generation API Reference for information on the XML tags to create custom identifiers in license definition, and methods that can be used to apply license definition templates.
License generation fails in the following situations:
>Your custom clone protection scheme requires a custom identifier, but the provided C2V file does not contain the required identifier.
>The C2V originates from an outdated Sentinel RTE. See the Requirements for Custom Clone Protection Schemes page for minimum requirements.
NOTE If you use custom fingerprint identifiers (or vendor-defined identifiers) for a custom clone protection scheme, always regenerate the C2V after deploying the custom fingerprint library. Otherwise, Sentinel EMS or Sentinel License Generation API will reject license creation due to missing custom identifiers.
Using the Custom Fingerprint Library
Supported Platforms
The Custom Fingerprint Library is supported in the following platforms:
>Windows: x86 (32-bit) and x64 (64-bit)
>Linux Intel: x86_64 (64-bit)
>Linux ARM: armel (32-bit), armhf (32-bit), and arm64
Custom Fingerprint Library Naming Convention
The custom fingerprint library follows a standard naming convention that encodes platform, architecture, and Vendor ID.
sntl_cflib_{platform}_{architecture}_{vendor_id}.{extension}
The following table describes the components of the custom fingerprint library file:
| Component | Description | Example for Windows | Example for Linux |
|---|---|---|---|
sntl_cflib | Fixed prefix identifying the library type | sntl_cflib | |
{platform} | Operating system | windows | linux |
{architecture} | CPU architecture | x86 (32-bit): leave empty x64 (64-bit): x64 | Linux ARM: |
{vendor_id} | Vendor ID (numeric) | 12345 | |
{extension} | Library extension | .dll | .so |
For example:
>sntl_cflib_windows_x64_12345.dll
>sntl_cflib_linux_armhf_12345.so
Custom Fingerprint Library Sample Location
The custom fingerprint library sample is available in the following directories:
Windows:
>x86 (32-bit): %ProgramFiles(x86)%\Thales\Sentinel LDK\Samples\CustomFingerprintLibrary\C\win32
>x64 (64-bit): %ProgramFiles(x86)%\Thales\Sentinel LDK\Samples\CustomFingerprintLibrary\C\x64
Linux ARM:
>armhf (32-bit): Sentinel-LDK/Samples/CustomFingerprintLibrary/C/armhf
>armel (32-bit): Sentinel-LDK/Samples/CustomFingerprintLibrary/C/armel
>arm64 (64-bit): Sentinel-LDK/Samples/CustomFingerprintLibrary/C/arm64
Linux Intel:
>x86_64 (64-bit): Sentinel-LDK/Samples/CustomFingerprintLibrary/C/x86_64
Custom Fingerprint Library API
You can use any of the supported languages listed in Sentinel LDK Release Notes to build the custom fingerprint library. The following functions are provided by the custom fingerprint library API:
| Function Signature | Description |
|---|---|
sntl_cf_get_fingerprint(unsigned char **out_buf, unsigned int *out_len) | Retrieves custom fingerprint data as an XML string. The function allocates memory for the output buffer and returns the fingerprint data and length. The XML structure returned in |
sntl_cf_free_fingerprint(unsigned char *buf) | Releases memory allocated by |
The Custom Fingerprint Library API returns SNTL_CF_STATUS_SUCCESS for a successful fingerprint data retrieval (status code 0) and SNTL_CF_STATUS_FAILURE if the operation fails (status code 1).
The out_buf parameter of sntl_cf_get_fingerprint() returns fingerprint data in the following XML format:
<?xml version="1.0" encoding="UTF-8"?>
<sntl_cf>
<custom_fingerprints>
<custom_fingerprint id="1" value="XXXX" />
<custom_fingerprint id="2" value="XXXX" />
</custom_fingerprints>
</sntl_cf>Each custom fingerprint identifier contains:
>id: Unique identifier for the custom fingerprint entry.
>value: Custom fingerprint data associated with the identifier.
You can define a maximum of two custom fingerprint identifiers per C2V.
Create and Deploy a Custom Fingerprint Library
Before a custom clone protection scheme can use vendor‑defined identifiers, create and deploy a custom fingerprint library. This library retrieves vendor-defined identifiers and provides them to Sentinel LDK when generating the system fingerprint.
The following steps describe how to customize the sample source code, compile the custom fingerprint library, sign the compiled library, and deploy it so that Sentinel License Manager can load and use it.
To create and deploy the custom fingerprint library, complete the following steps:
Step 1: Customize the Source Code and Compile the Custom Fingerprint Library
Edit the sntl_cflib.c file to specify vendor-defined identifiers by replacing the values in sntl_cf_get_fingerprint() function with your vendor identifiers. You can modify both placeholder values or only one, depending on the number of custom fingerprint identifiers you want. The maximum is two.
Next, compile or build the library (.dll for Windows or .so for Linux).
1.Locate the sample directory in your installation folder and copy its file path.
2.Open the command line interface and navigate to the sample directory.
3.Build the sample.
•Windows: Run mk.bat in the command line and pass your Vendor ID (numeric identifier) as a parameter to build the sample .dll file.
mk.bat [vendorid]
•Linux ARM / Linux Intel: Run ./mk in the command line and pass your Vendor ID (numeric identifier) as a parameter to build the sample .so file.
./mk [vendorid]
After successful compilation, the compiled sample library file (.dll or .so) is generated as follows:
•For Windows, in the build folder in the sample directory.
•For Linux ARM and Linux Intel, in the current directory.
Step 2: Sign the Custom Fingerprint Library
The compiled custom fingerprint library must be signed before distribution to protect the library from replacement or unauthorized modification. The Sentinel License Manager accepts only signed custom fingerprint libraries and rejects any unsigned library. Use the dfcrypt command-line utility to sign the library. The following sections describe the location of the dfcrypt utility and the prerequisites required to perform the signing operation.
The dfcrypt utility is available in the following directory:
>Windows: %ProgramFiles(x86)%\Thales\Sentinel LDK\VendorTools\VendorSuite\
>Linux ARM / Linux Intel: /Linux/VendorTools/Envelope/
Ensure that the following prerequisites are met to use dfcrypt utility:
>Ensure that the dfcrypt utility is available at the directory specified above.
>The corresponding Vendor (master or developer) key containing Vendor Code is available.
To sign the compiled custom fingerprint library, complete the following steps.
1.Open a Command Prompt and navigate to the directory containing the compiled sample.
2.Connect a Vendor (master or developer) key that contains the appropriate Vendor Code. If the Vendor key is not detected, the signing operation fails.
3.Run the signing command.
dfcrypt sign -c:<vendor_code_file> <compiled_custom_fingerprint_lib_file>
Where:
•<vendor_code_file> is your Vendor Code file (.hvc).
•<compiled_custom_fingerprint_lib_file> is the compiled custom fingerprint library file (.dll on Windows or .so on Linux following the required naming convention.)
Examples (where Vendor Code file name is W3FLY.hvc and Vendor ID is XXXXX; you need to replace these with actual values):
•Windows:
dfcrypt sign -c:W3FLY.hvc sntl_cflib_windows_x64_XXXXX.dll
•Linux ARM / Linux Intel:
dfcrypt sign -c:W3FLY.hvc sntl_cflib_linux_armhf_XXXXX.so
NOTE The dfcrypt tool of Windows and Linux Intel can be used to sign Linux ARM custom fingerprint library.
The signing operation generates a corresponding .p7s signature file in the same directory as the library file.
Step 3: Deploy the Custom Fingerprint Library
When deploying your protected application, you must include the signed custom fingerprint library and its corresponding signature file (.p7s).
Ensure that the following prerequisites are met to allow the protection scheme to function correctly:
>Ensure the library follows the standard naming convention so the Sentinel License Manager can automatically detect and load it from the predefined search paths.
>Select the custom fingerprint library file that matches the target system architecture.
>Always deploy the signature file (.p7s) alongside its respective custom fingerprint library in the same directory.
After deployment, the Sentinel License Manager must locate and load the appropriate custom fingerprint library based on the target system architecture. The following sections describe how the Sentinel License Manager detects the system architecture and searches for the library in predefined locations.
To ensure that the custom fingerprint library is detected and the protection scheme functions correctly, place the library in one of the locations listed below. The Sentinel License Manager searches these locations in a predefined order until it finds the library. The search behavior varies depending on the type of Sentinel License Manager in use.
For the Integrated License Manager and External License Manager, the custom fingerprint library is searched for in the following order:
>Windows
| Library search priority (highest to lowest) | Search Path | Description |
|---|---|---|
1 | C:\MyApp\ | Application directory For the External LM, the application directory refers to the directory where hasp_rt.exe resides. |
| 2 | %ProgramFiles(x86)%\Common Files\Aladdin Shared\HASP | Official installation directory |
| 3 | %LocalAppData%\SafeNet Sentinel\Sentinel LDK\ | User-specific directory |
NOTE To view the correct status of an SL UserMode license in the Admin Control Center, ensure that the custom fingerprint library is placed in the %\Program Files (x86)%\Common Files\Aladdin Shared\HASP directory.
>Linux ARM / Linux Intel
| Library search priority (highest to lowest) | Search Path | Description |
|---|---|---|
1 | /opt/myapp/ | Application directory |
| 2 | $HOME/.hasplm/ | User-specific directory |
For the Admin License Manager, the custom fingerprint library is searched for in the following order:
>Windows
| Library search priority (highest to lowest) | Search Path | Description |
|---|---|---|
1 | %ProgramFiles(x86)%\Common Files\Aladdin Shared\HASP | Official installation directory |
| 2 | %SystemRoot%\System32\ | System directory |
>Linux ARM / Linux Intel
| Library search priority (highest to lowest) | Search Path | Description |
|---|---|---|
1 | /var/hasplm/ | License Manager directory |