.. _west_secjrnl-tool:

Atmosic Secure Journal Tool
###########################

Overview
********

The secure journal is a dedicated block of RRAM that has the property of being a write-once, append-only data storage area that replaces traditional OTP memory. This region is located near the end of the RRAM storage array at **0x8F800 – 0x8FEEF** (1776 bytes).

The secure journal data updates are controlled by a secure counter (address **ratchet**). The counter determines the next writable location at an offset from the start of the journal. An offset greater than the counter value is writable while any offset below or equal to the counter is locked from updates. The counter can only increment monotonically and cannot be rolled back. This provides the immutability of OTP as well as the flexibility to append new data items or override past items using a find the latest TLV search.

The west extension command is provided by the Atmosic HAL to allow for easy access and management of the secure journal on supported platforms.

Python Requirements
*******************

The following setup procedures are not required when using atmoautil (see :ref:`OpenAir Utility <atmoautil>`).

The Atmosic Secure Journal Tool requires Python packages of Zephyr.

To install with the Zephyr requirements file:

.. code-block:: bash

   pip install -r zephyr/scripts/requirements.txt

If needed, create a symbolic link or use a Python virtual environment:

For Linux:

.. code-block:: bash

   sudo ln -s $(which python3) /usr/bin/python

For Windows:

.. code-block:: bash

   mklink "C:\Path\To\Python\python3.exe" "C:\Path\To\Python\python.exe"

.. note::
   On Windows:

   - you can use ``where python3`` to locate the path of the Python executable.
   - Ensure that the symlink or Python installation directory is included in the system PATH environment variable, or place the symlink in a directory that is already in the PATH.

West secjrnl Commands
*************************

Use the following command to view usage details:

.. code-block:: bash

   west secjrnl --help

Required parameters:

- ``BOARD`` Atmosic device (see :ref:`board <atmosic_evk>`).
- ``DEVICE_ID`` Serial number of the programmer (see :ref:`serial <atmosic_evk>`).

.. note::
  ``--jlink`` Specify if using a **J-Link** interface. If omitted, the **FTDI** interface is assumed.

Dumping Secure Journal
======================

To dump all the TLV tags located in the secure journal:

.. code-block:: bash

    west secjrnl dump --device <DEVICE_ID> --jlink --board <BOARD>

Appending a Tag to the Secure Journal
=====================================

The secure journal uses a find latest search algorithm to allow overrides. If the passed tag should NOT be overridden in the future, add the flag ``--locked`` to the append command. See the following section for more information regarding locking a tag.

To append a new tag to the secure journal:

.. code-block:: bash

    west secjrnl append --device <DEVICE_ID> --jlink --board <BOARD> --tag <tag_id> --data <tag_data>

- ``tag_id`` appropriate tag ID (Ex: ``0xde``)
- ``tag_data`` the data for the tag. This is passed as a string with **ASCII-only characters** (0-127). To pass raw byte values format it like so: ``\xde\xad\xbe\xef``. As such, ``--data "data"`` will result in the same output as ``--data "\x64\x61\x74\x61"``.

Data Format Examples
--------------------

The ``--data`` parameter supports ASCII text and escape sequences for binary data:

- **ASCII text**: ``--data "hello world"`` (characters 0-127 only)
- **Binary bytes**: ``--data "\xde\xad\xbe\xef"`` (any byte value 0-255)
- **Mixed data**: ``--data "text\x00\xfabinary"`` (ASCII text with binary bytes)
- **Special characters**: ``--data "line1\nline2\ttab"`` (newlines, tabs, etc.)

.. important::

   - Use ``\xab`` format for hex bytes, **not** ``\0xab``. Each byte is represented as ``\x`` followed by exactly two hex digits.
   - **ASCII characters (0-127) can be typed directly**. Non-ASCII characters must use ``\x`` escape sequences.
   - **Example**: Use ``\xe9`` instead of typing ``é`` directly to avoid encoding issues.

Complete Example
----------------

Here's a complete example showing how mixed ASCII text and binary data is processed:

.. code-block:: bash

   west secjrnl append --device <DEVICE_ID> --jlink --board <BOARD> --tag 0x15 --data "text\x00\x01binary\n" --dry-run

This command will result in the following output:

.. code-block:: text

   @00b9 tag:(15)   [V][!L][!E] data: [74 65 78 74 00 01 62 69 6e 61 72 79 0a]

**Data breakdown:**
- ``text`` → ``74 65 78 74`` (ASCII: 't', 'e', 'x', 't')
- ``\x00`` → ``00`` (null byte)
- ``\x01`` → ``01`` (binary byte value 1)
- ``binary`` → ``62 69 6e 61 72 79`` (ASCII: 'b', 'i', 'n', 'a', 'r', 'y')
- ``\n`` → ``0a`` (newline character)

**Example with byte values:**

.. code-block:: bash

   west secjrnl append --device <DEVICE_ID> --jlink --board <BOARD> --tag 0x16 --data "abcd\xfa\xff" --dry-run

Results in: ``[61 62 63 64 fa ff]`` (ASCII 'abcd' + bytes 250, 255)

.. note::
   **BD Address Configuration**

   When setting a BD address in the secure journal, **the byte sequence must be reversed** from the standard representation. The BD address uses **tag ID 0x1**.

   - **Tag ID**: ``0x1`` (BD address)
   - **Standard BD Address Format**: ``AA:BB:CC:DD:EE:FF``
   - **Secure Journal Format**: ``\xFF\xEE\xDD\xCC\xBB\xAA`` (reversed byte order)

   **Example:** If your intended BD address is ``12:34:56:78:9A:BC``, you must provide it as:

   .. code-block:: bash

      west secjrnl append --device <DEVICE_ID> --jlink --board <BOARD> --tag 0x1 --data "\xBC\x9A\x78\x56\x34\x12"

   This reversal is required because the secure journal stores the BD address in little-endian byte order, while the standard representation uses big-endian format.

.. note::

  The ``append`` command does NOT increment the ratchet. The newly appended tag is still unprotected from erasing.

Locking Down a Tag
==================

The secure journal provides a secure method of storing data while still providing options to update the data if needed. However, there are key data entries that should never be updated across the life of the device (e.g. UUID).
This support is provided by software and can be enabled for a tag by passing the ``--locked`` to the command when appending a new tag.

It is important to understand, that once a tag is **locked** (and ratcheted), the specific tag can never be updated in the future - Appending a new tag of the same value will be ignored.

Erasing Non-ratcheted Data From the Secure Journal
==================================================

Appended tags are not ratcheted down. This allows for prototyping with the secure journal before needing to lock down the TLVs.

To support prototyping, you can erase non-ratcheted data easily through:

.. code-block:: bash

   west secjrnl erase --device <DEVICE_ID> --jlink --board <BOARD>

Ratcheting Secure Journal
=========================

This will list the non-ratcheted tags and confirm that you want to ratchet the tags. Confirm by typing 'yes'.

To ratchet data, run the command:

.. code-block:: bash

   west secjrnl ratchet_jrnl --device <DEVICE_ID> --jlink --board <BOARD>

.. note::

   This process is non-reversible. Once ratcheted, that region of the secure journal cannot be modified.