Libyubihsm Backend

Libyubihsm has two builtin communication backends:

HTTP Backend requires an HTTP connector to sit between the YubiHSM 2 and the USB connection on the host machine. Yubico provides the yubihsm-connector tool for this purpose, which can be run on the same machine as the YubiHSM 2 or on a different machine that has network access to the YubiHSM 2.
USB Backend allows direct communication with the YubiHSM 2 over USB without the need for an HTTP connector.

Both backends can be used with the same libyubihsm API, and the choice of backend is determined by the URL scheme used when initializing the connector. A default URL can be specified using the environment variable DEFAULT_CONNECTOR_URL.

HTTP Backend

When an http:// or https:// URL is provided to libyubihsm, the library loads its HTTP backend and uses libcurl to communicate with whatever is listening at that address. All commands and responses are exchanged as raw binary data over standard HTTP POST requests; however, since all communication with the YubiHSM 2 occur within the context of an encrypted session, all data going through the HTTP connection is already encrypted.

Yubico provides the YubiHSM 2 Connector to act as an HTTP connector for the YubiHSM 2. The connector listens for HTTP requests on a specified port and forwards them to the YubiHSM 2 over USB, and then sends the responses back to the client over HTTP. This allows applications using libyubihsm to communicate with the YubiHSM 2 over a network connection, which can be useful in scenarios where the application and the YubiHSM 2 are not on the same machine.

USB Backend

With a direct USB connection, your application communicates with the YubiHSM 2 directly over USB, without the connector service running at all. The USB backend is loaded directly by libyubihsm using the yhusb:// URL scheme.

Direct USB connection is suitable where the YubiHSM 2 is physically connected to the same machine as the application and there is no need for remote access.

How to Connect Using Direct USB

Use the yhusb:// URL scheme in place of the HTTP connector URL. For example:

$ yubihsm-shell --connector yhusb://

$ yubihsm-manager --connector yhusb://

To target a specific YubiHSM 2 device by its serial number use yhusb://serial=<SERIAL_NUMBER>. For example:

$ yubihsm-shell --connector yhusb://serial=12345678

When using libyubihsm directly in application code, pass the same URL to yh_init_connector(). For example:

yh_connector *connector;
yh_init_connector("yhusb://", &connector);

OS Permissions for USB Access

Regardless of which backend is used, the process accessing the YubiHSM 2 over USB must have permission to access the USB device on the host operating system. The recommended approach is to grant access to a dedicated group rather than running as root.

Linux — udev Rules

On Linux, USB device permissions are managed by udev. By default, raw USB device access is restricted to root. The best practice is to create a dedicated group and a udev rule that grants that group access to the YubiHSM 2.

Step 1: Create a dedicated group:

$ groupadd yubihsm
$ usermod -aG yubihsm <your-username>

Step 2: Create a udev rule file at /etc/udev/rules.d/70-yubihsm.rules:

SUBSYSTEM=="usb", ATTR{idVendor}=="1050", ATTR{idProduct}=="0030", MODE="0660", GROUP="yubihsm"

The vendor ID 1050 and product ID 0030 identify the YubiHSM 2.

Step 3: Reload udev rules and re-plug the device:

$ udevadm control --reload-rules
$ udevadm trigger

Note

Best practice: Use MODE="0660" (group read/write, no world access). Avoid MODE="0666", which would grant all users on the system raw access to the device.

When using the HTTP Connector, only the user account running the connector needs to be in the yubihsm group. The YubiHSM applications connect to the connector over HTTP and never touch the USB device directly.

MacOS

On macOS, USB HID-class devices are generally accessible to user-space applications without special configuration. If permission issues are encountered, ensure the process is running as a user with access to the USB subsystem.

Windows

On Windows, the YubiHSM 2 driver handles access control. When using the HTTP Connector, it is recommended to install and run yubihsm-connector as a Windows Service under a dedicated low-privilege service account. The connector installer handles the necessary driver configuration automatically.