Update dongle details with a bit more correct information.

DONGLE.md

@@ -4,13 +4,14 @@ All firebeat games use a Dallas DS1991 iButton connected to the firebeat through
 a DB9 interface as the protection against piracy and as a factory service switch.
 The DS1991 is a small 1-wire non-volatile memory device with three 48-byte
 enclaves that can hold any data. Each enclave is password-protected by an 8-byte
-key and identified with an 8-bit ID. In order to read a secure enclave you must
+key and identified with an 8-byte ID. In order to read a secure enclave you must
 provide the correct password. If you don't, the dongle will appear to return
 memory but it will be random data. It is not clear whether the data returned is
 an XOR with the key provided or if the DS1991 generates actual random data when
 the key is wrong. If it is an XOR then we can use knowledge of what should appear
 in the enclaves as a way of brute-forcing the password, but this has not been
-researched.
+researched. In practice it is not necessary as all known dongle variant passwords
+are extracted.
 
 In order to access the security key without forcing the game to be initialized
 and locked to a particular token, each firebeat executable must include the IDs
@@ -25,16 +26,24 @@ The first enclave is the unique serial number for the copy of the game and
 starts with the 3-letter code for the game (C01 in the case of BeatmaniaIII The
 Final) and is followed by six digits. The game will verify that the 3-letter
 code is a match and reject dongles that do not match, and will display the
-9-digit serial on the boot-up and attract screen. It does not appear to
-validate the rest of the digits so any valid displayable ascii string is
-technically a correct dongle. The rest of the enclave appears to be filled
-with ascii space characters.
+9-digit serial on the boot-up and attract screen. Almost every game will use
+the fourth digit as a region selection switch, comparing it to the cabinet
+ID register. Normally, digits 1, 3 and 7 specify Japan region, 2 and 4 specify
+overseas, and 0 and 9 are reserved. Some games use 9 as a rental code, some
+use 0. It does not appear to validate the rest of the digits so any valid
+displayable ascii string is technically a correct dongle as long as the first
+3 digits match the game code and the fourth digit is correct for the hardware
+you are running on. The rest of the enclave appears to be filled with ascii
+space characters.
 
 The second enclave appears to be completely ignored in most games aside from
 verifying that the data itself can be transferred. It appears to be filled
 entirely with ascii space characters. For the few games that do use this
 enclave (Pop'n Music Mickey Tunes, Animelo 1 and 2) this includes additional
-license information.
+license information. On KeyboardMania 2ndMIX this enclave appears to be filled
+with random data that matches on both Japan and overseas regions so it is possible
+that the enclave password is incorrect or whoever programmed the dongles didn't
+initialize the second enclave properly.
 
 The third enclave is the service mode enclave and is normally all ascii
 space characters on a consumer dongle. Various games recognize various
@@ -55,14 +64,16 @@ the left, a 2 digit hex number on the right and a 12 digit hex number below
 both of them. The left number is the ROM ID CRC, the right is the product code
 (always 02) and the bottom is the unique serial number. This should be transcribed
 by first noting down the CRC, then the 12 digit serial, and finally the product
-code (02).
+code (02). Then the bytes should be reversed. This can be checked by using the
+`dallas_crc` utility by providing the hex codes for the first seven bytes (after
+reversing them), and you should get a hex CRC value that matches the 8th byte.
 
 ## Dumping Theory
 
 In order to dump the secure enclave of a security iButton, you must know the
 correct ID and password for that enclave and have hardware capable of interfacing
 with the iButton itself. It just so happens that a firebeat has compatible
-hardware for interfacing with a button, and the ID and password can be mined out
+hardware for interfacing with an iButton, and the ID and password can be mined out
 of the decompressed executable for each game. Looking at the bootup sequence
 for BeatmaniaIII The Final, the game first sets up a multithreaded environment,
 then kicks off a watchdog thread and then kicks off the main game thread. The
@@ -83,22 +94,23 @@ on the startup screen below the game model number and it continues booting.
 
 Two things can be gained from this understanding. First, that the game does
 not seem to use the serial number in any way aside from verifying that it is
-in the correct range. This means that it is trivial to bypass the security by
-simply skipping the dongle read and jumping directly to the "OK" response.
-Second, if you have the correct IDs and passwords for a dongle in the game's
-code, it will read all 3 48-byte enclaves to a buffer on the stack. This means
-if you were to modify the serial number copy and check code to instead copy
-the hex values of all 3 enclaves to the serial number global before returning
-you would have a working dongle dump utility. This is precisely what the
-dongledumper.patch modifications achieve. The meat of the change is replacing
-the check and copy with a hex conversion loop and resizing the stack for the
-game's printf implementation so that the very long string doesn't blow the stack
-and cause an exception. The rest of the modifications are there to make the
-output on the screen prettier and to halt the game from continuing once it
-does print the dongle while still petting the watchdog. To read the dongle for
-another game, one must replace the ID and password strings with the correct ID
-and password pairs from that game itself. Aside from that, everything works as
-desired.
+in the correct range and matches the cabinet info register's region. This means
+that it is trivial to bypass the security by simply skipping the dongle read
+and jumping directly to the "OK" response. Second, if you have the correct IDs
+and passwords for a dongle in the game's code, it will read all 3 48-byte
+enclaves to a buffer on the stack. This means if you were to modify the serial
+number copy and check code to instead copy the hex values of all 3 enclaves to
+the serial number global before returning you would have a working dongle dump
+utility. This is precisely what the dongledumper.patch modifications achieve.
+The meat of the change is replacing the check and copy with a hex conversion loop
+and resizing the stack for the game's printf implementation so that the very long
+string doesn't blow the stack and cause an exception. The rest of the
+modifications are there to make the output on the screen prettier and to halt the
+game from continuing once it does print the dongle while still petting the
+watchdog. To read the dongle for another game, one must replace the ID and
+password strings with the correct ID and password pairs from that game itself.
+This can be accomplished using the `dongle_dump_utils` utility which already
+contains all of the known passwords. Aside from that, everything works as desired.
 
 Once you have all three enclaves output and have noted the ROM ID from the
 iButton itself, you can reconstruct a dongle file for use with MAME or to rewrite
@@ -110,4 +122,5 @@ the second ID, password and enclave, followed by the third. Finally, the 8
 byte ROM ID should follow all 3 enclaves. If done correctly, the resulting file
 should be exactly 200 bytes long. If you have an empty iButton you can program
 the three enclaves by using the ID and passwords followed by a copy of the data
-from another dongle or hand crafted data if you so desire.
+from another dongle or hand crafted data if you so desire. You can also verify
+that your dump looks correct using the `dongle_dump_utils` utlity.