1xBTS 1xBTS

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-dev and run pcscd
  • 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

  1. Install csim from the 1xBTS checkout:

    Terminal window
    cargo install --path crates/csim --features csim
  2. Download GlobalPlatformPro into the current directory, where csim install looks for it:

    Terminal window
    curl -L -o gp.jar \
    https://github.com/martinpaljak/GlobalPlatformPro/releases/download/v25.10.20/gp.jar
  3. Set the card’s keys from the key material:

    Terminal window
    export KIC1=<KIC1> KID1=<KID1> KIK1=<KIK1>
    export PLATFORM_ADM1=<ADM1>
  4. Install the applet:

    Terminal window
    csim install
  5. Create a profile for the subscriber and write it to the card:

    Terminal window
    csim profile sim/examples/card.tmpl.yaml --imsi 001010000000042 --mdn 5550142
    csim write sim/examples/card-001010000000042.local.yaml
  6. 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 6982 error 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:

FileUse
sim/examples/card.tmpl.yamlTemplate 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.yamlComplete 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 blockChecked by
simple_ip with a sip_chap secretThe PDSN, for Simple IP CHAP
mobile_ip with mn_ha and mn_aaa secretsThe home agent and the home AAA
hrpd_access with an hrpd secretThe 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

CommandResult
csim infoThe card’s ATR (Answer To Reset), whether a CSIM is present, and the files readable without a PIN
csim readEvery 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.

Esc