IKED.CONF(5)

📦
version 7.4 · 3 versions
, in debian trixie, fedora 43, fedora 44, ubuntu questing, ubuntu resolute, ubuntu stonking

okay so bestie, sit down, hydrate, because we're reading iked.conf(5) — File Formats Manual, section 5 — and it's literally the config file for iked(8). this is part one of a whole saga, so no skimming. 🫶

🌸 NAME 🌸

iked.conf — the IKEv2 configuration file. short, sweet, iconic. 💅

✨ DESCRIPTION ✨

iked.conf is the configuration file for iked(8), the Internet Key Exchange version 2 (IKEv2) daemon for IPsec. no cap, that's the whole job description.

IPsec itself is a pair of protocols, and they're kind of a duo:

  • Encapsulating Security Payload (ESP) — provides integrity and confidentiality 💖
  • Authentication Header (AH) — provides integrity ✨

The IPsec protocol itself is described in ipsec(4).

In its most basic form, a flow is established between hosts and/or networks, and then Security Associations (SA) are established, which detail how the desired protection will be achieved. IPsec uses flows to determine whether to apply security services to an IP packet or not. iked(8) is used to set up flows and establish SAs automatically, by specifying ikev2 policies in iked.conf (see "AUTOMATIC KEYING POLICIES", below). main character energy fr fr. 👑

Alternative methods of setting up flows and SAs are also possible using manual keying or automatic keying using the older ISAKMP/Oakley a.k.a. IKEv1 protocol. Manual keying is not recommended, but can be convenient for quick setups and testing. See ipsec.conf(5) and isakmpd(8) for more information about manual keying and ISAKMP support.

🙈 bestie, manual keying is the "not recommended but convenient for quick setups and testing" girlie of this whole file. we respect her, we don't date her.

🎀 IKED.CONF FILE FORMAT 🎀

iked.conf is divided into three main sections:

  • Macros — user-defined macros may be defined and used later, simplifying the configuration file. 🎀
  • Global Configuration — global settings for iked(8).
  • Automatic Keying Policies — policies to set up IPsec flows and SAs automatically.

Lines beginning with # and empty lines are regarded as comments, and ignored. Lines may be split using the \ character.

Argument names not beginning with a letter, digit, or underscore must be quoted.

Addresses can be specified in CIDR notation (matching netblocks), as symbolic host names, interface names, or interface group names.

Additional configuration files can be included with the include keyword, for example:

include "/etc/macros.conf"

Certain parameters can be expressed as lists, in which case iked(8) generates all the necessary flow combinations. For example:

ikev2 esp proto { tcp, udp } \
        from 192.168.1.1 to 10.0.0.18 \
        peer 192.168.10.1

🦋 MACROS 🦋

Macros can be defined that will later be expanded in context. Macro names must start with a letter, digit, or underscore, and may contain any of those characters. Macro names may not be reserved words (for example flow, from, esp). Macros are not expanded inside quotes. 💀

For example:

remote_gw = "192.168.3.12"
ikev2 esp from 192.168.7.0/24 to 192.168.8.0/24 peer $remote_gw

👑 GLOBAL CONFIGURATION 👑

Here are the settings that can be set globally:

  • set active — Set iked(8) to global active mode. In active mode the per-policy mode setting is respected. iked(8) will initiate policies set to active and wait for incoming requests for policies set to passive. This is the default.
  • set passive — Set iked(8) to global passive mode. In passive mode no packets are sent to peers and no connections are initiated by iked(8), even for active policies. This option is used for setups using sasyncd(8) and carp(4) to provide redundancy. iked(8) will run in passive mode until sasyncd has determined that the host is the master and can switch to active mode.
  • set couple — Load the negotiated security associations (SAs) and flows into the kernel. This is the default.
  • set decouple — Don't load the negotiated SAs and flows from the kernel.
