Project

General

Profile

Cardem

Card emulation (cardem for short) is a firmware for SIMtrace 2 devices allowing to emulate cards (e.g. SIM).
You then can leave the card adapter cable in the phone/modem/reader, and have the actual card outside, in a separate reader.
This allows to easily change or reprogram the card without having to touch the phone.

This functionality is already implemented and working on sysmoQMOD board.
It is now also available for SIMtrace boards.
This is a beta firmware and still in development.
See limitations for known limitations and issues.

Requirements

PCSC

The examples described in this article show how to use card emulation by forwarding the traffic to an actual card inserted in another reader.
To access this card, a card reader in used in conjunction with the PCSC software.
This software allows to use almost any CCID card reader.

To use PCSC:
  1. install the PCSC daemon (only needs to be done once):
    sudo apt install pcscd
    
  2. ensure the PCSC daemon is started
    sudo systemctl start pcscd
    
To check the available readers and if a card is present, you can use the PCSC tool:
  1. install tool
    sudo apt install pcsc-tools
    
  2. check if the card is detected by the reader (use CTRL-C to exit)
    pcsc_scan 
    
    Using reader plug'n play mechanism
    Scanning present readers...
    0: OMNIKEY 6321 CLi USB (OKCM0030506091345044320140749730) 00 00
    
    Tue Sep 10 16:03:49 2019
     Reader 0: OMNIKEY 6321 CLi USB (OKCM0030506091345044320140749730) 00 00
      Event number: 0
      Card state: Card inserted, 
      ATR: 3B 9F 94 80 1F C7 80 31 E0 73 FE 21 1B 67 01 00 00 04 4D 02 01 99
    

USB permissions

The SIMtrace board is a USB device, and we require the corresponding permission to access it.
One way to do it is by using the sudo command in front of all programs accessing the SIMtrace USB device.

A more appropriate and safer way is to grant the current user access right to this USB device:
  1. create the plugdev group commonly used to access development devices and add yourself into it (you must log out and back in for this change to take effect)
    sudo groupadd pulgdev
    sudo adduser $USER plugdev
    
  2. install the udev rules for SIMtrace 2 devices
    sudo wget -O /etc/udev/rules.d/99-simtrace2.rules https://git.osmocom.org/simtrace2/plain/host/99-simtrace2.rules
    
  3. reload the rules
    sudo udevadm control --reload-rules
    sudo udevadm trigger
    

Flashing

You can download the beta firmware for the SIMtrace board here: simtrace-cardem-dfu.bin.

To flash the firmware on the board:
  • install dfu-util to flash firmware
    sudo apt install dfu-util
    
  • flash firmware
    dfu-util --device 1d50:60e3 --cfg 1 --alt 1 --reset --download simtrace-cardem-dfu.bin
    

For more details about the flashing procedure, read this article.

Software

With the cardem firmware, the SIMtrace v2 board mainly forwards the ISO 7816 card communication over USB.
A software on the host must receive the APDU requests and send the corresponding APDU response.
There are several software available to do that.
Since the USB messages are specified and the software is open source, you could implement your own APDU handler.

Following are examples on how to use simtrace2-remsim and osmo-remsim:
  • simtrace2-remsim is meant to be used when you have a local setup (e.g. everything on one host computer). The SIMtrace board is connected to the phone/modem, and the actual card you want to forward the traffic to is inserted in a CCID reader connected to the host. The benefit of this setup is that you can easily re-program the card without having to remove it from the phone/modem slot.
  • osmo-remsim extends the simtrace2-remsim functionality by allowing to have multiple cards located on other hosts. The traffic is then forwarded over the network.

simtrace2-remsim

simtrace2-remsim is the simplest solution.
If forwards the APDU request/response to/from a PCSC card reader.

To get simtrace2-remsim:
  • Install required packages to compile the software:
    sudo apt-get install libusb-1.0-0-dev libosmocore-dev libpcsclite-dev
    
  • Get and compile the software:
    git clone git://git.osmocom.org/simtrace2.git
    cd simtrace2/host/
    make
    
