UE

August 7, 2025 · View on GitHub

This page describes how the UE developed in this project can be executed and which settings are required for it to connect to the gNB and the core network.

This tutorial is based on the tutorial pages mentioned in the UE/gNB Documentation and the Core Network Documentation and adapts them to the circumstances given here or extends them.

0. Build 5G-Pentest-UE
1. Install prerequisites
2. Build executables
3. Configure UE
4. Add UE to Core Network Database
- Some useful commands to work with the SQL Database
5. Run UE
6. Test if the UE connected correctly to the AMF
- Test the Data Connection from CN to UE
- Test/Use the Data Connection from UE to CN

0. Build 5G-Pentest-UE

First you need to clone this project and execute the create_project.sh script. What this script does is download the OAI UE, checkout the correct tag and apply all changes which create the 5G-Pentest-UE from the normal OAI UE. After that you can start with the following steps.

1. Install prerequisites

cd openairinterface5g/cmake_targets
sudo ./build_oai -I

2. Build executables

sudo ./build_oai --nrUE

3. Configure UE

Basic configuration

The configuration file we use is nrue.uicc.conf. Here the uicc0 part is interesting for us. This configuration file basically describes the information that is stored on the SIM card of a real device and is used by the usim interface.

Most of the following parameters are not listed in the unmodified oai file, as the default values are simply used there. However, I found it better to show and explain all the available parameters in the following. If you need them you can just add them to the file.

So the following is the complete configuration set:

uicc0 = {
  imsi = "208950100001100";
  nmc_size=2;
  key = "fec86ba6eb707ed08905757b1bb44b8f";
  opc= "c42449363bbad02b66d16bc975d77cc1";
  amf = "8000";
  sqn = "000000000020";
  dnn= "oai";
  nssai_sst=1;
  nssai_sd=16777215;
  imeisv="6754567890123413";
}

imsi (International Mobile Subscriber Identity):
- It is important here that the first 5 digits of the IMSI, which consists of MCC:MNC:MSIN, match the core network, i.e. what ever oai-cn5g-fed/docker-compose/docker-compose-basic-nrf.yaml says on oai-amf.environment.PLMN_SUPPORT_MCC and oai-amf.environment.PLMN_SUPPORT_MNC (if they dont change it it should be 208 and 95). This is important because the network name containing these numbers is used as part of the key generation function, and if the UE uses different values than the core network, the keys will not match and the UE will not be able to connect. (The UE obtains the numbers from its IMSI and the core network from its configuration)
nmc_size:
- This parameter is important because the composition of the (SNN) Serving Network Name in the UE code depends on how long the MNC is (servingNetworkName()). The format of this SNN, which is one of the inputs for key generation, is "5G:mnc000.mcc000.3gppnetwork.org". The nmc_size parameter is used in the UE code to know how many digits need to be copied out of the IMSI string, which contains the MNC, into the SNN. nmc_size is very confusing because nmc makes no sense. The parameter should actually be called mnc_size for mobile network code size. However, a typo was apparently made here in the OAI project, which has not yet been corrected.
- Specifications regarding the SNN Format can be found in TS 24.501.
- More information on MNC and MCC can be found here.
key:
- Authentication Key used to authenticate the UE with the CN.
- More information can be found here.
- The key set here will be important in the next step because its part of the information needed there.
opc:
- TODO what is the TOPC Key??? what is it used for?
- "Hexstring of the encrypted TOPC Key. Presence indicates that the provided value (decrypted) shall be used instead of the value derived from TOP and K." TS 29.505
- The key set here will be important in the next step because its part of the information needed there.
amf:
- In this case amf stands for authentication management field
  - The specifications (TS 33.501) have two entry for amf in the abbreviations part, but in this case authentication management field is meant.
- The number set here will be important in the next step because its part of the information needed there.
- The amf has something to do with the authentication procedure, but i am not sure what it does exactly, so i just kept it as it is set per default in usim_interface.c. TODO
sqn:
- This is a sequence number needed in the authentication procedure.
- The number set here will be important in the next step because its part of the information needed there.
dnn:
- DNN stands for Data Network Name
- The DNN for the various network slices defined in the core network can be found in the CN docker-compose file under oai-smf.environment at DNN_NI.
nssai_sst/sd:
- nssai stands for network slice selection assistance information and is used to identify network slices
  - sst thereby stands for slice/service type -> selects eMBB/URLLC/MIoT/V2X or HMTC 5g modes
  - sd stands for service differentiator -> used if multiple network slices have the same sst value
  - more information about nssai_sst and nssai_sd can be found here
  - for those parameters you can enter every network slice defined in the CN docker-compose file (oai-cn5g-fed/docker-compose/docker-compose-basic-nrf.yaml). However, it is important that the dnn parameter is adjusted accordingly, otherwise the PDU session establishment will not work.
imeisv/imei (International Mobile Equipment Identity Software Version):
- The IMEI identifies a device, with a SIM slot or eSIM capability. If a device has dual SIM capability it has 2 IMEI numbers

Where can i configure the used Ciphering and Integrity Algorithms?

I'm not sure where to configure on the UE side which ciphering algorithm to prioritize. The method I found to activate ciphering is to switch the supported algorithms to the desired one in the gNB settings. The exact steps are described in the gNB Setup Tutorial.

Where can i configure the UE Capabilities?

There is a separate configuration file for UE capabilities, and you determine the path to this file through the "--uecap_file" command-line parameter. Sample files are located in this folder, but I have not examined the content and quality of these.

Regarding the question above in theory, with this file, you can configure which security algorithms the UE is aware of. These algorithms are then sent to the gNB using the UE Capability Information message.

Furthermore, in this file, numerous radio-based information can be modified.

4. Add UE to Core Network Database

