6f80709a62156422ce62d5c81ce42db9f796070e
[strongswan.git] / man / ipsec.conf.5.in
1 .TH IPSEC.CONF 5 "2012-06-26" "@PACKAGE_VERSION@" "strongSwan"
2 .SH NAME
3 ipsec.conf \- IPsec configuration and connections
4 .SH DESCRIPTION
5 The optional
6 .I ipsec.conf
7 file
8 specifies most configuration and control information for the
9 strongSwan IPsec subsystem.
10 The major exception is secrets for authentication;
11 see
12 .IR ipsec.secrets (5).
13 Its contents are not security-sensitive.
14 .PP
15 The file is a text file, consisting of one or more
16 .IR sections .
17 White space followed by
18 .B #
19 followed by anything to the end of the line
20 is a comment and is ignored,
21 as are empty lines which are not within a section.
22 .PP
23 A line which contains
24 .B include
25 and a file name, separated by white space,
26 is replaced by the contents of that file.
27 If the file name is not a full pathname,
28 it is considered to be relative to the directory containing the
29 including file.
30 Such inclusions can be nested.
31 Only a single filename may be supplied, and it may not contain white space,
32 but it may include shell wildcards (see
33 .IR sh (1));
34 for example:
35 .PP
36 .B include
37 .B "ipsec.*.conf"
38 .PP
39 The intention of the include facility is mostly to permit keeping
40 information on connections, or sets of connections,
41 separate from the main configuration file.
42 This permits such connection descriptions to be changed,
43 copied to the other security gateways involved, etc.,
44 without having to constantly extract them from the configuration
45 file and then insert them back into it.
46 Note also the
47 .B also
48 parameter (described below) which permits splitting a single logical
49 section (e.g. a connection description) into several actual sections.
50 .PP
51 A section
52 begins with a line of the form:
53 .PP
54 .I type
55 .I name
56 .PP
57 where
58 .I type
59 indicates what type of section follows, and
60 .I name
61 is an arbitrary name which distinguishes the section from others
62 of the same type.
63 All subsequent non-empty lines
64 which begin with white space are part of the section.
65 Sections of the same type that share the same name are merged.
66 .PP
67 Lines within the section are generally of the form
68 .PP
69 \ \ \ \ \ \fIparameter\fB=\fIvalue\fR
70 .PP
71 (note the mandatory preceding white space).
72 There can be white space on either side of the
73 .BR = .
74 Parameter names are specific to a section type.
75 .PP
76 An empty
77 .I value
78 stands for the system default value (if any) of the parameter,
79 i.e. it is roughly equivalent to omitting the parameter line entirely. This may
80 be useful to clear a setting inherited from a
81 .B %default
82 section or via
83 .B also
84 parameter (see below).
85 A
86 .I value
87 may contain single spaces (additional white space is reduced to one space).
88 To preserve white space as written enclose the entire
89 .I value
90 in double quotes (\fB"\fR); in such values double quotes themselves may be
91 escaped by prefixing them with
92 .B \\\\
93 characters. A double-quoted string may span multiple lines by ending them with
94 .B \\\\
95 characters (following lines don't have to begin with white space, as that will
96 be preserved). Additionally, the following control characters may be encoded in
97 double-quoted strings: \\n, \\r, \\t, \\b, \\f.
98 .PP
99 Numeric values are specified to be either an ``integer''
100 (a sequence of digits) or a ``decimal number''
101 (sequence of digits optionally followed by `.' and another sequence of digits).
102 .PP
103 There is currently one parameter which is available in any type of
104 section:
105 .TP
106 .B also
107 the value is a section name; the parameters of that section are inherited by
108 the current section. Parameters in the current section always override inherited
109 parameters, even if an
110 .B also
111 follows after them.
112 The specified section must exist and must have the same section type; it doesn't
113 if it is defined before or after the current section.
114 Nesting is permitted, and there may be more than one
115 .B also
116 in a single section (parameters from referenced sections are inherited and
117 overridden in the order of these
118 .B also
119 parameters).
120 .PP
121 A section with name
122 .B %default
123 specifies defaults for sections of the same type. All parameters in it, are
124 inherited by all other sections of that type.
125 .PP
126 Currently there are three types of sections:
127 a
128 .B config
129 section specifies general configuration information for IPsec, a
130 .B conn
131 section specifies an IPsec connection, while a
132 .B ca
133 section specifies special properties of a certification authority.
134 .SH "CONN SECTIONS"
135 A
136 .B conn
137 section contains a
138 .IR "connection specification" ,
139 defining a network connection to be made using IPsec.
140 The name given is arbitrary, and is used to identify the connection.
141 Here's a simple example:
142 .PP
143 .ne 10
144 .nf
145 .ft B
146 .ta 1c
147 conn snt
148         left=192.168.0.1
149         leftsubnet=10.1.0.0/16
150         right=192.168.0.2
151         rightsubnet=10.1.0.0/16
152         keyingtries=%forever
153         auto=add
154 .ft
155 .fi
156 .PP
157 A note on terminology: There are two kinds of communications going on:
158 transmission of user IP packets, and gateway-to-gateway negotiations for
159 keying, rekeying, and general control.
160 The path to control the connection is called 'ISAKMP SA' in IKEv1
161 and 'IKE SA' in the IKEv2 protocol. That what is being negotiated, the kernel
162 level data path, is called 'IPsec SA' or 'Child SA'.
163 strongSwan previously used two separate keying daemons, \fIpluto\fP and
164 \fIcharon\fP. This manual does not discuss \fIpluto\fP options anymore, but
165 only \fIcharon\fP that since strongSwan 5.0 supports both IKEv1 and IKEv2.
166 .PP
167 To avoid trivial editing of the configuration file to suit it to each system
168 involved in a connection,
169 connection specifications are written in terms of
170 .I left
171 and
172 .I right
173 participants,
174 rather than in terms of local and remote.
175 Which participant is considered
176 .I left
177 or
178 .I right
179 is arbitrary;
180 for every connection description an attempt is made to figure out whether
181 the local endpoint should act as the
182 .I left
183 or
184 .I right
185 endpoint. This is done by matching the IP addresses defined for both endpoints
186 with the IP addresses assigned to local network interfaces. If a match is found
187 then the role (left or right) that matches is going to be considered local.
188 If no match is found during startup,
189 .I left
190 is considered local.
191 This permits using identical connection specifications on both ends.
192 There are cases where there is no symmetry; a good convention is to
193 use
194 .I left
195 for the local side and
196 .I right
197 for the remote side (the first letters are a good mnemonic).
198 .PP
199 Many of the parameters relate to one participant or the other;
200 only the ones for
201 .I left
202 are listed here, but every parameter whose name begins with
203 .B left
204 has a
205 .B right
206 counterpart,
207 whose description is the same but with
208 .B left
209 and
210 .B right
211 reversed.
212 .PP
213 Parameters are optional unless marked '(required)'.
214 .SS "CONN PARAMETERS"
215 Unless otherwise noted, for a connection to work,
216 in general it is necessary for the two ends to agree exactly
217 on the values of these parameters.
218 .TP
219 .BR aaa_identity " = <id>"
220 defines the identity of the AAA backend used during IKEv2 EAP authentication.
221 This is required if the EAP client uses a method that verifies the server
222 identity (such as EAP-TLS), but it does not match the IKEv2 gateway identity.
223 .TP
224 .BR aggressive " = yes | " no
225 whether to use IKEv1 Aggressive or Main Mode (the default).
226 .TP
227 .BR ah " = <cipher suites>"
228 comma-separated list of AH algorithms to be used for the connection, e.g.
229 .BR sha1-sha256-modp1024 .
230 The notation is
231 .BR integrity[-dhgroup] .
232 For IKEv2, multiple algorithms (separated by -) of the same type can be included
233 in a single proposal. IKEv1 only includes the first algorithm in a proposal.
234 Only either the
235 .B ah
236 or
237 .B esp
238 keyword may be used, AH+ESP bundles are not supported.
239
240 There is no default AH cipher suite since by default ESP is used.
241 The daemon adds its extensive default proposal to the configured value. To
242 restrict it to the configured proposal an
243 exclamation mark
244 .RB ( ! )
245 can be added at the end.
246
247 If
248 .B dh-group
249 is specified, CHILD_SA/Quick Mode setup and rekeying include a separate
250 Diffie-Hellman exchange (refer to the
251 .B esp
252 keyword for details).
253 .TP
254 .BR also " = <name>"
255 includes conn section
256 .BR <name> .
257 .TP
258 .BR auth " = <value>"
259 was used by the
260 .B pluto
261 IKEv1 daemon to use AH integrity protection for ESP encrypted packets, but is
262 not supported in charon. The
263 .B ah
264 keyword specifies algorithms to use for integrity protection with AH, but
265 without encryption. AH+ESP bundles are not supported.
266 .TP
267 .BR authby " = " pubkey " | rsasig | ecdsasig | psk | secret | never | xauthpsk | xauthrsasig"
268 how the two security gateways should authenticate each other;
269 acceptable values are
270 .B psk
271 or
272 .B secret
273 for pre-shared secrets,
274 .B pubkey
275 (the default) for public key signatures as well as the synonyms
276 .B rsasig
277 for RSA digital signatures and
278 .B ecdsasig
279 for Elliptic Curve DSA signatures.
280 .B never
281 can be used if negotiation is never to be attempted or accepted (useful for
282 shunt-only conns).
283 Digital signatures are superior in every way to shared secrets.
284 IKEv1 additionally supports the values
285 .B xauthpsk
286 and
287 .B xauthrsasig
288 that will enable eXtended AUTHentication (XAUTH) in addition to IKEv1 main mode
289 based on shared secrets or digital RSA signatures, respectively.
290 This parameter is deprecated, as two peers do not need to agree on an
291 authentication method in IKEv2. Use the
292 .B leftauth
293 parameter instead to define authentication methods.
294 .TP
295 .BR auto " = " ignore " | add | route | start"
296 what operation, if any, should be done automatically at IPsec startup;
297 currently-accepted values are
298 .BR add ,
299 .BR route ,
300 .B start
301 and
302 .B ignore
303 (the default).
304 .B add
305 loads a connection without starting it.
306 .B route
307 loads a connection and installs kernel traps. If traffic is detected between
308 .B leftsubnet
309 and
310 .BR rightsubnet ,
311 a connection is established.
312 .B start
313 loads a connection and brings it up immediately.
314 .B ignore
315 ignores the connection. This is equal to deleting a connection from the config
316 file.
317 Relevant only locally, other end need not agree on it.
318 .TP
319 .BR closeaction " = " none " | clear | hold | restart"
320 defines the action to take if the remote peer unexpectedly closes a CHILD_SA
321 (see
322 .B dpdaction
323 for meaning of values).
324 A
325 .B closeaction should not be
326 used if the peer uses reauthentication or uniquids checking, as these events
327 might trigger the defined action when not desired.
328 .TP
329 .BR compress " = yes | " no
330 whether IPComp compression of content is proposed on the connection
331 (link-level compression does not work on encrypted data,
332 so to be effective, compression must be done \fIbefore\fR encryption);
333 acceptable values are
334 .B yes
335 and
336 .B no
337 (the default). A value of
338 .B yes
339 causes the daemon to propose both compressed and uncompressed,
340 and prefer compressed.
341 A value of
342 .B no
343 prevents the daemon from proposing or accepting compression.
344 .TP
345 .BR dpdaction " = " none " | clear | hold | restart"
346 controls the use of the Dead Peer Detection protocol (DPD, RFC 3706) where
347 R_U_THERE notification messages (IKEv1) or empty INFORMATIONAL messages (IKEv2)
348 are periodically sent in order to check the
349 liveliness of the IPsec peer. The values
350 .BR clear ,
351 .BR hold ,
352 and
353 .B restart
354 all activate DPD and determine the action to perform on a timeout. With
355 .B clear
356 the connection is closed with no further actions taken.
357 .B hold
358 installs a trap policy, which will catch matching traffic and tries to
359 re-negotiate the connection on demand.
360 .B restart
361 will immediately trigger an attempt to re-negotiation the connection.
362 The default is
363 .B none
364 which disables the active sending of DPD messages.
365 .TP
366 .BR dpddelay " = " 30s " | <time>"
367 defines the period time interval with which R_U_THERE messages/INFORMATIONAL
368 exchanges are sent to the peer. These are only sent if no other traffic is
369 received. In IKEv2, a value of 0 sends no additional INFORMATIONAL
370 messages and uses only standard messages (such as those to rekey) to detect
371 dead peers.
372 .TP
373 .BR dpdtimeout " = " 150s " | <time>
374 defines the timeout interval, after which all connections to a peer are deleted
375 in case of inactivity. This only applies to IKEv1, in IKEv2 the default
376 retransmission timeout applies, as every exchange is used to detect dead peers.
377 .TP
378 .BR inactivity " = <time>"
379 defines the timeout interval, after which a CHILD_SA is closed if it did
380 not send or receive any traffic. The inactivity counter is reset during CHILD_SA
381 rekeying. This means that the inactivity timeout must be smaller than the
382 rekeying interval to have any effect.
383 .TP
384 .BR eap_identity " = <id>"
385 defines the identity the client uses to reply to an EAP Identity request.
386 If defined on the EAP server, the defined identity will be used as peer
387 identity during EAP authentication. The special value
388 .B %identity
389 uses the EAP Identity method to ask the client for an EAP identity. If not
390 defined, the IKEv2 identity will be used as EAP identity.
391 .TP
392 .BR esp " = <cipher suites>"
393 comma-separated list of ESP encryption/authentication algorithms to be used
394 for the connection, e.g.
395 .BR aes128-sha256 .
396 The notation is
397 .BR encryption-integrity[-dhgroup][-esnmode] .
398 For IKEv2, multiple algorithms (separated by -) of the same type can be included
399 in a single proposal. IKEv1 only includes the first algorithm in a proposal.
400 Only either the
401 .B ah
402 or
403 .B esp
404 keyword may be used, AH+ESP bundles are not supported.
405
406 Defaults to
407 .BR aes128-sha256 .
408 The daemon adds its extensive default proposal to this default
409 or the configured value.  To restrict it to the configured proposal an
410 exclamation mark
411 .RB ( ! )
412 can be added at the end.
413
414 .BR Note :
415 As a responder, the daemon defaults to selecting the first configured proposal
416 that's also supported by the peer. This may be changed via
417 .BR strongswan.conf (5)
418 to selecting the first acceptable proposal sent by the peer instead. In order to
419 restrict a responder to only accept specific cipher suites, the strict flag
420 .RB ( ! ,
421 exclamation mark) can be used, e.g: aes256-sha512-modp4096!
422
423 If
424 .B dh-group
425 is specified, CHILD_SA/Quick Mode rekeying and initial negotiation use a
426 separate Diffie-Hellman exchange using the specified group. However, for IKEv2,
427 the keys of the CHILD_SA created implicitly with the IKE_SA will always be
428 derived from the IKE_SA's key material. So any DH group specified here will only
429 apply when the CHILD_SA is later rekeyed or is created with a separate
430 CREATE_CHILD_SA exchange.  Therefore, a proposal mismatch might not immediately
431 be noticed when the SA is established, but may later cause rekeying to fail.
432
433 Valid values for
434 .B esnmode
435 are
436 .B esn
437 and
438 .BR noesn .
439 Specifying both negotiates Extended Sequence Number support with the peer,
440 the default is
441 .B noesn.
442 .TP
443 .BR forceencaps " = yes | " no
444 force UDP encapsulation for ESP packets even if no NAT situation is detected.
445 This may help to surmount restrictive firewalls. In order to force the peer to
446 encapsulate packets, NAT detection payloads are faked.
447 .TP
448 .BR fragmentation " = " yes "  | force | no"
449 whether to use IKE fragmentation (proprietary IKEv1 extension or IKEv2
450 fragmentation as per RFC 7383).  Acceptable values are
451 .B yes
452 (the default),
453 .B force
454 and
455 .BR no .
456 Fragmented IKE messages sent by a peer are always accepted
457 irrespective of the value of this option. If set to
458 .BR yes ,
459 and the peer supports it, larger IKE messages will be sent in fragments.
460 If set to
461 .B force
462 (only supported for IKEv1) the initial IKE message will already be fragmented
463 if required.
464 .TP
465 .BR ike " = <cipher suites>"
466 comma-separated list of IKE/ISAKMP SA encryption/authentication algorithms
467 to be used, e.g.
468 .BR aes128-sha256-modp3072 .
469 The notation is
470 .BR encryption-integrity[-prf]-dhgroup .
471 If no PRF is given, the algorithms defined for integrity are used for the PRF.
472 The prf keywords are the same as the integrity algorithms, but have a
473 .B prf
474 prefix (such as
475 .BR prfsha1 ,
476 .B prfsha256
477 or
478 .BR prfaesxcbc ).
479 .br
480 In IKEv2, multiple algorithms and proposals may be included, such as
481 .BR aes128-aes256-sha1-modp3072-modp2048,3des-sha1-md5-modp1024 .
482
483 Defaults to
484 .BR aes128-sha256-modp3072 .
485 The daemon adds its extensive default proposal to this
486 default or the configured value.  To restrict it to the configured proposal an
487 exclamation mark
488 .RB ( ! )
489 can be added at the end.
490
491 .BR Note :
492 As a responder the daemon accepts the first supported proposal received from
493 the peer.  In order to restrict a responder to only accept specific cipher
494 suites, the strict flag
495 .RB ( ! ,
496 exclamation mark) can be used, e.g:
497 .BR aes256-sha512-modp4096!
498 .TP
499 .BR ikedscp " = " 000000 " | <DSCP field>"
500 Differentiated Services Field Codepoint to set on outgoing IKE packets sent
501 from this connection. The value is a six digit binary encoded string defining
502 the Codepoint to set, as defined in RFC 2474.
503 .TP
504 .BR ikelifetime " = " 3h " | <time>"
505 how long the keying channel of a connection (ISAKMP or IKE SA)
506 should last before being renegotiated. Also see EXPIRY/REKEY below.
507 .TP
508 .BR installpolicy " = " yes " | no"
509 decides whether IPsec policies are installed in the kernel by the charon daemon
510 for a given connection. Allows peaceful cooperation e.g. with
511 the Mobile IPv6 daemon mip6d who wants to control the kernel policies.
512 Acceptable values are
513 .B yes
514 (the default) and
515 .BR no .
516 .TP
517 .BR keyexchange " = " ike " | ikev1 | ikev2"
518 which key exchange protocol should be used to initiate the connection.
519 Connections marked with
520 .B ike
521 use IKEv2 when initiating, but accept any protocol version when responding.
522 .TP
523 .BR keyingtries " = " 3 " | <number> | %forever"
524 how many attempts (a whole number or \fB%forever\fP) should be made to
525 negotiate a connection, or a replacement for one, before giving up
526 (default
527 .BR 3 ).
528 The value \fB%forever\fP
529 means 'never give up'.
530 Relevant only locally, other end need not agree on it.
531 .TP
532 .B keylife
533 synonym for
534 .BR lifetime .
535 .TP
536 .BR left " = <ip address> | <fqdn> | " %any " | <range> | <subnet> "
537 The IP address of the left participant's public-network interface
538 or one of several magic values.
539 The value
540 .B %any
541 (the default) for the local endpoint signifies an address to be filled in (by
542 automatic keying) during negotiation. If the local peer initiates the
543 connection setup the routing table will be queried to determine the correct
544 local IP address.
545 In case the local peer is responding to a connection setup then any IP address
546 that is assigned to a local interface will be accepted.
547
548 The prefix
549 .B %
550 in front of a fully-qualified domain name or an IP address will implicitly set
551 .BR leftallowany =yes.
552
553 If
554 .B %any
555 is used for the remote endpoint it literally means any IP address.
556
557 To limit the connection to a  specific range of hosts, a range (
558 .BR 10.1.0.0-10.2.255.255
559 ) or a subnet (
560 .BR 10.1.0.0/16
561 ) can be specified, and multiple addresses, ranges and subnets can be separated
562 by commas. While one can freely combine these items, to initiate the connection
563 at least one non-range/subnet is required.
564
565 Please note that with the usage of wildcards multiple connection descriptions
566 might match a given incoming connection attempt. The most specific description
567 is used in that case.
568 .TP
569 .BR leftallowany " = yes | " no
570 a modifier for
571 .BR left ,
572 making it behave as
573 .B %any
574 although a concrete IP address or domain name has been assigned.
575 .TP
576 .BR leftauth " = <auth method>"
577 Authentication method to use locally (left) or require from the remote (right)
578 side.
579 Acceptable values are
580 .B pubkey
581 for public key authentication (RSA/ECDSA),
582 .B psk
583 for pre-shared key authentication,
584 .B eap
585 to (require the) use of the Extensible Authentication Protocol in IKEv2, and
586 .B xauth
587 for IKEv1 eXtended Authentication.
588
589 To require a trustchain public key strength for the remote side, specify the
590 key type followed by the minimum strength in bits (for example
591 .BR ecdsa-384
592 or
593 .BR rsa-2048-ecdsa-256 ).
594 To limit the acceptable set of hashing algorithms for trustchain validation,
595 append hash algorithms to
596 .BR pubkey
597 or a key strength definition (for example
598 .BR pubkey-sha1-sha256
599 or
600 .BR rsa-2048-ecdsa-256-sha256-sha384-sha512 ).
601 Unless disabled in
602 .BR strongswan.conf (5),
603 or explicit IKEv2 signature constraints are configured (see below), such key
604 types and hash algorithms are also applied as constraints against IKEv2
605 signature authentication schemes used by the remote side.
606
607 If both peers support RFC 7427 ("Signature Authentication in IKEv2") specific
608 hash algorithms to be used during IKEv2 authentication may be configured.
609 The syntax is the same as above, but with ike: prefix. For example, with
610 .B ike:pubkey-sha384-sha256
611 a public key signature scheme with either SHA-384 or SHA-256 would get used for
612 authentication, in that order and depending on the hash algorithms supported by
613 the peer.  If no specific hash algorithms are configured, the default is to
614 prefer an algorithm that matches or exceeds the strength of the signature key.
615 If no constraints with ike: prefix are configured any signature scheme
616 constraint (without ike: prefix) will also apply to IKEv2 authentication, unless
617 this is disabled in
618 .BR strongswan.conf (5).
619
620 For
621 .BR eap ,
622 an optional EAP method can be appended. Currently defined methods are
623 .BR eap-aka ,
624 .BR eap-gtc ,
625 .BR eap-md5 ,
626 .BR eap-mschapv2 ,
627 .BR eap-peap ,
628 .BR eap-sim ,
629 .BR eap-tls ,
630 .BR eap-ttls ,
631 .BR eap-dynamic ,
632 and
633 .BR eap-radius .
634 Alternatively, IANA assigned EAP method numbers are accepted. Vendor specific
635 EAP methods are defined in the form
636 .B eap-type-vendor
637 .RB "(e.g. " eap-7-12345 ).
638 To specify signature and trust chain constraints for EAP-(T)TLS, append a colon
639 to the EAP method, followed by the key type/size and hash algorithm as discussed
640 above. For
641 .B xauth,
642 an XAuth authentication backend can be specified, such as
643 .B xauth-generic
644 or
645 .BR xauth-eap .
646 If XAuth is used in
647 .BR leftauth ,
648 Hybrid authentication is used. For traditional XAuth authentication, define
649 XAuth in
650 .BR lefauth2 .
651 .TP
652 .BR leftauth2 " = <auth method>"
653 Same as
654 .BR leftauth ,
655 but defines an additional authentication exchange. In IKEv1, only XAuth can be
656 used in the second authentication round. IKEv2 supports multiple complete
657 authentication rounds using "Multiple Authentication Exchanges" defined
658 in RFC 4739. This allows, for example, separated authentication
659 of host and user.
660 .TP
661 .BR leftca " = <issuer dn> | %same"
662 the distinguished name of a certificate authority which is required to
663 lie in the trust path going from the left participant's certificate up
664 to the root certification authority.
665 .B %same
666 means that the value configured for the right participant should be reused.
667 .TP
668 .BR leftca2 " = <issuer dn> | %same"
669 Same as
670 .BR leftca ,
671 but for the second authentication round (IKEv2 only).
672 .TP
673 .BR leftcert " = <path>"
674 the path to the left participant's X.509 certificate. The file can be encoded
675 either in PEM or DER format. OpenPGP certificates are supported as well.
676 Both absolute paths or paths relative to \fI/etc/ipsec.d/certs\fP
677 are accepted. By default
678 .B leftcert
679 sets
680 .B leftid
681 to the distinguished name of the certificate's subject.
682 The left participant's ID can be overridden by specifying a
683 .B leftid
684 value which must be certified by the certificate, though.
685 .br
686 A value in the form
687 .B %smartcard[<slot nr>[@<module>]]:<keyid>
688 defines a specific certificate to load from a PKCS#11 backend for this
689 connection. See ipsec.secrets(5) for details about smartcard definitions.
690 .B leftcert
691 is required only if selecting the certificate with
692 .B leftid
693 is not sufficient, for example if multiple certificates use the same subject.
694 .br
695 Multiple certificate paths or PKCS#11 backends can be specified in a comma
696 separated list. The daemon chooses the certificate based on the received
697 certificate requests if possible before enforcing the first.
698 .TP
699 .BR leftcert2 " = <path>"
700 Same as
701 .B leftcert,
702 but for the second authentication round (IKEv2 only).
703 .TP
704 .BR leftcertpolicy " = <OIDs>"
705 Comma separated list of certificate policy OIDs the peer's certificate must
706 have.
707 OIDs are specified using the numerical dotted representation.
708 .TP
709 .BR leftdns " = <servers>"
710 Comma separated list of DNS server addresses to exchange as configuration
711 attributes. On the initiator, a server is a fixed IPv4/IPv6 address, or
712 .BR %config4 / %config6
713 to request attributes without an address. On the responder,
714 only fixed IPv4/IPv6 addresses are allowed and define DNS servers assigned
715 to the client.
716 .TP
717 .BR leftfirewall " = yes | " no
718 whether the left participant is doing forwarding-firewalling
719 (including masquerading) using iptables for traffic from \fIleftsubnet\fR,
720 which should be turned off (for traffic to the other subnet)
721 once the connection is established;
722 acceptable values are
723 .B yes
724 and
725 .B no
726 (the default).
727 May not be used in the same connection description with
728 .BR leftupdown .
729 Implemented as a parameter to the default \fBipsec _updown\fR script.
730 See notes below.
731 Relevant only locally, other end need not agree on it.
732
733 If one or both security gateways are doing forwarding firewalling
734 (possibly including masquerading),
735 and this is specified using the firewall parameters,
736 tunnels established with IPsec are exempted from it
737 so that packets can flow unchanged through the tunnels.
738 (This means that all subnets connected in this manner must have
739 distinct, non-overlapping subnet address blocks.)
740 This is done by the default \fBipsec _updown\fR script.
741
742 In situations calling for more control,
743 it may be preferable for the user to supply his own
744 .I updown
745 script,
746 which makes the appropriate adjustments for his system.
747 .TP
748 .BR leftgroups " = <group list>"
749 a comma separated list of group names. If the
750 .B leftgroups
751 parameter is present then the peer must be a member of at least one
752 of the groups defined by the parameter.
753 .TP
754 .BR leftgroups2 " = <group list>"
755 Same as
756 .B leftgroups,
757 but for the second authentication round defined with
758 .B leftauth2.
759 .TP
760 .BR lefthostaccess " = yes | " no
761 inserts a pair of INPUT and OUTPUT iptables rules using the default
762 \fBipsec _updown\fR script, thus allowing access to the host itself
763 in the case where the host's internal interface is part of the
764 negotiated client subnet.
765 Acceptable values are
766 .B yes
767 and
768 .B no
769 (the default).
770 .TP
771 .BR leftid " = <id>"
772 how the left participant should be identified for authentication;
773 defaults to
774 .B left
775 or the subject of the certificate configured with
776 .BR leftcert .
777 If
778 .B leftcert
779 is configured the identity has to be confirmed by the certificate.
780
781 Can be an IP address, a fully-qualified domain name, an email address or a
782 Distinguished Name for which the ID type is determined automatically and the
783 string is converted to the appropriate encoding. The rules for this conversion
784 are described in IDENTITY PARSING below.
785
786 In certain special situations the identity parsing above might be inadequate
787 or produce the wrong result. Examples are the need to encode a FQDN as KEY_ID or
788 the string parser being unable to produce the correct binary ASN.1 encoding of
789 a certificate's DN.  For these situations it is possible to enforce a specific
790 identity type and to provide the binary encoding of the identity. To do this a
791 prefix may be used, followed by a colon (:). If the number sign (#) follows the
792 colon, the remaining data is interpreted as hex encoding, otherwise the string
793 is used as is as the identification data.
794 .BR Note :
795 The latter implies that no conversion is performed for non-string identities.
796 For example,
797 \fIipv4:10.0.0.1\fP does not create a valid ID_IPV4_ADDR IKE identity, as it
798 does not get converted to binary 0x0a000001. Instead, one could use
799 \fIipv4:#0a000001\fP to get a valid identity, but just using the implicit type
800 with automatic conversion is usually simpler. The same applies to the ASN.1
801 encoded types. The following prefixes are known:
802 .BR ipv4 ,
803 .BR ipv6 ,
804 .BR rfc822 ,
805 .BR email ,
806 .BR userfqdn ,
807 .BR fqdn ,
808 .BR dns ,
809 .BR asn1dn ,
810 .B asn1gn
811 and
812 .BR keyid .
813 Custom type prefixes may be specified by surrounding the numerical type value by
814 curly brackets.
815
816 For IKEv2 and
817 .B rightid
818 the prefix
819 .B %
820 in front of the identity prevents the daemon from sending IDr in its IKE_AUTH
821 request and will allow it to verify the configured identity against the subject
822 and subjectAltNames contained in the responder's certificate (otherwise it is
823 only compared with the IDr returned by the responder).  The IDr sent by the
824 initiator might otherwise prevent the responder from finding a config if it
825 has configured a different value for
826 .BR leftid .
827 .TP
828 .BR leftid2 " = <id>"
829 identity to use for a second authentication for the left participant
830 (IKEv2 only); defaults to
831 .BR leftid .
832 .TP
833 .BR leftikeport " = <port>"
834 UDP port the left participant uses for IKE communication.
835 If unspecified, port 500 is used with the port floating
836 to 4500 if a NAT is detected or MOBIKE is enabled. Specifying a local IKE port
837 different from the default additionally requires a socket implementation that
838 listens on this port.
839 .TP
840 .BR leftprotoport " = <protocol>/<port>"
841 restrict the traffic selector to a single protocol and/or port. This option
842 is now deprecated, protocol/port information can be defined for each subnet
843 directly in
844 .BR leftsubnet .
845 .TP
846 .BR leftsigkey " = <raw public key> | <path to public key>"
847 the left participant's public key for public key signature authentication,
848 in PKCS#1 format using hex (0x prefix) or base64 (0s prefix) encoding. With the
849 optional
850 .B dns:
851 or
852 .B ssh:
853 prefix in front of 0x or 0s, the public key is expected to be in either
854 the RFC 3110 (not the full RR, only RSA key part) or RFC 4253 public key format,
855 respectively.
856 Also accepted is the path to a file containing the public key in PEM, DER or SSH
857 encoding. Both absolute paths or paths relative to \fI/etc/ipsec.d/certs\fP
858 are accepted.
859 .TP
860 .BR leftsendcert " = never | no | " ifasked " | always | yes"
861 Accepted values are
862 .B never
863 or
864 .BR no ,
865 .B always
866 or
867 .BR yes ,
868 and
869 .BR ifasked " (the default),"
870 the latter meaning that the peer must send a certificate request payload in
871 order to get a certificate in return.
872 .TP
873 .BR leftsourceip " = %config4 | %config6 | <ip address>"
874 Comma separated list of internal source IPs to use in a tunnel, also known as
875 virtual IP. If the value is one of the synonyms
876 .BR %config ,
877 .BR %cfg ,
878 .BR %modeconfig ,
879 or
880 .BR %modecfg ,
881 an address (from the tunnel address family) is requested from the peer. With
882 .B %config4
883 and
884 .B %config6
885 an address of the given address family will be requested explicitly.
886 If an IP address is configured, it will be requested from the responder,
887 which is free to respond with a different address.
888 .TP
889 .BR rightsourceip " = %config | <network>/<netmask> | <from>-<to> | %poolname"
890 Comma separated list of internal source IPs to use in a tunnel for the remote
891 peer. If the value is
892 .B %config
893 on the responder side, the initiator must propose an address which is then
894 echoed back. Also supported are address pools expressed as
895 \fInetwork\fB/\fInetmask\fR
896 and
897 \fIfrom\fB-\fIto\fR
898 or the use of an external IP address pool using %\fIpoolname\fR,
899 where \fIpoolname\fR is the name of the IP address pool used for the lookup.
900 .TP
901 .BR leftsubnet " = <ip subnet>[[<proto/port>]][,...]"
902 private subnet behind the left participant, expressed as
903 \fInetwork\fB/\fInetmask\fR;
904 if omitted, essentially assumed to be \fIleft\fB/32\fR,
905 signifying that the left end of the connection goes to the left participant
906 only. Configured subnets of the peers may differ, the protocol narrows it to
907 the greatest common subnet. In IKEv1, this may lead to problems with other
908 implementations, make sure to configure identical subnets in such
909 configurations. IKEv2 supports multiple subnets separated by commas. IKEv1 only
910 interprets the first subnet of such a definition, unless the Cisco Unity
911 extension plugin is enabled.
912
913 The optional part after each subnet enclosed in square brackets specifies a
914 protocol/port to restrict the selector for that subnet.
915
916 Examples:
917 .BR leftsubnet=10.0.0.1[tcp/http],10.0.0.2[6/80] " or"
918 .BR leftsubnet=fec1::1[udp],10.0.0.0/16[/53] .
919 Instead of omitting either value
920 .B %any
921 can be used to the same effect, e.g.
922 .BR leftsubnet=fec1::1[udp/%any],10.0.0.0/16[%any/53] .
923
924 If the protocol is
925 .B icmp
926 or
927 .B ipv6-icmp
928 the port is interpreted as ICMP message type if it is less than 256 or as type
929 and code if it is greater or equal to 256, with the type in the most significant
930 8 bits and the code in the least significant 8 bits.
931
932 The port value can alternatively take the value
933 .B %opaque
934 for RFC 4301 OPAQUE selectors, or a numerical range in the form
935 .BR 1024-65535 .
936 None of the kernel backends currently supports opaque or port ranges and uses
937 .B %any
938 for policy installation instead.
939
940 Instead of specifying a subnet,
941 .B %dynamic
942 can be used to replace it with the IKE address, having the same effect
943 as omitting
944 .B leftsubnet
945 completely. Using
946 .B %dynamic
947 can be used to define multiple dynamic selectors, each having a potentially
948 different protocol/port definition.
949
950 .TP
951 .BR leftupdown " = <path>"
952 what ``updown'' script to run to adjust routing and/or firewalling
953 when the status of the connection
954 changes (default
955 .BR "ipsec _updown" ).
956 May include positional parameters separated by white space
957 (although this requires enclosing the whole string in quotes);
958 including shell metacharacters is unwise.
959 Relevant only locally, other end need not agree on it. Charon uses the updown
960 script to insert firewall rules only, since routing has been implemented
961 directly into the daemon.
962 .TP
963 .BR lifebytes " = <number>"
964 the number of bytes transmitted over an IPsec SA before it expires.
965 .TP
966 .BR lifepackets " = <number>"
967 the number of packets transmitted over an IPsec SA before it expires.
968 .TP
969 .BR lifetime " = " 1h " | <time>"
970 how long a particular instance of a connection
971 (a set of encryption/authentication keys for user packets) should last,
972 from successful negotiation to expiry;
973 acceptable values are an integer optionally followed by
974 .BR s
975 (a time in seconds)
976 or a decimal number followed by
977 .BR m ,
978 .BR h ,
979 or
980 .B d
981 (a time
982 in minutes, hours, or days respectively)
983 (default
984 .BR 1h ,
985 maximum
986 .BR 24h ).
987 Normally, the connection is renegotiated (via the keying channel)
988 before it expires (see
989 .BR margintime ).
990 The two ends need not exactly agree on
991 .BR lifetime ,
992 although if they do not,
993 there will be some clutter of superseded connections on the end
994 which thinks the lifetime is longer. Also see EXPIRY/REKEY below.
995 .TP
996 .BR marginbytes " = <number>"
997 how many bytes before IPsec SA expiry (see
998 .BR lifebytes )
999 should attempts to negotiate a replacement begin.
1000 .TP
1001 .BR marginpackets " = <number>"
1002 how many packets before IPsec SA expiry (see
1003 .BR lifepackets )
1004 should attempts to negotiate a replacement begin.
1005 .TP
1006 .BR margintime " = " 9m " | <time>"
1007 how long before connection expiry or keying-channel expiry
1008 should attempts to
1009 negotiate a replacement
1010 begin; acceptable values as for
1011 .B lifetime
1012 (default
1013 .BR 9m ).
1014 Relevant only locally, other end need not agree on it. Also see EXPIRY/REKEY
1015 below.
1016 .TP
1017 .BR mark " = <value>[/<mask>]"
1018 sets an XFRM mark in the inbound and outbound
1019 IPsec SAs and policies. If the mask is missing then a default
1020 mask of
1021 .B 0xffffffff
1022 is assumed. The special value
1023 .B %unique
1024 assigns a unique value to each newly created IPsec SA.
1025 .TP
1026 .BR mark_in " = <value>[/<mask>]"
1027 sets an XFRM mark in the inbound IPsec SA and
1028 policy. If the mask is missing then a default mask of
1029 .B 0xffffffff
1030 is assumed.
1031 .TP
1032 .BR mark_out " = <value>[/<mask>]"
1033 sets an XFRM mark in the outbound IPsec SA and
1034 policy. If the mask is missing then a default mask of
1035 .B 0xffffffff
1036 is assumed.
1037 .TP
1038 .BR mobike " = " yes " | no"
1039 enables the IKEv2 MOBIKE protocol defined by RFC 4555. Accepted values are
1040 .B yes
1041 (the default) and
1042 .BR no .
1043 If set to
1044 .BR no ,
1045 the charon daemon will not actively propose MOBIKE as initiator and
1046 ignore the MOBIKE_SUPPORTED notify as responder.
1047 .TP
1048 .BR modeconfig " = push | " pull
1049 defines which mode is used to assign a virtual IP.
1050 Accepted values are
1051 .B push
1052 and
1053 .B pull
1054 (the default).
1055 Push mode is currently not supported with IKEv2.
1056 .TP
1057 .BR reauth " = " yes " | no"
1058 whether rekeying of an IKE_SA should also reauthenticate the peer. In IKEv1,
1059 reauthentication is always done. In IKEv2, a value of
1060 .B no
1061 rekeys without uninstalling the IPsec SAs, a value of
1062 .B yes
1063 (the default) creates a new IKE_SA from scratch and tries to recreate
1064 all IPsec SAs.
1065 .TP
1066 .BR rekey " = " yes " | no"
1067 whether a connection should be renegotiated when it is about to expire;
1068 acceptable values are
1069 .B yes
1070 (the default)
1071 and
1072 .BR no .
1073 The two ends need not agree, but while a value of
1074 .B no
1075 prevents charon from requesting renegotiation,
1076 it does not prevent responding to renegotiation requested from the other end,
1077 so
1078 .B no
1079 will be largely ineffective unless both ends agree on it. Also see
1080 .BR reauth .
1081 .TP
1082 .BR rekeyfuzz " = " 100% " | <percentage>"
1083 maximum percentage by which
1084 .BR marginbytes ,
1085 .B marginpackets
1086 and
1087 .B margintime
1088 should be randomly increased to randomize rekeying intervals
1089 (important for hosts with many connections);
1090 acceptable values are an integer,
1091 which may exceed 100,
1092 followed by a `%'
1093 (defaults to
1094 .BR 100% ).
1095 The value of
1096 .BR marginTYPE ,
1097 after this random increase,
1098 must not exceed
1099 .B lifeTYPE
1100 (where TYPE is one of
1101 .IR bytes ,
1102 .I packets
1103 or
1104 .IR time ).
1105 The value
1106 .B 0%
1107 will suppress randomization.
1108 Relevant only locally, other end need not agree on it. Also see EXPIRY/REKEY
1109 below.
1110 .TP
1111 .B rekeymargin
1112 synonym for
1113 .BR margintime .
1114 .TP
1115 .BR replay_window " = " \-1 " | <number>"
1116 The IPsec replay window size for this connection. With the default of \-1
1117 the value configured with
1118 .I charon.replay_window
1119 in
1120 .BR strongswan.conf (5)
1121 is used. Larger values than 32 are supported using the Netlink backend only,
1122 a value of 0 disables IPsec replay protection.
1123 .TP
1124 .BR reqid " = <number>"
1125 sets the reqid for a given connection to a pre-configured fixed value.
1126 .TP
1127 .BR tfc " = <value>"
1128 number of bytes to pad ESP payload data to. Traffic Flow Confidentiality
1129 is currently supported in IKEv2 and applies to outgoing packets only. The
1130 special value
1131 .BR %mtu
1132 fills up ESP packets with padding to have the size of the MTU.
1133 .TP
1134 .BR type " = " tunnel " | transport | transport_proxy | passthrough | drop"
1135 the type of the connection; currently the accepted values
1136 are
1137 .B tunnel
1138 (the default)
1139 signifying a host-to-host, host-to-subnet, or subnet-to-subnet tunnel;
1140 .BR transport ,
1141 signifying host-to-host transport mode;
1142 .BR transport_proxy ,
1143 signifying the special Mobile IPv6 transport proxy mode;
1144 .BR passthrough ,
1145 signifying that no IPsec processing should be done at all;
1146 .BR drop ,
1147 signifying that packets should be discarded.
1148 .TP
1149 .BR xauth " = " client " | server"
1150 specifies the role in the XAuth protocol if activated by
1151 .B authby=xauthpsk
1152 or
1153 .B authby=xauthrsasig.
1154 Accepted values are
1155 .B server
1156 and
1157 .B client
1158 (the default).
1159 .TP
1160 .BR xauth_identity " = <id>"
1161 defines the identity/username the client uses to reply to an XAuth request.
1162 If not defined, the IKEv1 identity will be used as XAuth identity.
1163
1164 .SS "CONN PARAMETERS: IKEv2 MEDIATION EXTENSION"
1165 The following parameters are relevant to IKEv2 Mediation Extension
1166 operation only.
1167 .TP
1168 .BR mediation " = yes | " no
1169 whether this connection is a mediation connection, ie. whether this
1170 connection is used to mediate other connections.  Mediation connections
1171 create no child SA. Acceptable values are
1172 .B no
1173 (the default) and
1174 .BR yes .
1175 .TP
1176 .BR mediated_by " = <name>"
1177 the name of the connection to mediate this connection through.  If given,
1178 the connection will be mediated through the named mediation connection.
1179 The mediation connection must set
1180 .BR mediation=yes .
1181 .TP
1182 .BR me_peerid " = <id>"
1183 ID as which the peer is known to the mediation server, ie. which the other
1184 end of this connection uses as its
1185 .B leftid
1186 on its connection to the mediation server.  This is the ID we request the
1187 mediation server to mediate us with.  If
1188 .B me_peerid
1189 is not given, the
1190 .B rightid
1191 of this connection will be used as peer ID.
1192
1193 .SH "CA SECTIONS"
1194 These are optional sections that can be used to assign special
1195 parameters to a Certification Authority (CA). Because the daemons
1196 automatically import CA certificates from \fI/etc/ipsec.d/cacerts\fP,
1197 there is no need to explicitly add them with a CA section, unless you
1198 want to assign special parameters (like a CRL) to a CA.
1199 .TP
1200 .BR also " = <name>"
1201 includes ca section
1202 .BR <name> .
1203 .TP
1204 .BR auto " = " ignore " | add"
1205 currently can have either the value
1206 .B ignore
1207 (the default) or
1208 .BR add .
1209 .TP
1210 .BR cacert " = <path>"
1211 defines a path to the CA certificate either relative to
1212 \fI/etc/ipsec.d/cacerts\fP or as an absolute path.
1213 .br
1214 A value in the form
1215 .B %smartcard[<slot nr>[@<module>]]:<keyid>
1216 defines a specific CA certificate to load from a PKCS#11 backend for this CA.
1217 See ipsec.secrets(5) for details about smartcard definitions.
1218 .TP
1219 .BR crluri " = <uri>"
1220 defines a CRL distribution point (ldap, http, or file URI)
1221 .TP
1222 .B crluri1
1223 synonym for
1224 .B crluri.
1225 .TP
1226 .BR crluri2 " = <uri>"
1227 defines an alternative CRL distribution point (ldap, http, or file URI)
1228 .TP
1229 .TP
1230 .BR ocspuri " = <uri>"
1231 defines an OCSP URI.
1232 .TP
1233 .B ocspuri1
1234 synonym for
1235 .B ocspuri.
1236 .TP
1237 .BR ocspuri2 " = <uri>"
1238 defines an alternative OCSP URI.
1239 .TP
1240 .BR certuribase " = <uri>"
1241 defines the base URI for the Hash and URL feature supported by IKEv2.
1242 Instead of exchanging complete certificates, IKEv2 allows one to send an URI
1243 that resolves to the DER encoded certificate. The certificate URIs are built
1244 by appending the SHA1 hash of the DER encoded certificates to this base URI.
1245 .SH "CONFIG SECTIONS"
1246 At present, the only
1247 .B config
1248 section known to the IPsec software is the one named
1249 .BR setup ,
1250 which contains information used when the software is being started.
1251 The currently-accepted
1252 .I parameter
1253 names in a
1254 .B config
1255 .B setup
1256 section are:
1257 .TP
1258 .BR cachecrls " = yes | " no
1259 if enabled, certificate revocation lists (CRLs) fetched via HTTP or LDAP will
1260 be cached in
1261 .I /etc/ipsec.d/crls/
1262 under a unique file name derived from the certification authority's public key.
1263 .TP
1264 .BR charondebug " = <debug list>"
1265 how much charon debugging output should be logged.
1266 A comma separated list containing type/level-pairs may
1267 be specified, e.g:
1268 .B dmn 3, ike 1, net -1.
1269 Acceptable values for types are
1270 .B dmn, mgr, ike, chd, job, cfg, knl, net, asn, enc, lib, esp, tls,
1271 .B tnc, imc, imv, pts
1272 and the level is one of
1273 .B -1, 0, 1, 2, 3, 4
1274 (for silent, audit, control, controlmore, raw, private).  By default, the level
1275 is set to
1276 .B 1
1277 for all types.  For more flexibility see LOGGER CONFIGURATION in
1278 .IR strongswan.conf (5).
1279 .TP
1280 .BR strictcrlpolicy " = yes | ifuri | " no
1281 defines if a fresh CRL must be available in order for the peer authentication
1282 based on RSA signatures to succeed.
1283 IKEv2 additionally recognizes
1284 .B ifuri
1285 which reverts to
1286 .B yes
1287 if at least one CRL URI is defined and to
1288 .B no
1289 if no URI is known.
1290 .TP
1291 .BR uniqueids " = " yes " | no | never | replace | keep"
1292 whether a particular participant ID should be kept unique,
1293 with any new IKE_SA using an ID deemed to replace all old ones using that ID;
1294 acceptable values are
1295 .B yes
1296 (the default),
1297 .B no
1298 and
1299 .BR never .
1300 Participant IDs normally \fIare\fR unique, so a new IKE_SA using the same ID is
1301 almost invariably intended to replace an old one. The difference between
1302 .B no
1303 and
1304 .B never
1305 is that the daemon will replace old IKE_SAs when receiving an INITIAL_CONTACT
1306 notify if the option is
1307 .B no
1308 but will ignore these notifies if
1309 .B never
1310 is configured.
1311 The daemon also accepts the value
1312 .B replace
1313 which is identical to
1314 .B yes
1315 and the value
1316 .B keep
1317 to reject new IKE_SA setups and keep the duplicate established earlier.
1318
1319 .SH IDENTITY PARSING
1320 The type and binary encoding of identity strings specified in \fIleftid\fR
1321 are detected as follows:
1322 .IP \[bu]
1323 If the string value contains an equal sign (=) it is assumed to be a
1324 Distinguished Name, with RDNs separated by commas (,) \fIor\fR slashes (/ - the string
1325 must start with a slash to use this syntax). An attempt is made to create a
1326 binary ASN.1 encoding from this string. If that fails the type is set to KEY_ID
1327 with the literal string value adopted as encoding.
1328 .IP \[bu]
1329 If the string value contains an @ the type depends on the position of that
1330 character:
1331 .RS
1332 .IP \[bu]
1333 If the string begins with @# the type is set to KEY_ID and the string following
1334 that prefix is assumed to be the hex-encoded binary value of the identity.
1335 .IP \[bu]
1336 If the string begins with @@ the type is set to USER_FQDN and the encoding is
1337 the literal string after that prefix.
1338 .IP \[bu]
1339 If the string begins with @ the type is set to FQDN and the encoding is the
1340 literal string after that prefix.
1341 .IP \[bu]
1342 All remaining strings containing an @ are assumed to be of type USER_FQDN/RFC822
1343 with the literal string value as encoding.
1344 .RE
1345 .IP \[bu]
1346 If the value does not contain any @ or = characters it is parsed as follows:
1347 .RS
1348 .IP \[bu]
1349 If the value is an empty string, or equals %any[6], 0.0.0.0, ::, or * the
1350 type is set to ID_ANY, which matches any other identity.
1351 .IP \[bu]
1352 If the value contains a colon (:) it is assumed to be an IPv6 address. But if
1353 parsing the address and converting it to its binary encoding fails the type is
1354 set to KEY_ID and the encoding is the literal value.
1355 .IP \[bu]
1356 For all other strings an attempt at parsing them as IPv4 addresses is made. If
1357 that fails the type is set to FQDN and the literal value is adopted as
1358 encoding (this is where domain names and simple names end up).
1359 .RE
1360
1361 .SH SA EXPIRY/REKEY
1362 The IKE SAs and IPsec SAs negotiated by the daemon can be configured to expire
1363 after a specific amount of time. For IPsec SAs this can also happen after a
1364 specified number of transmitted packets or transmitted bytes. The following
1365 settings can be used to configure this:
1366 .TS
1367 l r l r,- - - -,lB s lB s,a r a r.
1368 Setting Default Setting Default
1369 IKE SA  IPsec SA
1370 ikelifetime     3h      lifebytes       -
1371                 lifepackets     -
1372                 lifetime        1h
1373 .TE
1374 .SS Rekeying
1375 IKE SAs as well as IPsec SAs can be rekeyed before they expire. This can be
1376 configured using the following settings:
1377 .TS
1378 l r l r,- - - -,lB s lB s,a r a r.
1379 Setting Default Setting Default
1380 IKE and IPsec SA        IPsec SA
1381 margintime      9m      marginbytes     -
1382                 marginpackets   -
1383 .TE
1384 .SS Randomization
1385 To avoid collisions the specified margins are increased randomly before
1386 subtracting them from the expiration limits (see formula below). This is
1387 controlled by the
1388 .B rekeyfuzz
1389 setting:
1390 .TS
1391 l r,- -,lB s,a r.
1392 Setting Default
1393 IKE and IPsec SA
1394 rekeyfuzz       100%
1395 .TE
1396 .PP
1397 Randomization can be disabled by setting
1398 .BR rekeyfuzz " to " 0% .
1399 .SS Formula
1400 The following formula is used to calculate the rekey time of IPsec SAs:
1401 .PP
1402 .EX
1403  rekeytime = lifetime - (margintime + random(0, margintime * rekeyfuzz))
1404 .EE
1405 .PP
1406 It applies equally to IKE SAs and byte and packet limits for IPsec SAs.
1407 .SS Example
1408 Let's consider the default configuration:
1409 .PP
1410 .EX
1411         lifetime = 1h
1412         margintime = 9m
1413         rekeyfuzz = 100%
1414 .EE
1415 .PP
1416 From the formula above follows that the rekey time lies between:
1417 .PP
1418 .EX
1419         rekeytime_min = 1h - (9m + 9m) = 42m
1420         rekeytime_max = 1h - (9m + 0m) = 51m
1421 .EE
1422 .PP
1423 Thus, the daemon will attempt to rekey the IPsec SA at a random time
1424 between 42 and 51 minutes after establishing the SA. Or, in other words,
1425 between 9 and 18 minutes before the SA expires.
1426 .SS Notes
1427 .IP \[bu]
1428 Since the rekeying of an SA needs some time, the margin values must not be
1429 too low.
1430 .IP \[bu]
1431 The value
1432 .B margin... + margin... * rekeyfuzz
1433 must not exceed the original limit. For example, specifying
1434 .B margintime = 30m
1435 in the default configuration is a bad idea as there is a chance that the rekey
1436 time equals zero and, thus, rekeying gets disabled.
1437
1438 .SH FILES
1439 .nf
1440 /etc/ipsec.conf
1441 /etc/ipsec.d/aacerts
1442 /etc/ipsec.d/acerts
1443 /etc/ipsec.d/cacerts
1444 /etc/ipsec.d/certs
1445 /etc/ipsec.d/crls
1446
1447 .SH SEE ALSO
1448 strongswan.conf(5), ipsec.secrets(5), ipsec(8)
1449 .SH HISTORY
1450 Originally written for the FreeS/WAN project by Henry Spencer.
1451 Updated and extended for the strongSwan project <http://www.strongswan.org> by
1452 Tobias Brunner, Andreas Steffen and Martin Willi.