Guide: Setup A Sigsum Lab Witness Using TKey

Introduction

Sigsum is a transparency log system made by our sister company Glasklar Teknik. Sigsum uses the concept of cosigning witnesses to increase trust in the log. You can read the original Sigsum design paper to understand this better.

This is an early attempt at a guide to configure a Sigsum cosigning witness using a Tillitis TKey for signatures. It’s not yet polished and obviously just meant for lab purposes. It’s meant as a proof of concept that you can use a TKey for signing in a Sigsum witness.

Note that this at first will use the standard tkey-device-signer device app which requires touch for every signature, just to make sure things are working. See Signing without touch at the end of the document if you want the touch requirement to be disabled.

Instead of being directly available on the Internet this witness will connect to Glasklar’s bastion at bastion.glasklar.is:443. It will observe Glasklar’s test log “barreleye”.

Witness functionality is provided by litewitness which is configured to use the TKey SSH Agent as a signer. The agent, in turn, uses a device app on the TKey to do the actual Ed25519 signatures. The device app is automatically loaded into the TKey on first use of the agent.

We will name our witness tillitis.se/test-witness-1.

The following diagram shows an overview of how the different components interact:

R P i G G T l l 5 K l a a e i s s y t k k e l l T S w a a K S i r r e H t y n B T A e a e g s s s e s t t n i t o L n o g

Prerequisites

Hardware

  • Raspberry Pi 5
    • Setup with Raspberry Pi OS 2025-05-13-raspios-bookworm-arm64-lite.img.xz
  • Tillitis TKey.

Information

To setup litewitness we need to know:

  • The fingerprint of the TKey identity in SHA256:... format.
    • This can be retrieved by running ssh-add -l through the tkey-ssh-agent.
  • The public key of the sigsum log as a 64 character long hex string.
    • This is the same public key as is used in the log entry of a sigsum policy files. In the case of Glasklar’s barreleye test log the key is: 4644af2abd40f4895a003bca350f9d5912ab301a49c77f13e5b6d905c20a5fe6.
  • The bastion address.
    • Since we are using Glasklar’s bastion this is bastion.glasklar.is:443.

Tell the log and bastion operators, in this case Glasklar Teknik, the following about the witness:

  • The name and public key of the witness. Litewitness will print this information as a verification key (vkey) when starting.

Follow Glasklar’s instructions on how to contact them with this information. Please specify in your message that this is for the “barreleye” test log.

Setup

The following commands will install litewitness and tkey-ssh-agent. Note that the Raspberry Pi OS comes with Go 1.19 and we need a more modern Go compiler.

sudo apt update
sudo apt upgrade

mkdir -p /tmp/witness
cd /tmp/witness

# Cannot install litewitness with go 1.19. Downloading go 1.23.10.
sudo apt install golang
go install golang.org/dl/go1.23.10@latest
~/go/bin/go1.23.10 download

# Installing litewitness
~/go/bin/go1.23.10 install filippo.io/torchwood/cmd/{litewitness,witnessctl}@v0.5.0

# Downloading and installing tkey-ssh-agent if digest is correct
wget https://github.com/tillitis/tkey-ssh-agent/releases/download/v1.0.0/tkey-ssh-agent_1.0.0_linux_arm64.deb
echo "841f37954dcc382e3d6f0df519a5d1ef926118b45f88eb20608bd5e23bbd6898  tkey-ssh-agent_1.0.0_linux_arm64.deb" | sha256sum -c && sudo apt install ./tkey-ssh-agent_1.0.0_linux_arm64.deb || return

# Enabling the tkey-ssh-agent service
sudo systemctl --user enable tkey-ssh-agent

# Adding Glasklar barelleye sigsum test-log
~/go/bin/witnessctl add-sigsum-log -key 4644af2abd40f4895a003bca350f9d5912ab301a49c77f13e5b6d905c20a5fe6 -db ~/litewitness.db

Start litewitness manually

If you do not already have the fingerprint of the TKey public key, run:

# Getting the fingerprint of the tkey public key.
SSH_AUTH_SOCK=$XDG_RUNTIME_DIR/tkey-ssh-agent/sock ssh-add -l

Then start litewitness:

# Starting litewitness. Replace SHA256:... with the SHA256:... string
# from the output of the previous line
~/go/bin/litewitness -name tillitis.se/test-witness-1 -ssh-agent $XDG_RUNTIME_DIR/tkey-ssh-agent/sock -key SHA256:... -bastion "bastion.glasklar.is:443" -db ~/litewitness.db

Is it working?

Once the witness is up and running a cosignature=-line matching your witness should be visible at https://test.sigsum.org/barreleye/get-tree-head.

