Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
IKED.CONF(5)		      File Formats Manual		  IKED.CONF(5)

       iked.conf - IKEv2 configuration file

       iked.conf  is  the configuration	file for iked(8), the Internet Key Ex-
       change version 2	(IKEv2)	daemon for IPsec.  IPsec itself	is a  pair  of
       protocols:  Encapsulating Security Payload (ESP), which provides	integ-
       rity and	confidentiality; and Authentication Header  (AH),  which  pro-
       vides 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  de-
       tail  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	conve-
       nient for quick setups and testing.

       iked.conf is divided into three main sections:

       Macros User-defined variables may be defined and	used later,  simplify-
	      ing 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 com-
	      ments, 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 net-
	      blocks), 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"

       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 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 pro-
	      vide redundancy.	iked will run in passive  mode	until  sasyncd
	      has determined that the host is the master and can switch	to ac-
	      tive 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	 /usr/local/etc/iked/ocsp/responder.crt	 and  /usr/lo-

       user name password
	      iked(8)  supports	user-based authentication by tunneling the Ex-
	      tensible Authentication Protocol (EAP) over IKEv2.  In its  most
	      basic form, the users will be authenticated against a local, in-
	      tegrated password	database that  is  configured  with  the  user
	      lines  in	 iked.conf  and	the name and password arguments.  Note
	      that the password	has to be specified in plain text which	is re-
	      quired  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 au-
       tomatic 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 de-
       cides what action is taken; if no policy	matches	 the  connection,  the
       default	action	is  to ignore the connection attempt or	to use the de-
       fault policy, if	set.  Please also see the EXAMPLES section for	a  de-
       tailed 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  automati-
       cally 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  automati-
	      cally 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 con-
	      nection  matches a policy	with the quick option set, that	policy
	      is considered the	last matching policy, and evaluation of	subse-
	      quent policies is	skipped.  The skip option will disable evalua-
	      tion of this policy for incoming connections.  The  default  op-
	      tion sets	the default policy and should only be specified	once.

       [mode] mode  specifies the IKEv2	mode to	use: one of passive, active or
	      lazy.  When passive is specified,	iked(8)	will  not  immediately
	      start  negotiation  of this tunnel, but wait for an incoming re-
	      quest from the remote peer.  When	active is specified,  negotia-
	      tion  will be started at once.  When lazy	is specified, negotia-
	      tion will	start if and when needed.   A  negotiation  is	needed
	      when  a  packet matches the flow and there is no association for
	      it yet.  If omitted, passive mode	will be	used.

       ipcomp Enable optional support for ipcomp(4), the IP  Payload  Compres-
	      sion protocol.

	      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.  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.  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/BI-
	      NAT scenarios 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 num-
	      ber or by	name.  For a list of all port name to number mappings,
	      see the file /etc/services.

       local localip Ic	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.  Note  that  when	 these
	      parameters are omitted, iked(8) will attempt to negotiate	trans-
	      port mode	IPSec.

	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 pro-
	      posals 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  ex-
	      change;  additional  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	additional Child SAs exchanges that are	 not  part  of
	      the initial key exchange.

       srcid string Ic dstid string
	      srcid  defines  an  ID  of type ``FQDN'',	``ASN1_DN'', ``IPV4'',
	      ``IPV6'',	or ``UFQDN'' that will be used by iked(8) as the iden-
	      tity  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  ac-
	      tive IKE SA rekeying.  This is the default.

       lifetime	time [Ic 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 re-

	      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

       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

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

       protected-subnet	address/prefix
	      The address of the protected subnet within the internal 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
	      connection.   This  will allow matching packets for this connec-
	      tion by defining rules in	pf.conf(5) using the tagged keyword.

	      The following variables can be used in tags to include  informa-
	      tion from	the remote peer	on runtime:

       $id    The  dstid  that was proposed by the remote peer to identify it-
	      self.  It	will be	 expanded  to  id-value,  e.g.	FQDN/foo.exam-	To limit the size of the derived tag, iked(8) will ex-
	      tract the	common	name  `CN='  from  ASN1_DN  IDs,  for  example
	      ASN1_ID//C=DE/../CN=  will be expanded	to

	      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/user@ex-,  ``ipsec-$domain''  expands to	``''.
	      The variable expansion for the tag directive occurs only at run-
	      time, not	during configuration file parse	time.

       tap interface
	      Send  the	decapsulated IPsec traffic to the specified enc(4) in-
	      terface instead of enc0 for filtering and	monitoring.  The traf-
	      fic  will	 be blocked if the specified interface does not	exist.
	      This option is only valid	with the operating system has or  sup-
	      ports the	enc(4) interface.

       In  some	 network  topologies it	is desirable to	perform	NAT on traffic
       leaving through the VPN tunnel.	In order to achieve that, the src  ar-
       gument  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 \

       From  the  peer's point of view,	the local end of the VPN tunnel	is de-
       clared to be and all the traffic arrives  with  that	source

       The following authentication types are permitted	with the auth keyword:

       AuthenticationTa.IRKey LengthTa.IRTruncated Length

       hmac-md5	Ta "128	bits" Ta "96 bits"

       hmac-sha1 Ta "160 bits" Ta "96 bits"

       hmac-sha2-256 Ta	"256 bits" Ta "128 bits"

       hmac-sha2-384 Ta	"384 bits" Ta "192 bits"

       hmac-sha2-512 Ta	"512 bits" Ta "256 bits"

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

       PRFTa.IRKey LengthTa

       hmac-md5	Ta "128	bits" Ta "[IKE only]"

       hmac-sha1 Ta "160 bits" Ta "[IKE	only]"

       hmac-sha2-256 Ta	"256 bits" Ta "[IKE only]"

       hmac-sha2-384 Ta	"384 bits" Ta "[IKE only]"

       hmac-sha2-512 Ta	"512 bits" Ta "[IKE only]"

	      The following cipher types are permitted with the	enc keyword:

       CipherTa.IRKey LengthTa

       3des Ta "168 bits" Ta ""

       aes-128 Ta "128 bits" Ta	""

       aes-192 Ta "192 bits" Ta	""

       aes-256 Ta "256 bits" Ta	""

       aes-128-ctr Ta "160 bits" Ta "[ESP only]"

       aes-192-ctr Ta "224 bits" Ta "[ESP only]"

       aes-256-ctr Ta "288 bits" Ta "[ESP only]"

       aes-128-gcm Ta "160 bits" Ta "[ESP only]"

       aes-192-gcm Ta "224 bits" Ta "[ESP only]"

       aes-256-gcm Ta "288 bits" Ta "[ESP only]"

       blowfish	Ta "160	bits" Ta "[ESP only]"

       cast Ta "128 bits" Ta "[ESP only]"

       chacha20-poly1305 Ta "288 bits" Ta "[ESP	only]"

	      The following cipher types provide only authentication, not  en-

       aes-128-gmac Ta "160 bits" Ta "[ESP only]"

       aes-192-gmac Ta "224 bits" Ta "[ESP only]"

       aes-256-gmac Ta "288 bits" Ta "[ESP only]"

       null Ta "" Ta "[ESP only]"

	      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,
	      AES-GMAC	and  Chacha20-Poly1305,	however	in the latter case the
	      keysize is 256 bit.

	      Using AES-GMAC or	NULL with ESP will  only  provide  authentica-
	      tion.   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:


       modp768 Ta grp1 Ta 768 Ta "MODP"

       modp1024	Ta grp2	Ta 1024	Ta "MODP"

       ec2n155 Ta grp3 Ta 155 Ta "EC2N [insecure]"

       ec2n185 Ta grp4 Ta 185 Ta "EC2N [insecure]"

       modp1536	Ta grp5	Ta 1536	Ta "MODP"

       modp2048	Ta grp14 Ta 2048 Ta "MODP"

       modp3072	Ta grp15 Ta 3072 Ta "MODP"

       modp4096	Ta grp16 Ta 4096 Ta "MODP"

       modp6144	Ta grp17 Ta 6144 Ta "MODP"

       modp8192	Ta grp18 Ta 8192 Ta "MODP"

       ecp256 Ta grp19 Ta 256 Ta "ECP"

       ecp384 Ta grp20 Ta 384 Ta "ECP"

       ecp521 Ta grp21 Ta 521 Ta "ECP"

       modp1024-160 Ta grp22 Ta	2048 Ta	"MODP, 160 bit Prime Order Subgroup"

       modp2048-224 Ta grp23 Ta	2048 Ta	"MODP, 224 bit Prime Order Subgroup"

       modp2048-256 Ta grp24 Ta	2048 Ta	"MODP, 256 bit Prime Order Subgroup"

       ecp192 Ta grp25 Ta 192 Ta "ECP"

       ecp224 Ta grp26 Ta 224 Ta "ECP"

       brainpool224 Ta grp27 Ta	224 Ta "ECP, brainpoolP224r1"

       brainpool256 Ta grp28 Ta	256 Ta "ECP, brainpoolP256r1"

       brainpool384 Ta grp29 Ta	384 Ta "ECP, brainpoolP384r1"

       brainpool512 Ta grp30 Ta	512 Ta "ECP, brainpoolP512r1"

       curve25519 Ta - Ta 256 Ta "Curve25519"

	      The currently supported group types are either MODP (exponentia-
	      tion  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 provided for backwards  compati-

       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

       user "test" "password123"

       ikev2 "win7" esp	\
	    from 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 3des auth	hmac-sha1 group	modp1024 \
	    childsa enc	aes-128	auth hmac-sha1 \
	    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; con-
       nections	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 policy.

       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

       enc(4), ipsec(4), ikectl(8), iked(8)

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

       This version of the iked(8) program was written by

       Reyk  Floeter  <Mt ,> with modifications and enhance-
       ments by

       Marcel Moolenaar	<Mt .>

			       December	9 2015			  IKED.CONF(5)


Want to link to this manual page? Use this URL:

home | help