Project

General

Profile

Cardem » History » Version 24

laforge, 07/25/2022 07:35 AM
raw rules

1 2 tsaitgaist
{{>toc}}
2
3 1 tsaitgaist
h1. Cardem
4
5 14 tsaitgaist
Card emulation (cardem for short) is a firmware for SIMtrace 2 devices allowing to emulate cards (e.g. SIM).
6
You then can leave the card adapter cable in the phone/modem/reader, and have the actual card outside, in a separate reader.
7 1 tsaitgaist
This allows to easily change or reprogram the card without having to touch the phone.
8
9
This functionality is already implemented and working on sysmoQMOD board.
10 14 tsaitgaist
It is now also available for SIMtrace boards.
11 1 tsaitgaist
*This is a beta firmware and still in development*.
12
See [[Cardem#Limitations|limitations]] for known limitations and issues.
13
14 14 tsaitgaist
h2. Requirements
15
16
h3. PCSC
17
18
The examples described in this article show how to use card emulation by forwarding the traffic to an actual card inserted in another reader.
19
To access this card, a card reader in used in conjunction with the PCSC software.
20
This software allows to use almost any CCID card reader.
21
22
To use PCSC:
23
# install the PCSC daemon (only needs to be done once):
24
<pre>
25
sudo apt install pcscd
26
</pre>
27
# ensure the PCSC daemon is started
28
<pre>
29
sudo systemctl start pcscd
30
</pre>
31
32
To check the available readers and if a card is present, you can use the PCSC tool:
33
# install tool
34
<pre>
35
sudo apt install pcsc-tools
36
</pre>
37
# check if the card is detected by the reader (use CTRL-C to exit)
38
<pre>
39
pcsc_scan 
40
41
Using reader plug'n play mechanism
42
Scanning present readers...
43
0: OMNIKEY 6321 CLi USB (OKCM0030506091345044320140749730) 00 00
44
 
45
Tue Sep 10 16:03:49 2019
46
 Reader 0: OMNIKEY 6321 CLi USB (OKCM0030506091345044320140749730) 00 00
47
  Event number: 0
48
  Card state: Card inserted, 
49
  ATR: 3B 9F 94 80 1F C7 80 31 E0 73 FE 21 1B 67 01 00 00 04 4D 02 01 99
50
</pre>
51
52
h3. USB permissions
53
54
The SIMtrace board is a USB device, and we require the corresponding permission to access it.
55
One way to do it is by using the @sudo@ command in front of all programs accessing the SIMtrace USB device.
56
57
A more appropriate and safer way is to grant the current user access right to this USB device:
58
# 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)
59
<pre>
60
sudo groupadd pulgdev
61 16 tsaitgaist
sudo adduser $USER plugdev
62 14 tsaitgaist
</pre>
63
# install the udev rules for SIMtrace 2 devices
64
<pre>
65 24 laforge
sudo wget -O /etc/udev/rules.d/99-simtrace2.rules https://git.osmocom.org/simtrace2/plain/host/contrib/99-simtrace2.rules
66 14 tsaitgaist
</pre>
67
# reload the rules
68
<pre>
69
sudo udevadm control --reload-rules
70
sudo udevadm trigger
71
</pre>
72
73 1 tsaitgaist
h2. Flashing
74
75 22 dexter
You can download the beta firmware for the SIMtrace board here: https://downloads.osmocom.org/binaries/simtrace2/firmware/all/simtrace-cardem-dfu-latest.bin.
76 23 laforge
The corresponding source code is available "here":https://gitea.osmocom.org/sim-card/simtrace2/src/branch/master/firmware
77 1 tsaitgaist
78
To flash the firmware on the board:
79 15 tsaitgaist
* install dfu-util to flash firmware
80 1 tsaitgaist
<pre>
81 15 tsaitgaist
sudo apt install dfu-util
82 1 tsaitgaist
</pre>
83 15 tsaitgaist
* flash firmware
84
<pre>
85
dfu-util --device 1d50:60e3 --cfg 1 --alt 1 --reset --download simtrace-cardem-dfu.bin
86
</pre>
87 1 tsaitgaist
88
For more details about the flashing procedure, read [[Flashing#SIMtrace2-board|this article]].
89
90
h2. Software
91
92
With the cardem firmware, the SIMtrace v2 board mainly forwards the ISO 7816 card communication over USB.
93
A software on the host must receive the APDU requests and send the corresponding APDU response.
94
There are several software available to do that.
95 23 laforge
Since the USB messages are "specified":https://gitea.osmocom.org/sim-card/simtrace2/src/branch/master/firmware/libcommon/include/simtrace_prot.h and the software is "open source":https://gitea.osmocom.org/sim-card/simtrace2/src/branch/master/host, you could implement your own APDU handler.
96 1 tsaitgaist
97 11 tsaitgaist
Following are examples on how to use @simtrace2-remsim@ and @osmo-remsim@:
98
* @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.
99
* @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.
100
101 1 tsaitgaist
h3. simtrace2-remsim
102
103
@simtrace2-remsim@ is the simplest solution.
104
If forwards the APDU request/response to/from a PCSC card reader.
105
106
To get @simtrace2-remsim@:
107
* Install required packages to compile the software:
108
<pre>
109
sudo apt-get install libusb-1.0-0-dev libosmocore-dev libpcsclite-dev
110
</pre>
111
* Get and compile the software:
112
<pre>
113 23 laforge
git clone https://gitea.osmocom.org/sim-card/simtrace2.git
114 1 tsaitgaist
cd simtrace2/host/
115
make
116
</pre>
117
118
To use @simtrace2-remsim@:
119
# power off phone
120
# insert card adapter cable into phone
121
# insert card adapter cable SIMtrace v2 board
122
# plug SIMtrace v2 board in host computer USB port
123 3 tsaitgaist
# connect external card reader to host (any USB CCID reader should do the job)
124 1 tsaitgaist
# ensure a card is present in the reader slot (not in the SIMtrace port)
125
# check if the card is detected by the reader (use CTRL-C to exit)
126
<pre>
127
pcsc_scan 
128
129
Using reader plug'n play mechanism
130
Scanning present readers...
131
0: OMNIKEY 6321 CLi USB (OKCM0030506091345044320140749730) 00 00
132
 
133
Tue Sep 10 16:03:49 2019
134
 Reader 0: OMNIKEY 6321 CLi USB (OKCM0030506091345044320140749730) 00 00
135
  Event number: 0
136
  Card state: Card inserted, 
137
  ATR: 3B 9F 94 80 1F C7 80 31 E0 73 FE 21 1B 67 01 00 00 04 4D 02 01 99
138
</pre>
139
# get SIMtrace USB path (this step will soon be not required anymore)
140
<pre>
141
dfu-util -l
142
143
...
144
Found Runtime: [1d50:60e3] ver=0002, devnum=59, cfg=1, intf=1, path="1-2.2", alt=0, name="UNKNOWN", serial="UNKNOWN"
145
</pre>
146
# start @simtrace2-remsim@ with corresponding USB path (here 1-2.2)
147
<pre>
148
./simtrace2-remsim --usb-vendor 1d50 --usb-product 60e3 --usb-path 1-2.2 --usb-config 1
149
150
(C) 2010-2017, Harald Welte <laforge@gnumonks.org>
151
(C) 2018, sysmocom -s.f.m.c. GmbH, Author: Kevin Redon <kredon@sysmocom.de>
152
153
SCardEstablishContext: OK
154
155
SCardListReaders: OK
156
157
SCardConnect: OK
158
159
<- 01 05 00 00 00 00 09 00 01 
160
<- 02 02 00 00 00 00 09 00 01 
161
<= cardem_request_set_atr(3b 00 )
162
<- 01 02 00 00 00 00 0b 00 02 3b 00 
163
<- 02 01 00 00 00 00 0b 00 02 2c 01 
164
Entering main loop
165
</pre>
166
# 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
167
<pre>
168
URB: 01 06 00 00 00 00 13 00 01 00 00 00 05 00 a0 a4 00 00 02 
169
-> 01 06 00 00 00 00 13 00 01 00 00 00 05 00 a0 a4 00 00 02 
170
=> 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)
171
<= cardem_request_pb_and_rx(a4, 2)
172
<- 01 01 00 00 00 00 0f 00 08 00 00 00 01 00 a4 
173
URB: 01 06 00 00 00 00 10 00 02 00 00 00 02 00 7f 20 
174
-> 01 06 00 00 00 00 10 00 02 00 00 00 02 00 7f 20 
175
=> DATA: flags=2, 7f 20 : CLA=a0 INS=a4 P1=00 P2=00 P3=02; case=4, lc=2(2), le=0(0)
176
TX: a0 a4 00 00 02 7f 20 
177
SCardEndTransaction: OK
178
179
RX: 9f 17 
180
SW=0x9f17, len_rx=0
181
<= cardem_request_sw_tx(9f 17)
182
<- 01 01 00 00 00 00 10 00 06 00 00 00 02 00 9f 17 
183
URB: 01 06 00 00 00 00 13 00 01 00 00 00 05 00 a0 f2 00 00 17 
184
-> 01 06 00 00 00 00 13 00 01 00 00 00 05 00 a0 f2 00 00 17 
185
=> 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)
186
TX: a0 f2 00 00 17 
187
SCardEndTransaction: OK
188
</pre>
189 5 tsaitgaist
190
h3. osmo-remsim
191
192
"osmo-remsim":/projects/osmo-remsim/wiki 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.
193
194
# add the "osmo-remsim":/projects/cellular-infrastructure/wiki/Binary_Packages repository on each host you want to operator parts of @osmo-remsim@ (so you don't have to compile osmo-remsim yourself)
195
# run the server. This is the central instance telling the bankd which reader to use, and the client which bankd to contact.
196
** install @osmo-remsim-server@:
197
<pre>
198
sudo apt install osmo-remsim-server
199
</pre>
200 15 tsaitgaist
** run server
201 5 tsaitgaist
<pre>
202
osmo-remsim-server
203
</pre>
204
# the server needs to be additionally configured through its RESTful interface. For that we will use the small tool @remsim-apitool.py@
205
** download @remsim-apitool.py@
206
<pre>
207 23 laforge
wget https://gitea.osmocom.org/sim-card/osmo-remsim/src/branch/master/contrib/osmo-remsim-apitool
208 6 tsaitgaist
</pre>
209
** 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.
210 5 tsaitgaist
<pre>
211 23 laforge
python3 osmo-remsim-apitool --create-slotmap 1 1 1 1
212 5 tsaitgaist
</pre>
213 15 tsaitgaist
# @osmo-remsim@ uses PCSC to access card readers (this setup only needs to be done once)
214
** connect external card readers to host (any USB CCID reader should do the job)
215
** ensure cards are present in the card readers
216
** get reader name (use CTRL-C to exit)
217 1 tsaitgaist
<pre>
218 15 tsaitgaist
pcsc_scan 
219
220
Using reader plug'n play mechanism
221
Scanning present readers...
222
0: OMNIKEY 6321 CLi USB (OKCM0030506091345044320140749730) 00 00
223 7 tsaitgaist
</pre>
224 15 tsaitgaist
** 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.
225 7 tsaitgaist
<pre>
226 19 emvivre
cat << EOF > bankd_pcsc_slots.csv
227 15 tsaitgaist
"1","1","OMNIKEY 6321 CLi USB (OKCM0030506091345044320140749730) 00 00"
228
EOF
229 7 tsaitgaist
</pre>
230 15 tsaitgaist
# 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.
231 6 tsaitgaist
** install @osmo-remsim-bankd@:
232 5 tsaitgaist
<pre>
233 6 tsaitgaist
sudo apt install osmo-remsim-bankd
234
</pre>
235 13 tsaitgaist
** 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)
236 6 tsaitgaist
<pre>
237 5 tsaitgaist
osmo-remsim-bankd --server-host localhost --server-port 9998 --bank-id 1
238 1 tsaitgaist
</pre>
239
# now we need to actually emulate the card
240
** power off phone
241
** insert card adapter cable into phone
242 5 tsaitgaist
** insert card adapter cable SIMtrace v2 board
243
** plug SIMtrace v2 board in host computer USB port
244 6 tsaitgaist
** install @osmo-remsim-client@:
245
<pre>
246
sudo apt install osmo-remsim-client
247
</pre>
248 5 tsaitgaist
** get SIMtrace USB path (this step will soon be not required anymore)
249
<pre>
250
dfu-util -l
251
252
...
253
Found Runtime: [1d50:60e3] ver=0002, devnum=59, cfg=1, intf=1, path="1-2.2", alt=0, name="UNKNOWN", serial="UNKNOWN"
254
</pre>
255
** 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).
256
<pre>
257 20 emvivre
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-ip localhost --server-port 9998
258 5 tsaitgaist
</pre>
259
** you can now power on the phone, and should see some APDU traffic on the client and bankd.
260 1 tsaitgaist
261
h2. Limitations
262
263
Here are the known limitations:
264
* 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).
265
* 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)
266
* 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
267
* the error messages returned by @simtrace2-remsim@ are not very useful
268
* @simtrace2-remsim@ does not automatically reconnect to the SIMtrace board when the hardware is reset
269
* you have to specify the USB path to @simtrace2-remsim@
270
* no long term tests have been performed (this is already planned)
271 2 tsaitgaist
* you can't use the card reader built in SIMtrace
272 4 tsaitgaist
* @simtrace2-remsim@ does not send the APDU to GSMTAP so you can trace the traffic using wireshark
273 2 tsaitgaist
* @simtrace2-remsim-udp@ does not connect to SIMtrace v2 boards
274 1 tsaitgaist
275
We are currently working on resolving these issues.
276
If you found yet unknown issues, you can report them to the main developer at kredon AT sysmocom DOT de.
277
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)