The first field after = is the SHA256 hash of the witness’s public key in hex.

Starting TKey SSH Agent & litewitness at boot

By default the TKey SSH Agent only starts once a user logs in. To instead start the agent on boot we modify the existing service.

Below we use “USERNAME” to indicate the user you installed litewitness as, which will also be used for running the tkey-ssh-agent. Replace “USERNAME” below with the real user name.

First disable the existing tkey-ssh-agent service and copy its service file:

systemctl --user stop tkey-ssh-agent
systemctl --user disable tkey-ssh-agent
sudo cp /lib/systemd/user/tkey-ssh-agent.service /lib/systemd/system/tkey-ssh-agent@.service

Edit /lib/systemd/system/tkey-ssh-agent@.service and:

  • Add User=%i to the [Service] section. (This allows us to run the service as a specific user)
  • Change WantedBy=default.target to WantedBy=multi-user.target. (This runs the service at boot instead of when the user logs in)

The service file should look something like this:

[Unit]
...
[Service]
User=%i
ExecStart=/usr/bin/tkey-ssh-agent --agent-path /%t/tkey-ssh-agent/sock
...
[Install]
WantedBy=multi-user.target

Enable the new service by running sudo systemctl enable tkey-ssh-agent@USERNAME.

Add the litewitness start script (remember to give the user USERNAME execution rights) at ~/litewitness-start containing:

#!/bin/bash

~/go/bin/litewitness \
    -name tillitis.se/test-witness-1 \
    -ssh-agent //run/tkey-ssh-agent/sock \
    -db ~/litewitness.db \
    -key SHA256:qZi6Us0VIxMNqKsE7cK4LpKQa2lnR8GbRHUID7VCFGM \
    -bastion "bastion.glasklar.is:443" \
    -db ~/litewitness.db

Add a litewitness service file /lib/systemd/system/litewitness@.service containing:

# This systemd service file is a mix of:
#
# <https://github.com/FiloSottile/torchwood/blob/v0.5.0/cmd/litewitness/systemd/litewitness.service>
# <https://git.glasklar.is/sigsum/admin/ansible/-/blob/v1.3.0/roles/litewitness/templates/litewitness@.service.j2?ref_type=tags>

[Unit]
Description=Witnessing of append-only transparency logs
Requires=tkey-ssh-agent@.service
Wants=network-online.target tkey-ssh-agent@.service

[Service]
User=%i
Type=simple
StandardError=journal
ExecStart=/home/%i/litewitness-start
Restart=on-failure
RestartSec=1m

[Install]
WantedBy=multi-user.target

Run sudo systemctl enable litewitness@USERNAME

If you restart the Raspberry Pi both the tkey-ssh-agent and litewitness should now start automatically without any user intervention.

TKey in the Raspberry Pi 5 USB-C port

To be able to use the TKey in the RPi 5 USB-C port host mode needs to be enabled. Add the following to the bottom of /boot/firmware/config.txt:

[pi5]
dtoverlay=dwc2,dr_mode=host

Then reboot the Raspberry Pi.

Signing without touch

In the setup above the device app requires that you touch the TKey for every signature. This is very inconvenient for a real witness.

You can build the signer and the agent without touch requirement by following these descriptions. These descriptions require that you have native tools installed for developing TKey client apps and device apps. See the Development Handbook.

The latest release of the signer device app which supports the current version of TKey (Bellatrix) is v1.0.2, so clone and build that with the special TKEY_SIGNER_APP_NO_TOUCH variable set:

git clone -b v1.0.2 https://github.com/tillitis/tkey-device-signer.git
cd tkey-device-signer
TKEY_SIGNER_APP_NO_TOUCH=yesplease ./build.sh

Clone the tkey-ssh-agent and embed the signer/app.bin built in the step above into it.

git clone -b v1.0.0 https://github.com/tillitis/tkey-ssh-agent.git

Copy the signer to the right place and the right name:

cp tkey-device-signer/signer/app.bin signer.bin-v1.0.0 tkey-ssh-agent/cmd/tkey-ssh-agent/

Since the digest of the device app will have changed, replace the old digest:

sha512sum tkey-device-signer/signer/app.bin > tkey-ssh-agent/cmd/tkey-ssh-agent/signer.bin.sha512

Build the agent, copy it to where the package installed the binary, and restart it:

cd tkey-ssh-agent
make TKEY_SIGNER_APP_NO_TOUCH=yesplease
sudo cp tkey-ssh-agent /usr/bin/
sudo systemctl restart tkey-ssh-agent@USERNAME