fw-packager

Tool that creates a FW update file package from a FW binary for TROPIC01.

This tool is used to facilitate the customer (vendor key) feature of TROPIC01. For more details, see ODN_TR01_app_007 - FW Update Application Note document.

Getting started

1. clone this repository and initialize submodules: git clone --recurse-submodules https://github.com/tropicsquare/fw-packager.git
2. install dependencies (see below)
3. run python fw_packager.py -h to see help:

usage: FW packager [-h] {pack,sign,chain} ...

Script could package plain FW binary from HEX file or update the signature in FW package file.

positional arguments:
  {pack,sign,chain}
    pack             Package the plain FW binary (add header and signature).
    sign             Sign FW package file (replaces existing signature with a new one).
    chain            Create FW update signed hash chain.

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

The tool supports 3 operations: 'pack', 'sign' and 'chain'. You can see help for each of the operations: python fw_packager.py {pack,sign,chain} -h

Pack

Packages the compiled FW binary - adds a header and a signature.

python fw_packager.py pack
    --inp FW_BINARY  # .hex32 binary
    --ver VERSION    # for example 'v1.2.3'
    --type TYPE      # 'APP'/'SPECT'
    --git-hash HASH  # 32bit FW revision, for example a part of git commit hash ('2bca14bf')
    --key PRIV_KEY   # Ed25519 private key in PEM format
    --out OUT_FILE

Sign

Signs the already packed binary (from the 'pack' operation). Replaces the signature with a new one from the provided private key.

python fw_packager.py sign
    --inp PACKED_FW_BINARY
    --key PRIV_KEY   # Ed25519 private key in PEM format
    --out OUT_FILE

Chain

Creates a signed hash chain from the packed binary. The resulting file is the FW update file that can be used to update TROPIC01 FW.

python fw_packager.py chain
    --inp PACKED_FW_BINARY
    --key PRIV_KEY   # Ed25519 private key in PEM format
    --out OUT_FILE

Typical usage

Create a TROPIC01 FW update file

For firmware signing, you need the private key in the PEM format. You can generate the vendor private key in the PEM format, for example, via OpenSSL: openssl genpkey -algorithm ed25519 -out private.pem

To create a TROPIC01 FW update file:

1. obtain the vendor private key (PEM format) of TROPIC01 part number you want to create the update package for
2. obtain the compiled FW binary
3. create a packed FW binary ('pack' operation) with the vendor private key
4. create a FW update file ('chain' operation) with the vendor private key

The process is identical for both both the ECC engine (SPECT) and CPU FWs.

Verify Tropic Square provided TROPIC01 FW update file from source code

To verify the Tropic Square provided TROPIC01 FW update files (for example the official FW update files bundled with libtropic) were built from the published source code:

1. Build the ECC engine (SPECT) or CPU FWs yourself from source from https://github.com/tropicsquare/ts-spect-fw or https://github.com/tropicsquare/ts-tr01-app repositories and obtain the compiled FW binary
2. Use the Create a TROPIC01 FW update file process using the compiled FW binary with a dummy key to create own FW update file
3. Obtain Tropic Square FW update file you want to verify
4. Diff the two FW update files -> only the EdDSA 64B signature shall be different (Tropic Square production key vs dummy key used during creation of the update file), other data shall be the same.

Dependencies

Requires python3 and the following packages: typing_extensions cryptography crcmod pydantic

Tested python versions: 3.8 and 3.12

For python3.8 and python3.12 we provide a requirements.txt file with exact versions of dependencies that was tested to be working:

pip install -r requirements3.8.txt - installs needed dependencies for python 3.8

pip install -r requirements3.12.txt - installs needed dependencies for python 3.12