The "iButton with Java" (JiB) Command processor allows you to get and set the iButtons configuration parameters, delete applets, get the current value of the real-time clock, get random data, list the applets that are currently loaded, set the commit buffer size and to master erase the iButton. The Command Processor commands do not use the JavaCard Virtual Machine.
The JiB communicates using Application Protocol Data Units (APDUs) as described in ISO 7816 and the JavaCard 2.0 specification. Command APDUs are sent to the iButton and Response APDUs are received from the iButton. A Status Word (SW) always follows Response APDUs. The SW 0x9000 is returned if the command was executed with no error. The Command APDU header contains the following parameters (All parameters are one-byte except for Data[Lc], which is a byte array of length Lc):
CLA: Class
INS: Instruction
P1: Parameter 1
P2: Parameter 2
Lc: Length of command data
Data[Lc]: Lc bytes of command data
Le: Expected response length
The following list of JiB commands list the header values and data required for each command. Command categories that are "Master Pin Protected" require a Master PIN in the first bytes of the Data field. The format of the Master PIN is [PIN length byte Len][Len bytes of PIN data]. The maximum PIN length is eight bytes, therefore every Master PIN protected command will have one to nine bytes of PIN information pre-pended to the data field. A null PIN is represented by a length byte of zero and no PIN data.
CLA: D0h
INS: 95h
Administrative commands
(Master PIN Protected)
P1: 00h
Description: Erase all of the applets installed on the iButton, free all memory created by these applets, and reset all configuration options back to default values. (i.e. set AppletGC to off, etc.)
Input data: None.
Description: Set the Master PIN for this iButton.
Input data: Old PIN followed by new PIN.
Description: The ephemeral collector recovers data that was referenced for a short period of time and then went out of scope (local variables, objects whose references were never stored in reference fields, etc).
Input data: byte 0 to disable 1 to enable.
Description: The applet collector recovers data that was referenced by the fields of an applet. These references were instanciated and then the references were lost either by setting the field to null or by instantiating another block of data.
Input data: byte 0 to disable 1 to enable.
Description: When Command PIN Mode is enabled, all administrative and AID commands require a Master PIN match before the command is executed. When disabled, the PIN match is skipped. To pass the PIN in the input data for the administrative command, first pass a byte indicating the length of the PIN, then 'length' bytes of PIN data followed by any other data the administrative command requires.
Input data: byte 0 to disable 1 to enable.
Description: When Load PIN Mode is enabled, nine bytes of PIN data, pre-pended to the applet data (JiB file data), must match the Master PIN in order for the applet load to succeed. The first byte is the length of the PIN being passed (max size of 8 bytes), followed by the PIN data, followed by (8 - PIN length) bytes of '0'. When disabled, the applet must be signed (Applet signing is disabled in 32 firmware).
Input data: byte 0 to disable 1 to enable.
Description: When Restore Mode is enabled, all field updates and javacard.framework.System transactions are considered atomic. If a tear occurs in the middle of these updates, the values just prior to the update are restored.
Input data: byte 0 to disable 1 to enable.
Description: When Exception Mode is enabled, Java API exceptions are thrown and can be caught. All uncaught exceptions return 0x6f00 in the SW. When disabled, any exception that is encountered will immediately terminate the process, and a 0x6f00 will be returned in the SW. Any catch blocks will be ignored in this disabled mode.
Input data: byte 0 to disable 1 to enable.
Description: This method is only available on iButtons revision 1.00 and later. If the error reporting mode is set, the iButton stores the last exception value code. This code can be retreived by performing a getLastError.
Description: Sets the size of the buffer where transactions are stored. Committing one field to the buffer requires 9 bytes. Therefore the default size of 72 bytes allows 8 field updates. The minimum size allowed is 72 bytes and the maximum is restricted by the amount of free RAM. All values will be rounded up to the next multiple of 9.
Input data: short (LSB first) commit buffer size in bytes.
Information
commands (Free Access)
P1: 01h
Description: Returns the Firmware Version String (FVS) in the following format: [length byte - Len][Len bytes of FVS data].
Input data: None.
The fields of the firmware version are "Firmware Version (FV) Major"."FV Minor"."API Build Number"
Description: Returns a short (LSB first) in hexadecimal format representing the amount of free RAM remaining in the iButton.
Input data: None.
Description: Returns a byte representing the mode 0 for disabled, 1 for enabled. See Set Ephemeral GC Mode for details on the Ephemeral garbage collector.
Input data: None.
Description: Returns a byte representing the mode 0 for disabled, 1 for enabled. See Set Applet GC Mode for details on the Applet garbage collector.
Input data: None.
Description: Returns a byte representing the mode 0 for disabled, 1 for enabled. See Set Command PIN mode for more details.
Input data: None.
Description: Returns a byte representing the mode 0 for disabled, 1 for enabled. See Set Load PIN Mode for more details.
Input data: None.
Description: Returns a byte representing the mode 0 for disabled, 1 for enabled. See Set Restore Mode for more details.
Input data: None.
Description: Returns a byte representing the mode 0 for disabled, 1 for enabled. See Set Exception Mode for more details.
Input data: None.
Description: This method is only available on iButtons revision 1.00 and later. If the error reporting mode is set, the iButton stores the last exception value code. This code can be retreived by performing a getLastError.
Description: Returns a short (LSB first) representing the size, in bytes, of the Commit Buffer. See Set Commit Buffer Size for more details.
Input data: None.
Description: Return the Answer to Reset string.
Input data: None.
Description: Returns a 4 byte number (LSB first) representing the current value of the real-time clock in seconds. This value counts up from zero and represents the amount of time since the battery was attached.
Input data: None.
Description: Returns the specified number of randomly generated bytes.
Input data: Short value (LSB first) representing the number of random bytes to retrieve.
Description: Returns the AID (applet name) in the format [AID length - Len][Len bytes of AID data].
Input data: Byte (0-15) representing applet number.
Description: Gets the last error value. If the Error Reporting mode is set, then this method will return the value of the last exception.
Statistical
commands (Free Access)
P1: 02h
Description: Returns a short (LSB first) representing the number of Power On Resets that have occurred since the last Master Erase. A Power On Reset occurs every time an iButton is inserted into a Blue Dot Reader.
Input data: None.
AID commands (Master PIN
Protected)
P1: 03h
Description: Deletes the currently selected applet and frees any memory owned by that applet.
Input data: None.
Description: Deletes the specified applet and frees any memory owned by that applet.
Input data: Byte (0-15) representing the applet number of the applet to be deleted.
Description: Deletes the specified applet and frees any memory owned by that applet. If more than one applets have the same AID, the applet with the lowest applet number will be deleted.
Input data: AID corresponding to the applet to be deleted.
iButton Homepage: http://www.ibutton.com/