It is recommended to store your keys in hardware wallets. It's one of the safest ways of creating signatures without exposing sensitive data. This guide will show you how to connect your hardware wallet in the CLI. It uses the PKCS#11 standard for the communication.
We tested this configuration with a Ledger Nano S Plus. A different hardware wallet may require additional steps.
Install OpenSC
OpenSC is a driver to connect with smart cards by using the PKCS#11 standard.
Go to https://github.com/OpenSC/OpenSC/releases/latest to download the latest release and install the package.
After the installation, you should see the library located at /Library/OpenSC/lib/opensc-pkcs11.so in the case of MacOS/Linux, or at C:\Program Files\OpenSC Project\OpenSC\pkcs11\opensc-pkcs11.dll in the case of Windows.
If you have troubles with the installation, please follow the quick start instructions documented in the official repo https://github.com/OpenSC/OpenSC/.
Configuration in EBSI CLI
If you use Windows, go to the folder of the EBSI CLI tool and set the library in the .env file:
OPEN_SC_LIBRARY="C:\\Program Files\\OpenSC Project\\OpenSC\\pkcs11\\opensc-pkcs11.dll"
For MacOS or Linux, it is not necessary since the default value is "/usr/local/lib/opensc-pkcs11.so".
Install and configure OpenPGP app
Install the Ledger Live app (https://www.ledger.com/ledger-live) and update the firmware of the device to the latest version, or at least version 1.1.2 (Ledger Nano S plus) or 2.2.4 (Ledger Nano X). This step will probably require several updates of the firmware until it gets the latest one.
Go to Settings > Experimental features, and enable the developer mode.
Now go to My Ledger, search and install the "OpenPGP app". Its version should be >=2.3.0. Otherwise check again for updates in the firmware of Ledger.
Open the OpenPGP app in your Ledger device. Go to Settings > Key template. Then set Key to Signature and Type to SECP 256R1. Finally, click on Set Template.
Your hardware wallet is ready to be used in the EBSI CLI tool.
By default, the CLI will ask for your PIN code before each command, but it won't require you to physically approve any operation on your Ledger.
In order to change that, open the OpenPGP Ledger app, go to Settings > UIF Mode and set UIF for Authentication to ON.
After this change, the OpenPGP will ask you to physically confirm the operation — e.g. before signing a JWT.
How to use the hardware wallet in EBSI CLI
Run hardwarewallet info to see the details of your device:
==> hardwarewallet info
{
"slot": 0,
"description": "Ledger Nano S Plus 0",
"serial": "2c97200e4c5e",
"password": {
"min": 6,
"max": 12
},
"isHardware": true,
"isRemovable": true,
"isInitialized": true
}
Now, generate a new key with the generatekey command. It will require you to enter the admin pin, which by default is 12345678:
==> hardwarewallet generatekey
Enter admin pin:
Key pair generated successfully!
Get the public key already generated:
==> hardwarewallet publickey
{
"kty": "EC",
"crv": "P-256",
"x": "FvfSizOfrGkq-xti3FidtNLuduqmHGyoWWcm1hRfhhY",
"y": "o7rRs9f9zUWBorH2CHDh-M7HHhJt1ua2207Jqfy6kHg"
}
You have generated an ES256 key pair in your the device. You won't need to generate it again the next time you open the CLI.
Connect the wallet to the user
When you load the keys of your user in the CLI, use the word hardwarewallet in the place where you normally enter the private key. Also, use this only with the ES256 algorithm:
==> using user ES256 did1 hardwarewallet
Update your DID document
Remember to update your DID document with this new ES256 key. If you already have an ES256 key in your DID document, follow these instructions to add another one.
Load your user and keys as usual:
==> using user ES256K did1 PRIVATE_KEY_ES256K
==> using user ES256 did1 PRIVATE_KEY_ES256
Save the new public key in a variable:
pubkey: hardwarewallet publickey
{
"kty": "EC",
"crv": "P-256",
"x": "FvfSizOfrGkq-xti3FidtNLuduqmHGyoWWcm1hRfhhY",
"y": "o7rRs9f9zUWBorH2CHDh-M7HHhJt1ua2207Jqfy6kHg"
}
Value saved in 'pubkey':
{
"kty": "EC",
"crv": "P-256",
"x": "FvfSizOfrGkq-xti3FidtNLuduqmHGyoWWcm1hRfhhY",
"y": "o7rRs9f9zUWBorH2CHDh-M7HHhJt1ua2207Jqfy6kHg"
}
Compute the corresponding thumbprint and save it in a variable:
vMethodId: compute thumbprint pubkey
Request an access token and update the DID document by using this key. During this process, you will be required to enter the PIN of the hardware wallet as "user" to continue, which by default is 123456.
# Request access token
authDidWrite: authorisation auth didr_write_presentation ES256
using token authDidWrite.access_token
# Add the new key
did addVerificationMethod user.did pubkey vMethodId
# Add the relationships
did addVerificationRelationship user.did authentication vMethodId
did addVerificationRelationship user.did assertionMethod vMethodId
Check if the DID document was correctly updated:
did get /identifiers/ user.did
Now, load your user again using the key from the hardware wallet:
using user null
using user ES256K did1 PRIVATE_KEY_ES256K
using user ES256 did1 hardwarewallet
You have connected your user with the hardware wallet and updated the corresponding DID document. You can now sign credentials as usual.
Update PIN
By default, the OpenPGP app uses the PINs 123456 and 12345678 for user and admin accounts respectively. To update them, use the setpin function.
For example, to update the user pin:
hardwarewallet setpin user
Enter current pin for user: # set 123456
Enter new pin: # define new pin
New pin configured!