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 OpenAir Utility).

The Atmosic Secure Journal Tool requires Python packages of Zephyr.

To install with the Zephyr requirements file:

pip install -r zephyr/scripts/requirements.txt

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

For Linux:

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

For Windows:

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:

west secjrnl --help

Required parameters:

  • board Atmosic device (see board).

  • serial Serial number of the programmer (see serial).

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:

west secjrnl dump --device <serial> --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:

west secjrnl append --device <serial> --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. To pass raw byte values format it like so: \0xde\0xad\0xbe\0xef. As such, --data="data" will result in the same output as --data="\0x64\0x61\0x74\0x61.

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:

west secjrnl erase --device <serial> --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:

west secjrnl ratchet_jrnl --device <serial> --jlink --board <board>

Note

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