.. _west_slkey-tool:

Atmosic Side-Load Key (SLKEY) Tool
###################################

It is a simple command line utility to manage private keys stored in RRAM memory slots on Atmosic devices. The tool supports reading and writing individual keys or all 8 slots at once, currently supports Windows and Linux platforms.

The table below lists the available actions of ``SLKEY``. Detailed descriptions of each action can be found in :ref:`West slkey command <west_slkey_command>` section.

.. raw:: html

   <div>
      <table style="border-collapse: collapse;width:auto;;border-style:double;font-family: Arial, sans-serif">
         <tr>
            <th style="background-color: #EDEDED;color: rgb(37, 37, 37);padding: 10px;border: 1px solid white !important">Command</th>
            <th style="background-color: #EDEDED;color: rgb(37, 37, 37);padding: 10px;border: 1px solid white !important">Explanation</th>
         </tr>
         <tr>
            <td style="background-color: white; color: rgb(37, 37, 37); padding: 10px;border: 1px solid black !important">-h, --help</td>
            <td style="background-color: white; color: rgb(37, 37, 37); padding: 10px;border: 1px solid black !important">List available commands</td>
         </tr>
         <tr>
            <td style="background-color: white; color: rgb(37, 37, 37); padding: 10px;border: 1px solid black !important">read</td>
            <td style="background-color: white; color: rgb(37, 37, 37); padding: 10px;border: 1px solid black !important">Read private key from a specific slot</td>
         </tr>
         <tr>
            <td style="background-color: white; color: rgb(37, 37, 37); padding: 10px;border: 1px solid black !important">write</td>
            <td style="background-color: white; color: rgb(37, 37, 37); padding: 10px;border: 1px solid black !important">Write private key to a specific slot</td>
         </tr>
         <tr>
            <td style="background-color: white; color: rgb(37, 37, 37); padding: 10px;border: 1px solid black !important">read_all</td>
            <td style="background-color: white; color: rgb(37, 37, 37); padding: 10px;border: 1px solid black !important">Read all private keys from slots 0-7</td>
         </tr>
         <tr>
            <td style="background-color: white; color: rgb(37, 37, 37); padding: 10px;border: 1px solid black !important">write_all</td>
            <td style="background-color: white; color: rgb(37, 37, 37); padding: 10px;border: 1px solid black !important">Write all private keys from a file to slots 0-7</td>
         </tr>
      </table>
   </div>

|

Before You Begin
================
Before running the ``SLKEY`` tool, ensure the following items are prepared:

1. Private Key Storage Information
----------------------------------
Private keys are stored in 8 slots (0-7) in RRAM memory. Each slot can hold a 32-byte private key.

**Memory Layout:**

- **RRAM Base Address:** ``0x10000000``
- **Private Key Start Offset:** ``0x8FF00``
- **Slot Size:** ``32 bytes`` (256 bits)
- **Total Slots:** ``8`` (slots 0-7)
- **Total Key Area:** ``256 bytes``

**Slot Address Calculation:**

.. code-block:: bash

   Slot Address = 0x8FF00 + (Slot Index × 32)

   Slot 0: 0x8FF00
   Slot 1: 0x8FF20
   Slot 2: 0x8FF40
   Slot 3: 0x8FF60
   Slot 4: 0x8FF80
   Slot 5: 0x8FFA0
   Slot 6: 0x8FFC0
   Slot 7: 0x8FFE0

2. Key Data Format
------------------
Private keys can be provided in two formats:

**Hex String Format (for single key write):**

.. code-block:: bash

   10eb3d60be71ca15f0ae732b81777d85072c351fd708613ba310982df4df1409

**File Format (for write_all):**

- **Binary format:** 256 bytes (8 keys × 32 bytes each)

The file must contain raw binary data (hex bytes), not ASCII text.

.. note::

   Keys shorter than 32 bytes will be automatically padded with ``0xFF`` at the end.

3. Partition Information File
-----------------------------
The partition_info.map file is required to locate the private key storage offset. The tool extracts the ``SEC_SIDELOAD_KEYS_OFFSET`` parameter.

