Note: a seprate subscription is required to use the license server: https://cryptolens.io/products/license-server/
Idea
Problem: Large companies tend to have strict policies that restrict certain machines to have direct internet access. This is a problem if we want license files on them to be up-to-date. Solution: We allow one computer, the license server, to have internet access. All the machines in the network will contact the license server and it will in turn contact Cryptolens. Alternatively, the license server can store a copy of the license files and work offline.
Getting started
Since v2.12-rc, there are two ways you can configure the server. Either, you can use the pre-built version of the server or you can use the configuration string from this page and build the server yourself.Using the pre-built license server
You can use our pre-built binaries for all use cases (including the local floating license server feature). When you use the binaries, you can either store the configuration in the config file (as we describe later), configure the server using environment variables (read more here) or pass on the configuration as a command line variable (read more here). Please keep in mind that the license server will only read the environment variables or the -config command line parameter if you run it as a service (read more here), unless you setcryptolens_configurationstring
environment variable with the configuration string from this page.
To sum up, you can start the server in two ways:
- If you choose to use environment variable, you would need to set
cryptolens_configurationstring
to the configuration string. - If you instead want to supply the configuration string as a command line argument, you can start the server using as follows:
- By using a
config.json
file (not recommended).
Building the server yourself
If you need the local floating license server and cannot use environment variables or pass the configuration string as a command line argument as described here, the license server needs to be compiled on your end to create the binaries. All configuration is stored inside theConfigurationFromCryptolens
variable in Program.cs
, which can be created on this page. In other words, there is no need to provide any arguments when calling the license server or use an external configuration file.
The license server can be compiled on most operating systems and the process is as follows:
Install .NET
To install .NET, visit https://dotnet.microsoft.com/en-us/download/dotnet/6.0 and download the SDK (i.e. not the runtime).Configuring the server
There are three steps involved:- Visit the configuration page to create a configuration that will make the server work in standard mode.
- Copy the configuration string and paste it in the
ConfigurationFromCryptolens
variable inProgram.cs
. - Environment variables can also be used to change configuration data for a specific user. Please read more here.
Building the server
To build the server, you can run the following command in the folder that contains theLicenseServerCore.sln
file:
Starting the server
In order to launch the server, you need to runLicenseServer.exe
as an administrator (you can download it here). The default port is 8080 but this can be changed. One way of doing it is to run CMD as an administrator and then type the command below:
Please make sure to check that this port is open so that other computers in the network can access it (shown below).
Running as a Windows service
If you would like to run the license server as a service on Windows, you can accomplish that as described here.Running on Linux and Mac
To run the license server on either Linux or Mac, you need to make sure that .NET 5 runtime or later is installed (read more here). Once it is installed, the license server can be started as follows:dotnet
before launching the server. Everything else is the same. Based on our tests, no sudo access is needed to run the license server on Linux.
Allowing ports (Windows only)
In order to allow other computers in the network to access the license server, you need to open up the desired port in the firewall. If you use the default firewall, it can be opened as follows:- Run
wf.msc
- Right click on Inbound Rules and then click on Add Rule
- Ryle type should be Port
- Specific local ports should be checked, and the textbox at the right of it should be set to 5000 (or any other port of your choosing).
- Click next through the entire wizzard and that should be it.
Connect to the server
Depending on which of our client SDKs you use, there will be a different way to provide the URL of the license server. For example, if you use the .NET SDK, every API method (such as Key.Activate) will have an extra parameterLicenseServerUrl
, which can be used to provide the URL of the license server.
Additional features
There are two versions of the license server,v1.*
and v2.*
. If you only need the request forwarding feature, v.1.*
version will suffice. If you want to use the extra features listed below, you can use v2.*
version instead.
Enable caching of licenses
Since v2.0 there is a way to cache responses toKey.Activate
, which helps to reduce the number of requests sent to Cryptolens. This is useful especially if your clients would have temporary internet connectivity issues. To enable license caching, you need to specify how long the license server should store each license. Note: if your application uses the signatureExpirationInterval
parameter in HasValidSignature
, the lifetime of the cache on the license server needs to be either equal to signatureExpirationInterval
or less. Otherwise, your client application will throw an error.
As an example, to launch the server that caches licenses for 10 days, it can be started as follows:
Customers who are permanently offline
The default behaviour of the server is to always attempt to get the latest copy of the license. However, if you know that the license server will not have access to the internet, it is better to enable the offline mode so that the license server always reads from cache. To enable offline mode, you can launch the server as follows (or use this configuration string):.skm
extension) is in the Downloads folder, it can be loaded as follows (or use this configuration string):
- Visit https://app.cryptolens.io/extensions/licenseserver and copy the “License server configuration” and “RSA Public Key”.
- When verifying the signature inside your application, please use the RSA Public Key on this page instead of the one you would normally use when your application can access our API. This key will only work with the license server that uses the configuration above.
- In the license server project, paste the value of “license server configuration” to
ConfigurationFromCryptolens
variable inProgram.cs
. In newer versions, you can choose to place the configuration string in an environment variable (cryptolens_configurationstring
) or by supplying it as a command line argument (-config). - Compile the license server in release mode.
- In the release folder, create a new folder called “licensefiles”.
- Visit the product page and click on the yellow button next to the license key that belongs to your client (to manage all activations). Now, click on “Download activation file” and put this file into the “licensefiles” folder created earlier.
- You can now send the license server (in the release folder, including all the files and folders) to your client.
Note (for .NET users) For the time being,
Key.Activate
needs to be called the same way as the in the Unity example: https://help.cryptolens.io/getting-started/unityNote If the local license server is enabled, floating license status will not be synchronized with Cryptolens, even if online mode is enabled. Moreover, GetKey request will return the information stored on the local license server and sign it using the local license server’s private key. This means that if you have enabled floating licensing offline, you need to use public key that was shown on the configuration page for both
Activate
and GetKey
requests.Floating=true
, similar to the way it would have been done when calling Cryptolens’ Web API:
Note: The license file in the
licensefiles
folder needs to have the data objects that will be incremented or decremented. Otherwise, the license server will throw an error.Loading settings from a config file
Note In newer versions of the license server, we recommend to create a configuration string as described in the beginning of this page.
config.json
in the same folder as the server. The structure of the configuration file is shown below:
ActivationFiles
can either reference a specific file or a folder. If it references a folder, all files with the .skm
extension will be loaded.
Running the license server as a service
The license server can run as a Windows service in the background. This can be accomplished as follows (using sc). Note, these commands need to be ran as an Administrator:If you have compiled the server yourself
- Copy the configuration string that you obtained above into
ConfigurationFromCryptolens
variable and build the License Server yourself.
If you are using the pre-built binaries
- Create an environment variable
cryptolens_configurationstring
with the configuration string from above. - Supply the configuration string (from above) as a command line argument when registering LicenseServer.exe as a service, as follows:
To obtain information about server status, e.g. the IP it is listening or if any errors have occurred, you can use the Windows Event log.
Alternative ways to configure the server
Using environment variables
It is also possible to configure the license server using environment variables. For now, the license server will only read the environment variables in two cases:- If the
ConfigurationFromCryptolens
in Program.cs is not null or empty. - If license server runs as a service (Windows).
ConfigurationFromCryptolens
to any string value and then rely on the environment variables. Alternatively, you can create a configuration string at https://app.cryptolens.io/extensions/licenseserver and then set “path to config file” to USE_ENVIRONMENT_VARIABLES
.
Cryptolens uses the following environment variables:
Name | Description |
---|---|
cryptolens_offlinemode | Specifies if the license server should contact the central server (if set to false) or rely on the cached version if such exists (if set to true). When set to true, the license server will at first try the cache before attempting to contact the license server. |
cryptolens_port | The port to use. |
cryptolens_activationfilefolder | The path to the folder with activation files. Please set it to an absolute path when running the license server as a service. |
cryptolens_cachelength | The amount of days until a new license file should be obtained. |
cryptolens_pathtoconfigfile | The path to the configuration file. This can be useful if you anticipate that your clients might need to change certain properties more often, and then it may be easier to change the file rather than restarting the machine (which is often required for the environment variables to take effect). For now, you can set the port and the folder to the activation files. If you plan to run the server as a service, please set this to absolute path. |
cryptolens_cachefolder | Path to the cache folder. If you plan to run the server as a service, please set this to absolute path. |
cryptolens_configurationstring | An optional parameter that you can use to provide the configuration string that would normally need to be added in the code. The license server will always check for this environment variable at start and it will have priority over command line arguments. |
Note: when running the license server as a service, all paths to files and folders need to be absolute.