Fingerprint Generator API
NOTE This API is applicable for Linux only.
The Fingerprint Generator API provides a simple and secure way to generate fingerprints for a target system without executing a tool directly on that system.
To generate an SL AdminMode or SL UserMode protection key license to run a protected application, you need a fingerprint (C2V file) from the target machine where you will install the license. Include the Fingerprint Generator API in your backend application to allow your employee to manually generate machine fingerprints on behalf of users for machines where outgoing file transmission is restricted.
Users can display the required hardware identifiers data on the target machine's screen by calling the Licensing API get_info function. They can then share the information with you via email or telephone. You enter these values into your application, which uses the Fingerprint Generator API as described later in this document. For details, see Sentinel LDK ToolBox User Guide.
After generating the fingerprint, you can use Sentinel EMS to create the required license (V2C or V2CP file) and install it on the target machine.
The Fingerprint Generator API enables you to:
>Support environments where C2V files cannot be shared due to security restrictions.
>Generate fingerprints that are compatible with both Windows and Linux platforms.
>Generate fingerprints for both physical machines and virtual machines.
>Use identifiers of hardware-based components (described below) to generate fingerprints for SL UserMode and SL AdminMode licenses.
The fingerprint generated by the API includes the mandatory parameters SSID (Secure Storage Identifier), vid, and fptype, along with at least one of the following hardware identifiers from the target machine:
>MAC address
>FQDN (Fully Qualified Domain Name)
>IP address
>SID (Security Identifier on Windows or System ID on Linux)
Security Requirement
When generating a fingerprint file, consider the following:
>Security decreases when using fewer components (for example, using only MAC address or only FQDN).
>If the SSID (Secure Storage Identifier) is not provided, Thales recommends that you use Perpetual or Expiration Date licenses for enhanced security.
>When generating a license using the fingerprint generated by the API, you must use the custom clone protection scheme. This ensures compatibility with the fingerprint data and prevents license misuse or cloning.
Usage of the Fingerprint Generator API
The Sentinel Fingerprint Generator API functions in this reference apply to the C programming language interface. Sentinel Fingerprint Generator API supports languages other than C. APIs for supported languages can be accessed in the following directories:
>%Program Files(x86)%\Thales\Sentinel LDK\API\FingerprintGenerator
>%Program Files(x86)%\Thales\Sentinel LDK\Sample\FingerprintGenerator
Refer to sntl_fingerprint_gen.h for detailed programming interface information.
The following functions are provided by the Fingerprint Generator library:
| Functions | Description |
|---|---|
| sntl_fg_get_version() |
This function returns the version of the Fingerprint Generator library. Each parameter is optional and can be set to NULL. |
| sntl_fg_generate_fingerprint() | This function generates a fingerprint from the input data. If an error occurs, the error_info parameter provides detailed information. This parameter is optional and can be NULL. |
| sntl_fg_free_string() | This function is used to free the memory allocated by sntl_fg_generate_fingerprint(). See the header file for the encoded_fingerprint_xml and error_info parameters. |
Installation
No installation is required. You can include the header file and link your application with the provided library file.
XML Input Format
The sntl_fg_generate_fingerprint() function accepts an XML string (plain_fingerprint_xml) with the following structure:
<fingerprint_request> <ssid>unenforced</ssid> <fptype>adminmode</fptype> <vid>37517</vid> <mac>B8:27:EB:50:47:D8</mac> <ip>10.23.1.2</ip> <fqdn>caligula</fqdn> <sid>18f40b0</sid> <vm>true</vm> </fingerprint_request>
XML Field Descriptions
| Parameter | Description |
|---|---|
| -ssid |
(Mandatory) Secure Storage Identifier. Value: unenforced. NOTE When you set the SSID to unenforced, the Fingerprint Generator API disables the SSID check. In this case, the system does not support rehost and detach operations. |
| -fptype | (Mandatory) License Type to generate. Possible values are: adminmode and usermode. |
| -vid | (Mandatory) Vendor ID in decimal. |
| -mac | (Optional) MAC address of network interface. |
| -ip |
(Optional) IP address (only IPv4 is supported). NOTE Enter the machine’s IP address only when it is static or fixed. A static IP allows the system to consistently identify the machine during license validation. IP addresses of WiFi cards are not supported. |
| -fqdn |
(Optional) Fully Qualified Domain Name (hostname). |
| -sid | (Optional) System ID (Linux) or Security Identifier (Windows). |
| -vm | (Optional) If specified, indicates that the fingerprint is for a virtual machine. |
NOTE
>The sntl_fg_generate_fingerprint() function returns SNTL_FG_MISSING_MANDATORY_FIELD if any of the mandatory parameters (ssid, fptype, or vid) is missing.
>The sntl_fg_generate_fingerprint() function returns SNTL_FG_MISSING_REQUIRED_FIELD if none of the following parameters is provided: mac, ip, fqdn, or sid. At least one must be present.
Working With the Fingerprint Generator API
The fingerg2-static and fingerg2-shared executables demonstrate how to generate a fingerprint using the Fingerprint Generator library. Both programs are based on the same source file, fingerg2.c.
>fingerg2-static is compiled with the static version of the library (libsntl_fingerprint_gen_linux_*.a).
>fingerg2-shared is compiled with the dynamic (shared) version of the library (libsntl_fingerprint_gen_linux_*.so).
Each program constructs an XML request from the command-line parameters and calls the fingerprint generator API to generate the fingerprint.
Prerequisites
>Ensure that the correct sample program (either fingerg2-static or fingerg2-shared) is compiled and available on your ARM64 Linux machine.
>Make sure the appropriate version of the Fingerprint Generator library is compiled and available in your working directory:
•For dynamic: libsntl_fingerprint_gen_linux_*.so file must be present.
•For static : libsntl_fingerprint_gen_linux_*.a file must be present.
NOTE Compilation must be performed on an ARM64 Linux machine
1.Copy the sample directory from your Windows machine to your ARM64 Linux environment. For example:
%Program Files(x86)%\Thales\Sentinel LDK\Samples\FingerprintGenerator
2.On your ARM64 Linux machine, navigate to the directory where you copied the sample from your Windows machine. For example:
cd /path/to/FingerprintGenerator
3.Move to the static directory. Call ./mk in the command line to build the static library (.a) samples.
4.Move to the shared directory. Call ./mk-so in the command line to build the shared library (.so) samples.
After successful compilation, the executables fingerg2-static and fingerg2-shared will be available in their respective directories.
To generate a fingerprint file:
NOTE The following steps must be performed on an ARM64 Linux machine. You can either use the precompiled sample or the ones you compiled in the previous step.
1.On your ARM64 Linux machine, navigate to the directory where you copied the sample. For example:
cd %path)%\Thales\Sentinel LDK\Sample\FingerprintGenerator
2. If not using precompiled samples, compile the sample as described in the Compiling the Sample section.
3.Prepare and execute the appropriate command to generate the fingerprint file. Below is the general example syntax:
fingerg2-shared -mac <MACAddress> -fqdn <Fully Qualified Domain Name> -ip <IPAddress> -sid <Machine SID> -ssid <SecureStorageID> -fptype <FingerprintType> -vid <VendorID> -vm -f <Output File Name>
NOTE You can also use fingerg2-static in place of fingerg2-shared, depending on the sample you compiled.
Replace the placeholders with the relevant information as specified in the table below. Make sure to include all mandatory parameters and at least one of the following: -mac, -ip, -fqdn, -sid
| Parameter | Description |
|---|---|
| -ssid |
(Mandatory) Secure Storage Identifier. Value: unenforced. NOTE When you set the SSID to unenforced, the Fingerprint Generator API disables the SSID check. In this case, the system does not support rehost and detach operations.. |
| -fptype | (Mandatory) License Type to generate. Possible values are: adminmode and usermode. |
| -vid | (Mandatory) Vendor ID in decimal. |
| -mac | (Optional) MAC address of network interface. |
| -ip |
(Optional) IP address (only IPv4 is supported). NOTE Enter the machine’s IP address only when it is static or fixed. A static IP allows the system to consistently identify the machine during license validation. IP addresses of WiFi cards are not supported. |
| -fqdn |
(Optional) Fully Qualified Domain Name (hostname). |
| -sid | (Optional) System ID (Linux) or Security Identifier (Windows). |
| -vm | (Optional) If specified, indicates that the fingerprint is for a virtual machine. |
| -f | The output file name. If not specified, the fingerprint data is displayed in the command prompt console. |
| -help | Display help and usage instructions. |
Run the command to generate a fingerprint and save it to a file. For example,
fingerg2-shared -mac D0:51:A9:0B:9F:80 -fqdn darkstar.example.com -ip 10.23.105.51 -sid 18f40b0 -ssid 1A145732 -fptype usermode -vid 21499 -f output.txt
If the command runs successfully, a message is displayed in the console indicating that data is written to the file. For example, Data written to file:output.txt.
4. Check the console or output file (if available) for the generated fingerprint details in XML format. For example:
<hasp_info> <host_fingerprint type="SL-UserMode" vendorid="21499" crc="1023009405">MnhJSbP0sIO3eLBDiJ5e6oG5CRo6wMewJPT2rB5GxszRTzuoYFEPn+VgTs79fYEHOgv+/sAHOeTc1/c81A==</host_fingerprint> </hasp_info>
The output.txt file is saved in your current directory.
5.Use the generated fingerprint file in
Example: Viewing XML Input and Generating Fingerprint
Run the following command to generate a fingerprint and view the XML input:
/fingerg2-static -v -ssid unenforced -fptype adminmode -vid 21499 -mac 11:22:33:44:55:aa -ip 10.23.1.2 -fqdn www.john.org -sid 1234abcd
NOTE You can use the same syntax with fingerg2-shared.
Example Output
If the -v switch is used, the program displays the generated XML request:
XML input data: <fingerprint_request> <ssid>unenforced</ssid> <fptype>adminmode</fptype> <vid>37517</vid> <mac>B8:27:EB:50:47:D8</mac> <ip>10.23.1.2</ip> <fqdn>caligula</fqdn> <sid>18f40b0</sid> <vm>true</vm> </fingerprint_request>
Then it returns the fingerprint result in XML format:
<hasp_info> <host_fingerprint type="SL-AdminMode" vendorid="21499" crc="650800216">MXhJSelBPY17i4d9AD+cVupRPthBjAF8vGfzMv2sHvLd33zftAP49WtWn+WAruj71Bd4oKn7OP7AB2bF/5x8z0M=</host_fingerprint> </hasp_info>
Sentinel Licensing API Status Codes
Below is a list of possible return codes related to the operation of the Sentinel Fingerprint Generator API functions.