The "iButton with Java" (JiB) Command processor allows you to get and set the iButton’s 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):
Lc: Length 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: When ISO Exception Mode is enabled, uncaught ISO exceptions return the reason value in the SW. When disabled ISOExceptions are handled like every other exception - uncaught ISOExceptions return 0x6f00 in the SW.
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.
Description: Runs the memory
compactor. This command returns SW=0x9000 in revisions higher than 1.1*
but performs no work.
NOTE:
This command is not POR safe. You can lose data if the power fails during
execution.
Input data: None.
Description: Generates a 20 byte random challenge.
Input data: None.
Description: Verifies signed challenge response and activates the iButton. A Dallas Semiconductor signature is required.
Input data: Challenge response - Len | Data[Len].
Description: Sets the activation time period. This is the time period, starting at the time this command is executed, that the iButton will respond to APDUs destined for JavaCard Applets. After the activation time expires the response to all Applet APDUs will be SW=0x6684 (ISO_ERR_SECURITY_XX:JIB_ERR_IBUTTON_INACTIVE). This command can only be executed one time. It will fail with SW=0x6683 (ISO_ERR_SECURITY_XX:JIB_ERR_COMMAND_NOT_AVAILABLE) on all subsequent attempts.
Input data: Activation time in seconds (4 bytes).
Description: When Load PIN mode is disabled, Applets must be signed by Dallas Semiconductor. This mode adds the restriction that the signature must incorporate the serial number of the iButton that is allowed to run the applet.
Input data: byte - 0 to disable 1 to enable.
Description: The bytes in a SHA-1 hash created by the Java Powered iButton have always been reversed on a 4-byte boundary (default, legacy ordering). This command allows you to reverse that ordering to produce the correct, FIPS 180-1 specified byte ordering.
Input data: byte - 0 for legacy SHA byte ordering, 1 for FIPS 180-1 SHA byte ordering
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: Returns a byte representing the mode - 0 for disabled, 1 for enabled. See Set ISO 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.
Description: Returns
all AIDs in decending order. The format of each AID entry of the return
data is:
[Applet number(1 byte)][AID
length(1 byte)][AID data(AID length bytes)].
Input data: None.
Description: Returns a 4 byte number (LSB first) representing the time in seconds before the iButton activation expires. See Set Activation Time for more details.
Input data: None.
Description: Returns a byte representing the mode - 0 for disabled, 1 for enabled. See Set Verify Load with Serial number mode for more details.
Input data: None.
Description: Returns a byte
representing the crypto disable mode, 1 if the button's cryptographic
features are disabled, and 0 if the cryptographic features are not disabled.
Cryptographic features can only be disabled during the manufacturing process,
there is no corresponding Set Crypto Disable Flag feature.
The cryptographic features of all Java Powered
iButtons (as described in the JavaDocs for a particular firmware
revision) have always been enabled on all buttons shipped to date (November 2001).
Input data: None.
Description: Returns a byte representing the SHA return mode - 0 for legacy, 1 for FIPS-180. See Set Legacy SHA Disable for more details.
Input data: None.
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.
Description: Returns a two
byte value (LSB first) for each of the 5 memory banks in the iButton. The
format of the return data is:
[6k Bank][Bank 0][Bank1][Bank
2][Bank3]
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/
