381 lines
15 KiB
Plaintext
381 lines
15 KiB
Plaintext
== 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
|
|
*-s, --server-host 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-65535>*::
|
|
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-65535>*::
|
|
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`.
|
|
*-i, --gsmtap-ip A.B.C.D*::
|
|
Specify the IP address (if any) to which APDU traces are sent in
|
|
GSMTAP format (useful for debugging; supported by wireshark).
|
|
*-k, --keep-running*::
|
|
Specify if the `osmo-remsim-client` should terminate after handling one
|
|
session, or whether it should keep running. Fast respawn (i.e. no
|
|
--keep-running) is probably the more robust option at this point.
|
|
*-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.
|
|
*-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.
|
|
*-e, --event-script COMMAND*::
|
|
Specify the shell command to be execute when the client wants to call its
|
|
helper script
|
|
|
|
|
|
==== 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
|
|
*-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-65535>*::
|
|
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-65535>*::
|
|
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.
|