NAS 5GS refactor
The goal of this MR is to reorganize the NR NAS code into:
- enc/dec library functions (5GS, 5GMM, 5GSM, NR_NAS_defs.h,
nr_fgs_nas_lib.c)
- handlers and callbacks (nr_nas_msg.c)
The following changes are introduced:
1. migrate 5GS enc/dec lib (5GMM and 5GSM) to a dedicated folder
2. add a nested CMakeLists structure
3. refactor NR NAS enc/dec functions
4. refactor NR NAS messages struct definitions
5. remove most of dependency from NAS LTE
6. further refactor of PDU Session Establishment Accept processing to
separate enc/dec from handling
7. made naming of 5GS definitions consistent whenever necessary
8. cleanup unused code
9. remove redundant struct definitions
Also:
1. fix decoding of AMF Set ID in 5G-S-TMSI UE identity
2. replace Byte_t directly with uint8_t
* move enc/dec definitions to NR_NAS_defs.h and add new lib file nr_fgs_nas_lib.c
both used by nr_nas_msg.c
* move utility macros to fgs_nas_utils.h: this can be used in all the 5GMM, 5GSM lib files
* use nr_nas_msg.c for handlers/callbacks only, it should call the enc/dec
functions in nr_fgs_nas_lib and in the 5GMM, 5GSM libs
* 5GMM, 5GSM libs should only do the enc/dec of the NAS message contents
* the only function used from nr_common.c is servingNetworkName which is
used in nr_nas_msg.c, so it was moved to the latter file and its scope
was reduced
Every NAS 5GS message can have 3 different headers: (1) security protected
(2) 5GMM plain (3) 5GS plain;
According to 3GPP TS 24.501:
> 4.2 Coordination between the protocols for 5GS mobility management and 5GS session management
> A 5GS session management (5GSM) message is piggybacked in specific 5GS mobility management (5GMM) transport
> messages. To this purpose, the 5GSM messages can be transmitted in an information element in the 5GMM transport
> messages.
A PDU Session Establishment accept is a 5GSM message and as such it is contained in a 5GMM
transport message. The code in capture_pdu_session_establishment_accept_msg is reflecting this.
The message is thus expected to have: (1) Security protected 5GMM header (2) Plain 5GMM message
(3) 5GSM Payload Container (4) Plain 5GSM message.
5.4.5 of 3GPP TS 24.501: also says:
> The type of the payload is identified by the Payload container type IE and includes one of the following: a) a single 5GSM message;
Thus, a 5GSM is not the only possible payload of a NAS transport message.
This commit is focusing on the refactoring of the structs definitions and adaptation of the CMakeLists.
Based on the above:
* Move NR_NAS_defs.h to 5GS subfolder in NR_UE
* Move NAS FGS structs and definitions to NR_NAS_defs.h
* Rename mm_msg_header_t to fgmm_msg_header_t
* Remove duplicated NAS struct definitions
(1) kept fgs_nas_message_security_header_t over security_protected_nas_5gs_msg_t
(2) Kept fgsm_msg_header_t over fgs_sm_nas_msg_header_t
* Remove unused definitions, structs, functions in the process
This commit is introducing the following macro changes:
(1) Migrate NAS 5GS lib files to a new 5GS subfolder in NR_UE
and organize NAS 5GS lib messages into 5GMM and 5GSM subfolders.
A nested CMake structure was implemented and CMakeLists.txt were
added whenever necessary. This is effectively separating 5GS
libraries from LTE libraries.
(2) In order to simplify the separation of 5GS libs from LTE libs,
remaining dependencies from NAS LTE (e.g. nas_ue_task.c, ue-idx-standalone)
were removed in the process
(3) ExtendedProtocolDiscriminator.c/.h and SpareHalfOctet.c/.h were deleted
and affected types were replaced with simple integer types
(4) Cleanup: unused definitions and libs (e.g. LIB_5GNAS_GNB)
were removed
(5) Update doc/Doxyfile
(6) clang-formatted the migrated files in the process
(7) Update includes of headers in affected files
* ideally the result of these macros shall be relevant
only in unit tests, in order to validate enc/dec NAS functions
* use a local print macro
* remove dependency from LOG module
* simplified the code
* cleanup TLVDecoder.c (kept it for LTE dependencies)
* FGMM enc/dec library files
* Plain message encoding + logic for security protected message
* added fill_fgstmsi function
* add checks on length in 5G-S-TMSI encoder function
* encoding of NAS Service Request and relevant mandatory IEs
Fix Regression 4G
- Fix various bugs and/or regressions in 4G code
- Also, the CI does not test RFsim 4G with --sanitize, enables this to
detect problems.
The IES_DECODE_U16 macro loads a 16 bit integer from an arbitrary
address; this can lead to reads from misaligned addresses, and undefined
behavior sanitizer warns, like, e.g., so:
openair3/NAS/COMMON/IES/ProtocolConfigurationOptions.c:62:5: runtime error: load of misaligned address 0x7f3c24032c01 for type 'uint16_t', which requires 2 byte alignment
To fix this, first use memcpy() to load to a 16-bit aligned address,
then do the actual decoding.
- rename as_nas_info_t member data to nas_data to have a uniq name to
trace between complex malloc/free of this pointer
- fix, maybe not perfect, these pais od malloc/free
- remove typedef name changes across transmission of these as_nas_info_t
over itti, as name changing makes it even more confusing
- remove globals that are likely possible races
- in as_message_decode() fix memcpy size, it is hard to understand the
initial idea, likely the author beleives a struct of struct makes a
intermediate pointer
- in network_api.c remove globals (static but used globally)
- remove casts that are there to hide gcc warnings on probable unaligned
access
- remain a weird mix of packed/unpacked versions of the same typedef,
but gcc is happy
This commit resolves undefined behaviour runtime errors related
to misaligned memory access. E.g.
> openair3/NAS/COMMON/IES/FGSMobileIdentity.c:193:3:
> runtime error: store to misaligned address 0x608000021e2b for type 'uint16_t',
> which requires 2 byte alignment 0x608000021e2b: note: pointer points here 00 f1 ...
* ENCODE_U24: safely encode 24-bit values into a buffer
by using memcpy to copy 3 bytes in network byte order (big-endian).
* ENCODE_U16: safely encodes a 16-bit value into a buffer, handling
misalignment by memcpy 2 bytes to buffer in network byte order (big-endian).
Handle IPv6 (and IPv4v6) PDU sessions by correctly instructing
nas_config() to set up the interface with provided IP addresses.
Note that as of now, IPv6 PDU sessions have not been fully tested.
Remove a useless assert at the gNB; to my understanding the gNB does not
care about the IP session type (at least for IP), as it just
transparently tunnels the IP packets from/to GTP.
I added a comment in the code where to change to request a PDU session
different from IPv4. Currently it is hardcoded to IPv4, and it seems
that a default OAI 5GC config would reject a PDU session type different
from IPv4.
These rules & route are necessary to properly send packets on oaitun_ue1
interface:
1. This forces the packets coming from a subnet different than the UE's
subnet to go back through oaitun_ue1 rather than via what the default
route defined on the system (e.g., important if ping from the
internet arrives).
2. On machines setting net.ipv4.conf.oaitun_ue1.rp_filter=1 (e.g.
RHEL), this prevents that source filtering for packets coming back is
applied and those packets be dropped. By default, many hosts have
rp_filter=2, so no strict source filtering is applied, and it would
work; on others, this rule prevents source filter dropping.
Prior to this commit, there was a global variable baseNetAddress that
could be set independently through a setter and also through the
configuration module. This baseNetAddress (16 bits IPv4) would then be
complemented with two more bytes in nas_config().
However, this is counter-productive, as not only we have a global
variable that is avoidable (we can give the entire address to
nas_config() directly), but it also would not work with IPv6. Hence,
modify to give nas_config() the entire address. A follow-up commit will
add IPv6 support.
The main work of this commit is to rewrite cipher_aes_128_cbc_cmac()
which was too slow and created issues when running the 4G eNB on some
machines (LLL when using a b210).
Instead of creating the security context, use it, and delete it, all in
cipher_aes_128_cbc_cmac(), we introduce the function init_aes_128_cbc_cmac()
to create it, and we change cipher_aes_128_cbc_cmac() to just use it,
and we also adapt free_aes_128_cbc_cmac(). The function aes_128_cbc_cmac()
is removed, it does not follow the new init/use/free API.
Doing so, on the primary test machine used to do this work (a powerful
and fast machine where it is possible to set the CPUs' frequencies)
it was possible to limit the CPUs' frequencies to 500 MHz (it was not
possible to go lower) without any LLL (using a b210, quectel UE in
idle, no data traffic, only periodic measurement reports). Before this
commit, it was necessary to set a frequency of at least 1.8 GHz
otherwise some LLL would appear.
Then we need to adapt the rest of the code to take into account those
changes.
A notion of security container (stream_security_container_t) containing
ciphering and integrity contexts is introduced.
And the code is harmonized for, hopefully, better readability.
The (opaque) type stream_security_context_t is introduced, used by
both integrity and ciphering contexts. The idea is to use a
init()/use()/free() API for all the security procedures, identical for
all the ciphering and integrity procedures.
remove several unused files
remove mem_block_t that is never used in a different way than a simple heap buffer
move up IP address type and remove duplications of the same struct declaration
Robert Schmidt