Guide

Native IKEv2 and IPsec

Pre-Alpha. This page describes behavior that may change.

Ze implements native IKEv2 in Go for route-based IPsec VPN tunnels. It does not require strongSwan, libreswan, or another external IKE daemon. The IKE engine, cryptographic primitives, wire codec, and XFRM dataplane integration are all in-tree. The Ze binary negotiates IKE SAs, installs XFRM policies and states, and programs routes through XFRM interfaces from the same YANG config tree as every other subsystem.

Live IPsec demonstration

The recording loads IKE, ESP, peer authentication and selectors, then XFRM routing into one SSH candidate on a running router. A hidden Ze responder protects the other host. Kernel SPIs and increasing packets-in after a protected-host ping distinguish installed forwarding from negotiated state.

The failure changes only ESP to a cipher the responder does not offer. show vpn ipsec peer name responder can still report established IKE with no Child SA. show log recent level warn | match NO_PROPOSAL_CHOSEN | last 1 | yaml shows the latest refusal with notify: NO_PROPOSAL_CHOSEN and peer: responder in the same entry's structured attributes, without unrelated warnings scrolling it out of view. Empty dataplane drift means the expected SA identities are present, not that a tunnel exists or that every forwarding policy is installed. The repair restores the ESP group, clears that peer's SAs and proves protected traffic again.

For Junos operators, the equivalent observations are show security ike security-associations for IKE and show security ipsec security-associations for the installed IPsec SAs and SPIs.

Ze terminal lab

Build and repair a native IPsec tunnel live

Commit IKE, ESP, selectors and XFRM routing over SSH, prove kernel SPIs with protected traffic, diagnose an ESP mismatch, and restore the tunnel.

Reproducible
Ze 26.10.285 minutes 33 secondsLinux namespace labTerminalZe recorder Plain-text transcript
Read the demonstration transcript
Native IKEv2 and Linux IPsec, configured live

Lab: shown Ze 172.30.0.1 initiates to a hidden Ze responder at 172.30.0.2.
Protected hosts 10.78.1.2 and 10.78.2.2 live behind different routers.
The shown daemon starts with no VPN configuration or XFRM interface.

$ ze-demo card topic-ipsec lab
$ ze-demo card topic-ipsec overview

In one SSH candidate, load topics/ipsec/1-ike.conf, 2-esp.conf, 3-peer.conf,
and 4-xfrm.conf with load file absolute merge. Review show | compare and
commit now. The sections define IKE, ESP, authenticated peer and selectors,
and the route through vpn-xfrm (if-id 42).

$ sshpass -e ssh ze-demo
ze# load file absolute merge /src/demos/terminal/topics/ipsec/1-ike.conf
ze# load file absolute merge /src/demos/terminal/topics/ipsec/2-esp.conf
ze# load file absolute merge /src/demos/terminal/topics/ipsec/3-peer.conf
ze# load file absolute merge /src/demos/terminal/topics/ipsec/4-xfrm.conf
ze# show | compare
ze# commit now
ze# exit
ze> exit

$ ze-demo card topic-ipsec proof
$ ze cli -c 'show vpn ipsec status | no-more'
$ ze cli -c 'show vpn ipsec sa | no-more'
$ ze cli -c 'show vpn ipsec dataplane sa | no-more'
$ ze-demo run showcase-lab control vpn ping
$ ze cli -c 'show vpn ipsec sa | no-more'

The kernel SPIs must match the negotiated Child SA. The protected ping
must succeed and the same inbound SA's packets-in must increase.

Failure: load 5-mismatch.conf and commit. It changes only ESP to AES-128;
the far end offers AES-256. IKE can stay established while no Child SA exists.

$ ze-demo card topic-ipsec failure
$ sshpass -e ssh ze-demo
ze# load file absolute merge /src/demos/terminal/topics/ipsec/5-mismatch.conf
ze# show | compare
ze# commit now
ze# exit
ze> exit

$ ze-demo card topic-ipsec diagnosis
$ ze cli -c 'show vpn ipsec peer name responder | no-more'
$ ze cli -c 'show log recent level warn | match NO_PROPOSAL_CHOSEN | last 1 | yaml | no-more'
$ ze cli -c 'show vpn ipsec dataplane sa | yaml | no-more'
$ ze cli -c 'show vpn ipsec dataplane drift | yaml | no-more'

The same log entry carries peer responder and notify NO_PROPOSAL_CHOSEN
under attributes beside the message that IKE remains established. An empty
drift result means the engine and kernel agree, not that a tunnel carries traffic.
Load 2-esp.conf, review and commit, then clear vpn ipsec sa peer responder.
Verify the new kernel SPIs, successful protected ping and increasing packets-in.
The shown Ze process is never restarted.

$ sshpass -e ssh ze-demo
ze# load file absolute merge /src/demos/terminal/topics/ipsec/2-esp.conf
ze# show | compare
ze# commit now
ze# exit
ze> exit
$ ze cli -c 'clear vpn ipsec sa peer responder | no-more'
$ ze-demo run showcase-lab control vpn ping
$ ze cli -c 'show vpn ipsec sa | no-more'
$ ze cli -c 'show vpn ipsec dataplane sa | no-more'
$ ze-demo card topic-ipsec recap

Vendor mapping: Junos show security ike security-associations reads IKE state;
show security ipsec security-associations reads the IPsec SAs and their SPIs.
https://www.juniper.net/documentation/us/en/software/junos/cli-reference/topics/ref/command/show-security-ike-security-associations.html
https://www.juniper.net/documentation/us/en/software/junos/cli-reference/topics/ref/command/show-security-ipsec-security-associations.html
https://www.juniper.net/documentation/us/en/software/junos/cli-reference/topics/ref/statement/security-edit-proposal.html

Architecture

The IPsec stack is split across several packages:

Package Role
internal/component/ike/wire IKEv2 wire format codec for RFC 7296 payloads
internal/component/ike/crypto DH groups, PRFs, integrity, encryption, and key derivation
internal/component/ike/transport UDP transport with NAT-T keepalives and port 4500 encapsulation
internal/core/eap EAP-MSCHAPv2, EAP-TLS and EAP MD5-Challenge authentication
internal/component/ike/engine IKE_SA_INIT, IKE_AUTH, CREATE_CHILD_SA, and INFORMATIONAL state machines for initiator and responder roles, rekeying, and DPD
internal/component/ike/ipsec YANG schema, configuration, and validation
internal/component/ike/dataplane XFRM policy and state programming through netlink
internal/component/pki X.509 certificate and private-key store

Configuration

IPsec is configured under vpn { ipsec { } }. Named ike-group and esp-group blocks hold the IKE and ESP proposals and lifetimes. Each site-to-site peer references a group pair, sets its authentication, and binds to an XFRM interface for route-based forwarding. A peer's and remote-access's ike-group and esp-group are leafrefs: commit, a SIGHUP reload and ze config validate refuse a name no group declares, naming the groups that exist, and the editor completes the names.

pki {
    ca my-ca {
        certificate "-----BEGIN CERTIFICATE-----...";
    }
    certificate my-cert {
        certificate "-----BEGIN CERTIFICATE-----...";
        private {
            key "-----BEGIN PRIVATE KEY-----...";
        }
    }
}

vpn {
    ipsec {
        interface eth0;

        ike-group site-b-ike {
            key-exchange ikev2;
            lifetime     28800;
            proposal 1 {
                encryption aes256gcm;
                hash       sha256;
                dh-group   14;
            }
            dead-peer-detection { interval 30; timeout 120; }
        }

        esp-group site-b-esp {
            lifetime 3600;
            pfs      enable;
            proposal 1 { encryption aes256gcm; }
        }

        site-to-site {
            peer site-b {
                ike-group       site-b-ike;
                esp-group       site-b-esp;
                connection-type initiate;
                local-address   198.51.100.2;
                remote-address  198.51.100.1;
                authentication {
                    mode           x509;
                    certificate    my-cert;
                    ca-certificate my-ca;
                }
                vti { bind vti0; }
            }
        }
    }
}

Traffic selectors constrain which protected networks a peer negotiates. Route-based forwarding also needs a route through the bound XFRM interface. The generated configuration reference documents the XFRM interface leaves.

In the live demonstration, the route is 10.78.2.0/24 with next { interface vpn-xfrm {} }. The empty next-hop entry is meaningful: it selects the XFRM interface without a gateway or another leaf. The editor records this as an owned entry, not as a side effect of configuring the nearby interface leaves. It must survive the SSH candidate commit and appear in the kernel routing table. Established IKE, installed SAs and an up XFRM interface do not substitute for that route. If the protected ping receives Destination Net Unreachable from the local router, inspect the committed route and kernel route lookup before changing selectors or proposals.

If the routes exist but a protected-host ping still loses every packet, compare SA counters with the receiving router's /proc/net/xfrm_stat and show vpn ipsec dataplane policy. Decryption alone is not forwarding. On Linux, a tunnel needs a fwd PROTECT policy as well as in and out: the fwd policy uses the inbound protected prefixes, tunnel endpoints, owner and XFRM if-id. Ze installs and removes these together; this is not another configuration knob.

A receiving SA whose packet count increases while XfrmInNoPols increases has decrypted packets rejected by a later policy lookup. In the live demonstration, both routes and both SAs existed, but the receiving router had only in and out policies at if-id 42. The missing fwd policy caused that drop. A wildcard bypass at if-id 0 does not satisfy a lookup at if-id 42. Changing the traffic test to ping the router itself, disabling policy checks, or adding a bypass would not repair protected-host forwarding.

Which edits restart a tunnel

Committing a change to ANY leaf inside a peer block restarts that peer, and so does a change to the ike-group or esp-group that peer names. The tunnel drops, Ze re-negotiates it, and the new configuration is what the new IKE SA and its Child SA carry. There is no list of leaves that count and leaves that do not: the whole peer configuration and both resolved groups are compared, so a leaf that Ze gains in a later release restarts the tunnel from the day it exists.

