WeOS
5.20.1

# IPsec Tunnelling Guide

## Introduction

WeOS provides virtual private network (VPN) support via IPsec VPNs. A switch can act as a VPN gateway in site-to-site, site-to-host, or host-to-host scenarios. Configured as a VPN gateway, it can be used to securely connect branch office networks with a central office network. The data traffic will be protected by encrypted tunnels when sent over the Internet.

## Overview

                           .--.-.
                          ( (    )__
                         (_,  \ ) ,_)  Internet/Public Network
                           '-'--`--'
                            |    |
         .------------------'    '--------------------.
         |                                            |
         |Public IP:                                  |Public IP:
         |192.168.0.1                                 |192.168.0.2
     .---+----.                                   .---+----.
     |        |           IPsec Tunnel            |        |
     | Alice  |===================================|  Bob   |
     |        | Responder               Initiator |        |
     '---+----'                                   '---+----'
         |                                            |
      .--.-.                                       .--.-.
     ( (    )__                                   ( (    )__
    (_,  \ ) ,_)                                 (_,  \ ) ,_)
      '-'--`--'                                    '-'--`--'
    Central Office network                    Branch office network

Figure 1: VPN tunnel connecting two branch office networks.

### IPsec concepts

- Peers: The two VPN gateways (Alice and Bob) are referred to as IPsec peers. The peers constitute the end-points, or gateways, of the secure tunnel. One of the peers will take the role of tunnel initiator and the other takes the responder role.

- Initiator and Responder: The VPN initiator is the peer that is responsible for initiating the tunnel establishment by contacting the other peer - the responder. In Figure 1 we have assumed that Alice is the responder and Bob is the initiator. A switch configured as a VPN gateway is able to act both as responder (default) and as initiator.

- Local and Remote Subnet: Each peer will define policies that describe which traffic should be allowed to pass through the established tunnel. Each peer will define the local and remote subnet, and all traffic between these subnets is sent securely through the tunnel. The policies work both ways, i.e. only traffic matching an inbound policy will be allowed after decryption.

- IDs: IKE identities of both peers are used with authentication round.

- Dead Peer Detection: The connectivity through an established IPsec tunnel may be broken unexpectedly, e.g., one of the peers go down or is disconnected, or if some kind of routing, NAT or firewall problem occurs on the path between them. Dead Peer Detection (DPD) can be used to discover and manage such situations. In DPD the peers exchange keep-alive messages to monitor if the remote peer is still reachable. If a peer determines connectivity to be broken, appropriate actions should be taken. Active DPD checking is only enforced if no IKE or ESP packet has been received for the configured DPD delay.

- Pre-Shared-Key Authentication: A pre-shared-key (PSK) is a shared secret that both peers know before establishing a secure connection. It is an easy-to-deploy option but requires strong secrets, i.e., chosen randomly with sufficient entropy. Care should be take to protect the secret from leaking so that nobody can impersonate a gateway.

### IPsec Protocol

IPsec is divided into two phases where you can think of the handshake taking place in phase 1 and secure data transmission happens in phase 2.

More specifically:

- Phase 1 establishes an Internet Key Exchange Security Association (IKE SA) where negotiation is performed in a secure manner for parameters such as encryption and authentication using the IKEv2 protocol.

- Phase 2 uses the established IKE_SA(s) to securely negotiate IPsec SA(s), often called CHILD_SA(s) and enable secure data transmission using the ESP protocol.

IKE and ESP settings is default set to Auto. If you have specific requirements you can instead manually specify the exact algorithms to use for each stage in the communication. For classical ciphers (like aes128) is selected then an authentication algorithm and Diffie-Hellman group also needs to be specified while a modern AEAD Algorithm automatically handles authentication during the cipher stage.

#### Options for IKE (phase 1)

- Classical Cipher: Specify authentication algorithm, e.g., aes128-sha256-x25519.
- AEAD Cipher: Requires a PRF parameter instead of authentication, e.g., aes128gcm16-prfsha256-x25519.

