Harald Welte | 5103ea0 | 2020-03-04 15:31:58 +0100 | [diff] [blame^] | 1 | [[remism-client]] |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 2 | == osmo-remsim-client-st2 |
Harald Welte | 5bae20b | 2019-04-01 09:36:42 +0200 | [diff] [blame] | 3 | |
Harald Welte | 35f2b20 | 2019-04-01 11:01:51 +0200 | [diff] [blame] | 4 | The client interfaces with GSM phones / modems via dedicated "Card |
| 5 | Emulation" devices such as the Osmocom SIMtrace2 or sysmocom sysmoQMOD |
| 6 | board + firmware. This hardware implements the ISO7816-3 electrical |
| 7 | interface and protocol handling and passes any TPDU headers received |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 8 | from the phone/modem to `osmo-remsim-client` for further processing of |
| 9 | the TPDUs associated to the given APDU transfer. |
Harald Welte | 35f2b20 | 2019-04-01 11:01:51 +0200 | [diff] [blame] | 10 | |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 11 | `osmo-remsim-client` connects via a RSPRO control connection to |
| 12 | `osmo-remsim-server` at startup and registers itself. It will receive |
| 13 | configuration data such as the `osmo-remsim-bankd` IP+Port and the |
| 14 | ClientId from `osmo-remsim-server`. |
Harald Welte | 35f2b20 | 2019-04-01 11:01:51 +0200 | [diff] [blame] | 15 | |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 16 | After receiving the configuration, `osmo-remsim-client` will establish a |
| 17 | RSPRO data connection to the `osmo-remsim-bankd` IP:Port. |
Harald Welte | 35f2b20 | 2019-04-01 11:01:51 +0200 | [diff] [blame] | 18 | |
| 19 | As the USB interface for remote SIM in simtrace2.git uses one interface |
| 20 | per slot, we can implement the client in blocking mode, i.e. use |
| 21 | blocking I/O on the TCP/RSPRO side. This simplifies the code compared |
| 22 | to a more complex async implementation. |
| 23 | |
Harald Welte | 8c0adf6 | 2020-03-04 15:16:47 +0100 | [diff] [blame] | 24 | [graphviz] |
| 25 | .Overall osmo-remsim architecture using osmo-remsim-client-st2 |
| 26 | ---- |
| 27 | graph G { |
| 28 | rankdir = LR; |
| 29 | |
| 30 | subgraph cluster_0 { |
| 31 | label = "Client"; |
| 32 | modem [label="Phone/Modem",shape="rectangle"]; |
| 33 | cardem [label="cardem firmware\ne.g. on sysmoQMOD",shape="rectangle"]; |
| 34 | client [label="remsim-client-st2"]; |
| 35 | modem -- cardem [label="ISO 7816-3"]; |
| 36 | cardem -- client [label="USB ST2"]; |
| 37 | } |
| 38 | |
| 39 | subgraph cluster_2 { |
| 40 | label = "SIM Bank"; |
| 41 | bankd [label="remsim-bankd"]; |
| 42 | reader [label="Card Reader\ne.g. sysmoOCTSIM",shape="rectangle"]; |
| 43 | b_pcscd [label="PC/SC Daemon\nlibccid driver"]; |
| 44 | bankd -- b_pcscd; |
| 45 | b_pcscd -- reader [label = "USB CCID"]; |
| 46 | } |
| 47 | |
| 48 | subgraph cluster_1 { |
| 49 | label = "Server/Backend"; |
| 50 | server [label="remsim-server"]; |
| 51 | backend [label="Back-End Application"]; |
| 52 | server -- backend [label="REST Interface"]; |
| 53 | } |
| 54 | |
| 55 | client -- bankd [label="RSPRO Data"]; |
| 56 | client -- server [label="RSPRO Control"]; |
| 57 | bankd -- server [label="RSPRO Control"]; |
| 58 | } |
| 59 | ---- |
| 60 | |
| 61 | |
| 62 | |
Harald Welte | 5bae20b | 2019-04-01 09:36:42 +0200 | [diff] [blame] | 63 | === Running |
| 64 | |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 65 | osmo-remsim-client-st2 currently has the following command-line options: |
Harald Welte | 5bae20b | 2019-04-01 09:36:42 +0200 | [diff] [blame] | 66 | |
| 67 | ==== SYNOPSIS |
| 68 | |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 69 | *osmo-remsim-client-st2* [...] |
Harald Welte | 5bae20b | 2019-04-01 09:36:42 +0200 | [diff] [blame] | 70 | |
| 71 | ==== OPTIONS |
| 72 | |
| 73 | *-h, --help*:: |
| 74 | Print a short help message about the supported options |
| 75 | *-s, --server-host A.B.C.D*:: |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 76 | Specify the remote IP address / hostname of the `osmo-remsim-server` to |
| 77 | which this client shall establish its RSPRO control connection |
Harald Welte | 5bae20b | 2019-04-01 09:36:42 +0200 | [diff] [blame] | 78 | *-p, --server-port <1-65535>*:: |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 79 | Specify the remote TCP port number of the `osmo-remsim-server` to which |
| 80 | this client shall establish its RSPRO control connection |
Harald Welte | 5bae20b | 2019-04-01 09:36:42 +0200 | [diff] [blame] | 81 | *-c, --client-id <1-65535>*:: |
| 82 | Specify the numeric client identifier of the SIM bank this bankd |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 83 | instance operates. The tuple of client-id and client-slot must be |
| 84 | unique among all clients connecting to the same `osmo-remsim-server`. |
Harald Welte | 5bae20b | 2019-04-01 09:36:42 +0200 | [diff] [blame] | 85 | *-n, --client-slot <0-65535>*:: |
| 86 | Specify the slot number served within this client. The tuple of |
| 87 | client-id and client-slot must be unique among all clients connecting |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 88 | to the same `osmo-remsim-server`. |
Harald Welte | 5bae20b | 2019-04-01 09:36:42 +0200 | [diff] [blame] | 89 | *-i, --gsmtap-ip A.B.C.D*:: |
| 90 | Specify the IP address (if any) to which APDU traces are sent in |
| 91 | GSMTAP format (useful for debugging; supported by wireshark). |
| 92 | *-k, --keep-running*:: |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 93 | Specify if the `osmo-remsim-client` should terminate after handling one |
Harald Welte | 5bae20b | 2019-04-01 09:36:42 +0200 | [diff] [blame] | 94 | session, or whether it should keep running. Fast respawn (i.e. no |
| 95 | --keep-running) is probably the more robust option at this point. |
| 96 | *-V, --usb-vendor*:: |
| 97 | Specify the USB Vendor ID of the USB device served by this client, |
| 98 | use e.g. 0x1d50 for SIMtrace2, sysmoQMOD and OWHW. |
| 99 | *-P, --usb-product*:: |
| 100 | Specify the USB Product ID of the USB device served by this client, |
| 101 | use e.g. 0x4004 for sysmoQMOD. |
| 102 | *-C, --usb-config*:: |
| 103 | Specify the USB Cofiguration number of the USB device served by this |
| 104 | client. Default will use current configuration of the device. |
| 105 | *-I, --usb-interface*:: |
| 106 | Specify the USB Interface number (within active configuration) of the |
| 107 | USB device served by this client. Default will use FIXME. |
| 108 | *-S, --usb-altsetting*:: |
| 109 | Specify the USB Alternate Setting to be used within the USB Interface |
| 110 | of the USB device served by this client. Default will use FIXME. |
| 111 | *-A, --usb-address <0-255>*:: |
| 112 | Specify the USB Address of the USB device served by this client. This |
| 113 | is useful in case multiple identical USB devices are attached to the |
| 114 | same host. However, the address changed at every re-enumeration and |
| 115 | it's therefor recommended to use the USB path (see below). |
| 116 | *-H, --usb-path*:: |
| 117 | Specify the USB path of the USB device served by this client. This is |
| 118 | usefule to disambiguate between multiple identical USB devices |
| 119 | attached to the same host. You don't need this if you have only one |
| 120 | SIM emulation device attached to your system. |
| 121 | *-a, --atr HEXSTRING*:: |
| 122 | Specify the initial ATR to be communicated to the modem/phone. Can |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 123 | and will later be overridden by the ATR as specified by |
| 124 | `osmo-remsim-bankd` once a card has been mapped to this client. |
Harald Welte | 55c7f44 | 2019-12-17 01:14:43 +0100 | [diff] [blame] | 125 | *-e, --event-script COMMAND*:: |
| 126 | Specify the shell command to be execute when the client wants to call its |
| 127 | helper script |
| 128 | |
Harald Welte | 5bae20b | 2019-04-01 09:36:42 +0200 | [diff] [blame] | 129 | |
Joachim Steiger | 68f9510 | 2019-07-03 19:03:24 +0200 | [diff] [blame] | 130 | ==== Examples |
| 131 | .remsim-server is on 10.2.3.4, sysmoQMOD on usb bus, all 4 modems: |
| 132 | ---- |
| 133 | osmo-remsim-client-st2 -s 10.2.3.4 -V 1d50 -P 4004 -C 1 -I 0 -H 2-1.1 -c 0 -n 0 |
| 134 | osmo-remsim-client-st2 -s 10.2.3.4 -V 1d50 -P 4004 -C 1 -I 1 -H 2-1.1 -c 0 -n 1 |
| 135 | osmo-remsim-client-st2 -s 10.2.3.4 -V 1d50 -P 4004 -C 1 -I 0 -H 2-1.4 -c 0 -n 2 |
| 136 | osmo-remsim-client-st2 -s 10.2.3.4 -V 1d50 -P 4004 -C 1 -I 1 -H 2-1.4 -c 0 -n 3 |
| 137 | ---- |
| 138 | |
Harald Welte | 5bae20b | 2019-04-01 09:36:42 +0200 | [diff] [blame] | 139 | === Logging |
| 140 | |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 141 | `osmo-remsim-client` currently logs to stdout only, and the logging |
| 142 | verbosity is not yet configurable. However, as the libosmocore logging |
| 143 | framework is used, extending this is an easy modification. |
Harald Welte | 55c7f44 | 2019-12-17 01:14:43 +0100 | [diff] [blame] | 144 | |
| 145 | === Helper Script |
| 146 | |
| 147 | `osmo-remsim-client` can call an external shell command / script / program at specific |
| 148 | instances of time. This serves two purposes: |
| 149 | |
| 150 | * To keep external system integration posted about the overall status of remsim-client, |
| 151 | such as whether or not it is connected to a server and/or bankd. |
| 152 | * To request the external system to perform specific actions, such as triggering the reset |
| 153 | of the modem - in case the hardware doesn't allow the simtrace2 firmware to do that itself. |
| 154 | |
| 155 | ==== Script Environment Variables |
| 156 | |
| 157 | The environment passed to the helper script contains a number of variables to provide inormation |
| 158 | to the external script: |
| 159 | |
| 160 | .Environment Variables |
| 161 | [options="header",cols="27%,18%,55%"] |
| 162 | |=== |
| 163 | | Name | Example Value | Description |
| 164 | | REMSIM_CLIENT_VERSION | 0.2.2.37-5406a | Compile version of the software |
| 165 | | REMSIM_SERVER_ADDR | 1.2.3.4:1234 | Address and port of the remsim-server |
| 166 | | REMSIM_SERVER_STATE | CONNECTED | FSM state of the connection to remsim-server |
| 167 | | REMSIM_BANKD_ADDR | 1.2.3.4:1234 | Address and port of the remsim-bankd |
| 168 | | REMSIM_BANKD_STATE | CONNECTED | FSM state of the connection to remsim-bankd |
| 169 | | REMSIM_CLIENT_SLOT | 23:42 | Client ID and Client Slot Number |
| 170 | | REMSIM_BANKD_SLOT | 55:33 | Bank ID and Bank Slot Number |
| 171 | | REMSIM_USB_PATH | 2-1.1 | USB path of the USB device with simtrace2 cardem firmware |
| 172 | | REMSIM_USB_INTERFACE | 1 | Interface number of the USB device with simtrace2 cardem firmware |
| 173 | | REMSIM_SIM_VCC | 1 | Whether or not the modem currently applies SIM VCC (0/1) |
| 174 | | REMSIM_SIM_RST | 1 | Whether or not the modem currently asserts SIM RST (0=inactive, 1=active) |
| 175 | | REMSIM_CAUSE | request-card-insert | The cause why this script has been called |
| 176 | |=== |
| 177 | |
| 178 | ==== REMSIM_CAUSE values |
| 179 | |
| 180 | The REMSIM_CAUSE environment variable (as well as the first argument) passed to the helper |
| 181 | script indicated why the script has been called. |
| 182 | |
| 183 | [options="header",cols="25%,75%"] |
| 184 | |=== |
| 185 | | Name | Description |
| 186 | | event-modem-status | The SIM card interface status has changed (e.g. VCC/RST change) |
| 187 | | event-bankd-connect | A logical RSPRO connection to a bankd has been established |
| 188 | | event-server-connect | A logical RSPRO connection to a server has been established |
| 189 | | event-config-bankd | The server has instructed the client of the bankd address |
| 190 | | request-card-insert | The client asks the system to simulate SIM card insertion to the modem |
| 191 | | request-card-remove | The client asks the system to simulate SIM card removal from the modem |
| 192 | | request-sim-remote | The client asks the system to switch to remote SIM |
| 193 | | request-sim-local | The client asks the system to switch to local SIM |
| 194 | | request-modem-reset | The client asks the system to perform a modem reset |
| 195 | |=== |
Harald Welte | a8e2db9 | 2020-03-04 13:11:16 +0100 | [diff] [blame] | 196 | |
| 197 | == osmo-remsim-client-shell |
| 198 | |
| 199 | This is a remsim-client that's mostly useful for manual debugging/testing or automatic testing. |
| 200 | |
| 201 | Instead of using hardware like the SIMtrace with cardem firmware to interface a virtual SIM card |
| 202 | to a real phone or modem, it simply offers and interactive way to exchange APDUs with a remote |
| 203 | SIM card via STDIO of the process. |
| 204 | |
| 205 | This allows testing of large parts of the osmo-remsim-client code as well as the integration with |
| 206 | the overall osmo-remsim network including osmo-remsim-server, osmo-remsim-bankd and any external |
| 207 | backend application driving the REST interface. |
| 208 | |
| 209 | === Running |
| 210 | |
| 211 | osmo-remsim-client-shell currently has the following command-line options: |
| 212 | |
| 213 | ==== SYNOPSIS |
| 214 | |
| 215 | *osmo-remsim-client-shell* [...] |
| 216 | |
| 217 | ==== OPTIONS |
| 218 | |
| 219 | *-h, --help*:: |
| 220 | Print a short help message about the supported options |
| 221 | *-v, --version*:: |
| 222 | Print the compile-time version information |
| 223 | *-i, --server-ip A.B.C.D*:: |
| 224 | Specify the remote IP address / hostname of the `osmo-remsim-server` to |
| 225 | which this client shall establish its RSPRO control connection |
| 226 | *-p, --server-port <1-65535>*:: |
| 227 | Specify the remote TCP port number of the `osmo-remsim-server` to which |
| 228 | this client shall establish its RSPRO control connection |
| 229 | *-c, --client-id <1-65535>*:: |
| 230 | Specify the numeric client identifier of the SIM bank this bankd |
| 231 | instance operates. The tuple of client-id and client-slot must be |
| 232 | unique among all clients connecting to the same `osmo-remsim-server`. |
| 233 | *-n, --client-slot <0-65535>*:: |
| 234 | Specify the slot number served within this client. The tuple of |
| 235 | client-id and client-slot must be unique among all clients connecting |
| 236 | to the same `osmo-remsim-server`. |
| 237 | `osmo-remsim-bankd` once a card has been mapped to this client. |
| 238 | *-e, --event-script COMMAND*:: |
| 239 | Specify the shell command to be execute when the client wants to call its |
| 240 | helper script |
| 241 | |
| 242 | ==== Examples |
| 243 | |
| 244 | The below example uses stderr-redirection to avoid the log output cluttering the console. |
| 245 | |
| 246 | .remsim-server is at 192.168.11.10; we are client 23 slot 0 |
| 247 | ---- |
| 248 | ./osmo-remsim-client-shell -i 192.168.11.10 -c 23 2>/dev/null |
| 249 | SET_ATR: 3b 00 |
| 250 | SET_ATR: 3b 7d 94 00 00 55 55 53 0a 74 86 93 0b 24 7c 4d 54 68 |
| 251 | a0a40000023f00 |
| 252 | R-APDU: 9f 17 |
| 253 | ---- |
| 254 | |
| 255 | * The first SET_ATR is performed by osmo-remsim-client locally using a default ATR |
| 256 | * The second SET_ATR is performed by osmo-remsim-bankd to inform us about the ATR of the real remote card |
| 257 | * The `a0a40000023f00` is a command TPDU entered on STDIN by the suer |
| 258 | * The `9f17` is a response TPDU provided by the remote card in response to the command |
| 259 | |
| 260 | The program continues in this loop (read command APDU as hex-dump from stdin; provide response on stdout) |
| 261 | until it is terminated by Ctrl+C or by other means. |
Harald Welte | 9fac496 | 2020-02-14 21:01:23 +0100 | [diff] [blame] | 262 | |
| 263 | == libifd_remsim_client |
| 264 | |
| 265 | This is a remsim-client implemented as so-called `ifd_handler`, i.e. a card reader driver |
| 266 | that plugs into the bottom side of the PC/SC daemon of pcsc-lite. |
| 267 | |
| 268 | Using this library, you can use normal smart card application programs with remote smart |
| 269 | cards managed by osmo-remsim. The setup looks like this: |
| 270 | |
| 271 | [graphviz] |
| 272 | .Overall osmo-remsim architecture using libifd_remsim_client |
| 273 | ---- |
| 274 | graph G { |
| 275 | rankdir = LR; |
| 276 | |
| 277 | subgraph cluster_0 { |
| 278 | label = "Client"; |
| 279 | application [label="Any application\nusing PC/SC"]; |
| 280 | pcscd [label="PC/SC Daemon\nlibifd_remsim_client driver"]; |
| 281 | application -- pcscd; |
| 282 | } |
| 283 | |
| 284 | subgraph cluster_2 { |
| 285 | label = "SIM Bank"; |
| 286 | bankd [label="remsim-bankd"]; |
| 287 | reader [label="Card Reader\ne.g. sysmoOCTSIM",shape="rectangle"]; |
| 288 | b_pcscd [label="PC/SC Daemon\nlibccid driver"]; |
| 289 | bankd -- b_pcscd; |
| 290 | b_pcscd -- reader [label = "USB CCID"]; |
| 291 | } |
| 292 | |
| 293 | subgraph cluster_1 { |
| 294 | label = "Server/Backend"; |
| 295 | server [label="remsim-server"]; |
| 296 | backend [label="Back-End Application"]; |
| 297 | server -- backend [label="REST Interface"]; |
| 298 | } |
| 299 | |
| 300 | pcscd -- bankd [label="RSPRO Data"]; |
| 301 | pcscd -- server [label="RSPRO Control"]; |
| 302 | bankd -- server [label="RSPRO Control"]; |
| 303 | } |
| 304 | ---- |
| 305 | |
| 306 | |
| 307 | === Configuration |
| 308 | |
| 309 | Like all non-USB PC/SC reader drivers, this is happening in `/etc/reader.conf` or, at |
| 310 | least on Debian GNU/Linux based systems via files in `/etc/reader.conf.d`. The |
| 311 | osmo-remsim software includes an example configuration file and installs it as |
| 312 | `osmo-remsim-client-reader_conf` in that directory. |
| 313 | |
| 314 | .contents of the configuration example provided by osmo-remsim-client |
| 315 | ---- |
| 316 | #FRIENDLYNAME "osmo-remsim-client" |
| 317 | #DEVICENAME 0:0:192.168.11.10:9998 |
| 318 | #LIBPATH /usr/lib/pcsc/drivers/libifd-osmo-remsim-client.bundle/Contents/Linux/libifd_remsim_client.so |
| 319 | ---- |
| 320 | |
| 321 | As you can see, all lines are commented out by default. In order to enable the |
| 322 | remsim-client virtual reader, you need to |
| 323 | |
| 324 | * remove the `#` character on all three lines |
| 325 | * configure the DEVICNAME according to your local configuration. It is a string with |
| 326 | fields separated by colons, in the form of CLIENT_ID:CLIENT_SLOT:SERVER_IP:SERVER_PORRT |
| 327 | ** First part is the Client ID (default: 0) |
| 328 | ** Second part is the Client SlotNumbera (default: 0) |
| 329 | ** Third part is the IP address of the `osmo-resim-server` (default: localhost) |
| 330 | ** Last part is the RSPRO TCP port of the `osmo-remsim-server` (default: 9998) |
| 331 | |
| 332 | Once the configuration file has been updated, you should re-start pcscd by issuing |
| 333 | `systemctl restart pcscd` or whatever command your Linux distribution uses for restarting |
| 334 | services. |
| 335 | |
| 336 | You can check if the driver is loaded by using the `pcsc_scan` tool included with `pcscd`: |
| 337 | |
| 338 | ---- |
| 339 | $ pcsc_scan |
| 340 | Using reader plug'n play mechanism |
| 341 | Scanning present readers... |
| 342 | 0: osmo-remsim-client 00 00 |
| 343 | |
| 344 | Wed Mar 4 13:31:42 2020 |
| 345 | Reader 0: osmo-remsim-client 00 00 |
| 346 | Event number: 0 |
| 347 | Card state: Card removed, |
| 348 | - |
| 349 | ---- |
| 350 | |
| 351 | Once a proper slotmap to an existing SIM card in a remote bank daemon has been installed |
| 352 | in the server, you should see something like this: |
| 353 | |
| 354 | ---- |
| 355 | $ pcsc_scan |
| 356 | Using reader plug'n play mechanism |
| 357 | Scanning present readers... |
| 358 | 0: osmo-remsim-client 00 00 |
| 359 | |
| 360 | Wed Mar 4 13:35:18 2020 |
| 361 | Reader 0: osmo-remsim-client 00 00 |
| 362 | Event number: 1 |
| 363 | Card state: Card inserted, |
| 364 | ATR: 3B 7D 94 00 00 55 55 53 0A 74 86 93 0B 24 7C 4D 54 68 |
| 365 | |
| 366 | ATR: 3B 7D 94 00 00 55 55 53 0A 74 86 93 0B 24 7C 4D 54 68 |
| 367 | + TS = 3B --> Direct Convention |
| 368 | + T0 = 7D, Y(1): 0111, K: 13 (historical bytes) |
| 369 | TA(1) = 94 --> Fi=512, Di=8, 64 cycles/ETU |
| 370 | 62500 bits/s at 4 MHz, fMax for Fi = 5 MHz => 78125 bits/s |
| 371 | TB(1) = 00 --> VPP is not electrically connected |
| 372 | TC(1) = 00 --> Extra guard time: 0 |
| 373 | + Historical bytes: 55 55 53 0A 74 86 93 0B 24 7C 4D 54 68 |
| 374 | Category indicator byte: 55 (proprietary format) |
| 375 | |
| 376 | Possibly identified card (using /home/laforge/.cache/smartcard_list.txt): |
| 377 | NONE |
| 378 | ---- |
| 379 | |
| 380 | From now on, you can use any application using PC/SC, whether C, Python or Java with a |
| 381 | remote SIM card managed by osmo-remsim. |