Rotating a cipher is the case worth naming, because it edits no peer block at all. A peer holds the NAME of its groups and none of the crypto, so ike-group IKE-1 { proposal 1 { encryption ... restarts every peer that names IKE-1 and no other.

One edit does not restart the tunnel. When a peer's IKE SA is up with no Child SA, because the two sides could not agree on ESP when it was established, a commit that changes only that peer's esp-group keeps the IKE SA. Nothing is carrying traffic yet, so nothing runs under the old settings; the new esp-group applies when the Child SA is created on that IKE SA, with no reconnect. Change the ike-group or the peer block in the same commit, or make the edit while a Child SA exists, and the peer restarts as above.

A commit that leaves a peer's block and its two groups unchanged does not touch that peer, whatever else in the configuration moved. Adding a second peer, editing a firewall rule or changing a log level leaves a running tunnel carrying traffic.

Three consequences are worth planning around:

  • A tunnel bounce is how a narrowing takes effect. Narrowing a peer's traffic-selector list to stop carrying a prefix works, and it costs the tunnel a re-negotiation. RFC 7296 Section 2.9.2 leaves no other route: a Child SA cannot be narrowed in place.
  • Batch peer edits into one commit. Three commits touching one peer bounce it three times. One commit carrying all three edits bounces it once.
  • A group is shared, so an edit to it bounces every peer that names it. Give a peer its own group when you want to rotate its crypto without touching the others.

A commit is REFUSED when interface cannot supply an address and some peer has no local-address of its own. The transaction rolls back and every running tunnel keeps carrying traffic, because applying that configuration would restart each of those peers into a state that cannot bind. The error names the interface and how many peers depend on it. Give those peers a local-address, or bring the interface up, then commit again. At DAEMON START the same configuration is applied and the condition is logged instead: there is no running tunnel to protect, and the peers that carry their own local-address still come up.

IKE features

Feature Detail
IKEv2, RFC 7296 Full IKE_SA_INIT, IKE_AUTH, CREATE_CHILD_SA, and INFORMATIONAL exchange support
Role Initiator or responder per peer through connection-type initiate or respond
Proposals AES-CBC and AES-GCM 128/256 for the IKE SA and ESP; AES-CCM 128/256 with an 8, 12 or 16 octet ICV for the IKE SA only (RFC 5282), refused at commit in an esp-group; NULL encryption with an integrity algorithm for ESP only (integrity-only ESP, RFC 4303 Section 1), refused at commit in an ike-group (RFC 7296 Section 5); ESP-only chacha20poly1305 with no hash, and legacy ESP 3des with hash sha1; DH groups 14 (MODP 2048), 19 (ECP 256) and 20 (ECP 384); SHA-256/384/512 PRFs. ChaCha20, 3DES and SHA-1 remain unavailable for the IKE control channel
Authentication Pre-shared key, X.509 certificates, EAP-MSCHAPv2, and EAP-TLS; Ze acts as the EAP authenticator in responder mode
NAT-T, RFC 3948 Automatic NAT detection, UDP encapsulation on port 4500, and keepalives
DPD Dead Peer Detection through INFORMATIONAL exchanges with configurable interval and timeout
Rekeying On-wire CREATE_CHILD_SA rekeying for IKE and Child SAs, make-before-break installation, and collision handling
MOBIKE, RFC 4555 Tunnel-mode endpoint movement as initiator or responder, with authenticated return-routability checks; requires the Linux atomic XFRM state-migration API
Denial-of-service COOKIE challenge before a half-open slot is committed, and the INVALID_KE_PAYLOAD group retry
Dataplane read-back show vpn ipsec dataplane reads the kernel SAD and SPD, and a drift check compares them against the engine
Virtual IP pool A respond peer with virtual-ip-pool is leased a unique inner address from the named remote-access pool in IKE_AUTH (RFC 7296 Section 2.19), and its Child SAs name that address

Prefer AES-GCM or ChaCha20-Poly1305 for new ESP deployments. 3des and sha1 are explicit legacy interoperability choices, not defaults. ChaCha20-Poly1305 uses a 32-byte key plus a four-byte salt and a 16-byte tag. 3DES uses a 24-byte key including DES parity; SHA-1 integrity uses a 20-byte key and a 12-byte ICV. The fixed-size ciphers send no Key Length attribute. Linux XFRM and VPP have explicit algorithm mappings; an unavailable backend algorithm fails installation, never falls back to AES. Interoperability proof for both new combinations is pending the scoped two-role rekey runs.

MOBIKE endpoint movement

IPv4 tunnel peers negotiate MOBIKE automatically when the dataplane can migrate a live ESP state without resetting its sequence number or replay window. The Linux backend requires Linux 7.2's XFRM_MSG_MIGRATE_STATE API and CONFIG_XFRM_MIGRATE. Kernels without that API, other backends and transport-mode peers do not advertise MOBIKE; their existing IKE and IPsec behavior is unchanged.

The initiator keeps the configured responder address. If its local address disappears, it selects the routed source address and sends an authenticated address update. The responder accepts explicit updates from that initiator. Both roles require a matching COOKIE2 return-routability response before moving the Child SA. The IKE and Child SPIs, keys and inner traffic selectors remain the same. An invalid COOKIE2 closes the IKE SA rather than installing an unverified path.

MOBIKE uses UDP 4500 even without a NAT. This alone does not enable outbound ESP-in-UDP; the NAT detection result still controls ESP encapsulation. The per-peer nat-traversal policy defaults to allow, preserving existing NAT tunnels. Set vpn ipsec site-to-site peer <name> nat-traversal to prohibit to reject translated paths. This protects the first IKE_AUTH and every address update with NO_NATS_ALLOWED. A prohibiting peer also refuses an unprotected MOBIKE address update from its correspondent; configure the corresponding prohibition there. NAT detection remains active to detect forbidden translation, and UDP 4500 capability does not override the prohibition.

There is no separate MOBIKE enable leaf. An operator configuration edit, including a NAT-policy change, restarts the peer. Mobility handles a live network address change, not a configuration replacement.

IKEv2 responder role

Ze can act as an IKEv2 responder or initiator. A peer with connection-type respond waits for an unsolicited inbound IKE_SA_INIT from its configured remote-address, answers IKE_AUTH, and installs the first Child SA. connection-type initiate, the default, starts the exchange. The UDP transport always listens, so responder mode does not need a separate listen switch.

As responder, Ze authenticates with a pre-shared key, X.509 certificate, or EAP. For EAP it acts as the EAP-MSCHAPv2 or EAP-TLS server for a road-warrior client. It presents its own certificate or PSK first, runs the EAP method, and derives session keys from the EAP MSK.

A new inbound IKE_SA_INIT can proceed while an older established SA for the same peer is still being maintained. Once the replacement authenticates, its INITIAL_CONTACT notification tells the remote endpoint to discard the stale SA. This lets a responder recover immediately after an operator clear or peer restart instead of waiting for Dead Peer Detection.

The replacement takes over only once its Child SA is installed. If Ze refuses that Child SA (no matching ESP proposal, traffic selectors it cannot accept), the new IKE SA is held beside the old one and the old tunnel keeps carrying traffic; the log names the refusal and its fix. The peer can still create the Child SA on the replacement later, and the tunnel then moves onto it; it can also delete the replacement, which leaves the old tunnel as it was. If the old IKE SA then ends while the replacement still has no Child SA, Ze deletes the replacement and the session reconnects.

A gateway can also reauthenticate a tunnel that Ze started (RFC 7296 Section 2.8.3 lets either end create the new IKE SA). An initiate peer accepts a new IKE_SA_INIT while its IKE SA is established, and only from the address that SA talks to; with no established SA it still refuses every unsolicited initiation. The new IKE SA authenticates with the same peer configuration, and Ze moves the tunnel onto it, new Child SA first, without reconnecting. A peer that authenticates with EAP refuses it, because RFC 7296 says reauthentication then has to come from the side that started the original IKE SA: set reauth_time = 0s on a strongSwan gateway for such a peer. If the gateway's reauthentication crosses Ze's own IKE SA rekey, or Ze's reconnect after it gave the old SA up, Ze keeps the IKE SA the gateway started and deletes its own, in whichever order the two complete, so one tunnel remains.

vpn {
    ipsec {
        interface eth0;
        ike-group IKE-PSK {
            key-exchange ikev2;
            proposal 1 { encryption aes256gcm; hash sha256; dh-group 14; }
        }
        esp-group ESP-PSK {
            pfs enable;
            proposal 1 { encryption aes256gcm; }
        }
        site-to-site {
            peer swan {
                ike-group       IKE-PSK;
                esp-group       ESP-PSK;
                connection-type respond;
                local-address   172.28.0.2;
                remote-address  172.28.0.3;
                authentication {
                    mode              pre-shared-secret;
                    local-id          "172.28.0.2";
                    remote-id         "172.28.0.3";
                    pre-shared-secret "$9$encoded";
                }
            }
        }
    }
}

For a road-warrior EAP server, set authentication { mode eap-mschapv2 }, eap-tls or eap-md5, then reference a device certificate and ca-certificate from the PKI store. Configure the client as a site-to-site peer. Read the EAP MD5-Challenge section below before you select eap-md5.

A remote-access pool serves the site-to-site peers whose virtual-ip-pool leaf names it. Such a peer must use connection-type respond and send a CFG_REQUEST in IKE_AUTH: Ze leases it an inner address no other live peer holds (RFC 3948 Section 5.1), answers with a CFG_REPLY carrying the address and the pool's DNS servers, and narrows every Child SA the peer asks for to the address. A Child SA Ze asks for on that IKE SA, a rekey included, proposes only that address for the peer's side, and an answer naming a wider one is refused. The peer's proposed inner selector must contain that address, as a strongSwan client's 0.0.0.0/0 does: a Child SA proposing only other addresses is refused with TS_UNACCEPTABLE, because the answer may only narrow what the peer proposed. A bound peer that asks for no address is refused its Child SA with FAILED_CP_REQUIRED, and one Ze cannot serve with INTERNAL_ADDRESS_FAILURE; both keep the IKE SA. The address returns to the pool when the IKE SA ends, and the same peer gets it back on reconnect while it is free. show vpn ipsec sa lists it under virtual-ip. Admission of clients from unconfigured sources and the eap-user list are not served yet, so an eap-user authenticates nobody; plan/release/fixes/spec-ipsec-remote-access.md owns that.

A peer bound to no pool keeps the inner source it proposes when its configuration names no remote traffic selector. Ze still never gives two peers tunnels that one packet could be sent into (RFC 3948 Section 5.1). When a peer proposes inner selectors that overlap a live tunnel of another peer, those selectors are left out of the answer, and when nothing is left the peer gets TS_UNACCEPTABLE: its IKE SA stays up with no Child SA, and Ze logs a warning that names both peers, both selector pairs and the fix. The first peer to hold the address keeps it until its tunnel goes away. The fix is to configure disjoint remote prefixes (set vpn ipsec site-to-site peer <name> traffic-selector <n> remote prefix <prefix>), to bind the peer to a pool (set vpn ipsec site-to-site peer <name> virtual-ip-pool <pool>), or, for an overlap you configured on purpose, to give one of the two peers a different priority (set vpn ipsec site-to-site peer <name> policy-priority <n>). A leased address counts like any other, so keep pool ranges disjoint from other peers' remote prefixes.

When Ze is the side that asks for the Child SA and the tunnel the responder answers with overlaps another peer's, Ze refuses the answer itself. It deletes the Child SA pair it just negotiated, keeps the IKE SA with no Child SA, and asks again 30 seconds later, doubling the wait after each refusal up to 300 seconds. The warning it logs names the fix, which is the same as above without the pool, since a pool is the responder's to lease.

The same happens when Ze is the side that started the IKE SA and cannot install or bind the Child SA it negotiated in IKE_AUTH: the kernel refused the install (a transform it lacks, or a container started without /dev/net/tun for a Child SA that must receive both ESP forms), the peer's vti binding names no XFRM interface, or Ze could not build the Child SA at all (its esp-group holds no proposal Ze can use, or its keys could not be derived). Ze deletes the Child SA pair, keeps the IKE SA with no Child SA, and asks again 30 seconds later, doubling the wait after each refusal up to 300 seconds. The warning repeats only at each retry, and it carries the fix the refusal names, such as --device /dev/net/tun for the missing device. The first attempt after the cause is gone installs the Child SA with no restart.

show doctor reports each peer whose Child SA this node refused after the peer accepted it, under doctor-ipsec-child-install-refused (check ipsec-child-install): the peer, when, the cause, the next attempt and the fix. The row clears once a Child SA installs, whichever exchange installs it.

A tunnel keeps its selectors until its kernel policies are gone, not only until the tunnel ends. If Ze cannot remove a policy when a tunnel ends, after a transient netlink error for example, the policy can still send packets into the old tunnel, so its selectors stay reserved and a peer proposing an overlapping tunnel is refused. The warning lists, for each policy left, the command that removes it in the dataplane's own tool: ip xfrm policy delete ... on the Linux kernel, vppctl ipsec policy del ... on VPP. IKE cannot drive the VPP dataplane yet: the VPP backend refuses a policy that names no interface, and IKE names none, so the VPP command and the retry below apply once that support lands (plan/post-release/features/spec-ipsec-vpp-policy-interface.md). Ze tries the removal again each time a peer proposes a tunnel and each time a configuration is committed, and releases the selectors as soon as the policies are gone. Running the listed commands lets the next proposal succeed, and restarting Ze is the last resort. The refusal names no configuration of the peer that held the tunnel, which may no longer exist.

Remote prefixes that you configure on two peers, and that each peer negotiates exactly as written, may overlap only when the two peers have different policy-priority values: you ordered them, and the lower value decides which tunnel a packet takes (RFC 4301 Section 4.4.1). At one value, the default 2000 on both for example, nothing orders them, so the second peer to establish is refused like an unconfigured one. An overlap a peer chose by narrowing inside a configured selector, to a smaller prefix, one protocol or one port, is refused at any priority. Route-based peers on distinct XFRM interfaces never conflict.

The same rule covers a peer in transport mode. Its connection is held from its own address to Ze's, so a tunnel that another peer negotiates around that address, for example an unbound peer proposing 198.18.0.9/32 to 0.0.0.0/0 while a transport-mode peer runs from 198.18.0.9, is refused, and so is a transport-mode connection inside a tunnel another peer already holds, whichever of the two comes first. The warning names both peers, and the fix is on the tunnel peer: remote prefixes that leave out the transport-mode peer's address, or a pool. Where the overlap is on purpose, different policy-priority values order the two, exactly as for two tunnels, when the tunnel is exactly a traffic selector you configured on the tunnel peer, both sides, and the transport-mode connection runs exactly from that peer's remote-address to its local-address, for every protocol and port. A transport-mode peer that narrows its proposal to one protocol or one port, on its own address or on Ze's (198.18.0.9/32 to 192.0.2.1/32 TCP port 80 for example), chose that itself, and is refused at any priority. The refusal names the traffic selector that would order the connection, both prefixes at the connection's own addresses, /32 for IPv4 and /128 for IPv6. A host-to-host transport-mode peer at 198.18.0.9 beside a full-tunnel peer configured with 0.0.0.0/0 on both sides is therefore served at two different priorities, and refused at one. A transport-mode peer whose remote-address or local-address is a DNS hostname is ordered only by a traffic selector you configured on it. Two transport-mode peers that overlap, two clients behind one NAT for example, are refused by the dataplane instead (RFC 3948 Section 5.2).

strongSwan protects the same case differently: its default remote_ts is dynamic, the peer's observed address, so a client behind a NAT that proposes its private address gets no tunnel at all without a pool. Ze serves every client whose inner address is free, and refuses only the one that would share an address with another peer.

Every EAP mode and X.509 needs a ca-certificate. The daemon refuses a remote certificate it cannot chain to that anchor. A certificate with no trust anchor authenticates nobody: any self-signed certificate that carries a valid signature would pass. RFC 7296 Section 2.16 requires EAP to run with a public-key authentication of the responder, and the anchor is what makes that signature attributable.

ca-certificate holds one anchor, not a path. A two-level authority therefore needs the peer to send its intermediate certificates. RFC 7296 Section 3.6 puts the peer certificate first, and Ze reads every later CERT payload as a link toward the anchor. Ze sends its own chain the same way: the certificate entry first, then the intermediate that PKI entry carries. A refusal names the anchor and the number of intermediate certificates the peer supplied.

The signature method follows the peer. Ze announces RFC 7427 signature authentication in every IKE_SA_INIT, and a peer that announces it too gets an RFC 7427 Digital Signature (method 14). A peer that does not, such as strongSwan with charon.signature_authentication = no, gets the method that fits Ze's certificate key: RSA Digital Signature (method 1, SHA-1) for an RSA key, and ECDSA-256, ECDSA-384 or ECDSA-521 (methods 9, 10, 11) for an ECDSA key on P-256, P-384 or P-521. An Ed25519 or Ed448 key signs under RFC 7427 only, as RFC 8420 defines it: Ze announces the Identity hash in every IKE_SA_INIT, and when the peer announces it too (strongSwan does with its openssl plugin, and for Ed25519 with its curve25519 plugin too) Ze signs the AUTH octets whole with pure Ed25519 or pure Ed448. A peer that does not announce Identity, or sends no notify at all, cannot be signed for with an EdDSA key, and the IKE_AUTH fails with a message naming the peer: use an ECDSA or RSA certificate for it. Ze verifies all of these methods from the peer, Ed25519 and Ed448 included. An Ed448 certificate must be issued by an RSA, ECDSA or Ed25519 CA: Ze cannot check a chain whose CA signs with Ed448. A ze started with GODEBUG=fips140=only refuses method 1, because Go refuses SHA-1 signatures in that mode: enable RFC 7427 on the peer instead.

What a peer certificate must allow

Ze refuses a peer certificate issued for another purpose, as RFC 4945 requires. The rules apply to the peer's own certificate, not to its CAs:

Extension in the peer certificate Accepted when
✕ always
extendedKeyUsage it names id-kp-ipsecIKE (1.3.6.1.5.5.7.3.17) or anyExtendedKeyUsage, beside any other purpose
✕ always
keyUsage it sets digitalSignature or nonRepudiation

A certificate whose extendedKeyUsage names only TLS purposes is refused. This includes a Let's Encrypt certificate (serverAuth, and on older ones clientAuth), and strongSwan's recipe for Windows clients, pki --issue --flag serverAuth --flag ikeIntermediate. strongSwan and libreswan accept such a peer, so a tunnel that worked against them can fail against Ze. The refusal names the extension found. To fix it, reissue the peer certificate with no extendedKeyUsage, or add id-kp-ipsecIKE to it. With openssl, put this line in the extension file given to openssl x509 -req -extfile or openssl ca -extfile:

extendedKeyUsage = 1.3.6.1.5.5.7.3.17

Add serverAuth after a comma when the same certificate also serves a Windows client. strongSwan's pki --issue cannot write id-kp-ipsecIKE: the extended key usages its --flag option writes are serverAuth, clientAuth, ikeIntermediate, ocspSigning and msSmartcardLogon only. Issue that certificate with openssl, or with strongSwan and no --flag, which writes no extendedKeyUsage.

Revoking a peer certificate

Ze checks a certificate peer against the revocation lists in the PKI store. To revoke a peer certificate, add the list its CA published to the crl of the pki ca entry that holds that CA:

pki {
    ca corp-root { certificate "<pem>"; crl "<pem>"; }
}

Ze then checks every certificate on the peer's chain, except the trust anchor, against the lists of each pki ca entry whose certificate is on that chain. A peer whose certificate is on a list is refused, and the log names the certificate, its serial number and the CA that revoked it. When the peer's certificate comes from an intermediate CA that the peer sends in its CERT payloads, add that intermediate as a pki ca entry with its own crl. It needs no other reference: Ze finds it on the chain.

Once any ca on the chain holds a list, the check is strict. A certificate whose issuer has no current list is refused, so publish a fresh list before the nextUpdate of the one in the config passes. A list with a critical extension Ze cannot process (a delta CRL, an issuing distribution point) answers nothing and refuses the same way. When no ca on the chain holds a list, the peer authenticates and Ze logs a warning that its revocation status was not checked. Ze fetches no list from a CRL distribution point and asks no OCSP responder for an IKE peer.

An eap-tls peer whose EAP-TLS client sends its certificate without the intermediate that issued it can still authenticate. Store that intermediate as a PKI ca entry and name it in intermediate-certificate, a list. When Ze is the EAP-TLS authenticator, it builds the client's path from the certificates the client sent plus this list, anchored at ca-certificate only: an intermediate completes a path and never ends one. On TLS 1.3 the client certificate's revocation status must be read, so give the intermediate entry its own crl. RFC 5216 Section 5.3 asks the authenticator to obtain the intermediates a path needs. Ze does not fetch them from the Authority Information Access URL, so that SHOULD is not met; this list is the pre-configuration the same section names for a server that cannot retrieve them.

pki {
    ca corp-root { certificate "<pem>"; crl "<pem>"; }
    ca corp-sub  { certificate "<pem>"; crl "<pem>"; }
}
vpn ipsec site-to-site peer branch authentication {
    mode eap-tls
    certificate ze-server
    ca-certificate corp-root
    intermediate-certificate corp-sub
}

Commit and reload refuse a name that is not a PKI ca entry (as does ze config validate, because the leaf-list is a ze:reference "pki-ca"), an entry that holds no CA certificate, and the list on a peer whose mode is not eap-tls, where nothing would read it.

Ze refuses a config that names no ca-certificate at commit and at reload. It does NOT refuse it under ze config validate, which reads the schema and does not run a plugin's config verifier.

Pre-shared secret encoding

pre-shared-secret-encoding reads the secret as ascii, the default, or as hex. RFC 7296 Section 2.15 requires the management interface to accept both. Use hex for a secret that holds non-printable octets.

The encoding is stated and is never guessed from the value. A secret such as abcdef0123456789 is valid ASCII and valid hex. A daemon that read the value to decide would silently reinterpret a deployed secret. A hex value with an odd length or a non-hexadecimal character is refused at commit rather than read as ASCII.

The at-rest $9$ obfuscation is unwrapped first, so a hex secret can also be stored obfuscated.

Remote identity

remote-id is the identity Ze expects the remote endpoint to assert. When it is set, Ze enforces it twice on every authentication.

Check What it compares Refusal
Policy The IDi or IDr payload the peer sent against remote-id Every authentication mode
Certificate The same asserted identity against the remote certificate Certificate modes only

The certificate check is the half that matters when one authority issues to several clients. The chain proves the authority issued the certificate. It does not prove the certificate speaks for this peer, because the peer chooses the identity its signature covers. Without the second check any client of that authority authenticates as any peer.

A subject alternative name binds. The subject common name binds only when the certificate carries no alternative name extension at all. The two fields do not carry the same attestation: X.509 name constraints reach the alternative names and never the subject distinguished name. An authority that permits only dNSName .branch.example.com leaves the common name free, so a common name read after a present alternative name would defeat that constraint.

The value you configure picks the field. An address remote-id binds against the address alternative names alone, never against a domain name that spells the same address. Certificate authorities issue an address alternative name under a tighter policy than a name, and this stops the peer from choosing the weaker field.

Ze compares six identity types: ID_IPV4_ADDR, ID_IPV6_ADDR, ID_FQDN, ID_RFC822_ADDR, ID_KEY_ID, and ID_DER_ASN1_DN. A domain name and a mail address compare with the ASCII letters folded. An address compares as an address, so the encoding does not matter. A distinguished name compares in RFC 4514 string form, and it binds against the certificate subject octet for octet. A peer that asserts ID_DER_ASN1_GN is refused, because Ze compares no general name.

A local-id written as a distinguished name is still refused at commit. Ze derives the type it SENDS from the shape of the value, and that derivation has no ID_DER_ASN1_DN form.

One peer, or a set of peers

A remote-id can name one peer or a group of them. RFC 4301 Section 4.4.3.1 requires both forms of Peer Authorization Database entry. Write a group with the hierarchy separator in front. Such an entry admits the identities BELOW it and never the entry text itself.

You write It admits
vpn.example.com that name alone
.example.com vpn.example.com, gw.branch.example.com
gateway@example.com that address alone
@example.com gateway@example.com
CN=hq,O=Example that distinguished name alone
,ST=MA,C=US every distinguished name whose top RDNs are ST=MA,C=US
10.0.0.1 that address alone
10.0.0.0/24 every address in the block

RFC 4514 renders the most significant RDN last, so a distinguished-name group is written with the top of the tree at the end and a leading comma in front. An address group takes the same CIDR prefix a traffic selector takes. ID_KEY_ID is always compared exactly: an opaque octet string has no hierarchy, so a leading . or @ in one is content.

Substring matching is not offered. .example.com refuses notexample.com, and it refuses the bare example.com too. Write the apex exactly when you mean it.

A group never widens what one certificate proves. The certificate check above still binds the identity the peer ASSERTED, so a peer admitted by .example.com must hold a certificate that carries its own name. A local-id that names a group is refused at commit, because Ze asserts exactly one identity and would send the pattern text verbatim.

RFC 7296 Section 4 requires that you can configure Ze to accept a PKIX peer whose identity is ID_KEY_ID. An opaque key id matches no certificate field, so Ze cannot derive that binding and denies it by default. Set remote-id-type key-id to state that the chain to ca-certificate plus the exact key id IS the binding you intend.

remote-id-type also pins ONE identity type for the peer. Without it a text remote-id accepts ID_FQDN, ID_RFC822_ADDR and ID_KEY_ID alike. All three compare as text. Set remote-id-type rfc822-address when you know the value is a mail address. Ze then refuses a peer that asserts ID_FQDN with the same text.

The leaf governs what Ze ACCEPTS. The type Ze sends still follows local-id.

An unset remote-id runs neither check. Every certificate the configured authority issued then authenticates as this peer. Ze logs a warning that names the peer and the identity it accepted. Set remote-id whenever the authority issues to more than one client.

Certificate chain length

certificate-count bounds the X.509 chain in both directions. It is the most certificates Ze sends for the peer, and the most it accepts from it. RFC 7296 Section 3.6 sets that figure at four, and the default is four, so a peer you never configure gets the conformant behaviour.

A peer that sends more than the bound is REFUSED. Ze does not truncate the chain. A silent trim hides from you that the limit was reached. It also makes the surviving certificates depend on the order the peer chose.

Name the intermediates on the PKI certificate entry, in order from the issuer of your device certificate toward the trust anchor. Ze refuses at commit a peer whose certificate-count is smaller than the chain its PKI entry holds.

Hash and URL certificates

hash-and-url replaces the certificate on the wire with a 20-octet SHA-1 hash and a URL that resolves to it (RFC 7296 Section 3.6). It keeps IKE messages short. Set certificate-url to the http URL where you publish this device's certificate.

The leaf defaults to false, and that default is a security property. Resolving a URL a peer sends makes an outbound request on behalf of a peer that is NOT yet authenticated. Ze must fetch the certificate before it CAN authenticate the peer. With the leaf false Ze advertises nothing, a conforming peer sends no such payload, and Ze drops one from a peer that sends it anyway.

When you enable it, the lookup is bounded:

Control Bound
Scheme http only. Every other scheme is refused before any name resolution
Response size 64 KiB
Total timeout 5 seconds
Redirects None. A redirect is refused
Destination Loopback, private, link-local, multicast and metadata addresses are denied
Hash The SHA-1 is verified BEFORE any parser reads the fetched bytes
Cache Keyed by the hash, never by the URL

Use certificate-url-allow to permit a destination the deny list refuses. Run ze doctor to check a configured certificate-url.

The EAP peer validates the authenticator's certificate chain against that trust anchor. EAP-TLS has no server hostname, so the check validates the chain without DNS-name matching.

A second authentication round (RFC 4739)

A site-to-site peer can authenticate twice in each direction: for example a device certificate first, then a pre-shared key that belongs to a user or to a third party behind the gateway. The first round is the authentication block you already have. second-round adds one more round for each direction:

vpn ipsec site-to-site peer branch-1 authentication {
    mode x509
    local-id ze-device.example.com
    remote-id 192.0.2.1
    certificate ze-device
    ca-certificate site-ca
    second-round {
        local {
            mode pre-shared-secret
            pre-shared-secret <secret>
            id ze-user.example.com
        }
        remote {
            mode pre-shared-secret
            pre-shared-secret <secret>
            id gateway-user.example.com
        }
    }
}

local is the credential Ze proves in its second round, and remote the one it requires from the peer. Either can be left out. Each round runs in its own IKE_AUTH exchange and signs over its own identity, and the tunnel comes up only once every configured round has succeeded. A round is mode pre-shared-secret or mode x509; an x509 round names its own certificate (local) or ca-certificate (remote).

Situation What Ze does
The peer asks for a round that second-round remote does not configure Refuses with AUTHENTICATION_FAILED
second-round remote is set and the peer finishes without that round Refuses with AUTHENTICATION_FAILED, and the log names the leaf
The peer asks for a third round Refuses with AUTHENTICATION_FAILED. Ze runs at most one extra round each way
second-round local is set and the peer does not announce RFC 4739 support Completes with the first round alone, and logs one warning naming the leaf to remove

Commit refuses a second round on a peer whose first round is an EAP method, a round of mode pre-shared-secret with no secret, a local x509 round with no certificate, and a remote x509 round with no ca-certificate. It also refuses a local round with no id. The round asserts an identity of its own, and a peer such as strongSwan picks the round's pre-shared key by that identity, so falling back to the peer name would make it look up the first round's key.

hash-and-url applies to the first round only. A second-round certificate always goes out inline, which every peer accepts.

Ze announces MULTIPLE_AUTH_SUPPORTED only to a peer that configures a second round, so every other peer sees exactly what it saw before. When Ze verifies a peer's second round it logs ike: second authentication round verified with the peer and the identity that round proved.

One property comes with the RFC, and Ze does not change it: when the initiator authenticates more than once, the responder reveals its identity before all of the initiator's rounds have completed (RFC 4739 Section 5).

EAP method negotiation

The far end chooses the EAP method, and authentication { mode ... } sets the one Ze runs. When the far end asks for a different authentication method, Ze answers with an EAP Nak that names the configured method (RFC 3748 Section 5.3.1) rather than ending the exchange. A concentrator that also runs that method then offers it, and the tunnel establishes with no configuration change. A concentrator that runs no other method ends the exchange, and Ze logs ike: EAP failed. Change mode to a method both ends run.

The far end can also send an EAP Notification, which is how a concentrator reports something such as an expiring password. Ze logs it as ike: EAP notification from the authenticator with the message, and the authentication continues. The message is unauthenticated: it is chosen by whoever sent the packet, so read it as a claim.

When Ze is the EAP server and the client refuses the offered method, the ike: EAP authentication failed line names the types the client asked for and the type Ze offered.

When Ze is the EAP-TLS client on TLS 1.3, it requires the RFC 9190 Section 2.5 protected success result indication before it accepts the EAP-Success. An authenticator that does not send it fails the peering, and the message names the authenticator, the negotiated version and two remedies: an authenticator that follows Section 2.5, or a peering on TLS 1.2, which RFC 5216 governs and where no indication exists. TLS 1.2 peerings are unaffected.

EAP MD5-Challenge

authentication { mode eap-md5 } runs EAP Type 4, the CHAP exchange of RFC 1994 carried inside EAP (RFC 3748 Section 5.4). Both ends read the pre-shared-secret leaf as the CHAP secret. Ze runs it as the authenticator and as the peer.

It is discouraged, and the daemon says so. RFC 7296 Section 2.16: "EAP methods that do not establish a shared key SHOULD NOT be used, as they are subject to a number of man-in-the-middle attacks". The daemon writes one warning for each peer that carries the mode. It writes it when the configuration is applied, and not for each handshake.

What it costs you, against the two other EAP modes:

Property eap-md5 eap-mschapv2 and eap-tls
Key derivation None. RFC 3748 Section 5.4 records "Key derivation: No" An MSK of 64 octets
IKEv2 AUTH payloads Keyed by SK_pi and SK_pr, which every party completing IKE_SA_INIT holds Keyed by the EAP MSK
Who is authenticated by EAP The client only Both ends, for eap-tls
Secret at rest The CHAP secret, needed in the clear on both ends The same for eap-mschapv2; a private key for eap-tls

The responder still authenticates itself with a public-key signature, because RFC 7296 Section 2.16 requires one whichever EAP method runs. So eap-md5 needs the same certificate and ca-certificate every other EAP mode needs. Select it when the client runs no other method, and prefer eap-tls or eap-mschapv2 everywhere else.

EAP-TLS with TLS 1.3

RFC 9190 Section 2.5 requires an encrypted TLS record that carries application data 0x00. The EAP-TLS 1.3 server sends it once it has processed the client Finished and sent its last handshake message. That record is the protected success result indication. Ze sends it in the flight that round already carries, so the exchange keeps its round count.

The record is what makes a TLS 1.3 EAP-TLS client work. strongSwan derives no MSK without it, so the AUTH payload of RFC 7296 Section 2.16 cannot be computed and the SA never establishes. A TLS 1.2 exchange concludes with the bare EAP-Success it concluded with before, because the version test reads the negotiated version.

Ze issues a TLS session ticket on every EAP-TLS 1.3 authentication, because RFC 9190 Section 2.1.2 makes that a MUST with no condition on it. The ticket key belongs to the peering rather than to the session, so a later authentication with the same peer can redeem it. Whether Ze USES a ticket is the session-resumption leaf, which defaults to true and covers both roles; with it false every authentication runs a full handshake and the ticket still goes out. As the authenticator, Ze resumes TLS 1.3 sessions only: a peer that offers a TLS 1.2 ticket gets a full handshake, because RFC 5216 Section 2.1.2 allows nothing but change_cipher_spec and finished after a resuming TLS 1.2 server_hello, and the TLS library adds a new ticket there. So a TLS 1.2 handshake runs with session tickets off: Ze issues no TLS 1.2 ticket and redeems none, and its full-handshake server_hello carries a session_id Ze chose rather than an empty one. A resumed authentication re-checks the cached chain against the current ca-certificate and crl, so a certificate that was revoked or expired since the first handshake is refused.

Ze caps the TLS version at 1.3 on both EAP-TLS roles. RFC 9190 Section 1 requires that cap, because EAP-TLS couples the TLS state machine to the EAP one and a version nobody integrated into the EAP half breaks the pair. Ze offers no setting that raises the cap. TLS 1.2 stays reachable under it, and an EAP-TLS peer that speaks only TLS 1.2 still authenticates with the RFC 5216 key derivation.

Ze puts the four-octet TLS Message Length only on the first fragment of a message it had to fragment. RFC 9190 Section 2.1.9 forbids the L bit on a message that fits in one EAP-TLS packet, so in a packet capture the TLS data of such a message starts one octet after the EAP Type, not five. Ze accepts an unfragmented message from the far end with the L bit or without it, which the same sentence requires.

Ze does not send local-id as the EAP-TLS identity

RFC 9190 Section 2.1.8 says that "a client supporting TLS 1.3 MUST NOT send its username (or any other permanent identifiers) in cleartext in the Identity Response". So for mode eap-tls Ze does not put local-id in the EAP-Response/Identity. It sends an anonymous Network Access Identifier derived from it:

local-id EAP identity Ze sends Why
alice@example.com @example.com the username is omitted and the realm is kept, which is the form Section 2.1.8 recommends
@example.com @example.com already anonymous
ze-test-client anonymous ✕
alice@localhost anonymous localhost is not a realm the RFC 7542 Section 2.2 grammar accepts

The realm survives because it is what routes an EAP exchange to a home domain, and because RFC 9190 Section 2.1.3 asks for the same realm again when a session resumes. Give local-id a realm when the exchange has to route: an identity with none tells the far end nothing.

local-id is unchanged everywhere else. It is still IDi in IKE_AUTH, and the EAP-MSCHAPv2 and EAP MD5-Challenge methods still send it as their identity, because RFC 9190 governs EAP-TLS alone and those methods carry their username inside the method exchange.

EAP-TLS 1.3 needs a certificate revocation list

RFC 9190 Section 5.4 says that "when EAP-TLS is used with TLS 1.3, the revocation status of all the certificates in the certificate chains MUST be checked (except the trust anchor)". Ze checks it on both roles: the authenticator over the client's chain, and the peer over the authenticator's chain.

The revocation lists come from the pki ca the peer validates against, in a crl leaf-list. Each value is an X509 CRL PEM document or base64-encoded DER, and one CA can hold several, which is what a segmented CRL or a rollover needs. A list this CA did not sign is refused at commit, because it cannot answer for the certificates this CA issued.

pki {
    ca my-ca {
        certificate "-----BEGIN CERTIFICATE-----...";
        crl "-----BEGIN X509 CRL-----...";
    }
}

A CA with NO list and a list that revokes NOTHING are different answers, and the difference decides whether a session establishes:

What the CA holds TLS 1.3 TLS 1.2
A current list, and the chain is not on it The session establishes The session establishes
A current list naming a certificate on the chain Ze refuses, naming the certificate, its serial number and the CA that withdrew it The same
✕ Ze refuses: nothing can answer the question Section 5.4 makes mandatory The session establishes
A list whose nextUpdate has passed Ze refuses: an expired list says nothing about the present The same

The "no list at all" row is the only one where the two versions differ. TLS 1.2 is governed by RFC 5216 Section 5.4 instead, which asks only that an implementation "MUST support the use of Certificate Revocation Lists (CRLs)". Nothing there obliges a session the operator configured no list for, so a TLS 1.2 peer with no list still authenticates while the same peer on TLS 1.3 does not.

Every other row holds on both versions, because a list that IS configured is checked whatever was negotiated. An expired list is not a usable one, so it refuses on TLS 1.2 too: the operator asked for the check, and the source can no longer perform it.

Publish a fresh list before the nextUpdate of the one in the config passes. An expired list refuses the same peers a missing one does.

EAP-TLS 1.3 staples the OCSP response you give it

RFC 9190 Section 5.4 says that "EAP-TLS servers supporting TLS 1.3 MUST implement Certificate Status Requests (OCSP stapling)". Ze answers one with the response configured on the certificate it presents, in an ocsp-response leaf beside that certificate:

pki {
    certificate vpn-server {
        certificate "-----BEGIN CERTIFICATE-----...";
        ocsp-response "MIIBxAoBAKCB...";
        private { key "..."; }
    }
}

Fetch the value from the responder your CA publishes, with openssl ocsp -respout. Give it as base64-encoded DER or as an OCSP RESPONSE PEM document. A response about another certificate is refused at commit. A certificate with no response answers a Certificate Status Request with no status, which RFC 6066 Section 8 permits, and the peer then falls back to the crl of the CA that issued it.

An OCSP response carries a nextUpdate, and a peer that checks the status refuses the certificate once that time passes. Replace the value before it does, the same discipline a crl needs.

An EAP-TLS peer can require the stapled status

RFC 9190 Section 5.4 puts a MUST on a peer that uses Certificate Status Requests to check a chain: "it MUST treat a CertificateEntry (but not the trust anchor) without a valid CertificateStatus extension as invalid and abort the handshake with an appropriate alert". The certificate-status-request leaf makes Ze such a peer, and it is false by default:

ipsec {
    peer headquarters {
        authentication {
            mode eap-tls;
            certificate-status-request true;
        }
    }
}
What the authenticator staples certificate-status-request true certificate-status-request false
A current response saying the certificate is good The session establishes The session establishes
Nothing Ze refuses, naming the missing CertificateStatus The session establishes
A response reporting the certificate revoked or unknown Ze refuses, naming what the responder said The session establishes
A response whose nextUpdate has passed, or one about another certificate Ze refuses, naming which The session establishes

With the leaf false the chain is still checked against the crl of its CA, which Section 5.4 requires on TLS 1.3 either way.

One deployment limit comes with the leaf. Ze reads the stapled status of the LEAF certificate and of no other, because Go's TLS stack parses the status extension of the first CertificateEntry alone. Section 5.4 makes an entry whose status is not valid invalid, and an entry Ze cannot read the status of is one it cannot call valid, so a chain carrying an intermediate CA below the trust anchor is refused while the leaf is on. Give the authenticator a certificate its trust anchor signed directly, or leave the leaf off and check by crl.

An EAP-TLS peer re-checks the server certificate once the tunnel is up

RFC 9190 Section 5.4 asks an EAP-TLS peer to "support checking for certificate revocation after authentication completes and network connectivity is available", and to "use a secure transport" for it. RFC 5216 Section 5.4 asks for the same with no TLS version attached.

Ze runs that check as soon as the Child SA is installed, which is the moment the tunnel it just authenticated gives it a network. It asks the OCSP responder named by the authenticator's own certificate, over https, and it needs no configuration: the responder URL comes from the certificate's authority information access extension.

What the responder says What Ze does
The certificate is revoked Closes the SA and logs the revocation. The reconnect that follows runs a fresh authentication, which the same certificate fails inside the handshake
The certificate is good Logs it and leaves the SA up
Nothing, because it cannot be reached Logs a warning and leaves the SA up. A responder outage is not evidence of a revocation
Nothing, because the certificate names an http responder or none at all The same warning. Section 5.4 requires a secure transport, so an http responder is refused before any connection opens

The check runs once per authentication rather than on a timer, and it never delays the tunnel: the Child SA is up before it starts.

EAP-TLS with TLS 1.2 needs RFC 7627

RFC 5216 Section 2.3 derives the EAP-TLS MSK from a TLS key material export, and Go refuses that export on a TLS 1.2 session that did not negotiate the RFC 7627 extended master secret. Ze cannot authenticate such a peer. It says so rather than failing silently: the log line names the peer, the negotiated version, RFC 7627 and the answers below.

strongSwan 6.1.0, the lab's peer, is such a peer, by default rather than by limitation. src/libtls/tls.c sets the maximum to TLS 1.2 when charon.tls.version_max is unset, with the comment "default to TLS 1.2 until 1.3 is stable for use in EAP", and the generated strongswan.d/charon.conf documents it as # version_max = 1.2. Its libtls implements no extended master secret: the extension appears only as a name in its extension table. Set charon.tls.version_max = 1.3 and the same build reaches an established SA, which is what test/interop-ipsec/scenarios/eap-tls13 runs.

Answer What to change
Move the peer to TLS 1.3 RFC 9190 covers EAP-TLS over TLS 1.3, and the export is unconditional there. This is the preferred answer, and on strongSwan it is one line: charon.tls.version_max = 1.3
Add RFC 7627 to the peer's TLS 1.2 stack The export then works, and ze needs no change
Configure another EAP method EAP-MSCHAPv2 derives its key without a TLS export

Ze offers no setting that lifts the refusal, and there is nothing to add to the environment. Go 1.27 removed the tlsunsafeekm GODEBUG setting that once lifted it. A removed setting carrying its old value is a fatal error that the Go runtime raises before the daemon starts, so setting it stops ze rather than reaching the peer.

Denial-of-service protection

RFC 7296 Section 2.6 names two attacks on an IKE responder: state and CPU exhaustion from initiation requests with forged source addresses. The answer is a COOKIE. Ze answers an inbound IKE_SA_INIT with a COOKIE notification and commits no state, and the initiator must repeat its request with that cookie as the first payload before Ze creates an SA or takes the peer's half-open handshake slot.

cookie-threshold sets how many half-open IKE SAs Ze tolerates before it challenges. It defaults to 0, which challenges every inbound initiation. That default costs a genuine peer one extra round trip and closes a real availability hole: a responder peer has one half-open slot, held for 30 seconds, so a single spoofed datagram bearing that peer's source address would otherwise deny it service, and one datagram every 30 seconds would deny it indefinitely. Raise the value to tolerate that many half-open handshakes before challenging.

vpn {
    ipsec {
        cookie-threshold 0;
    }
}

The cookie is an HMAC-SHA256 over the initiator's nonce, its source address and its SPI, under a secret Ze generates and rotates every 60 seconds. A cookie minted under the previous secret stays valid for one further interval, so a rotation never breaks an in-flight handshake. A cookie that does not match is ignored rather than rejected, as the RFC requires: the message is processed as though it carried no cookie, which for a pressured responder means issuing a fresh challenge.

Diffie-Hellman group correction

An initiator has to guess which Diffie-Hellman group the responder will pick. When the guess is wrong the responder answers INVALID_KE_PAYLOAD naming the group it accepts, and Ze retries the IKE_SA_INIT under that group. Without this, Ze could never establish with a peer that prefers a different group.

The retry re-offers the whole configured proposal set rather than narrowing it to the suite carrying the responder's group. RFC 7296 Section 1.2 requires that, because the rejection is unauthenticated and a narrowed re-offer would let an attacker who forges one notify choose the cipher. Ze also refuses a group it never proposed, which stops the same attacker choosing the group. Both COOKIE and INVALID_KE_PAYLOAD retries share one budget of three per connection attempt, so two peers can never oscillate between them.

Rekeying

Both Child SAs and IKE SAs are rekeyed with an on-wire CREATE_CHILD_SA exchange. This replaced an earlier local-only key roll that could silently desynchronise a live tunnel. A Child SA rekey carries N(REKEY_SA) with fresh nonces and traffic selectors. An IKE SA rekey performs a fresh Diffie-Hellman exchange and resets the message-ID counters.

Rekeying is make-before-break: the replacement SA is installed before the old one is deleted, so forwarding does not pause. Simultaneous rekeys are resolved by the RFC 7296 nonce rule. Section 2.8.1 states it as a recommendation: if redundant SAs are created, the endpoint that created the SA with the lowest of the four nonces SHOULD close that SA. Ze resolves the collision one step earlier and abandons its own pending exchange when its nonce is the lower one, so the redundant SA is never created and both ends converge on one SA. Ze rekeys at the ESP or IKE soft lifetime and retransmits a lost CREATE_CHILD_SA before tearing the tunnel down. Rekeys are counted by ze_ipsec_rekey_total{peer} and streamed as child-rekey events by monitor vpn ipsec.

Child SA and dataplane

Child SAs define traffic selectors and the ESP proposal. Ze programs XFRM policies and states through netlink. Route-based IPsec uses XFRM interfaces.

Feature Detail
ESP proposals AES-GCM-16 128/256 and AES-CBC with HMAC-SHA-256/384/512
Traffic selectors IPv4 and IPv6 CIDR prefixes, an optional IP protocol, and an optional single port. See Traffic selectors and narrowing below
Encapsulation Tunnel mode by default; mode transport negotiates transport mode per RFC 7296 Section 1.3.1
Connection connection-type initiate starts the exchange; connection-type respond waits for the peer
Replay protection Anti-replay window, default 64, the size RFC 4303 Section 3.4.3 says SHOULD be the default
Lifetime Time-based rekeying, from the ESP group's lifetime in seconds. Ze carries no byte lifetime, so RFC 4301 Section 4.4.2.1's simultaneous use of both is not met
Policy order policy-priority ranks this peer's SPD entries, lower first. See SPD ordering below
DF bit df-bit copy (default), clear or set: what the tunnel header carries in its DF bit. See DF bit of the tunnel header below
Tunnel DSCP dscp-map copy (default) or a value 0 to 63 for every tunnel header. See DSCP of the tunnel header below
ICMP errors icmp-error-check true (default) or false: whether an ICMP error a Child SA carries has its payload checked. enable and disable are accepted too, and ze config fmt and show print the value that way. See ICMP error messages below

SPD ordering

RFC 4301 Section 4.4.1 makes the Security Policy Database an ordered database, because entries with range selectors overlap: "Thus, a user or administrator MUST be able to order the entries to express a desired access control policy."

policy-priority under a peer is that order. A LOWER value is searched FIRST, in Ze and in the Linux kernel. Two peers configured with overlapping remote prefixes describe the same traffic, so give the one that must win the lower value. Two tunnels that overlap at one value are not ordered at all, so Ze refuses the second peer's Child SA rather than let arrival order pick the tunnel (RFC 3948 Section 5.1, see the inner-address paragraphs above).

The default is 2000, which every peer took before the leaf existed. The range starts at 101 because 100 holds the IKE control-plane bypass. A peer entry at or above that rank matches the IKE datagrams first, which hands the exchange that builds and rekeys the SA to the SA itself, and the tunnel could then never renegotiate. Ze refuses such a value at commit.

ICMP error messages

An ICMP error reports a packet, and its own headers name the router that sent it, not the flow the packet belonged to. RFC 4301 Section 6.2 therefore asks for two things. An error that arrives on a Child SA with headers its selectors do not cover is checked against the header it carries: "the receiver must extract the header of the triggering packet from the ICMP payload, and reverse fields as described above to determine if the packet is consistent with the selectors for the SA via which the ICMP error message was received." And an outbound error that no SA and no SPD entry would carry goes to "the SA that would carry the return traffic associated with the packet that triggered the ICMP error message."

By default Ze does both:

  • an ICMP error addressed to Ze that arrives on a Child SA is delivered only when its embedded header, with source and destination addresses and ports reversed, falls inside the selectors of the SA it arrived on. Otherwise it is dropped.
  • an ICMP error Ze generates about a packet of a tunnelled flow is sent through the Child SA that carries the return traffic of that packet.

To turn both off for a peer:

set vpn ipsec site-to-site peer branch icmp-error-check false

An ICMP error is then carried only where a traffic selector or a vpn ipsec policy entry covers its own headers, and every other one is dropped unread. RFC 4301 Section 6.2 allows this as the way to carry ICMP errors without inspecting their payload, by configuring an entry that explicitly carries them.

A forwarded ICMP error, one Ze routes between two other hosts, is a different case on Linux. One that arrives on a Child SA with headers the selectors do not cover is dropped whatever the leaf says, because the kernel reads its payload only when no forward policy matches it, and Ze's catch-all always does. One leaving towards a Child SA is mapped to the return SA under unmatched bypass, and dropped under unmatched discard, where the catch-all blocks it before the mapping runs. LL-XFRM-ICMP-TRANSIT in Linux limitations has the kernel functions.

Linux also maps an error that a bypass entry would carry in clear. Section 6.2 maps an outbound error to the return SA only "if no SPD entry would allow carriage of this outbound ICMP error message", but the kernel cannot tell a bypass entry from no entry: whenever the lookup on the error's own headers finds no Child SA, it sends the error through the SA that carries the return traffic. So with a vpn ipsec policy bypass entry that covers ICMP errors towards hosts behind a peer, or with unmatched bypass, an error about a tunnelled packet would go into the tunnel rather than out in clear.

Commit refuses that pair rather than installing an entry the kernel does not honour. A peer whose icmp-error-check is true is refused beside unmatched bypass, and beside a bypass entry that is out or both, has protocol 0 or the ICMP protocol of its family, has icmp-type any or an ICMP error type (IPv4 3, 4, 5, 11 and 12; IPv6 1, 2, 3 and 4, the types Linux 7.3 sends through its return-SA lookup, listed with their kernel callers in icmp_overlap.go), and has a remote prefix that overlaps the peer's remote traffic selectors. A peer with no traffic selector accepts any selector, so every such entry overlaps it. The refusal is conservative about the entry's local prefix and its order, and looks at neither. The kernel picks the address an error leaves from, so no commit can know it. An entry ranked below the peer's own policy is overridden for every error whose address falls outside the peer's local selectors. A protocol 0 entry ranked above it may not be overridden for every error, but it is overridden for some, so it is refused too.

A route-based peer (vti bind) is exempt. Its Child SA policies carry the xfrm interface's if_id, and the kernel's return-SA lookup only looks at policies whose if_id is 0 (xfrm_lookup in net/xfrm/xfrm_policy.c), so it never maps an error into that peer's tunnel. ICMP that arrives on the interface is checked against that if_id too (xfrmi_decode_session), where no vpn ipsec policy entry applies.

The refusal names the peer and the entry, and one of these fixes it:

set vpn ipsec site-to-site peer branch icmp-error-check false
set vpn ipsec unmatched discard

For an entry, the refusal prints the exact command: set vpn ipsec policy <name> remote prefix <prefix> with a prefix that does not overlap the peer's remote selectors, which it lists (not offered when a remote selector covers a whole family, as a peer with no selector does), then set vpn ipsec policy <name> icmp-type <type> with a type that is not an error, such as 8, for a protocol 1 or 58 entry, or set vpn ipsec policy <name> protocol <protocol> for a protocol 0 entry.

ze config validate refuses the same configuration, because the check is part of the IPsec plugin's offline verifier. A configuration the daemon starts with is not verified, so the same conflict is logged at start at Error level and reported by ze doctor under config-plugin-verify.

The VPP dataplane performs neither check. VPP is reached only through the test override ze.test.ike.dataplane, and there commit refuses a peer whose icmp-error-check is true (the default, which keeps the RFC 4301 Section 6.2 processing on Linux), naming icmp-error-check false as the fix.

DF bit of the tunnel header

RFC 4301 Section 8.1 makes the DF treatment of each tunnel-mode SA configurable: "set, clear, copy from inner header". df-bit under a peer is that setting, for the IPv4 tunnel header the peer's outbound Child SAs build.

vpn {
    ipsec {
        site-to-site {
            peer branch {
                remote-address 198.51.100.1;
                df-bit clear;
            }
        }
    }
}
Value Tunnel header DF bit Linux VPP
copy (default) the inner IPv4 header's DF bit ✓ ✓
clear always clear, so a router on the path may fragment the tunnel packet ✓ ✓
set always set refused at commit refused at commit

clear is for a path that drops large tunnel packets and never returns Fragmentation Needed: the routers fragment instead, and the far end reassembles. Commit refuses clear or set on a mode transport peer, which builds no tunnel header, and on a peer whose local-address or remote-address is IPv6, whose header has no DF bit. set is refused on every dataplane today: the Linux kernel copies or clears the bit and has no flag that sets it, and VPP's ESP path ignores its set flag. Changing df-bit restarts the peer.

DSCP of the tunnel header

RFC 4301 Section 5.1.2.1 copies the inner DSCP into the tunnel header, and says that when the packet "will immediately enter a domain for which the DSCP value in the outer header is not appropriate, that value MUST be mapped to an appropriate value for the domain". dscp-map under a peer is that mapping: copy (the default), or one value 0 to 63 written into every tunnel header.

Value Linux VPP
copy ✓ ✓
0 ✓ ✓
1 to 63 refused at commit: the kernel can only copy or write 0 ✓

Commit refuses a value on a mode transport peer. Changing dscp-map restarts the peer.

Path MTU of a tunnel

On Linux the path MTU of a tunnel-mode SA is the path MTU of its outer route. When a router on the way between the tunnel endpoints sends back an ICMP Fragmentation Needed or Packet Too Big about an ESP packet, the kernel finds the SA from the SPI in the quoted packet, lowers the outer route's PMTU, and takes the ESP header, IV, ICV, padding and outer IP header off it to give the inner MTU (RFC 4301 Section 8.2.1). A packet larger than that inner MTU is then handled as Section 8.2.1 says:

Packet What happens
IPv4 with DF set dropped, and the sender gets an ICMP Fragmentation Needed carrying the inner MTU
IPv4 with DF clear encrypted, then the ESP packet is fragmented and forwarded; no ICMP
IPv6 dropped, and the sender gets a Packet Too Big carrying the inner MTU

With the default df-bit copy the tunnel header carries the inner packet's DF bit, so the routers return Fragmentation Needed and the PMTU is learned. With df-bit clear an IPv4 tunnel header always carries DF clear, so the routers fragment the tunnel packets, return nothing, and no PMTU is learned from them. The SA's PMTU is then the MTU of the outer route: the first-hop link's, or a PMTU other traffic to the same tunnel endpoint learned, which ages as below. The table above still holds against that MTU, and a tunnel packet larger than a link further on is fragmented by that router and reassembled by the far end. The kernel also clears the DF bit of every IPv4 outbound SA when net.ipv4.ip_no_pmtu_disc is set, whatever df-bit says, and show vpn ipsec dataplane sa then reads df-bit clear. ze doctor reports it as doctor-ipsec-no-pmtu-disc, naming each IPv4 df-bit copy peer it affects and the fix, set sysctl setting net.ipv4.ip_no_pmtu_disc value 0.

A learned PMTU expires: after the aging period the SA's PMTU returns to the MTU of the first-hop link, and the next large packet finds the path MTU again (RFC 4301 Section 8.2.2, the RFC 1191 Section 6.3 reset). The period is the kernel's route PMTU expiry, 600 seconds by default, one value per address family of the tunnel endpoints, set like any other kernel tunable:

sysctl {
    setting net.ipv4.route.mtu_expires {
        value 300;
    }
    setting net.ipv6.route.mtu_expires {
        value 300;
    }
}

Commit refuses a period below 1 second or above 2147483. The period applies to every PMTU the box learns, not only IPsec ones, and a PMTU already learned keeps the period it was learned with.

The VPP dataplane learns no PMTU: VPP takes no action on an ICMP Fragmentation Needed or Packet Too Big about an ESP packet, and its only path MTU is a value configured per destination (ip path-mtu), which never ages. Over VPP the SA's PMTU is the MTU of the outgoing interface.

Security Policy Database entries

RFC 4301 Section 4.4.1 gives the Security Policy Database three dispositions: "PROTECT, BYPASS, or DISCARD". A site-to-site peer produces the PROTECT entries, because a protect entry names an ESP transform and a peer to negotiate keys with. The other two name neither, so no negotiation can produce them and they are written directly:

set vpn ipsec policy drop-guest action discard
set vpn ipsec policy drop-guest local prefix 10.0.0.0/24
set vpn ipsec policy drop-guest remote prefix 192.168.99.0/24
set vpn ipsec policy drop-guest order 800

Section 7.4 makes the discard disposition an obligation: "All implementations MUST support DISCARDing of fragments using the normal SPD packet classification mechanisms." The list above is the management interface Section 4.4.1 requires for it.

Leaf Values Default Meaning
action bypass, discard none, required What the entry does with matching traffic
order 101 to 2147483647 1000 Rank, lowest searched first
direction out, in, both both Which half of the database the entry joins
protocol 0 to 255 0 (any) Next-layer protocol selector
local prefix CIDR none, required Ze's own side of the boundary
local port 1 to 65535, or any any Local port selector
remote prefix CIDR none, required The far side of the boundary
remote port 1 to 65535, or any any Remote port selector
icmp-type 0 to 255, or any any ICMP message type, under protocol 1 or 58
icmp-code 0 to 255, start-end, or any any ICMP code or inclusive code range, under one icmp-type

both installs a mirrored pair, one entry in each direction: the outbound entry keeps local and remote as written, and the inbound entry swaps them, because the local side of a flow is the destination of an inbound packet.

The default order of 1000 sits between the IKE control-plane bypass at 100 and a peer's default rank of 2000, so an entry written with no order outranks the tunnels and carves its hole out of them. Raise it above 2000 to let a tunnel win instead. An order at or below 100 is refused at commit, for the reason policy-priority states above.

These rules are refused at commit rather than approximated at install time, because a widened selector fails in both directions: a widened bypass passes protected traffic in the clear, and a widened discard black-holes traffic the operator meant to carry.

  • Both prefixes are required, and they must share an address family. One kernel policy selector carries one family.
  • A port other than any needs protocol to name a transport that has ports: 6 (TCP), 17 (UDP) or 132 (SCTP).
  • A port range is not accepted. An entry installs one selector, and the kernel selector carries a port and a mask, which expresses a block aligned on a power of two but not an arbitrary range; Ze does not split one entry into several.
  • action has no default. A bypass written where a discard was meant passes exactly the traffic the entry exists to stop.
  • icmp-type and icmp-code need protocol 1 (ICMP) or 58 (ICMPv6), and icmp-code needs an icmp-type. RFC 4301 Section 4.4.1.1 allows "a single type and a range of codes, a single type and ANY code, and ANY type and ANY code", and nothing else.
  • An out or both entry with icmp-type 0 and an icmp-code that includes 0 (any, 0, or a range starting at 0) is refused. Linux reads no ICMP type or code from an IP fragment, so the kernel classifies every fragment as type 0 code 0, and it classifies forwarded traffic before reassembling it. The outbound half of such an entry would also pass in the clear, or drop, every forwarded ICMP fragment between its prefixes, whatever message it belongs to: the hazard RFC 4301 Section 7.4 names for a bypass. Write it with direction in, because traffic for Ze itself is reassembled before it is classified, or with an icmp-code range that starts at 1.

ICMP type and code selectors

The kernel reads an ICMP message's type into the selector's source port and its code into the destination port, and matches each under a mask. Ze installs a type as one exact match, and a code range as the fewest mask-aligned blocks that cover exactly that range, one kernel policy per block, added and removed together. RFC 4301 Section 4.4.1.1 requires the test (T-start*256) + C-start <= (t*256) + c <= (T-end*256) + C-end, and no code outside the range matches. An ICMP message has one type whichever way it travels, so a both entry installs the same type and code in each direction.

The same entries are the ICMP controls of RFC 4301 Section 6.1. Section 6.1.1 requires that an administrator can "accept or reject unauthenticated ICMP traffic", at the granularity of ICMP type. An in entry with discard rejects one type arriving at Ze, and with bypass accepts it. The Linux kernel checks every ICMP message delivered to Ze against the inbound policies before it processes it (icmp_rcv, net/ipv4/icmp.c, and its IPv6 counterpart):

set vpn ipsec policy no-redirect action discard
set vpn ipsec policy no-redirect direction in
set vpn ipsec policy no-redirect protocol 1
set vpn ipsec policy no-redirect icmp-type 5
set vpn ipsec policy no-redirect local prefix 0.0.0.0/0
set vpn ipsec policy no-redirect remote prefix 0.0.0.0/0

Section 6.1.2 asks for controls over ICMP error messages "received on the protected side of the boundary, and directed to the IPsec implementation". Write the same kind of in entry with the protected-side subnet as the remote prefix, for example remote prefix 10.1.0.0/16 and icmp-type 3 to refuse Destination Unreachable from the hosts behind Ze. Those hosts send in the clear, so the entry decides every such message.

An ICMP message that arrives on a Child SA is decided by that SA's peer. When the peer's icmp-error-check is true (the default) and an in discard entry refuses the message, Linux reads the header the message carries after its ICMP header, reverses its addresses and ports, and delivers the message when that header matches the SA it arrived on. The type plays no part: the kernel does not check that the message is an error, so a message of any type whose following bytes read as such a header would be admitted, whatever the discard entry says. With icmp-error-check false on that peer, the entry decides. icmp_rcv (net/ipv4/icmp.c) and icmpv6_rcv (net/ipv6/icmp.c) make this check when the last state that decrypted the message carries XFRM_STATE_ICMP, the flag icmp-error-check true sets; LL-XFRM-ICMP-TRANSIT in Linux limitations records it.

For an ICMP error forwarded to a protected host, Linux can search the reversed quoted header before applying the final forwarding disposition. Ze uses the namespace's XFRM forwarding default for unmatched, rather than a forwarding catch-all that would hide that lookup. The Child SA's forwarding PROTECT entries remain in force, including on an XFRM interface. With the check enabled, a consistent quoted header can select that SA's policy; an inconsistent one is dropped. Disabling the check requires the error's own headers to be allowed by the SA's selectors and receive policy. It does not authorize an error outside them. Ze preserves the namespace's inbound and outbound default dispositions and restores the previous forwarding default when its SPD is released. Another XFRM policy manager must coordinate default-policy writes with Ze; an observed external change refuses a reload or restoration rather than being overwritten. The diagnostic code doctor-ipsec-forward-default reports a missing host permission, an unreadable default, a conflicting policy manager, or a restoration that has not completed. Its finding names the next command. A shutdown failure also remains in the warning log when the daemon connection has already closed.

So commit refuses a discard entry that is in or both, has protocol 0 or the ICMP protocol of its family, any icmp-type, and a family the selectors of a peer with icmp-error-check true can carry. Its prefixes and its order do not matter, because the kernel's second check reads neither the message's own source nor the address it arrived at. A peer with vti bind is exempt: ICMP that arrives on its xfrm interface is checked at the interface's if_id, where no vpn ipsec policy entry applies. The refusal names the peer and the entry; set icmp-error-check false on the peer, or delete the entry. The unmatched discard catch-all is not refused: delivering an error whose payload matches the SA is the Section 6.2 processing itself.

These entries install inbound and outbound policies only. ICMP that Ze forwards between two other hosts is decided by the Child SA forward policies and the catch-all entry below; an operator entry does not reach it yet.

The VPP dataplane compares ports only for TCP, UDP and SCTP, so an ICMP type entry there would match every ICMP message. Ze refuses such an entry on VPP with a message naming the reason, rather than installing it wider than written.

A tunnel can negotiate an ICMP selector too. IKE carries the type in the high eight bits of the port and the code in the low eight; Ze programs the type and code from the sending side's value in each direction.

On Linux a discard entry is an XFRM policy with action block and a bypass is allow with no template. On VPP they are IPSEC_API_SPD_ACTION_DISCARD and IPSEC_API_SPD_ACTION_BYPASS. show vpn ipsec dataplane reports the disposition of every installed policy, including one another daemon installed.

Ze installs these entries when the configuration is applied and removes them when the entry leaves the configuration or the engine stops. They need no peer, no key and no negotiation, so they are in force whether or not any tunnel is up.

The catch-all entry

RFC 4301 Section 5: "If no policy is found in the SPD that matches a packet (for either inbound or outbound traffic), the packet MUST be discarded." The Linux kernel does the opposite with no matching policy: it passes the packet in the clear. Ze installs last IN and OUT entries for IPv4 and IPv6 at the largest priority the kernel holds, so every entry above is searched first. Forwarding uses the namespace's XFRM default disposition, after ordinary policies and the ICMP quoted-header lookup. Its disposition is one leaf:

set vpn ipsec unmatched discard
Value Meaning
discard (default) Traffic no entry matches is dropped, the disposition Section 5 names
bypass Traffic no entry matches crosses the boundary in the clear, which is what the kernel did before the entry existed

The default is discard, the entry RFC 4301 Section 4.4.1 asks for: "Every SPD SHOULD have a nominal, final entry that matches anything that is otherwise unmatched, and discards it." Until 2026-10-18 the default was bypass; the owner reversed that ruling (R27) to follow the RFC.

The catch-all also drops the router's own traffic wherever it crosses in the clear:

  • BGP sessions, SSH and web logins, DNS and NTP.
  • ICMP: ping, traceroute, the probes of show mtu, and the path-MTU errors ("fragmentation needed", "packet too big") that tell the router to send smaller packets.
  • IPv6 neighbor discovery. It is ICMPv6 (protocol 58), and the catch-all matches every protocol, so with no bypass the router cannot resolve an IPv6 neighbor on a link and sends it nothing.

Only IKE (UDP 500 and 4500, the control-plane bypass at order 100), the negotiated tunnels and your policy entries stay open. So write a bypass entry under policy for every flow that must still cross in the clear, for example a BGP neighbor:

set vpn ipsec policy frr-bgp action bypass
set vpn ipsec policy frr-bgp local prefix 172.28.0.2/32
set vpn ipsec policy frr-bgp remote prefix 172.28.0.4/32

and ICMP for both address families, which keeps ping, traceroute, show mtu, path-MTU errors and IPv6 neighbor discovery working:

set vpn ipsec policy icmp4 action bypass
set vpn ipsec policy icmp4 protocol 1
set vpn ipsec policy icmp4 order 3000
set vpn ipsec policy icmp4 local prefix 0.0.0.0/0
set vpn ipsec policy icmp4 remote prefix 0.0.0.0/0
set vpn ipsec policy icmp6 action bypass
set vpn ipsec policy icmp6 protocol 58
set vpn ipsec policy icmp6 order 3000
set vpn ipsec policy icmp6 local prefix ::/0
set vpn ipsec policy icmp6 remote prefix ::/0

Order 3000 ranks these entries after a tunnel's default 2000, so ICMP that a tunnel's traffic selectors cover still goes through the tunnel. These entries carry ICMP errors in clear, so commit refuses them beside a site-to-site peer whose icmp-error-check is true and that has no vti bind (see ICMP error messages above): set icmp-error-check false on each such peer, and the entries then decide where an error goes. The refusal and the start-up log below print the same ICMP example.

Or write set vpn ipsec unmatched bypass to pass all of that traffic, with the same icmp-error-check false on each site-to-site peer that has no vti bind.

Ze cannot list those flows for you: they live in every other part of the configuration and in the routing table, and an exemption list that missed one would cut it with nobody told. Instead, a commit that would turn the discard on while unmatched is unset is refused, so nobody configuring vpn ipsec over SSH cuts their own session by default:

ike config: this commit turns on the SPD catch-all DISCARD without saying so: `vpn ipsec unmatched` is not set and its default is discard (RFC 4301 Section 4.4.1). ...

The refusal names what stays open, including how many policy bypass entries you have, and the two commands that settle it: add the bypass entries, then set vpn ipsec unmatched discard; or set vpn ipsec unmatched bypass. It fires only when the commit would turn the discard on: a written unmatched leaf, either value, always passes, and so does a commit to a box whose catch-all already discards.

The check runs on commit only. A configuration the daemon starts with is not verified, and start-up reads unmatched as the file states it: unset means discard, the default, with the error log below, whichever release saved the file. Write unmatched bypass into a file to keep passing unmatched traffic, and unmatched discard to say the discard is meant.

When the daemon starts with the discard in force by default, it logs it at error level, with the same facts and commands as the refusal, so the console says why BGP or SSH went quiet:

ike: the SPD catch-all DISCARD is in force because `vpn ipsec unmatched` is not set and its default is discard (RFC 4301 Section 4.4.1): ... bypass-entries=0 code=doctor-ipsec-implicit-discard

ze doctor reports the same state for as long as it lasts, as the error doctor-ipsec-implicit-discard with the same text, and names set vpn ipsec unmatched discard as the fix that confirms the default.

A box with no vpn ipsec block keeps a bypass catch-all: it configured no IPsec boundary.

The IKE control-plane bypass at order 100 is installed either way, so the tunnels can still be negotiated. Ze's entries appear together on the first apply, the catch-all first and the IKE bypass right after it, before any IKE socket opens. The catch-all is re-asserted on every apply. When the engine stops, every tunnel is torn down first, then the IKE bypass and your policy entries are removed, and the catch-all goes last, so no Ze entry is ever in force without it. If any of those entries cannot be removed, the catch-all stays installed beneath it, and the daemon logs a warning naming each entry left as the command that removes it in the dataplane's own tool. On the Linux kernel that is the exact ip xfrm policy delete command: direction, prefixes, protocol, ports and if_id, so two entries that differ only by port get two different commands. On VPP it is the vppctl ipsec policy del command for the entry VPP holds.

When the entry is not there

A catch-all that is not installed leaves a packet no entry matches meeting no entry at all, which RFC 4301 Section 5.2 forbids ("If there is no match, discard the traffic"), so Ze never reports such a configuration as applied, whichever value unmatched holds. The one exception is the VPP backend:

Situation discard bypass
The VPP backend, which holds no entry bound to no interface Refused at commit. A configuration the daemon starts with is not verified, so a start with unmatched unset (or discard) fails instead: installing the discard entry fails, and the configure step returns that error. Fix: set vpn ipsec unmatched bypass in the configuration file, then start again Accepted; no entry is installed, and the traffic crosses in the clear. This is an open RFC 4301 gap on VPP
A build off Linux, or a kernel without XFRM Refused at commit, and a start fails as in the row above The apply fails: a commit is refused, and at startup the configure step returns the error. Fix: run Ze on a Linux kernel with XFRM (CONFIG_XFRM_USER)
✕ Refused at commit The apply fails. Fix: the cause the daemon logged
The install itself fails when the configuration is applied, which includes a daemon without CAP_NET_ADMIN: it can open the XFRM socket, so the commit check passes, and the kernel refuses the install The apply fails with the error, and the configuration is not reported applied: a commit is refused, and at startup the configure step returns the error Same as discard. Fix: give the daemon CAP_NET_ADMIN
Before the first configuration is applied, and after the engine stops The IPsec engine holds no SPD entry and no SA, so it is not acting as an IPsec implementation and no packet is looked up in an SPD of its own; the kernel passes traffic as it does with no IPsec configured. Two exceptions: an entry the engine could not remove on stop keeps the catch-all beneath it (the warning names both), and OSPFv3 authentication with manual keys installs its own SAs and policies with no catch-all, an open RFC 4301 gap Same

The catch-all is installed before the policy entries, the peers and the cookie threshold of the same configuration, so a refused apply leaves the previous entries and threshold in place.

That order has a cost with discard. Between the catch-all install and the install of your bypass entries, traffic those entries are meant to pass matches only the catch-all and is dropped. This happens on the first apply, and on every reload that adds or changes a bypass entry, for the flows that entry covers (a changed entry is removed and installed again). An entry the reload leaves unchanged stays installed throughout. The window lasts as long as the apply takes to install the policy entries. When you first turn discard on, commit the bypass entries while unmatched is still bypass, then set unmatched discard in a later commit: the entries are then already installed when the catch-all starts dropping. A bypass entry added or changed once discard is in force always crosses the window.

Route-based tunnels under discard

The Linux kernel keeps one policy database for each XFRM if_id. The catch-all lives at if_id 0, and a peer with vti bind installs its Child SA policies at the if_id of that XFRM interface. A packet routed into the interface is looked up at if_id 0 first, and only reaches the interface's own policies once it gets there. Under discard it would meet the catch-all on the way and be dropped. So for every XFRM interface a peer binds, Ze installs bypass entries at if_id 0, ranked just above the catch-all and below every policy entry and every Child SA policy:

Entry Matches Why
out and fwd, IPv4 and IPv6 any address, output device the XFRM interface Forwarded traffic, and the router's own IPv4 traffic, carry the output device into the lookup
out, IPv6 source each IPv6 address the XFRM interface holds, any destination The router's own IPv6 traffic is looked up before the kernel records the output device

None of these is installed under unmatched bypass, since the catch-all already passes the traffic.

Each bound XFRM interface's own database also gets final discard entries in IN and OUT for IPv4 and IPv6 at the interface's if_id, ranked last, so the interface's Child SA policies are always searched first. A packet routed into the interface that no Child SA covers is dropped there and counted by the kernel's XfrmOutPolBlock counter. This entry discards under both values of unmatched: an XFRM interface has no path in the clear, because the kernel drops a packet there that matches no Child SA whatever entry it meets, so a bypass at the interface would only be listed as one. It goes in before the if_id 0 entries above hand any packet to the interface, and comes out after them. Its FWD lookup uses the namespace default after the Child policies and ICMP quoted-header lookup; a tunnel-mode packet no policy covers is still rejected even when that default accepts.

The entries follow the interface: Ze reads its index and addresses and if_id through the interface resolver, and reads them again when an interface address is added or removed or an interface is created. An address the interface loses takes its entry with it, and the entries are removed when no peer binds the interface and when the engine stops; the if_id 0 entries also leave when unmatched turns to bypass. An interface that reports if_id 0 is treated as one that cannot be read, because if_id 0 is the node-wide database. If the interface cannot be read, its entries stay as they were and the daemon logs a warning. If an if_id 0 entry cannot be installed, the daemon logs an error: the tunnel's traffic is then dropped by the catch-all. If an interface's own final entry cannot be installed, which includes a daemon without CAP_NET_ADMIN, the apply fails as it does for the node-wide catch-all: a commit is refused, at startup the configure step returns the error, and no if_id 0 entry hands that interface any traffic. Without its final entry the kernel would still accept an unmatched inbound packet that arrived under a transport-mode or offloaded state. Fix: give the daemon CAP_NET_ADMIN, then commit again. An interface address change meets the same failure with no commit to refuse, so the daemon logs it as an error and the next commit fails until the entry goes in. On a reload that turns discard on, the entries go in before the catch-all changes, so a running tunnel never loses traffic.

The IPv6 source entry is wider than the interface it stands for: an IPv6 packet sourced from the XFRM interface's own address but routed out of another interface would match it too. Under unmatched discard Ze therefore guards each such address, and installs its source entry only while the guard holds:

  • A rule from <address>/128 looks the packet up in a routing table Ze owns for the interface (tables 3000 to 3999, routes marked ze-ipsec-guard). The table holds a route into the interface for every IPv6 remote traffic selector of a Child SA bound to it, and ends in unreachable ::/0. A program that binds the tunnel address as its source is sent into the tunnel, or told the destination is unreachable.
  • The nft table ze_ipsec_source_guard drops, at postrouting, IPv6 from the address leaving through any other interface. This catches the packet whose source the kernel picked after routing it, which no source rule sees.

So traffic from a tunnel address leaves only through its tunnel, and the operator's own routing table IDs 1000 to 3999 are refused because Ze reserves them. A peer whose local-address is an address of an interface some peer binds with vti bind is refused at commit: the guard would send its IKE traffic into its own tunnel. Set local-address to an address of the WAN interface instead.

Application overrides

RFC 4301 Section 4.4.1: "However, the system administrator MUST be able to specify whether or not a user or application can override (default) system policies." On Linux an application overrides the SPD by setting a per-socket policy (IP_XFRM_POLICY, IPV6_XFRM_POLICY, and the older IP_IPSEC_POLICY and IPV6_IPSEC_POLICY). The kernel consults it before any SPD entry, so one ALLOW socket policy takes that socket past every entry, the discard catch-all included. Linux asks only for CAP_NET_ADMIN, and a Ze appliance gives that to every external plugin it starts. One leaf decides:

set vpn ipsec application-override deny
Value Meaning
deny (default) Ze attaches a cgroup BPF program to the cgroup2 root that refuses those four options with EPERM to every process in Ze's network namespace except Ze itself. Every other setsockopt passes untouched, and a process in another network namespace (which has its own SPD) is not affected
allow ✕

A box with no vpn ipsec block attaches nothing: it has no SPD to protect.

Ze's own exception is the ESP form reader's inbound socket policy (see "Both ESP wire forms"): it is the IPsec implementation's receive path, not an application, and the listing names it esp-form-socket. The program recognises Ze by its process id inside Ze's own PID namespace, so the exception holds when Ze runs in a container.

deny needs CAP_BPF and CAP_NET_ADMIN, a cgroup2 mount (Ze finds it in /proc/self/mountinfo; gokrazy's init and systemd both mount it at /sys/fs/cgroup at boot) and a kernel with CONFIG_CGROUP_BPF, Linux 6.10 or later, both of which Ze's kernel carries. The version matters on a distribution kernel: the guard names its caller with bpf_get_ns_current_pid_tgid, which Linux offers to a cgroup program only from 6.10 (bpf_base_func_proto in kernel/bpf/helpers.c; 6.9's cg_sockopt_func_proto does not offer it), so an older kernel refuses to load the guard. When any of them is missing the apply fails rather than run without the guard:

vpn ipsec application-override deny: Ze could not attach its setsockopt guard to the cgroup2 root (<kernel error>). Without it any process holding CAP_NET_ADMIN can exempt its sockets from the IPsec policy. Run ze with CAP_BPF and CAP_NET_ADMIN (under systemd, a ze unit written by an older ze does not grant CAP_BPF: stop ze with `sudo systemctl stop ze`, then rewrite the unit with `sudo ze install systemd --force --start`) on Linux 6.10 or later (an older kernel refuses the guard's bpf_get_ns_current_pid_tgid call), mount cgroup2 at /sys/fs/cgroup, or set `vpn ipsec application-override allow` to accept that risk.

Until an apply succeeds, show doctor reports the same refusal as doctor-ipsec-override-guard, and so does a ze doctor the running daemon answers, so a boot that left IPsec down on such a host says why. The check reads what the IKE engine recorded in the process that answers doctor. It therefore reports nothing in a ze doctor no daemon answered, and nothing in a daemon that runs the IKE engine as an external plugin.

A reload moves between the two values with no restart, and removing vpn ipsec detaches the program after the catch-all leaves.

What the guard cannot do, and what ze doctor reports instead:

Limit Why Doctor
A socket policy set before the guard attached, or while allow held, stays until its socket closes The kernel offers no way to delete a socket policy, and its dump names no owning process doctor-ipsec-socket-policy, a warning per policy that is not Ze's, under deny
A CAP_NET_ADMIN holder can still write the SPD itself over netlink cgroup BPF has no hook on a netlink send, and Linux treats that holder as an administrator doctor-ipsec-spd-writer, a warning naming each such process and its command; doctor-ipsec-spd-writer-unknown when /proc hides processes from Ze (not mounted, hidepid, no ptrace access), so it cannot tell
A process holding CAP_SYS_ADMIN or CAP_BPF can detach the program It is an ordinary cgroup link doctor-ipsec-override-guard, an error when the guard is not attached under deny

show vpn ipsec dataplane policy lists every socket policy with SPD socket, its direction, and role esp-form-socket or socket-override.

Both ESP wire forms

RFC 7296 Section 2.23 requires a device that supports NAT traversal to receive UDP-encapsulated ESP and bare ESP at any time. One Linux XFRM state serves one form (LL-XFRM-STATE-ONE-ESP-FORM). Ze serves the second form beside the kernel, on a Child SA whose inbound state is UDP-encapsulated: one whose IKE SA runs on port 4500, with or without a NAT. One established Child SA therefore keeps carrying traffic when its peer changes ESP form mid-session, with no rekey and no delete.

Bare ESP for such a Child SA reaches XFRM through one of two paths. On both, the packet XFRM decrypts arrives on an interface where Linux runs the inbound IPsec policy check, so the Child SA's traffic selectors and unmatched discard hold for it as RFC 4301 Section 5.2 requires.

Path What it carries Interface the decrypted packet arrives on
Fast path, in the kernel Every whole bare ESP datagram from the SA's peer to its local address, received on a link the program is attached to The link the datagram arrived on
Complete path, in Ze What the fast path leaves alone: fragmented datagrams (read after the kernel reassembles them), an IPv4 header with options, a frame that carries a VLAN tag (a rule on the VLAN's parent interface can match the tag, and would see UDP where it matches ESP), and a link the program is not attached to. It reads IPv4 only ze-espform

On a distribution kernel, the loaded module esp4_offload can consume bare ESP during Generic Receive Offload (GRO), before either of Ze's paths sees it. While a dual-form SA is installed, ze doctor reports that module under doctor-ipsec-esp-form-offload. Its systemd fix is:

sudo systemctl stop ze && sudo modprobe -r esp4_offload && sudo systemctl start ze

Stopping Ze interrupts all its tunnels and removes their SAs, which can hold references that prevent the module from unloading. Ze does not request hardware offload for its SAs, so negotiating them again does not autoload this module. Another IPsec owner can still hold or load it: if unloading fails, the command leaves Ze stopped. Stop that owner and retry before starting Ze. If another owner needs the module, disable GRO on the receiving interfaces through their existing offload { gro false; } configuration instead. Without systemd, stop and start Ze with the supervisor that runs it, with sudo modprobe -r esp4_offload between those steps.

An unreadable receiver state or module list is a separate doctor-ipsec-esp-form-offload-unknown warning, with the command to inspect the dataplane's warnings or restore missing procfs. A readable module list proves only whether the module is loaded; it cannot detect an ESP GRO implementation built into the kernel. Ze's runtime kernel does not enable that feature.

The fast path is a tc ingress program. It adds a UDP header with the IKE ports to a bare ESP datagram for a watched Child SA, in place, so the kernel receives the form the state expects on the real link. Ze attaches it to every interface except lo and ze-espform while any Child SA is served this way, and to an interface created later. An interface type the program cannot read is logged by name, and its bare ESP goes to the complete path. When the program cannot load at all, the complete path carries all bare ESP.

The doctor check ipsec-esp-form-fast-path reports a fast path that could not load, or that stopped following new interfaces, as a doctor-ipsec-esp-form-fast-path warning carrying the cause and the fix (CAP_BPF and CAP_NET_ADMIN, which a unit written by an older ze lacks: stop ze and rewrite the unit with sudo systemctl stop ze && sudo ze install systemd --force --start; or a kernel with TCX), and each interface it does not serve as a doctor-ipsec-esp-form-link warning naming the interface and the reason. That warning's fix is a step on the peer, so its message carries it (on strongSwan, set encap = yes in the connection and run swanctl --load-conns), or routing the traffic over an interface of a type the fast path serves. Its fix line is the command that shows the interface, ze show interface name <interface> detail, or ze show interface when the interface's name cannot be typed as one command word. A fast path whose state Ze could not read is the same warning, with the command that lists the warnings naming the cause.

A fast path that loaded and then detached itself is a different warning under the same code. Ze shuts the program's firewall gate while it checks the nftables ruleset, and when the kernel refuses that write, Ze removes the program from every interface rather than let it rewrite bare ESP past a firewall rule that should see it. All bare ESP then takes the complete path, at its rate bound, until ze restarts or until no Child SA is served in both ESP forms and one is installed again. The warning says the gate could not be shut and names the refused write, and its fix is sudo systemctl restart ze. It names no capability or kernel step: the program had loaded. Only a fast path that never loaded gets the CAP_BPF warning above.

Ze picks each inbound SPI at random, so two Child SAs on two different local addresses can draw the same one. The kernel serves both, but the fast path serves one SA per SPI, the first one installed, so bare ESP for the second SA takes the complete path at its rate bound. The same check reports this as a doctor-ipsec-esp-form-fast-path warning that names the SPI and both local addresses. Its fix is ze clear vpn ipsec sa peer <name> for the peer that holds the second SA: Ze has no command that rekeys one Child SA, so the clear negotiates that peer's SAs again, and the new Child SA draws a new SPI. That peer's tunnel carries no traffic until its new SAs are up. When Ze cannot name the peer, for example while a rekey replaces the SA, or when the peer's name cannot be typed as one command word, the fix is ze show vpn ipsec sa, which lists each peer with its inbound SPI but not its local address. Clear either peer whose Child SA carries that SPI: either way the cleared peer's new Child SA draws a new SPI, the other SA holds the SPI alone, and the fast path serves it. The warning goes when either SA is removed.

Ze also logs the collision at Warn when the second SA is installed, but only while the fast path is attached: a fast path that could not load or detached itself serves no SA, so the collision costs nothing more and that status has its own warning. The log line's fix is the listing, ze show vpn ipsec sa, and its message says that clearing either peer whose Child SA carries the SPI, with ze clear vpn ipsec sa peer <name>, ends the collision. A MOBIKE move that would put an SA on the local address where another SA with the same inbound SPI is received is refused before Ze changes anything, and the tunnel stays on its old address. The refusal's fix is ze show vpn ipsec sa; clear either of the two peers to end the collision.

A MOBIKE move also needs the complete path. After the move the SA's inbound state carries the ESP-in-UDP template, so the kernel refuses its bare ESP and only Ze's receiver, its raw ESP socket and the ze-espform device, serves that form. When the SA was not served in both forms before the move and those cannot open, Ze refuses the move with nothing changed, and the tunnel stays on its old address. The refusal names the SPI and both local addresses, and its fix is the one the cause names, shown once. Every cause the host can produce names its own fix:

Cause Fix
✕ sudo systemctl stop ze && sudo ze install systemd --force --start
A Linux security module (SELinux or AppArmor) refuses the raw ESP socket or its exemption (EACCES); no capability changes that sudo journalctl -b --grep 'avc:|apparmor="DENIED"', which lists the denials, then change the policy for ze
ze reached its limit of open files (EMFILE); the ze unit sets LimitNOFILE=65536 sudo systemctl stop ze && sudo ze install systemd --force --start
The host reached its limit of open files (ENFILE) sudo sysctl -w fs.file-max=9223372036854775807, the value systemd sets at boot
The kernel is short of memory (ENOMEM, ENOBUFS) free -m
The TUN device does not open, or ze-espform cannot be created The fix the TUN refusal names, such as ls -l /dev/net/tun or modprobe tun
✕ sudo systemctl stop ze && sudo ze install systemd --force --start; in Docker, start the container with --cap-add NET_ADMIN
Another step of the configuration of ze-espform failed, and Ze removed it again ze show log recent level warn component ike.dataplane, whose warnings carry the kernel's answer
An IPv4 setting of ze-espform that Ze could not write, for a reason other than a read-only /proc/sys sudo sysctl -w net.ipv4.conf.default.<setting>=<value>, as the refusal names it
Any other answer of the socket or its exemption ze show log recent level warn component ike.dataplane: Ze tries again at the next install, and by itself while such an SA is installed

The same causes refuse the install of a Child SA that must receive both ESP forms, with the same fix. Ze records its last failure to open its own receiver for bare ESP, and the doctor check reports it as a doctor-ipsec-esp-form-tun error with the cause, the time and the fix, until an open succeeds. When the TUN outcome the last configuration apply recorded has the same cause, the check reports this one error alone.

The raw ESP socket can also fail after it opened. The Child SAs it served stay installed, so Ze opens the receiver again by itself while such an SA is installed: at once, then further apart, doubling up to 30 seconds. The wait starts again at once only after a receiver that served for a minute, so a socket that fails right after each open is not reopened in a tight loop. Ze logs each stop at Warn and raises it on the report bus as a doctor-ipsec-esp-form-reader-stopped error event, which ze show errors and ze show doctor report even when the receiver opened again at once. Until it opens, bare ESP for those SAs is received only where the fast path rewrites it, and the next install, or a move onto the ESP-in-UDP form, opens it or is refused with the cause.

The fast path runs before netfilter, so Ze keeps it off while a firewall rule or policy on the input path could drop ESP. The check then reports a doctor-ipsec-esp-form-firewall warning naming the first site that could drop it. Bare ESP takes the complete path, after the input path, so the firewall still decides on it. The warning says what that costs: the complete path's rate bound, the datagrams above it dropped before XFRM sees them, and the input interface a rule sees, which is ze-espform. To keep the fast path, and only if that ESP should be accepted, accept protocol esp ahead of that site in its chain; otherwise leave the firewall as it is. The warning says who writes the site's table, and its fix depends on that:

  • A table Ze does not own (its kernel name does not start with ze_) takes the nft command that inserts the accept at the head of the base chain, such as sudo nft 'insert rule inet "filter" "input" meta l4proto esp accept'. When the table or chain name holds a quote or a control character, Ze prints no command to paste: the fix is sudo nft list ruleset, and the warning says to insert that rule with nft. A table created with the owner flag, which nft list ruleset marks # owner, takes that change only from the process that owns it.

  • A table of Ze's firewall configuration (its kernel name is ze_ and the table's name in the configuration) is rewritten at each firewall commit, so an nft rule there would be gone after the next one. The fix is three lines to paste into ze config edit, here for table wan and chain input:

    set firewall table wan chain input term accept-esp from protocol esp
    set firewall table wan chain input term accept-esp then accept
    commit now
    

    The editor adds a new term after the chain's existing terms and has no command that moves a term ahead of another, so accept-esp accepts ESP only where no earlier term of the chain drops it. While an earlier term can drop ESP, that term stays the site and the fast path stays off.

  • A table a Ze plugin or component writes (it reserved the table's name) has rules that follow that plugin's state, and Ze rewrites the table whenever the state changes, so neither an nft rule nor the configuration editor changes it for long. The warning names the plugin and what decides its rules, and the fix is the command that shows that state: show bgp rib best | family ipv4/flow for the flowspec-firewall plugin's ze_flowspec, or show firewall ruleset ipsec_source_guard for the IKE engine's tunnel-source guard. The rule changes only with that state.

  • A ze_ table that no plugin reserved and whose table or chain name the configuration cannot hold is neither, and the fix is show firewall ruleset.

When the fast path started and Ze could not open its nftables reader or join the monitor that follows the ruleset's changes, or that monitor was closed, the fast path is off for safety, and the same warning names the cause, with sudo systemctl restart ze as the fix: nothing reads the ruleset again until ze restarts, or until no Child SA is served in both ESP forms and one is installed again. When the reader and the monitor are open but one read of the ruleset failed, Ze needs no restart: the monitor still runs, so the next commit to the ruleset, by Ze's firewall or by any other program, makes Ze read it again, and nothing reads it before then. The warning says so, and its fix, sudo systemctl restart ze, reads the ruleset at once. When the monitor fails, Ze needs no restart: it watches the ruleset again by itself, after a wait that doubles from one second up to thirty seconds, and turns the fast path back on once a fresh read of the ruleset finds no rule that can drop ESP. While the fast path is off for that reason, the warning says no restart is needed for the firewall reading, and its fix is ze show log recent level warn component ike.dataplane, which names why the monitor keeps failing, usually a missing CAP_NET_ADMIN.

Ze's own firewall commits hold the fast path off while they land: the IKE engine registers a firewall commit observer that takes the hold before the nftables backend applies a reconcile and releases it once the apply returns. With the IKE engine run as a forked plugin, the daemon's commits take no hold, and Ze learns of them from the nftables monitor alone.

The check reads the state the IKE engine's own process holds, so it is a runtime check the engine answers: show doctor runs it, and so does ze doctor when the running daemon answers it. A ze doctor no daemon answered reports doctor-runtime-not-checked instead.

The same check reports doctor-ipsec-esp-form-tun, an error, when Ze could not create a usable ze-espform interface for the complete path. For example, Ze can neither open nor create /dev/net/tun. Or Ze cannot write /proc/sys (it is read-only, as in a container), and the interface would take from net.ipv4.conf.default a disable_policy of 1, which skips the inbound policy check, or a strict rp_filter (the larger of conf.default and conf.all is 1). Every Child SA on UDP port 4500 is then refused at install, because such an SA must receive bare ESP as well as ESP-in-UDP.

The IKE engine checks this itself on every configuration apply that configures an IPsec peer on the Linux kernel dataplane, because any IKE SA can move to UDP port 4500. The apply opens the device as a Child SA install would, so where the node is missing the apply creates it. It logs a refusal once per apply, at WARN. The doctor check only reads the outcome that apply recorded, so show doctor never creates the device node. While the receiver watches a Child SA it holds the device, and the check reports no finding. The message names the cause, and the fix is the one the refusal gives, listed below after the complete path. A refusal that names no fix gets ze show log recent level warn component ike.dataplane.

The complete path is a raw IPPROTO_ESP reader. Linux gives it a copy of the bare datagram XFRM refused. Ze writes that datagram again with the UDP header into its own TUN interface ze-espform, which has disable_policy 0, and the kernel receives it there. The complete path runs in Ze, so it is bounded to 5000 datagrams per second, with a burst of 10000. The fast path has no such bound.

The complete path needs the TUN clone device /dev/net/tun. Where the node is missing, as in a container started without --device /dev/net/tun, Ze creates it (c 10 200, mode 0600, in /dev/net) when the kernel allows it: the process must hold CAP_MKNOD in the initial user namespace, and the device cgroup must grant the device. A default Docker container meets both. Ze never changes a node that exists. When Ze can neither open nor create the node, it refuses every Child SA that must receive both ESP forms, with an error that names the cause and the fix. Under Docker the fix is --device /dev/net/tun (Compose: devices: [/dev/net/tun]); on a host it is modprobe tun; a kernel without CONFIG_TUN needs a new kernel; and creating ze-espform needs CAP_NET_ADMIN. The refusal is not a configuration error: without the device, Ze cannot receive bare ESP on the SA and still run the inbound policy check (RFC 4301 Section 5.2).

The kernel gives the new ze-espform interface the values of net.ipv4.conf.default, and Ze writes disable_policy 0 and rp_filter 2 on it only where the interface does not already hold them. In a container whose /proc/sys is read-only, start the container with --sysctl net.ipv4.conf.default.disable_policy=0 --sysctl net.ipv4.conf.default.rp_filter=2 (Docker accepts net.* sysctls for the container's own network namespace). Otherwise Ze refuses a Child SA that must accept both ESP forms when the interface would skip the inbound policy check or use strict reverse-path filtering.

Setting net.ipv4.conf.all.disable_policy to 1 turns the inbound policy check off on every interface of the host, ze-espform included, and Ze reports nothing about it: that is the operator's choice for the whole host, and Ze does not override it.

Both paths keep the outer TOS octet the bare datagram arrived with, so XFRM copies an ECN congestion mark (CE) from the outer header into the decrypted packet, as RFC 7296 Section 2.24 requires: the fast path never rewrites that octet, and the complete path copies it into the header it builds.

The cost for a firewall rule. A packet the complete path carries arrives on ze-espform, not on the link it came in on. A firewall rule that matches the input interface sees ze-espform for that traffic.

The fast path does not take a decision away from the firewall. It adds the UDP header at tc ingress, and Linux runs tc ingress before the firewall: before the netdev ingress hook and before prerouting. A datagram it rewrote would reach a rule on protocol esp as UDP to port 4500. So the fast path rewrites only while no nftables rule or chain policy on the input path could drop or change the peer's ESP: a base chain on the ingress, prerouting or input hook of an inet, ip, netdev or bridge table. While one could, the fast path leaves bare ESP as it arrived, and the rule keeps deciding. That holds for a Ze firewall term on protocol esp and for a rule an operator added with nft alike, because Ze reads the kernel's ruleset, not its own configuration. A rule Ze cannot read in full, such as one using an iptables extension or an expression Ze does not know, counts as one that could drop ESP.

Ze tells a rule that cannot match ESP from one that can only by the match the rule opens with: meta l4proto equal to a protocol other than ESP, in any table; the IPv4 protocol field (ip protocol) equal to one, in an inet or ip table only; or meta nfproto ipv6, in an inet or ip table, as the rule's first match. In a netdev or bridge table an ip protocol match does not count, because the packet there need not be IPv4. meta l4proto udp drop cannot match ESP. A rule whose first match is an address, a port or an interface counts as one that can, even when a protocol match follows, and so does a rule on meta l4proto != esp. Ze's own drops open with their protocol for that reason, so the GTSM drops of a BGP peer with connection ttl max, and an on-host DDoS mitigation against a protocol other than ESP, keep the fast path on. A DDoS mitigation against ESP itself, or against a protocol Ze has no name for, keeps it off: the first opens with ESP, the second with the victim's address, and both can drop ESP sent to that address.

A rule that can match ESP keeps the fast path on only when all it does is select, count, log or rate-limit, and it then accepts or goes on to the next rule. A rule that matches nothing but protocol esp, counts at most and accepts ends the check of its chain: ESP is accepted there. Any rule that can match ESP and changes something counts as one that could drop it: a mark or conntrack mark set, notrack, a DSCP or other header rewrite, a TCP option strip, a set lookup (ip saddr @trusted, because a set element can carry a connlimit or quota of its own that the rule does not show), a map lookup, a set update, dup, a named object, quota or connlimit. The warning and show doctor name the rule and the reason.

Ze reads the tables, chains and rules itself, through nftables dumps of its own, so no expression is lost in the reading. One reading is several dumps, so Ze reads the ruleset's generation number before the first dump and after the last. Every commit changes that number. When the two differ, a commit landed while Ze read, so what it read is not one ruleset: Ze turns the fast path off and reads again. The comparison does not catch every such commit: the kernel changes the number before it applies a commit's table and chain changes, so a reading that begins in between sees the new number and the old rules. The notice the kernel sends once a commit is applied covers that case, because every commit Ze hears of turns the fast path off until Ze has read the ruleset again. While commits keep coming faster than Ze can read (fail2ban adding addresses to a set every few milliseconds, each addition a commit), the fast path stays off, and Ze waits between readings, 50 ms at first, doubling to one second. A dump the kernel flags as interrupted (NLM_F_DUMP_INTR, a commit inside one dump) counts the same way: it is a commit, never a failed read, so it turns the fast path off and Ze reads again, waiting between readings while such dumps keep coming. The fast path comes back on once a reading finds the ruleset unchanged and safe, and no restart is needed.

When the commits keep coming for ten seconds or longer, show doctor reports it under doctor-ipsec-esp-form-firewall: the nftables ruleset has kept changing since at least the time it names, so the fast path stays off, and bare ESP takes the complete path at its rate bound, at most 5000 datagrams per second. The fix line is sudo nft monitor, which shows each commit as it lands, so you can see which tool keeps committing. Then make that tool batch its changes, or stop it: fail2ban, for example, commits each ban on its own. For the firewall reading, no restart is needed: the fast path comes back on once the commits pause long enough for one reading, and that reading finds no rule that can drop ESP. The warning says it that way because another warning beside it, for a fast path that stopped following new interfaces, does name a restart. A stream shorter than ten seconds is reported nowhere: the fast path outlasts a burst of commits. While the fast path is unavailable or detached, show doctor reports that alone: no program reads the firewall gate then, so a stream of commits changes nothing for bare ESP.

Ze reads base chains only. A rule that can match ESP and jumps to another chain, goes to one, returns, or picks its verdict from a verdict map counts as one that could drop ESP, and Ze does not read the chain it leads to: in the kernel a return in a base chain skips every later rule and meets the chain's policy, so a later accept would prove nothing. To keep the fast path, accept ESP ahead of the jump. The flowspec-firewall plugin's base chain flowspec-in, in table ze_flowspec, holds such a jump with no match while Ze selects a FlowSpec route whose action is a traffic-rate limit above zero, or a traffic-action whose terminal bit asks for later routes to apply too, and ends with a goto with no match while it selects a route that marks traffic. Either keeps the fast path off while that route is selected, and the warning names the plugin's command, show bgp rib best | family ipv4/flow, which lists the routes the table follows.

With the fast path off, the complete path carries the bare ESP the firewall lets through. It reads a datagram after the input chain, so a rule there has already judged it, and writes it into ze-espform, where it reaches the firewall a second time, as UDP to port 4500. That costs what the complete path costs: at most 5000 datagrams per second, with a burst of 10000. Ze drops the datagrams above that rate before XFRM decrypts them. A rule keyed on the input interface sees ze-espform, not the link the datagram arrived on.

The fast path cannot see every filter on the host, and it cannot take back a datagram it already rewrote. Ze reads only the nftables ruleset, so anything else that decides on bare ESP after tc ingress sees the rewritten datagram as UDP to port 4500. The list below holds the limits known today, each with what to do about it. It is not a complete list of what can run on a Linux host: a filter of another kind that matches ESP after tc ingress meets the same limit, and the same fix applies to it: match UDP to port 4500 from the peer as well as ESP.

  • Rules loaded with iptables-legacy live in the kernel's x_tables, which Ze does not read, so the fast path rewrites bare ESP past them. Write the rule in nftables, or load it with iptables-nft, whose rules are nftables rules that Ze reads.

  • Bridge rules loaded with ebtables-legacy live in the kernel's ebtables tables, which Ze does not read either, so on a bridge port the fast path rewrites bare ESP past them. Write the rule in an nftables bridge table, which Ze reads, or load it with ebtables-nft.

  • A BPF program attached to a netfilter hook (a BPF_LINK_TYPE_NETFILTER link, at prerouting or input) runs inside netfilter, but it is not an nftables rule, and no nftables dump shows it. It sees a rewritten datagram as UDP to port 4500. sudo bpftool link show lists these links. Make the program match UDP to port 4500 from the peer as well as ESP, or detach it.

  • A tc ingress program or filter that Ze did not install and that runs after Ze's program sees a rewritten datagram as UDP to port 4500. Ze attaches its program at the head of the interface's TCX chain and passes every packet on. Match UDP port 4500 from the peer there as well as ESP, or remove that program.

  • Linux chooses a route for each packet, and checks its source address, after tc ingress, so an ip rule that selects on the protocol (ipproto esp) sees a rewritten datagram as UDP. Two cases reach that difference:

    • With reverse-path filtering on (rp_filter 1 or 2), Linux checks the source with a route lookup back to the peer. That lookup walks the rules, and the local rule at priority 0 does not stop it, because the peer's address is not local. An ipproto esp rule that answers prohibit, blackhole or unreachable, or that sends the lookup to a table with no route back to the peer (in strict mode, rp_filter 1, no route back through that link), then drops bare ESP as a reverse-path failure and lets the rewritten datagram through. With rp_filter 0 the check drops nothing.
    • When the local rule no longer sits at priority 0, as the usual Linux VRF setup moves it, the route lookup for the packet itself reaches the rules placed ahead of the local rule. An ipproto esp rule there then decides on bare ESP and not on the rewritten datagram.

    Only an ip rule you wrote that selects on ipproto esp reaches this difference. Ze does not read the routing rules, as it does not read iptables-legacy rules. A firewall rule that sets a mark on ESP, for an fwmark rule to pick up, keeps the fast path off, so no datagram the fast path rewrote misses a mark that rule would have set.

    Ze adds no ipproto rule and never moves the local rule: its own rules select on a source address or on a mark, behind the local rule. Where you added such a rule, give UDP from the peer to port 4500 the same priority and the same action, keeping any other selector your rule has. For the route lookup of the packet itself (the second case):

    sudo ip rule add priority <priority> from <peer> ipproto udp dport 4500 <action>
    

    For the reverse-path lookup (the first case), which looks up the route back to the peer, so the peer is its destination, and in which Linux swaps the two ports, so sport 4500 names the datagram's destination port:

    sudo ip rule add priority <priority> to <peer> ipproto udp sport 4500 <action>
    

    <priority> and <action> are your ipproto esp rule's (for example prohibit, or lookup <table>), and <peer> is the IPsec peer's address. For the second case, keeping the local rule at priority 0 also removes the difference, because locally addressed traffic is then delivered before any later rule is read.

  • Ze learns of a commit another program makes (an nft command, firewalld) only after it lands, from the nftables monitor, which turns the fast path off until Ze has judged the ruleset again. A reading that such a commit lands in the middle of is not used when the generation number Ze reads around it moved. When the commit moved that number just before the reading began and applied its changes during it, the reading can be used, and the monitor's notice of that commit then turns the fast path off again. Bare ESP that arrives in between, the monitor's latency plus the end of a reading already under way, is rewritten past the new rule. It is still decrypted and checked against the Child SA's selectors: what it misses is the rule. If that window matters, commit the rule that drops ESP through Ze's firewall, whose commits hold the fast path off while they land.

  • An IKE engine run as an external plugin takes no hold across Ze's own firewall reloads, so those reloads have the same monitor window. Where the window matters, run the IKE engine inside the daemon, as Ze does by default.

  • The hold Ze's own firewall commit takes stops the fast path from rewriting from the moment it begins. A datagram the fast path rewrote just before that is still on its way to the firewall hooks as UDP to port 4500, and if the commit lands before those hooks see it, a rule the commit adds for bare ESP does not see it. The window is the time one datagram takes from tc ingress to the input hook, and no setting closes it. Where that matters, commit the rule before the IPsec peer comes up.

  • A rule that drops UDP, such as meta l4proto udp drop, cannot match bare ESP, so Ze reads it as one that cannot drop ESP and keeps the fast path on, yet it drops the datagram the fast path rewrote into UDP. That fails closed: the ESP is lost, never let through. Such a rule also drops the peer's IKE messages on UDP port 4500 unless an earlier rule accepts them, and the rewritten datagram carries the same ports as those messages, so an earlier rule that accepts the peer's IKE on UDP port 4500 accepts it too. Accept the peer's IKE ahead of the UDP drop, as the IKE SA needs anyway.

A peer that encapsulates ESP itself (strongSwan encap = yes) never uses either path.

The reader carries a per-socket inbound policy exemption. Linux applies the inbound IPsec policy check before it queues a packet to a raw socket. Ze's own Child SA policy refuses exactly the datagrams this reader exists to recover. The exemption reaches that one socket, and covers only the reading of the still-encrypted copy: the datagram Ze writes into ze-espform gets the inbound policy check like any other. XFRM still decrypts and still owns the replay window.

Receiving both forms over an IPv6 outer header is a gap owed after the first release. Ze has no IPv6 IKE transport yet: the IKE listener opens IPv4 sockets only, so no Child SA has IPv6 outer addresses. An SA that asks for both forms over IPv6 is refused rather than installed with one form. plan/post-release/features/spec-ike-ipv6-transport.md owns the work. The fast path's program already holds an IPv6 rewrite, which nothing reaches yet, and it leaves alone an IPv6 header followed by an extension header and an IPv6 datagram whose checksum the network card already summed; no complete path serves those over IPv6 either, since it reads IPv4 only. The form Ze SENDS is a separate decision and follows the NAT verdict alone: Ze encapsulates when it detected a NAT.

Traffic selectors and narrowing

A peer's traffic-selector list states which traffic its Child SAs carry. It is also the policy RFC 7296 Section 2.9 narrows a peer's proposal against.

vpn { ipsec { site-to-site { peer branch-1 {
    traffic-selector 1 {
        protocol 6
        local  { prefix 10.3.0.0/24; port 179; }
        remote { prefix 10.2.0.0/16; }
    }
    traffic-selector 2 {
        protocol 6
        local  { prefix 10.3.0.0/24; port 179; }
        remote { prefix 10.4.0.0/24; }
    }
} } } }

When the list is absent the peer accepts whatever the remote endpoint proposes. That is the behaviour of every configuration written before the list existed, so adding the list is what restricts a peer, never omitting it.

A Child SA carries every combination of its local and remote selectors. RFC 7296 Section 3.13: "a packet matches a given TSi/TSr if it matches at least one of the individual selectors in TSi, and at least one of the individual selectors in TSr." So the list must name every combination of the local and remote selectors it uses, as the example above does with one local and two remote selectors. A packet is either IPv4 or IPv6, so an IPv4 selector is never combined with an IPv6 one: a dual-stack peer with one IPv4 entry and one IPv6 entry already names every combination. A list such as local 10.1.0.0/16 with remote 10.2.0.0/16, then local 10.3.0.0/16 with remote 10.4.0.0/16, would be offered as 10.1.0.0/16 with 10.4.0.0/16 as well, so ze config verify refuses it and names the missing combination. Add the missing entries, or remove the entry that brings in the extra prefix.

An omitted port, or port any, leaves that side unconstrained. A specific port requires a protocol that defines the field: TCP (6), UDP (17), SCTP (132) or UDP-Lite (136). DCCP (33) defines ports too, but Linux XFRM cannot select them, so Ze refuses a specific DCCP port; DCCP with port any is accepted. Protocols without ports, including GRE (47) and ESP (50), require port any.

For ICMP, the number is the IKE type/code value: type times 256 plus code. For IPv6 Mobility Header protocol 135, the IKE value is the Type times 256, with a zero low octet: Type 5 is 1280, rather than 5. Ze understands that encoding, but refuses every specific MH Type at config verify and negotiation. The Linux receive-flow decoder does not fill the Type used by XFRM: an exact Type 5 policy drops even matching received and forwarded packets. protocol 135 with port any remains usable. The wanted exact-Type kernel feature is tracked in plan/post-release/kernel/spec-xfrm-ipv6-mh-selector.md.

The VPP backend refuses constrained MH and UDP-Lite selectors because its SPD does not compare those fields. Linux supports UDP-Lite ports.

The inner family of a tunnel does not have to match its outer family. RFC 4301 Section 5.1.2: "IPsec allows the IP version of the encapsulating header to be different from that of the inner header." On Linux, a tunnel-mode SA Ze installs carries IPv4 or IPv6 inner traffic over an outer pair of either family, so one Child SA whose selectors hold an IPv4 and an IPv6 pair carries both. The two outer addresses of a tunnel always share one family.

What you can configure today is narrower, because Ze's IKE sockets are IPv4 only: a tunnel has an IPv4 outer pair and carries IPv4 or IPv6 inside it. IPv4 inside an IPv6 outer pair works in the kernel datapath, but no configuration reaches it until IKE runs over IPv6.

IPv6 inside an IPv4 tunnel on a VTI

A route-based peer that carries both families writes one entry for each family. A peer with no list proposes the wildcard of its outer family alone, so a peer reached over IPv4 would never propose IPv6.

interface {
    xfrm vti0 {
        if-id 7;
        unit 0 { ipv6 { address [ fd00:db8:1::1/128 ]; } }
    }
}
static {
    table default {
        route fd00:db8:1::/112 { next { interface vti0 { } } }
    }
}
vpn { ipsec { site-to-site { peer hq {
    vti { bind vti0; }
    traffic-selector 1 { local { prefix 0.0.0.0/0; } remote { prefix 0.0.0.0/0; } }
    traffic-selector 2 { local { prefix ::/0; } remote { prefix ::/0; } }
} } } }

Ze proposes both entries, the IPv4 one first. A responder whose own policy names IPv6 alone, such as strongSwan with local_ts = ::/0 and remote_ts = ::/0, answers ::/0 on both sides. RFC 7296 Section 2.9 allows that: "When the responder chooses a subset of the traffic proposed by the initiator, it narrows the Traffic Selectors to some subset of the initiator's proposal (provided the set does not become the null set)." Ze then installs what the responder answered and nothing more: an IPv6 policy for each of the in, out and forward directions, each carrying vti0's if_id, and no IPv4 policy, so the router's own IPv4 traffic never enters vti0. An answer wider than the entry Ze proposed is refused. show vpn ipsec sa reports the narrowed selectors and the if-id. The vti-ipv6-inner-ipv4-outer interop scenario runs this configuration against strongSwan, with a ping before and after a Child SA rekey. The mgmt-tunnel and mgmt-tunnel-ed25519 topology scenarios run the same shape from a CPE behind PPPoE, authenticating with a P-256 and an Ed25519 certificate: strongSwan narrows the selectors to ::/0, an IPv6 ping crosses vti0 with each direction's ESP counters advancing, and MOBIKE moves the IKE SA to UDP 4500.

As responder, Ze narrows the initiator's proposed TSi and TSr to a subset the list allows, and leads the answer with the initiator's first choices. When the pairs it accepts are not every combination of their own selectors, it answers the largest part that is, starting from the first choice, because the initiator installs every combination it is answered. A proposal it cannot narrow to a non-empty subset draws a TS_UNACCEPTABLE notification. As initiator, Ze proposes the list in order, because RFC 7296 reads the order as the preference order.

The selectors Ze puts on the wire are the selectors it programs. A proposal it cannot program exactly is narrowed FURTHER, never rounded outward: an address range that is not a prefix becomes the largest prefix inside it, and a port range that is neither all ports nor one port becomes its first port. A rekey is never narrowed below the scope in use.

A proposed or answered selector of exactly port 0, or under ICMP of type 0 code 0 (the IKE port value 0), is dropped from the answer as responder and refused as initiator. Linux reads no port, ICMP type or ICMP code from an IP fragment, so it classifies every fragment as port 0, type 0 and code 0, and it classifies forwarded traffic before reassembling it. A Child SA with such a selector would carry every fragment between its prefixes, and RFC 4301 Section 7.3 forbids that: "a receiver MUST discard non-initial fragments that arrive on an SA with non-trivial port (or ICMP type/code or MH type) selector values unless this feature has been negotiated." Ze negotiates no NON_FIRST_FRAGMENTS_ALSO. Any port, any other single port, and an ICMP selector of any other type or code are unaffected.

Editing a peer's traffic-selector list and committing restarts that peer. The tunnel drops and comes back carrying the new selectors, and the kernel policy follows. This is what RFC 7296 Section 2.9.2 asks for: a rekey that would need a narrower scope means the policy changed, and the SA should have been deleted when the change took effect. Narrowing a live tunnel by waiting for the rekey timer is not an option the protocol offers.

A REMOTE peer whose selectors narrow while a tunnel is up proposes exactly that at its next rekey. Ze refuses such a rekey with TS_UNACCEPTABLE instead of replacing the SA with a narrower one, and the log line names both selector sets. A repeating refusal means the other end narrowed its policy and left its tunnel up. Narrow the selectors on the Ze end too, or clear the peer.

The same floor applies to a rekey Ze STARTS. Ze installs the selectors the peer answered with, never the retired SA's, so both ends program the same traffic. An answer narrower than the scope in use is refused: Ze keeps the SA that is carrying traffic, sends no error notification (RFC 7296 Section 2.21.3), and logs both selector sets. It retries at each lifetime tick, so a repeating narrows the scope in use line means the peer's policy shrank and the tunnel will hard-expire unless one end is corrected.

Port value Meaning RFC 7296 Section 3.13.1 encoding
any (the default) every port start 0, end 65535
1..65535 one port start N, end N

A port other than any needs protocol to name a protocol that defines ports, such as 6 for TCP or 17 for UDP. Section 3.13.1 requires the port fields to be 0 and 65535 whenever the protocol is 0, so the combination is refused at commit rather than widened silently. Opaque ports are refused at commit too. OPAQUE names a port that is not visible in the packet, and Ze does not yet map that meaning onto a dataplane selector, so it refuses rather than install a guess.

Transport mode

mode transport asks the peer for transport mode with the USE_TRANSPORT_MODE notification of RFC 7296 Section 1.3.1. Tunnel mode is the default, and it is the RFC's own default.

vpn { ipsec { site-to-site { peer host-1 {
    mode transport
    transport-required true
    traffic-selector 1 {
        local  { prefix 10.0.0.3/32; }
        remote { prefix 10.0.0.4/32; }
    }
} } } }

Transport mode constrains the selectors. RFC 7296 Section 2.23.1 requires exactly one IP address in TSi and in TSr, so every prefix must be a single host, and a vti binding is refused because an XFRM interface carries tunnel encapsulation. A transport-mode Child SA also carries exactly one selector pair: the kernel's transport-mode SA holds one selector (LL-XFRM-STATE-ONE-SELECTOR), and one wide enough for several pairs would admit traffic that no pair negotiated. So ze config verify and ze config commit refuse a transport-mode peer that configures more than one traffic-selector entry: keep one entry, or set mode tunnel. The far end can still propose several pairs. As responder Ze answers such a proposal with the first one. As initiator it refuses an answer of several pairs and deletes the SA, so configure one selector on the far end too.

A tunnel-mode peer's vti { bind <name> } names an interface { xfrm <name> { if-id } } block. The Child SA is installed with that interface's if_id, so the tunnel's traffic enters and leaves through the named interface and the interface's MTU is the tunnel's. The interface has to exist when the peer's first Child SA is created: a binding that names no xfrm interface, or one configured with if-id 0, fails the Child SA with an error naming the interface. show mtu reports whether that interface's MTU fits the measured path (docs/architecture/diagnostics/path-mtu.md).

A peer that declines the request establishes the Child SA in tunnel mode. Set transport-required true when that downgrade is unacceptable: Ze then deletes the SA instead, which is what Section 1.3.1 asks of an initiator. It defaults to false, so a peer without transport mode keeps a working tunnel.

Transport mode behind a NAT

Transport mode works across an address-translating NAT, on both roles, and it needs no extra configuration. Write the addresses each end's own stack holds in local-address, local-id and the local half of every traffic-selector, and write the address you DIAL in remote-address, remote-id and the remote half. A respond peer writes the address it SEES the far end at, which is the translated one, because Ze accepts an unsolicited IKE_SA_INIT only from the configured remote-address.

Ze then substitutes the selector addresses for you. RFC 7296 Section 2.23.1 requires it: the peer answers in the addresses ITS stack sees, and those exist on neither node. Ze replaces them with the addresses it observed, so the policy it programs matches the packets its own kernel handles. This is the one place where the selectors on the wire and the selectors in show vpn ipsec sa differ, and the command reports what was programmed.

show vpn ipsec sa names which side is translated. nat-detected says a NAT is on the path, behind-nat says this node's own address was translated, and peer-behind-nat says the far end's was. Both can be true at once. A transport tunnel that does not come up behind a NAT is diagnosed with those three fields first: all false means the peer sent no NAT_DETECTION notification, which no conforming IKEv2 implementation omits.

The command shows both selector pairs, so you can see the substitution rather than infer it. original-tsi and original-tsr are the addresses the peer put on the wire, and ts-local and ts-remote inside child-sa are the addresses the kernel programs. On a tunnel-mode peer, and on any peer that never negotiated transport mode, the two original fields are null.

Tunnel mode across the same NAT is unaffected. Section 2.23.1 governs transport mode alone, so a tunnel-mode Child SA negotiates the selectors you configured, untouched.

The VPP dataplane backend does not implement transport mode. It refuses a transport-mode install with a clear error rather than programming a tunnel-mode entry and reporting success. The SA path and the policy path each refuse it on their own.

The VPP dataplane backend cannot be driven by IKE, and no configuration selects it. It installs security associations, and it refuses every security policy the IKE engine produces for them. VPP has no node-wide policy database: a policy lives in a security policy database that acts only on the interfaces it is bound to, and nothing tells the backend which interface to use. The backend is reached only through a private test override, it is compiled in only with the ze_vpp build tag, and no test has sent ESP through it. Use the XFRM backend, which is the default and the production path.

PKI certificate store

The pki { } block stores X.509 certificates, private keys, CA certificates, and the certificate revocation lists each CA published. A ca entry holds a CA certificate and its crl list; a certificate entry holds its certificate, its intermediate list and an optional private { key }. Each value is written inline in the config, not read from a file, and is validated at commit time. The key leaf accepts PKCS8, SEC1 and PKCS1 encodings, and IKEv2 signs with RSA, ECDSA, Ed25519 and Ed448 keys (Ed25519 and Ed448 only for a peer that announces RFC 8420's Identity hash). An Ed448 key is read from its PKCS8 encoding, and its certificate must come from a CA that does not itself sign with Ed448. The PKI store also serves TLS certificates for the web UI and gRPC API.

Health monitoring reports certificate expiry as a warning at 30 days and an error after expiry. Prometheus exposes ze_pki_certificate_expiry_seconds and ze_pki_certificate_valid.

XFRM interfaces

XFRM interfaces provide route-based IPsec. Traffic routed through the XFRM interface is encrypted, and incoming traffic is decrypted before it appears on the interface. The generated configuration reference documents the interface surface.

Reading the kernel dataplane

Every other IPsec command reports what the IKE engine believes it installed. The show vpn ipsec dataplane commands read the kernel instead. Three failures become visible: a state the kernel refused, a state it expired, and a policy that outlived its owner.

Command What it reads
show vpn ipsec dataplane sa [spi <spi>] The Security Association Database: SPI, addresses, if-id, mode, algorithms, replay window, byte and packet counters, timestamps, and the df-bit, dscp-map and icmp-error-check the SA holds. spi <spi> selects every matching SPI, which can occur under different destinations or interfaces. SPI 0 is refused under RFC 4303 Section 2.1
show vpn ipsec dataplane policy The Security Policy Database: selector prefixes and ports, direction, priority, upper-layer protocol, if-id, if-index, tunnel endpoints, and the peer that installed each policy. spd names the SPD holding the policy (node for if-id 0, the XFRM interface a peer binds with vti bind, or if-id <n> for one no bound interface has), and role names the job Ze installed it for (catch-all, interface-catch-all, interface-exemption, ike-bypass, child-sa, operator, ospf). A policy Ze did not install reports its owner and its role as unknown
show vpn ipsec dataplane drift Each expected Child SA identity absent from the kernel. The command exits non-zero when it finds drift, so a script can test it

RFC 4301 Section 4.4 keeps the SPD and the SAD separate, and so does this command tree.

Each SA row also carries the options the SA holds, read back from the kernel, never from the config: df-bit (copy or clear, RFC 4301 Section 8.1), dscp-map (copy, or the fixed outer DSCP as a decimal value, Section 5.1.2.1) and icmp-error-check (true or false, Section 6.2). On Linux they come from the state's XFRM_STATE_NOPMTUDISC, XFRM_SA_XFLAG_DONT_ENCAP_DSCP and XFRM_STATE_ICMP flags. The row says what the kernel does, which can differ from the config: the kernel clears the DF bit of an IPv4 outbound SA whenever net.ipv4.ip_no_pmtu_disc is set, and the row then reads df-bit clear. A backend that cannot read them back sets options-known: false and the three keys to null.

An SA row's direction is in or out only when the kernel recorded one for the state (its XFRMA_SA_DIR attribute), and unknown otherwise. A known direction nulls the options that side cannot carry: an in row shows df-bit and dscp-map as null, an out row shows icmp-error-check as null. Ze installs its states without a direction, so its own rows read unknown and show all three options as the kernel holds them.

Each policy row carries icmp-error-return (true or false): whether the kernel may send an outbound ICMP error that no SA and no entry carries through the SA this entry resolves to, the RFC 4301 Section 6.2 mapping. On Linux it is the policy's XFRM_POLICY_ICMP flag, which Ze sets on the outbound policy of a peer with icmp-error-check true.

A read that cannot happen is an error, never an empty table. No backend loaded, a backend that cannot enumerate, and a process without CAP_NET_ADMIN each get their own message. An empty table answers "is my tunnel programmed?" with "no", and that is the wrong answer when the truth is that nobody asked the kernel.

Drift compares expected SA identities: SPI, destination, protocol, and XFRM interface ID. Extra kernel SAs are permitted during rekey. RFC 7296 Section 2.8 permits the old and new Child SAs to coexist until cleanup.

show vpn ipsec sa and show vpn ipsec peer name <name> carry the kernel counters in each child SA object: bytes-in, packets-in, bytes-out, and packets-out. They come from the kernel because the IKE engine never sees ESP payload. A failed or changing observation sets counters-known: false and all counters to null. A stable SAD read sets counters-known: true; a missing SA then has null counters, while an SA that carried no traffic has numeric zero counters.

The health registry uses the same observation. A missing expected Child SA reports degraded and names the peer. An unreadable or changing observation also reports degraded, with an unknown-dataplane diagnosis.

IPsec is an enrolled kernel capability. When the configuration installs a Security Association and the kernel holds no XFRM dataplane, ze doctor reports doctor-ipsec-xfrm-unavailable as an ERROR, ze refuses to start with the same message and exit 1, and ze config validate fails. There is no override: a daemon that negotiates a tunnel and encrypts nothing is the hazard this removes.

The probe opens the XFRM netlink socket, which needs no CAP_NET_ADMIN, and it reports absence only for the errno that means the kernel carries no XFRM protocol. Every other failure, a permission denial included, is doctor-ipsec-xfrm-unknown at warning severity and ze still starts: no kernel rebuild fixes a privilege fault.

An empty vpn { ipsec { } } block installs no Security Association, so it is not IPsec in use. It gates nothing, warns about no kernel module, and binds no IKE listener.

doctor-ipsec-udp-encap is an error, and it covers a NAT-T socket that would not bind as well as one the kernel will not decapsulate through. Both leave a tunnel that establishes and carries no traffic.

CLI

Command Description
show vpn ipsec status Tunnel and peer status summary
show vpn ipsec sa Active IKE and Child SAs, including algorithms, kernel byte and packet counters, rekey timers, SPIs, NAT detection, and initiator role
show vpn ipsec peer name <name> Detail for one configured peer
show vpn ipsec dataplane sa [spi <spi>] The SAs the kernel holds. See Reading the kernel dataplane
show vpn ipsec dataplane policy The policies the kernel holds
show vpn ipsec dataplane drift Child SAs the engine expects that the kernel does not hold. Exits non-zero on drift
clear vpn ipsec sa all, clear vpn ipsec sa peer <name> Tear down and re-establish every SA, or one peer's. The bare clear vpn ipsec sa is refused and names both forms
monitor vpn ipsec Stream sa-up, sa-down, child-up, child-down, and child-rekey lifecycle events
show pki certificates List loaded certificates with expiry information

When scripting these commands with | json, decode the rendered answer rather than the handler's internal wrapper. The JSON formatter unwraps a single-key object whose value is an array:

Command with | json JSON shape
show vpn ipsec sa Array of SA records; [] when none exist
show vpn ipsec dataplane sa Array of kernel SA records; [] when none exist
show vpn ipsec dataplane drift [] when there is no drift; drift is a command error
show vpn ipsec peer name <name> Object with peer-name and the ike-sas array
show log recent level warn Object with count and the entries array, including each entry's structured attributes
clear vpn ipsec sa peer <name> Object with action: "clear-peer" and peer

The live demonstration validator uses these same rendered shapes for its absence, negotiation, kernel and refusal-log checks.

show vpn ipsec sa also reports peer-window-size, the number of outstanding requests the peer promised in its SET_WINDOW_SIZE notification. Zero means the peer sent none, which RFC 7296 Section 2.3 reads as a window of one. Ze holds one request outstanding and accepts exactly one request id.

The child-sa object of show vpn ipsec sa describes the Child SA as installed. esp-encryption and esp-integrity name the proposal the peer accepted: with two proposals in the esp-group and a peer that accepts only the second, the payload names the second. If Ze cannot resolve that proposal's transforms, which only a Ze defect produces, esp-integrity is absent and esp-transform-error says why. mode is tunnel or transport, udp-encapsulation says the SA receives ESP inside UDP on the ports the IKE SA uses: Ze's NAT-T port (4500) and the port the peer's authenticated IKE traffic comes from, which a NAT may have translated to any port, and remote-address is the endpoint the SA was installed on, which behind a NAT differs from the configured remote-address of the peer. Those three, with the transform, are what size an ESP packet on the tunnel.

Both clear vpn ipsec sa forms send a best-effort encrypted IKE Delete before removing local state. Initiator peers then re-establish immediately. If the UDP Delete is lost, the normal DPD path still removes the stale remote SA.

Health and metrics

The IPsec component registers with the health registry. It reports healthy when all configured tunnels are established, degraded when some are down, and down when critical tunnels fail.

Prometheus exposes ze_ipsec_sa_count, ze_ipsec_tunnel_up{peer}, ze_ipsec_tunnel_degraded{peer}, and ze_ipsec_rekey_total{peer}.

ze_ipsec_error_notify_sent_total{type,protected} counts error notifications Ze sent, by notify type and by whether the carrying message was encrypted. ze_ipsec_error_notify_suppressed_total{reason} counts the ones a guard stopped, by the name of that guard. Four reasons count IKE messages that failed their integrity check, which Ze drops without answering and without changing the SA (RFC 7296 Section 2.4): handshake-unauthenticated during the IKE_AUTH exchange, in either role; established-unauthenticated on an established SA; invalid-msgid-unauthenticated for an out-of-window request on an established SA; and held-successor-decrypt-failed on a re-authenticated IKE SA held before adoption. A rising count means someone is sending datagrams under the SPIs of a live SA, or a path is damaging them. ze doctor warns under ipsec-unauthenticated-input for each peer whose handshake in progress dropped such a message, naming the peer, how many were dropped and the handshake state. The handshake keeps waiting for the peer's genuine answer, so the tunnel comes up late or not at all while the forgeries win the race. The warning clears when the handshake establishes or a new attempt starts. ze doctor also warns under ipsec-peer-malformed-message for each peer whose live IKE SA received messages that passed their integrity check and do not parse. Only the peer can build such a message, so the defect is in the peer's IKE software: Ze drops it and keeps the SA, but the exchange it carried is lost. Collect the peer's log and report it to the peer's vendor.

Three more counters report the COOKIE challenge described under Denial-of-service protection. ze_ipsec_cookie_challenges_total{peer} counts the challenges Ze issues, ze_ipsec_cookie_verify_failures_total{peer} counts inbound cookies that did not verify, and ze_ipsec_sa_init_retries_total{peer,cause} counts the IKE_SA_INIT retries Ze sends, labeled cookie or invalid-ke-payload. A rising verify-failure count is either an attacker probing the half-open slot or a secret rotation catching an in-flight challenge. A rising retry count on the cookie cause is the signature of the forged-notify flood RFC 7296 Section 2.6 describes.

Two more gauges report kernel state. ze_ipsec_dataplane_sa_count{if_id} counts SAs under each interface ID used by an installed Child SA. ze_ipsec_dataplane_drift{peer} reads 1 when the kernel lacks an expected SA identity. Kernel expiry or an external flush can produce drift while ze_ipsec_tunnel_up still reports a successful install.

ze_ipsec_virtual_ip_leases{pool} counts the virtual IP addresses live IKE SAs hold in each remote-access pool. ze doctor warns under ipsec-virtual-ip-pool when one family of a pool is at least 90% held, because a full pool refuses the next client with INTERNAL_ADDRESS_FAILURE; widen range or range6, or bind some peers to another pool.

A failed or changing dataplane observation removes both gauge families' previous series. Absent series mean the observation is unknown, not that the kernel holds no SAs or that no drift exists. Peer removal also removes the peer's drift series and unused interface-ID series.

ze_ipsec_tunnel_up reads 1 only when the IKE SA is established and the Child SA is installed in the dataplane. A tunnel whose ESP install the kernel refused reads ze_ipsec_tunnel_up 0 and ze_ipsec_tunnel_degraded 1. Such a tunnel has a live control plane and carries no encrypted traffic. Alert on the degraded gauge, because the two gauges together separate a lost session from a session with no ESP.

The daemon logs child-sa: dataplane refused the ESP state, tunnel is degraded and carries no encrypted traffic when this happens.

Interop testing

The IKE implementation includes interop tests against strongSwan 6.1.0, built from the upstream release on Alpine 3.24.3 (test/interop-ipsec/Dockerfile.strongswan). The infrastructure in test/interop-ipsec/ drives strongSwan containers as remote IKE peers. The scenarios cover:

Area Scenarios
Authentication PSK, EAP-MSCHAPv2, EAP-TLS, and EAP-TLS over TLS 1.3
Ze as responder PSK, EAP-MSCHAPv2, EAP-TLS over TLS 1.3, IKE SA rekey started by strongSwan, and a fresh IKE_SA_INIT accepted beside an established SA
Rekey and teardown Child SA rekey with make-before-break, clear vpn ipsec sa and re-establishment, and a Delete sent while the one request window is held
Negotiation The INVALID_KE_PAYLOAD retry and the COOKIE challenge
Dataplane A live Child SA whose peer changes ESP form mid-session, BGP routes exchanged with FRR over the tunnel, and IPv6 carried inside an IPv4 Child SA on an xfrm interface after strongSwan narrows a two-family proposal to ::/0 (vti-ipv6-inner-ipv4-outer)
NAT traversal Transport mode and tunnel mode with ESP in UDP 4500, each measuring what Ze's stack does with the inner TCP and UDP checksum after decapsulation (RFC 3948 Section 3.1.2)
MOBIKE mobike-initiator and mobike-responder remove the mobile peer's original outer address, retain the same IKE and Child SPIs, and require encrypted traffic in both directions after migration
Traffic selectors Child SA rekey narrowing, an answer that narrows the initiator's proposal, ESN offered both ways, and a peer reload that narrows

There is no certificate-only (mode x509) scenario. The certificate paths are proven by unit tests and by the EAP-TLS scenarios, which authenticate both ends with certificates.

rfc/short/rfc7296.md records the extracted requirements and their tagged-test status. Those unit checks and the independent-peer scenarios cover different boundaries; neither is a claim that every IKE extension is implemented.

See also

A WAN address that comes and goes

A CPE often dials its tunnel from a PPPoE or DHCP WAN whose address does not exist at boot and can change on every reconnect. Ze follows it.

You write Local address of a peer that names no local-address
vpn ipsec interface <name> The interface's first IPv4 address, followed as it changes
Neither interface nor local-address The source address the route to the remote selects, looked up at the start of every connection attempt

With interface set:

  • At boot with no address yet, Ze warns, starts the peers that carry their own local-address, and holds the others. ze doctor reports each waiting peer (check ipsec-interface-address).
  • When the address appears, the waiting peers start from it.
  • When it changes, those peers restart from the new address, and their old Child SAs are removed.
  • When it leaves, those peers stop, remove their Child SAs, and wait.
  • A peer with its own local-address has its own socket and is never restarted by any of this.

Ze hears these changes from the kernel's interface address table, so it follows the interface whether or not the configuration has an interface block for it, and also when the interface does not exist yet at boot.

An interface that is deleted, as ppp0 is when a PPPoE session ends, holds no address: its peers stop and wait exactly as when the address leaves, and start again when the interface returns with an address. Ze logs one warning when the interface goes missing, not one for every address change while it stays missing. A read of the interface that fails for another reason (a netlink error) is not taken as absence: the running peers are kept, and Ze logs a warning.

A reload whose interface has no IPv4 address is still refused: an address that arrives later is followed without a commit.

local-address takes an IP address and nothing else. local-address any is refused; leave the leaf out instead.

remote-address may be a DNS name. It is resolved at the start of every connection attempt: a name that does not resolve yet is retried with the reconnect backoff (1 s, doubling to 60 s, never giving up), and the address it resolves to is the one NAT detection, the Child SA and transport mode use. A respond peer configured by name accepts an initiation from any address the name resolved to at the last refresh (every 60 s and after each commit); an incoming packet never causes a DNS query.

On a host with several addresses, the route-chosen source is also the address replies to an initiating peer leave from, which is not always the address the request reached (RFC 7296 Section 2.11; tracked by plan/release/fixes/spec-rfcgate-1b-rfc7296-pilot-deferred-ike-source-address.md).