#### Options for ESP (phase 2)

- Classical Cipher: Same as in phase 1.
- AEAD Cipher: Becomes something like aes128gcm16-x25519. No PRF parameter.

Note

aes128gcm16 is the same algorithm as aes128gcm128 (128 bits is 16 bytes). WeOS currently only supports to specify the GCM/CCM length in bytes while you may find both syntaxes in examples online.

### Retransmission

Retransmission refers to the process of resending certain packets during the establishment of an IPsec connection or after DPD timeout. The process consists of 5 attempts with progressively longer relative timeout between attempts. If the peer does not respond within the retransmission attempts, totaling at 165s, the connection fails and a configured dpd-action is taken. This process is used during Connecting and Retransmission states.

### Supported features

- IKEv2 The Internet Key Exchange Version 2 (IKEv2) auxiliary protocol responsible for the mutual authentication
- PSK (Pre Shared Keys). Initiator and responder uses a shared secret (password) for authentication.
- Static IPs. Local address needs to be specified as an IP address that exists on an interface. Either use a static IP address for the outgoing interface (preferred) or wait until an IP address has been assigned to the outgoing interface before entering the IP address in the IPsec configuration.
- CLI configuration. Webgui configuration is not yet supported.

### Supported scenarios

For examples of use-cases, refer to the following document:

- Site-2-Site
- Host-2-Host

### Current limitations

- Certificate-based authentication not implemented.
- WeOS-4 compatibility (IKEv1) not implemented.
- Webgui not implemented.
- Responder should start before initiator. As a general rule when configuring IPsec, it is advisable to configure the responder before the initiator. This helps prevent dropped connection attempts. If the initiator attempts to connect and encounters failure due to the responder lacking a matching configuration, it may respond with ‘NO_PROPOSAL_CHOSEN.’ Following this, the initiator ceases any further connection attempts. To achieve this behavior, the responder must already have an IPsec daemon running (for instance, handling another tunnel).

## Configuration

Configure IPsec in the tunnel overview context:

    example:/#> config
    example:/config/#> tunnel

### Tunnels overview context

Here you can create or delete an IPsec tunnel instance, or show summary of your tunnels.

`[no] ipsec ID`

  Create new instance, or enter the configuration context of an existing instance.

  no
    remove an instance entirely.

    example:/config/tunnel/#> ipsec 1
    example:/config/tunnel/ipsec-1/#>

Note

Up to 25 instances is supported. However, the exact number of connections the server can handle can be further limited of performance reasons, as it depends on the platform, the traffic load of the established tunnels as well as the configuration of your unit.

### Instance Configuration Syntax

To configure and show details of a single IPsec tunnel instance

    example:/config/tunnel/#> ipsec 1
    example:/config/tunnel/ipsec-1/#> help

`[no] enable`
  Enable/disable tunnel. Useful to disable a fully configured tunnel before deployment, the configuration will remain dormant while disabled.
`[no] dpd-action <clear|trap|restart>`

  Dead Peer Detection (DPD) action to perform for this tunnel when communication is lost. When retransmission of DPD packets fails a peer take one of the following actions. Only clear is available for a responder while an initiator can take any action.

  clear
    Close the tunnel and does not take further action (default for Responder).
  trap
    Install a trap policy, which will catch matching traffic and tries to re-negotiate the tunnel on-demand.
  restart
    Immediately try to re-negotiate the tunnel under a fresh IKE handshake (default for Initiator).
  no
    Disable dead peer detection. Without DPD, the connection may remain active even if the peer becomes unresponsive.
`[no] dpd-delay <SEC>`
  Period time for DPD packets. Active DPD checking is only enforced if no IKE or ESP packet has been received for the configured DPD delay.
`[no] initiator`

  Role, initiator (client) or responder (server). Initiator is the one that sends initial request for IKE handshake.

  no
    Reset role to responder.
