== 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>>.

=== osmo-remsim-apitool

The `osmo-remsim-apitool` 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.