GSM with Osmocom Part 7: The HLR – Home Location Register (and Friends)

OsmoHLR - Update Location Request

The Home Location Register serves the AAA functions in a GSM / UMTS (2G/3G) network as well as locating which Mobile Switching Center (MSC) a subscriber is being served by.

The HLR is the equivalent of the Home Subscriber Server in LTE (I’ve written a fair bit about the role of the HSS in LTE networks, and I’ve published my own open-source HSS software.)


One obvious need is to authenticate our subscribers so the network can verify their identity,

The IMSI (International Mobile Subscriber Identity) is used to identifier the user from all the other mobile subscribers worldwide. The IMSI is exposed to the user, but transmitting the IMSI in the clear is typically something that’s avoided where possible on the air interface.

GSM uses a single shared secret between the SIM and the network (the K key) for authentication. This shared secret is not exposed to the user and is never transmitted over the air.

When a user wants to authenticate, the HSS network takes a Random key (RAND) and mixes it with the secret key (K) to generate a Signed Response called SRES. The network sends the RAND key to the subscriber, and their SIM takes the secret key (K) and mixes it with the RAND value from the network, before sending their signed response (SRES) back to the network.
If the SRES sent by the subscriber matches the SRES generated by the HSS, then the user is authenticated. The set of keys used for one authentication session is referred to as an Authentication Vector or Authentication Tuple.

In Osmocom the generation of Authentication Tuples is requested in the GSUP “SendAuthInfo” request, and responded to by the “SendAuthInfoResponse” sent to the HLR by the MSC.

Side note about GSM Security

In a GSM setting the network only authenticates the subscribers, the subscribers don’t authenticate the network. In practice, this means there’s no way to verify in GSM if the network you’re connected to is the network it’s claiming to be.

Due to this shortfall and the cryptographic weakness in A5/x algorithm, 3GPP specified the AKA algorithm for mutual network authentication in 3G/UMTS networks.

I’ve written a fair bit about the role of SIMs for authentication in LTE which is the same scheme used in 3G/UMTS if you’d like to learn more.

LTE USIM Authentication - Mutual Authentication of the Network and Subscriber

Technically the generation of Authentication Vectors is handled by an Authentication Center (AuC) however OsomoHLR has an internal AuC that handles this internally.

Location Tracking

After a user has authenticated, the MSC sends an UpdateLocationRequest via GSUP to the HLR to let it know the current location of the subscriber is served by that MSC.

The Update Location Request is sent at the start of the session, periodic Update Location Requests can be sent based on the timers configured, and a Cancel Location Request can be sent when the subscriber disconnects from the MSC.

Subscriber Data Information

When the Update Location Request has been sent by the MSC, the HLR sends the MSC the subscriber’s info, and the MSC copies it to it’s own internal HLR called a Visitor Location Register (VLR). The VLR means the MSC doesn’t need to keep querying user data from the HLR.

This is again requseted by the MSC to the HLR via a GSUP request InsertSubscriberData Request which contains:

  • Subscriber’s IMSI
  • Subscriber’s MSISDN (Phone number)
  • Allowed Domains (CS/PS)

Note: In production GSM networks TCAP/MAP is used for communication between the HLR and the MSC. Osmocom uses GSUP for carrying this data instead.

Equipment Identity Register

Because mobiles are expensive they’ve historically been a target for theft.

To try and mitigate this GSMA encourages carriers to implement an Equipment Identity Register (EIR).

The EIR is essentially a database containing IMEIs (The Identifiers of Mobiles / Terminals) and permitting / denying access to the network based on the IMEI.

The idea being if a mobile device / terminal is stolen, it’s IMEI is blacklisted in the EIR and regardless of what SIM is put into it, it’s not permitted to access the network.

When a device connects to the network if configured the MSC will query the EIR (On the HLR in our case) with a Check IMEI Request, and will get a Check IMEI Result either permitting or denying access to the network.

Unfortunately, there is no global stolen IMEI database, meaning if a device is stolen and blocked on MNO X’s network, it may still work on MNO Y’s network if they don’t share stolen IMEI data.

Starting & Configuring OsmoHLR

We actually installed OmsoHLR in the post on Base Station Controllers, so we’ll just need to start the daemon / service:

systemctl start osmo-hlr

I’m going to enable the EIR functionality of the HSS by changing the config of the HLR, this is optional but it’s useful to use the EIR functionality.

