/
tkey-verification.1
184 lines (184 loc) · 4.81 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
.Dd $Mdocdate$
.Dt tkey-verification 1
.Os
.Sh NAME
.Nm tkey-verification
.Nd A program to sign or verify the identity of a Tillitis TKey.
.\" .Sh LIBRARY
.\" For sections 2, 3, and 9 only.
.Sh SYNOPSIS
.Nm tkey-verification remote-sign
.Op Fl -port Ar port
.Nm tkey-verification serve-signer
.Op Fl -config Ar path
.Op Fl -check-config
.Op Fl -port Ar port
.Nm tkey-verification verify
.Op Fl -base-url
.Op Fl d | -base-dir
.Op Fl -port Ar port
.Op Fl u | -show-url
.Sh DESCRIPTION
.Nm
is a program to sign or verify the identity of a Tillitis TKey.
.Pp
A typical end user will only be interested in the
.Sy verify
command.
.Pp
The commands are as follows:
.Bl -tag -width Ds
.It Ic remote-sign
.Pp
Request that the
.Nm 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:
.Bl -tag -width Ds
.It Fl -port Ar port
Path to the TKey device port. If not given, autodetection will be
attempted.
.El
.It Ic serve-signer
.Pp
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
.Sx FILES .
.Pp
Options:
.Bl -tag -width Ds
.It Fl -config Ar path
Path to the configuration file.
.It Fl -check-config
Check if the configuration file is OK and exit.
.It Fl -port Ar port
Path to the TKey device port. If not given, autodetection will be
attempted.
.El
.It Ic verify
.Pp
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:
.Bl -tag -width Ds
.It Fl -base-url Ar url
Set the base URL of verification server for fetching verification
data. Default is "https://example.com/verify".
.It Fl d | -base-dir Ar directory
Read verification data from a file located in
.Ar directory
and named after the TKey Unique Device Identifier in hex, instead of from a URL.
.It Fl -port Ar port
Path to the TKey device port. If not given, autodetection will be
attempted.
.It Fl u | -show-url
Only output the URL to the verification data that should be
downloaded, then exit.
.El
.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
.Nm
.Ic verify
.Fl -show-url
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:
.Nm
.Ic verify
.Fl d=.
to read from the current directory.
.\" .Sh CONTEXT
.\" For section 9 functions only.
.\" .Sh IMPLEMENTATION NOTES
.\" .Sh RETURN VALUES
.\" For sections 2, 3, and 9 function return values only.
.\" .Sh ENVIRONMENT
.\" For sections 1, 6, 7, and 8 only.
.Sh FILES
.Pp
.Nm
.Ic 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:
.Bl -bullet
.It
timestamp: RFC3339 UTC timestamp when the signature was done.
.It
tag: The Git tag of the signer program used on the device under verification,
.It
signature: Vendor ed25519 signature of the device public key. Stored
in hexadecimal.
.El
.Pp
The files generated will later be published on a public web server.
The publication is out of scope for the current program.
.\" .Sh EXIT STATUS
.\" For sections 1, 6, and 8 only.
.Sh EXAMPLES
.Pp
Verifying the identity of a Tillitis TKey using a networked computer.
.Bd -literal
$ tkey-verification verify
.Ed
.Pp
Verifying the identity with a non-networked computer: First
.Bd -literal
$ tkey-verification --show-url
.Ed
.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:
.Bd -literal
$ tkey-verification verify -d=.
.Ed
.Pp
.\" .Sh DIAGNOSTICS
.\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
.\" .Sh ERRORS
.\" For sections 2, 3, 4, and 9 errno settings only.
.\" .Sh SEE ALSO
.\" .Sh STANDARDS
.\" .Sh HISTORY
.Sh AUTHORS
Tillitis AB, https://tillitis.se/
.Sh CAVEATS
.Pp
You can currently not use several TKeys on the same computer at the
same time, which means you can't use
.Ic serve-signer
and the other commands on the same computer.
.\" .Sh BUGS
.Sh SECURITY CONSIDERATIONS
.Nm
only verifies the
.Sy 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
.Ic serve-signer
but is retrievable by anyone with access to the device under
verification.
.Pp
You probably shouldn't expose the computers running
.Ic serve-signer
or
.Ic remote-sign
on the Internet.