unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OpenBSD-5.7)
Page:
Section:
Apropos / Subsearch:
optional field

IKED.CONF(5)                BSD File Formats Manual               IKED.CONF(5)

NAME
     iked.conf -- IKEv2 configuration file

DESCRIPTION
     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 net-
     works, and then Security Associations (SA) are established, which detail
     how the desired protection will be achieved.  IPsec uses flows to deter-
     mine 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 FILE FORMAT
     iked.conf is divided into three main sections:

     Macros
           User-defined variables 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 sym-
     bolic host names, interface names, or interface group names.

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

           include "/etc/macros.conf"

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 active mode.  This is the default.

     set passive
           Set iked(8) to passive mode.  In passive mode no packets are sent
           to peers and no connections are initiated by iked(8).  This option
           is used for setups using sasyncd(8) and carp(4) to provide redun-
           dancy.  iked 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 ocsp URL
           Enable OCSP and set the URL of the OCSP responder.  Please note
           that the matching responder and issuer certificates have to be
           placed in /etc/iked/ocsp/responder.crt and
           /etc/iked/ocsp/issuer.crt.

     user name password
           iked(8) supports user-based authentication by tunneling the Exten-
           sible 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.  Note that the pass-
           word has to be specified in plain text which is required to support
           different challenge-based EAP methods like EAP-MD5 or EAP-MSCHAPv2.

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 auto-
     matic 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.  Please also 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 cre-
     ated; 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 pol-
           icy.  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 consid-
           ered the last matching policy, and evaluation of subsequent poli-
           cies 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 nego-
           tiation 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
           Enable optional support for ipcomp(4), the IP Payload Compression
           protocol.

     [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 fam-
           ily which can be either inet or inet6.  Note that 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
           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.

     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.  The keyword any will match any
           address (i.e. 0.0.0.0/0).  If the src argument specifies a fic-
           tional source ID, the srcnat parameter can be used to specify the
           actual source address.  This can be used in outgoing NAT/BINAT sce-
           narios as described below.

           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 end-
           point.  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 end-
           point.  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 propos-
           als are described below in CRYPTO TRANSFORMS.  If omitted, iked(8)
           will use the default proposals for the IKEv2 protocol.

     childsa auth algorithm enc algorithm group group
           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; addi-
           tional Child SAs may be negotiated with additional Child SA key
           exchanges for an established IKE SA.

           Possible values for auth, enc, group, 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 addi-
           tional Child SAs exchanges that are not part of the initial key
           exchange.

     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 (reyk@exam-
           ple.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=reykATexample.com).  If the argu-
           ment 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.

     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 512
           megabytes which means that SA will be rekeyed before reaching the
           time limit or 512 megabytes 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.

           Please note that rekeying must happen at least several times a day
           as IPsec security heavily depends on the frequent key renewals.

     [ikeauth]
           Specify the mode to mutually authenticate the peers.  Non-psk modes
           will require to set up certificates and RSA public keys; see
           iked(8) for more information.

                 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.
                 psk string
                          Use a pre-shared key string or hex value (starting
                          with 0x) for authentication.
                 rsa      Use RSA public key authentication.  This is the
                          default mode if no option is specified.

     config option address
           Send one or more optional configuration payloads (CP) to the peer.
           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 the protected subnet within the inter-
                         nal network.
                 access-server address
                         The address of an internal remote access server.

     tag string
           Add a pf(4) tag to all packets of IPsec SAs created for this con-
           nection.  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/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.
                 $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 direc-
           tive occurs only at runtime, not during configuration file parse
           time.

     tap interface
           Send the decapsulated IPsec traffic to the specified enc(4)
           interface instead of enc0 for filtering and monitoring.  The traf-
           fic will be blocked if the specified interface does not exist.

PACKET FILTERING
     IPsec traffic appears unencrypted on the enc(4) interface and can be fil-
     tered accordingly using the OpenBSD packet filter, pf(4).  The grammar
     for the packet filter is described in pf.conf(5).

     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.

           enc0
           Default interface for outgoing traffic before it's been encapsu-
           lated, 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.

           tagged ipsec-example.org
           Match traffic of IPsec SAs using the tag keyword.

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

           set skip on enc0

     In the following example, all traffic is blocked by default.  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 permitted.

           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)

     pf(4) has the ability to filter IPsec-related packets based on an arbi-
     trary 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 ipsec-developers.example.com set queue developers
           pass out on ix0 tagged ipsec-employees.example.com 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 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
     In some network topologies it is desirable to perform NAT on traffic
     leaving through the VPN tunnel.  In order to achieve that, the src argu-
     ment 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 192.168.1.0/24 and all the traffic
     for a specific VPN peer should appear as coming from 10.10.10.1, the fol-
     lowing configuration is used:

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

     Naturally, a relevant NAT rule is required in pf.conf(5).  For the exam-
     ple above, this 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.

