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/strongswan/ipsec.d/certs are accepted. By default leftcert
484 sets leftid to the distinguished name of the certificate's sub‐
485 ject. The left participant's ID can be overridden by specifying
486 a leftid value which must be certified by the certificate,
487 though.
488 A value in the form %smartcard[<slot nr>[@<module>]]:<keyid> de‐
489 fines a specific certificate to load from a PKCS#11 backend for
490 this connection. See ipsec.secrets(5) for details about smart‐
491 card definitions. leftcert is required only if selecting the
492 certificate with leftid is not sufficient, for example if multi‐
493 ple certificates use the same subject.
494 Multiple certificate paths or PKCS#11 backends can be specified
495 in a comma separated list. The daemon chooses the certificate
496 based on the received certificate requests if possible before
497 enforcing the first.
498 leftcert2 = <path>
500 Same as leftcert, but for the second authentication round (IKEv2
501 only).
502 leftcertpolicy = <OIDs>
504 Comma separated list of certificate policy OIDs the peer's cer‐
505 tificate must have. OIDs are specified using the numerical dot‐
506 ted representation.
507 leftdns = <servers>
509 Comma separated list of DNS server addresses to exchange as con‐
510 figuration attributes. On the initiator, a server is a fixed
511 IPv4/IPv6 address, or %config4/%config6 to request attributes
512 without an address. On the responder, only fixed IPv4/IPv6 ad‐
513 dresses are allowed and define DNS servers assigned to the
514 client.
515 leftfirewall = yes | no
517 whether the left participant is doing forwarding-firewalling
518 (including masquerading) using iptables for traffic from left‐
519 subnet, which should be turned off (for traffic to the other
520 subnet) once the connection is established; acceptable values
521 are yes and no (the default). May not be used in the same con‐
522 nection description with leftupdown. Implemented as a parameter
523 to the default ipsec _updown script. See notes below. Relevant
524 only locally, other end need not agree on it.
525 If one or both security gateways are doing forwarding fire‐
527 walling (possibly including masquerading), and this is specified
528 using the firewall parameters, tunnels established with IPsec
529 are exempted from it so that packets can flow unchanged through
530 the tunnels. (This means that all subnets connected in this
531 manner must have distinct, non-overlapping subnet address
532 blocks.) This is done by the default ipsec _updown script.
533 In situations calling for more control, it may be preferable for
535 the user to supply his own updown script, which makes the appro‐
536 priate adjustments for his system.
537 leftgroups = <group list>
539 a comma separated list of group names. If the leftgroups parame‐
540 ter is present then the peer must be a member of at least one of
541 the groups defined by the parameter.
542 leftgroups2 = <group list>
544 Same as leftgroups, but for the second authentication round de‐
545 fined with leftauth2.
546 lefthostaccess = yes | no
548 inserts a pair of INPUT and OUTPUT iptables rules using the de‐
549 fault ipsec _updown script, thus allowing access to the host it‐
550 self in the case where the host's internal interface is part of
551 the negotiated client subnet. Acceptable values are yes and no
552 (the default).
553 leftid = <id>
555 how the left participant should be identified for authentica‐
556 tion; defaults to left or the subject of the certificate config‐
557 ured with leftcert. If leftcert is configured the identity has
558 to be confirmed by the certificate.
559 Can be an IP address, a fully-qualified domain name, an email
561 address or a Distinguished Name for which the ID type is deter‐
562 mined automatically and the string is converted to the appropri‐
563 ate encoding. The rules for this conversion are described in
564 IDENTITY PARSING below.
565 In certain special situations the identity parsing above might
567 be inadequate or produce the wrong result. Examples are the need
568 to encode a FQDN as KEY_ID or the string parser being unable to
569 produce the correct binary ASN.1 encoding of a certificate's DN.
570 For these situations it is possible to enforce a specific iden‐
571 tity type and to provide the binary encoding of the identity. To
572 do this a prefix may be used, followed by a colon (:). If the
573 number sign (#) follows the colon, the remaining data is inter‐
574 preted as hex encoding, otherwise the string is used as is as
575 the identification data. Note: The latter implies that no con‐
576 version is performed for non-string identities. For example,
577 ipv4:10.0.0.1 does not create a valid ID_IPV4_ADDR IKE identity,
578 as it does not get converted to binary 0x0a000001. Instead, one
579 could use ipv4:#0a000001 to get a valid identity, but just using
580 the implicit type with automatic conversion is usually simpler.
581 The same applies to the ASN.1 encoded types. The following pre‐
582 fixes are known: ipv4, ipv6, rfc822, email, userfqdn, fqdn, dns,
583 asn1dn, asn1gn and keyid. Custom type prefixes may be specified
584 by surrounding the numerical type value by curly brackets.
585 For IKEv2 and rightid the prefix % in front of the identity pre‐
587 vents the daemon from sending IDr in its IKE_AUTH request and
588 will allow it to verify the configured identity against the sub‐
589 ject and subjectAltNames contained in the responder's certifi‐
590 cate (otherwise it is only compared with the IDr returned by the
591 responder). The IDr sent by the initiator might otherwise pre‐
592 vent the responder from finding a config if it has configured a
593 different value for leftid.
594 leftid2 = <id>
596 identity to use for a second authentication for the left partic‐
597 ipant (IKEv2 only); defaults to leftid.
598 leftikeport = <port>
600 UDP port the left participant uses for IKE communication. If
601 unspecified, port 500 is used with the port floating to 4500 if
602 a NAT is detected or MOBIKE is enabled. Specifying a local IKE
603 port different from the default additionally requires a socket
604 implementation that listens on this port.
605 leftprotoport = <protocol>/<port>
607 restrict the traffic selector to a single protocol and/or port.
608 This option is now deprecated, protocol/port information can be
609 defined for each subnet directly in leftsubnet.
610 leftsigkey = <raw public key> | <path to public key>
612 the left participant's public key for public key signature au‐
613 thentication, in PKCS#1 format using hex (0x prefix) or base64
614 (0s prefix) encoding. With the optional dns: or ssh: prefix in
615 front of 0x or 0s, the public key is expected to be in either
616 the RFC 3110 (not the full RR, only RSA key part) or RFC 4253
617 public key format, respectively. Also accepted is the path to a
618 file containing the public key in PEM, DER or SSH encoding. Both
619 absolute paths or paths relative to
620 /etc/strongswan/ipsec.d/certs are accepted.
621 leftsendcert = never | no | ifasked | always | yes
623 Accepted values are never or no, always or yes, and ifasked (the
624 default), the latter meaning that the peer must send a certifi‐
625 cate request payload in order to get a certificate in return.
626 leftsourceip = %config4 | %config6 | <ip address>
628 Comma separated list of internal source IPs to use in a tunnel,
629 also known as virtual IP. If the value is one of the synonyms
630 %config, %cfg, %modeconfig, or %modecfg, an address (from the
631 tunnel address family) is requested from the peer. With %config4
632 and %config6 an address of the given address family will be re‐
633 quested explicitly. If an IP address is configured, it will be
634 requested from the responder, which is free to respond with a
635 different address.
636 rightsourceip = %config | <network>/<netmask> | <from>-<to> | %poolname
638 Comma separated list of internal source IPs to use in a tunnel
639 for the remote peer. If the value is %config on the responder
640 side, the initiator must propose an address which is then echoed
641 back. Also supported are address pools expressed as network/net‐
642 mask and from-to or the use of an external IP address pool using
643 %poolname, where poolname is the name of the IP address pool
644 used for the lookup.
645 leftsubnet = <ip subnet>[[<proto/port>]][,...]
647 private subnet behind the left participant, expressed as net‐
648 work/netmask; if omitted, essentially assumed to be left/32,
649 signifying that the left end of the connection goes to the left
650 participant only. Configured subnets of the peers may differ,
651 the protocol narrows it to the greatest common subnet. In IKEv1,
652 this may lead to problems with other implementations, make sure
653 to configure identical subnets in such configurations. IKEv2
654 supports multiple subnets separated by commas. IKEv1 only inter‐
655 prets the first subnet of such a definition, unless the Cisco
656 Unity extension plugin is enabled. This is due to a limitation
657 of the IKEv1 protocol, which only allows a single pair of sub‐
658 nets per CHILD_SA. So to tunnel several subnets a conn entry has
659 to be defined and brought up for each pair of subnets.
660 The optional part after each subnet enclosed in square brackets
662 specifies a protocol/port to restrict the selector for that sub‐
663 net.
664 Examples: leftsubnet=10.0.0.1[tcp/http],10.0.0.2[6/80] or left‐
666 subnet=fec1::1[udp],10.0.0.0/16[/53]. Instead of omitting ei‐
667 ther value %any can be used to the same effect, e.g. leftsub‐
668 net=fec1::1[udp/%any],10.0.0.0/16[%any/53].
669 If the protocol is icmp or ipv6-icmp the port is interpreted as
671 ICMP message type if it is less than 256 or as type and code if
672 it is greater or equal to 256, with the type in the most signif‐
673 icant 8 bits and the code in the least significant 8 bits.
674 The port value can alternatively take the value %opaque for RFC
676 4301 OPAQUE selectors, or a numerical range in the form
677 1024-65535. None of the kernel backends currently supports
678 opaque or port ranges and uses %any for policy installation in‐
679 stead.
680 Instead of specifying a subnet, %dynamic can be used to replace
682 it with the IKE address, having the same effect as omitting
683 leftsubnet completely. Using %dynamic can be used to define mul‐
684 tiple dynamic selectors, each having a potentially different
685 protocol/port definition.
686 leftupdown = <path>
689 what ``updown'' script to run to adjust routing and/or fire‐
690 walling when the status of the connection changes (default ipsec
691 _updown). May include positional parameters separated by white
692 space (although this requires enclosing the whole string in
693 quotes); including shell metacharacters is unwise. Relevant
694 only locally, other end need not agree on it. Charon uses the
695 updown script to insert firewall rules only, since routing has
696 been implemented directly into the daemon.
697 lifebytes = <number>
699 the number of bytes transmitted over an IPsec SA before it ex‐
700 pires.
701 lifepackets = <number>
703 the number of packets transmitted over an IPsec SA before it ex‐
704 pires.
705 lifetime = 1h | <time>
707 how long a particular instance of a connection (a set of encryp‐
708 tion/authentication keys for user packets) should last, from
709 successful negotiation to expiry; acceptable values are an inte‐
710 ger optionally followed by s (a time in seconds) or a decimal
711 number followed by m, h, or d (a time in minutes, hours, or days
712 respectively) (default 1h, maximum 24h). Normally, the connec‐
713 tion is renegotiated (via the keying channel) before it expires
714 (see margintime). The two ends need not exactly agree on life‐
715 time, although if they do not, there will be some clutter of su‐
716 perseded connections on the end which thinks the lifetime is
717 longer. Also see EXPIRY/REKEY below.
718 marginbytes = <number>
720 how many bytes before IPsec SA expiry (see lifebytes) should at‐
721 tempts to negotiate a replacement begin.
722 marginpackets = <number>
724 how many packets before IPsec SA expiry (see lifepackets) should
725 attempts to negotiate a replacement begin.
726 margintime = 9m | <time>
728 how long before connection expiry or keying-channel expiry
729 should attempts to negotiate a replacement begin; acceptable
730 values as for lifetime (default 9m). Relevant only locally,
731 other end need not agree on it. Also see EXPIRY/REKEY below.
732 mark = <value>[/<mask>]
734 sets an XFRM mark on the inbound policy and outbound IPsec SA
735 and policy. If the mask is missing then a default mask of
736 0xffffffff is assumed. The special value %unique assigns a
737 unique value to each newly created IPsec SA. To additionally
738 make the mark unique for each IPsec SA direction (in/out) the
739 special value %unique-dir may be used.
740 mark_in = <value>[/<mask>]
742 sets an XFRM mark on the inbound policy (not on the SA). If the
743 mask is missing then a default mask of 0xffffffff is assumed.
744 mark_out = <value>[/<mask>]
746 sets an XFRM mark on the outbound IPsec SA and policy. If the
747 mask is missing then a default mask of 0xffffffff is assumed.
748 mobike = yes | no
750 enables the IKEv2 MOBIKE protocol defined by RFC 4555. Accepted
751 values are yes (the default) and no. If set to no, the charon
752 daemon will not actively propose MOBIKE as initiator and ignore
753 the MOBIKE_SUPPORTED notify as responder.
754 modeconfig = push | pull
756 defines which mode is used to assign a virtual IP. Accepted
757 values are push and pull (the default). Push mode is currently
758 not supported with IKEv2. The setting must be the same on both
759 sides.
760 reauth = yes | no
762 whether rekeying of an IKE_SA should also reauthenticate the
763 peer. In IKEv1, reauthentication is always done. In IKEv2, a
764 value of no rekeys without uninstalling the IPsec SAs, a value
765 of yes (the default) creates a new IKE_SA from scratch and tries
766 to recreate all IPsec SAs.
767 rekey = yes | no
769 whether a connection should be renegotiated when it is about to
770 expire; acceptable values are yes (the default) and no. The two
771 ends need not agree, but while a value of no prevents charon
772 from requesting renegotiation, it does not prevent responding to
773 renegotiation requested from the other end, so no will be
774 largely ineffective unless both ends agree on it. Also see
775 reauth.
776 rekeyfuzz = 100% | <percentage>
778 maximum percentage by which marginbytes, marginpackets and
779 margintime should be randomly increased to randomize rekeying
780 intervals (important for hosts with many connections); accept‐
781 able values are an integer, which may exceed 100, followed by a
782 `%' (defaults to 100%). The value of marginTYPE, after this
783 random increase, must not exceed lifeTYPE (where TYPE is one of
784 bytes, packets or time). The value 0% will suppress randomiza‐
785 tion. Relevant only locally, other end need not agree on it.
786 Also see EXPIRY/REKEY below.
787 replay_window = -1 | <number>
789 The IPsec replay window size for this connection. With the de‐
790 fault of -1 the value configured with charon.replay_window in
791 strongswan.conf(5) is used. Larger values than 32 are supported
792 using the Netlink backend only, a value of 0 disables IPsec re‐
793 play protection.
794 reqid = <number>
796 sets the reqid for a given connection to a pre-configured fixed
797 value.
798 sha256_96 = no | yes
800 HMAC-SHA-256 is used with 128-bit truncation with IPsec. For
801 compatibility with implementations that incorrectly use 96-bit
802 truncation this option may be enabled to configure the shorter
803 truncation length in the kernel. This is not negotiated, so
804 this only works with peers that use the incorrect truncation
805 length (or have this option enabled).
806 tfc = <value>
808 number of bytes to pad ESP payload data to. Traffic Flow Confi‐
809 dentiality is currently supported in IKEv2 and applies to outgo‐
810 ing packets only. The special value %mtu fills up ESP packets
811 with padding to have the size of the MTU.
812 type = tunnel | transport | transport_proxy | passthrough | drop
814 the type of the connection; currently the accepted values are
815 tunnel (the default) signifying a host-to-host, host-to-subnet,
816 or subnet-to-subnet tunnel; transport, signifying host-to-host
817 transport mode; transport_proxy, signifying the special Mobile
818 IPv6 transport proxy mode; passthrough, signifying that no IPsec
819 processing should be done at all; drop, signifying that packets
820 should be discarded.
821 xauth = client | server
823 specifies the role in the XAuth protocol if activated by au‐
824 thby=xauthpsk or authby=xauthrsasig. Accepted values are server
825 and client (the default).
826 xauth_identity = <id>
828 defines the identity/username the client uses to reply to an
829 XAuth request. If not defined, the IKEv1 identity will be used
830 as XAuth identity.
831 CONN PARAMETERS: IKEv2 MEDIATION EXTENSION
834 The following parameters are relevant to IKEv2 Mediation Extension op‐
835 eration only.
836 mediation = yes | no
838 whether this connection is a mediation connection, ie. whether
839 this connection is used to mediate other connections. Mediation
840 connections create no child SA. Acceptable values are no (the
841 default) and yes.
842 mediated_by = <name>
844 the name of the connection to mediate this connection through.
845 If given, the connection will be mediated through the named me‐
846 diation connection. The mediation connection must set media‐
847 tion=yes.
848 me_peerid = <id>
850 ID as which the peer is known to the mediation server, ie. which
851 the other end of this connection uses as its leftid on its con‐
852 nection to the mediation server. This is the ID we request the
853 mediation server to mediate us with. If me_peerid is not given,
854 the rightid of this connection will be used as peer ID.
855
858 These are optional sections that can be used to assign special parame‐
859 ters to a Certification Authority (CA). Because the daemons automati‐
860 cally import CA certificates from /etc/strongswan/ipsec.d/cacerts,
861 there is no need to explicitly add them with a CA section, unless you
862 want to assign special parameters (like a CRL) to a CA.
863 also = <name>
865 includes ca section <name>.
866 auto = ignore | add
868 currently can have either the value ignore (the default) or add.
869 cacert = <path>
871 defines a path to the CA certificate either relative to
872 /etc/strongswan/ipsec.d/cacerts or as an absolute path.
873 A value in the form %smartcard[<slot nr>[@<module>]]:<keyid> de‐
874 fines a specific CA certificate to load from a PKCS#11 backend
875 for this CA. See ipsec.secrets(5) for details about smartcard
876 definitions.
877 crluri = <uri>
879 defines a CRL distribution point (ldap, http, or file URI)
880 crluri1
882 synonym for crluri.
883 crluri2 = <uri>
885 defines an alternative CRL distribution point (ldap, http, or
886 file URI)
887 ocspuri = <uri>
890 defines an OCSP URI.
891 ocspuri1
893 synonym for ocspuri.
894 ocspuri2 = <uri>
896 defines an alternative OCSP URI.
897 certuribase = <uri>
899 defines the base URI for the Hash and URL feature supported by
900 IKEv2. Instead of exchanging complete certificates, IKEv2 al‐
901 lows one to send an URI that resolves to the DER encoded cer‐
902 tificate. The certificate URIs are built by appending the SHA1
903 hash of the DER encoded certificates to this base URI.
904
906 At present, the only config section known to the IPsec software is the
907 one named setup, which contains information used when the software is
908 being started. The currently-accepted parameter names in a config
909 setup section are:
910 cachecrls = yes | no
912 if enabled, certificate revocation lists (CRLs) fetched via HTTP
913 or LDAP will be cached in /etc/strongswan/ipsec.d/crls/ under a
914 unique file name derived from the certification authority's pub‐
915 lic key.
916 charondebug = <debug list>
918 how much charon debugging output should be logged. A comma sep‐
919 arated list containing type/level-pairs may be specified, e.g:
920 dmn 3, ike 1, net -1. Acceptable values for types are dmn, mgr,
921 ike, chd, job, cfg, knl, net, asn, enc, lib, esp, tls, tnc, imc,
922 imv, pts and the level is one of -1, 0, 1, 2, 3, 4 (for silent,
923 audit, control, controlmore, raw, private). By default, the
924 level is set to 1 for all types. For more flexibility see LOG‐
925 GER CONFIGURATION in strongswan.conf(5).
926 strictcrlpolicy = yes | ifuri | no
928 defines if a fresh CRL must be available in order for the peer
929 authentication based on RSA signatures to succeed. IKEv2 addi‐
930 tionally recognizes ifuri which reverts to yes if at least one
931 CRL URI is defined and to no if no URI is known.
932 uniqueids = yes | no | never | replace | keep
934 whether a particular participant ID should be kept unique, with
935 any new IKE_SA using an ID deemed to replace all old ones using
936 that ID; acceptable values are yes (the default), no and never.
937 Participant IDs normally are unique, so a new IKE_SA using the
938 same ID is almost invariably intended to replace an old one. The
939 difference between no and never is that the daemon will replace
940 old IKE_SAs when receiving an INITIAL_CONTACT notify if the op‐
941 tion is no but will ignore these notifies if never is config‐
942 ured. The daemon also accepts the value replace which is iden‐
943 tical to yes and the value keep to reject new IKE_SA setups and
944 keep the duplicate established earlier.
945
948 The type and binary encoding of identity strings specified in leftid
949 are detected as follows:
950 • If the string value contains an equal sign (=) it is assumed to
952 be a Distinguished Name, with RDNs separated by commas (,) or
953 slashes (/ - the string must start with a slash to use this syn‐
954 tax). An attempt is made to create a binary ASN.1 encoding from
955 this string. If that fails the type is set to KEY_ID with the
956 literal string value adopted as encoding.
957 • If the string value contains an @ the type depends on the posi‐
959 tion of that character:
960 • If the string begins with @# the type is set to KEY_ID
962 and the string following that prefix is assumed to be the
963 hex-encoded binary value of the identity.
964 • If the string begins with @@ the type is set to USER_FQDN
966 and the encoding is the literal string after that prefix.
967 • If the string begins with @ the type is set to FQDN and
969 the encoding is the literal string after that prefix.
970 • All remaining strings containing an @ are assumed to be
972 of type USER_FQDN/RFC822 with the literal string value as
973 encoding.
974 • If the value does not contain any @ or = characters it is parsed
976 as follows:
977 • If the value is an empty string, or equals %any[6],
979 0.0.0.0, ::, or * the type is set to ID_ANY, which
980 matches any other identity.
981 • If the value contains a colon (:) it is assumed to be an
983 IPv6 address. But if parsing the address and converting
984 it to its binary encoding fails the type is set to KEY_ID
985 and the encoding is the literal value.
986 • For all other strings an attempt at parsing them as IPv4
988 addresses is made. If that fails the type is set to FQDN
989 and the literal value is adopted as encoding (this is
990 where domain names and simple names end up).
991
994 The IKE SAs and IPsec SAs negotiated by the daemon can be configured to
995 expire after a specific amount of time. For IPsec SAs this can also
996 happen after a specified number of transmitted packets or transmitted
997 bytes. The following settings can be used to configure this:
998 Setting Default Setting Default
1000 ──────────────────────────────────────────────────
1001 IKE SA IPsec SA
1002 ikelifetime 3h lifebytes -
1003 lifepackets -
1004 lifetime 1h
1005 Rekeying
1007 IKE SAs as well as IPsec SAs can be rekeyed before they expire. This
1008 can be configured using the following settings:
1009 Setting Default Setting Default
1011 ───────────────────────────────────────────────────
1012 IKE and IPsec SA IPsec SA
1013 margintime 9m marginbytes -
1014 marginpackets -
1015 Randomization
1017 To avoid collisions the specified margins are increased randomly before
1018 subtracting them from the expiration limits (see formula below). This
1019 is controlled by the rekeyfuzz setting:
1020 Setting Default
1022 ──────────────────────
1023 IKE and IPsec SA
1024 rekeyfuzz 100%
1025 Randomization can be disabled by setting rekeyfuzz to 0%.
1027 Formula
1029 The following formula is used to calculate the rekey time of IPsec SAs:
1030 rekeytime = lifetime - (margintime + random(0, margintime * rekeyfuzz))
1032 It applies equally to IKE SAs and byte and packet limits for IPsec SAs.
1034 Example
1036 Let's consider the default configuration:
1037 lifetime = 1h
1039 margintime = 9m
1040 rekeyfuzz = 100%
1041 From the formula above follows that the rekey time lies between:
1043 rekeytime_min = 1h - (9m + 9m) = 42m
1045 rekeytime_max = 1h - (9m + 0m) = 51m
1046 Thus, the daemon will attempt to rekey the IPsec SA at a random time
1048 between 42 and 51 minutes after establishing the SA. Or, in other
1049 words, between 9 and 18 minutes before the SA expires.
1050 Notes
1052 • Since the rekeying of an SA needs some time, the margin values
1053 must not be too low.
1054 • The value margin... + margin... * rekeyfuzz must not exceed the
1056 original limit. For example, specifying margintime = 30m in the
1057 default configuration is a bad idea as there is a chance that
1058 the rekey time equals zero and, thus, rekeying gets disabled.
1059
1062 /etc/strongswan/ipsec.conf
1063 /etc/strongswan/ipsec.d/aacerts
1064 /etc/strongswan/ipsec.d/acerts
1065 /etc/strongswan/ipsec.d/cacerts
1066 /etc/strongswan/ipsec.d/certs
1067 /etc/strongswan/ipsec.d/crls
1068
1071 strongswan.conf(5), ipsec.secrets(5), ipsec(8)
1072
1074 Originally written for the FreeS/WAN project by Henry Spencer. Updated
1075 and extended for the strongSwan project <http://www.strongswan.org> by
1076 Tobias Brunner, Andreas Steffen and Martin Willi.
10775.9.9 2012-06-26 IPSEC.CONF(5)