Initial import

README.md

@@ -0,0 +1,27 @@
+From: https://www.reddit.com/r/SwitchHacks/comments/f7psrk/anatomy_of_an_eshop_card_code/
+
+Quite some years ago, [an effort has been made to look into how eShop codes worked](https://www.reddit.com/r/3dshacks/comments/5i1rhc/eshop_codes_out_of_curiosity/), but nothing really came from it. In the meantime, I've taken to actually analyzing the results, and we now know:
+
+- There are (at least) three generations of eShop codes.
+- How to decode the 'A' generation.
+- How to validate the 'A' generation.
+
+I'd like to thank /u/teseting in particular because [they noticed that there is a split between the first eight characters and the second eight characters](https://www.reddit.com/r/3dshacks/comments/5i1rhc/eshop_codes_out_of_curiosity/db5zkw2/), greatly accelerating my research on this.
+
+# Generations of codes
+
+There are at least three "generations" of eShop codes. Each generation has its own format and different kinds of validation.
+
+The **numeric generation** is the first generation of eShop codes. Each code consists of two eight-character halves. The first half is a monotonically increasing serial number. The second half is a high-entropy value. It is speculated that this second half actually be encrypted with a 64-bit block cipher (DES?); I've tentatively dubbed it the *external validator* because if there is validation to be had, it's external to the code itself. Codes for the numeric generation could be found in the wild around 2011.
+
+The **'A' generation** is the second generation of eShop codes. These codes have been in the wild since at least 2014, likely somewhat earlier. It is called the 'A' generation because the first character for these codes is always 'A'. It consists of four parts: The leading generation identifier 'A', a seven-character serial number in base 33XY encoding, a seven-character external validator in base 33XY encoding and a checksum in base 33XY encoding. Base 33XY is regular base 33 encoding (0123456789ABCDEFGHIJKLMNOPQRSTUVW), but the vowels 'O' and 'I' are replaced with the characters 'X' and 'Y', respectively.
+
+With some elbow grease, good guesses and trying out some constants, it has been possible to determine the checksum for the 'A' generation codes (pseudocode follows). It's a simple additive checksum that *looks* like it was meant to add the base 33 value of characters, but then messed up handling the alphabetic characters. Sample code can be found at the bottom of this post.
+
+The **'B' generation** is the current generation of eShop codes and the one that has been going since about 2015 or 2016. Little is known other than it apparently still using the base 33XY encoding. However, the checksum algorithm for the 'A' generation no longer works.
+
+# Additional speculation
+
+As far as I can tell, considering the somewhat small sample size, there are no predefined numeric ranges for eShop codes depending on purpose. Money and all kinds of contents are just generated with an increasing serial number.
+
+Even if codes have a valid checksum, they seem to be rejected by the system, so there's some kind of additional validation still taking place on the backend (maybe a check against a database). Because of the 64-bit-ish external validator, brute forcing codes is similarly infeasible. Perhaps 'B' generation codes have done away with the checksum; if so, then the fact that they still need to check the external validator is likely the cause for dropping it.

ninty-codes.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python2
+
+def generateChecksum(base_code):
+    if len(base_code) != 15:
+        raise RuntimeError("Bad argument to checksum")
+    # Mystery/bug: Why is this ord('7') in particular? 55, 0o55 and 0x55 are all unrelated to anything in base 33. The check looks like it's trying to do c - 'A', but does the weirdest thing instead.
+    cksum = reduce(lambda cksum, c: (cksum + (ord(c) - ord('0') if ord(c) <= ord('9') else ord(c) - ord('7'))) % 33, base_code, 0)
+    return '0123456789ABCDEFGHIJKLMNOPQRSTUVW'[cksum]
+
+def validate(code):
+    if len(code) != 16: return False
+    # Make uppercase if necessary, then change X and Y back to their base 33 equivalents
+    unmangled_code = code.upper().replace('X', 'I').replace('Y', 'O')
+    theirs = unmangled_code[15]
+    mine = generateChecksum(unmangled_code[0:15])
+    return theirs == mine
+
+def parse(code):
+    serial = None
+    external_validator = None
+    unmangled_code = code.upper().replace('X', 'I').replace('Y', 'O')
+    if code[0].decode('ASCII').isnumeric():
+        serial = long(code[0:8])
+        external_validator = long(code[8:])
+    elif code[0] == 'A':
+        serial = long(unmangled_code[1:8], 33)
+        external_validator = long(unmangled_code[8:15], 33)
+    elif code[0] == 'B':
+        serial = long(unmangled_code[1:8], 33)
+        external_validator = long(unmangled_code[8:15], 33)
+        print "warning: Format for 'B' generation speculative"
+    else:
+        print "unknown card generation '%s'" % code[0]
+        return
+
+    print "Serial number:      {0:010d}".format(serial)
+    print "External validator: {0:010d}".format(external_validator)
+
+if __name__ == '__main__':
+    import sys
+    # taken from the interwebs, none of these are new
+    predef = (
+            '5753437561933377',
+            '5753437675070492',
+            'A03RL0KB2XHHRRBD',
+            'A03RL0KC22JL2MEA',
+            'A03RL0KD0UXF49FK',
+            'A03RL0KE1X8GGMS6',
+            'A0796BH71Q1DSSYN',
+            'B0GLFY1H1QR5GGDT',
+            'B0K777732YWS7XVF',
+            )
+    args = None
+    if len(sys.argv) == 1:
+        args = predef
+    else:
+        args = sys.argv[1:]
+    for s in args:
+        if s[0] == 'A':
+            valid = validate(s)
+            print '%s: %s' % (s, "ok" if valid else "bad")
+            if not valid: continue
+            parse(s)
+        else:
+            print s
+            parse(s)
+        print ""