[Main]
Name=cfindfield
Type=Function
Subtype=ROM Call
Header Files=cert.h
Definition=short cfindfield (CFILE *context, unsigned short FieldID, CERT_FIELD *dest);

[ROM Call]
Index=$12A

[Description]
Finds a matching field from a context.

[Explanation]
cfindfield searches a file associated with the file context pointed to by <I>context</I> for a
field which has field ID number equal to <I>FieldID</I> (length bits should be set to 0).
If such field is found, cfindfield fills the field descriptor structure pointed to by <I>dest</I>
and returns <A HREF="$$LINK(alloc.h/Bool)">TRUE</A>, else returns <A HREF="$$LINK(alloc.h/Bool)">FALSE</A>.
<BR><BR>
cfindfield is used often in TIOS to access particular data in a certificate file. Usually,
function <A HREF="$$LINK(copensub)">copensub</A> is called immediately after cfindfield to get
access to the content of the field. If the field contains subfields, this procedure may be
repeated several times if necessary.
<BR><BR>
As an illustration of layout of certificate files, the layout of certificate files used in TIOS
is given below. First, the field ID number is shown, then the short description of the field
follows. Indentation shows that a particular field is a subfield of the field with smaller indentation.
<UL>
<LI>
Layout of AMS header (AMS is part of TIOS which may be replaced, in opposite to Base Code);
it starts at address 0x212000 on TI-89 and 0x412000 on TI-92 Plus:
<BR><BR>
<PRE>0x8000 AMS header (organized as a certificate file, although it is not
                   read-protected like "real" certificates)

0x8010  First part of Product ID
0x8020  Third part of Product ID
0x8030  Fourth part of Product ID
0x80A0  Second part of Product ID
0x8040  Product Name: "Advanced Mathematics Software"
0x0320  Product code (6 bytes)
0x0200  Signature - encrypted MD5 (see <A HREF="$$LINK(rsa.h/)">rsa.h</A>) of 0x320 field
        (including header)
0x8070  Actual AMS code

0x0200 Signature of entire AMS
</PRE>
Fields with ID numbers 0x0320 and 0x0200 contains some authenticated number.
More precise, field with ID number 0x0320 is a unique number for the ROM imate, and
field with ID 0x0200 is the encrypted digital signature of it.
Product ID is formed by applying format string "%02lX-%lX-%lx-%lX" to the content of
fields with ID numbers 0x8010, 0x80A0, 0x8020 and 0x8030.
<BR><BR>
</LI>
<LI>
Layout of Flash ROM certificate (it is stored in the part of the Flash ROM which is read-protected,
so reading it is extremely hard from any routine which is not the part of the TIOS Base Code);
it starts at address 0x210004 on TI-89 and 0x410004 on TI-92 Plus:
<BR><BR>
<PRE>0x0330 Flash ROM certificate

0xA10 Five-byte Serial Number (used as "pass phrase")
0xA20 Certificate Key
</PRE>
Serial number has layout #sssss&nbsp;sssss&nbsp;cccc (all digits are in hex). First ten digits
are picked up from the field with ID number 0xA10. Then, the Certificate Key is used to decrypt
the MD5 (see <A HREF="$$LINK(rsa.h/)">rsa.h</A> for more info about RSA encryption) of the Serial Number to get cccc. In fact,
decrypting the Serial Number in this way creates a 40 byte number. Only first two bytes (in
little endian) are taken for cccc. This method ensures that only TI can create valid Serial
Numbers, as both the Serial Number and Key are unique for each machine.
<BR><BR>
</LI>
<LI>
Layout of .cer files, which are attached to the start of Flash applications:
<BR><BR>
<PRE>0x0300 Flash application certificate

0x0100 Certificate Revision Number
0x0400 Five-byte Serial Number
0x0500 Optional field in .cer files

0x0510 Author name

0x0320 Product code
0x0200 Product code signature
0x0700 Unknown certificate data

0x0710 Unknown byte data
0x0730 Signature
0x0710 Unknown word data
0x0730 Signature
0x0710 Unknown word data
0x0730 Signature

0x0200 Signature of all certificate data</PRE>
Of course, such data are present in the certificate memory only if you have installed
additional Flash applications. Function <A HREF="$$LINK(flash.h/FL_addCert)">FL_addCert</A> is
used to add such data to the certificate memory (this routine performs
very strong checking of what may be written there and under what conditions, so it is not
possible to write a garbage in this area by calling this routine).
</LI></UL>
As it is not possible to access the certificate part of Flash ROM directly, ecxept from the
Base Code part of TIOS (this area of ROM is read-protected), the usuall method for reading
certificates is to call <A HREF="$$LINK(flash.h/FL_getCert)">FL_getCert</A> first. This function
will copy all data from the certificate area which may be shown to the public into the RAM,
so the certificate can be read later from the RAM. For example, if you need to access the
certificate data which shows the name of the author of an Flash application (assuming that
such data is present in the certificate), the usual procedure is:
<PRE>HANDLE handle;
unsigned long size;
CFILE context;
CERT_FIELD field;
...
FL_getCert (&amp;handle, &amp;size, FALSE);
copen (&amp;context, HeapDeref (handle), size);
cfindfield (&amp;context, 0x300, &amp;field);
copensub (&amp;context, &amp;field);
cfindfield (&amp;context, 0x500, &amp;field);
copensub (&amp;context, &amp;field);
cfindfield (&amp;context, 0x510, &amp;field);
copensub (&amp;context, &amp;field);
</PRE>
After this, context<B>.</B>Pos will point to the author name. Alternatively, you can pick the name
character-by-character using <A HREF="$$LINK(cgetc)">cgetc</A>. If any of calls to cfindfield
functions fail (i.e. return <A HREF="$$LINK(alloc.h/Bool)">FALSE</A>), then such data are not present in
the certificate area.

[References]
Out=cread
In=system.h/AB_prodid, system.h/AB_prodname, unknown.h/_ROM_CALL_504
