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

FreeBSD Manual Pages

  
 
  

home | help
IPSEC.CONF(5)			  strongSwan			 IPSEC.CONF(5)

NAME
       ipsec.conf - IPsec configuration	and connections

DESCRIPTION
       The  optional  ipsec.conf file specifies	most configuration and control
       information for the strongSwan IPsec subsystem.	The major exception is
       secrets for authentication; see ipsec.secrets(5).  Its contents are not
       security-sensitive.

       The file	is a text file,	consisting of one  or  more  sections.	 White
       space  followed	by  # followed by anything to the end of the line is a
       comment and is ignored, as are empty lines which	are not	within a  sec-
       tion.

       A  line	which  contains	 include  and  a file name, separated by white
       space, is replaced by the contents of that file.	 If the	file  name  is
       not  a  full pathname, it is considered to be relative to the directory
       containing the including	file.  Such inclusions can be nested.  Only  a
       single  filename	 may  be supplied, and it may not contain white	space,
       but it may include shell	wildcards (see sh(1)); for example:

       include ipsec.*.conf

       The intention of	the include facility is	mostly to permit  keeping  in-
       formation  on  connections,  or	sets of	connections, separate from the
       main configuration file.	 This permits such connection descriptions  to
       be changed, copied to the other security	gateways involved, etc., with-
       out having to constantly	extract	them from the configuration  file  and
       then insert them	back into it.  Note also the also parameter (described
       below) which permits splitting a	single logical section (e.g. a connec-
       tion description) into several actual sections.

       A section begins	with a line of the form:

       type name

       where type indicates what type of section follows, and name is an arbi-
       trary name which	distinguishes the section  from	 others	 of  the  same
       type.   All subsequent non-empty	lines which begin with white space are
       part of the section.  Sections of the same type	that  share  the  same
       name are	merged.

       Lines within the	section	are generally of the form

	    parameter=value

       (note  the  mandatory preceding white space).  There can	be white space
       on either side of the =.	 Parameter names are  specific	to  a  section
       type.

       An  empty value stands for the system default value (if any) of the pa-
       rameter,	i.e. it	is roughly equivalent to omitting the  parameter  line
       entirely.  This	may be useful to clear a setting inherited from	a %de-
       fault section or	via also parameter (see	below).	 A value  may  contain
       single  spaces  (additional  white  space is reduced to one space).  To
       preserve	white space as written enclose	the  entire  value  in	double
       quotes  (");  in	such values double quotes themselves may be escaped by
       prefixing them with \ characters. A double-quoted string	may span  mul-
       tiple  lines  by	 ending	 them with \ characters	(following lines don't
       have to begin with white	space, as that will be	preserved).  Addition-
       ally,  the following control characters may be encoded in double-quoted
       strings:	\n, \r,	\t, \b,	\f.

       Numeric values are specified to be either an ``integer''	(a sequence of
       digits) or a ``decimal number'' (sequence of digits optionally followed
       by `.' and another sequence of digits).

       There is	currently one parameter	which is available in any type of sec-
       tion:

       also   the  value is a section name; the	parameters of that section are
	      inherited	by the current section.	Parameters in the current sec-
	      tion  always override inherited parameters, even if an also fol-
	      lows after them.	The specified section must exist and must have
	      the same section type; it	doesn't	if it is defined before	or af-
	      ter the current section.	Nesting	is permitted, and there	may be
	      more  than  one also in a	single section (parameters from	refer-
	      enced sections are inherited and	overridden  in	the  order  of
	      these also parameters).

       A  section  with	 name  %default	specifies defaults for sections	of the
       same type. All parameters in it,	are inherited by all other sections of
       that type.

       Currently there are three types of sections: a config section specifies
       general configuration information for IPsec, a conn  section  specifies
       an IPsec	connection, while a ca section specifies special properties of
       a certification authority.

CONN SECTIONS
       A conn section contains a connection specification, defining a  network
       connection to be	made using IPsec.  The name given is arbitrary,	and is
       used to identify	the connection.	 Here's	a simple example:

       conn snt
	   left=192.168.0.1
	   leftsubnet=10.1.0.0/16
	   right=192.168.0.2
	   rightsubnet=10.1.0.0/16
	   keyingtries=%forever
	   auto=add

       A note on terminology: There are	two kinds of communications going  on:
       transmission  of	 user  IP packets, and gateway-to-gateway negotiations
       for keying, rekeying, and general control.  The	path  to  control  the
       connection  is  called  'ISAKMP	SA' in IKEv1 and 'IKE SA' in the IKEv2
       protocol. That what is being negotiated,	the kernel level data path, is
       called  'IPsec SA' or 'Child SA'.  strongSwan previously	used two sepa-
       rate keying daemons, pluto and charon. This  manual  does  not  discuss
       pluto  options  anymore,	but only charon	that since strongSwan 5.0 sup-
       ports both IKEv1	and IKEv2.

       To avoid	trivial	editing	of the configuration file to suit it  to  each
       system  involved	in a connection, connection specifications are written
       in terms	of left	and right participants,	rather than in terms of	 local
       and  remote.   Which  participant  is considered	left or	right is arbi-
       trary; for every	connection description an attempt is  made  to	figure
       out  whether  the  local	 endpoint should act as	the left or right end-
       point. This is done by matching the IP addresses	defined	for both  end-
       points with the IP addresses assigned to	local network interfaces. If a
       match is	found then the role (left or right) that matches is  going  to
       be considered local.  If	no match is found during startup, left is con-
       sidered local.  This permits using identical connection	specifications
       on  both	ends.  There are cases where there is no symmetry; a good con-
       vention is to use left for the local side and right for the remote side
       (the first letters are a	good mnemonic).

       Many of the parameters relate to	one participant	or the other; only the
       ones for	left are listed	here, but every	parameter  whose  name	begins
       with  left  has	a right	counterpart, whose description is the same but
       with left and right reversed.

       Parameters are optional unless marked '(required)'.

   CONN	PARAMETERS
       Unless otherwise	noted, for a connection	to work, in general it is nec-
       essary for the two ends to agree	exactly	on the values of these parame-
       ters.

       aaa_identity = <id>
	      defines the identity of the AAA backend used  during  IKEv2  EAP
	      authentication.	This  is  required  if	the  EAP client	uses a
	      method that verifies the server identity (such as	EAP-TLS),  but
	      it does not match	the IKEv2 gateway identity.

       aggressive = yes	| no
	      whether to use IKEv1 Aggressive or Main Mode (the	default).

       ah = <cipher suites>
	      comma-separated list of AH algorithms to be used for the connec-
	      tion,  e.g.   sha1-sha256-modp1024.   The	 notation  is	integ-
	      rity[-dhgroup].  For IKEv2, multiple algorithms (separated by -)
	      of the same type can be included in  a  single  proposal.	 IKEv1
	      only  includes  the  first algorithm in a	proposal.  Only	either
	      the ah or	esp keyword may	be used, AH+ESP	bundles	are  not  sup-
	      ported.

	      There  is	 no  default  AH  cipher suite since by	default	ESP is
	      used.  The daemon	adds its extensive  default  proposal  to  the
	      configured  value.  To restrict it to the	configured proposal an
	      exclamation mark (!)  can	be added at the	end.

	      If dh-group is specified,	CHILD_SA/Quick Mode setup and rekeying
	      include  a  separate  Diffie-Hellman  exchange (refer to the esp
	      keyword for details).

       also = <name>
	      includes conn section <name>.

       auth = <value>
	      was used by the pluto IKEv1 daemon to use	AH  integrity  protec-
	      tion  for	ESP encrypted packets, but is not supported in charon.
	      The ah keyword specifies algorithms to use for integrity protec-
	      tion  with  AH,  but  without encryption.	AH+ESP bundles are not
	      supported.

       authby =	pubkey | rsasig	| ecdsasig | psk | secret | never | xauthpsk |
       xauthrsasig
	      how  the	two  security gateways should authenticate each	other;
	      acceptable values	are psk	or secret for pre-shared secrets, pub-
	      key  (the	default) for public key	signatures as well as the syn-
	      onyms rsasig for RSA digital signatures and ecdsasig for	Ellip-
	      tic  Curve  DSA signatures.  never can be	used if	negotiation is
	      never to be attempted or accepted	(useful	for shunt-only conns).
	      Digital  signatures are superior in every	way to shared secrets.
	      IKEv1 additionally supports the values xauthpsk and  xauthrsasig
	      that  will enable	eXtended AUTHentication	(XAUTH)	in addition to
	      IKEv1 main mode based on shared secrets or  digital  RSA	signa-
	      tures, respectively.  This parameter is deprecated, as two peers
	      do not need to agree on an authentication	method in  IKEv2.  Use
	      the leftauth parameter instead to	define authentication methods.

       auto = ignore | add | route | start
	      what  operation,	if  any, should	be done	automatically at IPsec
	      startup; currently-accepted values are add, route, start and ig-
	      nore (the	default).  add loads a connection without starting it.
	      route loads a connection and installs kernel traps.  If  traffic
	      is  detected between leftsubnet and rightsubnet, a connection is
	      established.  start loads	a connection and brings	it up  immedi-
	      ately.  ignore ignores the connection. This is equal to deleting
	      a	connection from	the config file.  Relevant only	locally, other
	      end need not agree on it.

       closeaction = none | clear | hold | restart
	      defines  the  action  to	take  if  the remote peer unexpectedly
	      closes a CHILD_SA	(see dpdaction	for  meaning  of  values).   A
	      closeaction should not be	used if	the peer uses reauthentication
	      or uniquids checking, as these events might trigger the  defined
	      action when not desired.

       compress	= yes |	no
	      whether IPComp compression of content is proposed	on the connec-
	      tion (link-level compression does	not work on encrypted data, so
	      to  be  effective,  compression must be done before encryption);
	      acceptable values	are yes	and no (the default). A	value  of  yes
	      causes  the  daemon to propose both compressed and uncompressed,
	      and prefer compressed.  A	value of no prevents the  daemon  from
	      proposing	or accepting compression.

       dpdaction = none	| clear	| hold | restart
	      controls	the  use of the	Dead Peer Detection protocol (DPD, RFC
	      3706) where R_U_THERE notification messages (IKEv1) or empty IN-
	      FORMATIONAL  messages  (IKEv2) are periodically sent in order to
	      check the	liveliness of the IPsec	peer. The values clear,	 hold,
	      and restart all activate DPD and determine the action to perform
	      on a timeout. With clear the connection is closed	with  no  fur-
	      ther  actions  taken.   hold  installs a trap policy, which will
	      catch matching traffic and tries to re-negotiate the  connection
	      on  demand.   restart will immediately trigger an	attempt	to re-
	      negotiation the connection.  The default is none which  disables
	      the active sending of DPD	messages.

       dpddelay	= 30s |	<time>
	      defines  the  period  time  interval  with  which	R_U_THERE mes-
	      sages/INFORMATIONAL exchanges are	sent to	the  peer.  These  are
	      only  sent if no other traffic is	received. In IKEv2, a value of
	      0	sends no additional INFORMATIONAL messages and uses only stan-
	      dard messages (such as those to rekey) to	detect dead peers.

       dpdtimeout = 150s | <time>
	      defines  the  timeout interval, after which all connections to a
	      peer are deleted in case of inactivity.  This  only  applies  to
	      IKEv1,  in  IKEv2	the default retransmission timeout applies, as
	      every exchange is	used to	detect dead peers.

       inactivity = <time>
	      defines the timeout interval, after which	a CHILD_SA  is	closed
	      if  it  did  not	send  or  receive  any traffic.	The inactivity
	      counter is reset during CHILD_SA rekeying. This means  that  the
	      inactivity timeout must be smaller than the rekeying interval to
	      have any effect.

       eap_identity = <id>
	      defines the identity the client uses to reply to an EAP Identity
	      request.	 If  defined  on  the EAP server, the defined identity
	      will be used as peer identity  during  EAP  authentication.  The
	      special  value %identity uses the	EAP Identity method to ask the
	      client for an EAP	identity. If not defined, the  IKEv2  identity
	      will be used as EAP identity.

       esp = <cipher suites>
	      comma-separated list of ESP encryption/authentication algorithms
	      to be used for the connection, e.g.  aes128-sha256.   The	 nota-
	      tion  is	encryption-integrity[-dhgroup][-esnmode].   For	IKEv2,
	      multiple algorithms (separated by	-) of the same type can	be in-
	      cluded in	a single proposal. IKEv1 only includes the first algo-
	      rithm in a proposal.  Only either	the ah or esp keyword  may  be
	      used, AH+ESP bundles are not supported.

	      Defaults	to  aes128-sha256.   The daemon	adds its extensive de-
	      fault proposal to	this default or	the configured value.  To  re-
	      strict  it  to  the  configured proposal an exclamation mark (!)
	      can be added at the end.

	      Note: As a responder, the	daemon defaults	to selecting the first
	      configured  proposal that's also supported by the	peer. This may
	      be changed via strongswan.conf(5)	to selecting the first accept-
	      able  proposal  sent by the peer instead.	In order to restrict a
	      responder	to only	accept specific	cipher suites, the strict flag
	      (!, exclamation mark) can	be used, e.g: aes256-sha512-modp4096!

	      If  dh-group is specified, CHILD_SA/Quick	Mode rekeying and ini-
	      tial negotiation use a separate  Diffie-Hellman  exchange	 using
	      the  specified  group.  However,	for  IKEv2,  the  keys	of the
	      CHILD_SA created implicitly with the IKE_SA will always  be  de-
	      rived  from the IKE_SA's key material. So	any DH group specified
	      here will	only apply when	the CHILD_SA is	later  rekeyed	or  is
	      created  with a separate CREATE_CHILD_SA exchange.  Therefore, a
	      proposal mismatch	might not immediately be noticed when  the  SA
	      is established, but may later cause rekeying to fail.

	      Valid values for esnmode are esn and noesn.  Specifying both ne-
	      gotiates Extended	Sequence Number	support	with the peer, the de-
	      fault is noesn.

       forceencaps = yes | no
	      force UDP	encapsulation for ESP packets even if no NAT situation
	      is detected.  This may help to surmount  restrictive  firewalls.
	      In order to force	the peer to encapsulate	packets, NAT detection
	      payloads are faked.

       fragmentation = yes  | force | no
	      whether to use IKE fragmentation (proprietary IKEv1 extension or
	      IKEv2 fragmentation as per RFC 7383).  Acceptable	values are yes
	      (the default), force and no.  Fragmented IKE messages sent by  a
	      peer  are	 always	accepted irrespective of the value of this op-
	      tion. If set to yes, and the peer	supports it, larger  IKE  mes-
	      sages  will  be  sent  in	fragments.  If set to force (only sup-
	      ported for IKEv1)	the initial IKE	message	will already be	 frag-
	      mented if	required.

       ike = <cipher suites>
	      comma-separated  list of IKE/ISAKMP SA encryption/authentication
	      algorithms to be used, e.g.  aes128-sha256-modp3072.  The	 nota-
	      tion is encryption-integrity[-prf]-dhgroup.  If no PRF is	given,
	      the algorithms defined for integrity are used for	the PRF.   The
	      prf  keywords are	the same as the	integrity algorithms, but have
	      a	prf prefix (such as prfsha1, prfsha256 or prfaesxcbc).
	      In IKEv2,	multiple algorithms and	 proposals  may	 be  included,
	      such	  as	    aes128-aes256-sha1-modp3072-modp2048,3des-
	      sha1-md5-modp1024.

	      Defaults to aes128-sha256-modp3072.  The daemon adds its	exten-
	      sive  default  proposal to this default or the configured	value.
	      To restrict it to	the configured proposal	 an  exclamation  mark
	      (!)  can be added	at the end.

	      Note: As a responder the daemon accepts the first	supported pro-
	      posal received from the peer.  In	order to restrict a  responder
	      to  only	accept specific	cipher suites, the strict flag (!, ex-
	      clamation	mark) can be used, e.g:	aes256-sha512-modp4096!

       ikedscp = 000000	| <DSCP	field>
	      Differentiated Services Field Codepoint to set on	 outgoing  IKE
	      packets  sent from this connection. The value is a six digit bi-
	      nary encoded string defining the Codepoint to set, as defined in
	      RFC 2474.

       ikelifetime = 3h	| <time>
	      how  long	 the keying channel of a connection (ISAKMP or IKE SA)
	      should last before being renegotiated. Also see EXPIRY/REKEY be-
	      low.

       installpolicy = yes | no
	      decides  whether	IPsec  policies	are installed in the kernel by
	      the charon daemon	for a given connection.	Allows peaceful	 coop-
	      eration e.g. with	the Mobile IPv6	daemon mip6d who wants to con-
	      trol the kernel policies.	 Acceptable values are	yes  (the  de-
	      fault) and no.

       keyexchange = ike | ikev1 | ikev2
	      which  key exchange protocol should be used to initiate the con-
	      nection.	Connections marked with	ike use	IKEv2 when initiating,
	      but accept any protocol version when responding.

       keyingtries = 3 | <number> | %forever
	      how many attempts	(a whole number	or %forever) should be made to
	      negotiate	a connection, or a replacement for one,	before	giving
	      up (default 3).  The value %forever means	'never give up'.  Rel-
	      evant only locally, other	end need not agree on it.

       keylife
	      synonym for lifetime.

       left = <ip address> | <fqdn> | %any | <range> | <subnet>
	      The IP address of	the left participant's	public-network	inter-
	      face  or	one  of	several	magic values.  The value %any (the de-
	      fault) for the local endpoint signifies an address to be	filled
	      in  (by  automatic keying) during	negotiation. If	the local peer
	      initiates	the connection setup the routing table will be queried
	      to  determine  the  correct local	IP address.  In	case the local
	      peer is responding to a connection setup	then  any  IP  address
	      that is assigned to a local interface will be accepted.

	      The  prefix % in front of	a fully-qualified domain name or an IP
	      address will implicitly set leftallowany=yes.

	      If %any is used for the remote endpoint it literally  means  any
	      IP address.

	      If an FQDN is assigned it	is resolved every time a configuration
	      lookup is	done. If DNS resolution	times out, the lookup  is  de-
	      layed for	that time.

	      To limit the connection to a  specific range of hosts, a range (
	      10.1.0.0-10.2.255.255 ) or a subnet ( 10.1.0.0/16	) can be spec-
	      ified,  and  multiple addresses, ranges and subnets can be sepa-
	      rated by commas. While one can freely combine  these  items,  to
	      initiate	the  connection	 at  least one non-range/subnet	is re-
	      quired.

	      Please note that with the	usage of wildcards multiple connection
	      descriptions  might  match  a given incoming connection attempt.
	      The most specific	description is used in that case.

       leftallowany = yes | no
	      a	modifier for left, making it behave as %any  although  a  con-
	      crete IP address or domain name has been assigned.

       leftauth	= <auth	method>
	      Authentication  method to	use locally (left) or require from the
	      remote (right) side.  Acceptable values are  pubkey  for	public
	      key authentication (RSA/ECDSA), psk for pre-shared key authenti-
	      cation, eap to (require the) use of the  Extensible  Authentica-
	      tion Protocol in IKEv2, and xauth	for IKEv1 eXtended Authentica-
	      tion.

	      To require a trustchain public key strength for the remote side,
	      specify  the  key	 type followed by the minimum strength in bits
	      (for example ecdsa-384 or	rsa-2048-ecdsa-256).  To limit the ac-
	      ceptable	set  of	 hashing algorithms for	trustchain validation,
	      append hash algorithms to	pubkey or a  key  strength  definition
	      (for	     example	       pubkey-sha1-sha256	    or
	      rsa-2048-ecdsa-256-sha256-sha384-sha512).	  Unless  disabled  in
	      strongswan.conf(5),  or explicit IKEv2 signature constraints are
	      configured (see below), such key types and hash  algorithms  are
	      also  applied as constraints against IKEv2 signature authentica-
	      tion schemes used	by the remote side.

	      If both peers support RFC	 7427  ("Signature  Authentication  in
	      IKEv2") specific hash algorithms to be used during IKEv2 authen-
	      tication may be configured.  The syntax is the  same  as	above,
	      but with ike: prefix. For	example, with ike:pubkey-sha384-sha256
	      a	public key signature scheme with  either  SHA-384  or  SHA-256
	      would  get  used for authentication, in that order and depending
	      on the hash algorithms supported by the peer.   If  no  specific
	      hash  algorithms are configured, the default is to prefer	an al-
	      gorithm that matches or exceeds the strength  of	the  signature
	      key.  If no constraints with ike:	prefix are configured any sig-
	      nature scheme constraint (without	ike: prefix) will  also	 apply
	      to   IKEv2   authentication,   unless   this   is	  disabled  in
	      strongswan.conf(5).

	      For eap, an optional EAP method can be appended.	Currently  de-
	      fined  methods are eap-aka, eap-gtc, eap-md5, eap-mschapv2, eap-
	      peap, eap-sim, eap-tls, eap-ttls,	eap-dynamic,  and  eap-radius.
	      Alternatively,  IANA  assigned  EAP method numbers are accepted.
	      Vendor specific EAP methods are defined in  the  form  eap-type-
	      vendor (e.g. eap-7-12345).  To specify signature and trust chain
	      constraints for EAP-(T)TLS, append a colon to  the  EAP  method,
	      followed	by  the	 key type/size and hash	algorithm as discussed
	      above. For xauth,	an XAuth authentication	backend	can be	speci-
	      fied,  such  as xauth-generic or xauth-eap.  If XAuth is used in
	      leftauth,	Hybrid authentication is used. For  traditional	 XAuth
	      authentication, define XAuth in lefauth2.

       leftauth2 = <auth method>
	      Same  as	leftauth, but defines an additional authentication ex-
	      change. In IKEv1,	only XAuth can be used in the second authenti-
	      cation  round.  IKEv2  supports multiple complete	authentication
	      rounds using "Multiple Authentication Exchanges" defined in  RFC
	      4739. This allows, for example, separated	authentication of host
	      and user.

       leftca =	<issuer	dn> | %same
	      the distinguished	name of	a certificate authority	which  is  re-
	      quired  to  lie  in  the trust path going	from the left partici-
	      pant's certificate  up  to  the  root  certification  authority.
	      %same  means that	the value configured for the right participant
	      should be	reused.

       leftca2 = <issuer dn> | %same
	      Same as leftca, but for the second authentication	 round	(IKEv2
	      only).

       leftcert	= <path>
	      the  path	 to the	left participant's X.509 certificate. The file
	      can be encoded either in PEM or DER format. OpenPGP certificates
	      are supported as well.  Both absolute paths or paths relative to
	      /etc/ipsec.d/certs are accepted. By default leftcert sets	leftid
	      to  the  distinguished  name  of the certificate's subject.  The
	      left participant's ID can	be overridden by specifying  a	leftid
	      value which must be certified by the certificate,	though.
	      A	value in the form %smartcard[<slot nr>[@<module>]]:<keyid> de-
	      fines a specific certificate to load from	a PKCS#11 backend  for
	      this  connection.	 See ipsec.secrets(5) for details about	smart-
	      card definitions.	 leftcert is required only  if	selecting  the
	      certificate with leftid is not sufficient, for example if	multi-
	      ple certificates use the same subject.
	      Multiple certificate paths or PKCS#11 backends can be  specified
	      in  a  comma  separated list. The	daemon chooses the certificate
	      based on the received certificate	requests  if  possible	before
	      enforcing	the first.

       leftcert2 = <path>
	      Same as leftcert,	but for	the second authentication round	(IKEv2
	      only).

       leftcertpolicy =	<OIDs>
	      Comma separated list of certificate policy OIDs the peer's  cer-
	      tificate must have.  OIDs	are specified using the	numerical dot-
	      ted representation.

       leftdns = <servers>
	      Comma separated list of DNS server addresses to exchange as con-
	      figuration  attributes.  On  the	initiator, a server is a fixed
	      IPv4/IPv6	address, or %config4/%config6  to  request  attributes
	      without  an  address. On the responder, only fixed IPv4/IPv6 ad-
	      dresses are allowed and  define  DNS  servers  assigned  to  the
	      client.

       leftfirewall = yes | no
	      whether  the  left  participant  is doing	forwarding-firewalling
	      (including masquerading) using iptables for traffic  from	 left-
	      subnet,  which  should  be  turned off (for traffic to the other
	      subnet) once the connection is  established;  acceptable	values
	      are  yes and no (the default).  May not be used in the same con-
	      nection description with leftupdown.  Implemented	as a parameter
	      to the default ipsec _updown script.  See	notes below.  Relevant
	      only locally, other end need not agree on	it.

	      If one or	both security  gateways	 are  doing  forwarding	 fire-
	      walling (possibly	including masquerading), and this is specified
	      using the	firewall parameters, tunnels  established  with	 IPsec
	      are  exempted from it so that packets can	flow unchanged through
	      the tunnels.  (This means	that all  subnets  connected  in  this
	      manner   must  have  distinct,  non-overlapping  subnet  address
	      blocks.)	This is	done by	the default ipsec _updown script.

	      In situations calling for	more control, it may be	preferable for
	      the user to supply his own updown	script,	which makes the	appro-
	      priate adjustments for his system.

       leftgroups = <group list>
	      a	comma separated	list of	group names. If	the leftgroups parame-
	      ter is present then the peer must	be a member of at least	one of
	      the groups defined by the	parameter.

       leftgroups2 = <group list>
	      Same as leftgroups, but for the second authentication round  de-
	      fined with leftauth2.

       lefthostaccess =	yes | no
	      inserts  a pair of INPUT and OUTPUT iptables rules using the de-
	      fault ipsec _updown script, thus allowing	access to the host it-
	      self  in the case	where the host's internal interface is part of
	      the negotiated client subnet.  Acceptable	values are yes and  no
	      (the default).

       leftid =	<id>
	      how  the	left  participant should be identified for authentica-
	      tion; defaults to	left or	the subject of the certificate config-
	      ured  with leftcert.  If leftcert	is configured the identity has
	      to be confirmed by the certificate.

	      Can be an	IP address, a fully-qualified domain  name,  an	 email
	      address  or a Distinguished Name for which the ID	type is	deter-
	      mined automatically and the string is converted to the appropri-
	      ate  encoding.  The  rules  for this conversion are described in
	      IDENTITY PARSING below.

	      In certain special situations the	identity parsing  above	 might
	      be inadequate or produce the wrong result. Examples are the need
	      to encode	a FQDN as KEY_ID or the	string parser being unable  to
	      produce the correct binary ASN.1 encoding	of a certificate's DN.
	      For these	situations it is possible to enforce a specific	 iden-
	      tity type	and to provide the binary encoding of the identity. To
	      do this a	prefix may be used, followed by	a colon	 (:).  If  the
	      number  sign (#) follows the colon, the remaining	data is	inter-
	      preted as	hex encoding, otherwise	the string is used  as	is  as
	      the  identification data.	 Note: The latter implies that no con-
	      version is performed for non-string  identities.	 For  example,
	      ipv4:10.0.0.1 does not create a valid ID_IPV4_ADDR IKE identity,
	      as it does not get converted to binary 0x0a000001. Instead,  one
	      could use	ipv4:#0a000001 to get a	valid identity,	but just using
	      the implicit type	with automatic conversion is usually  simpler.
	      The  same	applies	to the ASN.1 encoded types. The	following pre-
	      fixes are	known: ipv4, ipv6, rfc822, email, userfqdn, fqdn, dns,
	      asn1dn, asn1gn and keyid.	 Custom	type prefixes may be specified
	      by surrounding the numerical type	value by curly brackets.

	      For IKEv2	and rightid the	prefix % in front of the identity pre-
	      vents  the  daemon  from sending IDr in its IKE_AUTH request and
	      will allow it to verify the configured identity against the sub-
	      ject  and	 subjectAltNames contained in the responder's certifi-
	      cate (otherwise it is only compared with the IDr returned	by the
	      responder).   The	IDr sent by the	initiator might	otherwise pre-
	      vent the responder from finding a	config if it has configured  a
	      different	value for leftid.

       leftid2 = <id>
	      identity to use for a second authentication for the left partic-
	      ipant (IKEv2 only); defaults to leftid.

       leftikeport = <port>
	      UDP port the left	participant uses for  IKE  communication.   If
	      unspecified,  port 500 is	used with the port floating to 4500 if
	      a	NAT is detected	or MOBIKE is enabled. Specifying a  local  IKE
	      port  different  from the	default	additionally requires a	socket
	      implementation that listens on this port.

       leftprotoport = <protocol>/<port>
	      restrict the traffic selector to a single	protocol and/or	 port.
	      This  option is now deprecated, protocol/port information	can be
	      defined for each subnet directly in leftsubnet.

       leftsigkey = <raw public	key> | <path to	public key>
	      the left participant's public key	for public key	signature  au-
	      thentication,  in	 PKCS#1	format using hex (0x prefix) or	base64
	      (0s prefix) encoding. With the optional dns: or ssh:  prefix  in
	      front  of	 0x  or	0s, the	public key is expected to be in	either
	      the RFC 3110 (not	the full RR, only RSA key part)	 or  RFC  4253
	      public key format, respectively.	Also accepted is the path to a
	      file containing the public key in	PEM, DER or SSH	encoding. Both
	      absolute	paths  or paths	relative to /etc/ipsec.d/certs are ac-
	      cepted.

       leftsendcert = never | no | ifasked | always | yes
	      Accepted values are never	or no, always or yes, and ifasked (the
	      default),	 the latter meaning that the peer must send a certifi-
	      cate request payload in order to get a certificate in return.

       leftsourceip = %config4 | %config6 | <ip	address>
	      Comma separated list of internal source IPs to use in a  tunnel,
	      also  known  as  virtual IP. If the value	is one of the synonyms
	      %config, %cfg, %modeconfig, or %modecfg, an  address  (from  the
	      tunnel address family) is	requested from the peer. With %config4
	      and %config6 an address of the given address family will be  re-
	      quested  explicitly.  If an IP address is	configured, it will be
	      requested	from the responder, which is free to  respond  with  a
	      different	address.

       rightsourceip = %config | <network>/<netmask> | <from>-<to> | %poolname
	      Comma  separated	list of	internal source	IPs to use in a	tunnel
	      for the remote peer. If the value	is %config  on	the  responder
	      side, the	initiator must propose an address which	is then	echoed
	      back. Also supported are address pools expressed as network/net-
	      mask and from-to or the use of an	external IP address pool using
	      %poolname, where poolname	is the name of	the  IP	 address  pool
	      used for the lookup.

       leftsubnet = <ip	subnet>[[<proto/port>]][,...]
	      private  subnet  behind  the left	participant, expressed as net-
	      work/netmask; if omitted,	essentially  assumed  to  be  left/32,
	      signifying  that the left	end of the connection goes to the left
	      participant only.	Configured subnets of the  peers  may  differ,
	      the protocol narrows it to the greatest common subnet. In	IKEv1,
	      this may lead to problems	with other implementations, make  sure
	      to  configure  identical	subnets	 in such configurations. IKEv2
	      supports multiple	subnets	separated by commas. IKEv1 only	inter-
	      prets  the  first	 subnet	of such	a definition, unless the Cisco
	      Unity extension plugin is	enabled. This is due to	 a  limitation
	      of  the  IKEv1 protocol, which only allows a single pair of sub-
	      nets per CHILD_SA. So to tunnel several subnets a	conn entry has
	      to be defined and	brought	up for each pair of subnets.

	      The  optional part after each subnet enclosed in square brackets
	      specifies	a protocol/port	to restrict the	selector for that sub-
	      net.

	      Examples:	 leftsubnet=10.0.0.1[tcp/http],10.0.0.2[6/80] or left-
	      subnet=fec1::1[udp],10.0.0.0/16[/53].  Instead of	 omitting  ei-
	      ther  value  %any	can be used to the same	effect,	e.g.  leftsub-
	      net=fec1::1[udp/%any],10.0.0.0/16[%any/53].

	      If the protocol is icmp or ipv6-icmp the port is interpreted  as
	      ICMP  message type if it is less than 256	or as type and code if
	      it is greater or equal to	256, with the type in the most signif-
	      icant 8 bits and the code	in the least significant 8 bits.

	      The  port	value can alternatively	take the value %opaque for RFC
	      4301  OPAQUE  selectors,	or  a  numerical  range	 in  the  form
	      1024-65535.   None  of  the  kernel  backends currently supports
	      opaque or	port ranges and	uses %any for policy installation  in-
	      stead.

	      Instead  of specifying a subnet, %dynamic	can be used to replace
	      it with the IKE address, having  the  same  effect  as  omitting
	      leftsubnet completely. Using %dynamic can	be used	to define mul-
	      tiple dynamic selectors, each  having  a	potentially  different
	      protocol/port definition.

       leftupdown = <path>
	      what  ``updown''	script	to  run	to adjust routing and/or fire-
	      walling when the status of the connection	changes	(default ipsec
	      _updown).	  May include positional parameters separated by white
	      space (although this requires  enclosing	the  whole  string  in
	      quotes);	including  shell  metacharacters  is unwise.  Relevant
	      only locally, other end need not agree on	it.  Charon  uses  the
	      updown  script  to insert	firewall rules only, since routing has
	      been implemented directly	into the daemon.

       lifebytes = <number>
	      the number of bytes transmitted over an IPsec SA before  it  ex-
	      pires.

       lifepackets = <number>
	      the number of packets transmitted	over an	IPsec SA before	it ex-
	      pires.

       lifetime	= 1h | <time>
	      how long a particular instance of	a connection (a	set of encryp-
	      tion/authentication  keys	 for  user  packets) should last, from
	      successful negotiation to	expiry;	acceptable values are an inte-
	      ger  optionally  followed	 by s (a time in seconds) or a decimal
	      number followed by m, h, or d (a time in minutes,	hours, or days
	      respectively)  (default 1h, maximum 24h).	 Normally, the connec-
	      tion is renegotiated (via	the keying channel) before it  expires
	      (see  margintime).  The two ends need not	exactly	agree on life-
	      time, although if	they do	not, there will	be some	clutter	of su-
	      perseded	connections  on	 the  end which	thinks the lifetime is
	      longer. Also see EXPIRY/REKEY below.

       marginbytes = <number>
	      how many bytes before IPsec SA expiry (see lifebytes) should at-
	      tempts to	negotiate a replacement	begin.

       marginpackets = <number>
	      how many packets before IPsec SA expiry (see lifepackets)	should
	      attempts to negotiate a replacement begin.

       margintime = 9m | <time>
	      how long	before	connection  expiry  or	keying-channel	expiry
	      should  attempts	to  negotiate  a replacement begin; acceptable
	      values as	for lifetime (default  9m).   Relevant	only  locally,
	      other end	need not agree on it. Also see EXPIRY/REKEY below.

       mark = <value>[/<mask>]
	      sets  an	XFRM  mark  in	the inbound and	outbound IPsec SAs and
	      policies.	If  the	 mask  is  missing  then  a  default  mask  of
	      0xffffffff  is  assumed.	The  special  value  %unique assigns a
	      unique value to each newly created IPsec SA.

       mark_in = <value>[/<mask>]
	      sets an XFRM mark	in the inbound IPsec SA	 and  policy.  If  the
	      mask is missing then a default mask of 0xffffffff	is assumed.

       mark_out	= <value>[/<mask>]
	      sets  an	XFRM  mark in the outbound IPsec SA and	policy.	If the
	      mask is missing then a default mask of 0xffffffff	is assumed.

       mobike =	yes | no
	      enables the IKEv2	MOBIKE protocol	defined	by RFC 4555.  Accepted
	      values  are  yes (the default) and no.  If set to	no, the	charon
	      daemon will not actively propose MOBIKE as initiator and	ignore
	      the MOBIKE_SUPPORTED notify as responder.

       modeconfig = push | pull
	      defines  which  mode  is	used to	assign a virtual IP.  Accepted
	      values are push and pull (the default).  Push mode is  currently
	      not  supported with IKEv2.  The setting must be the same on both
	      sides.

       reauth =	yes | no
	      whether rekeying of an IKE_SA  should  also  reauthenticate  the
	      peer.  In	 IKEv1,	 reauthentication  is always done. In IKEv2, a
	      value of no rekeys without uninstalling the IPsec	SAs,  a	 value
	      of yes (the default) creates a new IKE_SA	from scratch and tries
	      to recreate all IPsec SAs.

       rekey = yes | no
	      whether a	connection should be renegotiated when it is about  to
	      expire; acceptable values	are yes	(the default) and no.  The two
	      ends need	not agree, but while a value  of  no  prevents	charon
	      from requesting renegotiation, it	does not prevent responding to
	      renegotiation requested from  the	 other	end,  so  no  will  be
	      largely  ineffective  unless  both  ends	agree  on it. Also see
	      reauth.

       rekeyfuzz = 100%	| <percentage>
	      maximum  percentage  by  which  marginbytes,  marginpackets  and
	      margintime  should  be  randomly increased to randomize rekeying
	      intervals	(important for hosts with many	connections);  accept-
	      able  values are an integer, which may exceed 100, followed by a
	      `%' (defaults to 100%).  The value  of  marginTYPE,  after  this
	      random  increase,	must not exceed	lifeTYPE (where	TYPE is	one of
	      bytes, packets or	time).	The value 0% will suppress  randomiza-
	      tion.   Relevant	only  locally, other end need not agree	on it.
	      Also see EXPIRY/REKEY below.

       rekeymargin
	      synonym for margintime.

       replay_window = -1 | <number>
	      The IPsec	replay window size for this connection.	With  the  de-
	      fault  of	 -1  the value configured with charon.replay_window in
	      strongswan.conf(5) is used. Larger values	than 32	are  supported
	      using  the Netlink backend only, a value of 0 disables IPsec re-
	      play protection.

       reqid = <number>
	      sets the reqid for a given connection to a pre-configured	 fixed
	      value.

       tfc = <value>
	      number  of bytes to pad ESP payload data to. Traffic Flow	Confi-
	      dentiality is currently supported	in IKEv2 and applies to	outgo-
	      ing  packets  only.  The special value %mtu fills	up ESP packets
	      with padding to have the size of the MTU.

       type = tunnel | transport | transport_proxy | passthrough | drop
	      the type of the connection; currently the	 accepted  values  are
	      tunnel  (the default) signifying a host-to-host, host-to-subnet,
	      or subnet-to-subnet tunnel; transport,  signifying  host-to-host
	      transport	 mode;	transport_proxy, signifying the	special	Mobile
	      IPv6 transport proxy mode; passthrough, signifying that no IPsec
	      processing  should be done at all; drop, signifying that packets
	      should be	discarded.

       xauth = client |	server
	      specifies	the role in the	XAuth protocol	if  activated  by  au-
	      thby=xauthpsk or authby=xauthrsasig.  Accepted values are	server
	      and client (the default).

       xauth_identity =	<id>
	      defines the identity/username the	client uses  to	 reply	to  an
	      XAuth  request.  If not defined, the IKEv1 identity will be used
	      as XAuth identity.

   CONN	PARAMETERS: IKEv2 MEDIATION EXTENSION
       The following parameters	are relevant to	IKEv2 Mediation	Extension  op-
       eration only.

       mediation = yes | no
	      whether  this  connection	is a mediation connection, ie. whether
	      this connection is used to mediate other connections.  Mediation
	      connections  create  no  child SA. Acceptable values are no (the
	      default) and yes.

       mediated_by = <name>
	      the name of the connection to mediate this  connection  through.
	      If  given, the connection	will be	mediated through the named me-
	      diation connection.  The mediation connection  must  set	media-
	      tion=yes.

       me_peerid = <id>
	      ID as which the peer is known to the mediation server, ie. which
	      the other	end of this connection uses as its leftid on its  con-
	      nection  to the mediation	server.	 This is the ID	we request the
	      mediation	server to mediate us with.  If me_peerid is not	given,
	      the rightid of this connection will be used as peer ID.

CA SECTIONS
       These  are optional sections that can be	used to	assign special parame-
       ters to a Certification Authority (CA). Because the  daemons  automati-
       cally  import  CA  certificates	from /etc/ipsec.d/cacerts, there is no
       need to explicitly add them with	a CA section, unless you want  to  as-
       sign special parameters (like a CRL) to a CA.

       also = <name>
	      includes ca section <name>.

       auto = ignore | add
	      currently	can have either	the value ignore (the default) or add.

       cacert =	<path>
	      defines  a  path	to  the	 CA  certificate  either  relative  to
	      /etc/ipsec.d/cacerts or as an absolute path.
	      A	value in the form %smartcard[<slot nr>[@<module>]]:<keyid> de-
	      fines  a	specific CA certificate	to load	from a PKCS#11 backend
	      for this CA.  See	ipsec.secrets(5) for details  about  smartcard
	      definitions.

       crluri =	<uri>
	      defines a	CRL distribution point (ldap, http, or file URI)

       crluri1
	      synonym for crluri.

       crluri2 = <uri>
	      defines  an  alternative	CRL distribution point (ldap, http, or
	      file URI)

       ocspuri = <uri>
	      defines an OCSP URI.

       ocspuri1
	      synonym for ocspuri.

       ocspuri2	= <uri>
	      defines an alternative OCSP URI.

       certuribase = <uri>
	      defines the base URI for the Hash	and URL	feature	 supported  by
	      IKEv2.   Instead	of exchanging complete certificates, IKEv2 al-
	      lows one to send an URI that resolves to the  DER	 encoded  cer-
	      tificate.	 The  certificate URIs are built by appending the SHA1
	      hash of the DER encoded certificates to this base	URI.

CONFIG SECTIONS
       At present, the only config section known to the	IPsec software is  the
       one  named  setup, which	contains information used when the software is
       being started.  The currently-accepted  parameter  names	 in  a	config
       setup section are:

       cachecrls = yes | no
	      if enabled, certificate revocation lists (CRLs) fetched via HTTP
	      or LDAP will be cached in	/etc/ipsec.d/crls/ under a unique file
	      name derived from	the certification authority's public key.

       charondebug = <debug list>
	      how much charon debugging	output should be logged.  A comma sep-
	      arated list containing type/level-pairs may be  specified,  e.g:
	      dmn 3, ike 1, net	-1.  Acceptable	values for types are dmn, mgr,
	      ike, chd,	job, cfg, knl, net, asn, enc, lib, esp,	tls, tnc, imc,
	      imv,  pts	and the	level is one of	-1, 0, 1, 2, 3,	4 (for silent,
	      audit, control, controlmore, raw,	 private).   By	 default,  the
	      level  is	set to 1 for all types.	 For more flexibility see LOG-
	      GER CONFIGURATION	in strongswan.conf(5).

       strictcrlpolicy = yes | ifuri | no
	      defines if a fresh CRL must be available in order	for  the  peer
	      authentication  based on RSA signatures to succeed.  IKEv2 addi-
	      tionally recognizes ifuri	which reverts to yes if	at  least  one
	      CRL URI is defined and to	no if no URI is	known.

       uniqueids = yes | no | never | replace |	keep
	      whether  a particular participant	ID should be kept unique, with
	      any new IKE_SA using an ID deemed	to replace all old ones	 using
	      that  ID;	acceptable values are yes (the default), no and	never.
	      Participant IDs normally are unique, so a	new IKE_SA  using  the
	      same ID is almost	invariably intended to replace an old one. The
	      difference between no and	never is that the daemon will  replace
	      old  IKE_SAs when	receiving an INITIAL_CONTACT notify if the op-
	      tion is no but will ignore these notifies	if  never  is  config-
	      ured.   The daemon also accepts the value	replace	which is iden-
	      tical to yes and the value keep to reject	new IKE_SA setups  and
	      keep the duplicate established earlier.

IDENTITY PARSING
       The  type  and  binary encoding of identity strings specified in	leftid
       are detected as follows:

       o      If the string value contains an equal sign (=) it	is assumed  to
	      be  a  Distinguished  Name, with RDNs separated by commas	(,) or
	      slashes (/ - the string must start with a	slash to use this syn-
	      tax).  An	attempt	is made	to create a binary ASN.1 encoding from
	      this string. If that fails the type is set to  KEY_ID  with  the
	      literal string value adopted as encoding.

       o      If  the string value contains an @ the type depends on the posi-
	      tion of that character:

	      o	     If	the string begins with @# the type is  set  to	KEY_ID
		     and the string following that prefix is assumed to	be the
		     hex-encoded binary	value of the identity.

	      o	     If	the string begins with @@ the type is set to USER_FQDN
		     and the encoding is the literal string after that prefix.

	      o	     If	 the  string begins with @ the type is set to FQDN and
		     the encoding is the literal string	after that prefix.

	      o	     All remaining strings containing an @ are assumed	to  be
		     of	type USER_FQDN/RFC822 with the literal string value as
		     encoding.

       o      If the value does	not contain any	@ or = characters it is	parsed
	      as follows:

	      o	     If	 the  value  is	 an  empty  string, or equals %any[6],
		     0.0.0.0, ::, or *	the  type  is  set  to	ID_ANY,	 which
		     matches any other identity.

	      o	     If	 the value contains a colon (:)	it is assumed to be an
		     IPv6 address. But if parsing the address  and  converting
		     it	to its binary encoding fails the type is set to	KEY_ID
		     and the encoding is the literal value.

	      o	     For all other strings an attempt at parsing them as  IPv4
		     addresses	is made. If that fails the type	is set to FQDN
		     and the literal value is adopted  as  encoding  (this  is
		     where domain names	and simple names end up).

SA EXPIRY/REKEY
       The IKE SAs and IPsec SAs negotiated by the daemon can be configured to
       expire after a specific amount of time. For IPsec  SAs  this  can  also
       happen  after  a	specified number of transmitted	packets	or transmitted
       bytes. The following settings can be used to configure this:

       Setting	       Default	 Setting	 Default
       --------------------------------------------------
       IKE SA			 IPsec SA
	ikelifetime	    3h	  lifebytes	       -
				  lifepackets	       -
				  lifetime	      1h

   Rekeying
       IKE SAs as well as IPsec	SAs can	be rekeyed before  they	 expire.  This
       can be configured using the following settings:

       Setting	      Default	Setting		  Default
       ---------------------------------------------------
       IKE and IPsec SA		IPsec SA
	margintime	   9m	 marginbytes		-
				 marginpackets		-

   Randomization
       To avoid	collisions the specified margins are increased randomly	before
       subtracting them	from the expiration limits (see	formula	 below).  This
       is controlled by	the rekeyfuzz setting:

       Setting	     Default
       ----------------------
       IKE and IPsec SA
	rekeyfuzz	100%

       Randomization can be disabled by	setting	rekeyfuzz to 0%.

   Formula
       The following formula is	used to	calculate the rekey time of IPsec SAs:

	rekeytime = lifetime - (margintime + random(0, margintime * rekeyfuzz))

       It applies equally to IKE SAs and byte and packet limits	for IPsec SAs.

   Example
       Let's consider the default configuration:

		  lifetime = 1h
		  margintime = 9m
		  rekeyfuzz = 100%

       From the	formula	above follows that the rekey time lies between:

		  rekeytime_min	= 1h - (9m + 9m) = 42m
		  rekeytime_max	= 1h - (9m + 0m) = 51m

       Thus,  the  daemon  will	attempt	to rekey the IPsec SA at a random time
       between 42 and 51 minutes after	establishing  the  SA.	Or,  in	 other
       words, between 9	and 18 minutes before the SA expires.

   Notes
       o      Since  the  rekeying of an SA needs some time, the margin	values
	      must not be too low.

       o      The value	margin... + margin... *	rekeyfuzz must not exceed  the
	      original	limit. For example, specifying margintime = 30m	in the
	      default configuration is a bad idea as there is  a  chance  that
	      the rekey	time equals zero and, thus, rekeying gets disabled.

FILES
       /etc/ipsec.conf
       /etc/ipsec.d/aacerts
       /etc/ipsec.d/acerts
       /etc/ipsec.d/cacerts
       /etc/ipsec.d/certs
       /etc/ipsec.d/crls

SEE ALSO
       strongswan.conf(5), ipsec.secrets(5), ipsec(8)

HISTORY
       Originally written for the FreeS/WAN project by Henry Spencer.  Updated
       and extended for	the strongSwan project <http://www.strongswan.org>  by
       Tobias Brunner, Andreas Steffen and Martin Willi.

5.5.2				  2012-06-26			 IPSEC.CONF(5)

NAME | DESCRIPTION | CONN SECTIONS | CA SECTIONS | CONFIG SECTIONS | IDENTITY PARSING | SA EXPIRY/REKEY | FILES | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ipsec.conf&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help