https://github.com/fasferraz/eNB
eNB s1 Emulator - S1AP and S1-U interfaces.
https://github.com/fasferraz/eNB
Last synced: 20 days ago
JSON representation
eNB s1 Emulator - S1AP and S1-U interfaces.
- Host: GitHub
- URL: https://github.com/fasferraz/eNB
- Owner: fasferraz
- License: gpl-3.0
- Created: 2020-10-09T15:28:17.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-05-03T16:40:16.000Z (12 months ago)
- Last Synced: 2024-06-21T06:39:34.996Z (10 months ago)
- Language: Python
- Homepage:
- Size: 502 KB
- Stars: 53
- Watchers: 3
- Forks: 32
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-telco - eNB s1 emulator - This is an eNB emulator application done in python3 to interact with MME (S1AP) and SGW (S1-U). This application can be used to perform and simulate several EMM and ESM procedures, including user plane traffic. This application was tested with real MMEs (lab environment). (RAN / 4G)
README
# eNB s1 Emulator
This is an eNB emulator application done in python3 to interact with MME (S1AP) and SGW (S1-U).
This application can be used to perform and simulate several EMM and ESM procedures, including user plane traffic.
This application was tested with real MMEs (lab environment).
## Installation
To begin with you will need Python3 / Pip installed and a few other libraries / dependencies.
On a Debian/Ubuntu systems you can install with:
```apt-get install -y python3-pip libsctp-dev swig python3-pyscard git net-tools```
Now we can clone the repository with:
```
git clone https://github.com/fasferraz/eNB
cd eNB/
```
Finally we will need to install all of the Python packages needed to run the tool.
We can install all these packages using Pip3 with:
```sudo pip3 install -r requirements.txt```
## Authentication
We have 3 options for authenticating our simulated subscribers to the network:
- Using a physical SIM connected via a smart card reader (The modem needs to support the AT commands AT+CSIM. You can define the ttyUSBx to use in the options (-u).)
- Statically setting Ki & OP/OPc keys set as parameters when starting the program (See option ```--ki=KI```, ```--op=OP``` and ```--opc=OPc``` )
- Via an external USIM Server with a physical SIM connected controlled over HTTP (see https://github.com/fasferraz/USIM-https-server)
Note: If none of these options is defined, a default KASME and XRES are used (check corresponding variables inside *session_dict_initialization* function).
## Usage
Many variables needed for SA1P and NAS are defined inside the *session_dict_initialization* function.
You can change them to meet your own needs.
When you call the script these are the options available:
```
python3 eNB_LOCAL.py -h
Usage: eNB_LOCAL.py [options]
Options:
-h, --help show this help message and exit
-i ENB_IP, --ip=ENB_IP
eNB Local IP Address
-m MME_IP, --mme=MME_IP
MME IP Address
-g GATEWAY_IP_ADDRESS, --gateway_ip_address=GATEWAY_IP_ADDRESS
gateway IP address
-u SERIAL_INTERFACE, --usb_device=SERIAL_INTERFACE
modem port (i.e. COMX, or /dev/ttyUSBX), smartcard
reader index (0, 1, 2, ...), or server for https
-I IMSI, --imsi=IMSI IMSI (15 digits)
-E IMEI, --imei=IMEI IMEI-SV (16 digits)
-K KI, --ki=KI ki for Milenage (if not using option -u)
-P OP, --op=OP op for Milenage (if not using option -u)
-C OPC, --opc=OPC opc for Milenage (if not using option -u)
-o PLMN, --operator=PLMN
Operator MCC+MNC
```
Note: Gateway IP Address (option -g) is needed when the MME or SGW are not in the local LAN. With user plane activated, the default route points to a tunnel interface, so this Gateway IP Address is needed so that MME address and SGW address are also reachable (using /32 routes) using this IP as next-hop address. In case of multiple interfaces, this IP address must be in the same network as the source interface used for eNB address (option -i).
Example usage fo eNB address - 172.16.168.130, and MME address - 172.16.168.8 (eNB and MME in the same LAN), and ttyUSB2:
```python3 eNB_LOCAL.py -i 172.16.168.130 -m 172.16.168.8 -u /dev/ttyUSB2```
This is the application user interface, where we can see the current options and procedures supported:
This application implements S1-U, so after an successful Attach with PDN Connectivity activation, you can use the laptop applications (browser, terminal, etc...) to send/receive traffic over the GTP-U connection towards the SGW using the session IP address, using a tunnel interface.
In case the session is a NB-IoT session you can also send the user plane over NAS including Non-IP Data Delivery (NIDD).
The basic flow could be for example, option 15 - to bring up the s1 interface, and then option 20 - to perform attach.
## Functionality
The application supports currently the following options:
- S1 Setup type: LTE, NB-IoT, or both
- Mobile Identity Type: IMSI or GUTI
- Attach PDN: Default APN, or Specific APN
- Session Type: 4G, 5G or NB-IoT
- Session Sub-Type: No PSM and No eDRX, PSM, eDRX or both PSM and eDRX
- PDN Type ipv4, ipv6, ipv4v6 or Non-IP
- Control Plane Service Request with Radio Bearer or without Radio Bearer
- Attach Type: EPS Attach, Combined EPS/IMSI Attach or Emergency Attach
- TAU Type: TA Updating, Combined TA/LA Updating or Combined TA/LA Updating with IMSI Attach
- Process Paging: Enabled or Disabled
- SMS Update type: Additional Update Type SMS Only: False or True
- eNB Cell and TAC can change
- P-CSCF Restoration Support capability
In terms of procedures, the application supports the following ones:
- S1 Setup Request
- S1 Reset
- Attach
- Detach
- TAU
- TAU Periodic
- Service Request
- UE Context Release
- Send SMS (a predefined one)
- Control Plane Service Request
- E-RAB Modification Indication (5G)
- Secondary RAT Data Usage Report (5G)
- PDN Connectivity
- PDN Disconnect
- Activate/Deactivate GTP-U for Control Plane
- Activate/Deactivate Data over NAS
- Set/Send Non-IP Packet
You can also find more information in https://fabricioapps.blogspot.com/2020/07/mme-part-i-enb-emulator.html
## Dependencies
I had previously done some experiments with SCTP using the native socket module from python3, but starting a ASN.1 module for S1AP from scratch was a big challenge. Fortunately I found some magnificent python modules for ASN.1 and S1AP done by P1 Security that I highly recommend:
https://github.com/P1sec
They have plenty of modules for almost anything related to Mobile Developments, but for my project i just used the S1AP from pycrate_asn1dir module, and CM from the CryptoMobile module (that has all the ciphering and integrity protocols needed for NAS).
In order to derive the integrity and ciphering keys from KASME/CK/IK) i used another module: the Crypto.Hash (pip3 install pycryptodome) that has the HMAC and SHA256 functions needed for KDF.
For serial communication towards the modem I use the pyserial module (pip3 install pyserial)
For smartcard reader communication I use the smartcard module (pyscard module from https://pypi.org/project/pyscard/) and card module (from https://github.com/mitshell/card).
For https request to https server I use the requests module.
So in resume, these are the required external (non-standard) modules:
```
from pycrate_asn1dir import S1AP
from pycrate_asn1rt.utils import *
from CryptoMobile.CM import *
from CryptoMobile.Milenage import Milenage
from Crypto.Hash import HMAC
from Crypto.Hash import SHA256
```
For IMSI, and authentication these are the required external (non-standard) modules:
(at least one of these options should be available if we need to use real USIM)
```
try:
import serial
except:
pass
try:
from smartcard.System import readers
from smartcard.util import toHexString,toBytes
try:
from card.USIM import *
except:
pass
except:
pass
try:
import requests
requests.packages.urllib3.disable_warnings()
except:
pass
```
For authentication the application also accepts Ki and OP/OPC for Milenage operation (usefull for testing with developments like open5gs, where the USIM parameters are defined in the HSS/UDR).
## Updated version (2023/02/19):
- Support of gtp kernel (libgtpnl and modprobe gtp) for default namespace. New option -Z
## New branch added by Avmalavi that supports Multi-User!!!!
Check it here: https://github.com/fasferraz/eNB/tree/multi-user
## Updated version (2023/10/30):
- New option to support setting SCTP MAX SEG
- New option to define UERadioCapability in hex string (useful to test UERadioCapability bigger than MTU)
- New option to support a second SCTP connection to another MME, so that you can establish session in one MME, and perform other procedures like TAU in the other, etc...
- New option to set GUTI by CLI. This may be usueful to test S10 procedures (GTP or DNS)
```
python3 eNB_LOCAL.py -h
Usage: eNB_LOCAL.py [options]
Options:
-h, --help show this help message and exit
-i ENB_IP, --ip=ENB_IP
eNB Local IP Address
-m MME_IP, --mme=MME_IP
MME IP Address
-g GATEWAY_IP_ADDRESS, --gateway_ip_address=GATEWAY_IP_ADDRESS
gateway IP address
-u SERIAL_INTERFACE, --usb_device=SERIAL_INTERFACE
modem port (i.e. COMX, or /dev/ttyUSBX), smartcard
reader index (0, 1, 2, ...), or server for https
-I IMSI, --imsi=IMSI IMSI (15 digits)
-E IMEI, --imei=IMEI IMEI-SV (16 digits)
-K KI, --ki=KI ki for Milenage (if not using option -u)
-P OP, --op=OP op for Milenage (if not using option -u)
-C OPC, --opc=OPC opc for Milenage (if not using option -u)
-o PLMN, --operator=PLMN
Operator MCC+MNC
--tac1=TAC1 1st tracking area code
--tac2=TAC2 2nd tracking area code
-Z, --gtp-kernel Use GTP Kernel. Needs libgtpnl
-S MAXSEG, --maxseg=MAXSEG
SCTP MAX_SEG (>463 bytes)
--ue-radio-capability=UERADIOCAPABILITY
UERadioCapability in hex string
-G GUTI, --guti=GUTI GUTI in format ---
--mme-2=MME_2_IP 2nd MME IP Address
```