The Connector, yubihsm-connector, performs the communication between
the YubiHSM 2 and applications that use it.
The Connector must have permissions to access the USB device, and different
operating systems behave differently in this regard.
The easiest way to get started is to run the Connector with Administrator privileges
(e.g. with sudo), but the safest way to run the Connector is to use your
operating system’s configuration to only give it the privileges necessary to
access the YubiHSM 2 USB device.
The Connector is not a trusted component. Sessions are established
cryptographically between the application and the YubiHSM 2 using a
symmetric mutual authentication scheme that is both encrypted and
authenticated.
The Connector is not required to run on the same host as the
applications which access it. In that case the Connector should be
configured to be listening on a different address and port rather than
the default localhost:12345, making sure that the client has access.
The protocol is tunneled over HTTP, but it is not a RESTful API or similar.
It is however possible to get information regarding the Connector by issuing a
GET request on the /connector/status URI.
HTTPS Connections
As mentioned earlier, the Connector is not meant to be a trusted
component. For this reason it defaults to HTTP connections. It is
possible to use HTTPS, however this requires providing a key and a
certificate to the Connector.
Another option is to use a reverse proxy such as nginx before the
Connector and have that handle TLS.
Configuration
Sample configuration for the Connector; yubihsm-connector-config.yaml
# Certificate (X.509)
cert: ""
# Certificate key
key: ""
# Listening address. Defaults to "localhost:12345".
listen: localhost:12345
# Device serial in case of multiple devices
serial: ""
# Log to syslog/eventlog. Defaults to "false".
syslog: false
# Use to enable host header filtering. Default to "false".
# Use this if there is an absolute need to use a web browser on the host where the YubiHSM 2 is installed to connect to untrusted web sites on the Internet.
enable-host-whitelist: false
# Default list for the host header filter
host-whitelist: localhost,localhost.,127.0.0.1,[::1]
Sample udev rule to be placed into /etc/udev/rules.d/:
# This udev file should be used with udev 188 and newer
ACTION!="add|change", GOTO="yubihsm2_connector_end"
# Yubico YubiHSM 2
# The OWNER attribute here has to match the uid of the process running the Connector
SUBSYSTEM=="usb", ATTRS{idVendor}=="1050", ATTRS{idProduct}=="0030", OWNER="yubihsm-connector"
LABEL="yubihsm2_connector_end"