.. hsm2-intro-libyubihsm-backend.rst

.. _hsm2-intro-libyubihsm-backend-label:

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``.


.. _hsm2-backend-http-label:

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 :ref:`hsm2-tools-connector-label` 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.

.. _hsm2-backend-usb-label:

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:

.. code-block:: sh

   $ yubihsm-shell --connector yhusb://

.. code-block:: sh

   $ yubihsm-manager --connector yhusb://

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

.. code-block:: sh

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

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

.. code-block:: c

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


.. _hsm2-backend-usb-permissions-label:

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:

.. code-block:: sh

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

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

.. code-block:: sh

    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:

.. code-block:: sh

    $ 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.