YubiHSM setup for Web3Signer

yubihsm.md

YubiHSM

• Install YubiHSM tools https://developers.yubico.com/YubiHSM2/Releases/
• Set up a new key (id=3, password=password3) for opaque data management, using the YubiHSM default credentials (authkey=1, 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

The output would look like:

Created session 0
Stored Authentication key 0x0003

• Put opaque data using auth key 3 with the opaque object id is 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

The output should look like:

Session keepalive set up to run every 15 seconds
Created session 0
Stored 32 bytes to Opaque object 0x000f

• Use authkey 1 to view the inserted data

yubihsm-shell --connector=yhusb:// --authkey=1 --password=password --action=get-opaque --object-id=15 --outformat=hex

The output would look like:

Session keepalive set up to run every 15 seconds
Created session 0
5e8d5667ce78982a07242739ab03dc63c91e830c80a5b6adca777e3f216a405d

• Identify the location of yubihsm_pkcs11 dynamic library. For example, on Mac, it is installed at /usr/local/lib/pkcs11/yubihsm_pkcs11.dylib using the latest YubiHSM release. Due to a bug in how the yubihsm libraries are generated, this file needs to be copied in its parent folder i.e. /usr/local/lib

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

• In addition, a soft link for libyubihsm_usb.2.dylib needs to be created in current directory (from where web3signer is running) i.e.

ln -s /usr/local/lib/libyubihsm_usb.2.dylib ./libyubihsm_usb.2.dylib

The above changes may not be required on Linux.

• Create yubihsm configuration file as described at https://docs.web3signer.consensys.net/reference/key-config-file-params#yubihsm-2 under keys sub-folder. Take a note of pkcs11 module path. We are using the copied file path i.e. /usr/local/lib to bypass Mac issue.

mkdir ./keys

cat <<EOF > ./keys/yubihsm_key1.yaml
type: yubihsm  
connectorUrl: yhusb://  
authId: 3  
password: password3  
opaqueDataId: 15  
pkcs11ModulePath: /usr/local/lib/yubihsm_pkcs11.dylib
additionalInitConfig: debug libdebug timeout=5

EOF

• Web3Siger config file config.yaml

cat <<EOF > ./config.yaml
http-listen-host: "0.0.0.0"  
http-listen-port: 9000  
http-host-allowlist: "*"  
  
metrics-enabled: true  
metrics-host: "0.0.0.0"  
metrics-port: 9001  
metrics-host-allowlist: "*"

key-store-path: "./keys/"
  
# eth2 subcommand options  
eth2.network: "minimal"  

eth2.slashing-protection-enabled: false  

EOF

./web3signer --config-file config.yaml eth2

The output should look like:

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