Cardem » History » Version 14
tsaitgaist, 10/01/2019 03:39 PM
add requirements
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 | sudo adduser $USERNAME plugdev |
||
62 | </pre> |
||
63 | # install the udev rules for SIMtrace 2 devices |
||
64 | <pre> |
||
65 | sudo wget -O /etc/udev/rules.d/99-simtrace2.rules https://git.osmocom.org/simtrace2/plain/host/99-simtrace2.rules |
||
66 | </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 | 14 | tsaitgaist | You can download the beta firmware for the SIMtrace board here: attachment:simtrace-cardem-dfu.bin. |
76 | 1 | tsaitgaist | |
77 | To flash the firmware on the board: |
||
78 | <pre> |
||
79 | 9 | tsaitgaist | sudo dfu-util --device 1d50:60e3 --cfg 1 --alt 1 --reset --download simtrace-cardem-dfu.bin |
80 | 1 | tsaitgaist | </pre> |
81 | |||
82 | For more details about the flashing procedure, read [[Flashing#SIMtrace2-board|this article]]. |
||
83 | |||
84 | h2. Software |
||
85 | |||
86 | With the cardem firmware, the SIMtrace v2 board mainly forwards the ISO 7816 card communication over USB. |
||
87 | A software on the host must receive the APDU requests and send the corresponding APDU response. |
||
88 | There are several software available to do that. |
||
89 | Since the USB messages are "specified":https://git.osmocom.org/simtrace2/tree/firmware/libcommon/include/simtrace_prot.h and the software is "open source":https://git.osmocom.org/simtrace2/tree/host, you could implement your own APDU handler. |
||
90 | |||
91 | 11 | tsaitgaist | Following are examples on how to use @simtrace2-remsim@ and @osmo-remsim@: |
92 | * @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. |
||
93 | * @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. |
||
94 | |||
95 | 1 | tsaitgaist | h3. simtrace2-remsim |
96 | |||
97 | @simtrace2-remsim@ is the simplest solution. |
||
98 | If forwards the APDU request/response to/from a PCSC card reader. |
||
99 | |||
100 | To get @simtrace2-remsim@: |
||
101 | * Install required packages to compile the software: |
||
102 | <pre> |
||
103 | sudo apt-get install libusb-1.0-0-dev libosmocore-dev libpcsclite-dev |
||
104 | </pre> |
||
105 | * Get and compile the software: |
||
106 | <pre> |
||
107 | git clone git://git.osmocom.org/simtrace2.git |
||
108 | cd simtrace2/host/ |
||
109 | make |
||
110 | </pre> |
||
111 | |||
112 | To use @simtrace2-remsim@: |
||
113 | 5 | tsaitgaist | # power off phone |
114 | 1 | tsaitgaist | # insert card adapter cable into phone |
115 | # insert card adapter cable SIMtrace v2 board |
||
116 | # plug SIMtrace v2 board in host computer USB port |
||
117 | # connect external card reader to host (any USB CCID reader should do the job) |
||
118 | 12 | tsaitgaist | # ensure a card is present in the reader slot (not in the SIMtrace port) |
119 | 5 | tsaitgaist | # install PCSC daemon (only needs to be done once) |
120 | 1 | tsaitgaist | <pre> |
121 | sudo apt install pcscd |
||
122 | </pre> |
||
123 | # ensure the PCSC daemon is started |
||
124 | <pre> |
||
125 | sudo systemctl start pcscd |
||
126 | </pre> |
||
127 | # install tool to check reader status |
||
128 | <pre> |
||
129 | 3 | tsaitgaist | sudo apt install pcsc-tools |
130 | 1 | tsaitgaist | </pre> |
131 | # check if the card is detected by the reader (use CTRL-C to exit) |
||
132 | <pre> |
||
133 | pcsc_scan |
||
134 | |||
135 | Using reader plug'n play mechanism |
||
136 | Scanning present readers... |
||
137 | 0: OMNIKEY 6321 CLi USB (OKCM0030506091345044320140749730) 00 00 |
||
138 | |||
139 | Tue Sep 10 16:03:49 2019 |
||
140 | Reader 0: OMNIKEY 6321 CLi USB (OKCM0030506091345044320140749730) 00 00 |
||
141 | Event number: 0 |
||
142 | Card state: Card inserted, |
||
143 | ATR: 3B 9F 94 80 1F C7 80 31 E0 73 FE 21 1B 67 01 00 00 04 4D 02 01 99 |
||
144 | </pre> |
||
145 | # get SIMtrace USB path (this step will soon be not required anymore) |
||
146 | <pre> |
||
147 | dfu-util -l |
||
148 | |||
149 | ... |
||
150 | Found Runtime: [1d50:60e3] ver=0002, devnum=59, cfg=1, intf=1, path="1-2.2", alt=0, name="UNKNOWN", serial="UNKNOWN" |
||
151 | </pre> |
||
152 | # start @simtrace2-remsim@ with corresponding USB path (here 1-2.2) |
||
153 | <pre> |
||
154 | ./simtrace2-remsim --usb-vendor 1d50 --usb-product 60e3 --usb-path 1-2.2 --usb-config 1 |
||
155 | |||
156 | (C) 2010-2017, Harald Welte <laforge@gnumonks.org> |
||
157 | (C) 2018, sysmocom -s.f.m.c. GmbH, Author: Kevin Redon <kredon@sysmocom.de> |
||
158 | |||
159 | SCardEstablishContext: OK |
||
160 | |||
161 | SCardListReaders: OK |
||
162 | |||
163 | SCardConnect: OK |
||
164 | |||
165 | <- 01 05 00 00 00 00 09 00 01 |
||
166 | <- 02 02 00 00 00 00 09 00 01 |
||
167 | <= cardem_request_set_atr(3b 00 ) |
||
168 | <- 01 02 00 00 00 00 0b 00 02 3b 00 |
||
169 | <- 02 01 00 00 00 00 0b 00 02 2c 01 |
||
170 | Entering main loop |
||
171 | </pre> |
||
172 | # 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 |
||
173 | <pre> |
||
174 | URB: 01 06 00 00 00 00 13 00 01 00 00 00 05 00 a0 a4 00 00 02 |
||
175 | -> 01 06 00 00 00 00 13 00 01 00 00 00 05 00 a0 a4 00 00 02 |
||
176 | => 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) |
||
177 | <= cardem_request_pb_and_rx(a4, 2) |
||
178 | <- 01 01 00 00 00 00 0f 00 08 00 00 00 01 00 a4 |
||
179 | URB: 01 06 00 00 00 00 10 00 02 00 00 00 02 00 7f 20 |
||
180 | -> 01 06 00 00 00 00 10 00 02 00 00 00 02 00 7f 20 |
||
181 | => DATA: flags=2, 7f 20 : CLA=a0 INS=a4 P1=00 P2=00 P3=02; case=4, lc=2(2), le=0(0) |
||
182 | TX: a0 a4 00 00 02 7f 20 |
||
183 | SCardEndTransaction: OK |
||
184 | |||
185 | RX: 9f 17 |
||
186 | SW=0x9f17, len_rx=0 |
||
187 | <= cardem_request_sw_tx(9f 17) |
||
188 | <- 01 01 00 00 00 00 10 00 06 00 00 00 02 00 9f 17 |
||
189 | URB: 01 06 00 00 00 00 13 00 01 00 00 00 05 00 a0 f2 00 00 17 |
||
190 | -> 01 06 00 00 00 00 13 00 01 00 00 00 05 00 a0 f2 00 00 17 |
||
191 | => 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) |
||
192 | TX: a0 f2 00 00 17 |
||
193 | SCardEndTransaction: OK |
||
194 | </pre> |
||
195 | 5 | tsaitgaist | |
196 | h3. osmo-remsim |
||
197 | |||
198 | "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. |
||
199 | |||
200 | 6 | tsaitgaist | # 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) |
201 | 5 | tsaitgaist | # @osmo-remsim@ uses PCSC to access card readers (this setup only needs to be done once) |
202 | ** connect external card readers to host (any USB CCID reader should do the job) |
||
203 | 12 | tsaitgaist | ** ensure cards are present in the card reader |
204 | 7 | tsaitgaist | ** install PCSC daemon (will also be needed on the host which will run the bankd) |
205 | 5 | tsaitgaist | <pre> |
206 | sudo apt install pcscd |
||
207 | </pre> |
||
208 | ** ensure the PCSC daemon is started |
||
209 | <pre> |
||
210 | sudo systemctl start pcscd |
||
211 | </pre> |
||
212 | ** install tool to get reader name |
||
213 | <pre> |
||
214 | sudo apt install pcsc-tools |
||
215 | </pre> |
||
216 | ** get reader name (use CTRL-C to exit) |
||
217 | <pre> |
||
218 | pcsc_scan |
||
219 | |||
220 | Using reader plug'n play mechanism |
||
221 | Scanning present readers... |
||
222 | 0: OMNIKEY 6321 CLi USB (OKCM0030506091345044320140749730) 00 00 |
||
223 | </pre> |
||
224 | ** 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 | <pre> |
||
226 | echo << EOF > bankd_pcsc_slots.csv |
||
227 | "1","1","OMNIKEY 6321 CLi USB (OKCM0030506091345044320140749730) 00 00" |
||
228 | EOF |
||
229 | </pre> |
||
230 | 6 | tsaitgaist | # run the server. This is the central instance telling the bankd which reader to use, and the client which bankd to contact. |
231 | ** install @osmo-remsim-server@: |
||
232 | 5 | tsaitgaist | <pre> |
233 | 6 | tsaitgaist | sudo apt install osmo-remsim-server |
234 | 5 | tsaitgaist | </pre> |
235 | 6 | tsaitgaist | ** run server (*the @bankd_pcsc_slots.csv@ file must be in the current working directory*) |
236 | 5 | tsaitgaist | <pre> |
237 | osmo-remsim-server |
||
238 | </pre> |
||
239 | # the server needs to be additionally configured through its RESTful interface. For that we will use the small tool @remsim-apitool.py@ |
||
240 | ** download @remsim-apitool.py@ |
||
241 | <pre> |
||
242 | wget https://git.osmocom.org/osmo-remsim/plain/contrib/remsim-apitool.py |
||
243 | 1 | tsaitgaist | </pre> |
244 | 5 | tsaitgaist | ** 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. |
245 | 1 | tsaitgaist | <pre> |
246 | python remsim-apitool.py --create-slotmap 1 1 1 1 |
||
247 | </pre> |
||
248 | # run the bankd. This will contact the server (which can be on another host) to know which card reader it will manage. |
||
249 | 7 | tsaitgaist | ** install PCSC daemon (if not already done) |
250 | <pre> |
||
251 | sudo apt install pcscd |
||
252 | </pre> |
||
253 | ** ensure the PCSC daemon is started |
||
254 | <pre> |
||
255 | sudo systemctl start pcscd |
||
256 | </pre> |
||
257 | 6 | tsaitgaist | ** install @osmo-remsim-bankd@: |
258 | 5 | tsaitgaist | <pre> |
259 | 6 | tsaitgaist | sudo apt install osmo-remsim-bankd |
260 | </pre> |
||
261 | 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) |
262 | 6 | tsaitgaist | <pre> |
263 | 5 | tsaitgaist | osmo-remsim-bankd --server-host localhost --server-port 9998 --bank-id 1 |
264 | 1 | tsaitgaist | </pre> |
265 | # now we need to actually emulate the card |
||
266 | ** power off phone |
||
267 | ** insert card adapter cable into phone |
||
268 | 5 | tsaitgaist | ** insert card adapter cable SIMtrace v2 board |
269 | ** plug SIMtrace v2 board in host computer USB port |
||
270 | 6 | tsaitgaist | ** install @osmo-remsim-client@: |
271 | <pre> |
||
272 | sudo apt install osmo-remsim-client |
||
273 | </pre> |
||
274 | 5 | tsaitgaist | ** get SIMtrace USB path (this step will soon be not required anymore) |
275 | <pre> |
||
276 | dfu-util -l |
||
277 | |||
278 | ... |
||
279 | Found Runtime: [1d50:60e3] ver=0002, devnum=59, cfg=1, intf=1, path="1-2.2", alt=0, name="UNKNOWN", serial="UNKNOWN" |
||
280 | </pre> |
||
281 | ** 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). |
||
282 | <pre> |
||
283 | 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 |
||
284 | </pre> |
||
285 | ** you can now power on the phone, and should see some APDU traffic on the client and bankd. |
||
286 | 1 | tsaitgaist | |
287 | h2. Limitations |
||
288 | |||
289 | Here are the known limitations: |
||
290 | * 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). |
||
291 | * 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) |
||
292 | * 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 |
||
293 | * the error messages returned by @simtrace2-remsim@ are not very useful |
||
294 | * @simtrace2-remsim@ does not automatically reconnect to the SIMtrace board when the hardware is reset |
||
295 | * you have to specify the USB path to @simtrace2-remsim@ |
||
296 | * no long term tests have been performed (this is already planned) |
||
297 | 2 | tsaitgaist | * you can't use the card reader built in SIMtrace |
298 | 4 | tsaitgaist | * @simtrace2-remsim@ does not send the APDU to GSMTAP so you can trace the traffic using wireshark |
299 | 2 | tsaitgaist | * @simtrace2-remsim-udp@ does not connect to SIMtrace v2 boards |
300 | 1 | tsaitgaist | |
301 | We are currently working on resolving these issues. |
||
302 | If you found yet unknown issues, you can report them to the main developer at kredon AT sysmocom DOT de. |
||
303 | 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. |