man: Describe what happens when a FQDN is specified in left or right
[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 If an
558 .B FQDN
559 is assigned it is resolved every time a configuration lookup is done. If DNS
560 resolution times out, the lookup is delayed for that time.
561
562 To limit the connection to a  specific range of hosts, a range (
563 .BR 10.1.0.0-10.2.255.255
564 ) or a subnet (
565 .BR 10.1.0.0/16
566 ) can be specified, and multiple addresses, ranges and subnets can be separated
567 by commas. While one can freely combine these items, to initiate the connection
568 at least one non-range/subnet is required.
569
570 Please note that with the usage of wildcards multiple connection descriptions
571 might match a given incoming connection attempt. The most specific description
572 is used in that case.
573 .TP
574 .BR leftallowany " = yes | " no
575 a modifier for
576 .BR left ,
577 making it behave as
578 .B %any
579 although a concrete IP address or domain name has been assigned.
580 .TP
581 .BR leftauth " = <auth method>"
582 Authentication method to use locally (left) or require from the remote (right)
583 side.
584 Acceptable values are
585 .B pubkey
586 for public key authentication (RSA/ECDSA),
587 .B psk
588 for pre-shared key authentication,
589 .B eap
590 to (require the) use of the Extensible Authentication Protocol in IKEv2, and
591 .B xauth
592 for IKEv1 eXtended Authentication.
593
594 To require a trustchain public key strength for the remote side, specify the
595 key type followed by the minimum strength in bits (for example
596 .BR ecdsa-384
597 or
598 .BR rsa-2048-ecdsa-256 ).
599 To limit the acceptable set of hashing algorithms for trustchain validation,
600 append hash algorithms to
601 .BR pubkey
602 or a key strength definition (for example
603 .BR pubkey-sha1-sha256
604 or
605 .BR rsa-2048-ecdsa-256-sha256-sha384-sha512 ).
606 Unless disabled in
607 .BR strongswan.conf (5),
608 or explicit IKEv2 signature constraints are configured (see below), such key
609 types and hash algorithms are also applied as constraints against IKEv2
610 signature authentication schemes used by the remote side.
611
612 If both peers support RFC 7427 ("Signature Authentication in IKEv2") specific
613 hash algorithms to be used during IKEv2 authentication may be configured.
614 The syntax is the same as above, but with ike: prefix. For example, with
615 .B ike:pubkey-sha384-sha256
616 a public key signature scheme with either SHA-384 or SHA-256 would get used for
617 authentication, in that order and depending on the hash algorithms supported by
618 the peer.  If no specific hash algorithms are configured, the default is to
619 prefer an algorithm that matches or exceeds the strength of the signature key.
620 If no constraints with ike: prefix are configured any signature scheme
621 constraint (without ike: prefix) will also apply to IKEv2 authentication, unless
622 this is disabled in
623 .BR strongswan.conf (5).
624
625 For
626 .BR eap ,
627 an optional EAP method can be appended. Currently defined methods are
628 .BR eap-aka ,
629 .BR eap-gtc ,
630 .BR eap-md5 ,
631 .BR eap-mschapv2 ,
632 .BR eap-peap ,
633 .BR eap-sim ,
634 .BR eap-tls ,
635 .BR eap-ttls ,
636 .BR eap-dynamic ,
637 and
638 .BR eap-radius .
639 Alternatively, IANA assigned EAP method numbers are accepted. Vendor specific
640 EAP methods are defined in the form
641 .B eap-type-vendor
642 .RB "(e.g. " eap-7-12345 ).
643 To specify signature and trust chain constraints for EAP-(T)TLS, append a colon
644 to the EAP method, followed by the key type/size and hash algorithm as discussed
645 above. For
646 .B xauth,
647 an XAuth authentication backend can be specified, such as
648 .B xauth-generic
649 or
650 .BR xauth-eap .
651 If XAuth is used in
652 .BR leftauth ,
653 Hybrid authentication is used. For traditional XAuth authentication, define
654 XAuth in
655 .BR lefauth2 .
656 .TP
657 .BR leftauth2 " = <auth method>"
658 Same as
659 .BR leftauth ,
660 but defines an additional authentication exchange. In IKEv1, only XAuth can be
661 used in the second authentication round. IKEv2 supports multiple complete
662 authentication rounds using "Multiple Authentication Exchanges" defined
663 in RFC 4739. This allows, for example, separated authentication
664 of host and user.
665 .TP
666 .BR leftca " = <issuer dn> | %same"
667 the distinguished name of a certificate authority which is required to
668 lie in the trust path going from the left participant's certificate up
669 to the root certification authority.
670 .B %same
671 means that the value configured for the right participant should be reused.
672 .TP
673 .BR leftca2 " = <issuer dn> | %same"
674 Same as
675 .BR leftca ,
676 but for the second authentication round (IKEv2 only).
677 .TP
678 .BR leftcert " = <path>"
679 the path to the left participant's X.509 certificate. The file can be encoded
680 either in PEM or DER format. OpenPGP certificates are supported as well.
681 Both absolute paths or paths relative to \fI/etc/ipsec.d/certs\fP
682 are accepted. By default
683 .B leftcert
684 sets
685 .B leftid
686 to the distinguished name of the certificate's subject.
687 The left participant's ID can be overridden by specifying a
688 .B leftid
689 value which must be certified by the certificate, though.
690 .br
691 A value in the form
692 .B %smartcard[<slot nr>[@<module>]]:<keyid>
693 defines a specific certificate to load from a PKCS#11 backend for this
694 connection. See ipsec.secrets(5) for details about smartcard definitions.
695 .B leftcert
696 is required only if selecting the certificate with
697 .B leftid
698 is not sufficient, for example if multiple certificates use the same subject.
699 .br
700 Multiple certificate paths or PKCS#11 backends can be specified in a comma
701 separated list. The daemon chooses the certificate based on the received
702 certificate requests if possible before enforcing the first.
703 .TP
704 .BR leftcert2 " = <path>"
705 Same as
706 .B leftcert,
707 but for the second authentication round (IKEv2 only).
708 .TP
709 .BR leftcertpolicy " = <OIDs>"
710 Comma separated list of certificate policy OIDs the peer's certificate must
711 have.
712 OIDs are specified using the numerical dotted representation.
713 .TP
714 .BR leftdns " = <servers>"
715 Comma separated list of DNS server addresses to exchange as configuration
716 attributes. On the initiator, a server is a fixed IPv4/IPv6 address, or
717 .BR %config4 / %config6
718 to request attributes without an address. On the responder,
719 only fixed IPv4/IPv6 addresses are allowed and define DNS servers assigned
720 to the client.
721 .TP
722 .BR leftfirewall " = yes | " no
723 whether the left participant is doing forwarding-firewalling
724 (including masquerading) using iptables for traffic from \fIleftsubnet\fR,
725 which should be turned off (for traffic to the other subnet)
726 once the connection is established;
727 acceptable values are
728 .B yes
729 and
730 .B no
731 (the default).
732 May not be used in the same connection description with
733 .BR leftupdown .
734 Implemented as a parameter to the default \fBipsec _updown\fR script.
735 See notes below.
736 Relevant only locally, other end need not agree on it.
737
738 If one or both security gateways are doing forwarding firewalling
739 (possibly including masquerading),
740 and this is specified using the firewall parameters,
741 tunnels established with IPsec are exempted from it
742 so that packets can flow unchanged through the tunnels.
743 (This means that all subnets connected in this manner must have
744 distinct, non-overlapping subnet address blocks.)
745 This is done by the default \fBipsec _updown\fR script.
746
747 In situations calling for more control,
748 it may be preferable for the user to supply his own
749 .I updown
750 script,
751 which makes the appropriate adjustments for his system.
752 .TP
753 .BR leftgroups " = <group list>"
754 a comma separated list of group names. If the
755 .B leftgroups
756 parameter is present then the peer must be a member of at least one
757 of the groups defined by the parameter.
758 .TP
759 .BR leftgroups2 " = <group list>"
760 Same as
761 .B leftgroups,
762 but for the second authentication round defined with
763 .B leftauth2.
764 .TP
765 .BR lefthostaccess " = yes | " no
766 inserts a pair of INPUT and OUTPUT iptables rules using the default
767 \fBipsec _updown\fR script, thus allowing access to the host itself
768 in the case where the host's internal interface is part of the
769 negotiated client subnet.
770 Acceptable values are
771 .B yes
772 and
773 .B no
774 (the default).
775 .TP
776 .BR leftid " = <id>"
777 how the left participant should be identified for authentication;
778 defaults to
779 .B left
780 or the subject of the certificate configured with
781 .BR leftcert .
782 If
783 .B leftcert
784 is configured the identity has to be confirmed by the certificate.
785
786 Can be an IP address, a fully-qualified domain name, an email address or a
787 Distinguished Name for which the ID type is determined automatically and the
788 string is converted to the appropriate encoding. The rules for this conversion
789 are described in IDENTITY PARSING below.
790
791 In certain special situations the identity parsing above might be inadequate
792 or produce the wrong result. Examples are the need to encode a FQDN as KEY_ID or
793 the string parser being unable to produce the correct binary ASN.1 encoding of
794 a certificate's DN.  For these situations it is possible to enforce a specific
795 identity type and to provide the binary encoding of the identity. To do this a
796 prefix may be used, followed by a colon (:). If the number sign (#) follows the
797 colon, the remaining data is interpreted as hex encoding, otherwise the string
798 is used as is as the identification data.
799 .BR Note :
800 The latter implies that no conversion is performed for non-string identities.
801 For example,
802 \fIipv4:10.0.0.1\fP does not create a valid ID_IPV4_ADDR IKE identity, as it
803 does not get converted to binary 0x0a000001. Instead, one could use
804 \fIipv4:#0a000001\fP to get a valid identity, but just using the implicit type
805 with automatic conversion is usually simpler. The same applies to the ASN.1
806 encoded types. The following prefixes are known:
807 .BR ipv4 ,
808 .BR ipv6 ,
809 .BR rfc822 ,
810 .BR email ,
811 .BR userfqdn ,
812 .BR fqdn ,
813 .BR dns ,
814 .BR asn1dn ,
815 .B asn1gn
816 and
817 .BR keyid .
818 Custom type prefixes may be specified by surrounding the numerical type value by
819 curly brackets.
820
821 For IKEv2 and
822 .B rightid
823 the prefix
824 .B %
825 in front of the identity prevents the daemon from sending IDr in its IKE_AUTH
826 request and will allow it to verify the configured identity against the subject
827 and subjectAltNames contained in the responder's certificate (otherwise it is
828 only compared with the IDr returned by the responder).  The IDr sent by the
829 initiator might otherwise prevent the responder from finding a config if it
830 has configured a different value for
831 .BR leftid .
832 .TP
833 .BR leftid2 " = <id>"
834 identity to use for a second authentication for the left participant
835 (IKEv2 only); defaults to
836 .BR leftid .
837 .TP
838 .BR leftikeport " = <port>"
839 UDP port the left participant uses for IKE communication.
840 If unspecified, port 500 is used with the port floating
841 to 4500 if a NAT is detected or MOBIKE is enabled. Specifying a local IKE port
842 different from the default additionally requires a socket implementation that
843 listens on this port.
844 .TP
845 .BR leftprotoport " = <protocol>/<port>"
846 restrict the traffic selector to a single protocol and/or port. This option
847 is now deprecated, protocol/port information can be defined for each subnet
848 directly in
849 .BR leftsubnet .
850 .TP
851 .BR leftsigkey " = <raw public key> | <path to public key>"
852 the left participant's public key for public key signature authentication,
853 in PKCS#1 format using hex (0x prefix) or base64 (0s prefix) encoding. With the
854 optional
855 .B dns:
856 or
857 .B ssh:
858 prefix in front of 0x or 0s, the public key is expected to be in either
859 the RFC 3110 (not the full RR, only RSA key part) or RFC 4253 public key format,
860 respectively.
861 Also accepted is the path to a file containing the public key in PEM, DER or SSH
862 encoding. Both absolute paths or paths relative to \fI/etc/ipsec.d/certs\fP
863 are accepted.
864 .TP
865 .BR leftsendcert " = never | no | " ifasked " | always | yes"
866 Accepted values are
867 .B never
868 or
869 .BR no ,
870 .B always
871 or
872 .BR yes ,
873 and
874 .BR ifasked " (the default),"
875 the latter meaning that the peer must send a certificate request payload in
876 order to get a certificate in return.
877 .TP
878 .BR leftsourceip " = %config4 | %config6 | <ip address>"
879 Comma separated list of internal source IPs to use in a tunnel, also known as
880 virtual IP. If the value is one of the synonyms
881 .BR %config ,
882 .BR %cfg ,
883 .BR %modeconfig ,
884 or
885 .BR %modecfg ,
886 an address (from the tunnel address family) is requested from the peer. With
887 .B %config4
888 and
889 .B %config6
890 an address of the given address family will be requested explicitly.
891 If an IP address is configured, it will be requested from the responder,
892 which is free to respond with a different address.
893 .TP
894 .BR rightsourceip " = %config | <network>/<netmask> | <from>-<to> | %poolname"
895 Comma separated list of internal source IPs to use in a tunnel for the remote
896 peer. If the value is
897 .B %config
898 on the responder side, the initiator must propose an address which is then
899 echoed back. Also supported are address pools expressed as
900 \fInetwork\fB/\fInetmask\fR
901 and
902 \fIfrom\fB-\fIto\fR
903 or the use of an external IP address pool using %\fIpoolname\fR,
904 where \fIpoolname\fR is the name of the IP address pool used for the lookup.
905 .TP
906 .BR leftsubnet " = <ip subnet>[[<proto/port>]][,...]"
907 private subnet behind the left participant, expressed as
908 \fInetwork\fB/\fInetmask\fR;
909 if omitted, essentially assumed to be \fIleft\fB/32\fR,
910 signifying that the left end of the connection goes to the left participant
911 only. Configured subnets of the peers may differ, the protocol narrows it to
912 the greatest common subnet. In IKEv1, this may lead to problems with other
913 implementations, make sure to configure identical subnets in such
914 configurations. IKEv2 supports multiple subnets separated by commas. IKEv1 only
915 interprets the first subnet of such a definition, unless the Cisco Unity
916 extension plugin is enabled.
917
918 The optional part after each subnet enclosed in square brackets specifies a
919 protocol/port to restrict the selector for that subnet.
920
921 Examples:
922 .BR leftsubnet=10.0.0.1[tcp/http],10.0.0.2[6/80] " or"
923 .BR leftsubnet=fec1::1[udp],10.0.0.0/16[/53] .
924 Instead of omitting either value
925 .B %any
926 can be used to the same effect, e.g.
927 .BR leftsubnet=fec1::1[udp/%any],10.0.0.0/16[%any/53] .
928
929 If the protocol is
930 .B icmp
931 or
932 .B ipv6-icmp
933 the port is interpreted as ICMP message type if it is less than 256 or as type
934 and code if it is greater or equal to 256, with the type in the most significant
935 8 bits and the code in the least significant 8 bits.
936
937 The port value can alternatively take the value
938 .B %opaque
939 for RFC 4301 OPAQUE selectors, or a numerical range in the form
940 .BR 1024-65535 .
941 None of the kernel backends currently supports opaque or port ranges and uses
942 .B %any
943 for policy installation instead.
944
945 Instead of specifying a subnet,
946 .B %dynamic
947 can be used to replace it with the IKE address, having the same effect
948 as omitting
949 .B leftsubnet
950 completely. Using
951 .B %dynamic
952 can be used to define multiple dynamic selectors, each having a potentially
953 different protocol/port definition.
954
955 .TP
956 .BR leftupdown " = <path>"
957 what ``updown'' script to run to adjust routing and/or firewalling
958 when the status of the connection
959 changes (default
960 .BR "ipsec _updown" ).
961 May include positional parameters separated by white space
962 (although this requires enclosing the whole string in quotes);
963 including shell metacharacters is unwise.
964 Relevant only locally, other end need not agree on it. Charon uses the updown
965 script to insert firewall rules only, since routing has been implemented
966 directly into the daemon.
967 .TP
968 .BR lifebytes " = <number>"
969 the number of bytes transmitted over an IPsec SA before it expires.
970 .TP
971 .BR lifepackets " = <number>"
972 the number of packets transmitted over an IPsec SA before it expires.
973 .TP
974 .BR lifetime " = " 1h " | <time>"
975 how long a particular instance of a connection
976 (a set of encryption/authentication keys for user packets) should last,
977 from successful negotiation to expiry;
978 acceptable values are an integer optionally followed by
979 .BR s
980 (a time in seconds)
981 or a decimal number followed by
982 .BR m ,
983 .BR h ,
984 or
985 .B d
986 (a time
987 in minutes, hours, or days respectively)
988 (default
989 .BR 1h ,
990 maximum
991 .BR 24h ).
992 Normally, the connection is renegotiated (via the keying channel)
993 before it expires (see
994 .BR margintime ).
995 The two ends need not exactly agree on
996 .BR lifetime ,
997 although if they do not,
998 there will be some clutter of superseded connections on the end
999 which thinks the lifetime is longer. Also see EXPIRY/REKEY below.
1000 .TP
1001 .BR marginbytes " = <number>"
1002 how many bytes before IPsec SA expiry (see
1003 .BR lifebytes )
1004 should attempts to negotiate a replacement begin.
1005 .TP
1006 .BR marginpackets " = <number>"
1007 how many packets before IPsec SA expiry (see
1008 .BR lifepackets )
1009 should attempts to negotiate a replacement begin.
1010 .TP
1011 .BR margintime " = " 9m " | <time>"
1012 how long before connection expiry or keying-channel expiry
1013 should attempts to
1014 negotiate a replacement
1015 begin; acceptable values as for
1016 .B lifetime
1017 (default
1018 .BR 9m ).
1019 Relevant only locally, other end need not agree on it. Also see EXPIRY/REKEY
1020 below.
1021 .TP
1022 .BR mark " = <value>[/<mask>]"
1023 sets an XFRM mark in the inbound and outbound
1024 IPsec SAs and policies. If the mask is missing then a default
1025 mask of
1026 .B 0xffffffff
1027 is assumed. The special value
1028 .B %unique
1029 assigns a unique value to each newly created IPsec SA.
1030 .TP
1031 .BR mark_in " = <value>[/<mask>]"
1032 sets an XFRM mark in the inbound IPsec SA and
1033 policy. If the mask is missing then a default mask of
1034 .B 0xffffffff
1035 is assumed.
1036 .TP
1037 .BR mark_out " = <value>[/<mask>]"
1038 sets an XFRM mark in the outbound IPsec SA and
1039 policy. If the mask is missing then a default mask of
1040 .B 0xffffffff
1041 is assumed.
1042 .TP
1043 .BR mobike " = " yes " | no"
1044 enables the IKEv2 MOBIKE protocol defined by RFC 4555. Accepted values are
1045 .B yes
1046 (the default) and
1047 .BR no .
1048 If set to
1049 .BR no ,
1050 the charon daemon will not actively propose MOBIKE as initiator and
1051 ignore the MOBIKE_SUPPORTED notify as responder.
1052 .TP
1053 .BR modeconfig " = push | " pull
1054 defines which mode is used to assign a virtual IP.
1055 Accepted values are
1056 .B push
1057 and
1058 .B pull
1059 (the default).
1060 Push mode is currently not supported with IKEv2.
1061 .TP
1062 .BR reauth " = " yes " | no"
1063 whether rekeying of an IKE_SA should also reauthenticate the peer. In IKEv1,
1064 reauthentication is always done. In IKEv2, a value of
1065 .B no
1066 rekeys without uninstalling the IPsec SAs, a value of
1067 .B yes
1068 (the default) creates a new IKE_SA from scratch and tries to recreate
1069 all IPsec SAs.
1070 .TP
1071 .BR rekey " = " yes " | no"
1072 whether a connection should be renegotiated when it is about to expire;
1073 acceptable values are
1074 .B yes
1075 (the default)
1076 and
1077 .BR no .
1078 The two ends need not agree, but while a value of
1079 .B no
1080 prevents charon from requesting renegotiation,
1081 it does not prevent responding to renegotiation requested from the other end,
1082 so
1083 .B no
1084 will be largely ineffective unless both ends agree on it. Also see
1085 .BR reauth .
1086 .TP
1087 .BR rekeyfuzz " = " 100% " | <percentage>"
1088 maximum percentage by which
1089 .BR marginbytes ,
1090 .B marginpackets
1091 and
1092 .B margintime
1093 should be randomly increased to randomize rekeying intervals
1094 (important for hosts with many connections);
1095 acceptable values are an integer,
1096 which may exceed 100,
1097 followed by a `%'
1098 (defaults to
1099 .BR 100% ).
1100 The value of
1101 .BR marginTYPE ,
1102 after this random increase,
1103 must not exceed
1104 .B lifeTYPE
1105 (where TYPE is one of
1106 .IR bytes ,
1107 .I packets
1108 or
1109 .IR time ).
1110 The value
1111 .B 0%
1112 will suppress randomization.
1113 Relevant only locally, other end need not agree on it. Also see EXPIRY/REKEY
1114 below.
1115 .TP
1116 .B rekeymargin
1117 synonym for
1118 .BR margintime .
1119 .TP
1120 .BR replay_window " = " \-1 " | <number>"
1121 The IPsec replay window size for this connection. With the default of \-1
1122 the value configured with
1123 .I charon.replay_window
1124 in
1125 .BR strongswan.conf (5)
1126 is used. Larger values than 32 are supported using the Netlink backend only,
1127 a value of 0 disables IPsec replay protection.
1128 .TP
1129 .BR reqid " = <number>"
1130 sets the reqid for a given connection to a pre-configured fixed value.
1131 .TP
1132 .BR tfc " = <value>"
1133 number of bytes to pad ESP payload data to. Traffic Flow Confidentiality
1134 is currently supported in IKEv2 and applies to outgoing packets only. The
1135 special value
1136 .BR %mtu
1137 fills up ESP packets with padding to have the size of the MTU.
1138 .TP
1139 .BR type " = " tunnel " | transport | transport_proxy | passthrough | drop"
1140 the type of the connection; currently the accepted values
1141 are
1142 .B tunnel
1143 (the default)
1144 signifying a host-to-host, host-to-subnet, or subnet-to-subnet tunnel;
1145 .BR transport ,
1146 signifying host-to-host transport mode;
1147 .BR transport_proxy ,
1148 signifying the special Mobile IPv6 transport proxy mode;
1149 .BR passthrough ,
1150 signifying that no IPsec processing should be done at all;
1151 .BR drop ,
1152 signifying that packets should be discarded.
1153 .TP
1154 .BR xauth " = " client " | server"
1155 specifies the role in the XAuth protocol if activated by
1156 .B authby=xauthpsk
1157 or
1158 .B authby=xauthrsasig.
1159 Accepted values are
1160 .B server
1161 and
1162 .B client
1163 (the default).
1164 .TP
1165 .BR xauth_identity " = <id>"
1166 defines the identity/username the client uses to reply to an XAuth request.
1167 If not defined, the IKEv1 identity will be used as XAuth identity.
1168
1169 .SS "CONN PARAMETERS: IKEv2 MEDIATION EXTENSION"
1170 The following parameters are relevant to IKEv2 Mediation Extension
1171 operation only.
1172 .TP
1173 .BR mediation " = yes | " no
1174 whether this connection is a mediation connection, ie. whether this
1175 connection is used to mediate other connections.  Mediation connections
1176 create no child SA. Acceptable values are
1177 .B no
1178 (the default) and
1179 .BR yes .
1180 .TP
1181 .BR mediated_by " = <name>"
1182 the name of the connection to mediate this connection through.  If given,
1183 the connection will be mediated through the named mediation connection.
1184 The mediation connection must set
1185 .BR mediation=yes .
1186 .TP
1187 .BR me_peerid " = <id>"
1188 ID as which the peer is known to the mediation server, ie. which the other
1189 end of this connection uses as its
1190 .B leftid
1191 on its connection to the mediation server.  This is the ID we request the
1192 mediation server to mediate us with.  If
1193 .B me_peerid
1194 is not given, the
1195 .B rightid
1196 of this connection will be used as peer ID.
1197
1198 .SH "CA SECTIONS"
1199 These are optional sections that can be used to assign special
1200 parameters to a Certification Authority (CA). Because the daemons
1201 automatically import CA certificates from \fI/etc/ipsec.d/cacerts\fP,
1202 there is no need to explicitly add them with a CA section, unless you
1203 want to assign special parameters (like a CRL) to a CA.
1204 .TP
1205 .BR also " = <name>"
1206 includes ca section
1207 .BR <name> .
1208 .TP
1209 .BR auto " = " ignore " | add"
1210 currently can have either the value
1211 .B ignore
1212 (the default) or
1213 .BR add .
1214 .TP
1215 .BR cacert " = <path>"
1216 defines a path to the CA certificate either relative to
1217 \fI/etc/ipsec.d/cacerts\fP or as an absolute path.
1218 .br
1219 A value in the form
1220 .B %smartcard[<slot nr>[@<module>]]:<keyid>
1221 defines a specific CA certificate to load from a PKCS#11 backend for this CA.
1222 See ipsec.secrets(5) for details about smartcard definitions.
1223 .TP
1224 .BR crluri " = <uri>"
1225 defines a CRL distribution point (ldap, http, or file URI)
1226 .TP
1227 .B crluri1
1228 synonym for
1229 .B crluri.
1230 .TP
1231 .BR crluri2 " = <uri>"
1232 defines an alternative CRL distribution point (ldap, http, or file URI)
1233 .TP
1234 .TP
1235 .BR ocspuri " = <uri>"
1236 defines an OCSP URI.
1237 .TP
1238 .B ocspuri1
1239 synonym for
1240 .B ocspuri.
1241 .TP
1242 .BR ocspuri2 " = <uri>"
1243 defines an alternative OCSP URI.
1244 .TP
1245 .BR certuribase " = <uri>"
1246 defines the base URI for the Hash and URL feature supported by IKEv2.
1247 Instead of exchanging complete certificates, IKEv2 allows one to send an URI
1248 that resolves to the DER encoded certificate. The certificate URIs are built
1249 by appending the SHA1 hash of the DER encoded certificates to this base URI.
1250 .SH "CONFIG SECTIONS"
1251 At present, the only
1252 .B config
1253 section known to the IPsec software is the one named
1254 .BR setup ,
1255 which contains information used when the software is being started.
1256 The currently-accepted
1257 .I parameter
1258 names in a
1259 .B config
1260 .B setup
1261 section are:
1262 .TP
1263 .BR cachecrls " = yes | " no
1264 if enabled, certificate revocation lists (CRLs) fetched via HTTP or LDAP will
1265 be cached in
1266 .I /etc/ipsec.d/crls/
1267 under a unique file name derived from the certification authority's public key.
1268 .TP
1269 .BR charondebug " = <debug list>"
1270 how much charon debugging output should be logged.
1271 A comma separated list containing type/level-pairs may
1272 be specified, e.g:
1273 .B dmn 3, ike 1, net -1.
1274 Acceptable values for types are
1275 .B dmn, mgr, ike, chd, job, cfg, knl, net, asn, enc, lib, esp, tls,
1276 .B tnc, imc, imv, pts
1277 and the level is one of
1278 .B -1, 0, 1, 2, 3, 4
1279 (for silent, audit, control, controlmore, raw, private).  By default, the level
1280 is set to
1281 .B 1
1282 for all types.  For more flexibility see LOGGER CONFIGURATION in
1283 .IR strongswan.conf (5).
1284 .TP
1285 .BR strictcrlpolicy " = yes | ifuri | " no
1286 defines if a fresh CRL must be available in order for the peer authentication
1287 based on RSA signatures to succeed.
1288 IKEv2 additionally recognizes
1289 .B ifuri
1290 which reverts to
1291 .B yes
1292 if at least one CRL URI is defined and to
1293 .B no
1294 if no URI is known.
1295 .TP
1296 .BR uniqueids " = " yes " | no | never | replace | keep"
1297 whether a particular participant ID should be kept unique,
1298 with any new IKE_SA using an ID deemed to replace all old ones using that ID;
1299 acceptable values are
1300 .B yes
1301 (the default),
1302 .B no
1303 and
1304 .BR never .
1305 Participant IDs normally \fIare\fR unique, so a new IKE_SA using the same ID is
1306 almost invariably intended to replace an old one. The difference between
1307 .B no
1308 and
1309 .B never
1310 is that the daemon will replace old IKE_SAs when receiving an INITIAL_CONTACT
1311 notify if the option is
1312 .B no
1313 but will ignore these notifies if
1314 .B never
1315 is configured.
1316 The daemon also accepts the value
1317 .B replace
1318 which is identical to
1319 .B yes
1320 and the value
1321 .B keep
1322 to reject new IKE_SA setups and keep the duplicate established earlier.
1323
1324 .SH IDENTITY PARSING
1325 The type and binary encoding of identity strings specified in \fIleftid\fR
1326 are detected as follows:
1327 .IP \[bu]
1328 If the string value contains an equal sign (=) it is assumed to be a
1329 Distinguished Name, with RDNs separated by commas (,) \fIor\fR slashes (/ - the string
1330 must start with a slash to use this syntax). An attempt is made to create a
1331 binary ASN.1 encoding from this string. If that fails the type is set to KEY_ID
1332 with the literal string value adopted as encoding.
1333 .IP \[bu]
1334 If the string value contains an @ the type depends on the position of that
1335 character:
1336 .RS
1337 .IP \[bu]
1338 If the string begins with @# the type is set to KEY_ID and the string following
1339 that prefix is assumed to be the hex-encoded binary value of the identity.
1340 .IP \[bu]
1341 If the string begins with @@ the type is set to USER_FQDN and the encoding is
1342 the literal string after that prefix.
1343 .IP \[bu]
1344 If the string begins with @ the type is set to FQDN and the encoding is the
1345 literal string after that prefix.
1346 .IP \[bu]
1347 All remaining strings containing an @ are assumed to be of type USER_FQDN/RFC822
1348 with the literal string value as encoding.
1349 .RE
1350 .IP \[bu]
1351 If the value does not contain any @ or = characters it is parsed as follows:
1352 .RS
1353 .IP \[bu]
1354 If the value is an empty string, or equals %any[6], 0.0.0.0, ::, or * the
1355 type is set to ID_ANY, which matches any other identity.
1356 .IP \[bu]
1357 If the value contains a colon (:) it is assumed to be an IPv6 address. But if
1358 parsing the address and converting it to its binary encoding fails the type is
1359 set to KEY_ID and the encoding is the literal value.
1360 .IP \[bu]
1361 For all other strings an attempt at parsing them as IPv4 addresses is made. If
1362 that fails the type is set to FQDN and the literal value is adopted as
1363 encoding (this is where domain names and simple names end up).
1364 .RE
1365
1366 .SH SA EXPIRY/REKEY
1367 The IKE SAs and IPsec SAs negotiated by the daemon can be configured to expire
1368 after a specific amount of time. For IPsec SAs this can also happen after a
1369 specified number of transmitted packets or transmitted bytes. The following
1370 settings can be used to configure this:
1371 .TS
1372 l r l r,- - - -,lB s lB s,a r a r.
1373 Setting Default Setting Default
1374 IKE SA  IPsec SA
1375 ikelifetime     3h      lifebytes       -
1376                 lifepackets     -
1377                 lifetime        1h
1378 .TE
1379 .SS Rekeying
1380 IKE SAs as well as IPsec SAs can be rekeyed before they expire. This can be
1381 configured using the following settings:
1382 .TS
1383 l r l r,- - - -,lB s lB s,a r a r.
1384 Setting Default Setting Default
1385 IKE and IPsec SA        IPsec SA
1386 margintime      9m      marginbytes     -
1387                 marginpackets   -
1388 .TE
1389 .SS Randomization
1390 To avoid collisions the specified margins are increased randomly before
1391 subtracting them from the expiration limits (see formula below). This is
1392 controlled by the
1393 .B rekeyfuzz
1394 setting:
1395 .TS
1396 l r,- -,lB s,a r.
1397 Setting Default
1398 IKE and IPsec SA
1399 rekeyfuzz       100%
1400 .TE
1401 .PP
1402 Randomization can be disabled by setting
1403 .BR rekeyfuzz " to " 0% .
1404 .SS Formula
1405 The following formula is used to calculate the rekey time of IPsec SAs:
1406 .PP
1407 .EX
1408  rekeytime = lifetime - (margintime + random(0, margintime * rekeyfuzz))
1409 .EE
1410 .PP
1411 It applies equally to IKE SAs and byte and packet limits for IPsec SAs.
1412 .SS Example
1413 Let's consider the default configuration:
1414 .PP
1415 .EX
1416         lifetime = 1h
1417         margintime = 9m
1418         rekeyfuzz = 100%
1419 .EE
1420 .PP
1421 From the formula above follows that the rekey time lies between:
1422 .PP
1423 .EX
1424         rekeytime_min = 1h - (9m + 9m) = 42m
1425         rekeytime_max = 1h - (9m + 0m) = 51m
1426 .EE
1427 .PP
1428 Thus, the daemon will attempt to rekey the IPsec SA at a random time
1429 between 42 and 51 minutes after establishing the SA. Or, in other words,
1430 between 9 and 18 minutes before the SA expires.
1431 .SS Notes
1432 .IP \[bu]
1433 Since the rekeying of an SA needs some time, the margin values must not be
1434 too low.
1435 .IP \[bu]
1436 The value
1437 .B margin... + margin... * rekeyfuzz
1438 must not exceed the original limit. For example, specifying
1439 .B margintime = 30m
1440 in the default configuration is a bad idea as there is a chance that the rekey
1441 time equals zero and, thus, rekeying gets disabled.
1442
1443 .SH FILES
1444 .nf
1445 /etc/ipsec.conf
1446 /etc/ipsec.d/aacerts
1447 /etc/ipsec.d/acerts
1448 /etc/ipsec.d/cacerts
1449 /etc/ipsec.d/certs
1450 /etc/ipsec.d/crls
1451
1452 .SH SEE ALSO
1453 strongswan.conf(5), ipsec.secrets(5), ipsec(8)
1454 .SH HISTORY
1455 Originally written for the FreeS/WAN project by Henry Spencer.
1456 Updated and extended for the strongSwan project <http://www.strongswan.org> by
1457 Tobias Brunner, Andreas Steffen and Martin Willi.