For example (partition_info.map):

.. code-block:: bash

   SEC_SIDELOAD_KEYS_OFFSET=0x8FF00
   SEC_SIDELOAD_KEYS_SIZE=0x100


.. _west_slkey_command:

West slkey Commands
===================

Use the following command to view usage details:

**Syntax**

.. code-block:: bash

   west slkey --help

**Example**

.. code-block:: bash

   $ west slkey --help
   usage: west slkey [-h] {read,write,read_all,write_all} ...

   Atmosic Side-Load Key (SLKEY) management tool

   positional arguments:
     {read,write,read_all,write_all}
                           sub-command to run
       read                Read private key from specified slot
       write               Write private key to specified slot
       read_all            Read all private keys from slots 0-7
       write_all           Write private keys from file to slots 0-7

   options:
     -h, --help            show this help message and exit

Read a Single Private Key
--------------------------

**Syntax**

.. code-block:: bash

   west slkey read [-h] --slot_index SLOT_INDEX [--device DEVICE_ID] [--dl] [--jlink] [--board BOARD] [-p PARTITION_FILE]

Required parameters:

- ``--slot_index`` Key slot number (0-7)
- ``--device`` Serial number of the programmer (see :ref:`serial <atmosic_evk>`)
- ``--board`` Atmosic device (see :ref:`board <atmosic_evk>`)
- ``-p`` Partition_info.map file path

Optional parameters:

- ``--dl`` Specify if using a **Download Board (DL)** interface
- ``--jlink`` Specify if using a **J-Link** interface

**Example**

.. code-block:: bash

   $ west slkey read --slot_index 0 --device ATMAPT1000000006 --dl --board ATMEVK-3405-WQK-5 -p build/settings/zephyr/partition_info.map
   SEC_SIDELOAD_KEYS_OFFSET: 0x8FF00
   Using ATM OpenOCD 'D:\Project\zephyr\zephyrproject\modules\hal\atmosic_lib\tools\openocd\bin\Windows_NT\openocd'
   Inferred OpenOCD config for board 'ATMEVK-3405-WQK-5': D:\Project\zephyr\zephyrproject\zephyr/../openair/modules/hal_atmosic/ATM34xx/rev-5/openocd/atmx3_openocd.cfg
   Reading private key from slot 0 (address 0x8FF00) from RRAM...
   Slot 0 (32 bytes): 10eb3d60be71ca15f0ae732b81777d85072c351fd708613ba310982df4df1409

Write a Single Private Key
---------------------------

**Syntax**

.. code-block:: bash

   west slkey write [-h] --slot_index SLOT_INDEX --data DATA [--device DEVICE_ID] [--dl] [--jlink] [--board BOARD] [-p PARTITION_FILE]

Required parameters:

- ``--slot_index`` Key slot number (0-7)
- ``--data`` Private key as hex string (will be padded to 32 bytes with 0xFF if shorter)
- ``--device`` Serial number of the programmer (see :ref:`serial <atmosic_evk>`)
- ``--board`` Atmosic device (see :ref:`board <atmosic_evk>`)
- ``-p`` Partition_info.map file path

Optional parameters:

- ``--dl`` Specify if using a **Download Board (DL)** interface
- ``--jlink`` Specify if using a **J-Link** interface

**Example**

.. code-block:: bash

   $ west slkey write --slot_index 1 --data 10eb3d60be71ca15f0ae732b81777d85072c351fd708613ba310982df4df1409 --device ATMAPT1000000006 --dl --board ATMEVK-3405-WQK-5 -p build/settings/zephyr/partition_info.map
   SEC_SIDELOAD_KEYS_OFFSET: 0x8FF00
   Using ATM OpenOCD 'D:\Project\zephyr\zephyrproject\modules\hal\atmosic_lib\tools\openocd\bin\Windows_NT\openocd'
   Inferred OpenOCD config for board 'ATMEVK-3405-WQK-5': D:\Project\zephyr\zephyrproject\zephyr/../openair/modules/hal_atmosic/ATM34xx/rev-5/openocd/atmx3_openocd.cfg
   Writing private key to slot 1 (address 0x8FF20) to RRAM...
   Successfully wrote private key to slot 1

