[[hlr]] == OsmoNITB HLR subsystem As OsmoNITB is a fully autonomous system, it also includes a minimal/simplistic HLR and AUC. Compared to real GSM networks, it does not implement any of the external interfaces of a real HLR, such as the MAP/TCAP/SCCP protocol. It can only be used inside the OsmoNITB. While functionally maintaining the subscriber database and authentication keys, it offers a much reduced feature set. For example, it is not possible to configure bearer service permission lists, or BAOC. At this time, the only supported database back end for the OsmoNITB internal HLR/AUC is the file-based SQL database SQLite3. === Authorization Policy Authorization determines how subscribers can access your network. This is unrelated to authentication, which verifies the authenticity of SIM cards that register with the network. OsmoNITB supports three different authorization policies: closed:: This mode requires subscribers to have a record with their IMSI in the HLR, and it requires that their status is set to `authorized 1` + This reflects the most typical operation of GSM networks, where subscribers have to obtain a SIM card issued by the operator. At the time the SIM gets issued, it is provisioned in the HLR to enable the subscriber to use the services of the network. accept-all:: This policy accepts any and all subscribers that every try to register to the network. Non-existent subscribers are automatically and dynamically created in the HLR, and they immediately have full access to the network. Any IMSI can register, no matter what SIM card they are using in their phones. + This mode is mostly useful for lab testing or for demonstrating the lack of mutual authentication and the resulting security problems in the GSM system. NOTE: As you do not know the Ki of dynamically created subscribers with SIM cards of unknown origin, you cannot use cryptographic authentication and/or encryption! CAUTION: Never run a network in accept-all mode, unless you know exactly what you are doing. You are very likely causing service interruption to mobile phones in the coverage area of your BTSs, which is punishable under criminal law in most countries! token:: This method was created for special-purpose configurations at certain events. It tries to combine the benefits of automatic enrollment with foreign IMSI while trying to prevent causing disruption to phones that register to the network by accident. + This policy is currently not actively supported. The currently active policy can be selected using the `auth policy (closed|accept-all|token)` at the `network` configuration node of the VTY. === Location Update Reject Cause When a 'Location Update Request' is to be rejected by the network (e.g. due to an unknown or unauthorized subscriber), the 'Location Update Reject' message will contain a 'Reject Cause'. You can configure the numeric value of that cause by means of the `location updating reject cause <2-111>` command at the network node. === Querying information about a subscriber Information about a specific subscriber can be obtained from the HLR by issuing `show subscriber` command. For example, to display information about a subscriber with the IMSI 602022080345046, you can use the following command: .Displaying information about a subscriber ---- OpenBSC> show subscriber imsi 602022080345046 ID: 1, Authorized: 1 <1> Name: 'Frank' Extension: 2342 <2> LAC: 1/0x1 <3> IMSI: 602022080345046 TMSI: 4DB8B4D8 Pending: 0 Use count: 1 ---- <1> Whether or not the subscriber is authorized for access <2> OsmoNITB is often treated like a PBX, this is why phone numbers are called extensions <3> The Location Area Code (LAC) indicates where in the network the subscriber has last performed a LOCATION UPDATE. Detached subscribers indicate a LAC of 0. Subscribers don't have to be identified/referenced by their IMSI, but they can also be identified by their extension (phone number), their TMSI as well as their internal database ID. Example alternatives showing the same subscriber record are: ---- OpenBSC> show subscriber id 1 ---- or ---- OpenBSC> show subscriber extension 2342 ---- === Enrolling a subscriber A subscriber can be added to the network in different ways: . authorizing an auto-generated subscriber . manually creating a subscriber using VTY commands . manually creating subscriber by insert into SQL database by external program ==== Authorizing an auto-generated subscriber If the `subscriber-create-on-demand` configuration option is set in the `nitb` VTY config node, then OsmoNITB will automatically create a subscriber record for every IMSI that ever tries to perform a LOCATION UPDATE with the network. However, those subscriber records are marked as "not authorized", i.e. they will not be able to use your network. You can latter on _authorize_ any such a subscriber using the `subscriber IMSI ... authorized 1` command at the VTY enable node. .Example: Authorizing an auto-generated subscriber ---- OpenBSC> enable OpenBSC# configure terminal OpenBSC(config)# nitb OpenBSC(config-nitb)# subscriber-create-on-demand <1> OpenBSC(config-nitb)# end OpenBSC# <2> OpenBSC# subscriber imsi 262420123456789 authorized 1 <3> ---- <1> We first ensure that `subscriber-create-on-demand` is active <2> At this time we ensure that the MS with IMSI 262420123456789 performs a location update to our network, e.g. by powering up the associated phone followed by manual operator selection <3> Here we authorize that ISMI The above method implies that you know the IMSI stored on the SIM card of the subscriber that you want to to authorize. Unfortunately there is no easy/standard way to obtain the IMSI on most phones. If the phone has an AT-command interface, you may try `AT+CIMI`. You can also read the IMSI off the SIM using a PC-attached smart card reader. NOTE: Contrary to classic GSM networks and for historic reasons, this behavior is the default behavior of OsmoNITB. For production networks with a closed subscriber base, it is strongly recommended to use the `no subscriber-create-on-demand` option at the `nitb` VTY config node. ==== Manually creating a subscriber from the VTY You can manually add a subscriber to the HLR by VTY commands. To do so, yo will need to know at the minimum the IMSI of the subscriber. .Example: Create a new subscriber for IMSI 262429876543210 ---- OpenBSC# subscriber create imsi 262429876543210 ID: 3, Authorized: 0 <1> Extension: 22150 <2> LAC: 0/0x0 <3> IMSI: 262429876543210 Expiration Time: Thu, 01 Jan 1970 01:00:00 +0100 Paging: not paging Requests: 0 Use count: 1 OpenBSC# subscriber imsi 262429876543210 authorized 1 <4> OpenBSC# subscriber imsi 262429876543210 extension 23234242 <5> OpenBSC# subscriber imsi 262429876543210 name Sub Scriber <6> OpenBSC# show subscriber imsi 262429876543210 <7> ID: 3, Authorized: 1 Name: 'Sub Scriber' Extension: 23234242 LAC: 0/0x0 IMSI: 262429876543210 Expiration Time: Thu, 01 Jan 1970 01:00:00 +0100 Paging: not paging Requests: 0 Use count: 1 ---- <1> as you can see, a newly-created subscriber is not automatically authorized. We will change this in the next step. <2> the NITB has automatically allocated a random 5-digit extension (MSISDN) <3> Location Area Code 0 means that this subscriber is currently not registered on the network <4> Authorize the subscriber <5> Change the extension (MSISDN) to 23234242 (optional) <6> Give the subscriber a human-readable name (optional) <7> Review the content of your new subscriber record NOTE: If you are running a network with A5 encryption enabled, you must also configure the secret key (Ki) of the SIM card in the HLR. You can change further properties on your just-created subscriber as explained in <>. ==== Creating subscribers in the SQL database In most applications, the network operator issues his own SIM cards, and the subscriber records corresponding to each SIM will be pre-provisioned by direct insertion into the SQL database. This is performed long before the SIM cards are issued towards the actual end-users. This can be done by a custom program, the SQL schema is visible from the `.schema` command on the sqlite3 command-line program, and there are several scripts included in the OpenBSC source code, written in both Python as well as Perl language. In case you are obtaining a starter kit with pre-provisioned SIM cards from sysmocom: They will ship with a HLR SQL database containing the subscriber records. ==== Provisioning SIM cards In most applications, the operator obtains pre-provisioned SIM cards from a SIM card supplier. If you prefer to provision the SIM cards yourself, you can use the pySim tool available from http://cgit.osmocom.org/cgit/pysim/. It has the ability to append the newly-provisioned SIM cards to an existing HLR database, please check its `--write-hlr` command line argument. [[hlr-subscr-properties]] === Changing subscriber properties Once a subscriber exists in the HLR, his properties can be set interactively from the VTY. Modifying subscriber properties requires the VTY to be in the privileged (`enable`) mode. All commands are single-line commands and always start with identifying the subscriber on which the operation shall be performed. Such identification can be performed by * IMSI * TMSI * extension number * ID (internal identifier) ==== Changing the subscriber phone number You can set the phone number of the subscriber with IMSI 602022080345046 to 12345 by issuing the following VTY command from the enable node: .Changing the phone number of a subscriber ---- OpenBSC# subscriber imsi 602022080345046 extension 12345 ---- ==== Changing the subscriber name The subscriber name is an internal property of OsmoNITB. The name will never be transmitted over the air interface or used by the GSM protocol. The sole purpose of the name is to make log output more intuitive, as human readers of log files tend to remember names easier than IMSIs or phone numbers. In order to set the name of subscriber with extension number 12345 to "Frank", you can issue the following command on the VTY enable node: `subscriber extension 12345 name Frank` The name may contain spaces and special characters. You can verify the modified subscriber record by issuing the `show subscriber extension 12345` command. ==== Changing the authorization status As the HLR automatically adds records for all subscribers it sees, those that are actually permitted to use the network have to be authorized by setting the authorized property of the subscriber. You can set the authorized property by issuing the following VTY command from the enable node: .Authorizing a subscriber ---- OpenBSC# subscriber extension 12345 authorized 1 ---- Similarly, you can remove the authorized status from a subscriber by issuing the following command: .Un-authorizing a subscriber ---- OpenBSC# subscriber extension 12345 authorized 0 ---- ==== Changing the GSM authentication algorithm and Ki In order to perform cryptographic authentication of the subscriber, his Ki needs to be known to the HLR/AUC. Furthermore, the authentication algorithm implemented on the SIM card (A3/A8) must match that of the algorithm configured in the HLR. Currently, OsmoNITB supports the following authentication algorithms: none:: No authentication is performed xor:: Authentication is performed using the XOR algorithm (for test/debugging purpose) comp128v1:: Authentication is performed according to the COMP128v1 algorithm WARNING: None of the supported authentication algorithms are cryptographically very strong. Development is proceeding to include support for stronger algorithms like GSM-MILENAGE. Please contact sysmocom if you require strong authentication support. In order to configure a subscriber for COMP128v1 and to set his Ki, you can use the following VTY command from the enable node: .Configuring a subscriber for COMP128v1 and setting Ki ---- OpenBSC# subscriber extension 2342 a3a8 comp128v1 000102030405060708090a0b0c0d0e0f ----