Skip to main content
Version: development

Use Web3Signer with YubiHSM 2

Web3Signer can sign payloads using private keys stored in the YubiHSM 2 hardware security module. Web3Signer supports using the device as a secure key storage only.

Prerequisites

Install the YubiHSM 2 SDK on the Web3Signer machine.

Store private keys in YubiHSM 2

Store private keys in the device using the opaque-data algorithm in hex format. All private keys on the device must be accessible using the same authentication key ID and password.

The following steps show an example of storing a key in YubiHSM:

  1. Store a private key in YubiHSM with object-id=3 and new-password=password3, using the YubiHSM default credentials of authkey=1 and password=password:

    yubihsm-shell \
    --connector=yhusb:// \
    --authkey=1 \
    --password=password \
    --action=put-authentication-key \
    --new-password=password3 \
    --object-id=3 \
    --domains=1,2,3 \
    --delegated=exportable-under-wrap,export-wrapped,import-wrapped \
    --capabilities=get-opaque,put-opaque,delete-opaque,export-wrapped,get-pseudo-random,put-wrap-key,import-wrapped
  2. Put the opaque data using authkey=3 with the opaque object-ID=15:

    yubihsm-shell \
    --connector=yhusb:// \
    --authkey=3 \
    --password=password3 \
    --action=put-opaque \
    --object-id=15 \
    --label="bls_key_1" \
    --domains=1,2,3 \
    --algorithm=opaque-data \
    --capabilities=none \
    --informat=hex --in=5e8d5667ce78982a07242739ab03dc63c91e830c80a5b6adca777e3f216a405d
  3. Use authkey=1 to view the inserted data:

    yubihsm-shell \
    --connector=yhusb:// \
    --authkey=1 \
    --password=password \
    --action=get-opaque \
    --object-id=15 \
    --outformat=hex
  4. Identify the location of the yubihsm_pkcs11 dynamic library. For example, on Mac, it is installed at /usr/local/lib/pkcs11/yubihsm_pkcs11.dylib using the latest YubiHSM release.

    Note for Mac only

    Due to a bug in how the YubiHSM libraries are generated, copy the file to the parent directory (/usr/local/lib):

    sudo cp /usr/local/lib/pkcs11/yubihsm_pkcs11.dylib /usr/local/lib/

    Create a soft link in the directory from where Web3Signer is running:

    ln -s /usr/local/lib/libyubihsm_usb.2.dylib ./libyubihsm_usb.2.dylib
  5. Create a key configuration file for YubiHSM in the keys subdirectory.

    type: yubihsm
    connectorUrl: yhusb://
    authId: 3
    password: password3
    opaqueDataId: 15
    pkcs11ModulePath: /usr/local/lib/yubihsm_pkcs11.dylib
    additionalInitConfig: debug libdebug timeout=5
  6. Specify the key-store-path as the keys subdirectory when starting Web3Signer.

    The output displayed indicates one key has been loaded:

    2023-10-04 15:30:27.761+10:00 | pool-2-thread-1 | INFO  | SignerLoader | Converting signing metadata to Artifact Signer using parallel streams ...
    [P11 - INF 15:30:27.769485] yubihsm_pkcs11.c:266 (C_Initialize): Found 1 configured connector(s)
    [LIB - INF 15:30:27.769505] yubihsm.c:4426 (yh_init_connector): Loading usb backend
    [LIB - INF 15:30:27.770065] yubihsm_libusb.c:61 (backend_create): backend_create
    [LIB - INF 15:30:27.772352] yubihsm_usb.c:48 (backend_connect): backend_connect
    [LIB - INF 15:30:27.772364] lib_util.c:178 (parse_usb_url): USB url parsed with serial decimal 0.
    ...
    2023-10-04 15:30:28.176+10:00 | pool-2-thread-1 | INFO | DefaultArtifactSignerProvider | Total signers (keys) currently loaded in memory: 1

PKCS#11 driver

To communicate with the YubiHSM 2 device, Web3Signer uses the PKCS#11 driver to load the PKCS#11 module in the SDK.

Important

A limitation of the PKCS#11 driver is that it communicates with only one device by loading one instance of the PKCS#11 module. If using multiple YubiHSM 2 devices then you must have additional copies of the SDK installation.

Additionally, the loaded PKCS#11 module can open only one session when communicating with a YubiHSM 2 device. Because key configuration files are parsed in parallel, the same authentication key ID and password must be specified in the key configuration files for a given device.