.. hsm2-logging.rst

.. _hsm2-concepts-logs-label:

=================
Logging and Logs
=================

Logs
=====

A YubiHSM 2 device maintains a list of recently executed commands in a portion of non-volatile memory known as the Log Store. This allows logging commands across different power cycles. Specific commands are used to extract logs from the device. Since the Log Store uses non-volatile memory, it can only store up to ``62`` different entries. When the Log Store is full, it is used as a circular buffer, meaning that the least recently used entry is overwritten.

It is possible to set the device in Force Audit mode. When this is done entries from the Log Store must be retrieved or commands that cannot be logged will fail. Together with individual commands, power-on and reboot events are also logged.

The establishment of a session is logged like any other operation; however those commands are always allowed, independent of the current status of the Log Store. This is so that it is always possible to retrieve logs and free up the Log Store, even when the device is in Force Audit mode and the Log Store is full. However, the number of unlogged authentication and power-up events is stored in a counter that is retrieved as part of the log retrieval.

Entries in the Log Store are organized to form a chain of hashes. This enables auditors to verify that a given set of entries has not been tampered with after extraction, and that all entries are present. More details on the format of log entries can be found in the protocol description document for :ref:`hsm2-cmd-get-log-entries-label`.


.. _hsm2-concepts-options-label:

Options
============

Options are device-global settings. The following Options are defined:

.. table::

   +-------------------+--------------+
   | Option Name       |  Hex Value   |
   +===================+==============+
   | force-audit       | 0x01         |
   +-------------------+--------------+
   | command-audit     | 0x03         |
   +-------------------+--------------+

The data payload is Option-specific.

Force Audit
-------------

This Option is used to enable Force Audit mode which prevents the device from performing additional operations when the :ref:`hsm2-concepts-logs-label` is full.

The Option accepts three different values:

* 0x00: Option disabled

* 0x01: Option enabled

* 0x02: Option permanently enabled (only possible to turn off through factory reset)

Command Audit
---------------

This Option is used to enable or disable logging of specific commands. Logging commands impacts performance. By default logging is enabled for all operations.

The Option accepts three different values:

* 0x00: Option disabled

* 0x01: Option enabled

* 0x02: Option permanently enabled (only possible to turn off through factory reset)

Multiple commands can be specified at once with the syntax ``C1 V1, C2 V2, ..., Cn Vn`` where ``Ci`` is the Command Code and ``Vi`` is the Option Value. An example of this syntax can be found at the :ref:`hsm2-cmd-set-option-label` description.