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. Data traffic is 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 establishing the tunnel by contacting the other peer - the responder. In Figure 1 we assume that Alice is the responder and Bob is the initiator. A switch configured as a VPN gateway can act both as a responder (default) and as an initiator.

‑ Local and remote subnet: Each peer defines policies that describe which traffic is allowed to pass through the established tunnel. Each peer defines a local and a 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 is allowed after decryption.

‑ IDs: IKE identities of both peers are used during the authentication round.

‑ Dead Peer Detection (DPD): 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 (>256 bits). Care should be taken to protect the secret from leaking so that nobody can impersonate a gateway.

‑ NAT-Traversal (NAT-T): Network Address Translation (NAT), also called IP masquerading, can interfere with protocols like IPsec, which relies on end-to-end connectivity and unaltered packet headers. NAT-Traversal (NAT-T) is a build-in solution that enables IPsec traffic to pass through NAT devices by encapsulating IPsec packets within UDP packets (a.k.a. ESP-in-UDP). This allows the packets to be routed correctly even when NAT is present, ensuring secure VPN connections can be established across NAT boundaries. NOTE: NAT-T is applied when peers are separated by a NAT gateway. If a single device acts as both the NAT and IPsec gateway at the same time, then IPsec traffic will be exempted from NAT.

IPsec Protocol

IPsec is divided into two phases. You can think of the handshake taking place in phase 1 and secure data transmission happening 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 are by 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. If a classical cipher (like aes128) is selected, then an authentication algorithm and Diffie-Hellman group also need 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.

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.

Start policy

When configuring an IPsec tunnel, the user can select the role of each peer: responder or initiator. Responders act like servers, waiting for incoming connections, while initiators act like clients and start the connection.

To improve connectivity and availability, a trap start policy is configured for both roles. The trap policy triggers tunnel establishment as soon as matching traffic (i.e., traffic destined for the remote subnet) is detected.

In most cases this is not noticeable, since the initiator typically starts the tunnel immediately after a successful configuration. However, if tunnel establishment initially fails (for example due to authentication errors, missing certificates, or the peer not being ready), both peers (responder and initiator) will attempt to establish the tunnel again when traffic is detected – provided that the initial problem has been resolved.

The start policy is not configurable parameter and currently cannot changed in config.

Supported features

• IKEv2: The Internet Key Exchange Version 2 (IKEv2) auxiliary protocol responsible for mutual authentication.

• IKEv1: Version 1 is considered deprecated, as per RFC 9395. However, it is supported for backwards compatibility with WeOS-4 devices. Only Main mode is available.

• PSK (pre-shared keys): Initiator and responder use a shared secret (password) for authentication.

• Certificate-based authentication: X.509 certificates can be used for tunnel authentication. A local certificate (with associated private key) is presented to the peer, and a CA certificate is used to validate the peer’s certificate chain.

• Certificate revocation using CRL: Certificate revocation is checked against CRLs, and the behaviour when CRL information is missing or unavailable is controlled by a configurable revocation policy (see the revocation command below).

• Static IPs: The 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 and WebGUI configuration.

Supported scenarios

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

• Site-2-Site
• Host-2-Host
• IKEv1
• Certificate authentication

Current limitations

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

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] version 1 | 2

Select IKE protocol version.

Note

IKEv1 is considered deprecated according to RFC 9395.

no

Set default IKEv2 version of the protocol.

[no] dpd-action <clear|trap|restart>

Dead Peer Detection (DPD) action to perform for this tunnel when communication is lost. Since trap start policy is set for both roles setting trap here is redundant. 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] dpd-timeout <SEC>

(IKEv1 only) Timeout before declaring the peer dead after no response to DPD probes and retransmissions. This option is ignored for IKEv2 and is only available when the tunnel is configured to use IKEv1.

[no] initiator

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

no

Reset role to responder.

[no] ike cipher <option> auth|prf <option> dh <option>

Phase-1 handshake negotiation. no ike 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

