Offline Licensing

40min
In certain scenarios, some computers may lack an active internet connection or be behind a restrictive firewall, hindering online activation. 
To address this, we have developed a mechanism that enables the activation and deactivation of licenses in an offline environment.
Prerequisites
Completed the Getting Started﻿ Tutorial, specifically:
Initialized LicenseManager (or LicenseHandler) with your configuration using the appropriate settings.
Created a LicenseID using either LicenseID::fromKey or LicenseID::fromUser function, depending on the activation method you prefer.
Performing offline license activation using the LicenseSpring SDKs is a straightforward process. Follow the steps below to activate and deactivate licenses:
License Activation Process:
Generate a request file by calling the createOfflineActivationFile function of LicenseManager. Provide the LicenseID you created earlier and specify the path where you want to save the request file. The function will return the path to the created file.
Open the offline activation page and upload the request file you generated in the previous step. Once uploaded, download the offline activation file from this page.
Activate the license by calling the activateLicenseOffline function of LicenseManager and passing the path to the offline activation file received from the website. The function will return a License object upon successful activation, or null if the activation process fails. 
License Deactivation Process:
Call the deactivateOffline function of the License object, and optionally provide the path where you want to save the deactivation request file. The function will return the path to the created file.
Call the clearLocalStorage function of LicenseManager to delete the files created by the SDK to store license data.
Open the offline activation page and upload the deactivation request file you generated in the previous step. Once uploaded, you will receive a message confirming that the license has been deactivated.
Let's get started!
Offline Activation Process
Request File Creation
To initiate offline license activation, the first step involves creating an offline activation request file. 
You can accomplish this by utilizing the following function:
C++
Swift
|
let fileLocation = try manager.createOfflineActivationFile(licenseKey: "XXXX-XXXX-XXXX-XXXX")
let fileLocation = try manager.createOfflineActivationFile(licenseKey: "XXXX-XXXX-XXXX-XXXX")
﻿
The provided function generates an offline activation request file for the specified key-based/user-based license, identified by LicenseID. 
If you include a 'path' parameter, the file will be created with the specified path and name. 
Note: If 'path' is not provided, the default location for the offline activation request file will be the desktop, and the default name will be "ls_activation.req": C:\Users%USERNAME%\Desktop\ls_activation.req.
Uploading the Request to the Offline Activation Portal
Once you have generated your offline activation request file, the next step is to upload it to the LicenseSpring offline portal. It's essential to note that this process requires a computer with online access.
﻿
LicenseSpring Offline Portal
﻿
Upon uploading the request file, you will receive an offline activation response file named "ls_activation.lic." This response file will enable you to proceed with the offline activation process successfully.
Activation With a Response File 
To complete the offline activation process on a device, utilize the function activateLicenseOffline(path) as demonstrated below:
C++
C#
Swift
|
let responseFile: URL = ...
let license = try manager.activateLicenseOffline(responseFile)
let responseFile: URL = ...
let license = try manager.activateLicenseOffline(responseFile)
﻿
In the 'path' parameter, provide the name and path of the offline activation response file. 
If 'path' is left empty, the function will search for the response file named "ls_activation.lic" on the desktop by default: C:\Users%USERNAME%\Desktop\ls_activation.lic.
By running this, you will have successfully activated the license offline on the device.
There is a checker for if the license is offline activated also, as shown below:
C++
Swift
|
license.isOfflineActivated
license.isOfflineActivated
﻿
This Boolean checker returns true if offline activated, and false if not.
How to Secure Offline Activation With ExtendedOptions::enableGuardFile 
Guard files prevent users from using the same license request file and are automatically enabled within ExtendedOptions. 
Guard files can be disabled in the ExtendedOptions constructor or by running the following method, where options is an ExtendedOptions object:
C++
|
options.enableGuardFile( false );
options.enableGuardFile( false );
﻿
Once enabled, LicenseSpring generates a guard file in the same folder where the license and SDK logs are stored. 
This guard file remains hidden and plays a crucial role in safeguarding the licensing process. Should anyone attempt to remove or alter this file, the license activation will fail as a protective measure.
The guard file is automatically created when you generate the request file for offline activation. 
It must remain valid and present when a user submits the response file to ensure a successful activation process. The presence of the guard file is pivotal for maintaining the integrity and security of the offline activation procedure.
To determine the current status of the guard file, you can utilize the following method (where options is an ExtendedOptions object):
C++
|
bool guardFileTest = options.isGuardFileEnabled();
bool guardFileTest = options.isGuardFileEnabled();
﻿
If a guard file is actively protecting the offline activation process guardFileTest returns true.
This method also exists within the Configuration object, so using the following (where config is a Configuration object) will yield an identical result:
C++
|
bool guardFileTest = config.isGuardFileEnabled();
bool guardFileTest = config.isGuardFileEnabled();
﻿
Offline License Update
How to Get a Refresh File
Offline license refresh allows users to update their activated offline license, which is typically used when certain aspects of the license have been modified on the backend. 
For instance, you might want to add a new feature without requiring license reactivation. 
To perform an offline license refresh, locate the license on the LicenseSpring Platform and access the Devices tab.
﻿
Downloading License Refresh File
﻿
UpdateOffline Method Usage
The line of code responsible for the update is as follows:
C++
Swift
|
let updateFile: URL = ...
try license.updateOffline(with: updateFile)
let updateFile: URL = ...
try license.updateOffline(with: updateFile)
﻿
In the path parameter, you should provide the path to the license_refresh.lic file, which you downloaded from the page, as shown above.
updateOffline also has a secondary optional parameter, resetConsumpion, which is disabled by default. If this parameter is set to true, then this update also resets the consumption.
This method returns true if the license is successfully updated, and false otherwise.
Offline Deactivation
How to Create Deactivation Request File
Once a license has been activated, it can also be deactivated through a similar process. The function responsible for creating the offline deactivation request file is as follows:
C++
Swift
|
let request = try license.deactivateOffline()
let request = try license.deactivateOffline()
﻿
Additionally, you have the option to provide an alternative path as an optional parameter to the deactivateOffline function, where the deactivation request file will be created and stored. 
Note: If you leave this parameter empty, the default file path will be used, saving the file to the desktop.
Deleting Local License File
To eliminate any local license data, after creating the deactivation file, we execute the following:
C++
Swift
|
try manager.clearLocalStorage()
try manager.clearLocalStorage()
﻿
By performing these steps, you can efficiently deactivate the license and clear any associated local data.
Code Sample 
Loading Local License and Creating Offline Activation Request File
First we load the local license, using getCurrentLicense whilst checking for any local license errors:
C++
|
try
    {
        license = licenseManager->getCurrentLicense();
    }
    catch ( LocalLicenseException )
    { 
        //Cannot read the local license or the local license file is corrupt
    }
