Tillitis TKey

Related articles
Smartcards
Universal 2nd Factor
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
.