yubihsm-shell --connector yhusb://
YubiHSM Shell is a tool to directly interface with a YubiHSM 2 device.
For the most part it is a thin wrapper around libyubihsm exposing
most of its functions directly to the user.
YubiHSM Shell can be invoked in interactive mode and from the command
line. Special (national) characters are supported on MacOS and Linux
platforms. On Windows, they are supported in interactive mode and the
same support can be activated through the OpenSSL environment variable
OPENSSL_WIN32_UTF8 for interactive password entry in non-interactive
mode (i.e if password is not given on the command line). Such characters
will be encoded according to current locale settings on MacOS/Linux
(typically utf-8), and always as utf-8 on Windows.
To invoke YubiHSM Shell in interactive mode simply run yubihsm-shell
with no parameters. This mode supports tab-completion (not on Windows)
and "classic" terminal shortcuts (C-p, C-n, C-a, C-e, etc.)
In this mode, the default Connector URL is http://127.0.01:12345. If
a different URL is needed, it can be specified with the
--connector option. For example, to select direct USB run
yubihsm-shell --connector yhusb://
Help can be obtained by running
yubihsm> help
to get a list of available commands and their syntax, or by running
yubihsm> help COMMAND
to get help on a specific command.
Debug messages can be turned on by running
yubihsm> debug all
other levels of verbosity are available as well.
Each command has its own default input and output format. Possible
choices are PEM, base64, binary, hex, password and
default. Those can be changed by running
yubihsm> set informat base64
or
yubihsm> set outformat hex
Input and Output formats are a generic modifier and some values may not
make sense in some cases. The default setting can be restored by using
the default format.
It is possible to run yubihsm-shell as a non-interactive command-line
utility. To do so add the --action option with the desired command
to execute.
For example, to generate an RSA 2048 key with Label Signature_Key,
Object ID 10 and Capabilities sign-pss, run
$ yubihsm-shell -p password -a generate-asymmetric -A rsa2048 -i 10 -c sign-pss -l Signature_Key
to sign a file called message.dat using the previously generated
key, PSS with SHA256 as padding scheme and save the result to a file
called signature.dat run
$ yubihsm-shell -p password -a sign-pss -i 10 -A rsa-pss-sha256 --in message.dat --out signature.dat --outformat binary
it is then possible to extract the public key by using
yubihsm-shell -p password -a get-public-key -i 10 --out key.pem --outformat PEM
and verify the signature with OpenSSL by running
$ openssl dgst -sha256 -binary message.dat > digest.dat
openssl pkeyutl -verify -in digest.dat -sigfile signature.dat -pkeyopt rsa_padding_mode:pss -pubin -inkey key.pem -pkeyopt rsa_pss_saltlen:-1 -pkeyopt digest:sha256
A detailed list of possible actions and parameters is available in the
manpage or by running yubihsm-shell --help.