⚠️ bestie, this mode is only useful for testing and debugging. do not make it your personality.
  • set dpd_check_interval time — Specify the liveness check interval, in seconds. Setting time to 0 disables DPD. The default value is 60 seconds. ⏰
  • set enforcesingleikesa — Allow only a single active IKE SA for each dstid. When a new SA with the same dstid is established, it replaces the old SA. one in, one out, periodt.
  • set noenforcesingleikesa — Don't limit the number of IKE SAs per dstid. This is the default.
  • set fragmentation — Enable IKEv2 Message Fragmentation (RFC 7383) support. This allows IKEv2 to operate in environments that might block IP fragments.
  • set nofragmentation — Disables IKEv2 Message Fragmentation support. This is the default.
  • set mobike — Enable MOBIKE (RFC 4555) support. This is the default. MOBIKE allows the peer IP address to be changed for IKE and IPsec SAs. Currently iked(8) only supports MOBIKE when acting as a responder.
  • set nomobike — Disables MOBIKE support.
  • set cert_partial_chain — Allow partial certificate chain if at least one certificate is a trusted CA from /etc/iked/ca/.
  • set ocsp URL [tolerate time [maxage time]] — Enable OCSP and set the fallback URL of the OCSP responder. This fallback will be used if the trusted CA from /etc/iked/ca/ does not have an OCSP-URL extension. The matching responder certificates have to be placed in /etc/iked/ocsp/responder.crt.

The optional tolerate parameter specifies how much the OCSP response attribute 'thisUpdate' may be in the future and how much 'nextUpdate' may be in the past, with respect to the local time. The optional maxage parameter specifies how much 'thisUpdate' may be in the past. If tolerate is set to 0 then the times are not verified at all. This is the default setting.

  • set vendorid — Send OpenIKED Vendor ID payload. This is the default.
  • set novendorid — Don't send a Vendor ID payload.
  • user name password — iked(8) supports user-based authentication by tunneling the Extensible Authentication Protocol (EAP) over IKEv2. In its most basic form, the users will be authenticated against a local, integrated password database that is configured with the user lines in iked.conf and the name and password arguments. The password has to be specified in plain text which is required to support different challenge-based EAP methods like EAP-MD5 or EAP-MSCHAPv2.
🚨 yes bestie, plain text. that is not a typo, that is required for those challenge-based EAP methods. protect that file like it's your last iced coffee. 😭

🌈 AUTOMATIC KEYING POLICIES 🌈

This section is used to configure policies that will be used by iked(8) to set up flows and SAs automatically. Some examples of setting up automatic keying:

# Set up a VPN:
# First between the gateway machines 192.168.3.1 and 192.168.3.2
# Second between the networks 10.1.1.0/24 and 10.1.2.0/24
ikev2 esp from 192.168.3.1 to 192.168.3.2
ikev2 esp from 10.1.1.0/24 to 10.1.2.0/24 peer 192.168.3.2

For incoming connections from remote peers, the policies are evaluated in sequential order, from first to last. The last matching policy decides what action is taken; if no policy matches the connection, the default action is to ignore the connection attempt or to use the default policy, if set. See the "EXAMPLES" section for a detailed example of the policy evaluation. ✨

The first time an IKEv2 connection matches a policy, an IKE SA is created; for subsequent packets the connection is identified by the IKEv2 parameters that are stored in the SA without evaluating any policies. After the connection is closed or times out, the IKE SA is automatically removed. it's giving self-cleaning. 💅

The commands are as follows:

  • ikev2 [name] — The mandatory ikev2 keyword will identify an IKEv2 automatic keying policy. name is an optional arbitrary string identifying the policy. The name should only occur once in iked.conf or any included files. If omitted, a name will be generated automatically for the policy.
  • [eval] — The eval option modifies the policy evaluation for this policy. It can be one of quick, skip or default. If a new incoming connection matches a policy with the quick option set, that policy is considered the last matching policy, and evaluation of subsequent policies is skipped. The skip option will disable evaluation of this policy for incoming connections. The default option sets the default policy and should only be specified once.
  • [mode] — mode specifies the IKEv2 mode to use: one of passive or active. When passive is specified, iked(8) will not immediately start negotiation of this tunnel, but wait for an incoming request from the remote peer. When active is specified, negotiation will be started at once. If omitted, passive mode will be used.
  • [ipcomp] — The keyword ipcomp specifies that ipcomp(4), the IP Payload Compression protocol, is negotiated in addition to encapsulation. The optional compression is applied before packets are encapsulated. IPcomp must be enabled in the kernel:
