Provided by: openiked_7.1-1build1_amd64 bug


     iked.conf — IKEv2 configuration file


     iked.conf is the configuration file for iked(8), the Internet Key Exchange version 2 (IKEv2)
     daemon for IPsec.  IPsec itself is a pair of protocols: Encapsulating Security Payload
     (ESP), which provides integrity and confidentiality; and Authentication Header (AH), which
     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).

     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.


     iked.conf is divided into three main sections:

           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 to \


     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 = ""
           ikev2 esp from to peer $remote_gw


     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.  This mode is only useful for
           testing and debugging.

     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.

     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

     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.

     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.


     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 and
        # Second between the networks and
        ikev2 esp from to
        ikev2 esp from to peer

     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

     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.

     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.

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

           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 describes the encapsulation mode to be used.  Possible modes are tunnel and
           transport; the default is tunnel.

           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.

           Each traffic selector will apply for packets with source address src and destination
           address dst.  If the src argument specifies a fictional source ID, the srcnat
           parameter can be used to specify the actual source address.  This can be used in
           outgoing NAT/BINAT scenarios as described below.  The keyword any will match any
           address (i.e. and ::/0).  If the config address option is specified, the
           dynamic keyword can be used to create flows from or to the dynamically assigned

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

     local localip peer remote
           The local 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.

           The peer parameter specifies the address or FQDN of the remote endpoint.  For host-to-
           host connections where dst is identical to remote, this option is generally not needed
           as it will be set to dst automatically.  If it is not specified or if the keyword any
           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 auth, enc, prf, group, 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 ikesa can be used multiple times as a delimiter between IKE SA proposals.
           The order of the proposals depend on the order in the configuration.  The keywords
           auth, enc, prf and group can be used multiple times within a single proposal to
           configure multiple crypto transforms.

     childsa auth algorithm enc algorithm group group esn
           These parameters define the cryptographic transforms to be used for the Child SA
           negotiation, also known as 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 auth, enc, group, esn, 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 group option will only be used to enable Perfect Forward Secrecy (PFS) for
           additional Child SAs exchanges that are not part of the initial key exchange.

           The keyword childsa can be used multiple times as a delimiter between Child SA
           proposals.  The order of the proposals depend on the order in the configuration.  The
           keywords auth, enc and group can be used multiple times within a single proposal to
           configure multiple crypto transforms.

     srcid string dstid string
           srcid 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.  If the argument is an email
           address (, 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=  If the argument is an IPv4
           address or a compressed IPv6 address, the ID types IPV4 or IPV6 will be used.
           Anything else is considered to be an FQDN.

           If srcid is omitted, the default is to use the hostname of the local machine, see
           hostname(1) to set or print the hostname.

           dstid is similar to srcid, but instead specifies the ID to be used by the remote peer.

     ikelifetime time
           The optional ikelifetime parameter defines the IKE SA expiration timeout by the time
           SA was created.  A zero value disables active IKE SA rekeying.  This is the default.

           The accepted format of the time specification is described below.

     lifetime time [bytes bytes]
           The optional lifetime 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

           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.

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

                 eap type
                          Use EAP to authenticate the initiator.  The only supported EAP type is
                          currently MSCHAP-V2.  The responder will use RSA public key
                          Use ECDSA with a 256-bit elliptic curve key and SHA2-256 for
                          Use ECDSA with a 384-bit elliptic curve key and SHA2-384 for
                          Use ECDSA with a 521-bit elliptic curve key and SHA2-512 for
                 psk string
                          Use a pre-shared key string or hex value (starting with 0x) for
                 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.

           The default is to allow any signature authentication.

     config option address
     request option address
           Request or serve one or more optional configuration payloads (CP).  The configuration
           option 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 on runtime:

                 $id      The dstid that was proposed by the remote peer to identify itself.  It
                          will be expanded to id-value, e.g. FQDN/  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= will be
                          expanded to
                 $eapid   For a connection using EAP, the identity (username) used by the remote
                 $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/ or UFQDN/,
           “ipsec-$domain” expands to “”.  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.

     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.


     IPsec traffic appears unencrypted on the enc(4) interface and can be filtered accordingly
     using the OpenBSD packet filter, pf(4).  The grammar for the packet filter is described in

     The following components are relevant to filtering IPsec traffic:

           external interface
           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.

           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; see enc(4) for further information.

           proto ipencap
           [tunnel mode only] IP-in-IP traffic flowing between gateways on the enc0 interface.

           Match traffic of IPsec SAs using the tag keyword.

     If the filtering rules specify to block everything by default, the following rule would
     ensure that IPsec traffic never hits the packet filtering engine, and is therefore passed:

           set skip on enc0

     In the following example, all traffic is blocked by default.  IPsec-related traffic from
     gateways {,} and networks {,} is permitted.

           block on ix0
           block on enc0

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

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

           pass  in on enc0 proto ipencap from to \
                   keep state (if-bound)
           pass out on enc0 proto ipencap from to \
                   keep state (if-bound)
           pass  in on enc0 from to \
                   keep state (if-bound)
           pass out on enc0 from to \
                   keep state (if-bound)

     pf(4) has the ability to filter IPsec-related packets based on an arbitrary tag specified
     within a ruleset.  The tag is used as an internal marker which can be used to identify the
     packets later on.  This could be helpful, for example, in scenarios where users are
     connecting in from differing IP addresses, or to support queue-based bandwidth control,
     since the enc0 interface does not support it.

     The following pf.conf(5) fragment uses queues for all IPsec traffic with special handling
     for developers and 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 \
                   set queue developers
           pass out on ix0 tagged \
                   set queue employees

     The following example assigns the tags in the iked.conf configuration and also sets an
     alternative enc(4) device:

           ikev2 esp from to peer \
                   tag "ipsec-$domain" tap "enc1"


     In some network topologies it is desirable to perform NAT on traffic leaving through the VPN
     tunnel.  In order to achieve that, the src argument is used to negotiate the desired network
     ID with the peer and the srcnat parameter defines the true local subnet, so that a correct
     SA can be installed on the local side.

     For example, if the local subnet is and all the traffic for a specific VPN
     peer should appear as coming from, the following configuration is used:

           ikev2 esp from ( to \

     Naturally, a relevant NAT rule is required in pf.conf(5).  For the example above, this would

           match out on enc0 from to \

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


     The following 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

     The following 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]

     The following 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]

     The following cipher types provide only authentication, not encryption:

           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 enabled or disabled with the esn or noesn

           ESN      Default
           esn      x          [ESP only]
           noesn    x          [ESP only]

     Transforms followed by [IKE only] can only be used with the ikesa keyword, transforms with
     [ESP only] can only be used with the childsa keyword.

     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.

     The following 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.  MODP groups of less than 2048
     bits are considered as weak or insecure (see RFC 8247 section 2.4) and only provided for
     backwards compatibility.




     The first example is intended for a server with clients connecting to iked(8) as an IPsec
     gateway, or IKEv2 responder, using mutual public key authentication and additional
     challenge-based EAP-MSCHAPv2 password authentication:

           user "test" "password123"

           ikev2 "win7" esp \
                   from dynamic to \
                   peer local \
                   eap "mschap-v2" \
                   config address \
                   tag "$name-$id"

     The next example allows peers to authenticate using a pre-shared key ‘foobar’:

           ikev2 "big test" \
                   esp proto tcp \
                   from port 23 to port 40 \
                   from to \
                   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 \
                   dstid \
                   psk "foobar"

     The following example illustrates the last matching policy evaluation for incoming
     connections on an IKEv2 gateway.  The peer will always match the first policy
     because of the quick keyword; connections from the peers and will be
     matched by one of the last two policies; any other connections from will be
     matched by the ‘subnet’ policy; and any other connection will be matched by the ‘catch all’

           ikev2 quick esp from to \
           ikev2 "catch all" esp from to \
                   peer any
           ikev2 "subnet" esp from to \
           ikev2 esp from to peer
           ikev2 esp from to peer

     This example encrypts a gre(4) tunnel from local machine A (2001:db8::aa:1) to peer D
     (2001:db8::dd:4) based on FQDN-based public key authentication; transport mode avoids double

           ikev2 transport \
                   proto gre \
                   from 2001:db8::aa:1 to 2001:db8::dd:4 \


     enc(4), ipsec(4), ipsec.conf(5), pf.conf(5), ikectl(8), iked(8)


     The iked.conf file format first appeared in OpenBSD 4.8.


     The iked(8) program was written by Reyk Floeter <>.