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