# sysctl net.inet.ipcomp.enable=1
  • [tmode] — tmode describes the encapsulation mode to be used. Possible modes are tunnel and transport; the default is tunnel.
  • [natt] — natt forces negotiation of NAT-Traversal after the initial handshake.
  • [encap] — encap specifies the encapsulation protocol to be used. Possible protocols are esp and ah; the default is esp.
  • [af] — This policy only applies to endpoints of the specified address family which can be either inet or inet6. This only matters for IKEv2 endpoints and does not restrict the traffic selectors to negotiate flows with different address families, e.g. IPv6 flows negotiated by IPv4 endpoints.
  • proto protocol / proto { protocol ... } — The optional proto parameter restricts the flow to a specific IP protocol. Common protocols are icmp(4), tcp(4), and udp(4). For a list of all the protocol name to number mappings used by iked(8), see the file /etc/protocols.

Multiple protocol entries can be specified, separated by commas or whitespace, if enclosed in curly brackets:

proto { tcp, udp }
  • rdomain number — Specify a different routing domain for unencrypted traffic. The resulting IPsec SAs will match outgoing packets in the specified rdomain number and move the encrypted packets to the rdomain the iked(8) instance is running in. Vice versa, incoming ipsec(4) traffic is moved to rdomain number after decryption.
  • from src [port sport] [(** *srcnat* **)] to dst [port dport] — Specify one or more traffic selectors for this policy which will be used to negotiate the IPsec flows between the IKEv2 peers. During the negotiation, the peers may decide to narrow a flow to a subset of the configured traffic selector networks to match the policies on each side.

Every traffic selector is gonna apply to packets where the source is <code>src</code> and the destination is <code>dst</code> — like, that's its whole job bestie. And if your <code>src</code> arg is a fictional source ID (iconic, honestly), then the <code>srcnat</code> parameter steps in to give the actual source address. This is the move for outgoing NAT/BINAT scenarios, which are described below, so don't stress. The keyword <code>any</code> will match any address at all (i.e. <code>0.0.0.0/0</code> and <code>::/0</code>) 💫. And if the config <code>address</code> option is specified, you can use the <code>dynamic</code> keyword to create flows from or to the dynamically assigned address. so cute.

