YubiHSM & Identity Server#

This document describes how to use the Identity Server with the YubiHSM v. 2.

YubiHSM is already setup in server1.local machine and it can be connected remotely. So if you’re in VPN/office network, you can continue with the following steps.

YubiHSM Connection Check#

Can you reach http://server1.local:12345/connector/status and see the following? Then you are good to go!

If you’re not able to reach this URL, then:

• Make sure you are on VPN
• Contact build & QA team

Access via PKCS#11 Module#

1. Download release 2025.06b from here: https://developers.yubico.com/YubiHSM2/Releases/

2. Check if you have file /usr/local/lib/yubihsm_pkcs11.dylib

3. Now you can connect to HSM using pkcs#11 module:

pkcs11-tool --module /usr/local/lib/yubihsm_pkcs11.dylib --login --pin hsm_pin -O

Start idsvr#

1. Create a file /etc/yubihsm_pkcs11.conf, and write following line to it:

connector = http://server1.local:12345

2. Set env variable in your shell before starting Curity:

export YUBIHSM_PKCS11_CONF=/etc/yubihsm_pkcs11.conf

3. Start Curity in debug mode and also with HSM password:

debug/run --debug-hsm -i hsm_pin

Access via YubiHSM Shell#

After downloading YubiHSM SDK you can connect to the HSM server using the shell it comes with it.

1. First you need to create the file /etc/yubihsm_pkcs11.conf, if not already created, and add the following line:

connector = http://server1.local:12345

2. Next in new prompt create the env variable YUBIHSM_PKCS11_CONF, then to gain shell access to the YubiHSM 2, launch the YubiHSM Shell program:

% export YUBIHSM_PKCS11_CONF=/etc/yubihsm_pkcs11.conf
% yubihsm-shell --connector http://server1.local:12345:12345

3. To connect to the YubiHSM 2, at the yubihsm command line, type connect. A message saying that you have a successful connection is displayed.

yubihsm> connect

4. To open a session with the YubiHSM 2, type session open 1 (where 1 is the ID of the default authentication key pre-installed on the device).

You now have an administrative connection to the YubiHSM 2 and you can list the objects available by typing list objects 0 and pressing Enter. Your results should be similar to the following:

yubihsm>session open 0 <<password>>
Created session 0
yubihsm>list objects 0
Found 3 object(s)
id: 0x0002, type: wrap-key, sequence: 0
id: 0x0003, type: authentication-key, sequence: 0
id: 0x0004, type: authentication-key, sequence: 0

Generating an Asymmetric Key Object for Signing#

Specifically, we will ask the device to generate an Asymmetric Key with ID 100 and a given set of Domains and Capabilities. We will also specify the kind of Asymmetric Key that we would like to generate, an EC key using the NIST P-256 curve in this case.

The command is:

yubihsm> generate asymmetric 1 100 label_ecdsa_sign 1,2,3 sign-ecdsa ecp256

Where:

• generate is YubiHSM shell command.
• asymmetric is the key type to be generated.
• 1 is the session ID.
• 100 is the key ID.
• label_ecdsa_sign is the label for the new key object.
• 1,2,3 are the domains where the new key will be accessible.
• sign-ecdsa allows this key to be used to perform ECDSA signature.
• ecp256 specifies NIST P-256 curve for the key.

On success, we will see the message:

Generated Asymmetric key 0x0064