`[no] ike cipher <option> auth|prf <option> dh <option>`

  Phase-1 handshake negotiation. no cipher activates default settings.

  Note

  AEAD ciphers needs a PRF algorithm while the other ones needs an auth algorithm instead. The AEAD ciphers are those with CCM or GCM in the name.

  cipher
    Encryption algorithm
  auth
    Authentication mechanism
  prf
    Pseudo random function
  dh
    Diffie-Hellman group
`[no] esp cipher <option> [auth <option>] dh <option>`

  Phase-2 handshake negotiation.

  Note

  AEAD ciphers do not use an auth algorithm. The AEAD ciphers are those with CCM or GCM in the name.

  cipher
    Encryption algorithm
  prf
    Pseudo random function
  dh
    Diffie-Hellman group
`[no] secret <SECRET>`

  Mandatory pre-shared key when PSK method is used.

  SECRET
    MIN:8 MAX:63 Valid characters are ASCII characters 33-126, except ‘#’ which is the CLI comment character.
`[no] peer <ADDRESS>`

  When acting as an initiator, the peer refers to the remote server IP to connect to. As a responder, it can be used to allow a specific IP or ANY address, which is the default setting when set to `no peer`.

`[no] local-address <ADDRESS>`

  This is the local address of the outbound interface. It must be set for the tunnel to work.

`[no] local-id <inet <ADDRESS> | name <DOMAIN|USER> | email <USER@DOMAIN> | key <ID> | dn <STRING>>`

  Set the identifier (type and value) for the VPN gateway. The local-id is used by the VPN gateway during the IKE handshake. Typically the ”name” type with a simple ID text string (e.g., alice) can be used to identify the VPN gateway.

  no
    The value sets local-id to Auto, which defaults to the local-address when PSK is selected.

  Supported standard RFC2407 ID types:

  Type | Description | Example
  --- | --- | ---
  inet | ID_IPV4_ADDR | 192.168.1.10
  name | ID_FQDN | server.example.com
  email | ID_USER_FQDN | user@example.com
  key | ID_KEY_ID | my_vpn_key
  dn | ID_DER_ASN1_DN | CN=John Doe, OU=IT, O=Company

`[no] remote-id <inet <ADDRESS> | name <DOMAIN|USER> | email <USER@DOMAIN> | key <ID> | dn <STRING>>`

  Remote peer ID. IKE identity to expect for authentication round.

  Types are the same for local-id.

  no
    Will result in “Auto” setting, which has different meaning depending on the role. When acting as a responder it means accepting any remote peer, as an initiator it is set to peer’s IP address.
`[no] local-subnet <ADDRESS/LEN | ADDRESS[ NETMASK]>`

  Subnet to expose to other side of VPN tunnel. Only traffic from this IP range is allowed to enter the tunnel through this gateway, and traffic arriving through the tunnel is only accepted when destined to an address in this range.

  no
    Only traffic to/from the IP address of the local-address interface will be allowed through the tunnel, e.g., ”192.168.0.1/32”.
`[no] remote-subnet <ADDRESS/LEN | ADDRESS[ NETMASK]>`

  Remote subnet allowed to access your local site. `no remote-subnet` gets replaced by peer’s address.

`[no] description <STRING>`

  Short free form description of this IPSec tunnel.

## Cipher Suites

A cipher suite is a combination of algorithms to use in different stages of the secure communication. The cipher is used for encryption, authentication is used to verify the message integrity (that it is recieved unchanged), prf is used to derive subkey and Diffie-Hellman group is used during key exchange.

### Classical ciphers

Classical ciphers are specified together with an authentication algorithm and a Diffie-Hellman group. The cipher algorithms supported are:

Algorithm | Description
--- | ---
aes128 | AES, 128 bit key in CBC mode.
aes128ctr | AES, 128 bit key in CTR mode.
aes256 | AES, 256 bit key in CBC mode.
aes256ctr | AES, 256 bit key in CTR mode.

### AEAD ciphers

Authenticated Encryption (with Associated Data) algorithms automatically do authentication while encrypting so no authentication algorithm should be specified together with these ciphers. CCM ciphers use a Counter mechanism with CBC-MAC and GCM ciphers use a mechanism called Galois/Counter mode.

