Hardware Key

22min
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 the instructions on our Hardware Key Licensing﻿ page to create a new license that requires hardware keys.
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.
﻿
Configuration page of the floating server
﻿
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.
﻿
The license is successfully added.
﻿
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.
Multiple licenses added using the same hardware key.
﻿
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
curl -u 'user1':'pass1' http://localhost:8080/auth -H "Accept: application/json"
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
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 '{}'
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
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}'
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
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}'
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
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"
}'
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
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"
}'
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
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}'
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.
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.
Run the following command to check which processes are accessing the device:
Curl
lsof /dev/<device-name>
lsof /dev/<device-name>
﻿
Example:
Curl
lsof /dev/ttyUSB0
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:
Curl
ps aux | grep pcscd
ps aux | grep pcscd
﻿
Use fuser:
The fuser command shows which processes are accessing a specific file or device:
Curl
fuser /dev/<device-name>
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:
Curl
sc query SCardSvr
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:
Curl
lsof | grep smartcard
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:
Curl
pcsctest
pcsctest
﻿
These methods should help you identify which processes are interacting with your smart card reader.
Updated 20 Nov 2024
Did this page help you?
Air-Gapped
Which to Use?