TKey sign-if-logged pre-release

Author: Niels Möller
Date: 2026-04-10

Last year, we started exploring Sigsum apps for the Tillitis TKey. We are now closer to the release of our first tool, sign-if-logged, and would like to solicit testing and feedback.

What is it for?

The Sigsum transparency system enables detection of unexpected or malicious use of a signing key. The owner of a signing key submits each signature made to a Sigsum log, and gets back a corresponding Sigsum proof of logging. The parties that rely on these signatures (e.g., for installing signed software updates) are expected to reject any signature that does not come with a valid proof of logging. The key owner can then monitor the log and discover all signatures made that are going to be accepted.

The sign-if-logged tool is useful if you want gain discoverability of signatures, but you are making signatures in a context where those relying on your signatures are unable to process a Sigsum proof. E.g., the signature may have to follow some standard that’s not easily extended with a Sigsum proof, or the signature have to be verified on a slow embedded systems where extended verification is impractical for performance reasons.

The sign-if-logged tool is a program running on your laptop or server. It includes an embedded TKey device app, which is loaded into your attached TKey device. The tool configures the TKey and the device app so that the device signing key can be used only to sign data that is already Sigsum logged. Then you get key usage transparency: anything properly signed by this key is discoverable via the Sigsum log.

+-------------------------+                  +----------------+
| Host PC                 |   /dev/ttyACM0   | TKey           |
|                         | <--------------> |                |
| sign-if-logged          |       USB        | device app     |
+-------------------------+                  |   +------------+
  ^ ^                 | |                    |   |derived     |
  | |                 | |                    |   |signing key |
  | policy            | v                    +---+------------+
  | submit pubkey(s)  v signing pubkey
  proof of logging    signature

Figure 1: Host program and the device app, communicating over USB.
The host program, `sign-if-logged`, loads the device app into the
TKey device, and configures it with the desired policy and submit
pubkey(s). The device derives a signing key bound to the
configuration, and that signing key stays on the device. The host
program can now retrieve the corresponding public key. Next, the
host can ask the device to sign messages, but the device agrees to
sign a message only if the host also presents a proof that the
message has been Sigsum logged according to the configured policy.

How to use it?

It is a two stage process to sign your own artifacts using sign-if-logged.

First, you sign the artifact using a submit key, and submit the signature to a Sigsum log. A monitor can examine the log and look for signatures by the submit key, thus making all signed artifacts discoverable. Note that the process and tools so far are exactly the same as if you expect the users of your artifacts to enforce transparency logging by verifying the Sigsum proofs themselves.

Next, use the sign-if-logged tool to pass the artifact together with the Sigsum proof from the first step to the TKey device for signing. The TKey uses a signing key that is internal to the device, and tied to the trust policy used for verifying the Sigsum proof.

To run through the below example, you need both the Sigsum command line tools and sign-if-logged. They can be installed using:

go install sigsum.org/sigsum-go/cmd/sigsum-key@v0.13.1
go install sigsum.org/sigsum-go/cmd/sigsum-submit@v0.13.1
go install sigsum.org/sign-if-logged/cmd/sign-if-logged@v0.1.0

First stage: Sigsum submission

  1. Prepare the file you want to sign.

    echo "This is the file" > file.txt

  2. Generate a keypair to be used for submitting to a Sigsum log.

    sigsum-key generate -o submit-key

  3. Submit the file to a Sigsum log. Here we use a builtin test policy named sigsum-test-2025-3.

    sigsum-submit -k submit-key -P sigsum-test-2025-3 file.txt

    On success, a file file.txt.proof is created.

When using sign-if-logged, you need to decide on which policy and which submitter keys you are going to use. This is because any change in submitter keys or policy implies a change of the signing key used by the TKey (we’ll get back to key derivation later). If several people should be able to sign and submit, each with their own key, you want to generate all those keys up front (and maybe a few spares stored in your safe, depending on how difficult a key update will be).

