Enhance README files

# ETSI ITS protocols project

## General Information

## Introduction

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

ETSI ITS protocols project supports:

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

## STFs

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

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 TITAN compiler on a Docker image

Procedure on the host machine:

- Open a Terminal

- Clone the ETSI ITS Test System

```sh

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

```

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

```sh

- 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 ./TTF011_Its

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

```

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

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

- Switch to the next clause (Usage)

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

$ cd <eclipse workspace>/TS.ITS

$ mkdir -p ./bin/asn1

$ cd ./bin/asn1

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

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

- Procedure using TITAN command line (only):

    - Open several SSH session (PuTTY...)

    - Change to the directory ~/dev/TTF011_Its/

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

    - 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/TTF011_Its/scripts

$ cd ~/dev/TS.ITS/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 --single-branch https://forge.etsi.org/rep/ITS/itscertgen.git

cd itscertgen

make

```

### Generate the certificates

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

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

```

$ cd ~/dev/TTF011_Its/data/certificates

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

$ make

```

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

The certificates will be located in the folder '~/dev/TS.ITS/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/TTF011_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/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/TTF011_Its/data/profiles' contains an XML file for each certificate to be generated.

The folder '~/dev/TS.ITS/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/TTF011_Its/data/certificates/certificates

- sec_db_path=/home/<user>/dev/TS.ITS/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/TTF011_Its/data/certificates/certificates

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

### ITS Protocol Test suites for Security

echo -e "*****************************\n* Install asn1c\n*****************************\n"

cd ${HOME}/frameworks || exit 1

git clone https://github.com/fillabs/asn1c.git ./asn1c.fillabs || exit 1

git clone --branch=vlm_test https://github.com/fillabs/asn1c.git ./asn1c.fillabs || exit 1

cd ./asn1c.fillabs

autoreconf -iv && ./configure --prefix=${HOME} && make install || exit 1

RUN \

    mkdir -p frameworks dev tmp \

    && cd frameworks \ 

    && git clone https://github.com/fillabs/asn1c.git ./asn1c \

    && git clone --branch=vlm_test https://github.com/fillabs/asn1c.git ./asn1c \

    && cd ./asn1c \

    && autoreconf -iv && ./configure --prefix=${HOME} && make install \

    && cd - \

# HOWTO build docker images

## General imformation

Pre-requisites on your host machine:

- Install [Docker](https://docs.docker.com/install/)

#### From Windows host:

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

- Install any X Server. For example [VcXsrv](https://sourceforge.net/projects/vcxsrv/)

#### From Mac host:

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

- Install [XQuartz](https://www.xquartz.org)

#### From Linux host:

- No other requirements

## Build 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 ETSI ITS Test System

```sh

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

cd ${HOME}/dev/TS.ITS/titan-test-system-framework

git checkout devel

cd ./ttcn/LibHttp

ln -sf module_its.mk module.mk

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

git checkout devel

```

- 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

# Checkout TS.ITS sources

cd /home/vagrant/dev

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

git clone --recurse-submodules --branch=devel --single-branch https://forge.etsi.org/rep/ITS/TS.ITS.git TS.ITS

cd ./TS.ITS

for i in `find ./ttcn -type d -name "Ats*"`

do

# Install asn1c

cd ${HOME_FRAMEWORKS}

git clone https://github.com/fillabs/asn1c.git asn1c

git clone --branch=vlm_test https://github.com/fillabs/asn1c.git asn1c

cd ${HOME_FRAMEWORKS}/asn1c

test -f configure || autoreconf -iv

./configure