The optional port modifiers restrict the traffic selectors to the specified ports. They are only valid in conjunction with the tcp(4) and udp(4) protocols — no tcp/udp, no port games, sorry babe 💅. Ports can be specified by number or by name. For a list of all port name to number mappings used by ipsecctl(8), see the file /etc/services. iykyk.

  • local localip peer remote — The <code>local</code> parameter specifies the address or FQDN of the local endpoint. Unless the gateway is multi-homed or uses address aliases, this option is generally not needed, fr. The <code>peer</code> parameter specifies the address or FQDN of the remote endpoint. For host-to-host connections where <code>dst</code> is identical to <code>remote</code>, this option is generally not needed either, because it will be set to <code>dst</code> automatically ✨. If it is not specified, or if the keyword <code>any</code> is given, the default peer is used.
  • ikesa auth algorithm enc algorithm prf algorithm group group — These parameters define the mode and cryptographic transforms to be used for the IKE SA negotiation, also known as phase 1 👑. The IKE SA will be used to authenticate the machines and to set up an encrypted channel for the IKEv2 protocol. Possible values for <code>auth</code>, <code>enc</code>, <code>prf</code>, <code>group</code>, and the default proposals are described below in “CRYPTO TRANSFORMS”. If omitted, iked(8) will use the default proposals for the IKEv2 protocol. The keyword <code>ikesa</code> can be used multiple times as a delimiter between IKE SA proposals — the order of the proposals depends on the order in the configuration. And the keywords <code>auth</code>, <code>enc</code>, <code>prf</code> and <code>group</code> can be used multiple times within a single proposal to configure multiple crypto transforms. stacking queen behavior.
  • childsa auth algorithm enc algorithm group group esn — These parameters define the cryptographic transforms for the Child SA negotiation, aka phase 2 🎀. Each Child SA will be used to negotiate the actual IPsec SAs. The initial Child SA is always negotiated with the initial IKEv2 key exchange; additional Child SAs may be negotiated with additional Child SA key exchanges for an established IKE SA. Possible values for <code>auth</code>, <code>enc</code>, <code>group</code>, <code>esn</code>, and the default proposals are described below in “CRYPTO TRANSFORMS”. If omitted, iked(8) will use the default proposals for the ESP or AH protocol. The <code>group</code> option will only be used to enable Perfect Forward Secrecy (PFS) for additional Child SA exchanges that are not part of the initial key exchange. The keyword <code>childsa</code> can be used multiple times as a delimiter between Child SA proposals, and the order depends on the order in the configuration. The keywords <code>auth</code>, <code>enc</code> and <code>group</code> can be used multiple times within a single proposal to configure multiple crypto transforms 💜.
  • srcid string dstid string — <code>srcid</code> defines an ID of type “FQDN”, “ASN1_DN”, “IPV4”, “IPV6”, or “UFQDN” that will be used by iked(8) as the identity of the local peer 🫶. Here's how it decides, no cap: if the argument is an email address (reyk@example.com), iked(8) will use UFQDN as the ID type. The ASN1_DN type will be used if the string starts with a slash ‘/’ (/C=DE/../CN=10.0.0.1/emailAddress=reyk@example.com). If the argument is an IPv4 address or a compressed IPv6 address, the ID types IPV4 or IPV6 will be used. And anything else is considered to be an FQDN. If <code>srcid</code> is omitted, the default is to use the hostname of the local machine — see hostname(1) to set or print the hostname. <code>dstid</code> is similar to <code>srcid</code>, but instead specifies the ID to be used by the remote peer. matching besties ✨
  • ikelifetime time — The optional <code>ikelifetime</code> parameter defines the IKE SA expiration timeout by the time SA was created ⏳. A zero value disables active IKE SA rekeying, and this is the default. The accepted format of the time specification is described below.
  • lifetime time [bytes bytes] — The optional <code>lifetime</code> parameter defines the Child SA expiration timeout by the time SA was in use and by the number of bytes that were processed using the SA. Default values are 3 hours and 4 gigabytes, which means that SA will be rekeyed before reaching the time limit, or 4 gigabytes of data will pass through. Zero values disable rekeying. Several unit specifiers are recognized (ignoring case): ‘m’ and ‘h’ for minutes and hours, and ‘K’, ‘M’ and ‘G’ for kilo-, mega- and gigabytes accordingly.