Read All Private Keys
----------------------

**Syntax**

.. code-block:: bash

   west slkey read_all [-h] [-o OUTPUT] [--device DEVICE_ID] [--dl] [--jlink] [--board BOARD] [--rram] [-p PARTITION_FILE]

Required parameters:

- ``--device`` Serial number of the programmer (see :ref:`serial <atmosic_evk>`)
- ``--board`` Atmosic device (see :ref:`board <atmosic_evk>`)
- ``-p`` Partition_info.map file path

Optional parameters:

- ``-o, --output`` Optional output file to save all keys (256 bytes total)
- ``--dl`` Specify if using a **Download Board (DL)** interface
- ``--jlink`` Specify if using a **J-Link** interface

**Example**

1. Read all slots and display

   .. code-block:: bash

      $ west slkey read_all --device ATMAPT1000000006 --dl --board ATMEVK-3405-WQK-5 -p build/settings/zephyr/partition_info.map
      SEC_SIDELOAD_KEYS_OFFSET: 0x8FF00
      Using ATM OpenOCD 'D:\Project\zephyr\zephyrproject\modules\hal\atmosic_lib\tools\openocd\bin\Windows_NT\openocd'
      Inferred OpenOCD config for board 'ATMEVK-3405-WQK-5': D:\Project\zephyr\zephyrproject\zephyr/../openair/modules/hal_atmosic/ATM34xx/rev-5/openocd/atmx3_openocd.cfg
      Reading all private keys from slots 0-7 from RRAM...
      Reading 256 bytes from address 0x8FF00...

      ======================================================================
      All Slot Data:
      ======================================================================
      Slot 0: 10eb3d60be71ca15f0ae732b81777d85072c351fd708613ba310982df4df1409
      Slot 1: 10eb3d60be71ca15f0ae732b81777d85072c351fd708613ba310982df4df1409
      Slot 2: 404142434445464748494a4b4c4d4e4f505152535455565758595a5b5c5d5e5f
      Slot 3: 606162636465666768696a6b6c6d6e6f707172737475767778797a7b7c7d7e7f
      Slot 4: 808182838485868788898a8b8c8d8e8f909192939495969798999a9b9c9d9e9f
      Slot 5: a0a1a2a3a4a5a6a7a8a9aaabacadaeafb0b1b2b3b4b5b6b7b8b9babbbcbdbebf
      Slot 6: c0c1c2c3c4c5c6c7c8c9cacbcccdcecfd0d1d2d3d4d5d6d7d8d9dadbdcdddedf
      Slot 7: e0e1e2e3e4e5e6e7e8e9eaebecedeeeff0f1f2f3f4f5f6f7f8f9fafbfcfdfeff
      ======================================================================

      Successfully read all 256 bytes from slots 0-7

2. Read all slots and save to file

   .. code-block:: bash

      $ west slkey read_all --device ATMAPT1000000006 --dl --board ATMEVK-3405-WQK-5 -o all_keys.bin -p build/settings/zephyr/partition_info.map
      SEC_SIDELOAD_KEYS_OFFSET: 0x8FF00
      Using ATM OpenOCD 'D:\Project\zephyr\zephyrproject\modules\hal\atmosic_lib\tools\openocd\bin\Windows_NT\openocd'
      Inferred OpenOCD config for board 'ATMEVK-3405-WQK-5': D:\Project\zephyr\zephyrproject\zephyr/../openair/modules/hal_atmosic/ATM34xx/rev-5/openocd/atmx3_openocd.cfg
      Reading all private keys from slots 0-7 from RRAM...
      Reading 256 bytes from address 0x8FF00...

      ======================================================================
      All Slot Data:
      ======================================================================
      Slot 0: 10eb3d60be71ca15f0ae732b81777d85072c351fd708613ba310982df4df1409
      Slot 1: 10eb3d60be71ca15f0ae732b81777d85072c351fd708613ba310982df4df1409
      Slot 2: 404142434445464748494a4b4c4d4e4f505152535455565758595a5b5c5d5e5f
      Slot 3: 606162636465666768696a6b6c6d6e6f707172737475767778797a7b7c7d7e7f
      Slot 4: 808182838485868788898a8b8c8d8e8f909192939495969798999a9b9c9d9e9f
      Slot 5: a0a1a2a3a4a5a6a7a8a9aaabacadaeafb0b1b2b3b4b5b6b7b8b9babbbcbdbebf
      Slot 6: c0c1c2c3c4c5c6c7c8c9cacbcccdcecfd0d1d2d3d4d5d6d7d8d9dadbdcdddedf
      Slot 7: e0e1e2e3e4e5e6e7e8e9eaebecedeeeff0f1f2f3f4f5f6f7f8f9fafbfcfdfeff
      ======================================================================

      Successfully saved all 256 bytes to all_keys.bin

