| [[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 <<hlr-subscr-properties>>. |
| |
| ==== 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 |
| ---- |
| |