Harald Welte | 3c4d006 | 2019-03-31 18:55:18 +0200 | [diff] [blame] | 1 | == Overview |
| 2 | |
| 3 | === About this manual |
| 4 | |
| 5 | This manual should help you getting started with the osmo-remsim software. |
| 6 | |
| 7 | It will cover aspects of configuration and running osmo-remsim as well as some |
| 8 | introduction about its internal architecture and external interfaces. |
| 9 | |
| 10 | === About osmo-remsim |
| 11 | |
| 12 | osmo-remsim is a suite of software programs enabling physical/geographic |
| 13 | separation of a cellular phone (or modem) on the one hand side and the |
| 14 | SIM/USIM/ISIM card on the other side. |
| 15 | |
| 16 | Using osmo-remsim, you can operate an entire fleet of modems/phones, as |
| 17 | well as banks of SIM cards and dynamically establish or remove the |
| 18 | connections between modems/phones and cards. |
| 19 | |
| 20 | So in technical terms, it behaves like a proxy for the ISO 7816 smart |
| 21 | card interface between the MS/UE and the UICC/SIM/USIM/ISIM. |
| 22 | |
| 23 | While originally designed to be used in context of cellular networks, |
| 24 | there is nothing cellular specific in the system. It can therefore also |
| 25 | be used with other systems that use contact based smart cards according |
| 26 | to ISO 7816. Currently only the T=0 protocol with standard |
| 27 | (non-extended) APDUs is supported. Both T=1 and extended APDU support |
| 28 | can easily be added as a pure software update, should it be required at |
| 29 | some future point. |
| 30 | |
| 31 | === Credits |
| 32 | |
| 33 | osmo-remsim was originally developed by Harald Welte with contributions |
| 34 | by Kevin Redon. It builds on top of pre-existing infrastructure of |
| 35 | the Osmocom project, including the Osmocom SIMtrace project. |
| 36 | |
| 37 | Development of osmo-remsim software was funded by GSMK and sysmocom. |
| 38 | |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 39 | === osmo-remsim-server |
Harald Welte | 3c4d006 | 2019-03-31 18:55:18 +0200 | [diff] [blame] | 40 | |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 41 | The `osmo-remsim-server` is the central element of the osmo-remsim |
Harald Welte | 3c4d006 | 2019-03-31 18:55:18 +0200 | [diff] [blame] | 42 | architecture. All other elements connect to it. It maintains the |
| 43 | inventory of other network elements, as well as the list of |
| 44 | slot-mappings, i.e. the relationship between each given physical card |
| 45 | in a bank and each card emulator attached to a phone/modem. |
| 46 | |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 47 | The tasks of `osmo-remsim-server` include: |
Harald Welte | 3c4d006 | 2019-03-31 18:55:18 +0200 | [diff] [blame] | 48 | |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 49 | * accepting incoming TCP control connections from `osmo-remsim-client` and |
| 50 | `osmo-remsim-bankd` instances |
Harald Welte | 3c4d006 | 2019-03-31 18:55:18 +0200 | [diff] [blame] | 51 | * providing a RESTful JSON interface for external application logic to |
| 52 | |
Harald Welte | 5103ea0 | 2020-03-04 15:31:58 +0100 | [diff] [blame] | 53 | For more information, please see <<remsim-server>>. |
| 54 | |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 55 | === osmo-remsim-client |
Harald Welte | 3c4d006 | 2019-03-31 18:55:18 +0200 | [diff] [blame] | 56 | |
Harald Welte | e18069a | 2020-03-04 15:24:07 +0100 | [diff] [blame] | 57 | The `osmo-remsim-client` software is co-located next to the _user of the card_ |
| 58 | which traditionally is a phone or modem. However, there are other flavors |
| 59 | of clients available, too. This is for example useful if existing software |
| 60 | wants to interface remote smart cards, rather than those physically inserted |
| 61 | into a local reader next to the PC running that application. |
| 62 | |
| 63 | In the classic phone / modem use case, osmo-remsim-client |
| 64 | typically runs on an [embedded] computer next to the phone/modem. |
Harald Welte | 3c4d006 | 2019-03-31 18:55:18 +0200 | [diff] [blame] | 65 | |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 66 | The tasks of `osmo-remsim-client` include: |
Harald Welte | 3c4d006 | 2019-03-31 18:55:18 +0200 | [diff] [blame] | 67 | |
Harald Welte | e18069a | 2020-03-04 15:24:07 +0100 | [diff] [blame] | 68 | * interaction with the user application. For phone/modem, that's |
| 69 | over USB with a device supported by the 'SIMtrace2 cardem' |
Harald Welte | 3c4d006 | 2019-03-31 18:55:18 +0200 | [diff] [blame] | 70 | firmware, which provides the physical interface to the phone/modem SIM |
Harald Welte | e18069a | 2020-03-04 15:24:07 +0100 | [diff] [blame] | 71 | interface (ISO 7816-3). |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 72 | * establishing a TCP connection with the `osmo-remsim-server`, in order to |
Harald Welte | 3c4d006 | 2019-03-31 18:55:18 +0200 | [diff] [blame] | 73 | enable the server to issue control commands |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 74 | * under control of `osmo-remsim-server`, establishing a TCP connection to a |
| 75 | `osmo-remsim-bankd` in order to connect a card physically located at the |
Harald Welte | 3c4d006 | 2019-03-31 18:55:18 +0200 | [diff] [blame] | 76 | bankd. |
| 77 | |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 78 | `osmo-remsim-client` supports at this point only one phone/modem. If you have |
Harald Welte | 3c4d006 | 2019-03-31 18:55:18 +0200 | [diff] [blame] | 79 | multiple phones/modems at one location, you can simply run multiple |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 80 | instances of `osmo-remsim-client` on the same system, one for each phone/modem. |
Harald Welte | 3c4d006 | 2019-03-31 18:55:18 +0200 | [diff] [blame] | 81 | |
Harald Welte | 5103ea0 | 2020-03-04 15:31:58 +0100 | [diff] [blame] | 82 | For more information, please see <<remsim-client>>. |
| 83 | |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 84 | === osmo-remsim-bankd |
Harald Welte | 3c4d006 | 2019-03-31 18:55:18 +0200 | [diff] [blame] | 85 | |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 86 | The `osmo-remsim-bankd` software is co-located next to a bank of SIM cards. |
Harald Welte | 3c4d006 | 2019-03-31 18:55:18 +0200 | [diff] [blame] | 87 | |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 88 | The tasks of `osmo-remsim-bankd` include: |
Harald Welte | 3c4d006 | 2019-03-31 18:55:18 +0200 | [diff] [blame] | 89 | |
| 90 | * interaction with the actual card reader hardware. At this point, only |
| 91 | PC/SC based readers are supported, with 1 to 255 slots per reader. |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 92 | * establishing a TCP connection with the `osmo-remsim-server`, in order to |
Harald Welte | 3c4d006 | 2019-03-31 18:55:18 +0200 | [diff] [blame] | 93 | enable the server to issue control commands |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 94 | * running a TCP server where TCP connections from `osmo-remsim-client` |
Harald Welte | 3c4d006 | 2019-03-31 18:55:18 +0200 | [diff] [blame] | 95 | instances are accepted and handled. |
| 96 | |
Harald Welte | 5103ea0 | 2020-03-04 15:31:58 +0100 | [diff] [blame] | 97 | For more information, please see <<remsim-bankd>>. |
Harald Welte | 3c4d006 | 2019-03-31 18:55:18 +0200 | [diff] [blame] | 98 | |
Harald Welte | 830026a | 2020-03-04 15:48:49 +0100 | [diff] [blame] | 99 | === remsim-apitool.py |
| 100 | |
| 101 | The `remsim-apitool.py` utility is an optional tool that can be used to |
| 102 | manually interface with the RSRES interface of `osmo-remsim-server` in |
| 103 | absence of a back-end system managing this. |
| 104 | |
| 105 | For more information, please see <<remsim-apitool>>. |
| 106 | |
Harald Welte | 5103ea0 | 2020-03-04 15:31:58 +0100 | [diff] [blame] | 107 | === RSPRO |
| 108 | |
| 109 | RSPRO is the *R*emote *S*IM *PRO*tocol. It is a binary protocol |
| 110 | specified in ASN.1 which is spoken on any of the internal connections |
| 111 | between `osmo-remsim-client`, `osmo-remsim-bankd` and |
| 112 | `osmo-remsim-server`. |
| 113 | |
| 114 | You can find more information about RSPRO in <<rspro>>. |
| 115 | |
| 116 | === RSRES |
| 117 | |
| 118 | RSRES is the *R*emote *S*IM *RES*T protocol. It is an interface offered |
| 119 | by `osmo-remsim-server` towards external back-end application logic of |
| 120 | the operator of an osmo-remsim network. |
| 121 | |
| 122 | You can find more information about RSRES in <<rsres>>. |
| 123 | |
| 124 | === Security |
| 125 | |
| 126 | WARNING: RSPRO, RSRES and their underlying transport layer both operate in plain-text, |
| 127 | There is no authentication or encryption built into the protocol. It is |
| 128 | assumed that the protocols are only spoken over trusted, controlled IP |
| 129 | networks, such as inside a VPN or a closed / private corporate network. |