Review README file

# ETSI ITS protocols project

## General Information

## Introduction

This repositories contains the test specifications and test adapter code for ETSI ITS protocols testing, Release 2.

This repositories contains the test specifications and test adapter code for ETSI ITS protocols testing, Release 1.

ETSI ITS protocols project supports:

- ETSI EN 302 637-2: "Intelligent Transport Systems (ITS); Vehicular Communications; Basic Set of Applications; Part 2: Specification of Cooperative Awareness Basic Service"

- ETSI EN 102 637-3: "Intelligent Transport Systems (ITS); Vehicular Communications; Basic Set of Applications; Part 3: Specifications of Decentralized Environmental Notification Basic Service" 

- EN 302 636-4-1: "Intelligent Transport Systems (ITS); Vehicular Communications; GeoNetworking; Part 4: Geographical addressing and forwarding for point-to-point and point-to-multipoint communications; Sub-part 1: Media-Independent Functionality"

In addition, it also support ITS Security as define by:

- ETSI TS 102 941: "Intelligent Transport Systems (ITS); Security; Trust and Privacy Management technical specification"

- ETSI TS 103 097: "Intelligent Transport Systems (ITS); Security; Security header and certificate formats".

- ETSI TS 103 940: "Intelligent Transport Systems (ITS); Security; Security Architecture and Management".

- ETSI TS 103 759: "Intelligent Transport Systems (ITS); Security; isbehaviour Reporting service; Release 2"

- P1609.2™/D13: "Draft Standard for Wireless Access in Vehicular Environments – Security Services for Application and Management Messages"

- P1609.2.1™/D7: "Draft Standard for Wireless Access in Vehicular Environments (WAVE) – Certificate Management Interfaces for End Entities"

- ETSI TS 103 097: "Intelligent Transport Systems (ITS); Security; Security header and certificate formats".

- ETSI TS 102 941: "Intelligent Transport Systems (ITS); Security; Trust and Privacy Management technical specification"

- IEEE Std 1609.2™-2016: "IEEE Standard for Wireless Access in Vehicular Environments –Security Services for Applications and Management Messages"

- IEEE Std 1609.2a™-2017: "Standard for Wireless Access In Vehicular Environments – Security Services for Applications and Management Messages Amendment 1".

Contact information

Email at cti_support at etsi dot org

## Contact information

License

Unless specified otherwise, the content of this repository and the files contained are released under the ETSI Software License.

See the attached LICENSE file or visit

https://forge.etsi.org/etsi-software-license

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 ITS protocols project:

- STF 405, STF 422, STF 424, STF 455, STF 462, STF 481, STF 484, STF 507, STF 517, STF 525, STF 538, STF 545, STF 594, TTF T002, TTF T011, TTF T024

- STF 405, STF 422, STF 424, STF 455, STF 462, STF 481, STF 484, STF 507, STF 517, STF 525, STF 538, STF 545, STF 594, TTF T002, TTF T011

## Installation

# Installation

The ETSI ITS protocols project builds and tests regularly on the following platforms:

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

### How to do it?

## How to do it?

They are three different methods:

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

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 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

### 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)

### Using Vagrant

## 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 [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

- Install Docker

Procedure:

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

- From the ETSI ITS protocols 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:

Procedure on the host machine:

- Open a Terminal

- Clone the ETSI ITS Test System

```sh

$ vagrant up --provider virtualbox --provision

...

$ git clone --recurse-submodules https://forge.etsi.org/gitlab/ITS/TS.ITS.git ./TS.ITS_r1

```

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

- Stop vagrant virtual machine

- Select the branch you need:

 ITS Release 1

```sh

$ vagrant halt

...

$ git checkout devel

```

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

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

 ITS Release 2

```sh

$ vagrant up

...

$ vagrant ssh

$ git checkout ttf_t024

```

- Switch to the next clause (Usage)

- From the ETSI ITS Test System root directory, build the Docker image executing the following commands:

```sh

$ cd ./virtualization/docker

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

$ docker images

```

To build the ITS Test Suite, execute the following command:

```sh

$ ./docker-run.sh build

```

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

To retrieve the list of the available test cases, execute the following command:

```sh

$ ./docker-run.sh list

```

Before to execute the ITS Test Suite, prepare, edit and update the configuration file (e.g. CAM Test Suite):