Write All Private Keys from File
---------------------------------

**Syntax**

.. code-block:: bash

   west slkey write_all [-h] -f FILENAME [--device DEVICE_ID] [--dl] [--jlink] [--board BOARD] [-p PARTITION_FILE]

Required parameters:

- ``-f, --filename`` Path to file containing private keys for slots 0-7
- ``--device`` Serial number of the programmer (see :ref:`serial <atmosic_evk>`)
- ``--board`` Atmosic device (see :ref:`board <atmosic_evk>`)
- ``-p`` Partition_info.map file path

Optional parameters:

- ``--dl`` Specify if using a **Download Board (DL)** interface
- ``--jlink`` Specify if using a **J-Link** interface

.. note::

   The file must be in **binary format** containing 256 bytes (8 keys × 32 bytes each).
   The file should contain raw binary data (hex bytes), not ASCII text.

**Example**

.. code-block:: bash

   $ west slkey write_all -f keys.bin --device ATMAPT1000000006 --dl --board ATMEVK-3405-WQK-5 -p build/settings/zephyr/partition_info.map
   SEC_SIDELOAD_KEYS_OFFSET: 0x8FF00
   Using ATM OpenOCD 'D:\Project\zephyr\zephyrproject\modules\hal\atmosic_lib\tools\openocd\bin\Windows_NT\openocd'
   Inferred OpenOCD config for board 'ATMEVK-3405-WQK-5': D:\Project\zephyr\zephyrproject\zephyr/../openair/modules/hal_atmosic/ATM34xx/rev-5/openocd/atmx3_openocd.cfg
   Writing 256 bytes from keys.bin to slots 0-7 in RRAM...
   Writing to address 0x8FF00...
   Successfully wrote all 256 bytes to slots 0-7

Common Use Cases
================

Backup and Restore Keys
-----------------------

**Backup all keys from device:**

.. code-block:: bash

   west slkey read_all --device ATMAPT1000000006 --dl --board ATMEVK-3405-WQK-5 -o backup_keys.bin -p build/settings/zephyr/partition_info.map

**Restore all keys to device:**

.. code-block:: bash

   west slkey write_all -f backup_keys.bin --device ATMAPT1000000006 --dl --board ATMEVK-3405-WQK-5 -p build/settings/zephyr/partition_info.map

Update a Single Key
-------------------

**Update only slot 3 with a new key:**

.. code-block:: bash

   west slkey write --slot_index 3 --data 606162636465666768696a6b6c6d6e6f707172737475767778797a7b7c7d7e7f --device ATMAPT1000000006 --dl --board ATMEVK-3405-WQK-5 -p build/settings/zephyr/partition_info.map

Verify Key Write
----------------

**Write a key and then read it back to verify:**

.. code-block:: bash

   # Write the key
   west slkey write --slot_index 0 --data 10eb3d60be71ca15f0ae732b81777d85072c351fd708613ba310982df4df1409 --device ATMAPT1000000006 --dl --board ATMEVK-3405-WQK-5 -p build/settings/zephyr/partition_info.map

   # Read it back
   west slkey read --slot_index 0 --device ATMAPT1000000006 --dl --board ATMEVK-3405-WQK-5 -p build/settings/zephyr/partition_info.map