.. hsm2-tools-shell.rst

.. _hsm2-tools-shell-label:

YubiHSM 2 Shell
================

The `yubihsm-shell tool <https://developers.yubico.com/yubihsm-shell/yubihsm-shell.html>`_ is the administrative and testing tool you can use to interact with and configure the YubiHSM 2 device. All the commands supported by YubiHSM 2 :ref:`hsm2-cmd-reference-label` can be issued to YubiHSM 2 using YubiHSM 2 Shell.

The Shell can be invoked in two different ways: interactively, or as a command line tool useful for scripting.

Additional information on the various commands can be obtained with the ``help`` command in interactive mode or by referring to the ``--help`` argument for the command line mode.

Examples of commands can also be found in the :ref:`hsm2-cmd-reference-label` reference.

YubiHSM Shell Command Syntax
-------------------------------

Commands and subcommands require specific arguments to work. The Shell will return an error message if the command syntax is incorrect, pointing at the first invalid argument.

Arguments have different types. In interactive mode pre-defined values for command types can be tab-completed (Tab Completion does not work on Windows). Command arguments are explained in the table below.

.. table::

  +-----+-----------------+----------------------------------------------------+
  | Arg | Type            | Description                                        |
  +=====+=================+====================================================+
  | A   | Algorithm       | An algorithm in string form (ex: ecp256)           |
  +-----+-----------------+----------------------------------------------------+
  | B   | Byte            | A generic (hex or dec) 8-bit unsigned number       |
  +-----+-----------------+----------------------------------------------------+
  | C   | Capabilities    || A list of Capabilities in either form:            |
  |     |                 || hex (ex: 0xffffffffffffffff) or                   |
  |     |                 || string (ex: sign-pkcs,sign-pss, get-log-entries)  |
  +-----+-----------------+----------------------------------------------------+
  | D   | Domains         || A list of Domains, either in hex (ex: 0xffff) or  |
  |     |                 || string form (ex: 3,5,14)                          |
  +-----+-----------------+----------------------------------------------------+
  | I   | Format          | A format specifier in string form (ex: base64)     |
  +-----+-----------------+----------------------------------------------------+
  | I   | Input data      | Input data, generally defaults to standard input   |
  +-----+-----------------+----------------------------------------------------+
  | U   | Number          | A generic (hex or dec) unsigned number             |
  +-----+-----------------+----------------------------------------------------+
  | O   | Option          || A device-global option in string form             |
  |     |                 || (ex: force-audit)                                 |
  +-----+-----------------+----------------------------------------------------+
  | F   | Output filename || Output file name, generally defaults to standard  |
  |     |                 || output                                            |
  +-----+-----------------+----------------------------------------------------+
  | E   | Session         | The ID of an already-established Session           |
  +-----+-----------------+----------------------------------------------------+
  | S   | String          || A generic string (use quotes for strings          |
  |     |                 || including white spaces)                           |
  +-----+-----------------+----------------------------------------------------+
  | T   | Type            | An Object Type in string form (ex: Asymmetric)     |
  +-----+-----------------+----------------------------------------------------+
  | W   | Word            | A generic (hex or dec) 16-bit unsigned number      |
  +-----+-----------------+----------------------------------------------------+


Different commands have different default formats. These can be listed by invoking ``help`` on a specific command. For example, the ``help sign`` will display the following message:


.. code-block:: bash

   pss           Sign data using RSASSA-PSS (default input format: binary)
                 e:session,w:key_id,a:algorithm,i:data=-,F:out=-


As can be seen, the input format is binary. Additionally, arguments to a command that have ``=-`` after their type and name (like ``i:data`` and ``F:out`` in the example above), use the standard input or standard output by default for reading data.

Different levels of debug output can be enabled by using the ``-v`` flag in command line mode, or by issuing the ``debug LEVEL`` command in interactive mode, where LEVEL is one of ``all``, ``crypto``, ``error``, ``info``, ``intermediate``, ``none``, or ``raw``.

See :ref:`hsm2-cmd-reference-label` for yubihsm-shell commands interactive and command line mode examples.