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 #

Download and unzip or clone the repository

https://github.com/tillitis/tillitis-key1/releases/tag/TK1-23.03.2

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

All the paths in the instructions below are relative to where you unpacked the distribution or cloned the repo, so add a TK1-23.03.2 or a tillitis-key1 as necessary to the paths.

3. Start the container #

If you’re not going with the native tools, start the container by

podman run --rm --device /dev/bus/usb/$(lsusb | grep -m 1 1209:8886 | awk '{ printf "%s/%s", $2, substr($4,1,3) }') -v .:/build:Z -w /build -it ghcr.io/tillitis/tkey-builder:2 /usr/bin/bash

setsebool container_use_devices=true

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

podman run --rm --mount type=bind,source="./",target=/src -w /src -it ghcr.io/tillitis/tkey-builder:2 /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.

cd hw/application_fpga/
make 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 #

cd hw/application_fpga/
make 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