[[remism-client]] == osmo-remsim-client-st2 The client interfaces with GSM phones / modems via dedicated "Card Emulation" devices such as the Osmocom SIMtrace2 or sysmocom sysmoQMOD board + firmware. This hardware implements the ISO7816-3 electrical interface and protocol handling and passes any TPDU headers received from the phone/modem to `osmo-remsim-client` for further processing of the TPDUs associated to the given APDU transfer. `osmo-remsim-client` connects via a RSPRO control connection to `osmo-remsim-server` at startup and registers itself. It will receive configuration data such as the `osmo-remsim-bankd` IP+Port and the ClientId from `osmo-remsim-server`. After receiving the configuration, `osmo-remsim-client` will establish a RSPRO data connection to the `osmo-remsim-bankd` IP:Port. As the USB interface for remote SIM in simtrace2.git uses one interface per slot, we can implement the client in blocking mode, i.e. use blocking I/O on the TCP/RSPRO side. This simplifies the code compared to a more complex async implementation. [graphviz] .Overall osmo-remsim architecture using osmo-remsim-client-st2 ---- graph G { rankdir = LR; subgraph cluster_0 { label = "Client"; modem [label="Phone/Modem",shape="rectangle"]; cardem [label="cardem firmware\ne.g. on sysmoQMOD",shape="rectangle"]; client [label="remsim-client-st2"]; modem -- cardem [label="ISO 7816-3"]; cardem -- client [label="USB ST2"]; } subgraph cluster_2 { label = "SIM Bank"; bankd [label="remsim-bankd"]; reader [label="Card Reader\ne.g. sysmoOCTSIM",shape="rectangle"]; b_pcscd [label="PC/SC Daemon\nlibccid driver"]; bankd -- b_pcscd; b_pcscd -- reader [label = "USB CCID"]; } subgraph cluster_1 { label = "Server/Backend"; server [label="remsim-server"]; backend [label="Back-End Application"]; server -- backend [label="REST Interface"]; } client -- bankd [label="RSPRO Data"]; client -- server [label="RSPRO Control"]; bankd -- server [label="RSPRO Control"]; } ---- === Running osmo-remsim-client-st2 currently has the following command-line options: ==== SYNOPSIS *osmo-remsim-client-st2* [...] ==== OPTIONS *-h, --help*:: Print a short help message about the supported options *-V, --version*:: Print the software version number *-d, --debug LOGOPT*:: Configure the logging verbosity, see <>. *-i, --server-ip A.B.C.D*:: Specify the remote IP address / hostname of the `osmo-remsim-server` to which this client shall establish its RSPRO control connection *-p, --server-port <1-65535>*:: Specify the remote TCP port number of the `osmo-remsim-server` to which this client shall establish its RSPRO control connection *-c, --client-id <1-1023>*:: Specify the numeric client identifier of the SIM bank this bankd instance operates. The tuple of client-id and client-slot must be unique among all clients connecting to the same `osmo-remsim-server`. *-n, --client-slot <0-1023>*:: Specify the slot number served within this client. The tuple of client-id and client-slot must be unique among all clients connecting to the same `osmo-remsim-server`. *-a, --atr HEXSTRING*:: Specify the initial ATR to be communicated to the modem/phone. Can and will later be overridden by the ATR as specified by `osmo-remsim-bankd` once a card has been mapped to this client, unless the `--atr-ignore-rspro` option is also specified. *-r, --atr-ignore-rspro*:: Ignore any incoming RSPRO setAtrReq and always only use the locally-specified ATR when communicating with the UE/modem/phone. This can be used to constrain the capabilities advertised. This way, for example, the baud rate can be constrained, or the use of logical channels prevented. *-e, --event-script COMMAND*:: Specify the shell command to be execute when the client wants to call its helper script *-V, --usb-vendor*:: Specify the USB Vendor ID of the USB device served by this client, use e.g. 0x1d50 for SIMtrace2, sysmoQMOD and OWHW. *-P, --usb-product*:: Specify the USB Product ID of the USB device served by this client, use e.g. 0x4004 for sysmoQMOD. *-C, --usb-config*:: Specify the USB Cofiguration number of the USB device served by this client. Default will use current configuration of the device. *-I, --usb-interface*:: Specify the USB Interface number (within active configuration) of the USB device served by this client. Default will use FIXME. *-S, --usb-altsetting*:: Specify the USB Alternate Setting to be used within the USB Interface of the USB device served by this client. Default will use FIXME. *-A, --usb-address <0-255>*:: Specify the USB Address of the USB device served by this client. This is useful in case multiple identical USB devices are attached to the same host. However, the address changed at every re-enumeration and it's therefor recommended to use the USB path (see below). *-H, --usb-path*:: Specify the USB path of the USB device served by this client. This is usefule to disambiguate between multiple identical USB devices attached to the same host. You don't need this if you have only one SIM emulation device attached to your system. ==== Examples .remsim-server is on 10.2.3.4, sysmoQMOD on usb bus, all 4 modems: ---- 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 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 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 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 ---- === Logging `osmo-remsim-client` currently logs to stdout only, and the logging verbosity is not yet configurable. However, as the libosmocore logging framework is used, extending this is an easy modification. === Helper Script `osmo-remsim-client` can call an external shell command / script / program at specific instances of time. This serves two purposes: * To keep external system integration posted about the overall status of remsim-client, such as whether or not it is connected to a server and/or bankd. * To request the external system to perform specific actions, such as triggering the reset of the modem - in case the hardware doesn't allow the simtrace2 firmware to do that itself. ==== Script Environment Variables The environment passed to the helper script contains a number of variables to provide inormation to the external script: .Environment Variables [options="header",cols="27%,18%,55%"] |=== | Name | Example Value | Description | REMSIM_CLIENT_VERSION | 0.2.2.37-5406a | Compile version of the software | REMSIM_SERVER_ADDR | 1.2.3.4:1234 | Address and port of the remsim-server | REMSIM_SERVER_STATE | CONNECTED | FSM state of the connection to remsim-server | REMSIM_BANKD_ADDR | 1.2.3.4:1234 | Address and port of the remsim-bankd | REMSIM_BANKD_STATE | CONNECTED | FSM state of the connection to remsim-bankd | REMSIM_CLIENT_SLOT | 23:42 | Client ID and Client Slot Number | REMSIM_BANKD_SLOT | 55:33 | Bank ID and Bank Slot Number | REMSIM_USB_PATH | 2-1.1 | USB path of the USB device with simtrace2 cardem firmware | REMSIM_USB_INTERFACE | 1 | Interface number of the USB device with simtrace2 cardem firmware | REMSIM_SIM_VCC | 1 | Whether or not the modem currently applies SIM VCC (0/1) | REMSIM_SIM_RST | 1 | Whether or not the modem currently asserts SIM RST (0=inactive, 1=active) | REMSIM_CAUSE | request-card-insert | The cause why this script has been called |=== ==== REMSIM_CAUSE values The REMSIM_CAUSE environment variable (as well as the first argument) passed to the helper script indicated why the script has been called. [options="header",cols="25%,75%"] |=== | Name | Description | event-modem-status | The SIM card interface status has changed (e.g. VCC/RST change) | event-bankd-connect | A logical RSPRO connection to a bankd has been established | event-server-connect | A logical RSPRO connection to a server has been established | event-config-bankd | The server has instructed the client of the bankd address | request-card-insert | The client asks the system to simulate SIM card insertion to the modem | request-card-remove | The client asks the system to simulate SIM card removal from the modem | request-sim-remote | The client asks the system to switch to remote SIM | request-sim-local | The client asks the system to switch to local SIM | request-modem-reset | The client asks the system to perform a modem reset |=== == osmo-remsim-client-shell This is a remsim-client that's mostly useful for manual debugging/testing or automatic testing. Instead of using hardware like the SIMtrace with cardem firmware to interface a virtual SIM card to a real phone or modem, it simply offers and interactive way to exchange APDUs with a remote SIM card via STDIO of the process. This allows testing of large parts of the osmo-remsim-client code as well as the integration with the overall osmo-remsim network including osmo-remsim-server, osmo-remsim-bankd and any external backend application driving the REST interface. === Running osmo-remsim-client-shell currently has the following command-line options: ==== SYNOPSIS *osmo-remsim-client-shell* [...] ==== OPTIONS *-h, --help*:: Print a short help message about the supported options *-v, --version*:: Print the compile-time version information *-d, --debug LOGOPT*:: Configure the logging verbosity, see <>. *-i, --server-ip A.B.C.D*:: Specify the remote IP address / hostname of the `osmo-remsim-server` to which this client shall establish its RSPRO control connection *-p, --server-port <1-65535>*:: Specify the remote TCP port number of the `osmo-remsim-server` to which this client shall establish its RSPRO control connection *-c, --client-id <1-1023>*:: Specify the numeric client identifier of the SIM bank this bankd instance operates. The tuple of client-id and client-slot must be unique among all clients connecting to the same `osmo-remsim-server`. *-n, --client-slot <0-1023>*:: Specify the slot number served within this client. The tuple of client-id and client-slot must be unique among all clients connecting to the same `osmo-remsim-server`. `osmo-remsim-bankd` once a card has been mapped to this client. *-e, --event-script COMMAND*:: Specify the shell command to be execute when the client wants to call its helper script ==== Examples The below example uses stderr-redirection to avoid the log output cluttering the console. .remsim-server is at 192.168.11.10; we are client 23 slot 0 ---- ./osmo-remsim-client-shell -i 192.168.11.10 -c 23 2>/dev/null SET_ATR: 3b 00 SET_ATR: 3b 7d 94 00 00 55 55 53 0a 74 86 93 0b 24 7c 4d 54 68 a0a40000023f00 R-APDU: 9f 17 ---- * The first SET_ATR is performed by osmo-remsim-client locally using a default ATR * The second SET_ATR is performed by osmo-remsim-bankd to inform us about the ATR of the real remote card * The `a0a40000023f00` is a command TPDU entered on STDIN by the suer * The `9f17` is a response TPDU provided by the remote card in response to the command The program continues in this loop (read command APDU as hex-dump from stdin; provide response on stdout) until it is terminated by Ctrl+C or by other means. == libifd_remsim_client This is a remsim-client implemented as so-called `ifd_handler`, i.e. a card reader driver that plugs into the bottom side of the PC/SC daemon of pcsc-lite. Using this library, you can use normal smart card application programs with remote smart cards managed by osmo-remsim. The setup looks like this: [graphviz] .Overall osmo-remsim architecture using libifd_remsim_client ---- graph G { rankdir = LR; subgraph cluster_0 { label = "Client"; application [label="Any application\nusing PC/SC"]; pcscd [label="PC/SC Daemon\nlibifd_remsim_client driver"]; application -- pcscd; } subgraph cluster_2 { label = "SIM Bank"; bankd [label="remsim-bankd"]; reader [label="Card Reader\ne.g. sysmoOCTSIM",shape="rectangle"]; b_pcscd [label="PC/SC Daemon\nlibccid driver"]; bankd -- b_pcscd; b_pcscd -- reader [label = "USB CCID"]; } subgraph cluster_1 { label = "Server/Backend"; server [label="remsim-server"]; backend [label="Back-End Application"]; server -- backend [label="REST Interface"]; } pcscd -- bankd [label="RSPRO Data"]; pcscd -- server [label="RSPRO Control"]; bankd -- server [label="RSPRO Control"]; } ---- === Configuration Like all non-USB PC/SC reader drivers, this is happening in `/etc/reader.conf` or, at least on Debian GNU/Linux based systems via files in `/etc/reader.conf.d`. The osmo-remsim software includes an example configuration file and installs it as `osmo-remsim-client-reader_conf` in that directory. .contents of the configuration example provided by osmo-remsim-client ---- #FRIENDLYNAME "osmo-remsim-client" #DEVICENAME 0:0:192.168.11.10:9998 #LIBPATH /usr/lib/pcsc/drivers/libifd-osmo-remsim-client.bundle/Contents/Linux/libifd_remsim_client.so ---- As you can see, all lines are commented out by default. In order to enable the remsim-client virtual reader, you need to * remove the `#` character on all three lines * configure the DEVICNAME according to your local configuration. It is a string with fields separated by colons, in the form of CLIENT_ID:CLIENT_SLOT:SERVER_IP:SERVER_PORRT ** First part is the Client ID (default: 0) ** Second part is the Client SlotNumbera (default: 0) ** Third part is the IP address of the `osmo-resim-server` (default: localhost) ** Last part is the RSPRO TCP port of the `osmo-remsim-server` (default: 9998) Once the configuration file has been updated, you should re-start pcscd by issuing `systemctl restart pcscd` or whatever command your Linux distribution uses for restarting services. You can check if the driver is loaded by using the `pcsc_scan` tool included with `pcscd`: ---- $ pcsc_scan Using reader plug'n play mechanism Scanning present readers... 0: osmo-remsim-client 00 00 Wed Mar 4 13:31:42 2020 Reader 0: osmo-remsim-client 00 00 Event number: 0 Card state: Card removed, - ---- Once a proper slotmap to an existing SIM card in a remote bank daemon has been installed in the server, you should see something like this: ---- $ pcsc_scan Using reader plug'n play mechanism Scanning present readers... 0: osmo-remsim-client 00 00 Wed Mar 4 13:35:18 2020 Reader 0: osmo-remsim-client 00 00 Event number: 1 Card state: Card inserted, ATR: 3B 7D 94 00 00 55 55 53 0A 74 86 93 0B 24 7C 4D 54 68 ATR: 3B 7D 94 00 00 55 55 53 0A 74 86 93 0B 24 7C 4D 54 68 + TS = 3B --> Direct Convention + T0 = 7D, Y(1): 0111, K: 13 (historical bytes) TA(1) = 94 --> Fi=512, Di=8, 64 cycles/ETU 62500 bits/s at 4 MHz, fMax for Fi = 5 MHz => 78125 bits/s TB(1) = 00 --> VPP is not electrically connected TC(1) = 00 --> Extra guard time: 0 + Historical bytes: 55 55 53 0A 74 86 93 0B 24 7C 4D 54 68 Category indicator byte: 55 (proprietary format) Possibly identified card (using /home/laforge/.cache/smartcard_list.txt): NONE ---- From now on, you can use any application using PC/SC, whether C, Python or Java with a remote SIM card managed by osmo-remsim.