Rekeying must happen at least several times a day as IPsec security heavily depends on frequent key renewals. bestie please, do not skip this 😭🔐
  • [ikeauth] — Specify a method to be used to authenticate the remote peer. iked(8) will automatically determine a method based on public keys or certificates configured for the peer, but <code>ikeauth</code> can be used to override this behaviour 💅. Non-psk modes will require setting up certificates and RSA or ECDSA public keys; see iked(8) for more information. The default is to allow any signature authentication. Your options:
    • eap type — Use EAP to authenticate the initiator. The only supported EAP type is currently MSCHAP-V2. The responder will use RSA public key authentication.
    • ecdsa256 — Use ECDSA with a 256-bit elliptic curve key and SHA2-256 for authentication.
    • ecdsa384 — Use ECDSA with a 384-bit elliptic curve key and SHA2-384 for authentication.
    • ecdsa521 — Use ECDSA with a 521-bit elliptic curve key and SHA2-512 for authentication.
    • psk string — Use a pre-shared key string or hex value (starting with 0x) for authentication.
    • psk file path — Use a pre-shared hex key (without leading 0x) read from path for authentication.
    • rfc7427 — Only use RFC 7427 signatures for authentication. RFC 7427 signatures currently only support SHA2-256 as the hash.
    • rsa — Use RSA public key authentication with SHA1 as the hash.
  • config option address / request option address — Request or serve one or more optional configuration payloads (CP) 🧚. The configuration <code>option</code> can be one of the following, with the expected address format:
    • address address — Assign a static address on the internal network.
    • address address/prefix — Assign a dynamic address on the internal network. The address will be assigned from an address pool with the size specified by prefix.
    • netmask netmask — The IPv4 netmask of the internal network.
    • name-server address — The DNS server address within the internal network.
    • netbios-server address — The NetBIOS name server (WINS) within the internal network. This option is provided for compatibility with legacy clients 🫡.
    • dhcp-server address — The address of an internal DHCP server for further configuration.
    • protected-subnet address/prefix — The address of an additional IPv4 or IPv6 subnet reachable over the gateway. This option is used to notify the peer of a subnet behind the gateway (that might require a second SA). Networks specified in this SA's "from" or "to" options do not need to be included.
    • access-server address — The address of an internal remote access server.
  • iface interface — Enable automatic network configuration as initiator. Received addresses, routes and nameservers will be installed on the specified interface ✨.
  • tag string — Add a pf(4) tag to all packets of IPsec SAs created for this connection 🏷️. This will allow matching packets for this connection by defining rules in pf.conf(5) using the tagged keyword. The following variables can be used in tags to include information from the remote peer at runtime:
    • $id — The <code>dstid</code> that was proposed by the remote peer to identify itself. It will be expanded to id-value, e.g. FQDN/foo.example.com. To limit the size of the derived tag, iked(8) will extract the common name ‘CN=’ from ASN1_DN IDs, for example ASN1_ID//C=DE/../CN=10.1.1.1/.. will be expanded to 10.1.1.1.
    • $eapid — For a connection using EAP, the identity (username) used by the remote peer.
    • $domain — Extract the domain from IDs of type FQDN, UFQDN or ASN1_DN.
    • $name — The name of the IKEv2 policy that was configured in iked.conf or automatically generated by iked(8).

For example, if the ID is FQDN/foo.example.com or UFQDN/user@example.com, “ipsec-$domain” expands to “ipsec-example.com” 💖. The variable expansion for the tag directive occurs only at runtime (not when the file is parsed) and must be quoted, or it will be interpreted as a macro. so don't forget the quotes bestie, I'm begging 🙈.

  • tap interface — Send the decapsulated IPsec traffic to the specified enc(4) interface instead of enc0 for filtering and monitoring 👀.
The traffic will be blocked if the specified interface does not exist. like, fully blocked. no interface, no vibes 💀

Okay bestie, so here's the part where we talk about making the firewall actually cooperate and also all the crypto math you're gonna be picking from. Strap in. 💖

✨ PACKET FILTERING ✨

So here's the tea: IPsec traffic shows up unencrypted on the enc(4) interface, which means you can filter it like normal with the OpenBSD packet filter, pf(4). The grammar for that whole situation lives in pf.conf(5). 🎀

These are the components that actually matter when you're filtering IPsec traffic:

  • external interface — the interface for IKE traffic and encapsulated IPsec traffic.
  • proto udp port 500 — IKE traffic on the external interface.
  • proto udp port 4500 — IKE NAT-Traversal traffic on the external interface.
  • proto ah | esp — encapsulated IPsec traffic on the external interface.
  • enc0 — the default interface for outgoing traffic before it's been encapsulated, and incoming traffic after it's been decapsulated. State on this interface should be interface bound; go read enc(4) for more.
  • proto ipencap — [tunnel mode only] IP-in-IP traffic flowing between gateways on the enc0 interface.
  • tagged ipsec-example.org — match traffic of IPsec SAs using the tag keyword.