Second stage: TKey signing

  1. Insert a TKey.

  2. Start the device app and configure it with a policy, a submitter key file, and the desired signature type.

    sign-if-logged init -t ecdsa256 --ssh -k submit-key.pub -P sigsum-test-2025-3

    In this case, we use the same test policy as in the submission step above. We use a submit-key.pub file with only a single key. We ask for OpenSSH-style signatures (default namespace is “file”). Also by default, physical presence will be required for signing, via the TKey’s touch sensor.

    The device generates a secret signing key, and that key is cryptographically tied to the configuration you just passed in. The TKey can be reconfigured with any other policy or a different list of authorized submitter keys at a later time, but any changes will result in a different signing key.

  3. Extract the resulting public key.

    sign-if-logged pubkey -o sign-key.pub

    Since we specified OpenSSH signatures (with the --ssh option in the previous step), we get a public key file in OpenSSH format, ecdsa-sha2-nistp256 <base64 blob>.

  4. Request a signature. Both the SHA256 hash of the file to be signed and the corresponding .proof file are sent to the device.

    sign-if-logged sign -o file.txt.sig file.txt

    This command can be repeated with additional files and corresponding proofs. Verifying the Sigsum proof is rather slow (20s or more, depending on number of cosignatures), have patience. Since we didn’t pass the --no-touch option during configuration, the TKey will blink and require a touch before signing anything.

  5. Finally, the signature can be verified using the OpenSSH tools. To do this, we need an allowed_signers file, as documented in the ssh-keygen man page. We can create such a file from the public key file using

    echo "user@example.org namespaces=\"file\" $(cut -d' ' -f1-2 sign-key.pub)" >allowed-signers

    and use that file for verifying the signature like

    ssh-keygen -Y verify -f allowed-signers -I user@example.org -n file -s file.txt.sig < file.txt

    If all goes well, ssh-keygen displays a message Good "file" signature for user@example.org with ECDSA key SHA256:<fingerprint>, meaning that it found a valid signature with the right namespace and a public key belonging to user@example.org.

Features

The sign-if-logged tool can sign data using either Ed25519 or ECDSA using the NISTP256 curve. It can be configured to provide either raw signatures, or OpenSSH signatures under a given namespace. Signing can also be configured with or without requirement for physical presence.

The tool comes with an embedded TKey device app which is built reproducibly, and supports both the current “Bellatrix” version of the TKey, and the upcoming version “Castor”.

Note on hashing: The checksum that ends up in the Sigsum log is the double SHA256 hash of the file to be signed. We have msg = SHA256(file) and checksum = SHA256(msg). If we use an OpenSSH signature type, or raw ECDSA signatures, the first hash, msg, is sufficient for the signing operations, as well as for the verification of the Sigsum proof, so only the hash is sent to the device. But for a raw Ed25519 signature, the hash is not sufficient, and the complete file has to be sent to the TKey device, limiting the size of the file to a few KiB.

Key derivation

Like all TKey device apps, the device firmware provides our device app with a secret key derived using measured boot. This is done when the app is loaded by the firmware but before it starts execution. The inputs to key derivation at the firmware stage are the TKey’s unique device secret, the hash of the app binary being loaded, and an optional user password. But the sign-if-logged device app does not use this secret as a signing key directly.

After the device app is loaded it must be configured. When you run the sign-if-logged init command on the host computer, it tells the device app:

All this configuration is measured by the device app, and goes into key derivation, together with the secret provided by the firmware. This means that any change to the configuration will result in a different signing key. And like for any TKey app, any modification to the device app binary, or change of TKey device used, also results in a different signing key.

Concluding remarks

We’ve tried to keep the scope down in favor of getting a first release out the door. Any input on how the current pre-release is working (or not working) would be helpful. Similarly, if you have ideas about what you’d like to see added in the future, then such input would be much appreciated. Below are a few improvement ideas that we’ve thought of so far.