Project

General

Profile

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.
Add picture from clipboard (Maximum size: 48.8 MB)