This value selects the default proposals, a set of algorithms which are safe and is usually a good choice for interoperability.

[no] esp cipher <option> [auth <option>] dh <option>

Phase-2 handshake negotiation proposal.

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

This value selects the default proposals, a set of algorithms which are safe and is usually a good choice for interoperability.

[no] method <psk|cert>

Select authentication method for the tunnel.

psk

Use a pre-shared key for authentication (default).

cert

Use X.509 certificate-based authentication.

[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. Secrets starting with the “0s” prefix are considered base64 encoded, whereas “0x” designates a hex-encoded value.

[no] certificate <LABEL>

Label of a local certificate to use when method cert is selected. The certificate must have an associated private key present in the system.

LABEL

Use the specified certificate label.

[no] ca <LABEL>

Label of a CA certificate from the Trusted Local CA Store used to validate the certificate chain coming from the peer. Currently it can be a single certificate, i.e. not a bundle.

LABEL

Use the specified CA certificate label.

[no] revocation <relaxed|strict>

Set the certificate revocation checking policy using CRL for this IPsec tunnel. The CRL revocation checking does not require any additional configuration and relies on CRL Distribution Points defined in the incoming certificate chain. It cannot be disabled and performs according to selected policy during the authentication phase of the tunnel negotiation and at every next re-authentication attempt (see the reauth-time parameter). The timeout is 10s.

relaxed (default)

The tunnel fails authentication only if a certificate is explicitly revoked, i.e. it is known to be bad. If no revocation information is available (for example, CRL cannot be fetched), the certificate is treated as valid.

strict

The tunnel fails authentication if no valid revocation information is available. In other words, if the certificate is not known to be unrevoked (for example, missing or expired CRL), authentication fails.

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

When using certificate authentication, the IKE identity must be contained in the certificate, either as the subject DN or as a subjectAltName. The identity defaults to the certificate’s subject DN if set to Auto.

Note

When using PSK authentication, each tunnel must have a unique (local-id, remote-id) pair; reusing a pair can cause the wrong pre-shared key to be selected.

no

Sets local-id to Auto, which defaults to different values depending on the selected authentication method. When using the pre-shared-key method, the local-address is selected. When using the certificate method, the identity defaults to the certificate’s subject DN if not specified.

Supported ID types:

Type	Description	Example
inet	IPv4 address	192.168.1.10
name	Fully qualified domain name	server.example.com
email	E-mail address	user@example.com
key	Opaque key identifier	my_vpn_key
dn	ASN.1 DER-encoded hex string	0x3049310b…

Note

The dn type expects an ASN.1 DER-encoded Distinguished Name as a hex string (e.g. 0x3049310b...), not a human-readable string like CN=Alice, O=Example. Use a tool such as openssl to obtain the correct encoding from a certificate. To use a human-readable representation of a Distinguished Name, write it directly without a type prefix (e.g. CN=Alice, O=Example) and the type will be autodetected as a Distinguished Name.

autodetect <VALUE> is the default when a value is given without an explicit type keyword. WeOS deduces the type from the string content. show displays the deduced type in parentheses, e.g. autodetect (name) gateway.example.com. Use an explicit type when the value could be ambiguous.

Setting no local-id / no remote-id selects auto, which picks a sensible default: the local address for PSK or the certificate Subject DN for certificate authentication. On the remote side, a responder with auto accepts any peer identity while an initiator defaults to the peer’s IP address.

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

When using certificate-based authentication, the IKE identity must be contained in the peer’s certificate, either as the subject DN or as a subjectAltName. It is possible to use wildcards to match remote identities. Connections with exact matches are preferred.

no

Results in the “Auto” setting, which has different meanings depending on the role. When acting as a responder it means accepting any remote peer; as an initiator it is set to the peer’s IP address.

[no] local-subnet <ADDRESS/LEN | ADDRESS[ NETMASK]>

Subnet to expose to the other side of the 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.

[no] sa-rekey-time <SECONDS[s] | MINUTESm | HOURSh | DAYSd>

Time after which the IPsec CHILD_SA (phase 2) is rekeyed. This controls how often the data-plane keys are refreshed for this tunnel. CHILD_SA rekeying refreshes key material, optionally using a Diffie-Hellman exchange if a group is specified in the proposal. To avoid rekey collisions initiated by both ends simultaneously, a random value is subtracted to form the effective sa-rekey-time lifetime.

[no] reauth-time <SECONDS[s] | MINUTESm | HOURSh | DAYSd>

Time after which IKE re-authentication (phase 1) is performed. Re-authentication revalidates credentials and may cause a short interruption when enabled. It is disabled by default. Use this feature to align revocation checking to the refresh interval of revocation sources (for example, CRL refresh time). This is necessary to limit the possibility of undetected use of revoked certificates for tunnel authentication.

An example alignment is 0.5 x (CRL-refresh-time). You can configure the re-authentication time to align it with CRL refresh time or, alternatively, OCSP response caching time.

Cipher Suites

A cipher suite is a combination of algorithms used in different stages of the secure communication. The cipher is used for encryption, authentication is used to verify message integrity (that it is received unchanged), prf is used to derive subkeys and the 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:

AEAD ciphers

Authenticated Encryption (with Associated Data) algorithms automatically provide authentication while encrypting, so no separate 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.

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:

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:

Firewall consideration

When configuring a firewall, it is important to ensure that rules do not unintentionally block or disrupt IPsec traffic. IPsec relies on specific protocols and ports (such as UDP 500, UDP 4500, and ESP) to establish and maintain secure tunnels. If the firewall is too restrictive, it can prevent tunnel negotiation, key exchange, or data transfer, leading to failed or unstable VPN connections. Therefore, firewall rules should be carefully reviewed and tested to allow necessary IPsec-related traffic while still maintaining overall network security.

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(Unknown): A tunnel is configured but the daemon does not do anything about it. This usually indicates a misconfiguration. During this state the command show ipsec will not provide Security-Association (SA) details.

‑ Down(Connecting): The initiator is trying to establish a new tunnel. Remaining in this state can indicate problems reaching the peer.

‑ Down(IKE Established): The phase 1 handshake was successful but no CHILD_SA was created. When persistent, this might indicate configuration problems, for example when subnets on both sides do not match. Examine syslog to understand the issue.

‑ Up(Installed): Everything works; the tunnel is operational and sending encrypted data.

!!! note
    This is the only "Up" state.

‑ Down(Retransmission): A Dead Peer Detection (DPD) request went unanswered. See the retransmission section for details.

To show details of an ongoing connection and the currently loaded configuration of a specific IPsec tunnel instance:

example:/tunnel/#> show ipsec 1
Current state for tunnel ipsec1 is UP(Installed).

Security-Association(SA) details:
ipsec1: #6, ESTABLISHED, IKEv2, 20759114c78bf131_i* 4fb9e973f3067b48_r
  local  'alice' @ 192.168.0.1[500]
  remote 'bob' @ 192.168.0.2[500]
  AES_CBC-128/HMAC_SHA2_256_128/PRF_HMAC_SHA2_256/ECP_256
  established 5s ago, rekeying in 14304s
  tunnel1: #5, reqid 1, INSTALLED, TUNNEL, ESP:AES_CBC-128/HMAC_SHA2_256_128
    installed 5s ago, rekeying in 3267s, expires in 3955s
    in  c2032981,      0 bytes,     0 packets
    out cc173955,      0 bytes,     0 packets
    local  192.168.0.1/32
    remote 192.168.0.2/32

Loaded configuration for the connection:
ipsec1: IKEv2, no reauthentication, rekeying every 14400s, dpd delay 30s
  local:  192.168.0.1
  remote: 192.168.0.2
  local pre-shared key authentication:
    id: alice
  remote pre-shared key authentication:
    id: bob
  tunnel1: TUNNEL, rekeying every 3600s, dpd action is start
    local:  dynamic
    remote: dynamic

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.