14.4.2.1.3 Executing Secured Applets
Secured applets are small programs running in the target internal SRAM and extending the Secure SAM-BA Monitor features. Secured applet binaries are ciphered, signed and bundled with the SAM-BA tool. They cannot be modified by the user and only Microchip can provide them.
First, send the ciphered and signed applet to the target. This is done by the Send Applet command:
(PC to Device) >> SAPT,,9870,,#
(Device to PC) << CACK,00000000,00009870#
(PC to Device) >> <applet_binary.cip>
(Device to PC) << CACK,00000000,00000000#
In the example above, the SAM-BA tool requests sending an applet of size 0x9870 and the Secure SAM-BA Monitor acknowledges this. The SAM-BA tool sends the ciphered and signed applet binary (the file applet_binary.cip), and after checking the signature and deciphering the applet in SRAM, the Secure SAM-BA Monitor sends the status (0x0: successful).
Once the applet has been loaded into the internal SRAM, there is no need to load it again between applet command executions.
Once the applet is in SRAM, before executing its code, its mailbox must be filled. The mailbox is the 32-word buffer at the beginning of the applet area, which allows input parameters and output results to be exchanged with the applet. To do so, the Send Mailbox command must be issued.
The mailbox is not ciphered, and is automatically written at the correct address in SRAM0 by the Secure SAM-BA Monitor.
(PC to Device) >> SMBX,,80,,#
(Device to PC) << CACK,00000000,00000080#
(PC to Device) >> <applet_init_mailbox.bin>
(Device to PC) << CACK,00000000,00000000#
Now we can run the applet program with Execute Applet command.
(PC to Device) >> EAPP,,,,#
(Device to PC) << 0x06
(Device to PC) << ASTA,00000000,00000000#
First, the applet sends a 0x06 byte to notify completion, then the Secure SAM-BA Monitor replies with the status of the applet execution (0x0: successful). The status of applets are specific to each applet and are not related to the Secure SAM-BA Monitor error codes.
Also, depending on the applet and the executed command, the mailbox may have been updated with output results. Then the mailbox should be read back to get those outputs running the Read Mailbox command.
(PC to Device) >> RMBX,,,,#
(Device to PC) << CACK,00000000,00000080#<applet_output_mailbox.bin>
Finally, some applet commands need to exchange a large amount of data that does not fit into the 128-byte mailbox. In this case, applet commands can expect to exchange data through the applet buffer. The Send File (SFIL) and Receive File (RFIL) Secure SAM-BA Monitor commands are responsible for large data exchange through the applet buffer.
The Send File (SFIL) command should be executed before the Execute Applet (EAPP), whereas the Receive File (RFIL) should be executed after it.
(PC to Device) >> SFIL,,10000,,#
(Device to PC) << CACK,00000000,00010000#
(PC to Device) >> <data.bin>
(Device to PC) << CACK,00000000,00000000#
Or
(PC to Device) >> RFIL,00000000,00000400#
(Device to PC) << CACK,00000000,00000400#<data.bin>
The “initialize” command should be the first applet command to be executed for any applet. Then, the size of the applet buffer can be retrieved by reading the output mailbox.