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 | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 53 | === osmo-remsim-client |
Harald Welte | 3c4d006 | 2019-03-31 18:55:18 +0200 | [diff] [blame] | 54 | |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 55 | The `osmo-remsim-client` software is co-located next to a cellular phone/modem. |
Harald Welte | 3c4d006 | 2019-03-31 18:55:18 +0200 | [diff] [blame] | 56 | It typically runs on an [embedded] computer next to the phone/modem. |
| 57 | |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 58 | The tasks of `osmo-remsim-client` include: |
Harald Welte | 3c4d006 | 2019-03-31 18:55:18 +0200 | [diff] [blame] | 59 | |
| 60 | * interaction over USB with a device supported by the 'SIMtrace2 cardem' |
| 61 | firmware, which provides the physical interface to the phone/modem SIM |
| 62 | interface |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 63 | * establishing a TCP connection with the `osmo-remsim-server`, in order to |
Harald Welte | 3c4d006 | 2019-03-31 18:55:18 +0200 | [diff] [blame] | 64 | enable the server to issue control commands |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 65 | * under control of `osmo-remsim-server`, establishing a TCP connection to a |
| 66 | `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] | 67 | bankd. |
| 68 | |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 69 | `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] | 70 | multiple phones/modems at one location, you can simply run multiple |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 71 | 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] | 72 | |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 73 | === osmo-remsim-bankd |
Harald Welte | 3c4d006 | 2019-03-31 18:55:18 +0200 | [diff] [blame] | 74 | |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 75 | 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] | 76 | |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 77 | The tasks of `osmo-remsim-bankd` include: |
Harald Welte | 3c4d006 | 2019-03-31 18:55:18 +0200 | [diff] [blame] | 78 | |
| 79 | * interaction with the actual card reader hardware. At this point, only |
| 80 | 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] | 81 | * establishing a TCP connection with the `osmo-remsim-server`, in order to |
Harald Welte | 3c4d006 | 2019-03-31 18:55:18 +0200 | [diff] [blame] | 82 | enable the server to issue control commands |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 83 | * running a TCP server where TCP connections from `osmo-remsim-client` |
Harald Welte | 3c4d006 | 2019-03-31 18:55:18 +0200 | [diff] [blame] | 84 | instances are accepted and handled. |
| 85 | |
| 86 | |