Tunnel Setup

 

 

Tunnel Setup #

The Tunnel Security Levels #

The tunnel HMAC/encrytion parameter shortcode consists of two parts:

  1. The Tunnel HMAC Level
  • H0 - default authentication
  • H1 - authentication with a secret (tunnel-hmac-secret is set)
  • H2 - authentication with a 2^32 rotating random secret (tunnel-hmac-material is set)
  • H3 - authentication with both XORed (both, tunnel-hmac-secret and tunnel-hmac-material are set)
  1. The Tunnel Encryption Level
  • E0 - no encryption
  • E1 - encryption with a preshared key (tunnel-key-secret is set)
  • E2 - encryption with a 2^32 rotating random key (tunnel-key-material is set)
  • E3 - authentication with both XORed (both, tunnel-key-secret and tunnel-key-material are set)

Both combined result in 16 possible tunnel security levels to choose from, the corresponding shortcode ranges from H0E0 to H3E3.

The Registry Security Levels #

For communication with a EtherTunnel registry there are the following possibilities:

  1. The Registry HMAC Level
  • H0 - default authentication
  • H1 - authentication with a secret (tunnel-registry-secret is set)
  1. The Tunnel Encryption Level
  • E0 - no encryption
  • E1 - encryption with a preshared key (tunnel-registry-secret is set)

Both combined result in 4 possible registry security levels ranging from H0E0 to H1E1. The registry security level shortcode exists implicitly and does not appear as such in the CLI or in the EtherTunnel log messages.

Generating random material from /dev/urandom #

A shared random material file for tunnel-hmac-material and tunnel-key-material requires 32KB of random data (the file may be larger).

To generate this with dd works like this:

$ dd if=/dev/urandom bs=32768 count=1 > material.random
1+0 records in
1+0 records out
32768 bytes (33 kB, 32 KiB) copied, 0.000121559 s, 270 MB/s

If available you may of course use your TRNG device instead.

Examples #

The basic H0E0 Tunnel #

This example establishes a tunnel using the default HMAC authentication with encryption switched off. Both peers know each other, the Ethernet LANs connected to enp1s0f0 on each side are connected as with an Ethernet cable as soon as the tunnel is established.

Side A # 

1
2

tunnel-interfaces     = enp1s0f0
tunnel-remote-address = sideb.example.com

Side B # 

1
2

tunnel-interfaces     = enp1s0f0
tunnel-remote-address = sidea.example.com

An H1E1 Tunnel with an additional VLAN #

This configuration establishes a H1E1 tunnel and additionally transports VLAN 20. The 8021q module takes care of the tagging/untagging.

Side A # 

1
2
3
4

tunnel-interfaces     = enp1s0f0 enp1s0f0.20
tunnel-remote-address = sideb.example.com
tunnel-hmac-secret    = "MyHMACSecret"
tunnel-key-secret     = "MyKeySecret"

Side B # 

1
2
3
4

tunnel-interfaces     = enp1s0f0 enp1s0f0.20
tunnel-remote-address = sidea.example.com
tunnel-hmac-secret    = "MyHMACSecret"
tunnel-key-secret     = "MyKeySecret"

H2E2 Tunnel with two VLANs and Registry fallback #

This configuration configures a H2E2 tunnel and transports VLAN 20 and VLAN 21. As long as the tunnel is not established, the registry myregistry.example.com is additionally consulted to find a peer with the tunnel name “TestConnection” (which has to be present and the same on both sides).

Side A # 

1
2
3
4
5
6

tunnel-interfaces     = enp1s0f0 enp1s0f0.20 enp1s0f0.21
tunnel-name           = "TestConnection"
tunnel-remote-address = sideb.example.com
tunnel-hmac-material  = "/home/test/hmac-material.random"
tunnel-key-material   = "/home/test/key-material.random"
registry-address      = myregistry.example.com

Side B # 

1
2
3
4
5
6

tunnel-interfaces     = enp1s0f0 enp1s0f0.20 enp1s0f0.21
tunnel-name           = "TestConnection"
tunnel-remote-address = sidea.example.com
tunnel-hmac-secret    = "MyHMACSecret"
tunnel-key-secret     = "MyKeySecret"
registry-address      = myregistry.example.com

The matching H0E0 Registry #

To start the H0E0 registry for this example executing a ethtun start on myregistry.example.com with no or an empty configuration is all that’s required.

H3E3 Tunnel Registry only with Filters #

In this example both endpoints do not know each other, so the registry myregistry.example.com is consulted to find the peer for the tunnel name TestConnection. The authentication towards the registry

Side A # 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

tunnel-interfaces       = enp1s0f0
tunnel-name             = "TestConnection"
tunnel-hmac-secret      = "MyHMACSecret"
tunnel-hmac-material    = "/home/test/hmac-material.random"
tunnel-key-secret       = "MyKeySecret"
tunnel-key-material     = "/home/test/key-material.random"
registry-address        = myregistry.example.com
registry-hmac-secret    = "RegistrySecret"
filter-nic-etype-allow  = 0x0800    # IPv4
                          0x0806    # ARP
                          0x86dd    # IPv6

Side B # 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

tunnel-interfaces       = enp1s0f0
tunnel-name             = "TestConnection"
tunnel-hmac-secret      = "MyHMACSecret"
tunnel-hmac-material    = "/home/test/hmac-material.random"
tunnel-key-secret       = "MyKeySecret"
tunnel-key-material     = "/home/test/key-material.random"
registry-address        = myregistry.example.com
registry-hmac-secret    = "RegistrySecret"
filter-nic-etype-allow  = 0x0800    # IPv4
                          0x0806    # ARP
                          0x86dd    # IPv6

The matching H1E0 Registry #

The configuration of the registry running on myregistry.example.com just needs the matching parameter registry-hmac-secret configured in that case:

1

registry-hmac-secret    = "RegistrySecret"