1IPSEC.CONF(5) strongSwan IPSEC.CONF(5)
2
6 ipsec.conf - IPsec configuration and connections
7
9 The optional ipsec.conf file specifies most configuration and control
10 information for the strongSwan IPsec subsystem. The major exception is
11 secrets for authentication; see ipsec.secrets(5). Its contents are not
12 security-sensitive.
13 The file is a text file, consisting of one or more sections. White
15 space followed by # followed by anything to the end of the line is a
16 comment and is ignored, as are empty lines which are not within a sec‐
17 tion.
18 A line which contains include and a file name, separated by white
20 space, is replaced by the contents of that file. If the file name is
21 not a full pathname, it is considered to be relative to the directory
22 containing the including file. Such inclusions can be nested. Only a
23 single filename may be supplied, and it may not contain white space,
24 but it may include shell wildcards (see sh(1)); for example:
25 include ipsec.*.conf
27 The intention of the include facility is mostly to permit keeping in‐
29 formation on connections, or sets of connections, separate from the
30 main configuration file. This permits such connection descriptions to
31 be changed, copied to the other security gateways involved, etc., with‐
32 out having to constantly extract them from the configuration file and
33 then insert them back into it. Note also the also parameter (described
34 below) which permits splitting a single logical section (e.g. a connec‐
35 tion description) into several actual sections.
36 A section begins with a line of the form:
38 type name
40 where type indicates what type of section follows, and name is an arbi‐
42 trary name which distinguishes the section from others of the same
43 type. All subsequent non-empty lines which begin with white space are
44 part of the section. Sections of the same type that share the same
45 name are merged.
46 Lines within the section are generally of the form
48 parameter=value
50 (note the mandatory preceding white space). There can be white space
52 on either side of the =. Parameter names are specific to a section
53 type.
54 An empty value stands for the system default value (if any) of the pa‐
56 rameter, i.e. it is roughly equivalent to omitting the parameter line
57 entirely. This may be useful to clear a setting inherited from a %de‐
58 fault section or via also parameter (see below). A value may contain
59 single spaces (additional white space is reduced to one space). To
60 preserve white space as written enclose the entire value in double
61 quotes ("); in such values double quotes themselves may be escaped by
62 prefixing them with \ characters. A double-quoted string may span mul‐
63 tiple lines by ending them with \ characters (following lines don't
64 have to begin with white space, as that will be preserved). Addition‐
65 ally, the following control characters may be encoded in double-quoted
66 strings: \n, \r, \t, \b, \f.
67 Numeric values are specified to be either an ``integer'' (a sequence of
69 digits) or a ``decimal number'' (sequence of digits optionally followed
70 by `.' and another sequence of digits).
71 There is currently one parameter which is available in any type of sec‐
73 tion:
74 also the value is a section name; the parameters of that section are
76 inherited by the current section. Parameters in the current sec‐
77 tion always override inherited parameters, even if an also fol‐
78 lows after them. The specified section must exist and must have
79 the same section type; it doesn't if it is defined before or af‐
80 ter the current section. Nesting is permitted, and there may be
81 more than one also in a single section (parameters from refer‐
82 enced sections are inherited and overridden in the order of
83 these also parameters).
84 A section with name %default specifies defaults for sections of the
86 same type. All parameters in it, are inherited by all other sections of
87 that type.
88 Currently there are three types of sections: a config section specifies
90 general configuration information for IPsec, a conn section specifies
91 an IPsec connection, while a ca section specifies special properties of
92 a certification authority.
93
95 A conn section contains a connection specification, defining a network
96 connection to be made using IPsec. The name given is arbitrary, and is
97 used to identify the connection. Here's a simple example:
98 conn snt
100 left=192.168.0.1
101 leftsubnet=10.1.0.0/16
102 right=192.168.0.2
103 rightsubnet=10.1.0.0/16
104 keyingtries=%forever
105 auto=add
106 A note on terminology: There are two kinds of communications going on:
108 transmission of user IP packets, and gateway-to-gateway negotiations
109 for keying, rekeying, and general control. The path to control the
110 connection is called 'ISAKMP SA' in IKEv1 and 'IKE SA' in the IKEv2
111 protocol. That what is being negotiated, the kernel level data path, is
112 called 'IPsec SA' or 'Child SA'. strongSwan previously used two sepa‐
113 rate keying daemons, pluto and charon. This manual does not discuss
114 pluto options anymore, but only charon that since strongSwan 5.0 sup‐
115 ports both IKEv1 and IKEv2.
116 To avoid trivial editing of the configuration file to suit it to each
118 system involved in a connection, connection specifications are written
119 in terms of left and right participants, rather than in terms of local
120 and remote. Which participant is considered left or right is arbi‐
121 trary; for every connection description an attempt is made to figure
122 out whether the local endpoint should act as the left or right end‐
123 point. This is done by matching the IP addresses defined for both end‐
124 points with the IP addresses assigned to local network interfaces. If a
125 match is found then the role (left or right) that matches is going to
126 be considered local. If no match is found during startup, left is con‐
127 sidered local. This permits using identical connection specifications
128 on both ends. There are cases where there is no symmetry; a good con‐
129 vention is to use left for the local side and right for the remote side
130 (the first letters are a good mnemonic).
131 Many of the parameters relate to one participant or the other; only the
133 ones for left are listed here, but every parameter whose name begins
134 with left has a right counterpart, whose description is the same but
135 with left and right reversed.
136 Parameters are optional unless marked '(required)'.
138 CONN PARAMETERS
140 Unless otherwise noted, for a connection to work, in general it is nec‐
141 essary for the two ends to agree exactly on the values of these parame‐
142 ters.
143 aaa_identity = <id>
145 defines the identity of the AAA backend used during IKEv2 EAP
146 authentication. This is required if the EAP client uses a
147 method that verifies the server identity (such as EAP-TLS), but
148 it does not match the IKEv2 gateway identity.
149 aggressive = yes | no
151 whether to use IKEv1 Aggressive or Main Mode (the default).
152 ah = <cipher suites>
154 comma-separated list of AH algorithms to be used for the connec‐
155 tion, e.g. sha1-sha256-modp1024. The notation is integ‐
156 rity[-dhgroup]. For IKEv2, multiple algorithms (separated by -)
157 of the same type can be included in a single proposal. IKEv1
158 only includes the first algorithm in a proposal. Only either
159 the ah or esp keyword may be used, AH+ESP bundles are not sup‐
160 ported.
161 There is no default AH cipher suite since by default ESP is
163 used. The daemon adds its extensive default proposal to the
164 configured value. To restrict it to the configured proposal an
165 exclamation mark (!) can be added at the end.
166 If dh-group is specified, CHILD_SA/Quick Mode setup and rekeying
168 include a separate Diffie-Hellman exchange (refer to the esp
169 keyword for details).
170 also = <name>
172 includes conn section <name>.
173 auth = <value>
175 was used by the pluto IKEv1 daemon to use AH integrity protec‐
176 tion for ESP encrypted packets, but is not supported in charon.
177 The ah keyword specifies algorithms to use for integrity protec‐
178 tion with AH, but without encryption. AH+ESP bundles are not
179 supported.
180 authby = pubkey | rsasig | ecdsasig | psk | secret | never | xauthpsk |
182 xauthrsasig
183 how the two security gateways should authenticate each other;
184 acceptable values are psk or secret for pre-shared secrets, pub‐
185 key (the default) for public key signatures as well as the syn‐
186 onyms rsasig for RSA digital signatures and ecdsasig for Ellip‐
187 tic Curve DSA signatures. never can be used if negotiation is
188 never to be attempted or accepted (useful for shunt-only conns).
189 Digital signatures are superior in every way to shared secrets.
190 IKEv1 additionally supports the values xauthpsk and xauthrsasig
191 that will enable eXtended AUTHentication (XAUTH) in addition to
192 IKEv1 main mode based on shared secrets or digital RSA signa‐
193 tures, respectively. This parameter is deprecated, as two peers
194 do not need to agree on an authentication method in IKEv2. Use
195 the leftauth parameter instead to define authentication methods.
196 auto = ignore | add | route | start
198 what operation, if any, should be done automatically at IPsec
199 startup; currently-accepted values are add, route, start and ig‐
200 nore (the default). add loads a connection without starting it.
201 route loads a connection and installs kernel traps. If traffic
202 is detected between leftsubnet and rightsubnet, a connection is
203 established. start loads a connection and brings it up immedi‐
204 ately. ignore ignores the connection. This is equal to deleting
205 a connection from the config file. Relevant only locally, other
206 end need not agree on it.
207 closeaction = none | clear | hold | restart
209 defines the action to take if the remote peer unexpectedly
210 closes a CHILD_SA (see dpdaction for meaning of values). A
211 closeaction should not be used if the peer uses reauthentication
212 or uniqueids checking, as these events might trigger the defined
213 action when not desired.
214 compress = yes | no
216 whether IPComp compression of content is proposed on the connec‐
217 tion (link-level compression does not work on encrypted data, so
218 to be effective, compression must be done before encryption);
219 acceptable values are yes and no (the default). A value of yes
220 causes the daemon to propose both compressed and uncompressed,
221 and prefer compressed. A value of no prevents the daemon from
222 proposing or accepting compression.
223 dpdaction = none | clear | hold | restart
225 controls the use of the Dead Peer Detection protocol (DPD, RFC
226 3706) where R_U_THERE notification messages (IKEv1) or empty IN‐
227 FORMATIONAL messages (IKEv2) are periodically sent in order to
228 check the liveliness of the IPsec peer. The values clear, hold,
229 and restart all activate DPD and determine the action to perform
230 on a timeout. With clear the connection is closed with no fur‐
231 ther actions taken. hold installs a trap policy, which will
232 catch matching traffic and tries to re-negotiate the connection
233 on demand. restart will immediately trigger an attempt to re-
234 negotiation the connection. The default is none which disables
235 the active sending of DPD messages.
236 dpddelay = 30s | <time>
238 defines the period time interval with which R_U_THERE mes‐
239 sages/INFORMATIONAL exchanges are sent to the peer. These are
240 only sent if no other traffic is received. In IKEv2, a value of
241 0 sends no additional INFORMATIONAL messages and uses only stan‐
242 dard messages (such as those to rekey) to detect dead peers.
243 dpdtimeout = 150s | <time>
245 defines the timeout interval, after which all connections to a
246 peer are deleted in case of inactivity. This only applies to
247 IKEv1, in IKEv2 the default retransmission timeout applies, as
248 every exchange is used to detect dead peers.
249 inactivity = <time>
251 defines the timeout interval, after which a CHILD_SA is closed
252 if it did not send or receive any traffic. The inactivity
253 counter is reset during CHILD_SA rekeying. This means that the
254 inactivity timeout must be smaller than the rekeying interval to
255 have any effect.
256 eap_identity = <id>
258 defines the identity the client uses to reply to an EAP Identity
259 request. If defined on the EAP server, the defined identity
260 will be used as peer identity during EAP authentication. The
261 special value %identity uses the EAP Identity method to ask the
262 client for an EAP identity. If not defined, the IKEv2 identity
263 will be used as EAP identity.
264 esp = <cipher suites>
266 comma-separated list of ESP encryption/authentication algorithms
267 to be used for the connection, e.g. aes128-sha256. The nota‐
268 tion is encryption-integrity[-dhgroup][-esnmode]. For IKEv2,
269 multiple algorithms (separated by -) of the same type can be in‐
270 cluded in a single proposal. IKEv1 only includes the first algo‐
271 rithm in a proposal. Only either the ah or esp keyword may be
272 used, AH+ESP bundles are not supported.
273 Defaults to aes128-sha256. The daemon adds its extensive de‐
275 fault proposal to this default or the configured value. To re‐
276 strict it to the configured proposal an exclamation mark (!)
277 can be added at the end.
278 Note: As a responder, the daemon defaults to selecting the first
280 configured proposal that's also supported by the peer. This may
281 be changed via strongswan.conf(5) to selecting the first accept‐
282 able proposal sent by the peer instead. In order to restrict a
283 responder to only accept specific cipher suites, the strict flag
284 (!, exclamation mark) can be used, e.g: aes256-sha512-modp4096!
285 If dh-group is specified, CHILD_SA/Quick Mode rekeying and ini‐
287 tial negotiation use a separate Diffie-Hellman exchange using
288 the specified group. However, for IKEv2, the keys of the
289 CHILD_SA created implicitly with the IKE_SA will always be de‐
290 rived from the IKE_SA's key material. So any DH group specified
291 here will only apply when the CHILD_SA is later rekeyed or is
292 created with a separate CREATE_CHILD_SA exchange. Therefore, a
293 proposal mismatch might not immediately be noticed when the SA
294 is established, but may later cause rekeying to fail.
295 Valid values for esnmode are esn and noesn. Specifying both ne‐
297 gotiates Extended Sequence Number support with the peer, the de‐
298 fault is noesn.
299 forceencaps = yes | no
301 force UDP encapsulation for ESP packets even if no NAT situation
302 is detected. This may help to surmount restrictive firewalls.
303 In order to force the peer to encapsulate packets, NAT detection
304 payloads are faked.
305 fragmentation = yes | accept | force | no
307 whether to use IKE fragmentation (proprietary IKEv1 extension or
308 IKEv2 fragmentation as per RFC 7383). Acceptable values are yes
309 (the default), accept, force and no. If set to yes, and the
310 peer supports it, oversized IKE messages will be sent in frag‐
311 ments. If set to accept, support for fragmentation is announced
312 to the peer but the daemon does not send its own messages in
313 fragments. If set to force (only supported for IKEv1) the ini‐
314 tial IKE message will already be fragmented if required. Fi‐
315 nally, setting the option to no will disable announcing support
316 for this feature.
317 Note that fragmented IKE messages sent by a peer are always ac‐
319 cepted irrespective of the value of this option (even when set
320 to no).
321 ike = <cipher suites>
323 comma-separated list of IKE/ISAKMP SA encryption/authentication
324 algorithms to be used, e.g. aes128-sha256-modp3072. The nota‐
325 tion is encryption-integrity[-prf]-dhgroup. If no PRF is given,
326 the algorithms defined for integrity are used for the PRF. The
327 prf keywords are the same as the integrity algorithms, but have
328 a prf prefix (such as prfsha1, prfsha256 or prfaesxcbc).
329 In IKEv2, multiple algorithms and proposals may be included,
330 such as aes128-aes256-sha1-modp3072-modp2048,3des-
331 sha1-md5-modp1024.
332 Defaults to aes128-sha256-modp3072. The daemon adds its exten‐
334 sive default proposal to this default or the configured value.
335 To restrict it to the configured proposal an exclamation mark
336 (!) can be added at the end.
337 Note: As a responder the daemon accepts the first supported pro‐
339 posal received from the peer. In order to restrict a responder
340 to only accept specific cipher suites, the strict flag (!, ex‐
341 clamation mark) can be used, e.g: aes256-sha512-modp4096!
342 ikedscp = 000000 | <DSCP field>
344 Differentiated Services Field Codepoint to set on outgoing IKE
345 packets sent from this connection. The value is a six digit bi‐
346 nary encoded string defining the Codepoint to set, as defined in
347 RFC 2474.
348 ikelifetime = 3h | <time>
350 how long the keying channel of a connection (ISAKMP or IKE SA)
351 should last before being renegotiated. Also see EXPIRY/REKEY be‐
352 low.
353 installpolicy = yes | no
355 decides whether IPsec policies are installed in the kernel by
356 the charon daemon for a given connection. Allows peaceful coop‐
357 eration e.g. with the Mobile IPv6 daemon mip6d who wants to con‐
358 trol the kernel policies. Acceptable values are yes (the de‐
359 fault) and no.
360 keyexchange = ike | ikev1 | ikev2
362 which key exchange protocol should be used to initiate the con‐
363 nection. Connections marked with ike use IKEv2 when initiating,
364 but accept any protocol version when responding.
365 keyingtries = 3 | <number> | %forever
367 how many attempts (a whole number or %forever) should be made to
368 negotiate a connection, or a replacement for one, before giving
369 up (default 3). The value %forever means 'never give up'. Rel‐
370 evant only locally, other end need not agree on it.
371 left = <ip address> | <fqdn> | %any | <range> | <subnet>
373 The IP address of the left participant's public-network inter‐
374 face or one of several magic values. The value %any (the de‐
375 fault) for the local endpoint signifies an address to be filled
376 in (by automatic keying) during negotiation. If the local peer
377 initiates the connection setup the routing table will be queried
378 to determine the correct local IP address. In case the local
379 peer is responding to a connection setup then any IP address
380 that is assigned to a local interface will be accepted.
381 The prefix % in front of a fully-qualified domain name or an IP
383 address will implicitly set leftallowany=yes.
384 If %any is used for the remote endpoint it literally means any
386 IP address.
387 If an FQDN is assigned it is resolved every time a configuration
389 lookup is done. If DNS resolution times out, the lookup is de‐
390 layed for that time.
391 To limit the connection to a specific range of hosts, a range (
393 10.1.0.0-10.2.255.255 ) or a subnet ( 10.1.0.0/16 ) can be spec‐
394 ified, and multiple addresses, ranges and subnets can be sepa‐
395 rated by commas. While one can freely combine these items, to
396 initiate the connection at least one non-range/subnet is re‐
397 quired.
398 Please note that with the usage of wildcards multiple connection
400 descriptions might match a given incoming connection attempt.
401 The most specific description is used in that case.
402 leftallowany = yes | no
404 a modifier for left, making it behave as %any although a con‐
405 crete IP address or domain name has been assigned.
406 leftauth = <auth method>
408 Authentication method to use locally (left) or require from the
409 remote (right) side. Acceptable values are pubkey for public
410 key authentication (RSA/ECDSA), psk for pre-shared key authenti‐
411 cation, eap to (require the) use of the Extensible Authentica‐
412 tion Protocol in IKEv2, and xauth for IKEv1 eXtended Authentica‐
413 tion.
414 To require a trustchain public key strength for the remote side,
416 specify the key type followed by the minimum strength in bits
417 (for example ecdsa-384 or rsa-2048-ecdsa-256). To limit the ac‐
418 ceptable set of hashing algorithms for trustchain validation,
419 append hash algorithms to pubkey or a key strength definition
420 (for example pubkey-sha256-sha512,
421 rsa-2048-sha256-sha384-sha512, or
422 rsa-2048-sha256-ecdsa-256-sha256-sha384). Unless disabled in
423 strongswan.conf(5), or explicit IKEv2 signature constraints are
424 configured (see below), such key types and hash algorithms are
425 also applied as constraints against IKEv2 signature authentica‐
426 tion schemes used by the remote side.
427 If both peers support RFC 7427 ("Signature Authentication in
429 IKEv2") specific hash algorithms to be used during IKEv2 authen‐
430 tication may be configured. The syntax is the same as above,
431 but with ike: prefix. For example, with ike:pubkey-sha384-sha256
432 a public key signature scheme with either SHA-384 or SHA-256
433 would get used for authentication, in that order and depending
434 on the hash algorithms supported by the peer. If no specific
435 hash algorithms are configured, the default is to prefer an al‐
436 gorithm that matches or exceeds the strength of the signature
437 key. If no constraints with ike: prefix are configured any sig‐
438 nature scheme constraint (without ike: prefix) will also apply
439 to IKEv2 authentication, unless this is disabled in
440 strongswan.conf(5).
441 To use or require RSASSA-PSS signatures use rsa/pss instead of
443 rsa as in e.g. ike:rsa/pss-sha256. If pubkey or rsa con‐
444 straints are configured RSASSA-PSS signatures will only be
445 used/accepted if enabled in strongswan.conf(5).
446 For eap, an optional EAP method can be appended. Currently de‐
448 fined methods are eap-aka, eap-gtc, eap-md5, eap-mschapv2, eap-
449 peap, eap-sim, eap-tls, eap-ttls, eap-dynamic, and eap-radius.
450 Alternatively, IANA assigned EAP method numbers are accepted.
451 Vendor specific EAP methods are defined in the form eap-type-
452 vendor (e.g. eap-7-12345). To specify signature and trust chain
453 constraints for EAP-(T)TLS, append a colon to the EAP method,
454 followed by the key type/size and hash algorithm as discussed
455 above. For xauth, an XAuth authentication backend can be speci‐
456 fied, such as xauth-generic or xauth-eap. If XAuth is used in
457 leftauth, Hybrid authentication is used. For traditional XAuth
458 authentication, define XAuth in lefauth2.
459 leftauth2 = <auth method>
461 Same as leftauth, but defines an additional authentication ex‐
462 change. In IKEv1, only XAuth can be used in the second authenti‐
463 cation round. IKEv2 supports multiple complete authentication
464 rounds using "Multiple Authentication Exchanges" defined in RFC
465 4739. This allows, for example, separated authentication of host
466 and user.
467 leftca = <issuer dn> | %same
469 the distinguished name of a certificate authority which is re‐
470 quired to lie in the trust path going from the left partici‐
471 pant's certificate up to the root certification authority.
472 %same means that the value configured for the right participant
473 should be reused.
474 leftca2 = <issuer dn> | %same
476 Same as leftca, but for the second authentication round (IKEv2
477 only).
478 leftcert = <path>
480 the path to the left participant's X.509 certificate. The file
481 can be encoded either in PEM or DER format. OpenPGP certificates
482 are supported as well. Both absolute paths or paths relative to
483 /etc/ipsec.d/certs are accepted. By default leftcert sets leftid
484 to the distinguished name of the certificate's subject. The
485 left participant's ID can be overridden by specifying a leftid
486 value which must be certified by the certificate, though.
487 A value in the form %smartcard[<slot nr>[@<module>]]:<keyid> de‐
488 fines a specific certificate to load from a PKCS#11 backend for
489 this connection. See ipsec.secrets(5) for details about smart‐
490 card definitions. leftcert is required only if selecting the
491 certificate with leftid is not sufficient, for example if multi‐
492 ple certificates use the same subject.
493 Multiple certificate paths or PKCS#11 backends can be specified
494 in a comma separated list. The daemon chooses the certificate
495 based on the received certificate requests if possible before
496 enforcing the first.
497 leftcert2 = <path>
499 Same as leftcert, but for the second authentication round (IKEv2
500 only).
501 leftcertpolicy = <OIDs>
503 Comma separated list of certificate policy OIDs the peer's cer‐
504 tificate must have. OIDs are specified using the numerical dot‐
505 ted representation.
506 leftdns = <servers>
508 Comma separated list of DNS server addresses to exchange as con‐
509 figuration attributes. On the initiator, a server is a fixed
510 IPv4/IPv6 address, or %config4/%config6 to request attributes
511 without an address. On the responder, only fixed IPv4/IPv6 ad‐
512 dresses are allowed and define DNS servers assigned to the
513 client.
514 leftfirewall = yes | no
516 whether the left participant is doing forwarding-firewalling
517 (including masquerading) using iptables for traffic from left‐
518 subnet, which should be turned off (for traffic to the other
519 subnet) once the connection is established; acceptable values
520 are yes and no (the default). May not be used in the same con‐
521 nection description with leftupdown. Implemented as a parameter
522 to the default ipsec _updown script. See notes below. Relevant
523 only locally, other end need not agree on it.
524 If one or both security gateways are doing forwarding fire‐
526 walling (possibly including masquerading), and this is specified
527 using the firewall parameters, tunnels established with IPsec
528 are exempted from it so that packets can flow unchanged through
529 the tunnels. (This means that all subnets connected in this
530 manner must have distinct, non-overlapping subnet address
531 blocks.) This is done by the default ipsec _updown script.
532 In situations calling for more control, it may be preferable for
534 the user to supply his own updown script, which makes the appro‐
535 priate adjustments for his system.
536 leftgroups = <group list>
538 a comma separated list of group names. If the leftgroups parame‐
539 ter is present then the peer must be a member of at least one of
540 the groups defined by the parameter.
541 leftgroups2 = <group list>
543 Same as leftgroups, but for the second authentication round de‐
544 fined with leftauth2.
545 lefthostaccess = yes | no
547 inserts a pair of INPUT and OUTPUT iptables rules using the de‐
548 fault ipsec _updown script, thus allowing access to the host it‐
549 self in the case where the host's internal interface is part of
550 the negotiated client subnet. Acceptable values are yes and no
551 (the default).
552 leftid = <id>
554 how the left participant should be identified for authentica‐
555 tion; defaults to left or the subject of the certificate config‐
556 ured with leftcert. If leftcert is configured the identity has
557 to be confirmed by the certificate.
558 Can be an IP address, a fully-qualified domain name, an email
560 address or a Distinguished Name for which the ID type is deter‐
561 mined automatically and the string is converted to the appropri‐
562 ate encoding. The rules for this conversion are described in
563 IDENTITY PARSING below.
564 In certain special situations the identity parsing above might
566 be inadequate or produce the wrong result. Examples are the need
567 to encode a FQDN as KEY_ID or the string parser being unable to
568 produce the correct binary ASN.1 encoding of a certificate's DN.
569 For these situations it is possible to enforce a specific iden‐
570 tity type and to provide the binary encoding of the identity. To
571 do this a prefix may be used, followed by a colon (:). If the
572 number sign (#) follows the colon, the remaining data is inter‐
573 preted as hex encoding, otherwise the string is used as is as
574 the identification data. Note: The latter implies that no con‐
575 version is performed for non-string identities. For example,
576 ipv4:10.0.0.1 does not create a valid ID_IPV4_ADDR IKE identity,
577 as it does not get converted to binary 0x0a000001. Instead, one
578 could use ipv4:#0a000001 to get a valid identity, but just using
579 the implicit type with automatic conversion is usually simpler.
580 The same applies to the ASN.1 encoded types. The following pre‐
581 fixes are known: ipv4, ipv6, rfc822, email, userfqdn, fqdn, dns,
582 asn1dn, asn1gn and keyid. Custom type prefixes may be specified
583 by surrounding the numerical type value by curly brackets.
584 For IKEv2 and rightid the prefix % in front of the identity pre‐
586 vents the daemon from sending IDr in its IKE_AUTH request and
587 will allow it to verify the configured identity against the sub‐
588 ject and subjectAltNames contained in the responder's certifi‐
589 cate (otherwise it is only compared with the IDr returned by the
590 responder). The IDr sent by the initiator might otherwise pre‐
591 vent the responder from finding a config if it has configured a
592 different value for leftid.
593 leftid2 = <id>
595 identity to use for a second authentication for the left partic‐
596 ipant (IKEv2 only); defaults to leftid.
597 leftikeport = <port>
599 UDP port the left participant uses for IKE communication. If
600 unspecified, port 500 is used with the port floating to 4500 if
601 a NAT is detected or MOBIKE is enabled. Specifying a local IKE
602 port different from the default additionally requires a socket
603 implementation that listens on this port.
604 leftprotoport = <protocol>/<port>
606 restrict the traffic selector to a single protocol and/or port.
607 This option is now deprecated, protocol/port information can be
608 defined for each subnet directly in leftsubnet.
609 leftsigkey = <raw public key> | <path to public key>
611 the left participant's public key for public key signature au‐
612 thentication, in PKCS#1 format using hex (0x prefix) or base64
613 (0s prefix) encoding. With the optional dns: or ssh: prefix in
614 front of 0x or 0s, the public key is expected to be in either
615 the RFC 3110 (not the full RR, only RSA key part) or RFC 4253
616 public key format, respectively. Also accepted is the path to a
617 file containing the public key in PEM, DER or SSH encoding. Both
618 absolute paths or paths relative to /etc/ipsec.d/certs are ac‐
619 cepted.
620 leftsendcert = never | no | ifasked | always | yes
622 Accepted values are never or no, always or yes, and ifasked (the
623 default), the latter meaning that the peer must send a certifi‐
624 cate request payload in order to get a certificate in return.
625 leftsourceip = %config4 | %config6 | <ip address>
627 Comma separated list of internal source IPs to use in a tunnel,
628 also known as virtual IP. If the value is one of the synonyms
629 %config, %cfg, %modeconfig, or %modecfg, an address (from the
630 tunnel address family) is requested from the peer. With %config4
631 and %config6 an address of the given address family will be re‐
632 quested explicitly. If an IP address is configured, it will be
633 requested from the responder, which is free to respond with a
634 different address.
635 rightsourceip = %config | <network>/<netmask> | <from>-<to> | %poolname
637 Comma separated list of internal source IPs to use in a tunnel
638 for the remote peer. If the value is %config on the responder
639 side, the initiator must propose an address which is then echoed
640 back. Also supported are address pools expressed as network/net‐
641 mask and from-to or the use of an external IP address pool using
642 %poolname, where poolname is the name of the IP address pool
643 used for the lookup.
644 leftsubnet = <ip subnet>[[<proto/port>]][,...]
646 private subnet behind the left participant, expressed as net‐
647 work/netmask; if omitted, essentially assumed to be left/32,
648 signifying that the left end of the connection goes to the left
649 participant only. Configured subnets of the peers may differ,
650 the protocol narrows it to the greatest common subnet. In IKEv1,
651 this may lead to problems with other implementations, make sure
652 to configure identical subnets in such configurations. IKEv2
653 supports multiple subnets separated by commas. IKEv1 only inter‐
654 prets the first subnet of such a definition, unless the Cisco
655 Unity extension plugin is enabled. This is due to a limitation
656 of the IKEv1 protocol, which only allows a single pair of sub‐
657 nets per CHILD_SA. So to tunnel several subnets a conn entry has
658 to be defined and brought up for each pair of subnets.
659 The optional part after each subnet enclosed in square brackets
661 specifies a protocol/port to restrict the selector for that sub‐
662 net.
663 Examples: leftsubnet=10.0.0.1[tcp/http],10.0.0.2[6/80] or left‐
665 subnet=fec1::1[udp],10.0.0.0/16[/53]. Instead of omitting ei‐
666 ther value %any can be used to the same effect, e.g. leftsub‐
667 net=fec1::1[udp/%any],10.0.0.0/16[%any/53].
668 If the protocol is icmp or ipv6-icmp the port is interpreted as
670 ICMP message type if it is less than 256 or as type and code if
671 it is greater or equal to 256, with the type in the most signif‐
672 icant 8 bits and the code in the least significant 8 bits.
673 The port value can alternatively take the value %opaque for RFC
675 4301 OPAQUE selectors, or a numerical range in the form
676 1024-65535. None of the kernel backends currently supports
677 opaque or port ranges and uses %any for policy installation in‐
678 stead.
679 Instead of specifying a subnet, %dynamic can be used to replace
681 it with the IKE address, having the same effect as omitting
682 leftsubnet completely. Using %dynamic can be used to define mul‐
683 tiple dynamic selectors, each having a potentially different
684 protocol/port definition.
685 leftupdown = <path>
688 what ``updown'' script to run to adjust routing and/or fire‐
689 walling when the status of the connection changes (default ipsec
690 _updown). May include positional parameters separated by white
691 space (although this requires enclosing the whole string in
692 quotes); including shell metacharacters is unwise. Relevant
693 only locally, other end need not agree on it. Charon uses the
694 updown script to insert firewall rules only, since routing has
695 been implemented directly into the daemon.
696 lifebytes = <number>
698 the number of bytes transmitted over an IPsec SA before it ex‐
699 pires.
700 lifepackets = <number>
702 the number of packets transmitted over an IPsec SA before it ex‐
703 pires.
704 lifetime = 1h | <time>
706 how long a particular instance of a connection (a set of encryp‐
707 tion/authentication keys for user packets) should last, from
708 successful negotiation to expiry; acceptable values are an inte‐
709 ger optionally followed by s (a time in seconds) or a decimal
710 number followed by m, h, or d (a time in minutes, hours, or days
711 respectively) (default 1h, maximum 24h). Normally, the connec‐
712 tion is renegotiated (via the keying channel) before it expires
713 (see margintime). The two ends need not exactly agree on life‐
714 time, although if they do not, there will be some clutter of su‐
715 perseded connections on the end which thinks the lifetime is
716 longer. Also see EXPIRY/REKEY below.
717 marginbytes = <number>
719 how many bytes before IPsec SA expiry (see lifebytes) should at‐
720 tempts to negotiate a replacement begin.
721 marginpackets = <number>
723 how many packets before IPsec SA expiry (see lifepackets) should
724 attempts to negotiate a replacement begin.
725 margintime = 9m | <time>
727 how long before connection expiry or keying-channel expiry
728 should attempts to negotiate a replacement begin; acceptable
729 values as for lifetime (default 9m). Relevant only locally,
730 other end need not agree on it. Also see EXPIRY/REKEY below.
731 mark = <value>[/<mask>]
733 sets an XFRM mark on the inbound policy and outbound IPsec SA
734 and policy. If the mask is missing then a default mask of
735 0xffffffff is assumed. The special value %unique assigns a
736 unique value to each newly created IPsec SA. To additionally
737 make the mark unique for each IPsec SA direction (in/out) the
738 special value %unique-dir may be used.
739 mark_in = <value>[/<mask>]
741 sets an XFRM mark on the inbound policy (not on the SA). If the
742 mask is missing then a default mask of 0xffffffff is assumed.
743 mark_out = <value>[/<mask>]
745 sets an XFRM mark on the outbound IPsec SA and policy. If the
746 mask is missing then a default mask of 0xffffffff is assumed.
747 mobike = yes | no
749 enables the IKEv2 MOBIKE protocol defined by RFC 4555. Accepted
750 values are yes (the default) and no. If set to no, the charon
751 daemon will not actively propose MOBIKE as initiator and ignore
752 the MOBIKE_SUPPORTED notify as responder.
753 modeconfig = push | pull
755 defines which mode is used to assign a virtual IP. Accepted
756 values are push and pull (the default). Push mode is currently
757 not supported with IKEv2. The setting must be the same on both
758 sides.
759 reauth = yes | no
761 whether rekeying of an IKE_SA should also reauthenticate the
762 peer. In IKEv1, reauthentication is always done. In IKEv2, a
763 value of no rekeys without uninstalling the IPsec SAs, a value
764 of yes (the default) creates a new IKE_SA from scratch and tries
765 to recreate all IPsec SAs.
766 rekey = yes | no
768 whether a connection should be renegotiated when it is about to
769 expire; acceptable values are yes (the default) and no. The two
770 ends need not agree, but while a value of no prevents charon
771 from requesting renegotiation, it does not prevent responding to
772 renegotiation requested from the other end, so no will be
773 largely ineffective unless both ends agree on it. Also see
774 reauth.
775 rekeyfuzz = 100% | <percentage>
777 maximum percentage by which marginbytes, marginpackets and
778 margintime should be randomly increased to randomize rekeying
779 intervals (important for hosts with many connections); accept‐
780 able values are an integer, which may exceed 100, followed by a
781 `%' (defaults to 100%). The value of marginTYPE, after this
782 random increase, must not exceed lifeTYPE (where TYPE is one of
783 bytes, packets or time). The value 0% will suppress randomiza‐
784 tion. Relevant only locally, other end need not agree on it.
785 Also see EXPIRY/REKEY below.
786 replay_window = -1 | <number>
788 The IPsec replay window size for this connection. With the de‐
789 fault of -1 the value configured with charon.replay_window in
790 strongswan.conf(5) is used. Larger values than 32 are supported
791 using the Netlink backend only, a value of 0 disables IPsec re‐
792 play protection.
793 reqid = <number>
795 sets the reqid for a given connection to a pre-configured fixed
796 value.
797 sha256_96 = no | yes
799 HMAC-SHA-256 is used with 128-bit truncation with IPsec. For
800 compatibility with implementations that incorrectly use 96-bit
801 truncation this option may be enabled to configure the shorter
802 truncation length in the kernel. This is not negotiated, so
803 this only works with peers that use the incorrect truncation
804 length (or have this option enabled).
805 tfc = <value>
807 number of bytes to pad ESP payload data to. Traffic Flow Confi‐
808 dentiality is currently supported in IKEv2 and applies to outgo‐
809 ing packets only. The special value %mtu fills up ESP packets
810 with padding to have the size of the MTU.
811 type = tunnel | transport | transport_proxy | passthrough | drop
813 the type of the connection; currently the accepted values are
814 tunnel (the default) signifying a host-to-host, host-to-subnet,
815 or subnet-to-subnet tunnel; transport, signifying host-to-host
816 transport mode; transport_proxy, signifying the special Mobile
817 IPv6 transport proxy mode; passthrough, signifying that no IPsec
818 processing should be done at all; drop, signifying that packets
819 should be discarded.
820 xauth = client | server
822 specifies the role in the XAuth protocol if activated by au‐
823 thby=xauthpsk or authby=xauthrsasig. Accepted values are server
824 and client (the default).
825 xauth_identity = <id>
827 defines the identity/username the client uses to reply to an
828 XAuth request. If not defined, the IKEv1 identity will be used
829 as XAuth identity.
830 CONN PARAMETERS: IKEv2 MEDIATION EXTENSION
833 The following parameters are relevant to IKEv2 Mediation Extension op‐
834 eration only.
835 mediation = yes | no
837 whether this connection is a mediation connection, ie. whether
838 this connection is used to mediate other connections. Mediation
839 connections create no child SA. Acceptable values are no (the
840 default) and yes.
841 mediated_by = <name>
843 the name of the connection to mediate this connection through.
844 If given, the connection will be mediated through the named me‐
845 diation connection. The mediation connection must set media‐
846 tion=yes.
847 me_peerid = <id>
849 ID as which the peer is known to the mediation server, ie. which
850 the other end of this connection uses as its leftid on its con‐
851 nection to the mediation server. This is the ID we request the
852 mediation server to mediate us with. If me_peerid is not given,
853 the rightid of this connection will be used as peer ID.
854
857 These are optional sections that can be used to assign special parame‐
858 ters to a Certification Authority (CA). Because the daemons automati‐
859 cally import CA certificates from /etc/ipsec.d/cacerts, there is no
860 need to explicitly add them with a CA section, unless you want to as‐
861 sign special parameters (like a CRL) to a CA.
862 also = <name>
864 includes ca section <name>.
865 auto = ignore | add
867 currently can have either the value ignore (the default) or add.
868 cacert = <path>
870 defines a path to the CA certificate either relative to
871 /etc/ipsec.d/cacerts or as an absolute path.
872 A value in the form %smartcard[<slot nr>[@<module>]]:<keyid> de‐
873 fines a specific CA certificate to load from a PKCS#11 backend
874 for this CA. See ipsec.secrets(5) for details about smartcard
875 definitions.
876 crluri = <uri>
878 defines a CRL distribution point (ldap, http, or file URI)
879 crluri1
881 synonym for crluri.
882 crluri2 = <uri>
884 defines an alternative CRL distribution point (ldap, http, or
885 file URI)
886 ocspuri = <uri>
889 defines an OCSP URI.
890 ocspuri1
892 synonym for ocspuri.
893 ocspuri2 = <uri>
895 defines an alternative OCSP URI.
896 certuribase = <uri>
898 defines the base URI for the Hash and URL feature supported by
899 IKEv2. Instead of exchanging complete certificates, IKEv2 al‐
900 lows one to send an URI that resolves to the DER encoded cer‐
901 tificate. The certificate URIs are built by appending the SHA1
902 hash of the DER encoded certificates to this base URI.
903
905 At present, the only config section known to the IPsec software is the
906 one named setup, which contains information used when the software is
907 being started. The currently-accepted parameter names in a config
908 setup section are:
909 cachecrls = yes | no
911 if enabled, certificate revocation lists (CRLs) fetched via HTTP
912 or LDAP will be cached in /etc/ipsec.d/crls/ under a unique file
913 name derived from the certification authority's public key.
914 charondebug = <debug list>
916 how much charon debugging output should be logged. A comma sep‐
917 arated list containing type/level-pairs may be specified, e.g:
918 dmn 3, ike 1, net -1. Acceptable values for types are dmn, mgr,
919 ike, chd, job, cfg, knl, net, asn, enc, lib, esp, tls, tnc, imc,
920 imv, pts and the level is one of -1, 0, 1, 2, 3, 4 (for silent,
921 audit, control, controlmore, raw, private). By default, the
922 level is set to 1 for all types. For more flexibility see LOG‐
923 GER CONFIGURATION in strongswan.conf(5).
924 strictcrlpolicy = yes | ifuri | no
926 defines if a fresh CRL must be available in order for the peer
927 authentication based on RSA signatures to succeed. IKEv2 addi‐
928 tionally recognizes ifuri which reverts to yes if at least one
929 CRL URI is defined and to no if no URI is known.
930 uniqueids = yes | no | never | replace | keep
932 whether a particular participant ID should be kept unique, with
933 any new IKE_SA using an ID deemed to replace all old ones using
934 that ID; acceptable values are yes (the default), no and never.
935 Participant IDs normally are unique, so a new IKE_SA using the
936 same ID is almost invariably intended to replace an old one. The
937 difference between no and never is that the daemon will replace
938 old IKE_SAs when receiving an INITIAL_CONTACT notify if the op‐
939 tion is no but will ignore these notifies if never is config‐
940 ured. The daemon also accepts the value replace which is iden‐
941 tical to yes and the value keep to reject new IKE_SA setups and
942 keep the duplicate established earlier.
943
946 The type and binary encoding of identity strings specified in leftid
947 are detected as follows:
948 • If the string value contains an equal sign (=) it is assumed to
950 be a Distinguished Name, with RDNs separated by commas (,) or
951 slashes (/ - the string must start with a slash to use this syn‐
952 tax). An attempt is made to create a binary ASN.1 encoding from
953 this string. If that fails the type is set to KEY_ID with the
954 literal string value adopted as encoding.
955 • If the string value contains an @ the type depends on the posi‐
957 tion of that character:
958 • If the string begins with @# the type is set to KEY_ID
960 and the string following that prefix is assumed to be the
961 hex-encoded binary value of the identity.
962 • If the string begins with @@ the type is set to USER_FQDN
964 and the encoding is the literal string after that prefix.
965 • If the string begins with @ the type is set to FQDN and
967 the encoding is the literal string after that prefix.
968 • All remaining strings containing an @ are assumed to be
970 of type USER_FQDN/RFC822 with the literal string value as
971 encoding.
972 • If the value does not contain any @ or = characters it is parsed
974 as follows:
975 • If the value is an empty string, or equals %any[6],
977 0.0.0.0, ::, or * the type is set to ID_ANY, which
978 matches any other identity.
979 • If the value contains a colon (:) it is assumed to be an
981 IPv6 address. But if parsing the address and converting
982 it to its binary encoding fails the type is set to KEY_ID
983 and the encoding is the literal value.
984 • For all other strings an attempt at parsing them as IPv4
986 addresses is made. If that fails the type is set to FQDN
987 and the literal value is adopted as encoding (this is
988 where domain names and simple names end up).
989
992 The IKE SAs and IPsec SAs negotiated by the daemon can be configured to
993 expire after a specific amount of time. For IPsec SAs this can also
994 happen after a specified number of transmitted packets or transmitted
995 bytes. The following settings can be used to configure this:
996 Setting Default Setting Default
998 ──────────────────────────────────────────────────
999 IKE SA IPsec SA
1000 ikelifetime 3h lifebytes -
1001 lifepackets -
1002 lifetime 1h
1003 Rekeying
1005 IKE SAs as well as IPsec SAs can be rekeyed before they expire. This
1006 can be configured using the following settings:
1007 Setting Default Setting Default
1009 ───────────────────────────────────────────────────
1010 IKE and IPsec SA IPsec SA
1011 margintime 9m marginbytes -
1012 marginpackets -
1013 Randomization
1015 To avoid collisions the specified margins are increased randomly before
1016 subtracting them from the expiration limits (see formula below). This
1017 is controlled by the rekeyfuzz setting:
1018 Setting Default
1020 ──────────────────────
1021 IKE and IPsec SA
1022 rekeyfuzz 100%
1023 Randomization can be disabled by setting rekeyfuzz to 0%.
1025 Formula
1027 The following formula is used to calculate the rekey time of IPsec SAs:
1028 rekeytime = lifetime - (margintime + random(0, margintime * rekeyfuzz))
1030 It applies equally to IKE SAs and byte and packet limits for IPsec SAs.
1032 Example
1034 Let's consider the default configuration:
1035 lifetime = 1h
1037 margintime = 9m
1038 rekeyfuzz = 100%
1039 From the formula above follows that the rekey time lies between:
1041 rekeytime_min = 1h - (9m + 9m) = 42m
1043 rekeytime_max = 1h - (9m + 0m) = 51m
1044 Thus, the daemon will attempt to rekey the IPsec SA at a random time
1046 between 42 and 51 minutes after establishing the SA. Or, in other
1047 words, between 9 and 18 minutes before the SA expires.
1048 Notes
1050 • Since the rekeying of an SA needs some time, the margin values
1051 must not be too low.
1052 • The value margin... + margin... * rekeyfuzz must not exceed the
1054 original limit. For example, specifying margintime = 30m in the
1055 default configuration is a bad idea as there is a chance that
1056 the rekey time equals zero and, thus, rekeying gets disabled.
1057
1060 /etc/ipsec.conf
1061 /etc/ipsec.d/aacerts
1062 /etc/ipsec.d/acerts
1063 /etc/ipsec.d/cacerts
1064 /etc/ipsec.d/certs
1065 /etc/ipsec.d/crls
1066
1069 strongswan.conf(5), ipsec.secrets(5), ipsec(8)
1070
1072 Originally written for the FreeS/WAN project by Henry Spencer. Updated
1073 and extended for the strongSwan project <http://www.strongswan.org> by
1074 Tobias Brunner, Andreas Steffen and Martin Willi.
10755.9.4 2012-06-26 IPSEC.CONF(5)