# 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.
{% hint style="danger" %}
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.
{% endhint %}
### Activate a hardware-key-requiring license
The following steps are required to activate a hardware-key-requiring license in the floating server:
{% stepper %}
{% step %}
### Create a Hardware-Key-Requiring License
Follow [**Hardware Key Licensing**](/license-entitlements/license-activation-types/hardware-key-licensing.md) to create a license that requires a hardware key.
{% endstep %}
{% step %}
### Start the Floating Server
Launch the Floating Server and navigate to the configuration page.
{% endstep %}
{% step %}
### 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.
{% endstep %}
{% step %}
### Plug in the Hardware Key
Ensure that a hardware key, which has been provisioned using the LicenseSpring platform, is plugged into the server.
{% endstep %}
{% step %}
### 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.
{% endstep %}
{% step %}
### 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.
{% endstep %}
{% step %}
### 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.
{% endstep %}
{% step %}
### 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.
{% endstep %}
{% step %}
### 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.
{% endstep %}
{% endstepper %}
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"
```
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 '{}'
```
#### 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}'
```
#### 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}'
```
#### 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"
}'
```
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"
}'
```
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}'
```
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:
```curl
lsof /dev/
```
Example:
```curl
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
```
* Use `fuser`: The `fuser` command shows which processes are accessing a specific file or device:
```curl
fuser /dev/
```
#### 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
```
* Sysinternals Tools: The [**Sysinternals Process Explorer**](https://docs.microsoft.com/en-us/sysinternals/downloads/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
```
* 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
```
These methods should help you identify which processes are interacting with your smart card reader.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.licensespring.com/floating-server/floating-server-v1/license-options/hardware-key.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.