Skip to main content

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:

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 are an example of storing a key in YubiHSM:

  1. To store a private key in YubiHSM with ID=3 and 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 \
   --capabilities=get-opaque,put-opaque,delete-opaque,export-wrapped,get-pseudo-random,put-wrap-key,import-wrapped \
   --delegated=exportable-under-wrap,export-wrapped,import-wrapped```
  1. 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
  1. Use authkey 1 to view the inserted data:
yubihsm-shell --connector=yhusb:// --authkey=1 --password=password --action=get-opaque --object-id=15 --outformat=hex
  1. 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

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

  2. Specify the key-store-path as the keys subdirectory when starting Web3Signer.

    The output displayed indicates 1 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 2device, 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.