PLA software documentation

Installation

1. Requirements

• At least two computers
• Working network supporting IPv6.
• Linux kernel 2.6.15, or newer.
  • Kernel needs to have IPv6 and IPv6 packet filtering configured.
  • Kernel needs user space packet queueing for IPv6:
    1. Go to: Networking -> Networking Options -> Network Packet Filtering -> IPv6: Netfilter Configuration
    2. Select all boxes in the menu as modules.
  • Make sure that there exist a symlink from /lib/modules/linux-x.y.z/build to /usr/src/linux
• OpenSSL libraries and headers.
• GNU MP Bignum library version 4.20 or newer.
• User space tools for IPv6 netfilter configuration. Especially ip6tables
• Synchronized clocks on the nodes. By default, a time difference of more than 3 seconds in the clocks of the nodes in the network will result in dropped packets. Using NTP for synchronizing clocks is recommended.
• DHCP server is required for the FPGA board if the hardware acceleration is used

2. Compiling

• Untar the latest distribution
• If hardware acceleration is to be used, the IP address of the FPGA board must be specified in the user/ec_hw.h file under pla directory. For example:

  #define HW_HOST "10.0.0.3"

  Means that the IP address of the FPGA board is 10.0.0.3.

• Compile:

  make
  

Configuration

1. Creating necessary certificates

Before the PLA can be used, some certificates must be created and signed. This is done by using placonf tool from the pla directory.

First, a TTP certificate must be created with a following command, insert starting and ending date and time of the certificate in "YYYY-MM-DD HH:MM:SS" fields (currently these dates are ignored, but they must be given to the placonf). This step needs to be performed once.

./placonf ttp create "YYYY-MM-DD HH:MM:SS" "YYYY-MM-DD HH:MM:SS" > ttp.signed

Following steps must be carried out for each node that uses the PLA. Create an identity to the node.

./placonf id create > id1.tmp

Sign it with TTP certificate, again give valid starting and ending time of the certificate. Fields after "sign" denote rights and delegatable rights, value 1111 means full rights, rights fields are also currently ignored.

./placonf -C ttp.signed -K id1.tmp id sign 1111 1111 "YYYY-MM-DD HH:MM:SS" "YYYY-MM-DD HH:MM:SS" > id1.signed

Finally, verify that signing was successful.

./placonf -C id1.signed cert verify

cp id1.signed /etc/pla.conf

Rest of configuration is carried out by editing the 'start()' function of the startup script 'sp'

2. Enabling and disabling the packet signing

In the startup script, line containing 'eccrypto' determines wherever packets are signed by the PLA or not (-n flag), and wherever the hardware acceleration is used (-H flag. For example:

nice -n -20 ./eccrypto -n &

Means that the packets are not signed (-n flag for eccrypto) and:

nice -n -20 ./eccrypto &

Means that packets are signed. Note: signing packets in software is slow and this will significantly increase latency and decrease throughput. Finally:

nice -n -20 ./ecccrypto -H &

Means that hardware acceleration is used for verifying signatures

3. Specifying the location of certificate

The location of the certificate file is passed to the placonf utility via -C argument like this:

./placonf -C /etc/pla.conf kernelconfig configid || stop_quit

The default location is /etc/pla.conf

4. Iptables configuration

The rest of the startup script contains iptables configuration. The configuration depends wherever or not the PLA is used on all network interfaces. The configuration is chosen by the hostname of the node, thus the same script can be used for several nodes (as long as the script has entries for them).

4.1. PLA node contains only one network interface or the PLA is used on all interfaces

In this case, all packets are processed by the PLA. Only the following ip6tables related lines must be present:

ip6tables --table mangle -A OUTPUT -p all -j QUEUE
ip6tables --table mangle -A INPUT -p all -j QUEUE
ip6tables --table mangle -A FORWARD -p all -j QUEUE

4.2. There are two or more network interfaces and the PLA is not used on all of them

This is a slightly more complicated situation. Interfaces that are NOT using the PLA must be specified. Here is an example of the configuration where PLA is not used on eth0 interface:

ip6tables --table mangle -A OUTPUT -p all -o eth0 -j ACCEPT
ip6tables --table mangle -A OUTPUT -p all -j QUEUE

ip6tables --table mangle -A INPUT -p all -i eth0 -j ACCEPT
ip6tables --table mangle -A INPUT -p all -j QUEUE

ip6tables --table mangle -A FORWARD -p all -j QUEUE

This means that packets coming and goind to/from eth0 are not touched, but all other packets are processed by the PLA. Similarly, if there is a three or more interfaces, following lines must be added for each interface that is not using the PLA:

ip6tables --table mangle -A OUTPUT -p all -o interface_name -j ACCEPT
ip6tables --table mangle -A INPUT -p all -i interface_name -j ACCEPT

Testing

1. Starting the PLA

Execute the startup script with start argument in both PLA nodes, for example:

./sp start

The startup script should output something like this:

Starting PLA...
Configuring rho: 836a87e4df236eb6cbba42d694bd9c98c80b0843000000c0

If the startup scripts exit without an error and the IPv6 connection can be made between PLA nodes (ping6 can be used for testing) then the PLA is working. If signing of packets is enabled, latency should be tens of milliseconds.

2. Stopping the PLA

Run sp script with stop argument on PLA nodes:

./sp stop

Problems and bugs

PLA does not work

• Check that PLA kernel module is loaded successfully:

  /sbin/lsmod |grep pla

• Check that both computers have exactly the same time, use NTP if necessary to synchronize time.

PLA works when '-n' flag is used for eccrypto, but does not work otherwise

Make sure that the /etc/pla.conf certificate is valid by running:

./placonf -C /etc/pla.conf cert verify

Testing the hardware acceleration

Also placonf accepts -H flag, in which case it will use hardware for certificate verification:

./placonf -H -C /etc/pla.conf cert verify

In a case of a problem, this command can be used to check wherever the problem lies in the hardware acceleration (e.g. the connection between FPGA board and host PC is broken) or somewhere else.