Merge branch 'TTF_T048' of https://forge.etsi.org/rep/int/5g-core/nas into TTF_T048

# NG_NAS

# ETSI 5GNGAP protocol project

## Introduction

## Getting started

This repositories contains the test specificationsfor ETSI 5GNGAP protocols testing, Release 16.

ETSI 5GNGAP protocols project supports:

- ETSI TS 123 501: "5G; System architecture for the 5G System (5GS) (3GPP TS 23.501 version 16.16.0 Release 16)"

- ETSI TS 123 502: "5G; Procedures for the 5G System (5GS) (3GPP TS 23.502 version 16.15.0 Release 16)"

- ETSI TS 124 501: "5G; Non-Access-Stratum (NAS) protocol for 5G System (5GS); Stage 3 (3GPP TS 24.501 version 16.12.0 Release 16)"

- ETSI TS 138 413: "5G; NG-RAN; NG Application Protocol (NGAP) (3GPP TS 38.413 version 16.12.0 Release 16)"

To make it easy for you to get started with GitLab, here's a list of recommended next steps.

Already a pro? Just edit this README.md and make it your own. Want to make it easy? [Use the template at the bottom](#editing-this-readme)!

## Contact information

## Add your files

Email at `cti_support` at `etsi` dot `org`.

## License

Unless specified otherwise, the content of this repository and the files contained are released under the BSD-3-Clause license.

See the attached LICENSE file or visit https://forge.etsi.org/legal-matters.

## STFs/TTFs

The following STFs were or are currently involved in the evolutions of the ETSI 5GNGAP protocols project:

- TTF T033, TTF T048

# Installation

The NGAP/NAS Conformance Test System project builds and tests regularly on the following platforms:

  - Linux (Ubuntu)

  - Windows ([Cygwin x64](https://cygwin.com/install.html), [Npcap SDK x64](https://nmap.org/npcap/#download) and [OpenSSL-Windows x64](https://www.openssl.org) are required)

Note: The [OpenSSL](https://www.openssl.org) version >= 1.1.1 is also required.

## How to do it?

They are three different methods:

- Using [Vagrant](https://www.vagrantup.com/)

- Using [Docker](https://www.docker.com/)

- Using [Eclipse TITAN on Windows or Linux](https://projects.eclipse.org/projects/tools.titan/downloads)

How to choose one of these methods is depending of your host system.

NOTE: In all case, if you want to setup an continuous integration process (e.g. Jenkins), Docker is the best choice. 

### The host system is Windows

The both methods require a virtual machine. You can use either VirtualBox or WMware.

In this case, the easiest way is to use Vagrant.

### The host system is Linux

Vagrant requires a virtual machine. You can use either VirtualBox or WMware.

Docker does not need a virtual machine, so it is the more efficant way.

The following clauses describes four ways to build and deploy the CISE  Test System:

- [Using TITAN compiler on a Docker image](#using-titan-compiler-on-a-docker-image)

- [Using development Docker image](#using-development-docker-image)

- [Using Vagrant](#using-vagrant)

- [From scratch](#from-scratch)

- [ ] [Create](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#create-a-file) or [upload](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#upload-a-file) files

- [ ] [Add files using the command line](https://docs.gitlab.com/ee/gitlab-basics/add-file.html#add-a-file-using-the-command-line) or push an existing Git repository with the following command:

## Using TITAN compiler on a Docker image

In this configuration, TITAN compiler is located on a Docker image and the sources and the outputs are located on the host.

Pre-requisites on your host machine:

- Install Docker

Procedure on the host machine:

- Open a Terminal

- Clone the project

```sh

$ git clone --recurse-submodules --remote-submodules https://forge.etsi.org/rep/int/5g-core/nas.git

```

cd existing_repo

git remote add origin https://forge.etsi.org/rep/int/5g-core/nas.git

git branch -M main

git push -uf origin main

- Select the branch you need:

 devel

```sh

$ git checkout TTF_T048

```

- Execute the installation script to setup the correct environment:

```sh

$ cd ./nas

& ./install.sh

```

## Integrate with your tools

- From the NGAP/NAS Conformance Test System root directory, build the Docker image executing the following commands:

- [ ] [Set up project integrations](https://forge.etsi.org/rep/int/5g-core/nas/-/settings/integrations)

```sh

$ cd ./virtualization/docker

$ docker build --no-cache --tag alpine-nas -f Dockerfile --force-rm .

$ docker images

```

## Collaborate with your team

To build the NGAP/NAS Test Suite, execute the following command:

- [ ] [Invite team members and collaborators](https://docs.gitlab.com/ee/user/project/members/)

- [ ] [Create a new merge request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html)

- [ ] [Automatically close issues from merge requests](https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#closing-issues-automatically)

- [ ] [Enable merge request approvals](https://docs.gitlab.com/ee/user/project/merge_requests/approvals/)

- [ ] [Automatically merge when pipeline succeeds](https://docs.gitlab.com/ee/user/project/merge_requests/merge_when_pipeline_succeeds.html)

```sh

$ ./docker-run.sh build

```

## Test and Deploy

Possble other options are 'clean' to remove all the build outputs or 'rebuild' to force a build of the Test Suite after a 'clean'.

Use the built-in continuous integration in GitLab.

Before to execute the NGAP/NAS Test Suite, prepare, edit and update the configuration file (e.g. AtsNGAP Test Suite):

- Update the following fields:

    - system.NGAP_AMF.params

    - system.N2_gNBaMF_P.params

- Update the PICS and PIXITs accordingly

- [ ] [Get started with GitLab CI/CD](https://docs.gitlab.com/ee/ci/quick_start/index.html)

- [ ] [Analyze your code for known vulnerabilities with Static Application Security Testing(SAST)](https://docs.gitlab.com/ee/user/application_security/sast/)

- [ ] [Deploy to Kubernetes, Amazon EC2, or Amazon ECS using Auto Deploy](https://docs.gitlab.com/ee/topics/autodevops/requirements.html)

- [ ] [Use pull-based deployments for improved Kubernetes management](https://docs.gitlab.com/ee/user/clusters/agent/)

- [ ] [Set up protected environments](https://docs.gitlab.com/ee/ci/environments/protected_environments.html)

```sh

$ ln -sf ../../etc/AtsNGAP/AtsNGAP_AMF_open5gs.cfg_ ../../etc/AtsNGAP/AtsNGAP.cfg

$ vi ../../etc/AtsNGAP/AtsNGAP.cfg # To update it

```

***

To run the NGAP/NAS Test Suite, execute the following command:

# Editing this README

```sh

$ ./docker-run.sh run

```

When you're ready to make this README your own, just edit this file and use the handy template below (or feel free to structure it however you want - this is just a starting point!). Thank you to [makeareadme.com](https://www.makeareadme.com/) for this template.

<b>Notes</b>:

- The NGAP/NAS Conformance Test System is listening on port 38412

- Updating the file etc/AtsNGAP.cfg is about:

. Selecting the test(s) to be executed

. Updating value of PICs and PIXITs

. Updating HTTP port setting

## Suggestions for a good README

Every project is different, so consider which of these sections apply to yours. The sections used in the template are suggestions for most open source projects. Also keep in mind that while a README can be too long and detailed, too long is better than too short. If you think your README is too long, consider utilizing another form of documentation rather than cutting out information.

## Name

Choose a self-explaining name for your project.

## Using development Docker image

## Description

Let people know what your project can do specifically. Provide context and add a link to any reference visitors might be unfamiliar with. A list of Features or a Background subsection can also be added here. If there are alternatives to your project, this is a good place to list differentiating factors.

In this configuration, the TITAN compiler, the sources and the outputs are located on the Docker image.

## Badges

On some READMEs, you may see small images that convey metadata, such as whether or not all the tests are passing for the project. You can use Shields to add some to your README. Many services also have instructions for adding a badge.

Pre-requisites on your host machine:

- Install Docker

## Visuals

Depending on what you are making, it can be a good idea to include screenshots or even a video (you'll frequently see GIFs rather than actual videos). Tools like ttygif can help, but check out Asciinema for a more sophisticated method.

Procedure for a Windows host machine:

- On your host machine, open a the Docker Quickstart Terminal and change to a working folder such as ./temp/docker_its

## Installation

Within a particular ecosystem, there may be a common way of installing things, such as using Yarn, NuGet, or Homebrew. However, consider the possibility that whoever is reading your README is a novice and would like more guidance. Listing specific steps helps remove ambiguity and gets people to using your project as quickly as possible. If it only runs in a specific context like a particular programming language version or operating system or has dependencies that have to be installed manually, also add a Requirements subsection.

Procedure for a Linux host machine:

- On your host machine, open a terminal and change to a working folder such as $HOME/temp/docker_its

## Usage

Use examples liberally, and show the expected output if you can. It's helpful to have inline the smallest example of usage that you can demonstrate, while providing links to more sophisticated examples if they are too long to reasonably include in the README.

On your host machine, download the following items from NGAP/NAS Conformance Test System project:

- The docker folder

- The .jenkins.sh script file (hidden file) and add the execution rights on it

- Check the rights of the script files and the folders

## Support

Tell people where they can go to for help. It can be any combination of an issue tracker, a chat room, an email address, etc.

From the your current directory, execute the following commands:

## Roadmap

If you have ideas for releases in the future, it is a good idea to list them in the README.

```sh

$ ./.jenkins.sh

...

```

NOTE The creation and the installations will take some time to achieve

- Start the container

## Contributing

State if you are open to contributions and what your requirements are for accepting them.

```sh

$ ./virtualization/docker/run-container.sh

...

```

For people who want to make changes to your project, it's helpful to have some documentation on how to get started. Perhaps there is a script that they should run or some environment variables that they need to set. Make these steps explicit. These instructions could also be useful to your future self.

- Switch to the next clause (Usage)

You can also document commands to lint the code or run tests. These steps help to ensure high code quality and reduce the likelihood that the changes inadvertently break something. Having instructions for running tests is especially helpful if it requires external setup, such as starting a Selenium server for testing in a browser.

## Authors and acknowledgment

Show your appreciation to those who have contributed to the project.

## Using Vagrant

## License

For open source projects, say how it is licensed.

Pre-requisites on your host machine:

- Install [Virtualbox](https://www.virtualbox.org/manual/ch01.html)

- Install [Vagrant](https://www.vagrantup.com/intro/getting-started/)

- Install Vagrant plugin vagrant-vbguest

- Credentials to access [ETSI forge](https://forge.etsi.org/gitlab/users/sign_in)

    - Set the environment variable USERNAME to your ETSI EOL account user name

    - Set the environment variable PASSWORD to your ETSI EOL account password

Procedure:

- On your host machine, open a command line session (PuTTY, DOS window...)

- From the NGAP/NAS Conformance Test System project, clone the Vagrant folder

- In the file Vagrantfile, modify the tag config.vm.provision replacing <username> & <password> strings by your ETSI credentials

- In the Vagrant folder (./virtualization/vagrant), execute the following commands:

```sh

$ vagrant up --provider virtualbox --provision

...

```

NOTE The creation and the installations will take some time to achieve

- Stop vagrant virtual machine

```sh

$ vagrant halt

...

```

- Update the file 'Vagrantfile' to match with your networks configuration

- Re-start the vagrant virtual machine and log to to the machine

```sh

$ vagrant up

...

$ vagrant ssh

```

- Switch to the next clause (Usage)

NOTE The user password is vagrant.

## From scratch

Pre-requisites:

- Install Virtualbox

Procedure:

- Install a new Linux Virtual machine (Mint, Debian...)

- Update your system with the latest version of kernel and security packages

- Install the following packages (According to the Linux chosen, the package naming can be different)

    autoconf

    bison

    build-essential

    cmake

    curl

    dos2unix

    doxygen

    emacs

    expect

    flex

    g++:latest

    gcc:latest

    graphviz

    gdb 

    git-core

    gnutls-bin

    libglib2.0-dev

    libpcap-dev

    libgcrypt-dev

    libncurses5-dev

    libjsoncpp-dev

    libssl-dev

    libtool-bin

    libtool

    libwireshark-dev

    libxml2-dev

    lsof

    ntp

    pkg-config

    qt5-default

    qtmultimedia5-dev

    libqt5svg5-dev

    subversion

    sudo

    sshpass

    tcpdump

    texlive-font-utils

    tshark

    valgrind

    vim

    vsftpd

    xutils-dev 

    tree

    tzdata

    unzip

    wget

    xsltproc

- Clone the NGAP/NAS Conformance Test System project into $HOME/dev folder

```sh

$ git clone --branch=devel --recurse-submodules --remote-submodules https://forge.etsi.org/rep/int/5g-core/nas.git

```

- Execute the script install.sh

```sh

$ ./install.sh

```

- Build a test suite (e.g. AtsNGAP)

```sh

$ export ATS=AtsNGAP && make

```

- Switch to the next clause (Usage)

# Usage

This clause describes how to compile and execute an Abstract Test Suite.

The procedures below illustrate how to run the AtsNGAP test suite. The same procedures will apply for any other NGAP/NAS Test Suite.

Pre-requisites:

- Your machine is installed following one of the installation method describes in the previous clause

- Your are logged as 'etsi' or 'vagrant' user

- Procedure using TITAN command line (only):

    - Open several SSH session (PuTTY...)

    - Change to the directory ~/dev/nas/

    - Modify the file config.mk according to your system:

        - On Linux, comment all the lines using the '#' character

        - On Windows, update the path accordingly

    - Build the test suite AtsNGAP using the following command:

```sh

$ export ATS=AtsNGAP # The Abstract Test Suite you want to build, such as AtsNGAP...

$ make

...

```

Before to execute the NGAP/NAS Test Suite, prepare, edit and update the configuration file (e.g. AtsNGAP Test Suite):

- Update the following fields:

    - system.NGAP_AMF.params

    - system.N2_gNBaMF_P.params

- Update the PICS and PIXITs accordingly

```sh

$ ln -sf ../../etc/AtsNGAP/AtsNGAP_AMF_open5gs.cfg_ ../../etc/AtsNGAP/AtsNGAP.cfg

$ vi ../../etc/AtsNGAP/AtsNGAP.cfg # To update it

```

To run the NGAP/NAS Test Suite, execute the following command:

```sh

$ cd ~/dev/nas/scripts

$ ../run_all.bash

...

```

- The log files are located in ../logs/AtsNGAP folder for this example. You can edit them using any editor or using the Eclipse TITAN log plugins

# Limitations

The following limitations apply:

- AE test suite was not validated;

- CBOR is not supported;

- XML is not supported;

- Subscription/notification mechanism testing not implemented yet.

# How to Report a Bug

The NGAP/NAS Conformance Test System project is under constant development, so it is possible that you will

encounter a bug while using it. Please report bugs at cti_support at etsi dot org.

## Project status

If you have run out of energy or time for your project, put a note at the top of the README saying that development has slowed down or stopped completely. Someone may choose to fork your project or volunteer to step in as a maintainer or owner, allowing your project to keep going. You can also make an explicit request for maintainers.

[MODULE_PARAMETERS]

# This section shall contain the values of all parameters that are defined in your TTCN-3 modules.

# https://www.binaryhexconverter.com/hex-to-binary-converter

NGAP_Pics.PICS_NGAP_AMF_IUT    := true

NGAP_Pics.PICS_NGAP_GNB_IUT    := false

LibNGAP_Pics.PICS_OFFLINE_MODE := false

LibNGAP_Pics.PICS_OFFLINE_MODE := false # true for offline mode with pcap files, false for online mode with SCTP server

# 5GRegAuthSec_deReg.pcap

LibNGAP_Pixits.PX_AMF_NAME         := "open5gs-amf0"

LibNGAP_Pixits.PX_RAN_UE_NGAP_ID   := 1

LibNGAP_Pixits.PX_AMF_UE_NGAP_ID   := 2

LibNGAP_Pixits.PX_PLMN_IDENTITY    := '99f907'O

LibNGAP_Pixits.PX_AMF_REGION_ID    := '00000010'B

LibNGAP_Pixits.PX_AMF_SET_ID       := '0000000001'B

LibNGAP_Pixits.PX_AMF_POINTER      := '000000'B

LibNGAP_Pixits.PX_RAN_NODE_NAME    := "gnb0012345"

LibNGAP_Pixits.PX_GNB_ID           := '00000000000000000000000000000001'B

LibNGAP_Pixits.PX_RAN_NODE_NAME    := "UERANSIM-gnb-999-70-1"

LibNGAP_Pixits.PX_TACode           := '000001'O

LibNGAP_Pixits.PX_SST              := '01'O

LibNGAP_Pixits.PX_SD               := '000009'O

LibNGAP_Pixits.PX_PAGING_DRX       := v128

LibNGAP_Pixits.PX_AMF_NAME         := "open5gs-amf0"

LibNGAP_Pixits.PX_AMF_REGION_ID    := '00000010'B

LibNGAP_Pixits.PX_AMF_SET_ID       := '0000000001'B

LibNGAP_Pixits.PX_AMF_POINTER      := '000000'B

LibNGAP_Pixits.PX_RAN_UE_NGAP_ID   := 1

LibNGAP_Pixits.PX_AMF_UE_NGAP_ID   := 2

LibNGAP_Pixits.PX_PDU_SESSION_ID   := 1

Lib_NG_NAS_Pixits.PX_FORCE_USING_OPERATOR_SECRET_KEY := true

Lib_NG_NAS_Pixits.PX_SUBSCRIPTION_KEY                := '01000110010110110101110011101000101100011001100110110100100111111010101001011111000010100010111011100010001110001010011010111100'B

# https://www.binaryhexconverter.com/hex-to-binary-converter

Lib_NG_NAS_Pixits.PX_PLMN                            := '99f907'O;

Lib_NG_NAS_Pixits.PX_BEARER_ID                       := '00001'B

Parameters.px_IMSI_Def                               := '393939373030303030303030303031'H # 999700000000001

system.NGAP_AMF.params := "NGAP/SCTP(server=127.0.0.5,port=38412,debug=1)"

# Open5GS pcap files

#system.NGAP_AMF.params := "NGAP/SCTP_FILE/IP_OFFLINE/ETH(mac_src=8c554ac1eee0,mac_dst=8c554ac1eee1)/PCAP_FILE(file=../captures/open5gs.pcap)"

#system.NGAP_AMF.params := "NGAP/SCTP_FILE/IP_OFFLINE/PCAP_FILE(file=../captures/ttcn_5g_ngap.pcapng)" # Linux cooked capture v2, no Ethernet layer

#system.NGAP_AMF.params := "NGAP/SCTP_FILE/IP_OFFLINE/ETH(mac_src=8c554ac1eee0,mac_dst=8c554ac1eee1)/PCAP_FILE(file=../captures/open5gs.pcap)" # regular pcap with Ethernet layer

[DEFINE]

# In this section you can create macro definitions,

                            Authentication_parameter_AUTN

						;

				;

				to the UE entity

				to the GNB entity

            }

        ;

    } // End of Domain section