Licensefile Setup and Usage
Licensefile Setup
Key and IV Setup
To use licensefile inside a python SDK you should first setup your key and IV. Key and IV are used inside Python SDK for encryption and decryption process inside licensefile. This process is only required once at the setup.
from licensespring.licensefile.default_crypto import DefaultCryptoProvider
password = "YOUR_PASSWORD"
salt = "YOUR_SALT"
crypto = DefaultCryptoProvider()
key = crypto.derive_key(password=password,salt=salt)
iv = crypto.generate_random_iv()
Configuration Setup
After you have successfully setup your key and IV you should setup your Configuration.
from licensespring.licensefile.config import Configuration
#from licensespring.hardware import HardwareIdProviderSource
#The commented hardware_id_provider will become the default in the next major version of the SDK
#we advise using HardwareIdProviderSource!
conf = Configuration(product="your_product_key",api_key="your_api_key",
shared_key="your_shared_key",file_key=key,file_iv=iv,
is_guard_file_enabled=True,
#hardware_id_provider=HardwareIdProviderSource)Configuration Attributes
api_key (str, optional): Your unique API key used for authentication with the licensing server.
shared_key (str, optional): A shared secret key used alongside the API key for enhanced security during the license verification process.
file_key (str): The encryption key used for securing license files on the client side.
file_iv (str): The initialization vector for the encryption algorithm. This complements the file_key for encrypting and decrypting license files.
hardware_id_provider (object, optional): The provider class used for generating a unique hardware ID. This ID helps in binding the license to specific hardware. Defaults to HardwareIdProvider.
verify_license_signature (bool, optional): A boolean flag indicating whether the license's digital signature should be verified. Defaults to True for enhanced security.
signature_verifier (object, optional): The class responsible for verifying the digital signature of licenses. Defaults to SignatureVerifier.
api_domain (str, optional): The domain name of the API server with which the licensing operations are performed. Defaults to "api.licensespring.com".
api_version (str, optional): The version of the API to use for requests. This allows for compatibility with different versions of the licensing API. Defaults to "v4".
filename (str, optional): The default filename for saved license files. This can be customized as needed. Defaults to "License".
file_path (str, optional): The path where license files should be saved on the client system. If not specified, a default location is used.
grace_period_conf (int, optional): The number of hours to allow as a grace period. Defaults to 24 hours.
is_guard_file_enabled (bool): Enables guard protection for offline licenses if set to True.
air_gap_public_key (str, optional): Air gap public key.
client_id (str, optional): Client ID for OAuth authorization purposes.
client_secret (str, optional): Client Secret for OAuth authorization purposes.
certificate_chain_path (str, optional): path to
.pemfile used in provisioning (e.g "path_to_chain.pem").
We advise for hardware_id_provider to use a newly developed HardwareIdProviderSource provider.
On the next major version release HardwareIdProviderSource will be set as default hardware_id_provider.
If both API keys and OAuth are specified in Configuration, SDK will use OAuth for authorization.
LicenseID
Represents a mechanism for license identification and activation, supporting both key-based and user-based activations.
Methods
from_key(cls, key) - class method to create a LicenseID instance for key-based activation.
from_user(cls, username, password) - class method to create a LicenseID instance for user-based activation.
Key-Based Setup
User-Based Setup
LicenseManager
Manages license activations, supporting a variety of parameters to accommodate different licensing scenarios.
Configuration parametres
conf (Configuration): A configuration object
Methods
Getters
activate_license
Activates a license with the license server and updates local license data. Returns an instance of the License.
Key-based:
User-based:
There is optional unique_license_id which specifies license_id. It is preferred that given argument is used when activating user based licenses.
load_license
Loads the license file and sets attributes for the LicenseData instance. Returns an instance of the License class reflecting the loaded license.
reconfigure
Change the current configuration
clear_local_storage
Delete all files for given product
set_data_location
Set data location
Parameters:
path (str): new data location path
Return: None
set_license_file_name
Set licensefile name
Parameters:
name (str): license file name
Return: None
is_online
Checks if the licensing server is accessible.
Parameters:
throw_e (bool, optional): If True throws exception, otherwise exception won't be raised.
Returns: True if online, False otherwise.
create_offline_activation_file
Creates request file for offline activation.
Parameters:
license_id (LicenseID)
req_path (str): path where .req file is created
Returns (str): path to request file
activate_license_offline
Activates the .lic file
Parameters:
ls_activation_path (str): path to .lic file
Raises:
LicenseActivationException: Activation data is not valid
LicenseActivationException: Response file ID mismatch
LicenseActivationException: License does not belong to this device
Returns (License): License object
get_air_gap_activation_code
Get activation code for air gap license
Parameters:
initialization_code (str): initialization code
license_key (str): license key
Return (str): activation code
activate_air_gap_license
Activates air gap license
Parameters:
confirmation_code (str): confirmation code
policy_path (str): policy path (file or folder)
license_key (str): license_key
policy_id (str): policy id
Raises:
LicenseActivationException: Signature verification failed
Return (License): License
get_trial_license
Creates LicenseID for trial licenses
Parameters:
customer (Customer): Customer object
license_policy (str, optional): license policy code. Defaults to None.
Return (LicenseID): Returns a LicenseID object.
get_version_list
Get versions
Parameters:
license_id (LicenseID): license id object
bundle_code (str, optional): specify unique bundle_code of a bundle
unique_license_id (int, optional): A unique identifier for the license.
env (str, optional): Version of environment
Return (list): List of versions
get_installation_file
Get installation file
Parameters:
license_id (LicenseID): An instance containing the license key or user credentials
bundle_code (str, optional): specify unique bundle_code of a bundle
unique_license_id (int, optional): A unique identifier for the license.
env (str, optional): Version of environment
version (str, optional): Versions
Return (dict): installation file
get_customer_license_users
Get customer license users
Parameters:
customer (Customer): customer
Return (dict): customer license user
get_user_licenses
Get user licenses
Parameters:
license_id (LicenseID): license_id
Return (list): User licenses
get_sso_url
Parameters:
account_code (str): account code
use_auth_code (bool, optional): Use code for response_type. Defaults to True.
Return (dict): url
get_product_details
Parameters:
include_latest_version (bool, optional): include_latest_version. Defaults to False.
include_custom_fields (bool, optional): include_custom_fields. Defaults to False.
env (str, optional): env. Defaults to None.
Return (dict): Product details
Bundle Manager
Object responsible for Bundle operations
activate_bundle
Activates the bundle
Parameters:
license_id (LicenseID): An instance containing the license key or user credentials.
hardware_id (str, optional): A unique identifier for the hardware.
unique_license_id (int, optional): A unique identifier for the license.
customer_account_code (str, optional): An account code for the customer.
id_token (str, optional): Token for identity verification.
code (str, optional): An additional code for license verification.
app_ver (str, optional): The version of the application requesting activation.
os_ver (str, optional): The operating system version of the host.
hostname (str, optional): The hostname of the device requesting activation.
ip (str, optional): The IP address of the device.
is_vm (bool, optional): Indicates whether the application is running on a virtual machine.
vm_info (str, optional): Information about the virtual machine, if applicable.
mac_address (str, optional): The MAC address of the device.
Return (dict[str, License]): A dictionary where the keys are product short codes and the values are License objects.
get_current_bundle
Get current bundle from cache or licensefile.
Return (dict[str, License]): A dictionary where the keys are product short codes and the values are License objects.
create_offline_activation_file
Creates .req file for activation
Parameters:
license_id (LicenseID): An instance containing the license key or user credentials.
req_path (str): Specify place where to create .req file
hardware_id (str, optional): A unique identifier for the hardware.
app_ver (str, optional): The version of the application requesting activation.
os_ver (str, optional): The operating system version of the host.
hostname (str, optional): The hostname of the device requesting activation.
ip (str, optional): The IP address of the device.
is_vm (bool, optional): Indicates whether the application is running on a virtual machine.
vm_info (str, optional): Information about the virtual machine.
mac_address (str, optional): The MAC address of the device.
device_variables (dict, optional): device variables.
Return (str): path of the .req file
activate_bundle_offline
Activate offline bundle licenses
Parameters:
ls_activation_path (str): path to a .lic file
Return (dict[str, License]): dictionary of licenses in a bundle
deactivate_bundle_offline
Generates .req file for the offline deactivation
Parameters:
license_id (LicenseID)
offline_path (str): path of the .req file
unique_license_id (int): unique license id
Return (str): path of the deactivation file
check_bundle
Check bundle and update the licensefile
Parameters:
license_id (LicenseID)
hardware_id (str, optional): A unique identifier for the hardware. Defaults to None.
unique_license_id (int, optional): A unique identifier for the license. Defaults to None.
include_expired_features (bool, optional): If True, includes expired license features in the check. Defaults to False.
env (str, optional): optional param takes "win", "win32", "win64", "mac", "linux", "linux32" or "linux64". Defaults to None.
Returns (dict[str, License]): A dictionary where the keys are product short codes and the values are License objects.
deactivate_bundle
Deactivate bundle
Parameters:
license_id (LicenseID)
hardware_id (str, optional): hardware id. Defaults to None.
unique_license_id (int, optional): A unique identifier for the license. Defaults to None.
remove_local_data (bool, optional): remove licensefile from storage. Defaults to False.
License
Object responsible for license operations
Methods
Getters
All getters which are reading the license fields from a local licensefile
check_license_status
Verifies the current status of the license. It raises exceptions if the license is not enabled, not active, or expired.
Raises:
LicenseStateException: Raised if the license fails one of the following checks:
License is not enabled.
License is not active.
License validity period has expired.
Return: None
check
Performs an online check to synchronize the license data with the backend. This includes syncing consumptions for consumption-based licenses.
Parameters:
include_expired_features (bool, optional): Includes expired license features in the check.
env (str, optional): "win", "win32", "win64", "mac", "linux", "linux32" or "linux64"
Raises:
ClientError: Raised if there's an issue with the API client's request.
RequestException: Raised if there's a problem with the request to the licensing server.
Return (dict): The updated license cache.
deactivate
Deactivates the license and optionally deletes the local license file.
Parameters:
delete_license (bool, optional): If True, deletes the local license file upon deactivation.
Return: None
local_check
Ensures the integrity and consistency of the licensing information by comparing the data stored in the local license file with the predefined configurations in the Configuration object.
Raises:
ConfigurationMismatch: Raised if the product code or hardware ID in the license file does not match the expected values provided in the Configuration.
VMIsNotAllowedException: Raised if the license is used in a VM environment when the license explicitly disallows it.
TimeoutExpiredException: Raised if a floating license has expired.
ClockTamperedException: Raised if there is evidence of tampering with the system's clock.
Return: None
add_local_consumption
Adds local consumption records for consumption-based licenses.
Parameters:
consumptions (int, optional): The number of consumptions to add locally.
Raises:
LicenseSpringTypeError: Raised if the license type does not support consumption.
ConsumptionError: Raised if adding the specified number of consumptions would exceed the allowed maximum for the license.
Return: None
sync_consumption
Synchronizes local consumption data with the server, adjusting for overages if specified.
Parameters:
req_overages (int, optional): Specifies behavior for consumption overages.
Raises:
RequestException: Raised if the request to synchronize consumption data with the server fails.
Return (bool): True if the consumption data was successfully synchronized; False otherwise.
is_grace_period
Determines if the current license state is within its grace period following a specific exception.
Parameters:
ex (Exception): Raised Exception
Return (bool): True if the license is within its grace period, False otherwise.
change_password
Changes password of a user
Return (str): "password_changed"
add_local_feature_consumption
Adds local consumption to the feature.
Parameters:
feature (str): feature code.
consumptions (int, optional): Number of consumptions.
Raises:
ItemNotFoundError: If the feature specified by
feature_codedoes not exist.LicenseSpringTypeError: If the identified feature is not of the "consumption" type.
ConsumptionError: If adding the specified number of consumptions would exceed the feature's consumption limits.
Return: None
sync_feature_consumption
Synchronizes local consumption data with the server.
Parameters:
feature (str): feature code.
Raises:
RequestException: Raised if the request to synchronize consumption data with the server fails.
Return (bool): True if the consumption data was successfully synchronized; False otherwise.
floating_borrow
Attempts to borrow a floating license until the specified date.
Parameters:
borrow_until (str): A string representing the date until which the license should be borrowed.
password (str, optional)
id_token (str, optional)
code (str, optional)
customer_account_code (str, optional)
Return: None
floating_release
Releases a borrowed floating license and updates the license status accordingly.
Parameters:
throw_e (bool): A boolean indicating whether to raise an exception on failure.
Raises:
Exception
Return: None
check_feature
Checks for a specific license feature and updates the license cache accordingly.
Parameters:
feature (str): feature code.
add_to_watchdog (bool, optional): A boolean indicating whether to add the feature check to a watchdog routine. Default is False.
Raises:
Exception
Return: None
release_feature
Releases a borrowed license feature and updates the license cache accordingly.
Parameters:
feature (str): feature code.
Raises:
Exception
Return: None
update_offline
Updates license via refresh file
Parameters:
path (str): path of the refresh file
reset_consumption (bool): True resets consumption otherwise False
Raises:
ConfigurationMismatch: The update file does not belong to this device
ConfigurationMismatch: The update file does not belong to this product
Return (bool): True if license was successfully updated otherwise False
deactivate_offline
Generates .req file for the offline deactivation
Parameters:
offline_path (str): path of the .req file
device_variables (dict): device variables
Return (str): path of the deactivation file
get_deactivation_code
Get deactivation code for air gap licenses
Parameters:
initialization_code (str): initialization_code
Return (str): deactivation code
deactivate_air_gap
Deactivate air gap license and clear storage
Parameters:
confirmation_code (str): confirmation_code
Raises:
LicenseActivationException: VerificationError
Return: None
product_details
Update product details from LicenseSpring server
Parameters:
include_custom_fields (bool, optional): custom fields information. Defaults to False.
include_latest_version (bool, optional): Latest version information. Defaults to False.
env (str, optional): "win", "win32", "win64", "mac", "linux", "linux32" or "linux64"
Return (dict): response
set_device_variables
Set device variables locally
Parameters:
variables (dict): variables dict
save (bool, optional): Save cache to licensefile. Defaults to True.
Return: None
get_device_variables
Get device variables from server or locally
Parameters:
get_from_be (bool, optional): If True collects data from LicenseSpring server. Defaults to True.
Return (list): List of device variables
send_device_variables
Send device variables to LicenseSpring server. Handles GracePeriod
Parameters:
variables (dict): variables dict
save (bool, optional): Save cache to licensefile. Defaults to True.
Return (bool): True if new variables are sent to LicenseSpring server otherwise, False
custom_fields
Get custom fields from licensefile
Return (list): Custom fields
Was this helpful?