CRYPTO TRANSFORMS
     The following authentication types are permitted with the auth keyword:

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

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

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

     The following cipher types are permitted with the enc keyword:

           Cipher          Key Length
           des             56 bits       [ESP only]
           3des            168 bits
           aes-128         128 bits
           aes-192         192 bits
           aes-256         256 bits
           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      [ESP only]
           aes-192-gcm     224 bits      [ESP only]
           aes-256-gcm     288 bits      [ESP only]
           blowfish        160 bits      [ESP only]
           cast            128 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]

     Use of DES as an encryption algorithm is considered to be insecure since
     brute force attacks are practical due its short key length.

     DES requires 8 bytes to form a 56-bit key and 3DES requires 24 bytes to
     form its 168-bit key.  This is because the most significant bit of each
     byte is used for parity.

     The keysize of AES-CTR is actually 128-bit.  However as well as the key,
     a 32-bit nonce has to be supplied.  Thus 160 bits of key material have to
     be supplied.  The same applies to AES-GCM and AES-GMAC.

     Using AES-GMAC or NULL with ESP will only provide authentication.  This
     is useful in setups where AH can not be used, e.g. when NAT is involved.

     The following group types are permitted with the group keyword:

           Name            Group    Size    Type
           modp768         grp1     768     MODP
           modp1024        grp2     1024    MODP
           ec2n155         grp3     155     EC2N [insecure]
           ec2n185         grp4     185     EC2N [insecure]
           modp1536        grp5     1536    MODP
           modp2048        grp14    2048    MODP
           modp3072        grp15    3072    MODP
           modp4096        grp16    4096    MODP
           modp6144        grp17    6144    MODP
           modp8192        grp18    8192    MODP
           ecp256          grp19    256     ECP
           ecp384          grp20    384     ECP
           ecp521          grp21    521     ECP
           modp1024-160    grp22    2048    MODP, 160 bit Prime Order Subgroup
           modp2048-224    grp23    2048    MODP, 224 bit Prime Order Subgroup
           modp2048-256    grp24    2048    MODP, 256 bit Prime Order Subgroup
           ecp192          grp25    192     ECP
           ecp224          grp26    224     ECP
           brainpool224    grp27    224     ECP, brainpoolP224r1
           brainpool256    grp28    256     ECP, brainpoolP256r1
           brainpool384    grp29    384     ECP, brainpoolP384r1
           brainpool512    grp30    512     ECP, brainpoolP512r1
           curve25519      -        256     Curve25519

     The currently supported group types are either MODP (exponentiation
     groups modulo a prime), EC2N (elliptic curve groups over GF[2^N]), ECP
     (elliptic curve groups modulo a prime), or the non-standard Curve25519.
     Please note that the EC2N groups are considered as insecure and only pro-
     vided for backwards compatibility.

EXAMPLES
     The first example is intended for 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 0.0.0.0/0 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"

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

           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 3des auth hmac-sha1 group modp1024 \
                   childsa enc aes-128 auth hmac-sha1 \
                   srcid host.example.com \
                   dstid 192.168.0.254 \
                   psk "foobar"

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

           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

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

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

AUTHORS
     The iked(8) program was written by Reyk Floeter <reyk@openbsd.org>.

BSD                            February 28, 2015                           BSD