.. hsm2-option-audit-guide.rst

.. _hsm2-option-audit-guide-label:

=========================
Set Command Audit Option
=========================

A YubiHSM 2 device maintains a list of recently executed commands in a portion of non-volatile memory known as the Log
Store with space for 62 entries. By default, logging is disabled but can be turned on for:

* All commands using the option ``force-audit``
* Specific commands using the option ``command-audit``

The syntax for ``command-audit`` value is ``C1 V1, C2 V2, ..., Cn Vn`` where ``Ci`` is the Command Code and ``Vi`` is the
option value expressed in HEX. The command codes can be found in :ref:`hsm2-cmd-reference-label` in the Protocol
Details section of every command.

The option value can be one of three alternatives:

0x00: Command log disabled

0x01: Command log enabled

0x02: Command log permanently enabled (only possible to turn off through factory reset)


Retrieve Option Status
=======================

To check the value of the ``command-audit`` option, use the ``Get Option`` command as follows:

.. code-block:: bash

   $ yubihsm-shell -a get-option --opt-name command-audit
   Using default connector URL: http://localhost:12345
   Session keepalive set up to run every 15 seconds
   Created session 0
   Option value is: 0100030004000500060007000900080040004100420043004400450046004700550056004800490057004a004b004c004d0067004e004f0050005100520053005400580059005a005b005c005d005e005f006000610062006300640065006600680069006a006b006c000a006d006e006f0070007100720073007400750076007700


Taking the first four characters of the output ``0100``, it means that logging for the command with the command code
``0x01`` (:ref:`hsm2-cmd-echo-label`) is disabled. The next four characters ``0300`` means that logging for the command
with command code ``0x03`` (:ref:`hsm2-cmd-open-session-asymmetric-label`) is disabled. And so on.

Set Option Status
=======================

When setting the ``command-audit`` option, only the effected commands need to be specified. For example, to enable
logging for the commands Sign HMAC (command code 0x53 :ref:`hsm2-cmd-sign-hmac-label`) and Verify HMAC (command code
0x5c :ref:`hsm2-cmd-erify-hmac-label`), the command would be:

.. code-block:: bash

   $ yubihsm-shell -a put-option --opt-name command-audit --opt-value 53015c01

Retrieving the option value again would give the output:

0100030004000500060007000900080040004100420043004400450046004700550056004800490057004a004b004c004d0067004e004f0050005100
5200\ |5301|\ 5400580059005a005b00\ |5c01|\ 5d005e005f006000610062006300640065006600680069006a006b006c000a006d006e006f007000
7100720073007400750076007700

Note the parts in bold text, indicating that logging for commands Sign HMAC and Verify HMAC are now enabled.