--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Brute-force-search	Sun Mar 14 07:57:09 2021 +0000
@@ -0,0 +1,68 @@
+Brute force search of card file system file ID space
+====================================================
+
+The two protocols for accessing the file system of SIM cards (the original GSM
+11.11 SIM protocol and the UICC protocol of ETSI TS 102 221) allow for selecting
+directories and elementary files (EFs) by file IDs, but there is no provision
+in either protocol for listing or enumerating what file IDs exist - there is no
+'ls' operation.
+
+I (Mother Mychaela) really wanted to see the complete file system tree (all
+directories and files) on SIM and UICC cards that are sold as programmable, made
+by vendors such as Grcard and Sysmocom - my philosophy is that customers of such
+programmable SIMs have a natural right to know about every file on those cards
+and to exercise full control over the file system.  But the unfortunate reality
+with all currently available "programmable" SIMs on the market (or at least all
+known ones) is that not only are their vendors not giving us a way to reformat
+their cards and to recreate an entirely new file system layout as we like it,
+but they don't even document the complete file system content their cards are
+shipped with - and because there is no 'ls' operation in either of the two
+standard protocols, there is no trivial way for us to just see it.
+
+In order to see the true undocumented file system content of both Grcard and
+Sysmocom SIMs, I have implemented a brute force search of the file ID space.
+This brute force search works as follows:
+
+* Starting with MF (file ID 3F00), try selecting every possible file ID from
+  0000 to FFFF, skipping only 3F00.  For every file ID where the SELECT command
+  returns something other than "file ID not found" error (SW 9404 for SIM or
+  6A82 for UICC), follow up with GET RESPONSE and report what is found.  For
+  every found file ID that turns out to be a DF when the full response is
+  parsed, the brute force search code takes note of it for further descent.
+
+* For every found DF, repeat the same brute force search inside that DF.  File
+  IDs to be skipped at this search level include MF, the DF being searched, and
+  siblings of the current DF.  If there are further nested DFs, the search has
+  to continue recursively.
+
+In the case of the classic GSM 11.11 SIM protocol and fc-simtool, there is only
+one bfsearch-mf command, performing the search from MF - in this protocol there
+is only one file system tree.  In the case of UICC-architecture cards, there are
+multiple file system trees that are independent and disjoint: there is the main
+file system tree starting at MF, and then each application of the USIM/ISIM kind
+has its own ADF and a separate file system tree under that ADF, practically
+meaning ADF.USIM, ADF.ISIM and whatever other applications are present.
+
+bfsearch-mf command is implemented in both fc-simtool and fc-uicc-tool; this
+command takes no arguments and should work the same way irrespective of any
+prior card session state.  fc-uicc-tool also adds a complementary bfsearch-adf
+command for searching ADF-based directory trees; in order to use bfsearch-adf,
+you have to first select the desired application (select-aid, select-usim or
+select-isim) in the same card session.
+
+Please note that these brute force searches are very slow - in the Mother's
+experience with Grcard and Sysmocom cards, each bfsearch run took about an hour.
+
+Findings on GrcardSIM2 and sysmoISIM-SJA2
+=========================================
+
+The data directory in this code repository contains some findings that have been
+captured with brute force searches.  As one can see from these data captures,
+both Grcard and Sysmocom cards have plenty of additional directories and files
+beyond the standard ones called for SIM/USIM/ISIM, and we can only guess at what
+purpose all those extra proprietary directories and files may be serving.  There
+is one proprietary file on GrcardSIM2 and a few on sysmoISIM-SJA2 that are
+documented, but what we have found with bfsearch goes far beyond these few
+documented proprietary files.  I wonder if perhaps various card-resident
+applications are using some of these proprietary files for their internal
+purposes.