Licensefile Setup and Usage
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.
After you have successfully setup your key and IV you should setup your Configuration.
- product (str): product short code.
- api_key (str): Your unique API key used for authentication with the licensing server.
- shared_key (str): 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 for 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
Represents a mechanism for license identification and activation, supporting both key-based and user-based activations.
- 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.
Manages license activations, supporting a variety of parameters to accommodate different licensing scenarios.
- conf (Configuration): A configuration object
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 if prefered that given argument is used when activating user based licenses
Loads the license file and sets attributes for the LicenseData instance. Returns an instance of the License class reflecting the loaded license.
Get current configuration
Returns (dict): Current configuration
Change the current configuration
Checks if licensefile is corrupted
Returns (bool): If the file is corrupted return True, otherwise False
Delete all files for given product
Get licensefile location
Returns (str): Licensefile location
Get licensefile name
Returns (str): licensefile name
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.
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
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 activation code for air gap license
Parameters:
- initialization_code (str): initialization code
- license_key (str): license key
Return (str): activation code
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
Creates LiceseID for trial licenses
Parameters:
- customer (Customer): Customer object
- license_policy(str,optional): icense policy code. Defaults to None.
Return(LicenseID): Returns a LicenseID object.
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
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
Parameters:
- customer (Customer): customer
Return(dict): customer license user
Get user licenses
Parameters:
- license_id (LicenseID): license_id
Return(list): User licenses
Object responsible for license operations
Determines wheter the license floating period has expired
Return (bool): True if floating expired otherwise False
Determines whether the license's validity period has expired
Return (bool): True if license expired otherwise False
Gets the license validity period
Return (datetime): Datetime in UTC
Gets the validity period with grace period of the license
Return (datetime): Datetime in UTC
Gets how many days are left until the maintenance ends
Return (int): Maintenance days left
Gets how many days are left until the validity period ends
Return (int): Validity period days left
Gets customer information
Return (dict): Customer information
Gets a license id
Return (int): license id
Get a license max transfers
Return (int): max transfers
Get the transfer count
Return (int): transfer count
Get if a device transfer is allowed
Return (bool): True if device transfer is allowed otherwise False
Get if a device transfer is limited
Return (bool): True if device transfer is limited otherwise False
Get how many days passed since the last check
Return (int): How many days have passed since last check
Get a license start date
Return (datetime): Datetime in UTC
Get a license maintenance period
Return (datetime): Datetime in UTC
Checks if maintence period has expired
Return (bool): If maintence period expired returns True otherwise False
Get when last check was performed
Return (datetime): Datetime in UTC
Gets a license last usage
Return (datetime): Datetime in UTC
Gets the last license usage
Return (str): license_type
Gets the license max activations
Return (int): max activations
Gets the license metadata
Return (dict): metadata
Check if unlimited activations are allowed
Return (bool): If unlimited activations are allowed returns True otherwise False
Check if grace subscription period is allowed
Return (bool): If grace subscription period is allowed returns True otherwise False
Check if grace subscription period has started
Return (bool): If grace subscription period has started returns True otherwise False
Get grace period
Return (int): Grace period
Get subscription grace period
Return (int): Subscription grace period
Checks if a license validity has expired
Return (bool): True if license has expired otherwise False
Checks if a license is enabled
Return (bool): True if license is enabled otherwise False
Checks if a license is active
Return (bool): True if license is active otherwise False
Checks if the license is valid (license is active, enabled and didn't expired)
Return (bool): True if a license is valid otherwise False
Checks if a license prevents virtual machines
Return (bool): True if license prevents VM's otherwise False
Checks if a license is trial
Return (bool): True if a license is trial otherwise False
Get the expiry date of a floating license
Return (datetime): Expiry date in UTC
Get the date until a license is borrwed
Return (datetime): borrow date in UTC
Check if a license is borrowed
Return (bool): True if license is borrowed otherwise False
Get local consumptions
Return (int): Local consumptions
Get max consumptions
Return (int): max consumptions
Get total consumptions
Return (int): total consumptions
Get max overages
Return (int): max overages
Check if unlimited consumptions are allowed
Return (bool): If unlimited consumptions allowed return True otherwise False
Check if there is consumption reset
Return (bool): If there is consumption reset returns True otherwise False
Check if overages are allowed
Return (bool): If overages are allowed returns True otherwise False
Get consumption period
Return (str): Consumption period
Get feature data
Parameters:
- feature_code (str): feature code
Return (dict): Feature
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
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.
Raises:
ClientError: Raised if there's an issue with the API client's request, such as invalid credentials or unauthorized access.
RequestException: Raised if there's a problem with the request to the licensing server, such as network issues or server unavailability.
Return (dict): The updated license cache.
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
This method 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. This is more relevant if is_floating_expired is later implemented to perform actual checks.
ClockTamperedException: Raised if there is evidence of tampering with the system's clock, detected by comparing the system's current time with the last usage time recorded in the license file.
Return: None
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 (i.e., not a consumption-based license).
ConsumptionError: Raised if adding the specified number of consumptions would exceed the allowed maximum for the license.
Return: None
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, for instance, due to network issues or server unavailability.
Return (bool): True if the consumption data was successfully synchronized; False otherwise.
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
Changes password of a user
Return (str): "password_changed"
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_code` does 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
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, for instance, due to network issues or server unavailability.
Return (bool): True if the consumption data was successfully synchronized; False otherwise.
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.
Return: None
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
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
Releases a borrowed license feature and updates the license cache accordingly.
Parameters:
- feature(str): feature code.
Raises:
Exception
Return: None
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
Generates .req file for the offline deactivation
Parameters:
- offline_path (str): path of the .req file
Return (str): path of the deactivation file
Get deactivation code for air gap licenses
Parameters:
- initialization_code (str): initialization_code
Return (str): deactivation code
Deactivate air gap license and clear storage
Parameters:
- confirmation_code (str): confirmation_code
Raises:
- LicenseActivationException: VerificationError
Return: None
Update product details from LicenseSpring server
Parameters:
- include_custom_fields(bool, optional): custom fields information. Defaults to False.
- include_latest_version(bool, optional): Lateset version information. Defaults to False.
Return(dict): response
Get product details from Licensefile
Return(dict): Product details
Get device variable if exists
Parameters:
- variable_name(str): variable name
Return(dict): variable dictionary
Set device variables locally
Parameters:
- variables(dict): variables dict
- save(bool, optional): Save cache to licensefile. Defaults to True.
Return: None
Get device variables from server or locally
Parameters:
- get_from_be(bool, optional): If True collects data from LicenseSpring server. Defaults to True.