Detailed Specifications
=======================

Host Tools
----------

The host tools this year are created by the organizers and read-only.
The host tools create a basic input/output format for communications
between your devices and the host computer. More information on the host
tools is available :doc:`here <../system/ectf_tools>`.

Design Package
--------------

The Generate Secrets script must be implemented as a pip-installable Python package
named ``ectf26_design``.

Generate Secrets
^^^^^^^^^^^^^^^^

Generate Secrets is a function that should be importable using:

.. code-block:: python

  from ectf26_design.gen_secrets import gen_secrets

The function takes a list of groups that will be valid in the system and returns any
secrets that will be passed to future steps.

The full required interface is as follows:

.. code-block:: python

  def gen_secrets(groups: list[int]) -> bytes:
      pass

HSM Firmware
------------

There are six required functional elements to the HSM firmware. These
elements directly relate to the host tools:

- List Files
- Read a File from the HSM
- Write a File to the HSM
- Listen for Messages from a Neighboring HSM
- Interrogate Files from a Neighboring HSM
- Receive a File from a Neighboring HSM

All functional requirements must align with the :ref:`2026_timing_requirements`

.. _2026_file_allocation_table:

File Allocation Table
^^^^^^^^^^^^^^^^^^^^^

The File Allocation Table (FAT) is used by the :doc:`../system/bootloader` to calculate
cryptographic file digests. It must contain at least 8 of the following 24-byte struct
where each entry corresponds to a file slot. The FAT must be based at the flash address
0x3a000.

.. list-table:: FAT
    :header-rows: 1

    * - Offset
      - Size
      - Name
      - Description
    * - 0x0
      - 16
      - UUID
      - UUID of the file in that slot
    * - 0x10
      - 2
      - Length
      - Length of the file
    * - 0x12
      - 2
      - Padding
      - Unused to pad to 32-bit alignment
    * - 0x14
      - 4
      - Addr
      - Starting flash address of the file

|

.. _2026_flash_layout:

Flash Layout
^^^^^^^^^^^^

.. list-table:: Flash Layout
    :header-rows: 1

    * - Offset
      - Size
      - Name
      - Description
    * - 0x0
      - 0x6000
      - Bootloader
      - Reserved for the eCTF bootloader
    * - 0x6000
      - 0x34000
      - APP1
      - Flash region that may be used by your design however you see fit. The IVT must
        be loaded from the base of this region
    * - 0x3A000
      - 0x400
      - File Allocation Table
      - This page MUST store the :ref:`2026_file_allocation_table`
    * - 0x3A400
      - 0x5c00
      - APP2
      - Flash region that may be used by your design however you see fit.

|


Detailed Requirements
---------------------

The following constraints must be met:

.. _2026_permission_string:

Permission Strings
^^^^^^^^^^^^^^^^^^

At build time, a string representing the permission set is provided (e.g.,
``1234=RW-:aabb=RWC:1a2b=--C``).

**Permission list**: The string shall be a colon-separated list of permissions (e.g.,
``<perm1>:<perm2>:<perm3>``).

**Permission entry**: Each entry shall be a pair of group ID and permissions separated
by an equal sign (e.g., ``<group_id>=<permission>``).

**Group ID**: The group ID shall be a 16-bit hexadecimal number padded with 0s to be a
total of 4 characters with no preceding '0x' (e.g., ``4b1d``).

**Permission**: The permission shall be a 3-character string where present permissions
are represented by their opcode and absent permissions are represented by a '-' (e.g.,
``RWC``, ``RW-``, ``--C``).

.. _2026_pin:

PINs
^^^^

A PIN shall be exactly 6 lowercase hexadecimal characters (0-9, a-f).

.. _2026_timing_requirements:

.. list-table:: Timing Requirements
    :header-rows: 1

    * - Operation
      - Maximum Time for Completion
    * - Device Wake
      - 1 second
    * - List Files
      - 500 milliseconds
    * - Read File
      - 1000 milliseconds
    * - Write File
      - 1000 milliseconds
    * - Receive File
      - 2000 milliseconds
    * - Interrogate
      - 1000 milliseconds
    * - Any Operation Where an Invalid PIN is Provided
      - 5 seconds

|

.. _2026_size_requirements:

.. list-table:: File Size Requirements
    :header-rows: 1

    * - Component
      - Size
    * - Group ID
      - 16 bits
    * - File UUID
      - 16 bytes
    * - File Name
      - Max 32 bytes
    * - File Content Size
      - Max 8192 bytes

|

.. _2026_file_storage_requirements:

.. list-table:: File Storage Requirements
    :header-rows: 0

    * - File Slots
      - 8 slots

|

.. _2026_deployment_requirements:

.. list-table:: Deployment Requirements
    :header-rows: 0

    * - Number of supported group ids
      - 32 groups

|

.. image:: ../../_static/2026/2026\ Read\ The\ Rules.png
    :height: 5 ex

.. _2026_allowed_languages:

Allowed Programming Languages
-----------------------------

To build the firmware your design, your team may choose to implement your design
in any compatible language. To align with good development practices, you must
not use a language that was specifically chosen to be difficult to understand.

The pre-approved programming languages are: C, C++, and Rust. If you wish to use
a different language, please reach out to the organizers first.

Be aware that if your team decides to use a language  which incorporates a panic
handler, your design must still adhere to the :ref:`2026_timing_requirements`
and should not enter an infinite loop in response to any normal input.

The :doc:`../system/reference_design` was created in C, and as such if your
team decides to use another programming language, the Dockerfile must be updated
to allow for the organizers and teams to be able to build and utilize your
design.