Like with our other network elements we’ll use Tenet to interactively configure this one,

[email protected]:/home/nick# telnet localhost 4258
Welcome to the OsmoHLR VTY interface
OsmoHLR> enable
OsmoHLR# configure terminal
OsmoHLR(config)# hlr
OsmoHLR(config-hlr)# store-imei
OsmoHLR(config-hlr)# exit
OsmoHLR(config)# exit
OsmoHLR# copy running-config startup-config

Adding Subscribers to OsmoHLR

But before we go adding subscribers, let’s talk about SIMs.

Okay, I’ve written a lot about SIMs before, but there’s still more to talk about!

There’s really only one peice of information from your SIM we require to add the subscriber to the HLR, and that’s the IMSI – The unique identifier of the subscriber on the SIM. You can typically view the IMSI from your mobile device / terminal.

If you want to authenticate subscribers properly (confirm their identity) and enable encryption on the air interface, you’ll need to know the K key of the SIM, for that you’ll need a programmable SIM card like the Sysmocom programmable SIM cards, (By buying from Sysmocom you’re supporting the Osmocom project too).

So now we’ve got that out of the way, let’s add a subscriber:

We’ll connect to OsmoHLR via Telnet, the port it listens on is 4258:

[email protected]:/home/nick# telnet localhost 4258
Welcome to the OsmoHLR VTY interface
OsmoHLR> enable
OsmoHLR# subscriber imsi 001010000000004 create
OsmoHLR# subscriber imsi 001010000000004 update msisdn 61412341234
OsmoHLR# subscriber imsi 001010000000004 update aud2g comp128v3 ki 465B5CE8B199B49FAA5F0A2EE238A6BC

So I’ve created a subscriber with IMSI 001010000000004 in the HSS and assigned an MSISDN (phone number).

Optionally, if you’re using SIM cards you can program you can set the Ki / K key for authentication using the update aud2g function, if not you can skip that step.

And with that we’ve added our first subscriber, lather rinse repeat with any additional subscribers / SIMs you want to provision.

By default subscribers created using this method have access to both Circuit Switched (Voice and SMS) and Packet Switched (Data) networks. (We haven’t configured Packet Switched services yet)

If you’d like to restrict access to one, both or none of the above options, you can do that by using the subscriber update command to set the services available to those subscribers.

OsmoHLR# subscriber id 3 update network-access-mode cs+ps
OsmoHLR# subscriber id 3 update network-access-mode cs
OsmoHLR# subscriber id 3 update network-access-mode ps
OsmoHLR# subscriber id 3 update network-access-mode none

Creating Subscribers Programmatically

In reality if you’re trying to operate a network it’s not feasible to manually add each subscriber as needed.

If you’re buying SIMs in bulk preconfigured you’ll get sent a file containing the IMSI and Crypto values of each card, and you’d ingest that into your HLR.

We’ve used the Osmocom VTY / Telnet interface in quite a few posts now (hopefully you’re getting comfortable with it) but there’s another interface most Osmocom software has – the Osmocom Control Interface – aimed at providing a uniform way to interface external scripts / programs with Osmocom.

If you’d like to learn more about the Control Interface have a read of the OsmoHLR manual and take a look at this example in Python.

Creating Subscribers on Demand (Optional)

For most scenarios you would pre-provision each SIM in the HLR, if the SIM’s IMSI isn’t in the HLR then it’s access is rejected. However there are some scenarios where you may want to allow anyone to access the network, in this scenario Osmo-HLR features a “Create Subscribers on Demand” function.

This may be useful if you’re setting up a network where you don’t control the SIMs for example.

Let’s say we want to automatically create users with access to voice & data services and assign a 10 digit MSISDN for that subscriber, we can do that with:

OsmoHLR> enable
OsmoHLR# configure terminal
OsmoHLR(config)# hlr
OsmoHLR(config-hlr)# subscriber-create-on-demand 10 cs+ps

Alternatley you may wish to simply add the subscriber to the HLR but not provide any services:

OsmoHLR> enable
OsmoHLR# configure terminal
OsmoHLR(config)# hlr
OsmoHLR(config-hlr)# subscriber-create-on-demand no-msisdn none

Then if you wish to grant access to these users you can use the subscriber update network-access-mode method we talked about earlier to allow services for that user.

Packet Capture

To give some context I’ve attached a packet capture of the connection from the MSC to the HLR for some attach procedures on my lab network.



Leave a Reply