auto filePath = licenseManager->createOfflineActivationFile( licenseId );
     //Request file created at filePath
     //Upload request file to the LicenseSpring portal to get response file.
try
    {
        license = licenseManager->getCurrentLicense();
    }
    catch ( LocalLicenseException )
    { 
        //Cannot read the local license or the local license file is corrupt
    }
auto filePath = licenseManager->createOfflineActivationFile( licenseId );
     //Request file created at filePath
     //Upload request file to the LicenseSpring portal to get response file.
﻿
Similarly to creating a deactivation request file, we can select a path for this file to be created or use the default path by leaving the path as null in createOfflineActivationFile( licenseID, path ).
Note: If the path parameter is null, then the default path that createOfflineActivationFile( licenseID ) creates the file at is: 'C:\Users\%USERNAME%\Desktop\ls_deactivation.req'.
Activating Offline License Using Activation Response File
Now that we have submitted the offline activation file to the portal and downloaded the activation response file, we must activate our device locally.
After checking that our local license is not active, we run activateLicenseOffline( path ).
C++
|
if ( license == nullptr ) 
  {
    try
      {
        license = licenseManager->activateLicenseOffline( path );
      }
    catch ( SignatureMismatchException )
      {
        //Signature inside activation file is not valid." << std::endl;
      }
if ( license == nullptr ) 
  {
    try
      {
        license = licenseManager->activateLicenseOffline( path );
      }
    catch ( SignatureMismatchException )
      {
        //Signature inside activation file is not valid." << std::endl;
      }
﻿
Note: If the path parameter is null, then the default path that activateLicenseOffline searches for the file is: 'C:\Users\%USERNAME%\Desktop\ls_deactivation.req'.
﻿
Local License Check
To verify the license locally on the device without connecting to the backend, we utilize the localCheck function in the following manner:
C++
|
if ( license != nullptr )
  {
    license->localCheck();
  }
if ( license != nullptr )
  {
    license->localCheck();
  }
﻿
If license is a nullptr, it indicates that a local license does not exist. Therefore, it is crucial to first confirm the existence of a local license before proceeding with any operations related to the license. 
The localCheck function also throws exceptions to indicate any encountered issues. 
This feature proves beneficial in assessing the license's validity and detecting potential license tampering. If any irregularities are detected, the function will throw an exception.
To ensure license integrity, it is considered best practice to perform a localCheck (offline check) during each startup. 
This practice helps confirm that the license file has not been copied from another computer and that the license is in a valid state.
A code sample that handles all potential exceptions is also provided below:
C++
|
if ( license != nullptr )
    {
        try
        {
            license->localCheck();
        }
        catch ( LicenseStateException )
        {
            //License Invalid
            if ( !license->isActive() )
                //License Inactive
            if ( license->isExpired() )
                //License Expired
            if ( !license->isEnabled() )
                //License Disabled
        }
        catch ( ProductMismatchException )
        {
            //License does not belong to configured product.
        }
        catch ( DeviceNotLicensedException )
        {
            //License does not belong to current computer.
        }
        catch ( VMIsNotAllowedException )
        {
            //Currently running on VM, when VM is not allowed.
        }
        catch ( ClockTamperedException )
        {
            //Detected cheating with system clock.
        }
    }
if ( license != nullptr )
    {
        try
        {
            license->localCheck();
        }
        catch ( LicenseStateException )
        {
            //License Invalid
            if ( !license->isActive() )
                //License Inactive
            if ( license->isExpired() )
                //License Expired
            if ( !license->isEnabled() )
                //License Disabled
        }
        catch ( ProductMismatchException )
        {
            //License does not belong to configured product.
        }
        catch ( DeviceNotLicensedException )
        {
            //License does not belong to current computer.
        }
        catch ( VMIsNotAllowedException )
        {
            //Currently running on VM, when VM is not allowed.
        }
        catch ( ClockTamperedException )
        {
            //Detected cheating with system clock.
        }
    }
﻿
Offline Update
To update licenses offline, we use the updateOffline( path ) method as shown below, where license is a license object.
C++
|
if ( license->updateOffline( path ) )
  {
    //License succesfully updated.
  }
else
  //License could not be updated.
          
if ( license->updateOffline( path ) )
  {
    //License succesfully updated.
  }
else
  //License could not be updated.
          
﻿
Just like the previous code sample, we can also first check whether license is a nullptr to confirm the local license exists before we attempt to update it.
We can also handle the specific exceptions thrown by updateOffline( path ) as shown below:
C++
|
if ( license == nullptr ) 
    //Cannot refresh an inactive license.
else
  {
    try 
      {
        if ( license->updateOffline( path ) )
          {
            //License succesfully updated.
          }
        else
          {
            //License could not be updated.
          }
      }
    catch ( SignatureMismatchException )
        {
          //Device does not match update file's device signature.
        }
    catch ( LocalLicenseException )
        {
          //Local license file cannot be read, may be corrupted.
        }
    catch ( ProductMismatchException )
        {
          //License product code doesn't match configuration product code.
        }
    catch ( DeviceNotLicensedException )
        {
          //License refresh file does not correspond to current device.
        }
    } 
if ( license == nullptr ) 
    //Cannot refresh an inactive license.
else
  {
    try 
      {
        if ( license->updateOffline( path ) )
          {
            //License succesfully updated.
          }
        else
          {
            //License could not be updated.
          }
      }
    catch ( SignatureMismatchException )
        {
          //Device does not match update file's device signature.
        }
    catch ( LocalLicenseException )
        {
          //Local license file cannot be read, may be corrupted.
        }
    catch ( ProductMismatchException )
        {
          //License product code doesn't match configuration product code.
        }
    catch ( DeviceNotLicensedException )
        {
          //License refresh file does not correspond to current device.
        }
    } 
﻿
License Deactivation
To deactivate a license offline, first ensure that the license is currently active. Then an offline deactivation request file will be created at the path defined in the parameter of deactivateOffline( path ).
Note: If the path parameter is null, then the default path that deactivateOffline() creates the file at is: 'C:\Users\%USERNAME%\Desktop\ls_deactivation.req'.
After creating the offline deactivation request file, it is vital that the local license file is deleted, using clearLocalStorage.
A full code sample is as follows:
C++
|
if ( license != nullptr && license->isActive() )
  {
    try
      {
        auto filePath = license->deactivateOffline( path );
      }
    catch ( LocalLicenseException )
      {
        //Local license file cannot be read, may be corrupted.
      }
    licenseManager->clearLocalStorage();
    //To finish deactivation process, upload deactivation request file to the LicenseSpring portal.
  }
else
    //License is already deactivated.
if ( license != nullptr && license->isActive() )
  {
    try
      {
        auto filePath = license->deactivateOffline( path );
      }
    catch ( LocalLicenseException )
      {
        //Local license file cannot be read, may be corrupted.
      }
    licenseManager->clearLocalStorage();
    //To finish deactivation process, upload deactivation request file to the LicenseSpring portal.
  }
else
    //License is already deactivated.
﻿
Automating Offline Licensing
Automating the offline activation process becomes achievable by utilizing the following API endpoints:
﻿Offline Activation﻿
﻿Offline Deactivation﻿
These endpoints provide developers with the necessary tools to seamlessly manage offline license activation, enabling users to access and activate licenses without relying on a constant internet connection. 
Note: If you want to use these API endpoints directly, instead of using the SDK, please contact us for additional instructions.
Troubleshooting
Exceptions Related to Offline Activation
Exceptions that might occur when performing offline license activation:
SignatureMismatchException: Signature inside activation file is not valid.
LocalLicenseException: Invalid activation file provided.
ProductMismatchException: License product code does not correspond to configuration product code.
DeviceNotLicensedException: License file does not belong to the current device.
Why is the License File Not Generated After Uploading the Request File?
The offline license activation process may encounter failure due to any of the following reasons:
Total activations on the account have reached the maximum limit.
The license is expired or disabled.
Incorrect license credentials provided during activation.
Incorrect product configuration, such as using a shared key, API key, or product code.
The license is associated with an account using the free tier.
﻿
Updated 05 Sep 2023
Did this page help you?