If your filtering rules block everything by default, this rule right here makes sure IPsec traffic never even touches the packet filtering engine, so it just gets passed:

set skip on enc0

In the next example, all traffic is blocked by default, but IPsec-related traffic from gateways {192.168.3.1, 192.168.3.2} and networks {10.0.1.0/24, 10.0.2.0/24} is allowed through. She's thorough, she's organized, she's slaying. 💅

block on ix0
block on enc0

pass  in on ix0 proto udp from 192.168.3.2 to 192.168.3.1 \
        port {500, 4500}
pass out on ix0 proto udp from 192.168.3.1 to 192.168.3.2 \
        port {500, 4500}

pass  in on ix0 proto esp from 192.168.3.2 to 192.168.3.1
pass out on ix0 proto esp from 192.168.3.1 to 192.168.3.2

pass  in on enc0 proto ipencap from 192.168.3.2 to 192.168.3.1 \
        keep state (if-bound)
pass out on enc0 proto ipencap from 192.168.3.1 to 192.168.3.2 \
        keep state (if-bound)
pass  in on enc0 from 10.0.2.0/24 to 10.0.1.0/24 \
        keep state (if-bound)
pass out on enc0 from 10.0.1.0/24 to 10.0.2.0/24 \
        keep state (if-bound)

Now pf(4) can also filter IPsec-related packets based on an arbitrary tag that you specify inside a ruleset. The tag is basically an internal little marker you can use to identify those packets later on. Why would you care? Well bestie, it's lowkey helpful when users are connecting in from all different IP addresses, or when you wanna do queue-based bandwidth control, because the enc0 interface does not support it. 😭

This pf.conf(5) fragment uses queues for all IPsec traffic, with special handling for the developers and the employees:

queue std on ix0 bandwidth 100M
queue   deflt parent std bandwidth 10M default
queue   developers parent std bandwidth 75M
queue   employees parent std bandwidth 5M
queue   ipsec parent std bandwidth 10M

pass out on ix0 proto esp set queue ipsec

pass out on ix0 tagged ipsec-developers.example.com \
        set queue developers
pass out on ix0 tagged ipsec-employees.example.com \
        set queue employees

And this next one assigns those tags in the iked.conf configuration and sets an alternative enc(4) device at the same time. Two birds, one iconic stone. 🦋

ikev2 esp from 10.1.1.0/24 to 10.1.2.0/24 peer 192.168.3.2 \
        tag "ipsec-$domain" tap "enc1"

🌸 OUTGOING NETWORK ADDRESS TRANSLATION 🌸

Sometimes your network topology is just like that, and you genuinely want to do NAT on the traffic leaving through the VPN tunnel. To make that happen, you use the src argument to negotiate the desired network ID with the peer, and the srcnat parameter defines the true local subnet so a correct SA can get installed on the local side. ✨

Say the local subnet is 192.168.1.0/24 and you want all traffic headed for one specific VPN peer to look like it's coming from 10.10.10.1. Then you'd write:

ikev2 esp from 10.10.10.1 (192.168.1.0/24) to 192.168.2.0/24 \
        peer 10.10.20.1

Naturally you need a relevant NAT rule in pf.conf(5) too — can't skip that step, bestie. For the example above, it would be:

match out on enc0 from 192.168.1.0/24 to 192.168.2.0/24 \
        nat-to 10.10.10.1

From the peer's point of view, the local end of the VPN tunnel is declared to be 10.10.10.1 and all the traffic arrives with that source address. Consistent. Clean. Chef's kiss. 👑

🔥 CRYPTO TRANSFORMS 🔥

Okay this is the menu, and you get to order. Here's what you can pick from. 💅

These authentication types are permitted with the auth keyword:

