# Hardware Key Usage

LicenseSpring allows users to bind licenses to a YubiKey hardware key dongle.

### Prerequisites

Make sure to set up a YubiKey on the LicenseSpring platform and the LicenseSpring Provisioning Application for Desktop. See [**Hardware Key Licensing**](broken://pages/b38de3cd7080d093f1a6657478185902a811d1cf) for instructions.

#### C++ Platform-specific Library Placement

Since **C++ SDK v7.37.0**, we provide both LicenseSpring SDK libs that do link, and that don't link to [**libykpiv**](https://developers.yubico.com/yubico-piv-tool/). All samples also have multiple configurations, with and without linking to `libykpiv`.

* **Linux & macOS**
  * Shared libraries are located in `bin/shared_HardwareKey`
  * Static libraries are located in `bin/static_HardwareKey`
  * Note: The existing `bin/shared` and `bin/static` folders remain unchanged and do not link to `libykpiv`.
* **Linux ARM (i.e. ARM without hf support), ppc64le**
  * SDK builds targeting arm and ppc64le architectures do not link tl `libykpiv` (no hardware key support).
* **MSVC (Windows)**
  * Dynamic libraries are located in `bin/dynamic_HardwareKey`
  * Static linking to `libykpiv` is **not supported**.
  * The existing `bin/dynamic` folder remains unchanged and does not link to `libykpiv`.
* **MinGW**
  * We currently don't support hardware

{% hint style="info" %}
The `libykpiv` library has an external dependency which should be installed on user machines:

• Linux uses the pcsc backend (via pcsclite) to manage the YubiKey,\
• macOS uses the macscard backend (Apple’s built‑in PC/SC layer, pcsclite daemon),\
• Windows (MSVC targets) uses the winscard backend (Microsoft’s WinSCard API).
{% endhint %}

#### Usage samples

{% tabs %}
{% tab title="C++" %}

```cpp
#include <LicenseSpring/Configuration.h>
#include <LicenseSpring/ExtendedOptions.h>

// ...

// the following function returns an std::vector of all plugged YubiKeys' serials.
auto serials = LicenseSpring::HardwareKeyOptions::ListAvailableKeys();
if (!serials.empty()) {
    HardwareKeyOptions hwKeyOptions;
    hwKeyOptions.setTargetSerial(serials[0]); // query the user for the correct serial
    hwKeyOptions.setPin("123456"); // query the user for the pin

    ExtendedOptions options;
    options.setHardwareKeyOptions(hwKeyOptions);
}
```

{% endtab %}

{% tab title="Java" %}

```java
IdentityProvider identityProvider = config.getIdentityProvider();
String key = identityProvider.getKey();
```

{% endtab %}

{% tab title="C#" %}

```csharp
// the following function returns a list of all plugged YubiKeys' serials.
List<string> serials = LicenseSpring.HardwareKeyOptions.ListAvailableKeys();
if (serials.Count != 0)
{
    // query the user for the correct serial
    string serialNumber = serials.First();
    // query the user for the correct pin
    string pin = "123456"; 
    
    LicenseSpring.HardwareKeyOptions hardwareKeyOptions = new LicenseSpring.HardwareKeyOptions(serialNumber, pin);
    LicenseSpring.Configuration configuration = new LicenseSpring.Configuration();
}
```

{% endtab %}
{% endtabs %}

Calling `ExtendedOptions::setHardwareKeyOptions` automatically sets the machine hardware ID to the serial of the Yubikey.

Afterwards, all calls to the License API require that YubiKey to be plugged in, and `License::localCheck` will throw an appropriate `LicenseSpring::HardwareKeyException` exception in case the YubiKey is not plugged in.


---

# 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/sdks/tutorials/advanced-usage/hardware-key-usage.md?ask=<question>
```

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.