« back to all changes in this revision
Viewing changes to man/rabbitsign.1
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Bazaar Package Importer
- Author(s): Krzysztof Burghardt
- Date: 2009-10-21 23:02:36 UTC
- Revision ID: james.westby@ubuntu.com-20091021230236-y2gj8x2vu4fb6xqo
Tags: upstream-2.1+dmca1
Import upstream version 2.1+dmca1
- files added:
- man
- src
- test
added
removed
man/rabbitsign.1
1
'\" e
2
.TH rabbitsign 1 "July 2009" "RabbitSign 2.0"
3
.if t \{
4
.EQ
5
delim $$
6
.EN
7
\}
8
.SH NAME
9
rabbitsign \- sign applications for TI graphing calculators
10
.SH SYNOPSIS
11
\fBrabbitsign\fR [ \fIoptions\fR ] [ \fB-o \fIappfile\fR ]
12
[ \fB-k \fIkeyfile\fR ] \fIhexfile\fR ...
13
14
\fBrabbitsign\fR [ \fIoptions\fR ] [ \fB-k \fIkeyfile\fR ]
15
\fB-c\fR \fIhexfile\fR ...
16
17
.SH DESCRIPTION
18
\fBrabbitsign\fR is an implementation of Texas Instruments' Rabin and
19
RSA signing algorithms, as used on the TI-73, TI-83 Plus, TI-84 Plus,
20
TI-89, and TI-92 Plus graphing calculators. These algorithms are used
21
to sign Flash applications and operating systems so that the
22
calculator can recognize them as valid.
23
24
\fBrabbitsign\fR, like Texas Instruments' official signing programs,
25
needs a private key (a pair of large prime numbers) to sign apps. In
26
order for the app to be accepted, the corresponding public key (their
27
product) must be present on the calculator. As of this writing, the
28
``shareware'' private key number 0104, used for signing applications
29
for the TI-83 Plus and TI-84 Plus, is available through TI's SDK.
30
Unfortunately, the OS signing keys, as well as the app signing keys
31
for the TI-73, TI-89, and TI-92 Plus, have not been released, which
32
means that only TI can sign apps and OSes for those calculators.
33
34
.SS OPTIONS
35
.TP
36
\fB-a\fR
37
Attempt to match the output of Peter-Martijn Kuipers' \fBappsign\fR
38
program, for testing purposes. The resulting output file will have
39
Unix-style line termination, and hence will not be compatible with all
40
programs. This option is not recommended for ordinary use.
41
.TP
42
\fB-b\fR
43
Assume input files are raw binary files. If this option is not given,
44
the file type is detected automatically.
45
.TP
46
\fB-c\fR
47
Do not sign apps; instead, check that the signatures of the specified
48
apps are valid. Exit status is 0 if all apps are valid, 1 if one or
49
more apps fail, or 2 if there is a non-mathematical error.
50
.TP
51
\fB-f\fR
52
Ignore non-fatal errors, and force the application to be signed if
53
possible. (All of these messages are there for a reason, though, and
54
chances are that if your app generates any of them, it will also
55
either fail validation or crash the calculator. You have been
56
warned.)
57
.TP
58
\fB-g\fR
59
Write the output file in GraphLink ``TIFL'' format. (By default and
60
for historical reasons, apps and OSes for the TI-73 and TI-83 Plus are
61
written in plain TI Hex format instead; you can use \fBpackxxk\fR(1)
62
to convert these files into TIFL format.) Apps and OSes for the TI-89
63
and TI-92 Plus are always written in TIFL format. See \fBAPPLICATION
64
FILE FORMATS\fR below for more information.
65
.TP
66
\fB-k\fR \fIkeyfile\fR
67
Read signing and/or validation keys from the given file. This file
68
must be in one of the formats used by TI's SDK tools. (See \fBKEY
69
FILE FORMATS\fR below.) By default, \fBrabbitsign\fR searches for the
70
key named in the app header (for example, 0104.key for ``shareware''
71
TI-83 Plus apps.)
72
.TP
73
\fB-K\fR \fIid\fR
74
Search for the key with the given \fIid\fR (a small hexadecimal
75
number) rather than the ID specified in the app header.
76
.TP
77
\fB-n\fR
78
Attempt to sign the program as-is, without modifying the header.
79
(This option may not produce a file that the calculator will actually
80
accept; it is intended for testing and special-purpose signatures, not
81
for ordinary app signing.)
82
.TP
83
\fB-o\fR \fIoutfile\fR
84
Specify the output file. By default, output files are named by taking
85
the name of the input file, removing any suffix, and adding a `.app'
86
or `.8xk' suffix depending on whether \fB-g\fR is specified. (If the
87
input file already has a `.app' or `.8xk' suffix, `-signed' is
88
inserted, so `myapp.8xk' becomes `myapp-signed.8xk'.)
89
90
If `-' is specified as an input file, that indicates the
91
standard input, and the signed result is written by default to the
92
standard output.
93
.TP
94
\fB-p\fR
95
Fix the app pages header. This is not done by default because an
96
incorrect pages header is generally a sign of a much more serious
97
problem.
98
.TP
99
\fB-P\fR
100
If the application ends close to a page boundary, add an additional
101
page to hold the signature. (Application signatures on the TI-73 and
102
TI-83 Plus are not allowed to span a page boundary.) Keep in mind
103
that this is extremely wasteful, as it consumes 16384 bytes of Flash
104
to hold approximately 69 bytes of data; if your application is in this
105
situation, you should consider trying to reduce its size slightly, or
106
alternatively, adding more data to take advantage of the extra Flash
107
page.
108
.TP
109
\fB-q\fR
110
Do not print non-fatal warning messages.
111
.TP
112
\fB-r\fR
113
Re-sign a previously signed app (i.e., discard the previous signature
114
before signing.)
115
.TP
116
\fB-R\fR \fIn\fR
117
For signing TI-73 and TI-83 Plus applications, use root number \fIn\fR
118
.if t ($0 <= n <= 3$)
119
.if !t (0 \(<= \fIn\fR \(<= 3)
120
rather than the default, root number 0. All four roots are valid,
121
though distinct, signatures, so this option is mainly for debugging.
122
123
Root 0 is computed so as to be congruent to
124
.if t $m sup {left ( {p+1} over 4 right )}$ modulo \fIp\fR and
125
.if t $m sup {left ( {q+1} over 4 right )}$ modulo \fIq\fR.
126
.if !t \fIm\fR^[(\fIp\fR+1)/4] modulo \fIp\fR and
127
.if !t \fIm\fR^[(\fIq\fR+1)/4] modulo \fIq\fR.
128
Root 1 is the negation of root 0 modulo \fIp\fR, root 2 the negation
129
modulo \fIq\fR, and root 3 the negation both modulo \fIp\fR and modulo
130
\fIq\fR.
131
132
This option has no effect when signing OSes or TI-89/92 Plus
133
applications, which use the RSA algorithm rather than Rabin.
134
.TP
135
\fB-t\fR \fItype\fR
136
Explicitly specify the type of program (e.g., `8xk' for a TI-83 Plus
137
application, or `73u' for a TI-73 operating system.) The default
138
behavior is to infer the program type from the name of the input file.
139
(If the input file does not have a recognized suffix, the type is
140
guessed based on the contents of the program header.)
141
.TP
142
\fB-u\fR
143
Disable automatic page detection, and assume input files are unsorted.
144
This means that page boundaries must be defined explicitly. (See
145
\fBAPPLICATION FILE FORMATS\fR below.) This option has no effect in
146
binary (\fB-b\fR) mode.
147
.TP
148
\fB-v\fR
149
Be verbose; print out the names of apps and their signatures as they
150
are signed. Use \fB-vv\fR for more detailed information about the
151
computation.
152
.TP
153
\fB--help\fR
154
Print out a summary of options.
155
.TP
156
\fB--version\fR
157
Print out version information.
158
159
.SH APPLICATION FILE FORMATS
160
.SS Intel Hex
161
Intel hex is a standard ASCII file format used by many PROM
162
programmers, and a common assembler output format. Each line (or
163
``record'') consists of the following:
164
165
:\fINNAAAATTDDDDDD...CC\fR
166
.TP
167
:
168
The first character of the line is a colon; this is just used to
169
identify the format.
170
.TP
171
\fINN\fR
172
The next two characters are the number of data bytes on this line,
173
written in uppercase ASCII hexadecimal.
174
.TP
175
\fIAAAA\fR
176
The next four digits are the address of the data on this line.
177
\fBrabbitsign\fR only looks at the low 14 bits of this value.
178
.TP
179
\fITT\fR
180
These two digits identify the ``type'' of the record. Intel hex
181
defines several record types for various addressing models; the only
182
types which are meaningful for TI calculators are types 00 (ordinary
183
data) and 01 (end of file.)
184
.TP
185
\fIDD...\fR
186
2*\fINN\fR hex digits follow, the actual data.
187
.TP
188
\fICC\fR
189
Finally, the inverted checksum is added, so that adding up all the
190
bytes on the line gives a total of zero modulo 256. (As an extension,
191
\fBrabbitsign\fR permits you to use two uppercase `X's in place of a
192
checksum.)
193
.PP
194
Since the address is only 16 bits, this format cannot unambiguously
195
represent applications larger than 64 kilobytes. To enable multi-page
196
applications to be created, \fBrabbitsign\fR attempts to detect page
197
boundaries automatically, starting a new page for each field with a
198
zero address. Thus to create a multi-page app, you can simply
199
concatenate several Intel Hex files, e.g.
200
.IP
201
cat page0.hex page1.hex | rabbitsign - -o complete.app
202
.PP
203
This will only work if the records are correctly sorted within each
204
page. (If the assembler does not generate records in order, you can
205
sort the fields yourself using a command such as `sort -k1.8,1.9
206
-k1.4,1.7'.)
207
208
To turn off this automatic page detection, use the \fB-u\fR option.
209
In this case, you must define page boundaries explicitly using the TI
210
Hex format.
211
212
.SS TI Hex
213
``TI'' hex is an extension to Intel hex which provides unambiguous
214
representation of multi-page apps. It adds records of the form
215
216
:0200000200\fINNCC\fR
217
218
which indicate that subsequent data is placed on relative page number
219
\fINN\fR. (Keep in mind that the TI-83 and 84 Plus install
220
applications ``backwards,'' so if relative page 0 is stored on
221
absolute page 69, relative page 1 will be stored on absolute page 68,
222
and so forth.)
223
224
Some assemblers can generate multi-page data using type 4 records
225
instead of type 2; \fBrabbitsign\fR treats these as equivalent to type
226
2.
227
228
For compatibility with other software which makes certain assumptions
229
about the format, \fBrabbitsign\fR will write 32 bytes per line, and
230
will end lines with a DOS-style carriage return and line feed.
231
232
.SS GraphLink TIFL
233
The standard (newer) GraphLink format consists of a 78-byte binary
234
header which is added to the start of a hex or binary file. The
235
contents of this header are as follows:
236
237
.TP
238
0x00-07
239
The string `**TIFL**'.
240
.TP
241
0x08
242
The major version number (``App ID'') of the application.
243
.TP
244
0x09
245
The minor version number (``App Build'') of the application.
246
.TP
247
0x0A
248
Flags; apparently intended to indicate whether the contents of the
249
file are binary (0) or TI Hex (1). This value is not, however, set
250
consistently by other software.
251
.TP
252
0x0B
253
``Object Type'' field; apparently indicates something about the type
254
of data. Set to 0x88 in most TI-73 and TI-83 Plus files; set to 0 in
255
TI-89 and TI-92 Plus files.
256
.TP
257
0x0C-0F
258
Binary-coded decimal month (one byte), day (one byte), and year (two
259
bytes, big endian) when the app was signed.
260
.TP
261
0x10
262
Length of the app's name.
263
.TP
264
0x11-18
265
Name of the app.
266
.TP
267
0x19-2F
268
Reserved, always set to zero.
269
.TP
270
0x30
271
Calculator type (0x73 = TI-83 Plus, 0x74 = TI-73, 0x88 = TI-92 Plus,
272
0x98 = TI-89.)
273
.TP
274
0x31
275
Type of data (0x23 = OS upgrade, 0x24 = application, 0x25 = certificate.)
276
.TP
277
0x32-49
278
Reserved, always set to zero.
279
.TP
280
0x4A-4D
281
Little endian length of the following data (the length of the hex
282
file, not the on-calculator size of the application.)
283
.PP
284
There also exist multi-part TIFL files, which simply consist of two or
285
more TIFL files concatentated together. (For instance, a software
286
license agreement or a certificate file can be attached to an
287
application.) \fBrabbitsign\fR handles these files in a limited way:
288
it will read only the first section with a recognized data type,
289
ignoring any other data in the file. \fBrabbitsign\fR cannot create
290
multi-part TIFL files, but they can be created using \fBpackxxk\fR(1)
291
(or simply using \fBcat\fR(1).)
292
293
.SS Binary
294
\fBrabbitsign\fR can also read binary app files; they are assumed to
295
be contiguous, so when signing a multi-page app, each page except the
296
last must be filled to a full 16k.
297
298
.SH KEY FILE FORMATS
299
Key files contain the data needed for signing and validating
300
applications. (The portion of the key file used for validating is
301
known as the ``public'' key; the portion used for signing is the
302
``private'' key. Only the public key is stored on the calculator
303
itself.) Official key files from TI come in two varieties, known as
304
``Rabin'' and ``RSA'' formats. Note that \fBrabbitsign\fR currently
305
supports using Rabin-type key files to generate RSA signatures, but
306
not the other way around.
307
308
.SS Rabin key format
309
The Rabin key file format is typically used for TI-73 and TI-83 Plus
310
application signing keys. It consists of three lines, each containing
311
a big integer. The first line is the public key, \fIn\fR; the second
312
and third are its two factors, \fIp\fR and \fIq\fR.
313
314
Each line begins with two hexadecimal digits, giving the length of the
315
number in bytes, followed by the bytes themselves, written in
316
hexadecimal in little-endian order.
317
318
.SS RSA key format
319
The RSA key file format is typically used for TI-89 and TI-92 Plus
320
application signing keys. It consists of three lines: the key ID, the
321
public key \fIn\fR, and the signing exponent \fId\fR. (\fId\fR is the
322
inverse of the validation exponent, 17,
323
.if t modulo $phi (n)$,
324
.if !t modulo \(*f(\fIn\fR),
325
and thus calculating \fId\fR is computationally equivalent to
326
factoring \fIn\fR.)
327
328
The key ID is a short hexadecimal number, which should match the
329
contents of the 811x header field. The numbers \fIn\fR and \fId\fR
330
are written as big integers, as in the Rabin key format.
331
332
.SH FILES
333
.TP
334
/usr/local/share/rabbitsign/*.key
335
Private key files which will be used if the requested key is not found
336
in the current directory.
337
338
.SH BUGS
339
Who needs them?
340
341
\fBrabbitsign\fR accepts keys, applications, and even file names which
342
cause TI's programs to crash or generate invalid signatures.
343
344
Some apps which come very close to filling the last page may not be
345
usable with TI-Connect. This is a bug in TI-Connect. Try TiLP.
346
347
\fBrabbitsign\fR does not always generate the same signature as do
348
TI's programs. This is not a bug; it is simply due to the differences
349
in implementation. There are in fact four valid signatures for every
350
application hash; all four are accepted by the calculator.
351
352
If you encounter a valid app which \fBrabbitsign\fR is unable to sign,
353
or worse, generates an invalid signature, this is a serious bug, and I
354
would like to know about it.
355
356
.SH SEE ALSO
357
\fBpackxxk\fR(1), \fBrskeygen\fR(1)
358
359
.SH AUTHOR
360
Benjamin Moody <floppusmaximus@users.sf.net>
Loggerhead is a web-based interface for Breezy
Version: 2.0.1