Authentication    Key Length    Truncated Length    Default
hmac-md5          128 bits      96 bits
hmac-sha1         160 bits      96 bits             x
hmac-sha2-256     256 bits      128 bits            x
hmac-sha2-384     384 bits      192 bits            x
hmac-sha2-512     512 bits      256 bits            x

These pseudo-random function types are permitted with the prf keyword:

PRF              Key Length    Default
hmac-md5         128 bits                 [IKE only]
hmac-sha1        160 bits      x          [IKE only]
hmac-sha2-256    256 bits      x          [IKE only]
hmac-sha2-384    384 bits      x          [IKE only]
hmac-sha2-512    512 bits      x          [IKE only]

These cipher types are permitted with the enc keyword:

Cipher               Key Length    Default
3des                 168 bits      x
aes-128              128 bits      x
aes-192              192 bits      x
aes-256              256 bits      x
aes-128-ctr          160 bits                 [ESP only]
aes-192-ctr          224 bits                 [ESP only]
aes-256-ctr          288 bits                 [ESP only]
aes-128-gcm          160 bits      x
aes-192-gcm          224 bits                 [ESP only]
aes-256-gcm          288 bits      x
aes-128-gcm-12       160 bits                 [IKE only]
aes-256-gcm-12       288 bits                 [IKE only]
blowfish             160 bits                 [ESP only]
cast                 128 bits                 [ESP only]
chacha20-poly1305    288 bits                 [ESP only]

And these cipher types give you only authentication, not encryption. Not a typo, not a vibe, that's literally what they do. 🙈

aes-128-gmac         160 bits                 [ESP only]
aes-192-gmac         224 bits                 [ESP only]
aes-256-gmac         288 bits                 [ESP only]
null                                          [ESP only]

The Extended Sequence Numbers option can be turned on or off with the esn or noesn keywords:

ESN      Default
esn      x          [ESP only]
noesn    x          [ESP only]
Important, bestie: transforms followed by [IKE only] can only be used with the ikesa keyword, and transforms with [ESP only] can only be used with the childsa keyword. Don't mix them up or it's gonna be a whole thing. 💀

Also! Using AES-GMAC or NULL with ESP will only provide authentication. This is useful in setups where AH cannot be used, e.g. when NAT is involved. NAT girlies, this one's for you. 🫶

These group types are permitted with the group keyword:

Name              Group   Size     Type          Default
modp768           grp1    768      MODP                    [insecure]
modp1024          grp2    1024     MODP          x         [weak]
modp1536          grp5    1536     MODP          x         [weak]
modp2048          grp14   2048     MODP          x
modp3072          grp15   3072     MODP          x
modp4096          grp16   4096     MODP          x
modp6144          grp17   6144     MODP
modp8192          grp18   8192     MODP
ecp256            grp19   256      ECP           x
ecp384            grp20   384      ECP           x
ecp521            grp21   521      ECP           x
ecp192            grp25   192      ECP
ecp224            grp26   224      ECP
brainpool224      grp27   224      ECP
brainpool256      grp28   256      ECP
brainpool384      grp29   384      ECP
brainpool512      grp30   512      ECP
curve25519        grp31   256      Curve25519    x
sntrup761x25519           1190 B   Hybrid PQKE

The currently supported group types are either MODP (exponentiation groups modulo a prime), ECP (elliptic curve groups modulo a prime), or Curve25519. And listen — MODP groups of less than 2048 bits are considered weak or insecure (see RFC 8247 section 2.4) and are only provided for backwards compatibility. Do not pick those, bestie, I'm begging. 😭

🎀 FILES 🎀

  • /etc/iked.conf
  • /etc/examples/iked.conf

💅 EXAMPLES 💅

Okay bestie, this is the part where it all comes together. Four whole setups, real-world vibes, no cap. Let's go ✨

🎀 Example 1: The Gateway / Responder Glow-Up

