From 6638839177f81257d044b628b7640ad8804a9459 Mon Sep 17 00:00:00 2001 From: Guido Casati Date: Fri, 16 May 2025 16:42:32 +0200 Subject: [PATCH 1/4] Update NAS documentation with information about NAS 5GS and OAI implementation status --- doc/5Gnas.md | 96 +++++++++++++++++++++++++++------------------------- 1 file changed, 50 insertions(+), 46 deletions(-) diff --git a/doc/5Gnas.md b/doc/5Gnas.md index db0c19f07e..f3e3b8beeb 100644 --- a/doc/5Gnas.md +++ b/doc/5Gnas.md @@ -1,39 +1,63 @@ - +# About 5GS NAS +The 5G System Non-Access Stratum (5GS NAS) is defined in 3GPP TS 24.501. It operates within the control plane, facilitating communication between the User Equipment (UE) and the Access and Mobility Management Function (AMF) over the N1 interface. -This tuto for 5G gNB NAS design -{: .text-center} +Key 5GS NAS messages: -# source files +* Mobility Management (5GMM): Handles UE registration, deregistration, authentication and tracking area updates. 5GMM also manages transitions between idle and connected states. +* Session Management (5GSM): Establishes, modifies, and releases PDU sessions. Coordinates with the Session Management Function (SMF) to manage user-plane resources. -openair2/RRC/NR/nr_ngap_gNB.c: skeleton for interface with NGAP -openair3/NAS/COMMON/milenage.h: a simple milenage implementation, depend only on crypto library -openair3/NAS/COMMON/NR_NAS_defs.h: messages defined for NAS implemented in C: C struct, C enums and automatic conversion to labels for debug messages -openair3/NAS/COMMON/nr_common.c: 5G NAS common code between gNB and UE -openair3/UICC/usim_interface.c: UICC simulation for USIM messages +# OAI Implementation Status -openair3/NAS/NR_UE/ue_process_nas.c: NAS code for UE +The following tables lists implemented NAS messages and whether there is an encoder or decoder function, and if a corresponding unit test exists. -openair3/NAS/gNB/network_process_nas.c: NAS code for gNB running without 5GC +| Type | Message | Encoding | Decoding | Unit test | +|-------|-------------------------------------------|----------|----------|------------| +| 5GMM | Service Request | yes | yes | yes | +| 5GMM | Service Accept | yes | yes | yes | +| 5GMM | Service Reject | yes | yes | yes | +| 5GMM | Authentication Response | yes | no | no | +| 5GMM | Identity Response | yes | no | no | +| 5GMM | Security Mode Complete | yes | no | no | +| 5GMM | Uplink NAS Transport | yes | no | no | +| 5GMM | Registration Request | yes | yes | no | +| 5GMM | Registration Accept | yes | yes | yes | +| 5GMM | Registration Complete | yes | yes | no | +| 5GMM | Deregistration Request (UE originating) | yes | no | no | +| 5GSM | PDU Session Establishment Request | yes | no | no | +| 5GSM | PDU Session Establishment Accept | no | yes | no | -openair3/TEST/test5Gnas.c: unitary testing of NAS messages: encodes+decode a standard network entry, mixing code from UE and 5GC (or gNB in noCore) +## Code Structure + +[openair3/NAS/NR_UE/nr_nas_msg.c](../openair3/NAS/NR_UE/nr_nas_msg.c): +* NAS procedures and message handlers/callbacks +* Integration with RRC (ITTI) and SDAP +* Invokes enc/dec libraries +* Handles 5GMM state and mode + +[openair3/NAS/NR_UE/5GS/fgs_nas_lib.c](../openair3/NAS/NR_UE/5GS/fgs_nas_lib.c): +[openair3/NAS/NR_UE/5GS/NR_NAS_defs.h](../openair3/NAS/NR_UE/5GS/NR_NAS_defs.h): +* encoding and decoding functions for 5G NAS message headers and payloads +* relies on 5GMM/5GSM messages libs for payload encoding + +[openair3/NAS/NR_UE/5GS/fgs_nas_utils.h](../openair3/NAS/NR_UE/5GS/fgs_nas_utils.h): +* NAS helpers, macros + +[openair3/NAS/NR_UE/5GS/5GMM](../openair3/NAS/NR_UE/5GS/5GMM): +* encoding/decoding functions and definitions for 5GMM NAS messages payloads + +[openair3/NAS/NR_UE/5GS/5GMM/MSG/fgmm_lib.c](../openair3/NAS/NR_UE/5GS/5GMM/MSG/fgmm_lib.c): +[openair3/NAS/NR_UE/5GS/5GMM/MSG/fgmm_lib.h](../openair3/NAS/NR_UE/5GS/5GMM/MSG/fgmm_lib.h): +* encoding/decoding functions and definitions for common 5GMM IEs + +[openair3/NAS/NR_UE/5GS/5GSM](../openair3/NAS/NR_UE/5GS/5GSM): +* encoding and decoding functions for 5GSM NAS messages payloads # USIM simulation A new USIM simulation, that parameters are in regular OAI config files @@ -44,10 +68,6 @@ In case we run several UEs in one process, the variable section name allows to m The NAS implementation uses this possibility. -# UE side -UEprocessNAS() is the entry for all messages. -It decodes the message type and call the specific function for each messgae - ## Identityrequest + IdentityResponse When the UE receives the request, it stores the 5GC request parameters in the UE context ( UE->uicc pointer) It calls "scheduleNAS", that would trigger a answer (seeing general archtecture, it will probly be a itti message to future RRC or NGAP thread). @@ -88,19 +108,3 @@ Here after, the gNB mode "noCore" processing in gNB: NGAP calls the entry functi When the gNB completes RRC attach, it sends a first message to NGAP thread. Normal processing sends NGAP initial UE message, in noCore mode, it should call: identityRequest() that encode the NAS identity request inside the gNB. The gNB NGAP thread then should call the piece of code that forward the message to the UE as when it receives a NAS message from 5GC. - -## All NAS coming from UE -When NGAP thread receives a NAS message from lower layers, it encapsulates it to forward it to the 5GC. In "noCore" mode it calls processNAS(). - -This function stores in the gNB the NAS data, then it should encode the next message (identity, authentication, security mode) or do nothing (registration complete). - - -
-**Note** -{: .panel-heading} -
- - -
-
- From 4eb55f83ab94e8d5852b04cec59fbf0a9c2b16e4 Mon Sep 17 00:00:00 2001 From: Guido Casati Date: Tue, 20 May 2025 15:18:07 +0200 Subject: [PATCH 2/4] Remove gNB NAS documentation section: noCore function is no longer supported --- doc/5Gnas.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/doc/5Gnas.md b/doc/5Gnas.md index f3e3b8beeb..d6ae26cb27 100644 --- a/doc/5Gnas.md +++ b/doc/5Gnas.md @@ -97,14 +97,3 @@ When the scheduler wants to encode the answer, it calls registrationComplete() ## registrationComplete To be defined in UE, this NAS message is done after RRC sequence completes - -# gNB side -gNB NGAP thread receives the NAS message from PHY layers -In normal mode, it send it to the core network with no decoding. - -Here after, the gNB mode "noCore" processing in gNB: NGAP calls the entry function: processNAS() instead of forwarding the packet to the 5GC - -## RRCModeComplete + Identityrequest -When the gNB completes RRC attach, it sends a first message to NGAP thread. -Normal processing sends NGAP initial UE message, in noCore mode, it should call: identityRequest() that encode the NAS identity request inside the gNB. -The gNB NGAP thread then should call the piece of code that forward the message to the UE as when it receives a NAS message from 5GC. From 278a0bcc67787402a28d006e595281d9c080e897 Mon Sep 17 00:00:00 2001 From: Guido Casati Date: Tue, 20 May 2025 15:46:08 +0200 Subject: [PATCH 3/4] Update USIM section in 5GS NAS documentation --- doc/5Gnas.md | 68 ++++++++++++++++++++++++++++++---------------------- 1 file changed, 39 insertions(+), 29 deletions(-) diff --git a/doc/5Gnas.md b/doc/5Gnas.md index d6ae26cb27..a120ed2173 100644 --- a/doc/5Gnas.md +++ b/doc/5Gnas.md @@ -59,41 +59,51 @@ The following tables lists implemented NAS messages and whether there is an enco [openair3/NAS/NR_UE/5GS/5GSM](../openair3/NAS/NR_UE/5GS/5GSM): * encoding and decoding functions for 5GSM NAS messages payloads -# USIM simulation -A new USIM simulation, that parameters are in regular OAI config files +# USIM Simulation -## To open the USIM -init_uicc() takes a parameter: the name of the block in the config file -In case we run several UEs in one process, the variable section name allows to make several UEs configurations in one config file. +OAI includes a simulated USIM implementation that reads its parameters from standard configuration files. This allows for rapid prototyping and testing without relying on a physical UICC card. The USIM-related configuration is handled via the `init_uicc()` function. -The NAS implementation uses this possibility. +## Configuration -## Identityrequest + IdentityResponse -When the UE receives the request, it stores the 5GC request parameters in the UE context ( UE->uicc pointer) -It calls "scheduleNAS", that would trigger a answer (seeing general archtecture, it will probly be a itti message to future RRC or NGAP thread). +The simulation reads values from a named section in the config file. -When the scheduler wants to encode the answer, it calls identityResponse() -The UE search for a section in the config file called "uicc" -it encodes the NAS answer with the IMSI, as a 4G compatible authentication. -A future release would encode 5G SUPI as native 5G UICC. +**Config options in the `uicc` section**: -## Authenticationrequest + authenticationResponse -When the UE receives the request, it stores the 5GC request parameters in the UE context ( UE->uicc pointer) -It calls "scheduleNAS", that would trigger a answer (seeing general archtecture, it will probly be a itti message to future RRC or NGAP thread). +| Parameter | Description | Default value | +|---------------|-----------------------------------|--------------------------------------------| +| `imsi` | User IMSI | `2089900007487` | +| `nmc_size` | Number of digits in NMC | `2` | +| `key` | Subscription key (Ki) | `fec86ba6eb707ed08905757b1bb44b8f` | +| `opc` | OPc value | `c42449363bbad02b66d16bc975d77cc1` | +| `amf` | AMF value | `8000` | +| `sqn` | Sequence number | `000000` | +| `dnn` | Default DNN (APN) | `oai` | +| `nssai_sst` | NSSAI slice/service type | `1` | +| `nssai_sd` | NSSAI slice differentiator | `0xffffff` | +| `imeisv` | IMEISV string | `6754567890123413` | -When the scheduler wants to encode the answer, it calls authenticationResponse() -The UE search for a section in the config file called "uicc" -It uses the Milenage parameters of this section to encode a milenage response -A future release would encode 5G new authentication cyphering functions. +These are parsed and stored in the `uicc_t` structure. -## SecurityModeCommand + securityModeComplete -When the UE receives the request it will: -Selected NAS security algorithms: store it for future encoding -Replayed UE security capabilities: check if it is equal to UE capabilities it sent to the 5GC -IMEISV request: to implement -ngKSI: Key set Indicator, similator to 4G to select a ciphering keys set +## Initialization -When the scheduler wants to encode the answer, it calls registrationComplete() +The UE calls `init_uicc` via `checkUicc` to allocate memory for the `uicc_t` structure member and load parameters using `config_get()` from the selected config section. Then the UICC structure is stored in the NAS context. `nr_ue_nas_t`, to be used to fill identity and security credentials when generating responses to 5GC messages such as `Identity Response`, `Authentication Response`, and `Security Mode Complete`. + +## Milenage Authentication and Key Derivation + +When the UE receives a **5GMM Authentication Request**, the function `generateAuthenticationResp` generates a valid `Authentication Response` with the necessary derived NAS and AS security keys. The function `derive_ue_keys` parses the Authentication Request and performs the entire 5G AKA key hierarchy: + +* Extracts the `RAND` and `SQN` +* Performs Milenage Algorithms f2-f5 using `f2345()` from the UICC input +* Computes the `RES` using `transferRES()` +* Derives the keys `KAUSF`, `KSEAF`, `KAMF`, `KNASenc`/`KNASint` via `derive_knas()` and `KGNB` for RRC ciphering (via `derive_kgnb()`) + +## Security Mode Complete + +When the UE receives a **Security Mode Command** from the 5GC, it responds with a `Security Mode Complete` message. This message is protected with the newly established NAS security context and may carry additional payloads, including the UE’s identity and a nested NAS message (e.g., `Registration Request`) in the `FGSNasMessageContainer`. The function responsible for building and securing this response is `generateSecurityModeComplete`. + +### IMEISV + +The **IMEISV**, is encoded using the `fill_imeisv()` helper. This function extracts each digit from the configured `imeisvStr` in the UICC context and populates the mobile identity structure. + +See TS 24.501 §4.4 for reference. -## registrationComplete -To be defined in UE, this NAS message is done after RRC sequence completes From 1b84bd8b6544f2172ac72bb33205e1f26c1a1f81 Mon Sep 17 00:00:00 2001 From: Guido Casati Date: Tue, 27 May 2025 08:46:41 +0200 Subject: [PATCH 4/4] Update README.md --- doc/README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/doc/README.md b/doc/README.md index f1b0ba8284..24050666a7 100644 --- a/doc/README.md +++ b/doc/README.md @@ -86,9 +86,7 @@ Legacy unmaintained files: - [Information on gNB MAC](./MAC/mac-usage.md) - [Information on gNB RRC](./RRC/rrc-usage.md) - [Information on analog beamforming implementation](./analog_beamforming.md) - -Legacy unmaintained files: -- [`5Gnas.md`](./5Gnas.md) +- [Information on the UE 5G NAS implementation](./5Gnas.md) # Building and running from images