CSIM Cards
The 1xBTS CSIM applet adds a CSIM application to a sysmoISIM-SJA5, so the card can be used in newer CDMA devices that require a SIM. The card holds the IMSI, phone number, home system, roaming list, A-key and packet-data credentials, and the device uses those values instead of its own NAM. The csim tool installs the applet, writes profiles and reads cards back.
The applet supports CAVE authentication, OTASP and OTAPA, and packet-data CHAP and Mobile IP authentication. PIN1, PIN2 and ADM1 protect the card’s files. AKA, Secure Mode and the OTASP A-key Diffie-Hellman exchange are not implemented, because the SJA5 cannot run them.
Requirements
- A sysmoISIM-SJA5 and its key material, which sysmocom sends by email at shipping. It lists each card’s GlobalPlatform keys (KIC1, KID1, KIK1) and ADM1
- A PC/SC card reader. On Linux, install
libpcsclite-devand runpcscd - Rust, Java and Git LFS
- GlobalPlatformPro (
gp.jar), which loads the applet onto the card
The applet and the tool are in the 1xBTS repository under sim/. The bundled applet build, sim/applet/dist/csim.cap, is used unless another is given. Building the applet is needed only to change it.
Getting started
-
Install
csimfrom the 1xBTS checkout:Terminal window cargo install --path crates/csim --features csim -
Download GlobalPlatformPro into the current directory, where
csim installlooks for it:Terminal window curl -L -o gp.jar \https://github.com/martinpaljak/GlobalPlatformPro/releases/download/v25.10.20/gp.jar -
Set the card’s keys from the key material:
Terminal window export KIC1=<KIC1> KID1=<KID1> KIK1=<KIK1>export PLATFORM_ADM1=<ADM1> -
Install the applet:
Terminal window csim install -
Create a profile for the subscriber and write it to the card:
Terminal window csim profile sim/examples/card.tmpl.yaml --imsi 001010000000042 --mdn 5550142csim write sim/examples/card-001010000000042.local.yaml -
Add the subscriber to 1xBTS with the same IMSI and MDN, and set the A-key from the profile on the subscriber record in hex form. See Authentication & Voice Privacy.
A card allows about ten failed GlobalPlatform logins before it locks. Stop at the first
6982error and check the keys. ADM1 also allows 10 attempts and has no unblock code.
csim install erases any profile on the card, so run csim write again after every install. With more than one reader attached, set CSIM_READER to part of the card reader’s name.
Profiles
A profile is a YAML file with one key per card setting: identities, home SID and NID, the roaming list, the service programming code, packet-data NAIs and secrets. The repository includes two examples:
| File | Use |
|---|---|
sim/examples/card.tmpl.yaml | Template for csim profile. Fills the IMSI, MIN, MDN and ICCID, and generates a new A-key and new packet-data secrets for each card |
sim/examples/card.yaml | Complete profile with fixed values |
The home SID in the profile must match the cell’s SID, and the roaming list must include the cell’s channel.
csim profile writes the filled profile next to the template as card-<IMSI>.local.yaml, readable only by its owner and ignored by Git. The file holds the card’s A-key and secrets. These cannot be read back from the card, and the network must be given the same values. A random secret generated by the template cannot match a secret the network shares across subscribers. Replace {secret} in the template with the network’s value for those.
csim install and csim write disable PIN1, because handsets do not prompt for the CSIM’s PIN1 and a card with PIN1 enabled gets no service. --keep-pin1 leaves it enabled.
Packet data
Packet-data authentication succeeds only when the card’s NAI and secret match the network element that checks them:
| Profile block | Checked by |
|---|---|
simple_ip with a sip_chap secret | The PDSN, for Simple IP CHAP |
mobile_ip with mn_ha and mn_aaa secrets | The home agent and the home AAA |
hrpd_access with an hrpd secret | The AN-AAA, for EV-DO access authentication |
Without an hrpd_access NAI on the card, a handset uses its own EV-DO credentials. See Packet Data Setup and EV-DO (HRPD) for the network side.
Checking a card
| Command | Result |
|---|---|
csim info | The card’s ATR (Answer To Reset), whether a CSIM is present, and the files readable without a PIN |
csim read | Every setting on the card, decoded |
csim verify <profile> | Writes the profile, reads it back and reports any difference |
csim chpin pin1 --new <PIN> | Sets PIN1 with ADM1. PIN2, PUK1 and PUK2 are set the same way |
The full command list, options and install errors are in sim/docs/csim.md in the repository. Every profile key is listed in sim/docs/profiles.md.