Tools & libraries #
To build you can either use our OCI images or use native tools on your dev box.
If want your device applications not to change, which as you know also means changing that application’s CDI as explained in the introduction, it might be better to use the OCI images. At the very least you want to be sure that the versions of the compiler and other tools you use stays the same. Perhaps pin those packages if you don’t want to use containers?
Host toolchain #
To create applications you need at least
golang packages installed. Version 15 or later of LLVM/Clang is
required (with riscv32 support and the Zmmul extension,
-march=rv32iczmmul). Packages on Ubuntu 22.10 (Kinetic) are known to
On Ubuntu, you can install the required packages with the following command:
$ sudo apt install build-essential clang lld llvm bison flex libreadline-dev \ gawk tcl-dev libffi-dev git mercurial graphviz \ xdot pkg-config python3 libftdi-dev \ python3-dev libeigen3-dev \ libboost-dev libboost-filesystem-dev \ libboost-thread-dev libboost-program-options-dev \ libboost-iostreams-dev cmake libusb-1.0-0-dev \ ninja-build libglib2.0-dev libpixman-1-dev \ golang clang-format
We provide a container image which has all the above packages and tools already installed for use with Podman or Docker.
This assumes a working rootless podman. On Ubuntu 22.10, running
$ sudo apt install podman rootlesskit slirp4netns
should be enough to get you a working Podman setup.
You can use the following command to fetch the image:
$ podman pull ghcr.io/tillitis/tkey-builder:2
Note well: This image is really large (~ 2 GiB) because it also contains all the tools necessary to build the FPGA bitstream and the firmware.
Tillitis provides a TKey emulator based on QEMU.
The easiest way to run the TKey emulator is to use our OCI image (~120 MiB):
We provide a script in
that assumes a working rootless Podman setup and
socat installed. It
currently only works on a Linux system (specifically, it does not work
when containers are run in Podman’s virtual machine, which is required
on MacOS and Windows). On Ubuntu 22.10, running
apt install podman rootlesskit Ubuntu 22.10, running apt install podman rootlesskit
slirp4netns socat` should be enough. Then you can just run the script
This will let you run client apps with
--port ./tkey-qemu-pty and it
will find the running emulator.
QEMU on macOS #
Note that on macOS you need to add
--speed 9600 on the client apps
when you use the QEMU pty.
Building QEMU #
If you want to build QEMU yourself, go to the
tk1 branch in our
qemu repository to fetch the
emulator and then build it, or execute the following commands:
$ git clone -b tk1 https://github.com/tillitis/qemu $ mkdir qemu/build $ cd qemu/build $ ../configure --target-list=riscv32-softmmu --disable-werror $ make -j $(nproc)
(Built with warnings-as-errors disabled, see this issue.)
Then execute the following commands to fetch and build the firmware:
$ git clone https://github.com/tillitis/tillitis-key1 $ cd tillitis-key1/hw/application_fpga $ make firmware.elf
Then execute the following commands to run the emulator, setting the
built firmware with the
$ /path/to/qemu/build/qemu-system-riscv32 -nographic -M tk1,fifo=chrid -bios firmware.elf \ -chardev pty,id=chrid
In the output from QEMU it tells you which serial port it’s using, for
/dev/pts/1. This is what you need to use as
This is what you need to set with
--port when running a client
Device libraries #
Libraries for development of TKey device apps are available in:
Build the tkey-libs first, typically just:
$ git clone https://github.com/tillitis/tkey-libs.git $ cd tkey-libs $ make
$ make podman
if you have Podman installed.
Client libraries #
We provide two Go packages to help in developing client applications. What we call “client” is the computer or mobile device you insert your TKey into.
github.com/tillitis/tkeyclient: Contains functions to connect to, load and start a device application on the TKey. - Go doc.
github.com/tillitis/tkeysign: Contains functions to communicate with the
signerdevice app, an ed25519 signing oracle. Go doc.
Our TKey Client and Device Apps #
We provide some client and device apps in the tillitis-key1-apps GitHub repository.
First clone and build the device libraries as explained above.
Execute the following command to clone the repository:
$ git clone https://github.com/tillitis/tillitis-key1-apps.git $ cd tillitis-key1-apps
Again you have the choice of building with host tools or an OCI image.
Building with host tools #
Execute the following command to build all TKey client and device applications:
If you cloned and built the tkey-libs somewhere else than in a
tkey-libs next to
tillitis-key1-apps you need to
provide the path relative to
tillitis-key1-apps/apps, for instance:
$ make LIBDIR=../../tkey-libs-main
If your available
objcopy is anything other than the default
llvm-objcopy, then define
OBJCOPY to whatever they’re called on
TKey device applications can run both on the real hardware TKey and in
the QEMU emulator. In both cases, the client application (for example
tkey-ssh-agent) talks to the device app over a serial port, virtual
or real. There is a separate section below that explains how to run
device apps in QEMU.
To build everything in the apps repo:
$ git clone https://github.com/tillitis/tillitis-key1-apps $ cd tillitis-key1-apps $ make podman
Or use podman directly if you haven’t got
$ podman run --rm --mount type=bind,source=.,target=/src --mount type=bind,source=../tkey-libs,target=/tkey-libs -w /src -it ghcr.io/tillitis/tkey-builder:1 make -j