tkey-verification.1

.\" Generated by scdoc 1.11.3
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "tkey-verification" "1" "2024-07-03"
.PP
.SH NAME
.PP
A program to sign or verify the identity of a Tillitis TKey.\&
.PP
.SH SYNOPSIS
.PP
\fBtkey-verification\fR -h/--help
.PP
\fBtkey-verification\fR remote-sign [--port port] [--speed speed]
.PP
\fBtkey-verification\fR serve-signer [--config path] [--check-config] [--port
port] [--speed speed]
.PP
\fBtkey-verification\fR show-pubkey [--port port] [--speed speed]
.PP
\fBtkey-verification\fR verify [--base-url url] [-d | --base-dir] [--port
port] [-u | --show-url] [--speed speed]
.PP
.SH DESCRIPTION
.PP
\fBtkey-verification\fR is a program to sign or verify the identity of a
Tillitis TKey.\&
.PP
A typical end user will only be interested in the \fBverify\fR command.\&
.PP
The commands are as follows:
.PP
\fBremote-sign\fR
.PP
.RS 4
Request that the tkey-verification serve-signer sign the identity
of a TKey.\&
.PP
To use, first insert a TKey and then run the command.\& If one is
already running a TKey program, remove it and re-insert before
running the command.\&
.PP
Options:
.PP
\fB--port\fR port
.PP
.RS 4
Path to the TKey device port.\& If not given, autodetection will be
attempted.\&
.PP
.RE
\fB--speed\fR speed
.PP
.RS 4
Speed in bit/s of the TKey device port.\&
.PP
.RE
.RE
\fBserve-signer\fR
.PP
.RS 4
Provide a signing server with its own TKey, the vendor key.\&
.PP
When it receives a signing request it signs the data and creates a new
file with metadata and a signature.\& See FILES.\&
.PP
Options:
.PP
\fB--config\fR path
.PP
.RS 4
Path to the configuration file.\&
.PP
.RE
\fB--check-config\fR
.PP
.RS 4
Check if the configuration file is OK and exit.\&
.PP
.RE
\fB--port\fR port
.PP
.RS 4
Path to the TKey device port.\& If not given, autodetection will be
attempted.\&
.PP
.RE
\fB--speed\fR speed
.PP
.RS 4
Speed in bit/s of the TKey device port.\&
.PP
.RE
.RE
\fBshow-pubkey\fR
.PP
.RS 4
Output public key data to populate "vendor-signing-pubkeys.\&txt"
for building into \fBtkey-verification\fR to be able to use some other
commands.\& This is necessary in order to bootstrap \fBtkey-verification\fR
from scratch or to add another vendor signing key.\&
.PP
The output includes public key, app tag, and app hash in the
right format for the file.\&
.PP
Use the \fB--app\fR to specify the path of the app to load.\&
.PP
Options:
.PP
\fB--app\fR path
.PP
.RS 4
Load app in \fBpath\fR into TKey.\&
.PP
.RE
\fB--port\fR port
.PP
.RS 4
Path to the TKey device port.\& If not given, autodetection will be
attempted.\&
.PP
.RE
\fB--speed\fR speed
.PP
.RS 4
Speed in bit/s of the TKey device port.\&
.PP
.RE
.RE
\fBverify\fR
.PP
.RS 4
Verify a TKey identity.\&
.PP
To use, first insert a TKey and then run the command.\& If one is
already running a TKey program, remove it and re-insert before running
the command.\&
.PP
Options:
.PP
\fB--base-url\fR url
.PP
.RS 4
Set the base URL of verification server for fetching verification
data.\& Default is "https://example.\&com/verify".\&
.PP
.RE
\fB-d\fR | \fB--base-dir\fR directory
.PP
.RS 4
Read verification data from a file located in directory
and named after the TKey Unique Device Identifier in hex, instead of
from a URL.\&
.PP
.RE
\fB--port\fR port
.PP
.RS 4
Path to the TKey device port.\& If not given, autodetection will be
attempted.\&
.PP
.RE
\fB-u\fR | \fB--show-url\fR
.PP
.RS 4
Only output the URL to the verification data that should be
downloaded, then exit.\&
.PP
.RE
\fB--speed\fR speed
.PP
.RS 4
Speed in bit/s of the TKey device port.\&
.PP
.RE
.RE
.SS Verification on a machine without network
.PP
If you'\&re on a machine without network and need to verify a TKey you
can run
.PP
.nf
.RS 4
$ tkey-verification verify ---show-url
.fi
.RE
.PP
which will output the URL to the verification file.\& Download the file
using another, networked, computer and somehow bring the file or type
it in again on your airgapped computer.\& Then run:
.PP
.nf
.RS 4
tkey-verification verify -d=\&.
.fi
.RE
.PP
to read from the current directory.\&
.PP
.SH FILES
.PP
\fBtkey-verification\fR serve-signer produces a file which is named after
the Unique Device Identifier (in hexadecimal) for every signature
made.\& An example filename would be "signatures/0133704100000015".\&
.PP
The file contains:
.PP
.PD 0
.IP \(bu 4
timestamp: RFC3339 UTC timestamp when the signature was done.\&
.IP \(bu 4
tag: The Git tag of the signer program used on the device under
verification,
.IP \(bu 4
signature: Vendor ed25519 signature of the device public key.\& Stored
in hexadecimal.\&
.PD
.PP
The files generated will later be published on a public web server.\&
The publication is out of scope for the current program.\&
.PP
\fBtkey-verification\fR show-pubkey generates output for a file called
"vendor-signing-pubkeys.\&txt" to be included in the build of a new
\fBtkey-verification\fR.\& It'\&s output is:
.PP
.PD 0
.IP \(bu 4
Ed25519 public key
.IP \(bu 4
app name and tag.\&
.IP \(bu 4
digest of hash
.PD
.PP
Example file:
.PP
.nf
.RS 4
038dd0b898c601517a09cd249d3c4f2de8e9aab38c5fa02701ae29bb41a6d863 verisigner-v0\&.0\&.1 9598910ec9ebe2504a5f894de6f8e0677dc94c156c7bd6f7e805a35354b3c85daa4ca66ab93f4d75221b501def457b4cafc933c6cdcf16d1eb8ccba6cccf6630
.fi
.RE
.PP
.SH EXAMPLES
.PP
Verifying the identity of a Tillitis TKey using a networked computer.\&
.PP
.nf
.RS 4
$ tkey-verification verify
TKey UDI: 0x0133708100000002(BE) VendorID: 0x1337 ProductID: 2 ProductRev: 1
TKey is genuine!
.fi
.RE
.PP
Verifying the identity with a non-networked computer: First
.PP
.nf
.RS 4
$ tkey-verification --show-url
.fi
.RE
.PP
Then download the file and move it to your current working directory.\&
Keep the name of the file intact since it'\&s named after the TKey
Unique Device Identifier.\& and run:
.PP
.nf
.RS 4
$ tkey-verification verify -d=\&.
TKey UDI: 0x0133708100000002(BE) VendorID: 0x1337 ProductID: 2 ProductRev: 1
Reading verification data from file \&./0133708100000002 \&.\&.\&.
TKey is genuine!
.fi
.RE
.PP
In order to include a new vendor signing key, use:
.PP
.nf
.RS 4
% \&./tkey-verification show-pubkey --port /dev/pts/12 --app cmd/tkey-verification/bins/signer-v1\&.0\&.0\&.bin
Connecting to device on serial port /dev/pts/12 \&.\&.\&.
Firmware name0:\&'tk1 \&' name1:\&'mkdf\&' version:5
Public Key, app tag, and app hash for vendor-signing-pubkeys\&.txt follows on stdout:
038dd0b898c601517a09cd249d3c4f2de8e9aab38c5fa02701ae29bb41a6d863 verisigner-v0\&.0\&.1 9598910ec9ebe2504a5f894de6f8e0677dc94c156c7bd6f7e805a35354b3c85daa4ca66ab93f4d75221b501def457b4cafc933c6cdcf16d1eb8ccba6cccf6630
.fi
.RE
.PP
.SH AUTHORS
.PP
Tillitis AB, https://tillitis.\&se/
.PP
.SH CAVEATS
.PP
You can currently not use several TKeys on the same computer at the
same time, which means you can'\&t use \fBserve-signer\fR and the other
commands on the same computer.\&
.PP
.SH SECURITY CONSIDERATIONS
.PP
\fBtkey-verification\fR only verifies the /identity/ of the TKey hasn'\&t
changed since signing by the vendor.\& It might have been manipulated in
other ways.\&
.PP
The device public key isn'\&t published in the files generated by the
\fBserve-signer\fR but is retrievable by anyone with access to the device
under verification.\&
.PP
You probably shouldn'\&t expose the computers running \fBserve-signer\fR or
\fBremote-sign\fR on the Internet.\&