Provided by: rabbitsign_2.1+dmca1-2_amd64 
NAME
rabbitsign - sign applications for TI graphing calculators
SYNOPSIS
rabbitsign [ options ] [ -o appfile ] [ -k keyfile ] hexfile ...
rabbitsign [ options ] [ -k keyfile ] -c hexfile ...
DESCRIPTION
rabbitsign is an implementation of Texas Instruments' Rabin and RSA signing algorithms, as
used on the TI-73, TI-83 Plus, TI-84 Plus, TI-89, and TI-92 Plus graphing calculators.
These algorithms are used to sign Flash applications and operating systems so that the
calculator can recognize them as valid.
rabbitsign, like Texas Instruments' official signing programs, needs a private key (a pair
of large prime numbers) to sign apps. In order for the app to be accepted, the
corresponding public key (their product) must be present on the calculator. As of this
writing, the ``shareware'' private key number 0104, used for signing applications for the
TI-83 Plus and TI-84 Plus, is available through TI's SDK. Unfortunately, the OS signing
keys, as well as the app signing keys for the TI-73, TI-89, and TI-92 Plus, have not been
released, which means that only TI can sign apps and OSes for those calculators.
OPTIONS
-a Attempt to match the output of Peter-Martijn Kuipers' appsign program, for testing
purposes. The resulting output file will have Unix-style line termination, and
hence will not be compatible with all programs. This option is not recommended for
ordinary use.
-b Assume input files are raw binary files. If this option is not given, the file
type is detected automatically.
-c Do not sign apps; instead, check that the signatures of the specified apps are
valid. Exit status is 0 if all apps are valid, 1 if one or more apps fail, or 2 if
there is a non-mathematical error.
-f Ignore non-fatal errors, and force the application to be signed if possible. (All
of these messages are there for a reason, though, and chances are that if your app
generates any of them, it will also either fail validation or crash the calculator.
You have been warned.)
-g Write the output file in GraphLink ``TIFL'' format. (By default and for historical
reasons, apps and OSes for the TI-73 and TI-83 Plus are written in plain TI Hex
format instead; you can use packxxk(1) to convert these files into TIFL format.)
Apps and OSes for the TI-89 and TI-92 Plus are always written in TIFL format. See
APPLICATION FILE FORMATS below for more information.
-k keyfile
Read signing and/or validation keys from the given file. This file must be in one
of the formats used by TI's SDK tools. (See KEY FILE FORMATS below.) By default,
rabbitsign searches for the key named in the app header (for example, 0104.key for
``shareware'' TI-83 Plus apps.)
-K id Search for the key with the given id (a small hexadecimal number) rather than the
ID specified in the app header.
-n Attempt to sign the program as-is, without modifying the header. (This option may
not produce a file that the calculator will actually accept; it is intended for
testing and special-purpose signatures, not for ordinary app signing.)
-o outfile
Specify the output file. By default, output files are named by taking the name of
the input file, removing any suffix, and adding a `.app' or `.8xk' suffix depending
on whether -g is specified. (If the input file already has a `.app' or `.8xk'
suffix, `-signed' is inserted, so `myapp.8xk' becomes `myapp-signed.8xk'.)
If `-' is specified as an input file, that indicates the standard input, and the
signed result is written by default to the standard output.
-p Fix the app pages header. This is not done by default because an incorrect pages
header is generally a sign of a much more serious problem.
-P If the application ends close to a page boundary, add an additional page to hold
the signature. (Application signatures on the TI-73 and TI-83 Plus are not allowed
to span a page boundary.) Keep in mind that this is extremely wasteful, as it
consumes 16384 bytes of Flash to hold approximately 69 bytes of data; if your
application is in this situation, you should consider trying to reduce its size
slightly, or alternatively, adding more data to take advantage of the extra Flash
page.
-q Do not print non-fatal warning messages.
-r Re-sign a previously signed app (i.e., discard the previous signature before
signing.)
-R n For signing TI-73 and TI-83 Plus applications, use root number n (0 ≤ n ≤ 3) rather
than the default, root number 0. All four roots are valid, though distinct,
signatures, so this option is mainly for debugging.
Root 0 is computed so as to be congruent to m^[(p+1)/4] modulo p and m^[(q+1)/4]
modulo q. Root 1 is the negation of root 0 modulo p, root 2 the negation modulo q,
and root 3 the negation both modulo p and modulo q.
This option has no effect when signing OSes or TI-89/92 Plus applications, which
use the RSA algorithm rather than Rabin.
-t type
Explicitly specify the type of program (e.g., `8xk' for a TI-83 Plus application,
or `73u' for a TI-73 operating system.) The default behavior is to infer the
program type from the name of the input file. (If the input file does not have a
recognized suffix, the type is guessed based on the contents of the program
header.)
-u Disable automatic page detection, and assume input files are unsorted. This means
that page boundaries must be defined explicitly. (See APPLICATION FILE FORMATS
below.) This option has no effect in binary (-b) mode.
-v Be verbose; print out the names of apps and their signatures as they are signed.
Use -vv for more detailed information about the computation.
--help Print out a summary of options.
--version
Print out version information.
APPLICATION FILE FORMATS
Intel Hex
Intel hex is a standard ASCII file format used by many PROM programmers, and a common
assembler output format. Each line (or ``record'') consists of the following:
:NNAAAATTDDDDDD...CC
: The first character of the line is a colon; this is just used to identify the
format.
NN The next two characters are the number of data bytes on this line, written in
uppercase ASCII hexadecimal.
AAAA The next four digits are the address of the data on this line. rabbitsign only
looks at the low 14 bits of this value.
TT These two digits identify the ``type'' of the record. Intel hex defines several
record types for various addressing models; the only types which are meaningful for
TI calculators are types 00 (ordinary data) and 01 (end of file.)
DD... 2*NN hex digits follow, the actual data.
CC Finally, the inverted checksum is added, so that adding up all the bytes on the
line gives a total of zero modulo 256. (As an extension, rabbitsign permits you to
use two uppercase `X's in place of a checksum.)
Since the address is only 16 bits, this format cannot unambiguously represent applications
larger than 64 kilobytes. To enable multi-page applications to be created, rabbitsign
attempts to detect page boundaries automatically, starting a new page for each field with
a zero address. Thus to create a multi-page app, you can simply concatenate several Intel
Hex files, e.g.
cat page0.hex page1.hex | rabbitsign - -o complete.app
This will only work if the records are correctly sorted within each page. (If the
assembler does not generate records in order, you can sort the fields yourself using a
command such as `sort -k1.8,1.9 -k1.4,1.7'.)
To turn off this automatic page detection, use the -u option. In this case, you must
define page boundaries explicitly using the TI Hex format.
TI Hex
``TI'' hex is an extension to Intel hex which provides unambiguous representation of
multi-page apps. It adds records of the form
:0200000200NNCC
which indicate that subsequent data is placed on relative page number NN. (Keep in mind
that the TI-83 and 84 Plus install applications ``backwards,'' so if relative page 0 is
stored on absolute page 69, relative page 1 will be stored on absolute page 68, and so
forth.)
Some assemblers can generate multi-page data using type 4 records instead of type 2;
rabbitsign treats these as equivalent to type 2.
For compatibility with other software which makes certain assumptions about the format,
rabbitsign will write 32 bytes per line, and will end lines with a DOS-style carriage
return and line feed.
GraphLink TIFL
The standard (newer) GraphLink format consists of a 78-byte binary header which is added
to the start of a hex or binary file. The contents of this header are as follows:
0x00-07
The string `**TIFL**'.
0x08 The major version number (``App ID'') of the application.
0x09 The minor version number (``App Build'') of the application.
0x0A Flags; apparently intended to indicate whether the contents of the file are binary
(0) or TI Hex (1). This value is not, however, set consistently by other software.
0x0B ``Object Type'' field; apparently indicates something about the type of data. Set
to 0x88 in most TI-73 and TI-83 Plus files; set to 0 in TI-89 and TI-92 Plus files.
0x0C-0F
Binary-coded decimal month (one byte), day (one byte), and year (two bytes, big
endian) when the app was signed.
0x10 Length of the app's name.
0x11-18
Name of the app.
0x19-2F
Reserved, always set to zero.
0x30 Calculator type (0x73 = TI-83 Plus, 0x74 = TI-73, 0x88 = TI-92 Plus, 0x98 = TI-89.)
0x31 Type of data (0x23 = OS upgrade, 0x24 = application, 0x25 = certificate.)
0x32-49
Reserved, always set to zero.
0x4A-4D
Little endian length of the following data (the length of the hex file, not the on-
calculator size of the application.)
There also exist multi-part TIFL files, which simply consist of two or more TIFL files
concatentated together. (For instance, a software license agreement or a certificate file
can be attached to an application.) rabbitsign handles these files in a limited way: it
will read only the first section with a recognized data type, ignoring any other data in
the file. rabbitsign cannot create multi-part TIFL files, but they can be created using
packxxk(1) (or simply using cat(1).)
Binary
rabbitsign can also read binary app files; they are assumed to be contiguous, so when
signing a multi-page app, each page except the last must be filled to a full 16k.
KEY FILE FORMATS
Key files contain the data needed for signing and validating applications. (The portion
of the key file used for validating is known as the ``public'' key; the portion used for
signing is the ``private'' key. Only the public key is stored on the calculator itself.)
Official key files from TI come in two varieties, known as ``Rabin'' and ``RSA'' formats.
Note that rabbitsign currently supports using Rabin-type key files to generate RSA
signatures, but not the other way around.
Rabin key format
The Rabin key file format is typically used for TI-73 and TI-83 Plus application signing
keys. It consists of three lines, each containing a big integer. The first line is the
public key, n; the second and third are its two factors, p and q.
Each line begins with two hexadecimal digits, giving the length of the number in bytes,
followed by the bytes themselves, written in hexadecimal in little-endian order.
RSA key format
The RSA key file format is typically used for TI-89 and TI-92 Plus application signing
keys. It consists of three lines: the key ID, the public key n, and the signing exponent
d. (d is the inverse of the validation exponent, 17, modulo ϕ(n), and thus calculating d
is computationally equivalent to factoring n.)
The key ID is a short hexadecimal number, which should match the contents of the 811x
header field. The numbers n and d are written as big integers, as in the Rabin key
format.
FILES
/usr/local/share/rabbitsign/*.key
Private key files which will be used if the requested key is not found in the
current directory.
BUGS
Who needs them?
rabbitsign accepts keys, applications, and even file names which cause TI's programs to
crash or generate invalid signatures.
Some apps which come very close to filling the last page may not be usable with TI-
Connect. This is a bug in TI-Connect. Try TiLP.
rabbitsign does not always generate the same signature as do TI's programs. This is not a
bug; it is simply due to the differences in implementation. There are in fact four valid
signatures for every application hash; all four are accepted by the calculator.
If you encounter a valid app which rabbitsign is unable to sign, or worse, generates an
invalid signature, this is a serious bug, and I would like to know about it.
SEE ALSO
packxxk(1), rskeygen(1)
AUTHOR
Benjamin Moody <floppusmaximus@users.sf.net>