path: root/OsmoNITB/chapters/hlr.adoc

[[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
----