Fingerprint Generator API and Sample for Windows
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 generated by the API, you must use the custom clone protection scheme for both physical and virtual machines. 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.
API Locations:
>%Program Files (x86)%\Thales\Sentinel LDK\API\FingerprintGenerator\C\win32
>%Program Files (x86)%\Thales\Sentinel LDK\API\FingerprintGenerator\C\x64
Sample Locations:
>%\Program Files (x86)%\Thales\Sentinel LDK\Samples\FingerprintGenerator\C\win32
>%\Program Files (x86)%\Thales\Sentinel LDK\Samples\FingerprintGenerator\C\x64
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
Prerequisites
>Ensure that the correct sample program (fingerg2 ) is compiled and available on your Windows (x64 or x86) machine.
>Make sure the appropriate version of the Fingerprint Generator library is compiled and available in your working directory:
•For dynamic: sntl_fingerprint_gen_windows.dll file must be present.
•For static :libsntl_fingerprint_gen_windows.lib file must be present.
NOTE Compilation must be performed on a Windows x86 or Windows x64 machine.
1.Set the path and the environment variables for the Microsoft C compiler (cl.exe).
2.Copy the sample directory from your installation. For example:
%Program Files (x86)%\Thales\Sentinel LDK\Samples\FingerprintGenerator\C\win32 %Program Files (x86)%\Thales\Sentinel LDK\Samples\FingerprintGenerator\C\x64
3.Open a Developer Command Prompt for Visual Studio and navigate to the sample directory. For example:
%\Program Files (x86)%\Thales\Sentinel LDK\Samples\FingerprintGenerator\C\win32" or %\Program Files (x86)%\Thales\Sentinel LDK\Samples\FingerprintGenerator\C\x64"
4.Move to the lib directory. Call mk.bat in the command line to build the static library sample.
5.Move to the shared directory. Call mk.bat in the command line to build the shared library (DLL) sample.
After successful compilation, the executables fingerg2 will be available in their respective directories.
To generate a fingerprint file:
NOTE The following steps must be performed on a Windows x86 or Windows x64 machine. You can either use the precompiled sample or the ones you compiled in the previous step.
1.Open a Command Prompt and navigate to the sample directory. For example:
%Program Files (x86)%\Thales\Sentinel LDK\Samples\FingerprintGenerator\C\win32" %Program Files (x86)%\Thales\Sentinel LDK\Samples\FingerprintGenerator\C\x64"
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 -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>
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 -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 -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 -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
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 Licensing API Status Codes
Below is a list of possible return codes related to the operation of the Sentinel Fingerprint Generator API functions.