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