Tillitis TKey

The TKey is an Open-source hardware and open source software USB security key that can support use cases such as SSH login, Ed25519 digital signing, Root of Trust, FIDO2, and more. The software, and board designs, FPGA verilog and firmware for the TKey are released by Tillitis.

The threat model, such as assumptions on trust and attack vectors, for the TKey is specified by Tillitis.

As the TKey has no persistent storage its output are calculated from any input and a unique device secret (UDS), see Tillitis TKey Developer Handbook. Every time the TKey is plugged into the computer a device app has to be loaded onto it. When the device app is loaded, the TKey calculates a Compound Device Identifier (CDI) based on a hash of the device app binary code, the UDS and possibly a User Supplied Secret (USS). The CDI is then available for use by the device app, for example to derive a private key from.

Warning: If the code of the device app changes, also the CDI will change. This cuts your access to any account for which you used the TKey with this particular device app. For example, if you use TKey for ssh with tkey-ssh-agent version 41 and you upgrade to tkey-ssh-agent version 42 (in which the device app changed) you end up locked out of your ssh accounts. The package version should be backed-up and prevented from upgrades, see Pacman#Skip package from being upgraded.

First usage

The TKey identifies with the device signature:

$ lsusb | grep Tillitis

Bus 008 Device 001: ID 1207:8887 Tillitis MTA1-USB-V1

and is accessible at a serial port like /dev/ttyACM0. To use the TKey, add yourself to the uucp user group.

It is preferred to use a udev rule for the vendor 1207 and the product 8887 instead that makes the device writable for a user.

Verification with tkey-verification

To test if the device is properly set-up, it is recommended to run the vendor provided tkey-verification program, packaged in tkey-verification-bin^AUR. Apart from a functionality check of the TKey, the software also verifies that the TKey contains the same firmware as at the time of production so the firmware on the TKey has not been altered.

$ tkey-verification verify

...
TKey is genuine!

Applications

This section describes usage of some available tools.

tkey-ssh-agent

The TKey may authenticate SSH agent requests with tkey-ssh-agent^AUR. To print its public ssh key:

$ tkey-ssh-agent --show-pubkey

An additional user supplied secret (USS) can be provided either with --uss (requiring a pinentry program) or with --uss-file command-line arguments to tkey-ssh-agent. The USS determines the ssh public key, that means providing a different USS will output a different key. If, for instance, the USS that was used to generate a public ssh key is --uss "arch, btw", this USS shall be typed into the pinentry prompt when authenticating to the server that uses this public key.

To start the ssh agent:

$ tkey-ssh-agent --agent-socket $XDG_RUNTIME_DIR/tkey_ssh_agent.sock

Use both tkey-ssh-agent and ssh-agent

Openssh can be configured (see ssh_config(5)) to authenticate only some connections with tkey-ssh-agent and default to ssh-agent for other ssh connections. To use the TKey to authenticate a connection to a certain host set the ssh configuration option IdentityAgent to the socket path of the tkey-ssh-agent:

~/.ssh/config

Host aur.archlinux.org
  User aur
  IdentityAgent /run/user/1000/tkey-ssh-agent/sock

The above example would ask to authenticate to aur.archlinux.org with the TKey, assuming its --agent-socket is the above configured IdentityAgent path.

If tkey-ssh-agent is started/managed with the tkey-ssh-agent.service (provided as part of the tkey-ssh-agent^AUR package) as a Systemd/User unit, then the socket path is the value of $XDG_RUNTIME_DIR/tkey-ssh-agent/sock.