README.md 9.96 KB
Newer Older
garciay's avatar
garciay committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35
# ETSI ITS protocols project


## General Information

This repositories contains the test specifications and test adapter code for ETSI ITS protocols testing.
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" 
- ETSI TS 103 301: "Intelligent Transport Systems (ITS); Vehicular Communications; Basic Set of Applications; Facilities layer protocols and communication requirements for infrastructure services"
- EN 302 636-5-1: "Intelligent Transport Systems (ITS); Vehicular Communications; GeoNetworking; Part 5: Transport Protocols; Sub-part 1: Basic Transport Protocol"
- 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 103 940: "Intelligent Transport Systems (ITS); Security; Security Architecture and Management".
- 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

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

## STFs

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


## Installation

garciay's avatar
garciay committed
36
The ETSI ITS protocols project builds and tests regularly on the following platforms:
garciay's avatar
garciay committed
37 38 39

  - Linux (Ubuntu)

Yann Garcia's avatar
Yann Garcia committed
40
Note: The [OpenSSL](https://www.openssl.org) version > 1.1.x is also required.
Yann Garcia's avatar
Yann Garcia committed
41

Yann Garcia's avatar
Yann Garcia committed
42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62
### How to do it?

They are two different methods:
- Using [Vagrant](https://www.vagrantup.com/)
- Using [Docker](https://www.docker.com/)

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.


garciay's avatar
garciay committed
63 64 65 66 67
### 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/)
garciay's avatar
garciay committed
68
- Install Vagrant plugin vagrant-vbguest
Sebastian Müller's avatar
Sebastian Müller committed
69 70 71
- 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
garciay's avatar
garciay committed
72 73

Procedure:
garciay's avatar
garciay committed
74
- On your host machine, open a command line session (PuTTY, DOS window...)
garciay's avatar
garciay committed
75
- From the ETSI ITS protocols project, clone the Vagrant folder
Yann Garcia's avatar
Yann Garcia committed
76
- In the file Vagrantfile, modify the tag config.vm.provision replacing <username> & <password> strings by your ETSI credentials
garciay's avatar
garciay committed
77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100
- In the Vagrant folder, 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
```

garciay's avatar
garciay committed
101
- Switch to the next clause (Usage)
garciay's avatar
garciay committed
102

garciay's avatar
garciay committed
103
NOTE The user password is vagrant.
garciay's avatar
garciay committed
104

garciay's avatar
garciay committed
105 106

### Using Docker
garciay's avatar
garciay committed
107 108

Pre-requisites on your host machine:
YannGarcia's avatar
YannGarcia committed
109
- Install Virtualbox (For Windows host only)
garciay's avatar
garciay committed
110
- Install Docker
garciay's avatar
garciay committed
111

garciay's avatar
garciay committed
112
Procedure for a Windows host machine:
YannGarcia's avatar
YannGarcia committed
113
- On your host machine, open a the Docker Quickstart Terminal and change to a working folder such as ./temp/docker_its
Yann Garcia's avatar
Yann Garcia committed
114 115

Procedure for a Linux host machine:
YannGarcia's avatar
YannGarcia committed
116
- On your host machine, open a terminal and change to a working folder such as $HOME/temp/docker_its
Yann Garcia's avatar
Yann Garcia committed
117

YannGarcia's avatar
YannGarcia committed
118 119 120 121
On your host machine, download the following items from ETSI ITS protocols 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
Yann Garcia's avatar
Yann Garcia committed
122 123

From the your current directory, execute the following commands:
garciay's avatar
garciay committed
124 125 126 127 128 129 130 131 132 133 134

```sh
$ ./.jenkins.sh
...
```

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

```sh
$ ./docker/run-container.sh
garciay's avatar
garciay committed
135
...
garciay's avatar
garciay committed
136 137 138 139 140 141 142 143 144 145 146 147
```

- Switch to the next clause (Usage)


### From scratch

Pre-requisites:
- Install Virtualbox

Procedure:
- Install a new Linux Virtual machine (Mint, Debian...)
garciay's avatar
garciay committed
148 149 150 151 152 153 154
- 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
garciay's avatar
garciay committed
155
    dos2unix
garciay's avatar
garciay committed
156 157 158 159
    doxygen
    emacs
    expect
    flex
garciay's avatar
garciay committed
160 161
    g++:latest
    gcc:latest
garciay's avatar
garciay committed
162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187
    graphviz
    gdb 
    git-core
    gnutls-bin
    libglib2.0-dev
    libpcap-dev
    libgcrypt-dev
    libncurses5-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
garciay's avatar
garciay committed
188
    vim
garciay's avatar
garciay committed
189 190 191
    vsftpd
    xutils-dev 
    tree
garciay's avatar
garciay committed
192
    tzdata
garciay's avatar
garciay committed
193 194
    unzip
    wget
garciay's avatar
garciay committed
195
    xsltproc
garciay's avatar
garciay committed
196 197 198 199 200 201 202 203 204 205
- In your home directory, create the following folders: 
    - $HOME/frameworks, 
    - $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/)
    - 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
garciay's avatar
garciay committed
206 207 208 209 210 211

```sh
$ git clone 
```

- Update your default environment with the content of the script $HOME/dev/STF525_Its/scripts/devenv.bash.ubuntu
garciay's avatar
garciay committed
212 213 214 215 216 217 218 219 220 221
- 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 CAM test suite. The same procedures will apply for any other ETSI ITS test suite.


Pre-requisites:
Yann Garcia's avatar
Yann Garcia committed
222
- Your machine is installed following one of the installation method describes in the previous clause
garciay's avatar
garciay committed
223
- Refer to the ETSI TS 103 099 for the description of the Test System architecture and configuration
garciay's avatar
garciay committed
224
- Your are logged as 'etsi' or 'vagrant' user
garciay's avatar
garciay committed
225 226

Procedure using Eclipse TITAN:
227 228 229
- Start eclipse using a new workspace, (e.g. with the name workspace_titan)
- Download and follow the steps to install Eclipse plugins for TITAN, accessible [here]{https://www.eclipse.org/downloads/download.php?file=/titan/Eclipse_installationguide.pdf}
- Open the workspace_titan
Yann Garcia's avatar
Yann Garcia committed
230
- Create a new TITAN project (e.g. STF525_Its)
garciay's avatar
garciay committed
231
<TODO>
garciay's avatar
garciay committed
232 233

Procedure in TITAN command line:
garciay's avatar
garciay committed
234
- Open several SSH session (PuTTY...)
garciay's avatar
garciay committed
235
- Change to the directory ~/dev/STF525_Its/src/AtsCAM/objs
garciay's avatar
garciay committed
236 237 238 239 240 241 242
- Build the test suite AtsCAM

```sh
$ ../bin/cam_generate_makefile.bash
...
```

garciay's avatar
garciay committed
243
- Edit the file ../etc/AtsCAM.cfg
garciay's avatar
garciay committed
244
- Update the following fields (see ETSI TS 103 099 for details):
garciay's avatar
garciay committed
245 246
    - system.camPort.params
    - system.utPort.params
garciay's avatar
garciay committed
247
- To run the test suitem, execute the following command:
garciay's avatar
garciay committed
248 249 250

```sh
$ ../bin/run-all.bash
garciay's avatar
garciay committed
251
...
garciay's avatar
garciay committed
252
```
garciay's avatar
garciay committed
253

garciay's avatar
garciay committed
254
- The log files are located in ../logs folder. You can edit them using any editor or using the Eclipse TITAN log plugins
garciay's avatar
garciay committed
255

256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287
## How to generate ITS test certificates

The Test System includes a tool, asn1cert, to generate ITS test certificates used for Conformance Testing.
This tool is located in the folder '~/dev/STF525_Its/tools/itscertgen/'.

Note: These certificates can not be used in a true architectures, there are present only for testing and/or debug purposes.


### Build the tool 'asn1cert'

To build the tool, run the 'make' command in each of the following folders:
- cshared
- cxml
- checker
- asn1certgen


### Generate the certificates

After that change to the folder '~/dev/STF525_Its/data/v3' and execute 'make command.
The certificates will be located in the folder '~/dev/STF525_Its/data/v3/certificates'.


### Modify or create new certificates

The folder '~/dev/STF525_Its/data/v3/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.

To re-generates the certificates, refer to the previous clause.

garciay's avatar
garciay committed
288

Yann Garcia's avatar
Yann Garcia committed
289
## Wireshark with support of ETSI ITS Protocols
garciay's avatar
garciay committed
290

Yann Garcia's avatar
Yann Garcia committed
291
The official version of Wireshark, supporting ETSI ITS Protocols, is available [here](https://www.wireshark.org/download.html).
292
Some sample capture files are available [here](https://wiki.wireshark.org/SampleCaptures).
garciay's avatar
garciay committed
293

garciay's avatar
garciay committed
294 295 296

## How to Report a Bug

garciay's avatar
garciay committed
297
The ETSI ITS protocols project is under constant development, so it is possible that you will
garciay's avatar
garciay committed
298
encounter a bug while using it. Please report bugs at cti_support at etsi dot org.