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

  • DEVICE_ID 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 <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:

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:

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:

@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:

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:

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:

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:

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.