| == 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. |
| |
| === osmo-remsim-server |
| |
| The `osmo-remsim-server` is the central element of the osmo-remsim |
| 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. |
| |
| The tasks of `osmo-remsim-server` include: |
| |
| * accepting incoming TCP control connections from `osmo-remsim-client` and |
| `osmo-remsim-bankd` instances |
| * providing a RESTful JSON interface for external application logic to |
| |
| For more information, please see <<remsim-server>>. |
| |
| === osmo-remsim-client |
| |
| 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. |
| |
| The tasks of `osmo-remsim-client` include: |
| |
| * interaction with the user application. For phone/modem, that's |
| over USB with a device supported by the 'SIMtrace2 cardem' |
| firmware, which provides the physical interface to the phone/modem SIM |
| interface (ISO 7816-3). |
| * establishing a TCP connection with the `osmo-remsim-server`, in order to |
| enable the server to issue control commands |
| * 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 |
| bankd. |
| |
| `osmo-remsim-client` supports at this point only one phone/modem. If you have |
| multiple phones/modems at one location, you can simply run multiple |
| instances of `osmo-remsim-client` on the same system, one for each phone/modem. |
| |
| For more information, please see <<remsim-client>>. |
| |
| === osmo-remsim-bankd |
| |
| The `osmo-remsim-bankd` software is co-located next to a bank of SIM cards. |
| |
| The tasks of `osmo-remsim-bankd` include: |
| |
| * interaction with the actual card reader hardware. At this point, only |
| PC/SC based readers are supported, with 1 to 255 slots per reader. |
| * establishing a TCP connection with the `osmo-remsim-server`, in order to |
| enable the server to issue control commands |
| * running a TCP server where TCP connections from `osmo-remsim-client` |
| instances are accepted and handled. |
| |
| For more information, please see <<remsim-bankd>>. |
| |
| === remsim-apitool.py |
| |
| The `remsim-apitool.py` utility is an optional tool that can be used to |
| 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>>. |
| |
| === 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 |
| |
| 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. |