Algorithm | Description
--- | ---
aees128ccm12 | 128 bit AES-CCM with 12 byte ICV.
aes128ccm16 | 128 bit AES-CCM with 16 byte ICV.
aees128gcm12 | 128 bit AES-GCM with 12 byte ICV.
aes128gcm16 | 128 bit AES-GCM with 16 byte ICV.

### Authentication

These should be specified if a classical cipher is selected. All supported algorithms use the HMAC construct with an inner hash primitive. The inner primitive can be one of:

Algorithm | Description
--- | ---
sha1 | Deprecated, but needed for WeOS-4 compatibility.
sha256 | SHA2-256
sha384 | SHA2-384
sha512 | SHA2-512

### Pseudo Random Function

The PRF algorithm is used for key derivation. It should only be specified for IKE (phase 1) and only if an AEAD cipher has been selected for IKE. In that case, choose one of:

- prfsha256
- prfsha384
- prfsha512

### Diffie-Hellman group

The Diffie-Hellman group is used for key exchange. Choose one of:

Group Name | Bit Length | Description
--- | --- | ---
modp2048 | 2048 | modp, group 14, RFC 3526
modp3072 | 3072 | modp, group 15
modp4096 | 4096 | modp, group 16
ecp256 | 256 | elliptic curve, group 19, RFC 5903
ecp384 | 384 | elliptic curve, group 20
ecp521 | 521 | elliptic curve, group 21
x25519 | 256 | elliptic curve 25519, group 31, RFC 8031

## Status and debugging.

The tunnel exec context allow for showing status of an already configured IPsec tunnels or execute control commands to the IPsec daemon. When debugging a tunnel, examining the log is quite useful.

### Show status

    example:/#> tunnel
    example:/tunnel/#> show ipsec
    ID  DESCRIPTION      STATUS               TIME (since last rekey)
    1   ipsec1           Up(Installed)        0 Days 2 Hours 11 Mins 28 Secs

#### States

A tunnel can have one of the following execution statuses:

- Down: A tunnel is configured but the daemon doesn’t do anything about it.

- Down(Connecting): Initiator is tries to establish a new tunnel. Persisting of this state can indicate troubles in reaching the peer.

- Down(IKE Established): Phase 1 handshake was successful but no CHILD_SA was created. When persistent, it might indicate configuration problems, e.g. when subnets on both side don’t match. Examine syslog to understand the issue.

- Up(Installed): Everything works, tunnel is operational sending encrypted data.

  Note

  This is the only “Up” state.

- Down(Retransmission): Dead Peer Detection (DPD) request went unanswered. See next section for details.

To show details of an ongoing connection:

    example:/tunnel/#> show ipsec 1
    ipsec1: #1, ESTABLISHED, IKEv2, 3f05c46c3c7b87f7_i 44c0a5931247ae7e_r*
      local  'C=US, O=ACME, CN=Alice' @ 192.168.0.1[500]
      remote 'bob@westermo.com' @ 192.168.0.2[500]
      AES_CBC-128/HMAC_SHA2_256_128/PRF_HMAC_SHA2_256/MODP_3072
      established 7905s ago, rekeying in 6115s
      tunnel1: #3, reqid 1, INSTALLED, TUNNEL, ESP:AES_CBC-128/HMAC_SHA2_384_192/MODP_4096
        installed 1406s ago, rekeying in 2002s, expires in 2554s
        in  ce22e6a6,      0 bytes,     0 packets
        out c2e416f5,      0 bytes,     0 packets
        local  10.1.0.0/16
        remote 10.2.0.0/16

### Control commands

`[no] ipsec <restart|monitor>`

  Restart or monitor the IPsec daemon.

  restart
    force a restart of the IPsec daemon, this will restart all tunnels.
  monitor
    debug the IPsec packets passing through the kernel, this will show both ESP and IKE packets.

« Previous Next »