Hardware Key

In the floating server, when the hardware key is plugged in and a license-requiring hardware key is added to the floating server, the server's hardware ID changes to the serial number of the hardware key. From then on, every other action in this server uses the new hardware ID, as long as the hardware key is connected to the server. Multiple licenses can be activated using the same hardware key.

To successfully run the floating server with the hardware dongle, make sure that no other process is using smart card readers, as this will result in an error in the floating server.

More details on how to detect those services can be found at the end of this page.

Activate a hardware-key-requiring license

The following steps are required to activate a hardware-key-requiring license in the floating server:

1

Create a Hardware-Key-Requiring License

Follow Hardware Key Licensing to create a license that requires a hardware key.

2

Start the Floating Server

Launch the Floating Server and navigate to the configuration page.

3

Select the Authentication Method

From the dropdown menu on the configuration page, select the method of license authentication:

• Key Auth

• User Auth

Ensure that the checkbox for hardware key licenses is selected when adding a license that requires a hardware key.

4

Plug in the Hardware Key

Ensure that a hardware key, which has been provisioned using the LicenseSpring platform, is plugged into the server.

5

Add the License

Add the product that requires the hardware key (e.g., "hwbased") to the Floating Server. The server will recognize that the hardware key is connected.

Hardware Key Box

6

Confirm License Activation

After adding the product, the license will be successfully activated on the Floating Server. The hardware ID of the server will now change to the serial number of the hardware key, as long as the hardware key remains connected.

7

Observe the Hardware ID Change

The hardware ID of the Floating Server will continue to use the hardware key’s serial number for all actions as long as the key is connected. If the hardware key is disconnected, the hardware ID will revert to its original value.

8

View Activation in LicenseSpring

In the LicenseSpring platform, the license activation will be visible, showing that the hardware key’s serial number is being used as the hardware ID.

The Hardware ID shown in the platform is the serial number of the hardware key.

9

Add Additional Licenses

Additional licenses, whether they require hardware keys or not, can also be added to the Floating Server. This includes both user-based and license-key authentication methods.

Once a hardware-key-based license is added to the server, any subsequent actions involving that license will first verify the hardware key's validity. The action will fail if the key is invalid (e.g., disconnected).

Invalid Hardware Key Handling

To address scenarios with missing or invalid hardware keys, we provide two solutions:

• Default Behavior: When a hardware key is missing or invalid, the server returns an error.

• Crash on Missing Hardware Key: If the crashIfNoHardwareKey flag is set to true during server setup, the server will crash when an invalid or missing hardware key is accessed.

This feature was introduced in version v1.6.0 and was implemented to accommodate specific use cases, such as managing hardware keys in high-availability setups.

Usage examples

Using the API to log in as an admin, add consumptions, feature consumptions, register a user, and register a user to a feature of a license that requires hardware key verification. This example takes advantage of authentication mode to enforce role-based access control. If you are using the server without authentication mode, you can omit the authorization headers.

Use user/pass to login

curl -u 'user1':'pass1' http://localhost:8080/auth -H "Accept: application/json"

Response:

{"message":"Login successful","token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MjY4NTU4OTMsImlhdCI6MTcyNjc2OTQ5Mywicm9sZSI6ImFkbWluIiwidXNlcm5hbWUiOiJ1c2VyMSJ9.fhJefnu7X7iECS3Brf36PVdqHRLeZIuwONTfkHdJnjA"}

Add the product

using the "isHWKeyReq" parameter

curl -X GET "http://localhost:8080/api/v4/addProduct?product=hwbased&licenseKey=WTUS-5HHH-V8YP-WUHW&isHWKeyReq=yes" -H "Authorization: Bearer {token_here}" -H "Accept: application/json" -H "Content-Type: application/json" -d '{}'

Add consumptions

curl -X POST "http://localhost:8080/api/v4/add_consumption" -H "Authorization: Bearer {token_here}" -H "Accept: application/json" -H "Content-Type: application/json" -d '{"product":"hwbased", "consumptions": 2}'

Add feature consumptions

curl -X POST "http://localhost:8080/api/v4/add_feature_consumption" -H "Authorization: Bearer {token_here}" -H "Accept: application/json" -H "Content-Type: application/json" -d '{"product":"hwbased", "feature": "consFeature2", "consumptions": 2}'

Register User

curl -X POST "http://localhost:8080/api/v4/register" -H "Authorization: Bearer {token_here}" -H "Accept: application/json" -H "Content-Type: application/json" -d '{
  "product": "hwbased",
  "user": "user1",
  "os_hostname": "",
  "ip_local": "0.1.1.1",
  "user_info": "",
  "registered_at": "2024-08-26T12:21:59.776731-07:00",
  "borrowed_until": "0001-01-01T00:00:00Z"
}'

If no errors occur, the license object will be returned.

Register User to Feature

curl -X POST "http://localhost:8080/api/v4/featureRegister" -H "Authorization: Bearer {token_here}" -H "Accept: application/json" -H "Content-Type: application/json" -d '{
  "product": "hwbased", "feature": "consFeature2",
  "user": "user2",
  "os_hostname": "",
  "ip_local": "0.1.1.1",
  "user_info": "",
  "registered_at": "2024-08-26T12:21:59.776731-07:00",
  "borrowed_until": "0001-01-01T00:00:00Z"
}'

Response: {"product":"hwbased","feature":"consFeature2","user":"user2","os_hostname":"","ip_local":"0.1.1.1","user_info":"","registered_at":"2024-09-19T12:39:16.356495803-07:00","borrowed_until":"0001-01-01T00:00:00Z"}

Unplug the hardware key or restart the server, then add consumption

curl -X POST "http://localhost:8080/api/v4/add_feature_consumption" -H "Authorization: Bearer {token_here}" -H "Accept: application/json" -H "Content-Type: application/json" -d '{"product":"hwbased", "feature": "consFeature2", "consumptions": 2}'

Response: {"code":"hardware_key_not_accessible","message":"No available valid hardware key to perform the action: adding feature consumption","status":400}

Detect processes using smart card reader

To find which processes are using a smart card reader on your machine, you can use the following methods depending on your operating system:

On Linux

• Use lsof: The lsof command lists open files and the processes that have opened them. Since smart card readers are typically handled as devices, you can find processes interacting with them.

  1. First, find the device file for your smart card reader. This is usually in /dev and might be something like /dev/pcsc, /dev/ttyUSB0, or similar.

  2. Run the following command to check which processes are accessing the device:

  lsof /dev/<device-name>

  Example:

  lsof /dev/ttyUSB0

• Check PC/SC Daemon: If you’re using a PC/SC compliant smart card reader, the pcscd service manages the communication. You can check if pcscd is running, and find its process ID:

ps aux | grep pcscd

• Use fuser: The fuser command shows which processes are accessing a specific file or device:

fuser /dev/<device-name>

On Windows

• Use Task Manager: Open the Task Manager (Ctrl + Shift + Esc), and look for applications or services related to smart card access, like "Smart Card Service" or "SCardSvr". These may interact with the smart card reader.

• Use sc query: You can also use the command prompt to query the status of the Smart Card service:

sc query SCardSvr

• Sysinternals Tools: The Sysinternals Process Explorer allows you to see what files, directories, and handles processes are using. Open Process Explorer and search for processes accessing smart card-related files or drivers.

On macOS

• Use lsof: Similar to Linux, you can use lsof to find processes using the smart card reader:

lsof | grep smartcard

• Check the Smart Card Daemon: On macOS, the pcsctest command can interact with the smart card reader and might provide information about active processes:

pcsctest

These methods should help you identify which processes are interacting with your smart card reader.