TKey Device Verification

Description

The TKey Device Verification application is a program that verifies the TKey you have in your hand is genuine. A genuine TKey is produced by Tillitis and contains the exact same firmware and hardware secret (UDS) as when it was produced.

It is recommended that you verify your TKey before first use. You may also repeat the verification later.

Follow the below instructions for how to perform verification on different Operating Systems (OS). Note that you can verify your TKey on one computer/OS and use it on another. The verification is for your TKey, not your computer.

How it works

During provisioning of a TKey, Tillitis creates a signature of a message, this message consists of data only producible by this specific TKey being produced. The signature, along with some metadata, is published.

With the help of this metadata and your TKey, the message can be reproduced and the signature over this message can be verified.

If the verification is successful, this implies that the TKey was in fact provisioned by Tillitis and has not been manipulated with. TKey Device Verification automates this process, so you simply have to run one command to verify your TKey.

For more details regarding the process, see the Github repo.

Installation and usage: Linux →
Installation and usage: macOS →
Installation and usage: Windows →

Installation and usage

Linux

Download and install

We provide multiple types of packages for Linux, such as Debian, RPM, Arch, and Alpine. These are available for both amd64 and arm64. The app is statically linked.

If you need a different package or architecture, it is always an alternative to compile and install directly from source code. You will find the source code at our GitHub repository.

Below instructions are for a Debian package for amd64, but can be applied for each of these packages:

tkey-verification_1.0.0_linux_amd64.deb
tkey-verification_1.0.0_linux_arm64.deb
tkey-verification_1.0.0_linux_amd64.apk
tkey-verification_1.0.0_linux_arm64.apk
tkey-verification_1.0.0_linux_amd64.rpm
tkey-verification_1.0.0_linux_arm64.rpm
tkey-verification_1.0.0_linux_amd64.pkg.tar.zst
tkey-verification_1.0.0_linux_arm64.pkg.tar.zst

Open a terminal and download the package, for example the Debian amd64 version. Change the link to the appropriate package for your system
```
wget https://github.com/tillitis/tkey-verification/releases/download/v1.0.0/tkey-verification_1.0.0_linux_amd64.deb
```

Install tkey-sign by using the command appropriate for your package manager. For example

dpkg -i tkey-verification_1.0.0_linux_amd64.deb
apk add --allow-untrusted tkey-verification_1.0.0_linux_amd64.apk
rpm -ivh tkey-verification_1.0.0_linux_amd64.rpm
pacman -U tkey-verification_1.0.0_linux_amd64.pkg.tar.zst

tkey-verification is now installed and accessible in your path.

Usage

Plug in your TKey to your computer and execute this command in a terminal:

tkey-verification verify

After processing the data and communicating with your TKey, expect a final message saying

TKey is genuine!

If tkey-verification does not return “TKey is genuine!”, see Possible errors furthest down on the page.

The program requires Internet connectivity to download the verification data. It is possible to get this data downloaded on another system, and transfer it to where you want to run the verification. Execute either of these two commands for more help and other usage.

tkey-verification --help
man tkey-verification

macOS

Install

We distribute Tkey Device Verification using our own tap for Homebrew on GitHub.

Hash of the binary and source code is located in this GitHub repo. The published binaries can be reproduced.

Open a terminal and start by adding our Homebrew tap

brew tap tillitis/tkey

then install tkey-verification

brew install tkey-verification

tkey-verification is now installed and accessible in your path.

Usage

Plug in your TKey to your computer. Now you can run the verification like:

tkey-verification verify

After processing the data and communicating with your TKey, expect a final message saying

TKey is genuine!

If tkey-verification does not return “TKey is genuine!”, see Possible errors furthest down on the page.

tkey-verification --help
man tkey-verification

Windows

Install

We distribute our officially supported package for Windows through winget, so make sure to have winget and PowerShell installed before proceeding.

As an alternative, you may download the tkey-verification binary from our GitHub repository,or compile from source code.

Open PowerShell in Windows.

Install tkey-sign.

winget install tillitis.tkeyverification

Usage

Plug in your TKey to your computer. Now you can run the verification like:

tkey-verification verify

After processing the data and communicating with your TKey, expect a final message saying

TKey is genuine!

If tkey-verification does not return “TKey is genuine!”, see Possible errors furthest down on the page.

tkey-verification --help

Possible errors during verification

This section will focus on possible errors that can occur during verification of a TKey (command: tkey-verification verify).

tkey-verification can produce various errors, most of them are self explanatory, but some of them will be elaborated on here.

First, remember that it is only possible to verify your TKey using this tool if the TKey is produced and provisioned by Tillitis. This means a TKey provisioned by your IT department, or a TKey Unlocked provisioned by yourself is not possible to verify with Tillitis released version of tkey-verification.

These “VERIFICATION FAILED” can be a sign of that someone has been tampering or swapped your TKey and/or the version of tkey-verification you are using. Since TKey is a security product, it is important to be able to verify and trust the TKey you are using.

Verification errors:

VERIFICATION FAILED: unexpected firmware

If you receive this error it means that the digest of the firmware reported by the signer app, is not the same as during provisioning. This can be an indication of that someone has swapped your TKey running a different firmware.

VERIFICATION FAILED: vendor signature not verified

If you receive this error it means that the vendor signature produced during provisioning cannot be verified over the recreated message. This can occur due to:

1. 1. Your TKey has been manipulated with, the signer app, firmware and/or hardware is not identical to when it was provisioned by Tillitis.
  2. You happened to be using the exact same UDI as another TKey. This can happen if you have yourself provisioned a TKey Unlocked and happen to chose a UDI already used. Your TKey is not supported to be verified using this tool, only TKeys provisioned by Tillitis.

VERIFICATION FAILED: challenge not verified

If you receive this error it means that your TKey was not able to produce a valid signature, verifiable by the public key it claims it has. This can occur if the corresponding private key, to the public key, is not available on the TKey, in other words the signer app loaded onto the TKey is not the same.

Other errors:

tkey-verification can produce other errors, these are caused by circumstance, like failed HTTP requests or similar.

I/O FAILED

Describes an I/O failure of some kind, perhaps between the client and the TKey, an HTTP request that didn’t succeed, or perhaps reading a file.

PARSE ERROR

Describes an error where we have tried to parse something from external sources but failed.

MISSING IN PROGRAM:

Describes an error where something is missing from the binary to even complete a verification.

NOT FOUND

Describes an error where we with data from external source can’t find something, perhaps not finding something on a web server, or not finding the device app digest.