ipsec

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

Ze implements native IKEv2 in Go for route-based IPsec VPN tunnels. No strongSwan, no libreswan, no external IKE daemon. The IKE engine, the cryptographic primitives, the wire codec, and the XFRM dataplane integration are all in-tree. The result is a single binary that negotiates IKE SAs, installs XFRM policies and states, and programs routes through XFRM interfaces, all driven from the same YANG config tree as every other Ze subsystem.

Architecture

The IPsec stack is split across several packages:

Package	Role
internal/component/ike/wire	IKEv2 wire format codec (RFC 7296). Encodes and decodes all payload types.
internal/component/ike/crypto	Cryptographic primitives: DH groups, PRF, integrity, encryption, key derivation.
internal/component/ike/transport	UDP transport with NAT-T (RFC 3948) keepalives, port 4500 encapsulation.
internal/component/ike/eap	EAP authentication: EAP-MSCHAPv2, EAP-TLS.
internal/component/ike/engine	IKE FSM: IKE_SA_INIT, IKE_AUTH, CREATE_CHILD_SA, INFORMATIONAL. Rekeying, DPD.
internal/component/ipsec	Config, YANG schema, validation, XFRM dataplane abstraction.
internal/component/pki	PKI certificate store for X.509 certificates and private keys.

Configuration

IPsec tunnels are configured under ipsec { } with IKE proposals, authentication, and child SA definitions.

pki {
    certificate my-cert {
        certificate-file /etc/ze/certs/router.pem;
        private-key-file /etc/ze/certs/router-key.pem;
    }
    ca-certificate my-ca {
        certificate-file /etc/ze/certs/ca.pem;
    }
}

ipsec {
    tunnel site-b {
        ike {
            version 2;
            proposal default {
                encryption aes256gcm16;
                dh-group   modp2048;
                prf        sha256;
            }
            remote-address 198.51.100.1;
            authentication {
                method certificate;
                certificate my-cert;
                ca-certificate my-ca;
            }
            dpd {
                interval 30;
                timeout  120;
            }
        }
        child default {
            esp-proposal {
                encryption aes256gcm16;
            }
            local-ts  10.0.0.0/24;
            remote-ts 10.1.0.0/24;
            start-action auto;
        }
    }
}

IKE features

Feature	Detail
IKEv2 (RFC 7296)	Full IKE_SA_INIT, IKE_AUTH, CREATE_CHILD_SA, INFORMATIONAL exchange support.
Proposals	AES-CBC, AES-GCM (128/256), ChaCha20-Poly1305. DH groups: MODP 2048/3072/4096/8192, ECP 256/384/521. PRF: SHA-256/384/512.
Authentication	X.509 certificates, EAP-MSCHAPv2, EAP-TLS. PSK is future work.
NAT-T (RFC 3948)	Automatic NAT detection, UDP encapsulation on port 4500, keepalive.
DPD	Dead Peer Detection via INFORMATIONAL exchange. Configurable interval and timeout.
Rekeying	IKE SA and Child SA rekeying with configurable lifetime. Collision handling.
MOBIKE (RFC 4555)	Address update on interface change for mobile/multihomed clients.
Virtual IP pool	Remote-access server assigns addresses from a configured pool.

Child SA and dataplane

Child SAs define the traffic selectors and the ESP proposal. Ze programs XFRM policies and states via netlink. Route-based IPsec uses XFRM interfaces (see Interfaces: XFRM).

Feature	Detail
ESP proposals	AES-GCM-16 (128/256), AES-CBC + HMAC-SHA-256/384/512.
Traffic selectors	IPv4 and IPv6 CIDR prefixes.
Start actions	auto (initiate immediately), route (initiate on first packet), none (wait for remote).
Replay protection	Anti-replay window (default 32).
Lifetime	Time-based and byte-based rekeying thresholds.

PKI certificate store

The pki { } block stores X.509 certificates, private keys, and CA certificates. Certificates are loaded from PEM files and validated at commit time. The PKI store also serves TLS certificates for the web UI and the gRPC API.

Health monitoring reports certificate expiry as warnings (30 days) and errors (expired). Prometheus metrics: ze_pki_certificate_expiry_seconds, ze_pki_certificate_valid.

XFRM interfaces

XFRM interfaces provide route-based IPsec. Traffic routed through the XFRM interface is encrypted; traffic arriving on it is decrypted. See Interfaces: XFRM for the config surface.

CLI

Command	Description
show ipsec tunnels	Tunnel status, SA state, traffic counters.
show ipsec sa	Active IKE and Child SA details.
clear ipsec tunnel <name>	Tear down and re-establish a tunnel.
show pki certificates	List loaded certificates with expiry.

Health and metrics

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

Prometheus metrics include SA state, rekey counts, and traffic counters.

Interop testing

The IKE implementation includes interop tests against strongSwan. The test infrastructure lives in test/ipsec/ and uses Docker containers with strongSwan as the remote IKE peer. Interop coverage includes EAP authentication (EAP-MSCHAPv2 and EAP-TLS) for road-warrior clients, validated against strongSwan as the EAP peer.

See also

• Interfaces: XFRM for XFRM interface configuration.
• PKI for certificate management.
• Health Checks for the health registry.
• Feature Inventory for the full capability list.