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.

       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. If no activity  is	detected,  all
	      connections  with	 a dead	peer are stopped and unrouted (clear),
	      put in the hold state (hold) or restarted	 (restart).   The  de-
	      fault 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-sha1,3des-sha1.  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!
	      If dh-group is specified,	CHILD_SA/Quick Mode setup and rekeying
	      include a	separate Diffie-Hellman	exchange.   Valid  values  for
	      esnmode (IKEv2 only) are esn and noesn.  Specifying both negoti-
	      ates Extended Sequence Number support with the peer, the default
	      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, force and no	(the default). 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-sha1-modp2048.  The notation
	      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-modp1536-modp2048,3des-
	      sha1-md5-modp1024.

	      Defaults to aes128-sha1-modp2048,3des-sha1-modp1536.  The	daemon
	      adds  its	extensive default proposal to this default or the con-
	      figured value.  To restrict it to	the configured proposal	an ex-
	      clamation	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.

	      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)  such	key types and hash algorithms are also
	      applied as constraints against  IKEv2  signature	authentication
	      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.
	      For example, with	pubkey-sha384-sha256 a	public	key  signature
	      scheme with either SHA-384 or SHA-256 would get used for authen-
	      tication,	in that	order and depending  on	 the  hash  algorithms
	      supported	 by the	peer.  If no specific hash algorithms are con-
	      figured, the default is to prefer	an algorithm that  matches  or
	      exceeds the strength of the signature key.

	      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. To enforce a specific identity type, a prefix  may
	      be used, followed	by a colon (:).	If the number sign (#) follows
	      the colon, the remaining data is interpreted  as	hex  encoding,
	      otherwise	 the  string is	used as-is as the identification data.
	      Note that	this implies that no conversion	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	 auto-
	      matic  conversion	 is  usually  simpler. The same	applies	to the
	      ASN1 encoded types. The  following  prefixes  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.

	      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.

       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.

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.3.2				  2012-06-26			 IPSEC.CONF(5)

NAME | DESCRIPTION | CONN SECTIONS | CA SECTIONS | CONFIG SECTIONS | 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+10.2-RELEASE+and+Ports>

home | help