```sh

$ ln -sf ../../etc/AtsCam/AtsCAM_xxx.cf_ ../../etc/AtsCam/AtsCAN.cfg

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

```

To execute the ITS Test Suite, execute the following command:

```sh

$ ./docker-run.sh run

```

<b>Notes</b>:

- The ITS Test System is listening on port 442

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

. Selecting the test(s) to be executed

. Updating value of PICs and PIXITs

. Updating HTTP port setting

NOTE The user password is vagrant.

## Using development Docker image

### Using Docker

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

Pre-requisites on your host machine:

- Install Virtualbox (For Windows host only)

- Install Docker

Procedure for a Windows host machine:

- Switch to the next clause (Usage)

### From scratch

## Using Vagrant

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 ETSI ITS protocols 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

    - $HOME/dev

    - $HOME/lib

- In $HOME/frameworks, build the following package:

    - asn1c, according the procedure specified [here](https://github.com/vlm/asn1c.git)

    - Eclipse IDE for C/C++ Developers, according the procedure specified [here](https://www.eclipse.org/cdt/)

    - asn1c, according the procedure specified [here](https://github.com/fillabs/asn1c.git)

    - TITAN, according the procedure specified [here](https://github.com/eclipse/titan.core)

    - Import the TITAN plugin into your Eclipse IDE, according the procedure specified [here](https://github.com/eclipse/titan.core)

- Clone the ETSI ITS protocols project into $HOME/dev folder

```sh

$ git clone --recurse-submodules --single-branch https://forge.etsi.org/gitlab/ITS/TS.ITS.git

$ cd ${HOME}/dev/TS.ITS/

$ cp ./ttcn/patch_lib_common/module.mk ./ttcn/LibCommon/

$ cp ./ttcn/patch_lib_common/ttcn/* ./ttcn/LibCommon/ttcn

$ git clone --recurse-submodules https://forge.etsi.org/gitlab/ITS/TS.ITS.git ./TS.ITS_r1

```

- Select the branch you need:

 ITS Release 1 (this example)

```sh

$ git checkout devel

```

- Update your default environment with the content of the script $HOME/dev/TS.ITS/scripts/devenv.bash.ubuntu

- Switch to the next clause (Usage)

 ITS Release 2

```sh

$ git checkout ttf_t024

```

### Using Eclipse TITAN

- Apply the configuration

When cloning the ETSI ITS project, you can find two specific files:

- TS.ITS.tpd

- TS.ITS_Linux.tpd

```sh

$ ./switch_its_r2.sh

```

These two files are used create the ETSI ITS project workspace on Eclipse TITAN. To do it, please follow the steps below:

- Start eclipse using a new workspace, (e.g. with the name workspace_titan)

- Select the menu option File/import

- In the Dialog box,select TITAN/Project from .tpd file

- Select the correct TS.ITS.tpd file and follow the instructions

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

NOTE: When the Eclipse TITAN workspace is created, you have to build manually the librairy 'libasn1c.so' following the commands below:

```sh

$ cd <eclipse workspace>/TS.ITS

$ mkdir -p ./bin/asn1

$ cd ./bin/asn1

$ make CC=gcc -f ../../asn1/Makefile

$ rm *.cc # To prevent TITAN to import these .cc source files into our project

$ export ATS=AtsCAM && make

```

- Switch to the next clause (Usage)

## Usage

# Usage

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

The procedures below illustrate how to run the CAM test suite. The same procedures will apply for any other ETSI ITS test suite.

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

- Procedure using TITAN command line (only):

    - Open several SSH session (PuTTY...)

    - Change to the directory ~/dev/TS.ITS/

    - Change to the directory ~/dev/TS.ITS_r1/

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

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

        - On Windows, update the path accordingly

- To run the test suitem, execute the following command:

```sh

$ cd ~/dev/TS.ITS/scripts

$ cd ~/dev/TS.ITS_r1/scripts

$ ../run_all.bash

...

```

```sh

 cd ~/dev

$ git clone --recurse-submodules --single-branch https://forge.etsi.org/rep/ITS/itscertgen.git itscertgen

$ git clone --recurse-submodules https://forge.etsi.org/rep/ITS/itscertgen.git

cd itscertgen

make

```

### Generate the certificates

After applying the previous clause, change to the folder '~/dev/TS.ITS/data/certificates' and execute 'make' command:

After applying the previous clause, change to the folder '~/dev/TS.ITS_r1/data/certificates' and execute 'make' command:

```

$ cd ~/dev/TS.ITS/data/certificates

$ make

$ cd ~/dev/TS.ITS_r1/data/certificates

$ CERTGEN=~/dev/itscertgen/ make

$ CERTGEN=~/dev/itscertgen/ make install

```

The certificates will be located in the folder '~/dev/TS.ITS/data/certificates/certificates'.

The certificates will be located in the folder '~/dev/TS.ITS_r1/data/certificates/certificates'.

To use this newly generated certificates, you shall update two parameters located in the TTCN-3 file LibItsSecurity_Pixits. These are:

- LibItsSecurity_Pixits.PX_CERTIFICATE_POOL_PATH, which is the path the certificates folder (e.g. LibItsSecurity_Pixits.PX_CERTIFICATE_POOL_PATH := "/home/<user>/dev/TS.ITS/data/certificates")

- LibItsSecurity_Pixits.PX_CERTIFICATE_POOL_PATH, which is the path the certificates folder (e.g. LibItsSecurity_Pixits.PX_CERTIFICATE_POOL_PATH := "/home/<user>/dev/TS.ITS_r1/data/certificates")

- LibItsSecurity_Pixits.PX_IUT_SEC_CONFIG_NAME, which is the name of the certificates folder (e.g. LibItsSecurity_Pixits.PX_IUT_SEC_CONFIG_NAME := "certificates")

### Modify or create new certificates

The folder '~/dev/TS.ITS/data/profiles' contains an XML file for each certificate to be generated.

The folder '~/dev/TS.ITS_r1/data/profiles' contains an XML file for each certificate to be generated.

This XML file describes the certificate content (e.g. CERT_IUT_A_RCA.xml describes the root certificate for all CERT_IUT_A certificates).

By modifying these files, you can change create new certificate with different geographical area, different validity periods or different SSPs.

In addition, the Test System shall be configured to support the security modifying the following settings as described below:

- device_mode=1

- secured_mode=1

- sec_db_path=/home/<user>/dev/TS.ITS/data/certificates/certificates

- sec_db_path=/home/<user>/dev/TS.ITS_r1/data/certificates/certificates

### ITS Protocol Test suites for Transport layer

In addition, the Test System shall be configured to support the security modifying the following settings as described below:

- device_mode=1

- secured_mode=1

- sec_db_path=/home/<user>/dev/TS.ITS/data/certificates/certificates

- sec_db_path=/home/<user>/dev/TS.ITS_r1/data/certificates/certificates

### ITS Protocol Test suites for Security

- secured_mode=0

## Wireshark with support of ETSI ITS Protocols

# Wireshark with support of ETSI ITS Protocols

The official version of Wireshark, supporting ETSI ITS Protocols, is available [here](https://www.wireshark.org/download.html).

Some sample capture files are available [here](https://wiki.wireshark.org/SampleCaptures).

## How to Report a Bug

# How to Report a Bug

The ETSI ITS protocols 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.

export HOME_FRAMEWORKS=${HOME}/frameworks

export HOME_LIB=${HOME}/lib

export HOME_BIN=${HOME}/bin

export HOME_BIN=${HOME}/include

export HOME_ETC=${HOME}/etc

export HOME_TMP=${HOME}/tmp

export HOME_DOCS=${HOME}/docs

export HOME_FRAMEWORKS=${HOME}/frameworks

export HOME_LIB=${HOME}/lib

export HOME_BIN=${HOME}/bin

export HOME_BIN=${HOME}/include

export HOME_ETC=${HOME}/etc

export HOME_TMP=${HOME}/tmp

export HOME_DOCS=${HOME}/docs

# Turn on debug mode

#set -vx

set -e

#set -e

# Colors and Prompt

#export PS1="\w\$ "

export HOME_FRAMEWORKS=${HOME}/frameworks

export HOME_LIB=${HOME}/lib

export HOME_BIN=${HOME}/bin

export HOME_BIN=${HOME}/include

export HOME_ETC=${HOME}/etc

export HOME_TMP=${HOME}/tmp

export HOME_DOCS=${HOME}/docs

Subproject commit fdc5adbbaaa08e5b583eb90cb66aff370f9310bd

Subproject commit 4c952bd04cdbecdc17abe1f4001849f0247525b9