Tkey Signature tool

Description

tkey-sign – cryptographically sign and verify files with the Tillitis TKey

The tkey-sign command line tool creates and verifies cryptographic signatures. A signature verifies the integrity of a message. It uses the same signer device app as the tkey-ssh-agent and is automatically loaded onto the TKey when needed.

When the device app is loaded and running on the TKey, the status LED will indicate this with a blue color. tkey-sign also requires user input in the form of a touch when a signature is created, this is indicated with a green flashing LED. Touch the TKey’s touch sensor to confirm the creation of a signature.

This signature can be verified with tkey-sign (-V) but can also be verified using other utilities such as OpenBSD’s signify. See instructions in the usage paragraph.

Cryptography

The algorithm used by the signer is Ed25519. The Ed25519 keypair is generated automatically on the TKey but under some user control (see USS below). The public key can be exported, but the private key will never leave the TKey.

Due to bandwidth limitations of the TKey the file to be signed will be hashed with SHA-512 before it is signed, i.e. the signer will be signing the SHA-512 digest.

Anti-virus and reproducible builds

Note that some anti-virus programs, especially on Windows, can mark tkey-sign and many other Go programs as suspicious. More about this in the Go FAQ. We have attempted to be as transparent as possible and the released binaries, at least for Linux and Windows, are totally reproducible from source. We’re uncertain about macOS because it’s not a statically linked program, but that too should be reproducable, at least if you’re running the same macOS version.

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-sign_1.0.0_linux_amd64.deb
tkey-sign_1.0.0_linux_arm64.deb
tkey-sign_1.0.0_linux_amd64.apk
tkey-sign_1.0.0_linux_arm64.apk
tkey-sign_1.0.0_linux_amd64.rpm
tkey-sign_1.0.0_linux_arm64.rpm
tkey-sign_1.0.0_linux_amd64.pkg.tar.zst
tkey-sign_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-sign/releases/download/v1.0.0/tkey-sign_1.0.0_linux_amd64.deb
```

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

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

tkey-sign is now installed and accessible in your path. See usage furthest down on the page.

macOS

Download and install

We distribute tkey-sign using our own tap for Homebrew on GitHub. It is a universal macOS binary, working for both Apple Silicon (arm64) and Intel (amd64).

Hash of the binary and source code is located in this GitHub repo. As an alternative it is also possible to compile and install directly from source code.

Open a terminal and add our Homebrew tap
```
brew tap tillitis/tkey
```
Install tkey-sign
```
brew install tkey-sign
```

tkey-sign is now installed and accessible in your path. See usage furthest down on the page.

Windows

Download and install

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

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

Open PowerShell in Windows.
Install tkey-sign.
```
winget install tillitis.tkeysign
```

tkey-sign is now installed and accessible in your path. See usage furthest down on the page.

Linux / macOS / Windows

Usage

You can run

tkey-sign --help

to get the help text of the app or, on available platforms, access the man page

man tkey-sign

Creating a signature

To create a signature over a message you first have to get the public key.

tkey-sign -G -p pubkey

This will store the public key in a file named “pubkey”. If you want to use the USS, use the flags “–uss”, or “–use-file” with a corresponding file.

Remember: If you forget the USS you used, you wont be able to make more signatures with the same identity.

Create the signature by running:

tkey-sign -S -m message -p pubkey

The TKey will flash green when a touch is required by the user to performed the signature.

This will store the signature in a file named “message.sig”. If you want to use the USS, use the flags “–uss” or “–use-file” with a corresponding file (unless the app is already loaded onto the TKey).

Synopsis for creating a signature, for more details see the man page.

tkey-sign -S/--sign -m message -p/--public pubkey [-d/--port device] [-f/--force] [-s speed] [--uss] [--uss-file ussfile] [--verbose] [-x sigfile]

Verifying a signature

To verify a signature you need a the message file, a signature, and the public key. You do not need a TKey to verify a signature.

tkey-sign -V -m message -p pubkey

This will verify the signature with the expected name “message.sig”, with the public key “pubkey” over the file “message”.
If the signature is valid it will output “Signature verified” and exit with the exit code 0, otherwise stating “Error verifying: signature not valid” with a non-zero exit code.

Synopsis for verifying a signature, for more details see the man page.

tkey-sign -V/--verify -m message -p/--public pubkey [-x sigfile]

Verify signatures with signify

We provide a script called signify-verify to be able to verify signatures produced by tkey-sign with OpenBSD’s signify. The script hashes the message file so that signify is verifying the signature against the the hash digest and not the original message file.

The script is available here.

Usage:

To use signify-verify you need signify and sha512sum (or in macOS, shasum) installed, the message file, the signature and the public key form the TKey creating the signature. The signature is expected to have the name of the message file + “.sig”, e.g. “file_signed.sig”.

./signify-verify MESSAGE PUBKEY

If the verification is successful it will print “Signature verified” and exit with the exit code 0.

See the man page for more details about signify:

man signify