Cardem » History » Version 23
laforge, 07/25/2022 07:16 AM
gitea
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 | 23 | laforge | sudo wget -O /etc/udev/rules.d/99-simtrace2.rules https://gitea.osmocom.org/sim-card/simtrace2/src/branch/master/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. |