To use simtrace2-remsim:
  1. power off phone
  2. insert card adapter cable into phone
  3. insert card adapter cable SIMtrace v2 board
  4. plug SIMtrace v2 board in host computer USB port
  5. connect external card reader to host (any USB CCID reader should do the job)
  6. ensure a card is present in the reader slot (not in the SIMtrace port)
  7. check if the card is detected by the reader (use CTRL-C to exit)
    pcsc_scan 
    
    Using reader plug'n play mechanism
    Scanning present readers...
    0: OMNIKEY 6321 CLi USB (OKCM0030506091345044320140749730) 00 00
    
    Tue Sep 10 16:03:49 2019
     Reader 0: OMNIKEY 6321 CLi USB (OKCM0030506091345044320140749730) 00 00
      Event number: 0
      Card state: Card inserted, 
      ATR: 3B 9F 94 80 1F C7 80 31 E0 73 FE 21 1B 67 01 00 00 04 4D 02 01 99
    
  8. get SIMtrace USB path (this step will soon be not required anymore)
    dfu-util -l
    
    ...
    Found Runtime: [1d50:60e3] ver=0002, devnum=59, cfg=1, intf=1, path="1-2.2", alt=0, name="UNKNOWN", serial="UNKNOWN" 
    
  9. start simtrace2-remsim with corresponding USB path (here 1-2.2)
    ./simtrace2-remsim --usb-vendor 1d50 --usb-product 60e3 --usb-path 1-2.2 --usb-config 1
    
    (C) 2010-2017, Harald Welte <laforge@gnumonks.org>
    (C) 2018, sysmocom -s.f.m.c. GmbH, Author: Kevin Redon <kredon@sysmocom.de>
    
    SCardEstablishContext: OK
    
    SCardListReaders: OK
    
    SCardConnect: OK
    
    <- 01 05 00 00 00 00 09 00 01 
    <- 02 02 00 00 00 00 09 00 01 
    <= cardem_request_set_atr(3b 00 )
    <- 01 02 00 00 00 00 0b 00 02 3b 00 
    <- 02 01 00 00 00 00 0b 00 02 2c 01 
    Entering main loop
    
  10. now you can power on the phone (only after simtrace2-remsim is started since simtrace2-remsim can't tell the phone a card has been inserted). you should also see some APDU traffic
    URB: 01 06 00 00 00 00 13 00 01 00 00 00 05 00 a0 a4 00 00 02 
    -> 01 06 00 00 00 00 13 00 01 00 00 00 05 00 a0 a4 00 00 02 
    => DATA: flags=1, a0 a4 00 00 02 : CLA=a0 INS=a4 P1=00 P2=00 P3=02; case=4, lc=2(0), le=0(0)
    <= cardem_request_pb_and_rx(a4, 2)
    <- 01 01 00 00 00 00 0f 00 08 00 00 00 01 00 a4 
    URB: 01 06 00 00 00 00 10 00 02 00 00 00 02 00 7f 20 
    -> 01 06 00 00 00 00 10 00 02 00 00 00 02 00 7f 20 
    => DATA: flags=2, 7f 20 : CLA=a0 INS=a4 P1=00 P2=00 P3=02; case=4, lc=2(2), le=0(0)
    TX: a0 a4 00 00 02 7f 20 
    SCardEndTransaction: OK
    
    RX: 9f 17 
    SW=0x9f17, len_rx=0
    <= cardem_request_sw_tx(9f 17)
    <- 01 01 00 00 00 00 10 00 06 00 00 00 02 00 9f 17 
    URB: 01 06 00 00 00 00 13 00 01 00 00 00 05 00 a0 f2 00 00 17 
    -> 01 06 00 00 00 00 13 00 01 00 00 00 05 00 a0 f2 00 00 17 
    => DATA: flags=1, a0 f2 00 00 17 : CLA=a0 INS=f2 P1=00 P2=00 P3=17; case=2, lc=0(0), le=23(0)
    TX: a0 f2 00 00 17 
    SCardEndTransaction: OK
    

osmo-remsim

osmo-remsim is a separate project allowing to have the card/SIM at a different location than the modem/phone. It also allows to manage multiple cards and emulators. The setup is a bit more complicated though.

  1. add the osmo-remsim repository on each host you want to operator parts of osmo-remsim (so you don't have to compile osmo-remsim yourself)
  2. run the server. This is the central instance telling the bankd which reader to use, and the client which bankd to contact.
    • install osmo-remsim-server:
      sudo apt install osmo-remsim-server
      
    • run server
      osmo-remsim-server
      
  3. the server needs to be additionally configured through its RESTful interface. For that we will use the small tool remsim-apitool.py
    • download remsim-apitool.py
      wget https://git.osmocom.org/osmo-remsim/plain/contrib/remsim-apitool.py
      
    • tell the server client 1 with slot 1 (on the modem side) should use bank 1 slot 1 (on the reader side). This must be done every time after to server is started.
      python remsim-apitool.py --create-slotmap 1 1 1 1
      
  4. osmo-remsim uses PCSC to access card readers (this setup only needs to be done once)
    • connect external card readers to host (any USB CCID reader should do the job)
    • ensure cards are present in the card readers
    • get reader name (use CTRL-C to exit)
      pcsc_scan 
      
      Using reader plug'n play mechanism
      Scanning present readers...
      0: OMNIKEY 6321 CLi USB (OKCM0030506091345044320140749730) 00 00
      
    • create a bankd_pcsc_slots.csv file listing the card readers osmo-remsim should use. The CSV format is: user provided bank number (collection of readers/slots), user provided slot number (individual card in reader/bank), PCSC reader name.
      echo << EOF > bankd_pcsc_slots.csv
      "1","1","OMNIKEY 6321 CLi USB (OKCM0030506091345044320140749730) 00 00" 
      EOF
      
  5. run the bankd (the bankd_pcsc_slots.csv file must be in the current working directory). This will contact the server (which can be on another host) to know which card reader it will manage.
    • install osmo-remsim-bankd:
      sudo apt install osmo-remsim-bankd
      
    • here we tell it will take care of the card reader from bank 1 (no need to specify the number of slots available in the reader using the -n argument if it is less or equal than 8)
      osmo-remsim-bankd --server-host localhost --server-port 9998 --bank-id 1
      
  6. now we need to actually emulate the card
    • power off phone
    • insert card adapter cable into phone
    • insert card adapter cable SIMtrace v2 board
    • plug SIMtrace v2 board in host computer USB port
    • install osmo-remsim-client:
      sudo apt install osmo-remsim-client
      
    • get SIMtrace USB path (this step will soon be not required anymore)
      dfu-util -l
      
      ...
      Found Runtime: [1d50:60e3] ver=0002, devnum=59, cfg=1, intf=1, path="1-2.2", alt=0, name="UNKNOWN", serial="UNKNOWN" 
      
    • start the osmo-remsim-client-st2 client with corresponding USB path (here 1-2.2). This will contact the server (which can be on another host) to know which bankd to contact. Here we tell it will take care of slot 1 of modem 1 (SIMtrace can only emulate one card).
      osmo-remsim-client-st2 --usb-vendor 1d50 --usb-product 60e3 --usb-path 1-2.2 --usb-config 1 --client-id 1 --client-slot 1 --server-host localhost --server-port 9998
      
    • you can now power on the phone, and should see some APDU traffic on the client and bankd.

Limitations

Here are the known limitations:
  • there is no way for SIMtrace to tell the reader that a new card has been inserted. There is no specified way to do it (e.g. in ISO 7816 standard). This is generally done inside the reader hardware by a mechanical switch. The only way around is to restarted the reader (e.g. phone).
  • the cardem is currently a separate firmware. it is planned to combine it with the trace firmware (the software will then select the right functionality)
  • the firmware ignores the sent ATR (sent by the software, from the card to forward). this is to prevent the reader from switching to a yet untested baud rate
  • the error messages returned by simtrace2-remsim are not very useful
  • simtrace2-remsim does not automatically reconnect to the SIMtrace board when the hardware is reset
  • you have to specify the USB path to simtrace2-remsim
  • no long term tests have been performed (this is already planned)
  • you can't use the card reader built in SIMtrace
  • simtrace2-remsim does not send the APDU to GSMTAP so you can trace the traffic using wireshark
  • simtrace2-remsim-udp does not connect to SIMtrace v2 boards

We are currently working on resolving these issues.
If you found yet unknown issues, you can report them to the main developer at kredon AT sysmocom DOT de.
If possible, please also attach the corresponding debug serial output. To get the serial output, connect a USB to UART cable either to the 2.5 mm stereo headphone connector (tip = TX, ring = RX, sleeve = GND) or the nearby DEBUG port (pin 1 = GND, pin 4 = TX, pin 5 = RX). Open the serial port with the following configuration: 921600 8N1.

Add picture from clipboard (Maximum size: 48.8 MB)