2019-03-31 16:55:18 +00:00
|
|
|
== Overview
|
|
|
|
|
|
|
|
=== About this manual
|
|
|
|
|
|
|
|
This manual should help you getting started with the osmo-remsim software.
|
|
|
|
|
|
|
|
It will cover aspects of configuration and running osmo-remsim as well as some
|
|
|
|
introduction about its internal architecture and external interfaces.
|
|
|
|
|
|
|
|
=== About osmo-remsim
|
|
|
|
|
|
|
|
osmo-remsim is a suite of software programs enabling physical/geographic
|
|
|
|
separation of a cellular phone (or modem) on the one hand side and the
|
|
|
|
SIM/USIM/ISIM card on the other side.
|
|
|
|
|
|
|
|
Using osmo-remsim, you can operate an entire fleet of modems/phones, as
|
|
|
|
well as banks of SIM cards and dynamically establish or remove the
|
|
|
|
connections between modems/phones and cards.
|
|
|
|
|
|
|
|
So in technical terms, it behaves like a proxy for the ISO 7816 smart
|
|
|
|
card interface between the MS/UE and the UICC/SIM/USIM/ISIM.
|
|
|
|
|
|
|
|
While originally designed to be used in context of cellular networks,
|
|
|
|
there is nothing cellular specific in the system. It can therefore also
|
|
|
|
be used with other systems that use contact based smart cards according
|
|
|
|
to ISO 7816. Currently only the T=0 protocol with standard
|
|
|
|
(non-extended) APDUs is supported. Both T=1 and extended APDU support
|
|
|
|
can easily be added as a pure software update, should it be required at
|
|
|
|
some future point.
|
|
|
|
|
|
|
|
=== Credits
|
|
|
|
|
|
|
|
osmo-remsim was originally developed by Harald Welte with contributions
|
|
|
|
by Kevin Redon. It builds on top of pre-existing infrastructure of
|
|
|
|
the Osmocom project, including the Osmocom SIMtrace project.
|
|
|
|
|
|
|
|
Development of osmo-remsim software was funded by GSMK and sysmocom.
|
|
|
|
|
2019-04-03 07:18:44 +00:00
|
|
|
=== osmo-remsim-server
|
2019-03-31 16:55:18 +00:00
|
|
|
|
2019-04-03 07:18:44 +00:00
|
|
|
The `osmo-remsim-server` is the central element of the osmo-remsim
|
2019-03-31 16:55:18 +00:00
|
|
|
architecture. All other elements connect to it. It maintains the
|
|
|
|
inventory of other network elements, as well as the list of
|
|
|
|
slot-mappings, i.e. the relationship between each given physical card
|
|
|
|
in a bank and each card emulator attached to a phone/modem.
|
|
|
|
|
2019-04-03 07:18:44 +00:00
|
|
|
The tasks of `osmo-remsim-server` include:
|
2019-03-31 16:55:18 +00:00
|
|
|
|
2019-04-03 07:18:44 +00:00
|
|
|
* accepting incoming TCP control connections from `osmo-remsim-client` and
|
|
|
|
`osmo-remsim-bankd` instances
|
2019-03-31 16:55:18 +00:00
|
|
|
* providing a RESTful JSON interface for external application logic to
|
|
|
|
|
2020-03-04 14:31:58 +00:00
|
|
|
For more information, please see <<remsim-server>>.
|
|
|
|
|
2019-04-03 07:18:44 +00:00
|
|
|
=== osmo-remsim-client
|
2019-03-31 16:55:18 +00:00
|
|
|
|
2020-03-04 14:24:07 +00:00
|
|
|
The `osmo-remsim-client` software is co-located next to the _user of the card_
|
|
|
|
which traditionally is a phone or modem. However, there are other flavors
|
|
|
|
of clients available, too. This is for example useful if existing software
|
|
|
|
wants to interface remote smart cards, rather than those physically inserted
|
|
|
|
into a local reader next to the PC running that application.
|
|
|
|
|
|
|
|
In the classic phone / modem use case, osmo-remsim-client
|
|
|
|
typically runs on an [embedded] computer next to the phone/modem.
|
2019-03-31 16:55:18 +00:00
|
|
|
|
2019-04-03 07:18:44 +00:00
|
|
|
The tasks of `osmo-remsim-client` include:
|
2019-03-31 16:55:18 +00:00
|
|
|
|
2020-03-04 14:24:07 +00:00
|
|
|
* interaction with the user application. For phone/modem, that's
|
|
|
|
over USB with a device supported by the 'SIMtrace2 cardem'
|
2019-03-31 16:55:18 +00:00
|
|
|
firmware, which provides the physical interface to the phone/modem SIM
|
2020-03-04 14:24:07 +00:00
|
|
|
interface (ISO 7816-3).
|
2019-04-03 07:18:44 +00:00
|
|
|
* establishing a TCP connection with the `osmo-remsim-server`, in order to
|
2019-03-31 16:55:18 +00:00
|
|
|
enable the server to issue control commands
|
2019-04-03 07:18:44 +00:00
|
|
|
* under control of `osmo-remsim-server`, establishing a TCP connection to a
|
|
|
|
`osmo-remsim-bankd` in order to connect a card physically located at the
|
2019-03-31 16:55:18 +00:00
|
|
|
bankd.
|
|
|
|
|
2019-04-03 07:18:44 +00:00
|
|
|
`osmo-remsim-client` supports at this point only one phone/modem. If you have
|
2019-03-31 16:55:18 +00:00
|
|
|
multiple phones/modems at one location, you can simply run multiple
|
2019-04-03 07:18:44 +00:00
|
|
|
instances of `osmo-remsim-client` on the same system, one for each phone/modem.
|
2019-03-31 16:55:18 +00:00
|
|
|
|
2020-03-04 14:31:58 +00:00
|
|
|
For more information, please see <<remsim-client>>.
|
|
|
|
|
2019-04-03 07:18:44 +00:00
|
|
|
=== osmo-remsim-bankd
|
2019-03-31 16:55:18 +00:00
|
|
|
|
2019-04-03 07:18:44 +00:00
|
|
|
The `osmo-remsim-bankd` software is co-located next to a bank of SIM cards.
|
2019-03-31 16:55:18 +00:00
|
|
|
|
2019-04-03 07:18:44 +00:00
|
|
|
The tasks of `osmo-remsim-bankd` include:
|
2019-03-31 16:55:18 +00:00
|
|
|
|
|
|
|
* interaction with the actual card reader hardware. At this point, only
|
|
|
|
PC/SC based readers are supported, with 1 to 255 slots per reader.
|
2019-04-03 07:18:44 +00:00
|
|
|
* establishing a TCP connection with the `osmo-remsim-server`, in order to
|
2019-03-31 16:55:18 +00:00
|
|
|
enable the server to issue control commands
|
2019-04-03 07:18:44 +00:00
|
|
|
* running a TCP server where TCP connections from `osmo-remsim-client`
|
2019-03-31 16:55:18 +00:00
|
|
|
instances are accepted and handled.
|
|
|
|
|
2020-03-04 14:31:58 +00:00
|
|
|
For more information, please see <<remsim-bankd>>.
|
|
|
|
|
2022-07-11 20:29:40 +00:00
|
|
|
=== osmo-remsim-apitool
|
2020-03-04 14:48:49 +00:00
|
|
|
|
2022-07-11 20:29:40 +00:00
|
|
|
The `osmo-remsim-apitool` utility is an optional tool that can be used to
|
2020-03-04 14:48:49 +00:00
|
|
|
manually interface with the RSRES interface of `osmo-remsim-server` in
|
|
|
|
absence of a back-end system managing this.
|
|
|
|
|
|
|
|
For more information, please see <<remsim-apitool>>.
|
|
|
|
|
2020-03-04 14:31:58 +00:00
|
|
|
=== RSPRO
|
|
|
|
|
|
|
|
RSPRO is the *R*emote *S*IM *PRO*tocol. It is a binary protocol
|
|
|
|
specified in ASN.1 which is spoken on any of the internal connections
|
|
|
|
between `osmo-remsim-client`, `osmo-remsim-bankd` and
|
|
|
|
`osmo-remsim-server`.
|
|
|
|
|
|
|
|
You can find more information about RSPRO in <<rspro>>.
|
|
|
|
|
|
|
|
=== RSRES
|
|
|
|
|
|
|
|
RSRES is the *R*emote *S*IM *RES*T protocol. It is an interface offered
|
|
|
|
by `osmo-remsim-server` towards external back-end application logic of
|
|
|
|
the operator of an osmo-remsim network.
|
|
|
|
|
|
|
|
You can find more information about RSRES in <<rsres>>.
|
|
|
|
|
|
|
|
=== Security
|
2019-03-31 16:55:18 +00:00
|
|
|
|
2020-03-04 14:31:58 +00:00
|
|
|
WARNING: RSPRO, RSRES and their underlying transport layer both operate in plain-text,
|
|
|
|
There is no authentication or encryption built into the protocol. It is
|
|
|
|
assumed that the protocols are only spoken over trusted, controlled IP
|
|
|
|
networks, such as inside a VPN or a closed / private corporate network.
|