In order for the UE to connect to the core network, the core network must first add the UE's SIM data to its database. Either you do this permanently by adding the UE to the database file before starting the core network (as described in the core network tutorial). Or you do the following:

The data you need to set here is mostly defined in the previous step.

To add the UE to the core network while it is running do (ON THE CORE NETWORK MACHINE):

docker exec -it mysql /bin/bash
mysql -uroot -plinux
use oai_db

INSERT INTO `AuthenticationSubscription` (`ueid`, `authenticationMethod`, `encPermanentKey`, `protectionParameterId`, `sequenceNumber`, `authenticationManagementField`, `algorithmId`, `encOpcKey`, `encTopcKey`, `vectorGenerationInHss`, `n5gcAuthMethod`, `rgAuthenticationInd`, `supi`) VALUES
('208950100001100', '5G_AKA', 'fec86ba6eb707ed08905757b1bb44b8f', 'fec86ba6eb707ed08905757b1bb44b8f', '{\"sqn\": \"000000000020\", \"sqnScheme\": \"NON_TIME_BASED\", \"lastIndexes\": {\"ausf\": 0}}', '8000', 'milenage', 'C42449363BBAD02B66D16BC975D77CC1', NULL, NULL, NULL, NULL, '208950100001100');

Some useful commands to work with the SQL Database

Delete all UE's

delete from AuthenticationSubscription;

Show all UE's

select * from AuthenticationSubscription;

5. Run UE

sudo ./nr-uesoftmodem -O ../../../ci-scripts/conf_files/nrue.uicc.conf -r 106 --numerology 1 -C 3619200000 --rfsimulator.serveraddr <Address of gNB> --rfsim --thread-pool N --sectest-conf-file-path ../../../security_testing/config/secTest.conf

-O <path> defines the path to the ue sim configuration
-r, --numerology and -C define parameters needed for the lower layer connection establishment to the gNB
- -r bandwidth in terms of RBs (default value 106)
- --numerology numerology index (default value 1) --> sub carrier spacing (TS 38.211 4.2-1: Supported transmission numerologies)
- -C downlink carrier frequency in Hz (default value 0)
--rfsimulator.serveraddr <Address of gNB> takes the ip address of the gNB machine
--rfsim activates the rf simulator mode
--sectest-conf-file-path: describes the path to the security testing configuration file. When omitting the parameter no security testing functionalities will be executed that means the UE will have the same functionality as the vanilla oai UE.
--thread-pool N -> "use N for no pool (runs in calling thread) recommended with rfsim." (from --help)

For more information on the command line options and further options you can do:

sudo ./nr-uesoftmodem --help

If you don't want to do any security testing, make sure that every value in the securityTesting config JSON file is set to off, or don't provide the --sectest-conf-file-path command line parameter. More information on the configuration of the security tests can be found in the 5G-Pentest-UE Documentation.

6. Test if the UE connected correctly to the AMF

Step 5 should connect to gNB and after that to the core network. To check whether everything has worked, you can again:

docker logs oai-amf

The output should contain something like this:

...
[2023-11-03 15:29:33.022] [amf_app] [info] |----------------------------------------------------------------------------------------------------------------|
[2023-11-03 15:29:33.022] [amf_app] [info] |----------------------------------------------------UEs' information--------------------------------------------|
[2023-11-03 15:29:33.022] [amf_app] [info] | Index |      5GMM state      |      IMSI        |     GUTI      | RAN UE NGAP ID | AMF UE ID |  PLMN   |Cell ID|
[2023-11-03 15:29:33.022] [amf_app] [info] |      1|       5GMM-REGISTERED|   208950100001100|               |               2|          4| 208, 95 |14680064|
[2023-11-03 15:29:33.022] [amf_app] [info] |----------------------------------------------------------------------------------------------------------------|
...

Test the Data Connection from CN to UE

To test whether the UE is correctly connected to the core network and the oai-ext-dn container (which should represent a data network? TODO), the following command can be executed on the core network side.

 sudo docker exec –it oai-ext-dn ping <UE_IP>

The UE IP can be found in the UE logs. Once the UE is properly connected the log should print something like the following:

[OIP]   Interface oaitun_ue1 successfully configured, IPv4 12.1.1.130, IPv6 (null)

Corresponding to this Tutorial the command will ping the UE from the CN through the gNB.

Test/Use the Data Connection from UE to CN

First make sure this message appears in the UE Logs:

[OIP]   Interface oaitun_ue1 successfully configured, IPv4 12.1.1.130, IPv6 (null)

if this is the case executing the following:

ifconfig

should contain this interface:

oaitun_ue1: flags=4305<UP,POINTOPOINT,RUNNING,NOARP,MULTICAST>  mtu 1500
        inet 12.1.1.152  netmask 255.255.255.0  destination 12.1.1.152
        inet6 fe80::263f:ef16:aab9:1b61  prefixlen 64  scopeid 0x20<link>
        unspec 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00  txqueuelen 500  (UNSPEC)
        RX packets 0  bytes 0 (0.0 B)
        RX errors 0  dropped 0  overruns 0  frame 0
        TX packets 3  bytes 144 (144.0 B)
        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0

This interface is the 5G connection to the core network/ data network.

To access a webpage through this interface you can for example use the following:

curl --interface oaitun_ue1 www.google.de

To see your request on the core network machine you could just open a port like this:

nc -l -v <Port>

and then send a request to it like this:

curl --interface oaitun_ue1 <coreNetworkMachineIP>:<Port>

The result should look something like this:

Listening on 0.0.0.0 50124
Connection received on 192.168.70.134 54340
GET / HTTP/1.1
Host: 192.168.178.80:50124
User-Agent: curl/7.81.0
Accept: /