New SIM card testing and peek/poke tool

[Mychaela Falconia]

Hello FC community,

I am pleased to introduce a new FreeCalypso tool: fc-simtool.  This
program runs on a general-purpose computer (PC/laptop/etc) equipped
with a smart card "reader" device like the HID Omnikey readers sold by
Sysmocom, and it talks to a SIM card inserted into that "reader"
device - a PC host program talking directly to a SIM card, *without*
going through any kind of phone or other GSM device!  Available
functions are:

* All spec-mandated SIM PIN operations are supported: verifying,
enabling, disabling, changing and unblocking PINs.

* One can read all data items (elementary files in spec terminology)
that are stored on the SIM and are accessible via the standard protocol
- basically everything other than the cryptographic keys which the SIM
never reveals.  Any EF (whether fc-simtool knows it or not) can be
displayed in raw hex, but for some important SIM files there are
higher-level decoding and display functions.  The content of all 4 SIM
phonebooks (ADN, FDN, SDN, MSISDN) can be dumped in fully decoded form
and saved into a file.  To read SMS stored on the SIM, use the savebin
command to save EF_SMS into a binary file on your Unix host system,
then use pcm-sms-decode (added to FC host tools a few releases ago) to
fully decode.

* If you know what you are doing, you can make some writes to the SIM
too, to those files which the SIM will allow you to modify.  You can
restore a raw binary backup previously made with savebin, you can
write to phonebooks in the same high-level format that is emitted by
the pb-dump command (restoring backups or making new modifications, up
to you), and if you really know what you are doing, you can write your
own arbitrary bytes in hex.

fc-simtool only speaks the classic GSM 11.11 SIM protocol, no USIM or
ISIM support, nor does it support any of the beyond-the-standards
proprietary commands used by various programmable SIMs - those other
functions are already performed well by Osmocom SIM tools, no need to
duplicate.  fc-simtool can be used together with a card "reader"
device like Omnikey 3121 to test SIMs for 2G compatibility (tell if a
SIM is good or if it's an evil one like T-Mobile USA currently issues)
without breaking the little SIM out of the credit-card-sized carrier,
and if you are a truly devoted GSM/2G enthusiast and tinkerer in
general, it is nice to be able to play with SIMs directly in their
most native form.

Because fc-simtool requires pcsc-lite (specifically libpcsclite and
its C headers), it won't be included in the base FC host tools package
which does not allow any weird dependencies.  Instead it resides in
the freecalypso-hwlab Hg repository, to be used by those who have the
necessary hardware (smart card "reader" devices) and who will go
through the pain of installing the necessary exotic software if they
need this arguably esoteric functionality.

Oh, and if anyone in our community besides me has any SysmoUSIM-SJS1
cards made by Sysmocom, you might find it interesting that they have
their MSISDN record misprogrammed.  This SIM has 34-byte records for
EF_MSISDN, allowing 20 bytes of alpha tag (rarely used for MSISDN)
before the required 14-byte structure, but it is misprogrammed in that
the phone number record (the part that is supposed to be at the
beginning of the standard 14-byte structure) starts at byte offset
0x12 instead of 0x14.  The length and TON/NPI bytes are thus written
into the last two bytes of the space allotted for the alpha tag
instead of their proper place in the 14-byte structure, and the packed
digit bytes that follow are shifted accordingly.  Now I know why the
number reported by AT+CFUN when I stick one of those SIMs into an
FCDEV3B does not match what Sysmocom's manual says. :)  But with
fc-simtool this misprogramming can be trivially fixed by writing a new
MSISDN record with whatever number you like, and no ADM keys are
needed: GSM specs say that EF_MSISDN should be writable by ordinary
users just like EF_ADN (only CHV1 required), and Sysmocom's SIM
engineers apparently agreed, as I can write that file without ADM keys.

Further on the subject of the MSISDN record stored in SIM cards, it is
the record which all standard phones display when you select "Show my
own phone number" or whatever it is called in the menu.  As Osmocom
people explain to newbies who are just starting to run their own GSM
networks and issue their own SIMs, this MSISDN record is not needed
for any actual functionality as in phones connecting to the network,
making and receiving calls: when a network pages a phone to connect a
mobile-terminated call, it does so by IMSI/TMSI, not by directory
number, and the phone does NOT need to know its own number in order to
answer that call.  But of course life-long users of GSM/2G phones and
services do expect to see the correct number when they select "Show my
own phone number" in the menu, hence I argue that the MSISDN record in
the SIM does need to be programmed correctly.  Mainstream operators
have some kind of OTA provisioning mechanism for it: unactivated SIM
cards are shipped with this MSISDN record blank, and when you activate
a line, they send some kind of special SMS to the SIM that causes a
SIM-embedded OTAP application to write your newly activated phone
number to the MSISDN record.  The same procedure is repeated if you
ask the phone company to give you a new number on an existing line
without changing the SIM - the MSISDN record magically updates.
Replicating this feat in our own indie networks will take some work,
but in the meantime we can program the MSISDN record manually with
fc-simtool.

Hasta la Victoria, Siempre,
Mychaela aka The Mother