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