Build bitstream #

Building the bitstream consists of these steps:

1. Install the toolchain
2. Download the repository
3. Start the container, if using tkey-builder
4. Generate a unique UDS and UDI
5. Build the bitstream

1. Install the toolchain #

Our recommendation is to build using our OCI image, tkey-builder, in combination with Podman, which is supported on Linux, macOS, and Windows.

If Podman is not a valid choice for you, it is also possible to either use Docker or build the tools natively by compiling from source: native toolchain setup instructions.

Install and start Podman #

Start by installing Podman for your specific OS.

For Windows and macOS, you need to initialise a Podman Machine after you have installed Podman. This can be done with:

podman machine init
podman machine start

2. Download the repository #

It is highly recommended to use the latest official release, especially if you are programming the NVCM.

Download and unpack, or clone the repository

https://github.com/tillitis/tillitis-key1/releases

All the paths in the instructions below are relative to where you unpacked the distribution or cloned the repo, so add the tag of the downloaded release, like TK1-24.03, or a tillitis-key1 as necessary to the paths.

Open a terminal and move into the tillitis-key1 directory.

3. Start the container #

If you’re not going with the native tools, its time to start the container.

The make targets below will use the container associated with the given release, the raw podman commands below are written genericly to give you the latest container. That will most likely always work, but if you want to use the associated one, check the release notes to find it. Then add it to the commands below, for example such as ghcr.io/tillitis/tkey-builder:4.

make -C contrib run

podman run --rm --mount type=bind,source="$(pwd)",target=/src -w /src -it ghcr.io/tillitis/tkey-builder /usr/bin/bash

make -C contrib run

podman run --rm --mount type=bind,source="$(pwd)",target=/src -w /src -it ghcr.io/tillitis/tkey-builder /usr/bin/bash

podman run --rm --mount type=bind,source="./",target=/src -w /src -it ghcr.io/tillitis/tkey-builder /usr/bin/bash

which will give you a shell prompt inside the running container. Keep this open to run later commands.

4. Generate a unique UDS and UDI #

Before generating the bitstream, the UDS and UDI needs to be generated. We provide a tool, Tillitis TKey Provisioning Tool¹ (TPT), to generate a unique UDS and the UDI.

The UDS is very sensitive, so let’s explain how the TPT works when generating it.

The UDS is generated by fetching 256 bytes from the Python secrets module², which in turn fetches its entropy from the random number source provided by your system (it could be /dev/random/). As an additional layer of protection, the user is prompted to provide additional entropy. This serves two purposes; first, it is a string only the user knows and has control over as a part of the key derivation; second, the UDS is not dependent on only one random number source. All in all, you don’t have to put as much trust in a third party. These two sources are then the input data to the standardised key derivation function, HKDF³, which derives the UDS.

make -C hw/application_fpga secret

Note that if running outside a container, you need Python installed.

You will be prompted to input additional data in the form of:

• additional entropy; user controlled string of entropy, can be arbitrarily long (string)
• Vendor ID, use 16 (decimal)
• Product ID, use 8 (decimal)
• Product Revision, use 3 (decimal)
• Serial number, use any you like in the range 0 - 4 294 967 295 (2**32-1) (decimal)

The output is two generated files, uds.hex and udi.hex, in the /data folder.

NOTE: Remember to remove the generated secrets and binaries after the provision is completed. See instructions on how to remove secrets.

5. Build the bitstream #

make -C hw/application_fpga application_fpga.bin

This command will build the binary with the FPGA configuration, the firmware, and the secrets you created in the previous step. Depending on your computer, the build takes roughly 1-5 minutes. You will end up with a binary named application_fpga.bin.

Once the build is completed, it is time to program the TKey. Either continue to:

1. Program NVCM for a secure locked-down TKey, or
2. Program SPI flash for testing and development