Fingerprint Generator API and Sample for Linux ARM
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 plan to 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 run a vendor-provided application that uses Licensing API get_info functions to retrieve the required hardware identifier data from the target machine and display it on the screen. They then share this information with you by 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
The fingerprint generated by the API includes the mandatory parameters SSID (Secure Storage Identifier), vid (Vendor ID), and fptype (License Type), 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)
In the hardware identifiers provided by the Licensing API get_info function, each hardware identifier is appended with a single-character checksum, separated by a slash (/). This checksum character helps ensure that the value is not mistyped when it is communicated between the user and the vendor over the phone.
The checksum character is appended to the end of each hardware identifier (for example, MAC address, FQDN). Its purpose is to validate that the entered identifier is correct. For example:
MAC address: 00-50-56-84-64-F8/c FQDN: ndsmt0214271-2/j IP Address: 10.164.27.17/a SID: S-1-5-21-3288819229-3833815190-3254703673/t
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.
>Validate the accuracy of manually provided entered hardware identifier using checksum characters. The checksum is optional. If omitted, the tool accepts the identifier as is and skips checksum validation.
>Use identifiers of hardware-based components (described below) to generate fingerprints for SL UserMode and SL AdminMode licenses.
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 to avoid possible license abuse.
>When generating a license using the fingerprint provided by the API, ensure that the custom clone protection scheme is applied to both the physical and virtual machine, regardless of the machine type. 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 described in this reference apply to the C programming language interface. The API also supports other programming languages.
You can access the API and sample files in the following directories:
>Sentinel-LDK/API/FingerprintGenerator/C/
>Sentinel-LDK/Samples/FingerprintGenerator/C/
This directory includes architecture-specific subfolders for Linux ARM platforms:
>armel or armhf: for 32-bit (ARM32) builds.
>arm64: for 64-bit (ARM64) builds.
Select the appropriate subfolder based on your target system’s architecture.
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>12345</vid> <mac>B8:27:EB:50:47:D8</mac> <ip>10.23.1.2</ip> <fqdn>hostname.domain.tld</fqdn> <sid>18f40b0</sid> <vm>true</vm> <custom_id_1>ABC123</custom_id_1> <custom_id_2>XYZ456</custom_id_2> </fingerprint_request>
XML Field Descriptions
| Parameter | Description |
|---|---|
| -ssid |
(Mandatory) Secure Storage Identifier (SSID). Provide a valid SSID value. Use unenforced only in special cases to disable the SSID check. 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. 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. |
| -custom_id_1 | (Optional) Custom Fingerprint Identifier.1 |
| -custom_id_2 | (Optional) Custom Fingerprint Identifier.1 |
|
Legend 1 - The custom_id_1 and custom_id_2 parameters accept only alphanumeric characters, with a length of 1 to 20 characters. An optional checksum character can be included. To use these parameters, implement the Custom Fingerprint Library and place the library in the required location for the target platform where the application runs. These parameters are supported only when you generate licenses using Sentinel EMS or the Sentinel License Generation API. |
|
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 Linux ARM 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 a Linux ARM machine (ARM32 or ARM64).
1.Copy the sample directory from the Sentinel LDK Linux package to your Linux ARM environment. For example:
Sentinel-LDK/Samples/FingerprintGenerator/C/
This directory includes architecture-specific subfolders for Linux ARM platforms:
•armel or armhf: for 32-bit (ARM32) builds.
•arm64: for 64-bit (ARM64) builds.
Depending on your target architecture, navigate to the appropriate subfolder before compiling or running the sample.
2.On your Linux ARM machine, navigate to the directory where you copied the sample. For example
cd /path/to/Sentinel-LDK/Samples/FingerprintGenerator/C/arm64
or
cd /path/to/Sentinel-LDK/Samples/FingerprintGenerator/C/armhf
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 Linux ARM machine, navigate to the directory where you copied the sample. For example:
cd /path/to/Sentinel-LDK/Samples/FingerprintGenerator/C/arm64
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 -custom_id_1 <ABC123> -custom_id_2 <XYZ456> -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 (SSID). Provide a valid SSID value. Use unenforced only in special cases to disable the SSID check. 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. 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. |
| -custom_id_1 | (Optional) Custom Fingerprint Identifier.1 |
| -custom_id_2 | (Optional) Custom Fingerprint Identifier.1 |
| -f | The output file name. If not specified, the fingerprint data is displayed in the command prompt console. |
| -help | Display help and usage instructions. |
|
Legend 1 - The custom_id_1 and custom_id_2 parameters accept only alphanumeric characters, with a length of 1 to 20 characters. An optional checksum character can be included. To use these parameters, implement the Custom Fingerprint Library and place the library in the required location for the target platform where the application runs. These parameters are supported only when you generate licenses using Sentinel EMS or the Sentinel License Generation API. |
|
Run the command to generate a fingerprint and save it to a file. For example,
Without checksum:
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 12345 -custom_id_1 ABC123 -custom_id_2 XYZ456 -f output.txt
With checksum:
fingerg2-shared -fqdn ndsmt0214271-2/j -ssid 3258884752/4 -ip 10.164.27.17/b -mac 00-50-56-84-64-F8/b -sid S-1-5-21-3288819229-3833815190-3254703673/u -fptype adminmode -vid 12345 -custom_id_1 ABC123 -custom_id_2 XYZ456 -f output.txt
The API automatically validates the checksum for each identifier. If any identifiers are entered incorrectly (for example, incorrect MAC address or FQDN), the tool will return an error, prompting you to verify the values. For example:
The following identifier(s) are invalid because the checksum does not match the expected value. Verify that you entered them correctly. -mac -fqdn
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="12345" 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 -custom_id_1 ABC123 -custom_id_2 XYZ456
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>12345</vid> <mac>B8:27:EB:50:47:D8</mac> <ip>10.23.1.2</ip> <fqdn>caligula</fqdn> <sid>18f40b0</sid> <vm>true</vm> <custom_id_1>ABC123</custom_id_1> <custom_id_2>XYZ456</custom_id_2> </fingerprint_request>
Then it returns the fingerprint result in XML format:
<hasp_info> <host_fingerprint type="SL-AdminMode" vendorid="12345" crc="650800216">MXhJSelBPY17i4d9AD+cVupRPthBjAF8vGfzMv2sHvLd33zftAP49WtWn+WAruj71Bd4oKn7OP7AB2bF/5x8z0M=</host_fingerprint> </hasp_info>
Sentinel Fingerprint Generator API Status Codes
Below is a list of possible return codes related to the operation of the Sentinel Fingerprint Generator API functions.