sntl_lg_validate_fingerprint() Function

Description

This API function compares the fingerprint provided in the API call (which can be the current machine’s fingerprint or any other specified fingerprint) with the fingerprint stored in an existing license file (V2C or resultant state).

Usage Notes

This function helps the vendor determine whether a license request is legitimate when a user formats their machine and requests a new license. By comparing the old and new fingerprints, the vendor can verify if both belong to the same machine.

The sntl_lg_validate_fingerprint API compares the fingerprint provided in the API call (which can be the current machine’s fingerprint or any other specified fingerprint) with the one embedded in the original V2C file. Based on the comparison, the vendor can decide whether to reuse the existing license or issue a new one.

The API returns a result_info XML structure that contains details about the fingerprint match and any hardware differences. For example:

<result>
 <product>
  <id>XXX</id>
  <cloned>yes</cloned>
  <mismatched_items>
    <item name="cpu" />
    <item name="secure_storage_id" />
  </mismatched_items>
 </product>
</result>

If <cloned> is no, it means the fingerprint matches the original system, and the V2C license can be reused. In this case, the response will appear as follows, for example:

<result>
 <product>
  <id>all</id>
  <cloned>no</cloned>
  <mismatched_items></mismatched_items>
 </product>
</result>

If <cloned> is yes, the system detects significant hardware changes, which require the vendor to either issue a clear cloned license or generate a new license.

NOTE The system matches the fingerprint based on the clone protection scheme used during product creation. If the fingerprint does not match according to that scheme, it returns "yes".

When calling sntl_lg_validate_fingerprint API, consider the following:

>If the system compares two incompatible fingerprints (for example, SL AdminMode with SL UserMode), the API returns the following error:

Error Code: 5034 - SNTL_LG_INCOMPATIBLE_ENFORCEMENT_TYPE

This error indicates that the fingerprint comparison failed due to incompatible enforcement types between the two fingerprints.

>If the API returns <cloned>yes</cloned>, it means at least one product in the V2C is marked as cloned based on the fingerprint differences and the clone protection scheme defined for that product.

>If the V2C includes two or more products that use different clone protection schemes and produce different results, the API returns a separate result for each cloned product, instead of stopping at the first cloned product. For example:

•When multiple products are affected, the response will include a separate <product> entry for each:

<result>
 <product>
  <id>1</id>
  <cloned>yes</cloned>
  <mismatched_items>
    <item name="computer_name"/>
    <item name="domain_name"/>
    <item name="version"/>
    <item name="ip_address"/>
  </mismatched_items>
 </product>

 <product>
  <id>11</id>
  <cloned>yes</cloned>
  <mismatched_items>
    <item name="computer_name"/>
    <item name="ip_address"/>
  </mismatched_items>
 </product>
</result>

Syntax

sntl_lg_status_t  SNTL_LG_CALLCONV sntl_lg_validate_fingerprint (
          sntl_lg_handle_t       handle,
          sntl_lg_vendor_code_t  vendor_code,  
          const char *           fingerprint, 
          const char *           update_data, 
          char **                result_info
)

Parameters

`handle`	[IN] License generation handle.
`vendor_code`	[IN] Pointer to the Vendor Code.
`fingerprint`	[IN] String representing the fingerprint of the machine.
`update_data`	[IN] Pointer to a valid V2C file or resultant state.
`result_info`	[OUT] Returns an XML string indicating whether the fingerprint matches. If it does not match, the XML includes details of the mismatched items.

Return Values

SNTL_LG_STATUS_OK

SNTL_LG_OUT_OF_MEMORY

SNTL_LG_INVALID_PARAMETER

SNTL_LG_INVALID_HANDLE

SNTL_LG_INVALID_VENDOR_CODE

SNTL_LG_INVALID_KEY_CURRENT_STATE

SNTL_LG_INTERNAL_ERROR

SNTL_LG_MASTER_KEY_IO_ERROR

SNTL_LG_MASTER_KEY_ACCESS_ERROR

SNTL_LG_INVALID_FINGERPRINT