-
Notifications
You must be signed in to change notification settings - Fork 2
/
tkey-verification.1
313 lines (313 loc) · 7.29 KB
/
tkey-verification.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
.\" 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.\&