| 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 | |
| 39 | === remsim-server |
| 40 | |
| 41 | The remsim-server is the central element of the osmo-remsim |
| 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 | |
| 47 | The tasks of remsim-server include: |
| 48 | |
| 49 | * accepting incoming TCP control connections from remsim-client and |
| 50 | remsim-bankd instances |
| 51 | * providing a RESTful JSON interface for external application logic to |
| 52 | |
| 53 | === remsim-client |
| 54 | |
| 55 | The remsim-client software is co-located next to a cellular phone/modem. |
| 56 | It typically runs on an [embedded] computer next to the phone/modem. |
| 57 | |
| 58 | The tasks of remsim-client include: |
| 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 |
| 63 | * establishing a TCP connection with the remsim-server, in order to |
| 64 | enable the server to issue control commands |
| 65 | * under control of remsim-server, establishing a TCP connection to a |
| 66 | remsim-bankd in order to connect a card physically located at the |
| 67 | bankd. |
| 68 | |
| 69 | remsim-client supports at this point only one phone/modem. If you have |
| 70 | multiple phones/modems at one location, you can simply run multiple |
| 71 | instances of remsim-client on the same system, one for each phone/modem. |
| 72 | |
| 73 | === remsim-bankd |
| 74 | |
| 75 | The remsim-bankd software is co-located next to a bank of SIM cards. |
| 76 | |
| 77 | The tasks of remsim-bankd include: |
| 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. |
| 81 | * establishing a TCP connection with the remsim-server, in order to |
| 82 | enable the server to issue control commands |
| 83 | * running a TCP server where TCP connections from remsim-client |
| 84 | instances are accepted and handled. |
| 85 | |
| 86 | |