diff options
Diffstat (limited to 'manuals/OsmoNITB/chapters/hlr.adoc')
| -rw-r--r-- | manuals/OsmoNITB/chapters/hlr.adoc | 331 |
1 files changed, 331 insertions, 0 deletions
diff --git a/manuals/OsmoNITB/chapters/hlr.adoc b/manuals/OsmoNITB/chapters/hlr.adoc new file mode 100644 index 000000000..8f2840a6e --- /dev/null +++ b/manuals/OsmoNITB/chapters/hlr.adoc @@ -0,0 +1,331 @@ +[[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 +---- + |