So picture this: you got a server and your clients are connecting to iked(8) like it's an IPsec gateway — aka an IKEv2 responder — and they're doing mutual public key authentication plus an extra challenge-based EAP-MSCHAPv2 password authentication round. Extra security, extra slay 🫶

      user "test" "password123"

      ikev2 "win7" esp \
              from dynamic to 172.16.2.0/24 \
              peer 10.0.0.0/8 local 192.168.56.0/24 \
              eap "mschap-v2" \
              config address 172.16.2.1 \
              tag "$name-$id"

Not me giving the user "test" a password of "password123" 💀 bestie please change that before you ship it, iykyk.

🌸 Example 2: The Pre-Shared Key Classic

Next up: peers authenticate with a pre-shared key, and that key is 'foobar'. Iconic. Timeless. Slightly chaotic 🔥

      ikev2 "big test" \
              esp proto tcp \
              from 10.0.0.0/8 port 23 to 20.0.0.0/8 port 40 \
              from 192.168.1.1 to 192.168.2.2 \
              peer any local any \
              ikesa \
                      enc aes-128-gcm \
                      group ecp256 group curve25519 \
              ikesa \
                      enc aes-128 auth hmac-sha2-256 \
                      group ecp256 group curve25519 \
              childsa enc aes-128-gcm \
              childsa enc aes-128 auth hmac-sha2-256  \
              srcid host.example.com \
              dstid 192.168.0.254 \
              psk "foobar"

Look at all those ikesa and childsa blocks — she's giving multi-proposal main character energy 🌈

🦋 Example 3: The Last-Matching-Policy Situation

This one is chef's kiss for understanding how incoming connections get sorted on an IKEv2 gateway. The tea ☕:

  • Peer 192.168.1.34 will always match the first policy — because of the quick keyword, bestie. quick says "nope, we stop here, this is the one" 💅
  • Connections from peers 192.168.1.3 and 192.168.1.2 get matched by one of the last two policies.
  • Any other connection from 192.168.1.0/24 gets matched by the 'subnet' policy.
  • And literally anything else? Caught by the 'catch all' policy. She's the safety net 🫶
      ikev2 quick esp from 10.10.10.0/24 to 10.20.20.0/24 \
              peer 192.168.1.34
      ikev2 "catch all" esp from 10.0.1.0/24 to 10.0.2.0/24 \
              peer any
      ikev2 "subnet" esp from 10.0.3.0/24 to 10.0.4.0/24 \
              peer 192.168.1.0/24
      ikev2 esp from 10.0.5.0/30 to 10.0.5.4/30 peer 192.168.1.2
      ikev2 esp from 10.0.5.8/30 to 10.0.5.12/30 peer 192.168.1.3

Order matters SO much here, and the way that last-match wins unless you slap quick on it? That's the whole plot twist 🎀

🧚 Example 4: GRE Tunnel, Transport Mode, FQDN Auth

Last one, and she's fancy. This encrypts a gre(4) tunnel going from local machine A at 2001:db8::aa:1 all the way over to peer D at 2001:db8::dd:4, using FQDN-based public key authentication. And the reason we're in transport mode? Because it avoids double encapsulation, periodt ✨

      ikev2 transport \
              proto gre \
              from 2001:db8::aa:1 to 2001:db8::dd:4 \
              peer D.example.com

IPv6 addresses, GRE, FQDN peers — she ate and left no crumbs 👑

👀 SEE ALSO 👀

Go read these next, bestie, they're the whole friend group:

📜 HISTORY 📜

The iked.conf file format first appeared in OpenBSD 4.8. Baby's first appearance, and look at her now 🥹

💖 AUTHORS 💖

The iked(8) program was written by Reyk Floeter <reyk@openbsd.org>. Thank you for your service, king 🫡👑

That's the whole page, bestie!! This manual page is the Debian version, dated November 4, 2024, and it documents IKED.CONF(5) 💅✨ Go configure something gorgeous. You got this. 🦋🌸🎀

📦 where this page comes from